• Properties
• Multiple configurations on a single Web application archive
• Customization
• Defining properties
• Extending configuration
• Overrides
• Observation
• Content2Bean
• Content2Bean in module instances
• Data types
• Classes
• Simple Data Types
• Collections
• Maps
• Example: Cache Configuration
• Voters
• Voter examples

Properties

Property files are used for configuration during the startup sequence before the repository is available. These properties configure the instance for a particular use (such as a development or production environment) and set various system directories. Once the startup sequence is completed and the repository is available, the majority of configuration is done in the config workspace in the repository.

Properties are not stored in a single property file but come from multiple sources. These sources are processed or parsed in the order shown in this table:

	Source	Location	Path / Comment
1	Bean properties	magnolia-core.jar	/mgnl-beans.properties
2.	Module properties	module descriptor	<properties> <property> <name>defaultPublicURI</name> <value>redirect:/help.html</value> </property> </properties>
3.	Global file properties	web application	WEB-INF/config/magnolia.properties
4.	Default file properties	web application	WEB-INF/config/default/magnolia.properties
5.	Web application file properties	web application	WEB-INF/config/(webapp)/magnolia.properties
6.	Server file properties	web application	WEB-INF/config/(servername)/magnolia.properties
7.	Web application at server file properties	web application	WEB-INF/config/(servername)/(webapp)/magnolia.properties
8.	System properties	JVM (-Dx=y)	existing properties will be overriden by available System properties

Sources processed earlier may be overridden by sources processed later. The processing order and distribution of properties into several sources allows for flexible customization. The following are key properties set in the default magnolia.properties file:

Multiple configurations on a single Web application archive

Default properties are common regardless of the server name or webapp name. Webapp specific properties are installed only if the webapp name matches. Correspondingly, server specific properties are only installed if the server name matches. For example, Magnolia CMS ships with two webapps by default: magnoliaAuthor and magnoliaPublic.

It is possible to set a different persistence manager per environment. For example, on the development instance you could use the default embedded Derby database, whilst on production you could use a production-scale persistent storage such as a MySQL database.

See WAR file with multiple configurations for more on this topic.

Customization

The structure and the order of source execution allows you to provide sophisticated configurations and flexible customization. The default Magnolia CMS configuration (delivered in the web application bundle) provides an example of how the mechanism works:

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

Magnolia CMS provides a single web application which configures itself depending on the servlet context it is installed in. If your environment has multiple staging systems with differing configuration needs, you can apply different configurations by adding a server name to each of the listed paths.

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

Defining properties

Properties can be accessed through the static methods of the Magnolia CMS' SystemProperty class. The following table lists the properties and default values:

Property	Description	Default value
magnolia.cache.startdir	Directory used for cached pages.	${magnolia.app.rootdir}/cache
magnolia.upload.tmpdir	Temporary directory for uploaded files.	${magnolia.app.rootdir}/tmp
magnolia.exchange.history	History directory used for activation.	${magnolia.app.rootdir}/history
magnolia.repositories.config	Repository configuration, points to an XML file.	WEB-INF/config/default/repositories.xml
magnolia.repositories.home	Repository home directory.	${magnolia.app.rootdir}/repositories
magnolia.repositories.jackrabbit.config	Jackrabbit configuration, points to an XML file.	WEB-INF/config/repo-conf/jackrabbit-bundle-derby-search.xml or WEB-INF/config/repo-conf/jackrabbit-bundle-mysql-search.xml or WEB-INF/config/repo-conf/jackrabbit-memory-search.xml. Beware when using the last one that any changes to the JCR repository will be lost upon restart.
log4j.config	Location of a log4j config file. Can be a .properties or .xml file. The value can be: a full path a path relative to the webapp root a file name which will be loaded from the classpath	WEB-INF/config/default/log4j.xml
magnolia.logs.dir	Directory where logs are written.	${magnolia.app.rootdir}/logs
magnolia.bootstrap.dir	Directory containing XML files for initialization of a blank Magnolia CMS instance. If no content is found in any of the repositories, they are initialized by importing the XML files found in this folder. If you don't want to let Magnolia initialize repositories automatically then remove this parameter.	WEB-INF/bootstrap/author WEB-INF/bootstrap/common
magnolia.bootstrap.authorInstance	Set an instance as author (true) or public (false).	true This is only used for the initial installation afterward the configuration in the config repository is used. The value is saved in /server/admin.
magnolia.boostrap.samples	Some modules contain optional sample content. They will check this property to decide if they should install the content.	true
magnolia.utf8.enabled	Activate UTF-8 support for pages.	false
magnolia.develop	Set to false on production instances to enhance the performance of JavaScript generation.	true
magnolia.connection.jcr.userId	User ID for repository connection.	admin
magnolia.connection.jcr.password	Password for repository connection.	admin
magnolia.update.auto	Set to true if bootstrapping and update should be performed automatically after installation. This simply means the system won't wait for the user to start the update manually.	true
magnolia.author.key.location	Location of private and public keys used for activation	${magnolia.home}/WEB-INF/config/default/magnolia-activation-keypair.properties

