Voters

Voters are used in Magnolia whenever configuration values are not assigned at startup but instead depend on rules. The rules are user-defined using voter classes which evaluate established criteria by determining true or false of each rule.

Voters are currently used for:

• Filter configuration: uses voters to determine whether a filter should be executed or bypassed.
• Cache configuration: uses voters to determine whether a file should be cached or not.
• Personalization: uses voters to determine whether a user should be served a targeted content. 

The rules to determine values should be configurable and discrete.

Voting mechanism

For example, the Cache module has to determine if a requested resource may be cached or not. There may be a series of voters that feel responsible for casting a vote on that decision. The winner of a "voting round" is based on the concept of highest according to absolute value. 

Basic concept

Voters are classes which calculate an int vote value, where positive (1, 2, 3, ...) results are treated as "yes" or "true" and (0, -1, -2, ...) results are treated as "no" or "false". If you have a set of voters, then the result of a voting is the largest absolute result. If there are two voters with the same absolute result, then the one with the higher positive value will be taken.

Examples of voting decisions:

Configuration

The way voters are configured can vary based on the use case. One common use case for voters is as part of a filter configuration. Since filters can be costly to execute you can save precious execution time by configuring a bypass to be checked prior to running the filter. Any filter which extends AbstractMgnlFilter can have a set of Voter bypasses configured. Each bypass is checked in the same order in which they are defined, top-down. 

In the above example we see three bypasses configured on the registration filter. In this case the filter uses the URIPatternVoter for each bypass. We want the system to allow these resource requests to bypass this filter as it does not apply for the registration process. The resources are for the registration form itself. 

Voters package

Most of Magnolia's voter classes can be found in the core module in the package info.magnolia.voting.votes. Using one or more of these voters you can create simple or complex configurations which change the behavior of the product.

Interfaces

All voter classes should implement the Voter interface. The Voting interface provides a bases for working with multiple voters.  Some classes extend from abstract base classes which provide default configuration for other voter classes.

Voter

interface: info.magnolia.voting.voters.Voter

All voter classes by implement the Voter interface. 

The individual votes can then be operated on using Boolean logic. The Voter interface requires that you implement a vote() method which takes in the object T and return int. These boolean voters return "1" for a "true" and "0" for a "false" result. 

Voting

interface: info.magnolia.voting.Voting

The Voting interface is for dealing with sets of voters. Options are AND, OR, HIGHEST_LEVEL voting.

Abstract classes

Some voter classes extend from abstract base classes which provide default configurations.

BaseVoterImpl 

abstract class: info.magnolia.voting.voters.BaseVoterImpl implements Voter

BaseVoterImpl is the abstract voter that all other voters should extend from. It provides common properties for most other voters.

Properties:

AbstractBoolVoter

abstract class: info.magnolia.voting.voters.AbstractBoolVoter extends BaseVoterImpl

AbstractBoolVoter is used to create boolean voters which can't return integer values. You can steer the returned values by setting the trueValue and falseValue. Classes extending this class should override the boolVote() method. 

Properties:

if (not) outcome = -outcome;

BasePatternVoter

abstract class: info.magnolia.voting.voters.BasePatterVoter extends AbstractBoolVoter

