Magnolia 5.6 reached end of life on June 25, 2020. This branch is no longer supported, see End-of-life policy.
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 this order:
Source | Location | Path / Example | |
---|---|---|---|
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 options (-Dx=y) | Existing properties will be overridden 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.
Some important properties set in the default magnolia.properties
file:
# Repository configuration magnolia.repositories.config = WEB-INF/config/default/repositories.xml magnolia.repositories.home = $\{magnolia.app.rootdir\}/repositories magnolia.repositories.jackrabbit.config = WEB-INF/config/repo-conf/jackrabbit-bundle-h2-search.xml # Defining the instance as author instance # Only used for the initial installation. # Afterwards configuration in the config repository is used. # The value is saved in /server/admin magnolia.bootstrap.authorInstance=true # Switch to false to enhance the performance of Javascript generation magnolia.develop=false # Set to true if bootstrapping/update should be performed automatically magnolia.update.auto=false
magnolia.app.rootdir
is set programmatically during Magnolia start-up. Its value depends on the servlet container and on the environment, for instance on a production Tomcat it would be something like /some-path/some-tomcat/webapps
.
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 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.
The MySQL InnoDB storage engine is supported by Magnolia, the MyISAM engine is not. InnoDB is the default engine in MySQL 5.5 and later.
The structure and the order of source execution allows you to provide sophisticated configurations and flexible customization. The default Magnolia 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 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:
<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>
Properties can be accessed through the info.magnolia.init.MagnoliaConfigurationProperties
class.
Name | Required/Optional | Description |
---|---|---|
log4j.config | required | default is Name of a log4j config file. Can be a .properties or .xml file. The value can be:
|
magnolia.bootstrap.dir | required | default is Directory containing XML files for initialization of a blank Magnolia 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. |
magnolia.cache.startdir | required | default is Directory used for cached pages. |
magnolia.connection.jcr.password | required | default is Password for repository connection. |
magnolia.connection.jcr.userId | required | default is User ID for repository connection. Jackrabbit uses the default There is no security risk with those values because they are used only internally to communicate between Magnolia and Jackrabbit and are not exposed to the outside world. With those credentials, you cannot log in to the repository via UI or externally since Magnolia keeps exclusive access to it. |
magnolia.exchange.history | required | default is History directory used for activation. |
magnolia.repositories.config | required | default is Repository configuration, points to an XML file. |
magnolia.repositories.jackrabbit.cluster.master | required if you have any clustered workspaces in your project. | default is Identifies the instance as a cluster master node. During installation and update Magnolia bootstraps content only into master nodes. This ensures that other (replica) nodes installed later don't override already bootstrapped content. Example: Public instance A is defined as a cluster master node. The instance starts and creates a clustered
|
magnolia.upload.tmpdir | required | default is Temporary directory for uploaded files. |
magnolia.author.key.location | optional | default is Location of private and public keys used for activation. |
magnolia.bootstrap.authorInstance | optional | default is Sets an instance as author ( |
magnolia.bootstrap.samples | optional | default is Some modules contain optional sample content. They will check this property to decide if they should install the content. |
magnolia.components.config.properties.excluded | optional | List of component class names to be excluded from component instantiation. Separate class names with white space (space, tab) or commas. |
magnolia.content.bootstrap.dir | optional | The directory to import file system XML files from with the Content Importer module. If the path is not set, the content importer module is stopped. |
magnolia.develop | optional | default is
Set to |
magnolia.home | optional | default is Root of the webapp's deployment directory. |
magnolia.jsr250.enabled | optional | default is Enables support for JSR-250 annotations. Magnolia uses the |
magnolia.logs.dir | optional | default is Directory where logs are written. |
magnolia.migration.persistReport | optional | default is Turns off migration report generation to speed up the migration process. Set to |
magnolia.repositories.home | optional | default is Repository home directory. |
magnolia.repositories.jackrabbit.config | optional | default is Jackrabbit configuration file. See the |
magnolia.repositories.jackrabbit.cluster.config | optional | Jackrabbit configuration file for a clustered repository.
|
magnolia.resources.classpath.observation.pattern | optional | default is Pattern to define which resources should be observed by $webResourceManager.requireResource("info.magnolia.sys.confluence.artifact-info-plugin:javadoc-resource-macro-resources")
ClasspathScanner
The default pattern above observes any file names that end in .ftl and .yaml |
magnolia.resources.dir | optional | default is Defines the directory from which filesystem resources such as light modules are loaded in a Magnolia instance. |
magnolia.resources.filesystem.observation.excludedDirectories | optional | default is List of excluded resource directories in FileSystemResourceOrigin.
to prevent slow loading of pages. |
magnolia.resources.watcher.sensitivity | optional | default is The sensitivity (speed) with which the changes of the resources in the Possible values: |
magnolia.update.auto | optional | default is Set to |
magnolia.utf8.enabled | optional | default is Activate UTF-8 support for pages. |
magnolia.clusterid | optional | default is set in set in Jackrabbit configuration file The ID of the JCR cluster instance. When setting the value in magnolia.properties, it overrides the value set in the Jackrabbit configuration file; this allows using a single configuration file for all the cluster instances. |
| optional | (Magnolia 5.6.2+) The properties add a sticker to the AdminCentral interface to provide a clear visual clue about the type of the instance and environment the user is currently interacting with. Example setting:
Next to the logged in user's name, this configuration will render a sticker with the value set in the The instance name is taken from the
|
In addition to these examples you can define arbitrary properties (magnolia.home
is one example).
Substitution
Properties can be used to prefixother path-like properties. For example, in
the property magnolia.cache.startdir=${magnolia.home}/cache
magnolia.cache.startdir
is set by substituting the root directory with property magnolia.home
. See WAR file with multiple configurations on how to use properties to target a deployment environment.
You can extend a configuration by defining an extends
property 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 sportstation
site definition extends the travel
site definition. The definition inherits all configuration from the travel
configuration and adds its own domains, internationalization and URI-to-repository mappings, theme and templates. The extends
property can point to the source configuration with an absolute or relative path.
Node name | Value |
---|---|
fallback | |
travel | |
sportstation | |
mappings | |
theme | |
templates | |
domain | |
i18n | |
extends | ../travel |
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 travel
site definition supports two locales, en
(English) and de
(German), whereas site travel-fr
is targeted to French speakers only.
The French site extends travel
. It inherits all configuration except the locales. An override under the locales 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.
Node name | Value |
---|---|
travel | |
templates | |
theme | |
mappings | |
domains | |
i18n | |
locales | |
en | |
de | |
class | info.magnolia.cms.i18n.DefaultI18nContentSupport |
enabled | true |
fallbackLocale | en |
travel-fr | |
domains | |
i18n | |
locales | |
fr | |
extends | override |
extends | ../travel |
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 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 to assist you in using observation for your project. Use
Most configuration is stored in the config workspace. To transfer the repository stored configuration into a Java object, a mechanism called Node2Bean is used. Node2Bean 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 Node2Bean mechanism is currently used.
Where it is used | What is configured |
---|---|
$webResourceManager.requireResource("info.magnolia.sys.confluence.artifact-info-plugin:javadoc-resource-macro-resources")
ServerConfiguration
| Basic server configuration:
|
$webResourceManager.requireResource("info.magnolia.sys.confluence.artifact-info-plugin:javadoc-resource-macro-resources")
VirtualURIManager
| Mapping virtual URIs to pages. |
$webResourceManager.requireResource("info.magnolia.sys.confluence.artifact-info-plugin:javadoc-resource-macro-resources")
FilterManagerImpl
| Filter chain |
$webResourceManager.requireResource("info.magnolia.sys.confluence.artifact-info-plugin:javadoc-resource-macro-resources")
DefaultMessagesManager
| Messages for localized labels and descriptions in the UI. |
$webResourceManager.requireResource("info.magnolia.sys.confluence.artifact-info-plugin:javadoc-resource-macro-resources")
CommandsManager
| Commands and command catalogs. |
$webResourceManager.requireResource("info.magnolia.sys.confluence.artifact-info-plugin:javadoc-resource-macro-resources")
ModuleManagerImpl
| Module definitions |
$webResourceManager.requireResource("info.magnolia.sys.confluence.artifact-info-plugin:javadoc-resource-macro-resources")
ConfiguredComponentFactory
| Builds a component configured in the repository. |
$webResourceManager.requireResource("info.magnolia.sys.confluence.artifact-info-plugin:javadoc-resource-macro-resources")
ObservedComponentFactory
| |
$webResourceManager.requireResource("info.magnolia.sys.confluence.artifact-info-plugin:javadoc-resource-macro-resources")
GuiceConfiguredComponentProvider
| Guice Provider that creates an object by reading it from the repository. |
$webResourceManager.requireResource("info.magnolia.sys.confluence.artifact-info-plugin:javadoc-resource-macro-resources")
ConfiguredRendererProvider
| RendererProvider that instantiates a renderer from a configuration node. |
$webResourceManager.requireResource("info.magnolia.sys.confluence.artifact-info-plugin:javadoc-resource-macro-resources")
ConfiguredTemplateDefinitionProvider
| TemplateDefinitionProvider that instantiates a template from a configuration node. |
For developers, module configuration (ModuleManagerlmpl
) using the module class is the most important current usage of Content2Bean.
Module configuration data is transferred into a Bean from /modules/<module name>/config
. The Bean class to build is defined in the module descriptor XML file.
<!DOCTYPE module SYSTEM "module.dtd"> <module> <name>samples</name> <displayName>Magnolia Samples Module </displayName> <class> info.magnolia.module.samples.SamplesModule </class>
Components. If a path in the config workspace is given rather than a concrete class name, then Node2Bean is used to build the component instance.
# Map to a path in the config workspace info.magnolia.cms.i18n.I18nContentSupport = /server/i18n/content
Additional items such as components, templates and virtual URI mappings are configured at module level.
Node2Bean 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, Node2Bean can support all possible data types:
All sub elements are also built using Node2Bean.
The class used to instantiate an object through the Node2Bean 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 default configuration and implement your own caching behavior, security mechanism and so on.
Numbered items:
config
: Entry point of the transformation. In the module descriptor SampleConfig
class is used. Set text
and number
properties.sub
: Subbean. The class is determined using reflection if it is not explicitly defined.items
: Collection. The corresponding add
method is used to determine the class and populate the collection if existing.item2
: Special item with its own class and additional properties.parameters
: Collection of key-value pairs.Values with simple data types must be defined as properties. Each property name must match its respective setter method.
To configure a collection you have to create a sub node and a suitable "setter" method:
class
property in the sub node. If no class attribute is specified, a Map will be created instead. The sub nodes' names are not used by Node2Bean.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.
The configuration creates an object of type
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);
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.
Node name | Value |
---|---|
cache | |
config | |
configurations | |
default | |
cachePolicy | |
flushPolicy | |
browserCachePolicy | |
executors |
This is what happens with setCachePolicy(CachePolicy cachePolicy)
.
Node name | Value |
---|---|
cache | |
config | |
configurations | |
default | |
cachePolicy | |
voters | |
urls | |
deny | |
resources | |
class | info.magnolia.module.cache.cachepolicy.Default |
Since there is a class property defined, let's look at the
public void setVoters(VoterSet voters);
Now let's have a look at the addExecutor (String name, CachePolicyExecutor executor)
method in CacheConfiguration and the configuration:
Node name | Value |
---|---|
executor | |
bypass | |
class | info.magnolia.module.cache.executor.Bypass |
store | |
useCache |
As this method has two arguments, the node name bypass
is passed as the first argument and a Bypass
object as the second argument. Because CachePolicyExecutor
is an interface, the implementing class is specified.
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:
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 | Parameters | Boolean | Description |
---|---|---|---|
$webResourceManager.requireResource("info.magnolia.sys.confluence.artifact-info-plugin:javadoc-resource-macro-resources")
AuthenticatedVoter
| none | Yes | Checks if the current user is authenticated. |
$webResourceManager.requireResource("info.magnolia.sys.confluence.artifact-info-plugin:javadoc-resource-macro-resources")
ExtensionVoter
|
| Yes |
|
For further information, please see the
1 Comment
David Caviedes Marquez
Hello, we have a question relative to these properties:
magnolia.ui.sticker.environment
magnolia.ui.sticker.color
A very common error is to do the job in the wrong instance (public or author) so it´s very useful to show
MagnoliaConfigurationProperties#MAGNOLIA_WEBAPP
by default without the need of doing a click on the sticker. Is it possible?Regards