In addition to these examples you can define arbitrary properties (magnolia.home is one example).

Extending configuration

You can extend a configuration by defining an extends data node and setting its value to the source configuration you want it to inherit. The target configuration inherits everything from the source and adds its own exceptions. This can save time and effort as you only need to define exceptions explicitly. The mechanism is only available in the config repository. In the example below, the demo-project site definition extends the default site definition.

The definition inherits all configuration from the defaultconfiguration and adds its own domains, internationalization and URI-to-repository mappings. The extends property can point to the source configuration with an absolute or relative path.

Overrides

Extending is additive by default, which means that configuration specified at the extending level is added to the inherited configuration. Setting the extends property to override changes this behavior. An override allows the extending node to completely remove the inherited content and replace it with its own content entries. In the example below, the demo-project site definition supports two locales, en (English) and de (German), whereas site demo-project-fr is targeted to French speakers only.

The French site extends demo-project. It inherits all configuration except the locales. An override under the locales content node removes en and de. Only the French locale fr defined at this level is applied. This means that authors can enter only French content on the French site.

Observation

Observation is a feature of the Java Content Repository that enables applications to register interest in events that describe changes to a workspace. The applications can then monitor and respond to those events. The observation mechanism dispatches events when a persistent change is made to the workspace. Magnolia CMS 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 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. Note that configuration details are not restricted to the config node. The following table shows where the Content2Bean mechanism is currently used in Magnolia:

Where is it currently used?	What is configured?	Javadoc
ServerConfiguration	The server configuration with admin defaultBaseUrl defaultExtension	ServerConfiguration
ParagraphManager	The paragraphs	ParagraphManager
VirtualURIManager	The virtual URI settings	VirtualURIManager
MgnlMainFilter	The Magnolia filter chain	MgnlMainFilter
MessagesManager	The system languages stored at /server/i18n/system.languages	MessagesManager
FactoryUtil.ObservedObjectFactory		FactoryUtil.ObservedObjectFactory
CommandsManager	Registers the comand catalogs	CommandsManager
ModuleManagerImpl	The module configuration	ModuleManagerImpl
PageHandlerManager	The pages	PageHandlerManager

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

Content2Bean in module instances

Module configuration data is transferred into a Bean from /modules/moduleName/config. The Bean class to build is defined in the module descriptor XML file.

Components. If a path in the config workspace is given rather than a concrete class name, then Content2Bean is used to build the component instance.

Additional items such as paragraphs, templates and virtual URI mappings are configured at module level.

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

All sub elements are also built using Content2Bean.

Classes

The class used to instantiate an object through the Content2Bean mechanism is determined through reflection or by explicitly referencing a class in the class node data. By referencing a specific class you can override Magnolia CMS default configuration and implement your own caching behavior, security mechanism and so on.

Numbered items:

1. config: Entry point of the transformation. In the module descriptor {SampleConfig}} class is used. Set text and number properties.
2. sub: Sub bean. The class is determined using reflection if it is not explicitly defined.
3. items: Collection. The corresponding add method is used to determine the class and populate the collection if existing.
4. item2: Special item with its own class and additional properties.
5. parameters: Collection of key-value pairs.

Simple Data Types

Values with simple data types must be defined as properties (NodeData). Each property 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 configuration creates an object of type CacheConfiguration This class needs public suitable "setter" or "adder" methods. This is what we find: Note that all necessary setters are available. For the executors node there are "setter" and "adder" methods. As the adder is more specific the setExecutors method will not be used.

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

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

As 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.

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.

The basic concept of voters uses Voter 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:

Vote results	VoterSet result
-3, 0, 2	-3
-3, 0, 3	3
-3, 0, 4	4

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.

Voter examples

Voter	Parameters	Boolean	Description
AuthenticatedVoter	none	Yes	Checks if the current user is authenticated.
ExtensionVoter	allow: comma separated lists of allowed extensions. deny: comma separated lists of denied extensions.	Yes	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.

For further information, please see the javadoc at package-summary.