You are looking at documentation for an older release. Not what you want? See the current release documentation.
The container performs the following steps to make eXo Container configuration retrieval, depending on the container type.
Configuration retrieval order for PortalContainer
The container is initialized by looking into different locations. This container is used by portal applications. Configurations are overloaded in the following lookup sequence:
Default RootContainer configurations from .jar files at /conf/configuration.xml.
Configurations from .ear and .war files at /META-INF/exo-conf/configuration.xml.
In case of an .ear, if the configuration could be found inside the META-INF folder, it will use only this file and will ignore configuration
files in the META-INF folder of the web applications included in the .ear file.
External RootContainer configuration can be found at $AS_HOME/exo-conf/configuration.xml.
Default PortalContainer configurations from .jar files at /conf/portal/configuration.xml.
Web applications configurations from .war files at /WEB-INF/conf/configuration.xml.
External configuration for services of named portal can be found at $AS_HOME/exo-conf/portal/$PORTAL_NAME/configuration.xml.
Configuration retrieval for StandaloneContainer
The container is initialized by looking into different locations. This container is used by non-portal applications. Configurations are overloaded in the following lookup sequence:
Default StandaloneContainer configurations from JAR files
at /conf/configuration.xml.
Default StandaloneContainer configurations from JAR files
at /conf/portal/configuration.xml.
Web applications configurations from WAR files
at /WEB-INF/conf/configuration.xml.
Then depending on the StandaloneContainer
configuration URL initialization:
If configuration URL was initialized to be added to services defaults, as below:
// add configuration to the default services configurations from JARs/WARs
StandaloneContainer.addConfigurationURL(containerConf);
Configuration from added URL containerConf will override only services configured in the file.
If configuration URL is not initialized at all, it will be
found at $AS_HOME/exo-configuration.xml.
If $AS_HOME/exo-configuration.xml does not
exist, the container will look for it at
$AS_HOME/exo-conf/exo-configuration.xml
location and if it is still not found 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.
General notes about the configuration retrieval
$AS_HOME is application server home
directory, or user.dir JVM system property
value in case of Java Standalone application.
The application server home is:
For Jonas, the value of the variable
${jonas.base}.
For Jetty, the value of the variable
${jetty.home}.
For Websphere, the value of the variable
${was.install.root}.
For Weblogic, the value of the variable
${wls.home}.
For Glassfish, the value of the variable
${com.sun.aas.instanceRoot}.
For Tomcat, the value of the variable
${catalina.home}.
For JBoss AS, the value of the variable
${jboss.server.config.url} or
${jboss.server.config.dir} if the exo-conf directory can be found there;
otherwise it will be the value of the ${jboss.home.dir} variable.
$PORTAL_NAME is the name of portal web application.
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. In this
particular usecase, you do not 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.
The name of the configuration folder that is by default "exo-conf", can be changed thanks to the System property: exo.conf.dir.name.
Even if you modify the configuration folder, it will remain "exo-conf" for the files that are retrieved from the META-INF folder. This affects only the externalized configuration files.
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.
To be able to retrieve the configuration files inside the .ear
and .war files, Kernel does a lookup inside the standard folders
where the archives are deployed. If for some reasons, you would need to
redefine the list of folders where the archives are deployed, you
can use the System property: exo.archive.dirs
and set it to a comma separated list of paths relative to the $AS_HOME.
The .ear and .war files from which Kernel gets the
configuration files for the RootContainer, are found thanks to a
lookup inside the standard deployment folders, but so far those
folders are only properly defined in case of JBoss AS, Tomcat and Jetty.
For other application servers, you will need to use the
System property described in the previous note.
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 /conf/portal/configuration.xml file of a
given .jar file, you must not do it from the
/conf/portal/configuration.xml file of another .jar
but from another configuration file loaded after configurations
from .jar files: /conf/portal/configuration.xml.
After processing 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 is 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 once. This depends on the 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 is critical who will be the last, i.e. whose configuration will be used. In the second case, it does not matter who is the first and who is the last (if the parameter objects are independent).
Getting the effective configuration at runtime
The effective configuration of StandaloneContainer, RootContainer and/or PortalContainer can be known thanks to the getConfigurationXML() method that is exposed through JMX at the container's level. This method will give you the effective configuration in XML format that has been really interpreted by Kernel. This could be helpful to understand how a given component or plugin has been initialized.