1.2.4. Configuration retrieval

Warning

You are looking at documentation for an older release. Not what you want? See the current release documentation.

The configuration you find inside the .jar file is considered as the default configuration. If you want to override this default configuration, you can do it in different places outside the .jar. When the container finds several configurations for the same service, the configuration which is found later replaces completely the one found previously. Let's call the configuration overriding mechanism.

RootContainer

As both containers, PortalContainer and StandaloneContainer, depend on the RootContainer, we will start by looking into this one.

The retrieval sequence in short:

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 file 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, to be found at $PLATFORM_TOMCAT_HOME/gatein/conf/configuration.xml.

HashTable: The RootContainer creates a Java HashTable which contains key-value pairs for the services. The qualified interface name of each service is used as key for the hashtable. Hopefully, you still remember that the <key> tag of the configuration file contains the interface name? The value of each hashtable pair is an object that contains the service configuration (this means the whole structure between the <component> tags of your configuration.xml file).

The RootContainer runs over all .jar files you find in $PLATFORM_TOMCAT_HOME/lib and looks if there is a configuration file at /conf/configuration.xml, the services configured in this file are added to the hashtable. In that way (at the end of this process), the default configurations for all services are stored in the hashtable.

Note

What happens if the same service - recognized by the same qualified interface name - is configured in different jars? As the service only can exist one time, the configuration of the jar found later overrides the previous configuration. You know that the loading order of the jars is unpredictable, so you must not depend on this.

If you wish to provide your own configurations for one or several services, you can do it in a general configuration file that has to be placed at $PLATFORM_TOMCAT_HOME/gatein/conf/configuration.xml. Here again, the same rule applies: The posterior configuration replaces the previous one.

The further configuration retrieval depends on the container type.

PortalContainer

The PortalContainer takes the hashtable filled by the RootContainer and continues looking in some more places. Here you get the opportunity to replace RootContainer configurations by those which are specific to your portal. Again, the configurations are overridden whenever necessary.

In short, PortalContainer configurations are retrieved in the following lookup sequence:

Default PortalContainer configurations from all Jar files (/conf/portal/configuration.xml).
Web application configurations from the portal.war file - or the portal webapp (/WEB-INF/conf/configuration.xml).
External configuration for services of a named portal, it will be found at $PLATFORM_TOMCAT_HOME/gatein/conf/portal/$portal_name/configuration.xml.

As you see here, the /conf/portal/configuration.xml file of each jar enters the game, they are searched at first. Next, there is nearly always /WEB-INF/conf/configuration.xml in the portal.war. In this file, you will find a lot of import statements that point to other configuration files in portal.war.

Multiple Portals: Be aware that you might set up several different portals (for example, "admin", "mexico"), each of these portals will use a different PortalContainer. And each of these PortalContainers can be configured separately. Like in GateIn, you also will be able to provide configurations from outside the jars and wars or webapps. Put a configuration file in $PLATFORM_TOMCAT_HOME/gatein/conf/portal/$portal_name/configuration.xml where $portal_name is the name of the portal you want to configure for. But normally, you only have one portal which is called "portal", so you use $PLATFORM_TOMCAT_HOME/gatein/conf/portal/portal/configuration.xml.

Note

The location of external configuration file can be changed via system property exo.conf.dir.

StandaloneContainer

In the same way as the PortalContainer, the StandaloneContainer takes over the configuration of the RootContainer. After that, the configuration gets a little bit more tricky because standalone containers can be initialized using an URL. This URL contains a link to an external configuration. As you probably never need a standalone configuration, you can safely jump over the remaining confusing words of this section.

After taking over RootContainer's configuration, there are three cases which depend on the URL initialization:

Independent configuration by URL: No other configuration file is taken into consideration. The configuration provided by the URL is used without any default configurations. This means the container creates a new empty hashtable and not any bit of previous configuration is used. Apply the following code to do this:
```
StandaloneContainer.setConfigurationURL(containerConf);
```
Additional configuration by URL: The initialization of StandaloneContainer is very similar to that of PortalContainer, but the last step is slightly different. A configuration file that is provided by the URL is used to replace some of the service configurations. The code looks like this:
```
StandaloneContainer.addConfigurationURL(containerConf);
```
1. The hashtable is created by the RootContainer.
2. The default StandaloneContainer configurations from .jar files at /conf/portal/configuration.xml.
3. The web application configurations from .war files (/WEB-INF/conf/configuration.xml).
4. The configuration from added URL containerConf overrides only services configured in the file.
File based configuration: No URL is involved, in this case the sequence is:
1. The hashtable is created by the RootContainer.
2. Default StandaloneContainer configurations from .jar files at /conf/portal/configuration.xml.
3. Web applications configurations from .war files (/WEB-INF/conf/configuration.xml).
4. External configuration for StandaloneContainer services that is found at $user_home/exo-configuration.xml. If $user_home/exo-configuration.xml does not exist and the StandaloneContainer instance is obtained with the dedicated configuration classloader, the container will try to retrieve the resource conf/exo-configuration.xml within the given classloader ($user_home is your home directory like "C:/Documents and Settings/Smith").