Container configuration
eXo Portal uses PicoContainer, which implements the Inversion of Control (IoC) design pattern. All eXo containers inherit from a PicoContainer. There are mainly two eXo containers used, each of them can provide one or several services. Each container service is delivered in a JAR file. This JAR file may contain a default configuration. The use of default configurations is recommended and most services provide it.
When a Pico Container searches for services and its configurations, each configurable service may be reconfigured to override default values or set additional parameters. If the service is configured in two or more places the configuration override mechanism will be used.
Confused? - You might be interested in the
Service Configuration for Beginners article, which explains the basics.
Configuration Retrieval
The container performs the following steps making eXo Container configuration retrieval depending on the container type.
Configuration retrieval order for the PortalContainer
The container is initialized by looking into different locations. Configurations are overloaded in the following lookup sequence :
- Services default RootContainer configurations from JAR files /conf/configuration.xml
- External RootContainer configuration, if will be found at $AS_HOME/exo-conf/configuration.xml
- Services default PortalContainer configurations from JAR files /conf/portal/configuration.xml
- Web applications configurations from WAR files /WEB-INF/conf/configuration.xml
- External configuration for services of named portal, if will be found at $AS_HOME/exo-conf/portal/$PORTAL_NAME/configuration.xml (since kernel 2.0.3)
Configuration retrieval for a StandaloneContainer
- Services default RootContainer configurations from JAR files /conf/configuration.xml
- External RootContainer configuration, if will be found at $AS_HOME/exo-conf/configuration.xml
then depending on the StandaloneContainer configuration URL initialization,
- if configuration URL was initialized to be added to services defaults
// add configuration to the default services configurations from JARs/WARs
StandaloneContainer.addConfigurationURL(containerConf);
- Services default StandaloneContainer configurations from JAR files /conf/portal/configuration.xml
- Web applications configurations from WAR files /WEB-INF/conf/configuration.xml
- Configuration from added URL containerConf will override only services configured in the file
- if configuration URL was initialized to override services defaults
// full services configuration will be used instead of default ones from services JARs/WARs
StandaloneContainer.setConfigurationURL(containerConf);
- Overridden configuration only will be used (DEPRECATED, it's required to configure ALL services on which an application depends).
- if configuration URL not initialized at all, the order is
- Services default StandaloneContainer configurations from JAR files /conf/portal/configuration.xml
- Web applications configurations from WAR files /WEB-INF/conf/configuration.xml
- External configuration for StandaloneContainer services, it will be found at $AS_HOME/exo-configuration.xml. If $AS_HOME/exo-configuration.xml doesn't exist and the StandaloneContainer instance obtained with the dedicated configuration classloader the container will try to retrieve the resource conf/exo-configuration.xml within the given classloader.
Notes
$AS_HOME - application server home directory, or user.dir JVM system property value in case of Java Standalone application.
$PORTAL_NAME - portal web application name.
External configuration location can be overridden with System property exo.conf.dir. If the property exists its value will be used as path to eXo configuration directory, i.e. to $AS_HOME/exo-conf alternative. E.g. put property in command line java -Dexo.conf.dir=/path/to/exo/conf (since kernel 2.0.4). In this particular use case, you have no need to use any prefix to import other files. For instance, if your configuration file is $AS_HOME/exo-conf/portal/PORTAL_NAME/configuration.xml and you want to import the configuration file $AS_HOME/exo-conf/portal/PORTAL_NAME/mySubConfDir/myConfig.xml, you can do it by adding <import>mySubConfDir/myConfig.xml</import> to your configuration file.
Under JBoss application server exo-conf will be looked up in directory described by JBoss System property jboss.server.config.url. If the property is not found or empty $AS_HOME/exo-conf will be asked (since kernel 2.0.4).
The search looks for a configuration file in each JAR/WAR available from the classpath using the current thread context classloader. During the search these configurations are added to a set. If the service was configured previously and the current JAR contains a new configuration of that service the latest (from the current JAR/WAR) will replace the previous one. The last one will be applied to the service during the services start phase.
Warning: Take care to have no dependencies between configurations from JAR files (/conf/portal/configuration.xml and /conf/configuration.xml) since we have no way to know in advance the loading order of those configurations. In other words, if you want to overload some configuration located in the file /conf/portal/configuration.xml of a given JAR file, you must not do it from the file /conf/portal/configuration.xml of another JAR file but from another configuration file loaded after configurations from JAR files /conf/portal/configuration.xml
After the processing of all configurations available in system the container will initialize it and start each service in order of the dependency injection (DI).
The user/developer should be careful when configuring the same service in different configuration files. It's recommended to configure a service in its own JAR only. Or, in case of a portal configuration, strictly reconfigure the services in portal WAR files or in an external configuration.
There are services that can be (or should be) configured more than one time. This depends on business logic of the service. A service may initialize the same resource (shared with other services) or may add a particular object to a set of objects (shared with other services too). In the first case it's critical who will be the last, i.e. whose configuration will be used. In the second case it's no matter who is the first and who is the last (if the parameter objects are independent).
Configuration retrieval log
In case of problems with service configuration it's important to know from which JAR/WAR it comes. For that purpose the JVM system property
org.exoplatform.container.configuration.debug can be used.
java -Dorg.exoplatform.container.configuration.debug ...
If the property is enabled the container configuration manager will report the configuration adding process to the standard output (System.out).
......
Add configuration jar:file:/D:/Projects/eXo/dev/exo-working/exo-tomcat/lib/exo.kernel.container-trunk.jar!/conf/portal/configuration.xml
Add configuration jar:file:/D:/Projects/eXo/dev/exo-working/exo-tomcat/lib/exo.kernel.component.cache-trunk.jar!/conf/portal/configuration.xml
Add configuration jndi:/localhost/portal/WEB-INF/conf/configuration.xml
import jndi:/localhost/portal/WEB-INF/conf/common/common-configuration.xml
import jndi:/localhost/portal/WEB-INF/conf/database/database-configuration.xml
import jndi:/localhost/portal/WEB-INF/conf/ecm/jcr-component-plugins-configuration.xml
import jndi:/localhost/portal/WEB-INF/conf/jcr/jcr-configuration.xml
......