BasePatternVoter uses URLs to match against the pattern. The returned vote is the length of the pattern. This allows oversteering less precise votes (like allow /something/* but deny /somthing/otherthing/*). You can use the inverse property which will then return the negative value on a match. This is not the same thing as using the not property which will then vote if the pattern does not match at all.

BasePatternVoter implementations are typed to <Object> because they can work with String value, but will otherwise use the ThreadLocal context and its AggregationState. Finally, it will use a given HttpServletRequest value.

Properties:

AbstractRequestHeaderPatternVoter

abstract class: info.magnolia.voting.voters.AbstractRequestHeaderPatternVoter extends AbstractBoolVoter

AbstractRequestHeaderPatternVoter is used to match the request headers against a pattern.

Properties:

Definition classes

These classes are provided in the core module and can be used out of the box. Most voters extend from BaseVoterImpl either directly or indirectly. When dealing with a set of voters then it's typical to implement the Voting interface. 

AndVoting

class: info.magnolia.voting.voters.AndVoting implements Voting

AndVoting returns the maximum vote, but only if all voters voted positive. 

AuthenticatedVoter

class: info.magnolia.voting.voters.AuthenticatedVoter extends AbstractBoolVoter

AuthenticatedVoter checks if the current user is authenticated. Does not vote on the passed object.

BoolVoterSet

class: info.magnolia.voting.voters.BoolVoterSet extends AbstractBoolVoter

BoolVoterSet combines a set of other voters based on a given logical operation. It's backed by VoterSet, but boolean-aware. In particular, this means that the "not" flag is handled correctly.

DefaultVoting

class: info.magnolia.voting.DefaultVoting implements Voting

DefaultVoting returns the highest vote in the set of voters. The voting can return 0 if no voter casts a meaningful vote.

DomainNameRegexVoter

class: info.magnolia.voting.voters.DomainNameRegexVoter extends AbstractBoolVoter

DomainNameRegexVoter determines if the request has domain that matches configured regex. Typed to Object, as it can vote on both a passed HttpServletRequest, or the current context (i.e. WebContext) if any.

Properties:

ExtensionVoter

class: info.magnolia.voting.voters.ExtensionVoter extends AbstractBoolVoter

ExtensionVoter returns:

• false if the extension is not a valid mimetype (as configured in config:/server/MIMEMapping).
• false  if the allow list exists, but the extension is not  in the allow list.
• false  if the deny list exists and the extension is in the deny list.
• true  otherwise

Properties:

FalseVoter

class: info.magnolia.voting.voters.FalseVoter extends AbstractBoolVoter

FalseVoter simply returns false.

ForwardVoter

class: info.magnolia.voting.voters.ForwardVoter extends AbstractBoolVoter

ForwardVoter returns true if the request has been forwarded. It works by checking to see if the FORWARD_REQUEST_URI attribute is not null.

IfVoter

class: info.magnolia.voting.voters.IfVoter

Conditional voter. If the "condition" voter is positive, returns the "then" voter's value, otherwise returns the "otherwise" voter's value.

Properties:

InverseVoter

class: info.magnolia.voting.voters.InverseVoter

InverseVoter is a voter wrapper. It calls the vote() method of the wrapped voter and multiplies the value by -1 (i.e. 5 * -1 --> -5)

Properties:

NotVoter

class: info.magnolia.voting.voters.NotVoter extends AbstractBoolVoter

NotVoter inverts the boolean outcome of a voter. This is not the same thing as inverting the value InverseVoter.

Properties:

NullVoter

class: info.magnolia.voting.voters.NullVoter implements Voter

NullVoter always returns 0 and is disabled by default. Useful for default values.

Properties:

OnAdminVoter

class: info.magnolia.voting.voters.OnAdminVoter extends AbstractBoolVoter

OnAdminVoter checks if the admin property of the server configuration is true or false.

OrVoting

class: info.magnolia.voting.voters.OrVoting implements Voting

OrVoting returns the first positive vote. Negative votes are ignored.

PropertyVoter

class: info.magnolia.voting.voters.PropertyVoter extends AbstractBoolVoter

PropertyVoter checks if the named Magnolia property has the expected value.

Properties:

RequestExtensionVoter

class: info.magnolia.voting.voters.RequestExtensionVoter extends AbstractBoolVoter

RequestExtensionVoter checks the extension set in the AggregationState object against a list of allowed and/or rejected extensions.

Properties:

RequestHasParametersVoter

class: info.magnolia.voting.voters.RequestHasParametersVoter extends AbstractBoolVoter

RequestHasParametersVoter checks if the request used the "POST" method or if there are request parameters. Typed to Object, as it can vote on both a passed HttpServletRequest, or the current context (i.e. WebContext) if any.

RequestHeaderPatternRegexVoter

class: info.magnolia.voting.voters.RequestHeaderRegexVoter extends AbstractRequestHeaderPatternVoter

RequestHeaderPatternRegexVoter takes a plain regex pattern which is matched against the specified request (configured in the headerName property).

Properties:

RequestHeaderPatternSimpleVoter

class: info.magnolia.voting.voters.RequestHeaderPatternSimpleVoter extends AbstractRequestHeaderPatternVoter

RequestHeaderPatternSimpleVoter checks if the specified request header matches a simple url pattern (SimpleUrlPattern).

RequestParameterVoter

class: info.magnolia.voting.voters.RequestParameterVoter extends AbstractBoolVoter

RequestHeaderPatternSimpleVoter checks for a specific GET and POST parameter and an optional value. If no value is specified the voter just checks for the existence of the parameter no matter what value is set.

Properties:

RoleBaseVoter

class: info.magnolia.voting.voters.RoleBaseVoter extends AbstractBoolVoter

RoleBaseVoter checks if the current user has access permissions by comparing user roles and configured roles. The configured roles can be allowed or denied.

SystemOrAdminUserVoter

class: info.magnolia.voting.voters.SystemOrAdminUserVoter extends AbstractBoolVoter

SystemOrAdminUserVoter checks if the current user is a system or admin user by checking the user's Realm.

TrueVoter

class: info.magnolia.voting.voters.TrueVoter extends AbstractBoolVoter

TrueVoter extends AbstractBoolVoter which simply returns true.

URIPatternVoter

class: info.magnolia.voting.voters.URIPatternVoter extends BasePatternVoter

URIPatternVoter checks if URI matches the pattern.

URIRegexVoter

class: info.magnolia.voting.voters.URIRegexVoter extends BasePatternVoter

URIRegexVoter extends BasePatternVoter and uses the pattern to match against the current URI in the AggregationState.

URIStartsWithVoter

class: info.magnolia.voting.voters.URIStartsWithVoter extends BasePatternVoter

URIStartsWithVoter extends BasePatternVoter and checks if the URI starts with the given pattern.

UserAgentVoter

class: info.magnolia.voting.voters.UserAgentVoter extends AbstractBoolVoter

UserAgentVoter extends AbstractBoolVoter and checks the user agent header in request object against a list of allowed and/or rejected user agents. Typed to Object, as it can vote on both a passed HttpServletRequest, or the current context, if any. Checks if the URI starts with the given pattern.

Properties:

VoterSet

class: info.magnolia.voting.voters.VoterSet  extends BaseVoterImpl

VoterSet implements the Voting interface and takes a set of voters. The voting can be set as well as the returned level. If the level is not set (0) the votings result is returned.

Properties:

if (not) outcome = -outcome;