Configuration mechanisms

• Properties
• Observation
• Content2Bean
• Singletons and Configuration
• Voters

Properties

Magnolia is primarily configured using properties. Properties are not stored in a single file but come from multiple different sources. Essentially, sources are processed or parsed in an order that is reflected in the following table. Sources that are parsed early may have properties that are overridden by properties associated with later sources in the parsing order.

Magnolia reads the following property sources:

<properties> 
  <property> 
    <name>defaultPublicURI</name> 
    <value>redirect:/help.html</value> 
  </property> 
</properties>

The structure and order of execution of Magnolia sources enables you to provide sophisticated configurations and flexible customization. The default Magnolia configuration delivered in the web application bundle provides an example of how the Magnolia mechanism operates. In the default configuration you will find three properties files:

• WEB-INF/config/default/magnolia.properties
• WEB-INF/config/magnoliaAuthor/magnolia.properties
• WEB-INF/config/magnoliaPublic/magnolia.properties

Adding a server name to the listed paths allows you to apply different configurations if your environment has multiple staging systems with differing configuration needs.

For even more complex environments, the order of loading files can be defined in WEB-INF/web.xml as context-param:

<context-param>
    <param-name>magnolia.initialization.file</param-name>
    <param-value>
      WEB-INF/config/${servername}/${webapp}/magnolia.properties,
      WEB-INF/config/${servername}/magnolia.properties,
      WEB-INF/config/${webapp}/magnolia.properties,
      WEB-INF/config/default/magnolia.properties,
      WEB-INF/config/magnolia.properties
    </param-value>
  </context-param>

You can also use this mechanism to define and read properties in your own code. The properties can be accessed through the static methods of Magnolia's SystemProperty class.

Here is a list of the properties and their default values.

Observation

Observation is a feature of the Java Content Repository which enables applications to register interest in events that describe changes to a workspace, and then monitor and respond to those events. The observation mechanism dispatches events when a persistent change is made to the workspace. Magnolia uses observation heavily. For instance, observation is used to reload module configurations and to reload all objects provided by the FactoryUtil.

To use observation you must at least specify the workspace, the path to the node which should be observed, and an event listener. The event listener's onEvent() method is called whenever there are changes in the observed node.

Magnolia provides a helper class ObservationUtil to assist you in using observation for your project. For more information please refer to the Javadoc.

Content2Bean

Most of Magnolia's configuration is stored in the config workspace. To transfer the repository stored configuration into a Java object a mechanism called Content2Bean is used. Content2Bean populates a Java Bean from the content of a repository node including sub nodes. This functionality is not limited to the config node although that is the node most commonly used for storing Magnolia's configuration details.

Where is it used?

Content2Bean is a concept that will be used increasingly in more areas of Magnolia.

For developers the module configuration (ModuleManagerlmpl) using the module class is the most important current usage of Content2Bean.

Data types

Content2Bean analyses the bean's "setter" and "adder" methods using introspection and uses them if a suitable configuration value is available. With "adder" methods (using the singular form of the node names) you can populate collections and maps. With this mechanism, Content2Bean can support all possible data types:

• Simple data types like String, int, long, float, double, boolean (to specify "true" you can use "true", TRUE", or "1") with the suitable "setter" method
• Other data types matching the "setter" method's signature
• Collections with String values or other data types by specifying a class property
• Maps with keys and values as Strings or other data types by specifying a class property

Simple Data Types

Values with simple data types must be defined as properties (NodeData). The property's name must match its respective setter method.

Collections

To configure a collection you have to create a sub node and a suitable "setter" method.

• All properties of the collection node will create simple String entries in the collection. The properties' names are not used by Content2Bean, only the values.
• All sub nodes of the collection node will be treated as objects of the type specified in the class property (NodeData) in the sub node. If no class attribute is specified, a Map will be created instead. the sub nodes' names are not used by Content2Bean.
• All sub nodes of the collection node will be treated as maps unless they have a ".". The properties' names and the sub nodes' names are not used by Content2Bean.

Maps

The rules to populate a map are the same as with collections, except that the properties' names and the sub nodes' names are used as key values.

Example: Cache Configuration

The following example is used for clarification: Let's have a look at the cache configuration:

The configuration creates an object of type CacheConfiguration This class needs public suitable "setter" or "adder" methods. This is what we find:

    public void setCachePolicy(CachePolicy cachePolicy);
    public void setFlushPolicy(FlushPolicy flushPolicy);
    public void setBrowserCachePolicy(BrowserCachePolicy browserCachePolicy);
    public void setExecutors(Map executors);
    public void addExecutor(String name, CachePolicyExecutor executor);

Now let's see what happens with setCachePolicy(CachePolicy cachePolicy).

 Since there is a class property defined, let's look at the class Content2Bean uses to create the new object: Default

public void setVoters(VoterSet voters);

Now let's have a look at the addExecutor(String name, CachePolicyExecutor executor) method in CacheConfiguration and the configuration:

Since this method has two arguments, the node name bypass is passed as the first argument and a Bypass object as second argument. Because CachePolicyExecutor is an interface, the implementing class is specified.

Singletons and Configuration

Most of the important classes in Magnolia are singleton classes, which means that only one instance per class exists. The creation of such a singleton object is done by a factory utility: FactoryUtil.

The typical method to access a singleton is getInstance() which is implemented in Magnolia like this, an example from TemplateRendererManager:

public static TemplateRendererManager getInstance() {
        return (TemplateRendererManager) FactoryUtil.getSingleton(TemplateRendererManager.class);
}

The FactoryUtil checks to see if there is a property with the fully qualified class name as its key.

• If there is a fully qualified class name key then the value of the property is expected to be the fully qualified name of the implementing class to be used and FactoryUtil will instantiate the respective object.
• If not, then an instance of the previously applied class will be instantiated.

info.magnolia.module.templating.TemplateRendererManager=my.own.TemplateRendererManager

Voters

Voters are used in Magnolia whenever configuration values are not assigned at startup but instead depend on rules. For example the cache module has to determine if a requested resource may be cached or not. The rules to determine values should be configurable.

The rules are user-defined using voters 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.

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:

For most of the "real world" voters only boolean results make sense. These boolean voters return "1" for a "true" and "0" for a "false" result.

Examples of voters

Here are a couple of voters samples. For further information, please see the javadoc at package-summary.

Voter	Parameters	boolean?	Description
AuthenticatedVoter	(none)		Checks if the current user is authenticated.
ExtensionVoter	allow: comma separated lists of allowed extensions. deny: comma separated lists of denied extensions.		Returns false if the extension is not a valid mimetype (as configured in config:/server/MIMEMapping. Returns false if the allow list exists, but the extension is not in the allow list. Returns false if the deny list exists and the extension is in the deny list. Returns true in any other cases.