Author: sergiykarpenko Date: 2010-08-05 06:25:35 -0400 (Thu, 05 Aug 2010) New Revision: 2881 Removed: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/configuration.xml Modified: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/container-configuration.xml jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/services-wiring.xml jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/understanding-listnerservice.xml Log: EXOJCR-869: link fixes Deleted: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/configuration.xml =================================================================== --- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/configuration.xml 2010-08-05 09:16:13 UTC (rev 2880) +++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/configuration.xml 2010-08-05 10:25:35 UTC (rev 2881) @@ -1,1817 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" -"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<chapter id = "Kernel.Configuration"> - <?dbhtml filename="ch-configuration.html"?> - - <title>Configuration</title> - - <section> - <title>Kernel configuration namespace</title> - - <para>To be effective the namespace URI <link - linkend="???">http://www.exoplaform.org/xml/ns/kernel_1_1.xs... must - be target namespace of the XML configuration file.</para> - - <programlisting>&lt;xsd:schema - targetNamespace="http://www.exoplaform.org/xml/ns/kernel_1_1.xsd" - xmlns="http://www.exoplaform.org/xml/ns/kernel_1_1.xsd" - xmlns:xsd="http://www.w3.org/2001/XMLSchema" - elementFormDefault="qualified" - attributeFormDefault="unqualified" - version="1.0"&gt; - - ... -&lt;/xsd:schema&gt;</programlisting> - </section> - - <section> - <title>Understanding How configuration files are loaded</title> - - <para>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.</para> - - <para>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.</para> - - <section> - <title>Configuration Retrieval</title> - - <para>The container performs the following steps making eXo Container - configuration retrieval depending on the container type.</para> - - <section> - <title>Configuration retrieval order for the - <envar>PortalContainer</envar></title> - - <para>The container is initialized by looking into different - locations. This container is used by portal applications. - Configurations are overloaded in the following lookup sequence:</para> - - <orderedlist> - <listitem> - <para>Services default <envar>RootContainer</envar> configurations - from JAR files <emphasis>/conf/configuration.xml</emphasis></para> - </listitem> - - <listitem> - <para>External <envar>RootContainer</envar> configuration, if will - be found at - <emphasis>$AS_HOME/exo-conf/configuration.xml</emphasis></para> - </listitem> - - <listitem> - <para>Services default <envar>PortalContainer</envar> - configurations from JAR files - <emphasis>/conf/portal/configuration.xml</emphasis></para> - </listitem> - - <listitem> - <para>Web applications configurations from WAR files - <emphasis>/WEB-INF/conf/configuration.xml</emphasis></para> - </listitem> - - <listitem> - <para>External configuration for services of named portal, if will - be found at - <emphasis>$AS_HOME/exo-conf/portal/$PORTAL_NAME/configuration.xml</emphasis></para> - </listitem> - </orderedlist> - </section> - - <section> - <title>Configuration retrieval for a - <envar>StandaloneContainer</envar></title> - - <para>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:</para> - - <orderedlist> - <listitem> - <para>Services default <envar>RootContainer</envar> configurations - from JAR files <emphasis>/conf/configuration.xml</emphasis></para> - </listitem> - - <listitem> - <para>External <envar>RootContainer</envar> configuration, if will - be found at - <emphasis>$AS_HOME/exo-conf/configuration.xml</emphasis></para> - </listitem> - - <listitem> - <para>Services default <envar>StandaloneContainer</envar> - configurations from JAR files - <emphasis>/conf/portal/configuration.xml</emphasis></para> - </listitem> - - <listitem> - <para>Web applications configurations from WAR files - <emphasis>/WEB-INF/conf/configuration.xml</emphasis></para> - </listitem> - - <listitem> - <para>Then depending on the <envar>StandaloneContainer</envar> - configuration URL initialization:</para> - - <itemizedlist> - <listitem> - <para>if configuration URL was initialized to be added to - services defaults, as below:<programlisting>// add configuration to the default services configurations from JARs/WARs -StandaloneContainer.addConfigurationURL(containerConf);</programlisting></para> - - <para>Configuration from added URL - <emphasis>containerConf</emphasis> will override only services - configured in the file</para> - </listitem> - - <listitem> - <para>if configuration URL not initialized at all, it will be - found at <emphasis>$AS_HOME/exo-configuration.xml</emphasis>. - If <emphasis>$AS_HOME/exo-configuration.xml</emphasis> doesn't - exist the container will try find it at - <emphasis>$AS_HOME/exo-conf/exo-configuration.xml</emphasis> - location and if it's still not found and the - <envar>StandaloneContainer</envar> instance obtained with the - dedicated configuration <envar>ClassLoader</envar> the - container will try to retrieve the resource - <emphasis>conf/exo-configuration.xml</emphasis> within the - given <envar>ClassLoader</envar>.</para> - </listitem> - </itemizedlist> - </listitem> - </orderedlist> - </section> - - <section> - <title>General notes about the configuration retrieval</title> - - <note> - <para><emphasis>$AS_HOME</emphasis> - application server home - directory, or <emphasis>user.dir</emphasis> JVM system property - value in case of Java Standalone application.</para> - </note> - - <note> - <para><emphasis>$PORTAL_NAME</emphasis> - portal web application - name.</para> - </note> - - <note> - <para>External configuration location can be overridden with System - property <emphasis>exo.conf.dir</emphasis>. If the property exists - its value will be used as path to eXo configuration directory, i.e. - to <emphasis>$AS_HOME/exo-conf</emphasis> alternative. E.g. put - property in command line java - <emphasis>-Dexo.conf.dir=/path/to/exo/conf</emphasis>. In this - particular use case, you have no need to use any prefix to import - other files. For instance, if your configuration file is - <emphasis>$AS_HOME/exo-conf/portal/PORTAL_NAME/configuration.xml</emphasis> - and you want to import the configuration file - <emphasis>$AS_HOME/exo-conf/portal/PORTAL_NAME/mySubConfDir/myConfig.xml</emphasis>, - you can do it by adding - <emphasis>&lt;import&gt;mySubConfDir/myConfig.xml&lt;/import&gt;</emphasis> - to your configuration file.</para> - </note> - - <note> - <para>The name of the configuration folder that is by default - <emphasis>"exo-conf"</emphasis>, can be changed thanks to the System - property <emphasis>exo.conf.dir.name</emphasis>.</para> - </note> - - <note> - <para>Under JBoss application server <emphasis>exo-conf</emphasis> - will be looked up in directory described by JBoss System property - <emphasis>jboss.server.config.url</emphasis>. If the property is not - found or empty <emphasis>$AS_HOME/exo-conf</emphasis> will be - asked.</para> - </note> - - <note> - <para>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.</para> - </note> - - <warning> - <para>Take care to have no dependencies between configurations from - JAR files (<emphasis>/conf/portal/configuration.xml</emphasis> and - <emphasis>/conf/configuration.xml</emphasis>) 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 <emphasis>/conf/portal/configuration.xml</emphasis> of a - given JAR file, you must not do it from the file - <emphasis>/conf/portal/configuration.xml</emphasis> of another JAR - file but from another configuration file loaded after configurations - from JAR files - <emphasis>/conf/portal/configuration.xml.</emphasis></para> - </warning> - - <para>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).</para> - - <para>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.</para> - - <para>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).</para> - </section> - - <section> - <title>Configuration retrieval log</title> - - <para>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 - <emphasis>org.exoplatform.container.configuration.debug</emphasis> can - be used.<programlisting>java -Dorg.exoplatform.container.configuration.debug ...</programlisting></para> - - <para>If the property is enabled the container configuration manager - will log the configuration adding process at <emphasis>INFO</emphasis> - level.<programlisting>...... - 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 - ......</programlisting></para> - </section> - - <section> - <title>Get the effective configuration at Runtime</title> - - <para>The effective configuration of the StandaloneContainer, - RootContainer and/or PortalContainer can be known thanks to the method - <emphasis>getConfigurationXML</emphasis>() 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 the - kernel. This could be helpful to understand how a given component or - plugin has been initialized.</para> - </section> - </section> - - <section> - <title>Advanced concepts for the - <emphasis>PortalContainers</emphasis></title> - - <para>Since eXo JCR 1.12, we added a set of new features that have been - designed to extend portal applications such as GateIn.</para> - - <section> - <title>Add new configuration files from a WAR file</title> - - <para>A <envar>ServletContextListener</envar> called - <envar>org.exoplatform.container.web.PortalContainerConfigOwner</envar> - has been added in order to notify the application that a given web - application provides some configuration to the portal container, and - this configuration file is the file - <emphasis>WEB-INF/conf/configuration.xml</emphasis> available in the - web application itself.</para> - - <para>If your war file contains some configuration to add to the - <envar>PortalContainer</envar> simply add the following lines in your - <emphasis>web.xml</emphasis> file.</para> - - <programlisting>&lt;?xml version="1.0" encoding="ISO-8859-1" ?&gt; -&lt;!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN" - "http://java.sun.com/dtd/web-app_2_3.dtd"&gt; -&lt;web-app&gt; -... - &lt;!-- ================================================================== --&gt; - &lt;!-- LISTENER --&gt; - &lt;!-- ================================================================== --&gt; - &lt;listener&gt; - &lt;listener-class&gt;org.exoplatform.container.web.PortalContainerConfigOwner&lt;/listener-class&gt; - &lt;/listener&gt; -... -&lt;/web-app&gt;</programlisting> - </section> - - <section> - <title>Create your <emphasis>PortalContainers</emphasis> from a WAR - file</title> - - <para>A <envar>ServletContextListener</envar> called - <envar>org.exoplatform.container.web.PortalContainerCreator</envar> - has been added in order to create the current portal containers that - have been registered. We assume that all the web applications have - already been loaded before calling - <envar>PortalContainerCreator.contextInitialized<replaceable><optional>.</optional></replaceable></envar></para> - - <para><note> - <para>In GateIn, the <envar>PortalContainerCreator</envar> is - already managed by the file - <emphasis>starter.war/ear.</emphasis></para> - </note></para> - </section> - - <section> - <title>Define a <emphasis>PortalContainer</emphasis> with its - dependencies and its settings</title> - - <para>Now we can define precisely a portal container and its - dependencies and settings thanks to the - <envar>PortalContainerDefinition</envar> that currently contains the - name of the portal container, the name of the rest context, the name - of the realm he web application dependencies ordered by loading - priority (i.e. the first dependency must be loaded at first and so - on..) and the settings.</para> - - <para>To be able to define a <envar>PortalContainerDefinition</envar>, - we need to ensure first of all that a - <envar>PortalContainerConfig</envar> has been defined at the - <envar>RootContainer</envar> level, see below an example:</para> - - <programlisting> &lt;component&gt; - &lt;!-- The full qualified name of the PortalContainerConfig --&gt; - &lt;type&gt;org.exoplatform.container.definition.PortalContainerConfig&lt;/type&gt; - &lt;init-params&gt; - &lt;!-- The name of the default portal container --&gt; - &lt;value-param&gt; - &lt;name&gt;default.portal.container&lt;/name&gt; - &lt;value&gt;myPortal&lt;/value&gt; - &lt;/value-param&gt; - &lt;!-- The name of the default rest ServletContext --&gt; - &lt;value-param&gt; - &lt;name&gt;default.rest.context&lt;/name&gt; - &lt;value&gt;myRest&lt;/value&gt; - &lt;/value-param&gt; - &lt;!-- The name of the default realm --&gt; - &lt;value-param&gt; - &lt;name&gt;default.realm.name&lt;/name&gt; - &lt;value&gt;my-exo-domain&lt;/value&gt; - &lt;/value-param&gt; - &lt;!-- The default portal container definition --&gt; - &lt;!-- It cans be used to avoid duplicating configuration --&gt; - &lt;object-param&gt; - &lt;name&gt;default.portal.definition&lt;/name&gt; - &lt;object type="org.exoplatform.container.definition.PortalContainerDefinition"&gt; - &lt;!-- All the dependencies of the portal container ordered by loading priority --&gt; - &lt;field name="dependencies"&gt; - &lt;collection type="java.util.ArrayList"&gt; - &lt;value&gt; - &lt;string&gt;foo&lt;/string&gt; - &lt;/value&gt; - &lt;value&gt; - &lt;string&gt;foo2&lt;/string&gt; - &lt;/value&gt; - &lt;value&gt; - &lt;string&gt;foo3&lt;/string&gt; - &lt;/value&gt; - &lt;/collection&gt; - &lt;/field&gt; - &lt;!-- A map of settings tied to the default portal container --&gt; - &lt;field name="settings"&gt; - &lt;map type="java.util.HashMap"&gt; - &lt;entry&gt; - &lt;key&gt; - &lt;string&gt;foo5&lt;/string&gt; - &lt;/key&gt; - &lt;value&gt; - &lt;string&gt;value&lt;/string&gt; - &lt;/value&gt; - &lt;/entry&gt; - &lt;entry&gt; - &lt;key&gt; - &lt;string&gt;string&lt;/string&gt; - &lt;/key&gt; - &lt;value&gt; - &lt;string&gt;value0&lt;/string&gt; - &lt;/value&gt; - &lt;/entry&gt; - &lt;entry&gt; - &lt;key&gt; - &lt;string&gt;int&lt;/string&gt; - &lt;/key&gt; - &lt;value&gt; - &lt;int&gt;100&lt;/int&gt; - &lt;/value&gt; - &lt;/entry&gt; - &lt;/map&gt; - &lt;/field&gt; - &lt;!-- The path to the external properties file --&gt; - &lt;field name="externalSettingsPath"&gt; - &lt;string&gt;classpath:/org/exoplatform/container/definition/default-settings.properties&lt;/string&gt; - &lt;/field&gt; - &lt;/object&gt; - &lt;/object-param&gt; - &lt;/init-params&gt; - &lt;/component&gt;</programlisting> - - <table> - <title>Descriptions of the fields of - <envar>PortalContainerConfig</envar></title> - - <tgroup cols="2"> - <tbody> - <row> - <entry>default.portal.container</entry> - - <entry>The name of the default portal container. This field is - optional.</entry> - </row> - - <row> - <entry>default.rest.context</entry> - - <entry>The name of the default rest - <envar>ServletContext</envar>. This field is optional.</entry> - </row> - - <row> - <entry>default.realm.name</entry> - - <entry>The name of the default realm. This field is - optional.</entry> - </row> - - <row> - <entry>default.portal.definition</entry> - - <entry>The definition of the default portal container. This - field is optional. The expected type is - <envar>org.exoplatform.container.definition.PortalContainerDefinition</envar> - that is described below. Allow the parameters defined in this - default <envar>PortalContainerDefinition</envar> will be the - default values.</entry> - </row> - </tbody> - </tgroup> - </table> - - <para>A new <envar>PortalContainerDefinition</envar> can be defined at - the <envar>RootContainer</envar> level thanks to an external plugin, - see below an example:<programlisting> &lt;external-component-plugins&gt; - &lt;!-- The full qualified name of the PortalContainerConfig --&gt; - &lt;target-component&gt;org.exoplatform.container.definition.PortalContainerConfig&lt;/target-component&gt; - &lt;component-plugin&gt; - &lt;!-- The name of the plugin --&gt; - &lt;name&gt;Add PortalContainer Definitions&lt;/name&gt; - &lt;!-- The name of the method to call on the PortalContainerConfig in order to register the PortalContainerDefinitions --&gt; - &lt;set-method&gt;registerPlugin&lt;/set-method&gt; - &lt;!-- The full qualified name of the PortalContainerDefinitionPlugin --&gt; - &lt;type&gt;org.exoplatform.container.definition.PortalContainerDefinitionPlugin&lt;/type&gt; - &lt;init-params&gt; - &lt;object-param&gt; - &lt;name&gt;portal&lt;/name&gt; - &lt;object type="org.exoplatform.container.definition.PortalContainerDefinition"&gt; - &lt;!-- The name of the portal container --&gt; - &lt;field name="name"&gt; - &lt;string&gt;myPortal&lt;/string&gt; - &lt;/field&gt; - &lt;!-- The name of the context name of the rest web application --&gt; - &lt;field name="restContextName"&gt; - &lt;string&gt;myRest&lt;/string&gt; - &lt;/field&gt; - &lt;!-- The name of the realm --&gt; - &lt;field name="realmName"&gt; - &lt;string&gt;my-domain&lt;/string&gt; - &lt;/field&gt; - &lt;!-- All the dependencies of the portal container ordered by loading priority --&gt; - &lt;field name="dependencies"&gt; - &lt;collection type="java.util.ArrayList"&gt; - &lt;value&gt; - &lt;string&gt;foo&lt;/string&gt; - &lt;/value&gt; - &lt;value&gt; - &lt;string&gt;foo2&lt;/string&gt; - &lt;/value&gt; - &lt;value&gt; - &lt;string&gt;foo3&lt;/string&gt; - &lt;/value&gt; - &lt;/collection&gt; - &lt;/field&gt; - &lt;!-- A map of settings tied to the portal container --&gt; - &lt;field name="settings"&gt; - &lt;map type="java.util.HashMap"&gt; - &lt;entry&gt; - &lt;key&gt; - &lt;string&gt;foo&lt;/string&gt; - &lt;/key&gt; - &lt;value&gt; - &lt;string&gt;value&lt;/string&gt; - &lt;/value&gt; - &lt;/entry&gt; - &lt;entry&gt; - &lt;key&gt; - &lt;string&gt;int&lt;/string&gt; - &lt;/key&gt; - &lt;value&gt; - &lt;int&gt;10&lt;/int&gt; - &lt;/value&gt; - &lt;/entry&gt; - &lt;entry&gt; - &lt;key&gt; - &lt;string&gt;long&lt;/string&gt; - &lt;/key&gt; - &lt;value&gt; - &lt;long&gt;10&lt;/long&gt; - &lt;/value&gt; - &lt;/entry&gt; - &lt;entry&gt; - &lt;key&gt; - &lt;string&gt;double&lt;/string&gt; - &lt;/key&gt; - &lt;value&gt; - &lt;double&gt;10&lt;/double&gt; - &lt;/value&gt; - &lt;/entry&gt; - &lt;entry&gt; - &lt;key&gt; - &lt;string&gt;boolean&lt;/string&gt; - &lt;/key&gt; - &lt;value&gt; - &lt;boolean&gt;true&lt;/boolean&gt; - &lt;/value&gt; - &lt;/entry&gt; - &lt;/map&gt; - &lt;/field&gt; - &lt;!-- The path to the external properties file --&gt; - &lt;field name="externalSettingsPath"&gt; - &lt;string&gt;classpath:/org/exoplatform/container/definition/settings.properties&lt;/string&gt; - &lt;/field&gt; - &lt;/object&gt; - &lt;/object-param&gt; - &lt;/init-params&gt; - &lt;/component-plugin&gt; - &lt;/external-component-plugins&gt;</programlisting></para> - - <table> - <title>Descriptions of the fields of a - <envar>PortalContainerDefinition</envar> when it is used to define a - new portal container</title> - - <tgroup cols="2"> - <tbody> - <row> - <entry>name</entry> - - <entry>The name of the portal container. This field is - mandatory .</entry> - </row> - - <row> - <entry>restContextName</entry> - - <entry>The name of the context name of the rest web - application. This field is optional. The default value will - the value define at the <envar>PortalContainerConfig</envar> - level.</entry> - </row> - - <row> - <entry>realmName</entry> - - <entry>The name of the realm. This field is optional. The - default value will the value define at the - <envar>PortalContainerConfig</envar> level.</entry> - </row> - - <row> - <entry>dependencies</entry> - - <entry>All the dependencies of the portal container ordered by - loading priority. This field is optional. The default value - will the value define at the - <envar>PortalContainerConfig</envar> level. The dependencies - are in fact the list of the context names of the web - applications from which the portal container depends. This - field is optional. The dependency order is really crucial - since it will be interpreted the same way by several - components of the platform. All those components, will - consider the 1st element in the list less important than the - second element and so on. It is currently used - to:<itemizedlist> - <listitem> - <para>Know the loading order of all the - dependencies.</para> - </listitem> - - <listitem> - <para>If we have several - <envar>PortalContainerConfigOwner</envar><itemizedlist> - <listitem> - <para>The <envar>ServletContext</envar> of all the - <envar>PortalContainerConfigOwner</envar> will be - unified, if we use the unified - <envar>ServletContext</envar> - (<emphasis>PortalContainer.getPortalContext()</emphasis>) - to get a resource, it will try to get the resource - in the <envar>ServletContext</envar> of the most - important <envar>PortalContainerConfigOwner</envar> - (i.e. last in the dependency list) and if it cans - find it, it will try with the second most important - <envar>PortalContainerConfigOwner</envar> and so - on.</para> - </listitem> - - <listitem> - <para>The <envar>ClassLoader</envar> of all the - <envar>PortalContainerConfigOwner</envar> will be - unified, if we use the unified - <envar>ClassLoader</envar> - (<emphasis>PortalContainer.getPortalClassLoader()</emphasis>) - to get a resource, it will try to get the resource - in the <envar>ClassLoader</envar> of the most - important <envar>PortalContainerConfigOwner</envar> - (i.e. last in the dependency list) and if it cans - find it, it will try with the second most important - <envar>PortalContainerConfigOwner</envar> and so - on.</para> - </listitem> - </itemizedlist></para> - </listitem> - </itemizedlist></entry> - </row> - - <row> - <entry>settings</entry> - - <entry>A <envar>java.util.Map</envar> of internal parameters - that we would like to tie the portal container. Those - parameters could have any type of value. This field is - optional. If some internal settings are defined at the - <envar>PortalContainerConfig</envar> level, the two maps of - settings will be merged. If a setting with the same name is - defined in both maps, it will keep the value defined at the - <envar>PortalContainerDefinition</envar> level.</entry> - </row> - - <row> - <entry>externalSettingsPath</entry> - - <entry>The path of the external properties file to load as - default settings to the portal container. This field is - optional. If some external settings are defined at the - <envar>PortalContainerConfig</envar> level, the two maps of - settings will be merged. If a setting with the same name is - defined in both maps, it will keep the value defined at the - <envar>PortalContainerDefinition</envar> level. The external - properties files can be either of type "properties" or of type - "xml". The path will be interpreted as follows:<orderedlist> - <listitem> - <para>The path doesn't contain any prefix of type - "classpath:", "jar:" or "file:", we assume that the file - could be externalized so we apply the following - rules:<orderedlist> - <listitem> - <para>A file exists at - <emphasis>${exo-conf-dir}/portal/${portalContainerName}/${externalSettingsPath}</emphasis>, - we will load this file.</para> - </listitem> - - <listitem> - <para>No file exists at the previous path, we then - assume that the path cans be interpreted by the - <envar>ConfigurationManager</envar>.</para> - </listitem> - </orderedlist></para> - </listitem> - - <listitem> - <para>The path contains a prefix, we then assume that - the path cans be interpreted by the - <envar>ConfigurationManager</envar>.</para> - </listitem> - </orderedlist></entry> - </row> - </tbody> - </tgroup> - </table> - - <table> - <title>Descriptions of the fields of a - <envar>PortalContainerDefinition</envar> when it is used to define - the default portal container</title> - - <tgroup cols="2"> - <tbody> - <row> - <entry>name</entry> - - <entry>The name of the portal container. This field is - optional. The default portal name will be:<orderedlist> - <listitem> - <para>If this field is not empty, then the default value - will be the value of this field.</para> - </listitem> - - <listitem> - <para>If this field is empty and the value of the - parameter <emphasis>default.portal.container</emphasis> - is not empty, then the default value will be the value - of the parameter.</para> - </listitem> - - <listitem> - <para>If this field and the parameter - <emphasis>default.portal.container</emphasis> are both - empty, the default value will be - <emphasis>"portal".</emphasis></para> - </listitem> - </orderedlist></entry> - </row> - - <row> - <entry>restContextName</entry> - - <entry>The name of the context name of the rest web - application. This field is optional. The default value wil - be:<orderedlist> - <listitem> - <para>If this field is not empty, then the default value - will be the value of this field.</para> - </listitem> - - <listitem> - <para>f this field is empty and the value of the - parameter <emphasis>default.rest.context</emphasis> is - not empty, then the default value will be the value of - the parameter.</para> - </listitem> - - <listitem> - <para>f this field and the parameter - <emphasis>default.rest.context</emphasis> are both - empty, the default value will be - <emphasis>"rest".</emphasis></para> - </listitem> - </orderedlist></entry> - </row> - - <row> - <entry>realmName</entry> - - <entry>The name of the realm. This field is optional. The - default value wil be:<orderedlist> - <listitem> - <para>If this field is not empty, then the default value - will be the value of this field.</para> - </listitem> - - <listitem> - <para>f this field is empty and the value of the - parameter <emphasis>default.realm.name</emphasis> is not - empty, then the default value will be the value of the - parameter.</para> - </listitem> - - <listitem> - <para>f this field and the parameter - <emphasis>default.realm.name</emphasis> are both empty, - the default value will be - <emphasis>"exo-domain".</emphasis></para> - </listitem> - </orderedlist></entry> - </row> - - <row> - <entry>dependencies</entry> - - <entry>All the dependencies of the portal container ordered by - loading priority. This field is optional. If this field has a - non empty value, it will be the default list of - dependencies.</entry> - </row> - - <row> - <entry>settings</entry> - - <entry>A <envar>java.util.Map</envar> of internal parameters - that we would like to tie the default portal container. Those - parameters could have any type of value. This field is - optional.</entry> - </row> - - <row> - <entry>externalSettingsPath</entry> - - <entry>The path of the external properties file to load as - default settings to the default portal container. This field - is optional. The external properties files can be either of - type "properties" or of type "xml". The path will be - interpreted as follows:<orderedlist> - <listitem> - <para>The path doesn't contain any prefix of type - "classpath:", "jar:" or "file:", we assume that the file - could be externalized so we apply the following - rules:<orderedlist> - <listitem> - <para>A file exists at - <emphasis>${exo-conf-dir}/portal/${externalSettingsPath}</emphasis>, - we will load this file.</para> - </listitem> - - <listitem> - <para>No file exists at the previous path, we then - assume that the path cans be interpreted by the - <envar>ConfigurationManager</envar>.</para> - </listitem> - </orderedlist></para> - </listitem> - - <listitem> - <para>The path contains a prefix, we then assume that - the path cans be interpreted by the - <envar>ConfigurationManager</envar>.</para> - </listitem> - </orderedlist></entry> - </row> - </tbody> - </tgroup> - </table> - - <para>Internal and external settings are both optional, but if we give - a non empty value for both the application will merge the settings. If - the same setting name exists in both settings, we apply the following - rules:</para> - - <orderedlist> - <listitem> - <para>The value of the external setting is - <emphasis>null</emphasis>, we ignore the value.</para> - </listitem> - - <listitem> - <para>The value of the external setting is not - <emphasis>null</emphasis> and the value of the internal setting is - <emphasis>null</emphasis>, the final value will be the external - setting value that is of type <envar>String</envar>.</para> - </listitem> - - <listitem> - <para>Both values are not <envar>null</envar>, we will have to - convert the external setting value into the target type which is - the type of the internal setting value, thanks to the static - method <emphasis>valueOf(String)</emphasis>, the following - sub-rules are then applied:</para> - - <orderedlist> - <listitem> - <para>The method cannot be found, the final value will be the - external setting value that is of type - <envar>String</envar>.</para> - </listitem> - - <listitem> - <para>The method can be found and the external setting value - is an empty <envar>String</envar>, we ignore the external - setting value.</para> - </listitem> - - <listitem> - <para>The method can be found and the external setting value - is not an empty <envar>String</envar> but the method call - fails, we ignore the external setting value.</para> - </listitem> - - <listitem> - <para>The method can be found and the external setting value - is not an empty <envar>String</envar> and the method call - succeeds, the final value will be the external setting value - that is of type of the internal setting value.</para> - </listitem> - </orderedlist> - </listitem> - </orderedlist> - </section> - - <section> - <title><envar>PortalContainer</envar> settings</title> - - <para>We can inject the value of the portal container settings into - the portal container configuration files thanks to the variables which - name start with "<emphasis>portal.container.</emphasis>", so to get - the value of a setting called "<emphasis>foo</emphasis>" just use the - following syntax <emphasis>${portal.container.foo}</emphasis>. You can - also use internal variables, such as:</para> - - <table> - <title>Definition of the internal variables</title> - - <tgroup cols="2"> - <tbody> - <row> - <entry>portal.container.name</entry> - - <entry>Gives the name of the current portal container.</entry> - </row> - - <row> - <entry>portal.container.rest</entry> - - <entry>Gives the context name of the rest web application of - the current portal container.</entry> - </row> - - <row> - <entry>portal.container.realm</entry> - - <entry>Gives the realm name of the current portal - container.</entry> - </row> - </tbody> - </tgroup> - </table> - - <para>You can find below an example of how to use the - variables:<programlisting>&lt;configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.exoplaform.org/xml/ns/kernel_1_1.xsd http://www.exoplaform.org/xml/ns/kernel_1_1.xsd" - xmlns="http://www.exoplaform.org/xml/ns/kernel_1_1.xsd"&gt; - &lt;component&gt; - &lt;type&gt;org.exoplatform.container.TestPortalContainer$MyComponent&lt;/type&gt; - &lt;init-params&gt; - &lt;!-- The name of the portal container --&gt; - &lt;value-param&gt; - &lt;name&gt;portal&lt;/name&gt; - &lt;value&gt;${portal.container.name}&lt;/value&gt; - &lt;/value-param&gt; - &lt;!-- The name of the rest ServletContext --&gt; - &lt;value-param&gt; - &lt;name&gt;rest&lt;/name&gt; - &lt;value&gt;${portal.container.rest}&lt;/value&gt; - &lt;/value-param&gt; - &lt;!-- The name of the realm --&gt; - &lt;value-param&gt; - &lt;name&gt;realm&lt;/name&gt; - &lt;value&gt;${portal.container.realm}&lt;/value&gt; - &lt;/value-param&gt; - &lt;value-param&gt; - &lt;name&gt;foo&lt;/name&gt; - &lt;value&gt;${portal.container.foo}&lt;/value&gt; - &lt;/value-param&gt; - &lt;value-param&gt; - &lt;name&gt;before foo after&lt;/name&gt; - &lt;value&gt;before ${portal.container.foo} after&lt;/value&gt; - &lt;/value-param&gt; - &lt;/init-params&gt; - &lt;/component&gt; -&lt;/configuration&gt;</programlisting></para> - - <para>In the properties file corresponding to the external settings, - you can reuse variables previously defined (in the external settings - or in the internal settings) to create a new variable. In this case - the prefix "<emphasis>portal.container.</emphasis>" is not needed, see - an example below:<programlisting>my-var1=value 1 -my-var2=value 2 -complex-value=${my-var1}-${my-var2}</programlisting></para> - - <para>In the external and internal settings, you can also use create - variables based on value of System paramaters. The System parameters - can either be defined at launch time or thanks to the - <envar>PropertyConfigurator</envar> (see next section for more - details). See an example below:</para> - - <programlisting>temp-dir=${java.io.tmpdir}${file.separator}my-temp</programlisting> - - <para>However, for the internal settings you can use System parameters - only to define settings of type - <envar>java.lang.String</envar>.</para> - - <para>It cans be also very usefull to define a generic variable in the - settings of the default portal container, the value of this variable - will change according to the current portal container. See below an - example:<programlisting>my-generic-var=value of the portal container "${name}"</programlisting></para> - - <para>If this variable is defined at the default portal container - level, the value of this variable for a portal container called - <emphasis>"foo"</emphasis> will be <emphasis>value of the portal - container "foo"</emphasis>.</para> - </section> - - <section> - <title>Add dynamically settings and/or dependencies to a - <envar>PortalContainer</envar></title> - - <para>It is possible to use <envar>component-plugin</envar> elements - in order to dynamically change a PortalContainerDefinition. In the - example below, we add the dependency <envar>foo</envar> to the default - portal container and to the portal containers called - <envar>foo1</envar> and <envar>foo2</envar>:</para> - - <programlisting>&lt;external-component-plugins&gt; - &lt;!-- The full qualified name of the PortalContainerConfig --&gt; - &lt;target-component&gt;org.exoplatform.container.definition.PortalContainerConfig&lt;/target-component&gt; - &lt;component-plugin&gt; - &lt;!-- The name of the plugin --&gt; - &lt;name&gt;Change PortalContainer Definitions&lt;/name&gt; - &lt;!-- The name of the method to call on the PortalContainerConfig in order to register the changes on the PortalContainerDefinitions --&gt; - &lt;set-method&gt;registerChangePlugin&lt;/set-method&gt; - &lt;!-- The full qualified name of the PortalContainerDefinitionChangePlugin --&gt; - &lt;type&gt;org.exoplatform.container.definition.PortalContainerDefinitionChangePlugin&lt;/type&gt; - &lt;init-params&gt; - &lt;value-param&gt; - &lt;name&gt;apply.default&lt;/name&gt; - &lt;value&gt;true&lt;/value&gt; - &lt;/value-param&gt; - &lt;values-param&gt; - &lt;name&gt;apply.specific&lt;/name&gt; - &lt;value&gt;foo1&lt;/value&gt; - &lt;value&gt;foo2&lt;/value&gt; - &lt;/values-param&gt; - &lt;object-param&gt; - &lt;name&gt;change&lt;/name&gt; - &lt;object type="org.exoplatform.container.definition.PortalContainerDefinitionChange$AddDependencies"&gt; - &lt;!-- The list of name of the dependencies to add --&gt; - &lt;field name="dependencies"&gt; - &lt;collection type="java.util.ArrayList"&gt; - &lt;value&gt; - &lt;string&gt;foo&lt;/string&gt; - &lt;/value&gt; - &lt;/collection&gt; - &lt;/field&gt; - &lt;/object&gt; - &lt;/object-param&gt; - &lt;/init-params&gt; - &lt;/component-plugin&gt; -&lt;/external-component-plugins&gt;</programlisting> - - <table> - <title>Descriptions of the fields of a - <envar>PortalContainerDefinitionChangePlugin</envar></title> - - <tgroup cols="2"> - <tbody> - <row> - <entry>apply.all</entry> - - <entry>Indicates whether the changes have to be applied to all - the portal containers or not. The default value of this field - is <envar>false</envar>. This field is a - <envar>ValueParam</envar> and is not mandatory.</entry> - </row> - - <row> - <entry>apply.default</entry> - - <entry>Indicates whether the changes have to be applied to the - default portal container or not. The default value of this - field is <envar>false</envar>. This field is a - <envar>ValueParam</envar> and is not mandatory.</entry> - </row> - - <row> - <entry>apply.specific</entry> - - <entry>A set of specific portal container names to which we - want to apply the changes. This field is a - <envar>ValuesParam</envar> and is not mandatory.</entry> - </row> - - <row> - <entry><envar>Rest of the expected parameters </envar></entry> - - <entry>The rest of the expected paramaters are - <envar>ObjectParam</envar> of type - <envar>PortalContainerDefinitionChange</envar>. Those - parameters are in fact the list of changes that we want to - apply to one or several portal containers. If the list of - changes is empty, the component plugin will be ignored. The - supported implementations of PortalContainerDefinitionChange - are described later in this section.</entry> - </row> - </tbody> - </tgroup> - </table> - - <para>To identify the portal containers to which the changes have to - be applied, we use the follwing algorithm:</para> - - <orderedlist> - <listitem> - <para>The parameter <envar>apply.all</envar> has been set to - <envar>true</envar>. The corresponding changes will be applied to - all the portal containers. The other parameters will be - ignored.</para> - </listitem> - - <listitem> - <para>The parameter <envar>apply.default</envar> has been set to - <envar>true</envar> and the parameter - <envar>apply.specific</envar> is <envar>null</envar>. The - corresponding changes will be applied to the default portal - container only.</para> - </listitem> - - <listitem> - <para>The parameter <envar>apply.default</envar> has been set to - <envar>true</envar> and the parameter - <envar>apply.specific</envar> is not <envar>null</envar>. The - corresponding changes will be applied to the default portal - container and the given list of specific portal containers.</para> - </listitem> - - <listitem> - <para>The parameter <envar>apply.default</envar> has been set to - <envar>false</envar> or has not been set and the parameter - <envar>apply.specific</envar> is <envar>null</envar>. The - corresponding changes will be applied to the default portal - container only.</para> - </listitem> - - <listitem> - <para>The parameter <envar>apply.default</envar> has been set to - <envar>false</envar> or has not been set and the parameter - <envar>apply.specific</envar> is not <envar>null</envar>. The - corresponding changes will be applied to the given list of - specific portal containers.</para> - </listitem> - </orderedlist> - - <section> - <title>The existing implementations of - <envar>PortalContainerDefinitionChange</envar></title> - - <para>The modifications that can be applied to a - <envar>PortalContainerDefinition</envar> must be a class of type - <envar>PortalContainerDefinitionChange</envar>. The product proposes - out of the box some implementations that we describe in the next sub - sections. </para> - - <section> - <title><envar>AddDependencies</envar></title> - - <para>This modification adds a list of dependencies at the end of - the list of dependencies defined into the - <envar>PortalContainerDefinition</envar>. The full qualified name - is - <emphasis>org.exoplatform.container.definition.PortalContainerDefinitionChange$AddDependencies</emphasis>.</para> - - <table> - <title>Descriptions of the fields of an - <envar>AddDependencies</envar></title> - - <tgroup cols="2"> - <tbody> - <row> - <entry>dependencies</entry> - - <entry>A list of <emphasis>String</emphasis> corresponding - to the list of name of the dependencies to add. If the - value of this field is empty, the change will be - ignored.</entry> - </row> - </tbody> - </tgroup> - </table> - - <para>See an example below, that will add <envar>foo</envar> at - the end of the dependency list of the default portal - container:</para> - - <programlisting>&lt;external-component-plugins&gt; - &lt;!-- The full qualified name of the PortalContainerConfig --&gt; - &lt;target-component&gt;org.exoplatform.container.definition.PortalContainerConfig&lt;/target-component&gt; - &lt;component-plugin&gt; - &lt;!-- The name of the plugin --&gt; - &lt;name&gt;Change PortalContainer Definitions&lt;/name&gt; - &lt;!-- The name of the method to call on the PortalContainerConfig in order to register the changes on the PortalContainerDefinitions --&gt; - &lt;set-method&gt;registerChangePlugin&lt;/set-method&gt; - &lt;!-- The full qualified name of the PortalContainerDefinitionChangePlugin --&gt; - &lt;type&gt;org.exoplatform.container.definition.PortalContainerDefinitionChangePlugin&lt;/type&gt; - &lt;init-params&gt; - &lt;value-param&gt; - &lt;name&gt;apply.default&lt;/name&gt; - &lt;value&gt;true&lt;/value&gt; - &lt;/value-param&gt; - &lt;object-param&gt; - &lt;name&gt;change&lt;/name&gt; - &lt;object type="org.exoplatform.container.definition.PortalContainerDefinitionChange$AddDependencies"&gt; - &lt;!-- The list of name of the dependencies to add --&gt; - &lt;field name="dependencies"&gt; - &lt;collection type="java.util.ArrayList"&gt; - &lt;value&gt; - &lt;string&gt;foo&lt;/string&gt; - &lt;/value&gt; - &lt;/collection&gt; - &lt;/field&gt; - &lt;/object&gt; - &lt;/object-param&gt; - &lt;/init-params&gt; - &lt;/component-plugin&gt; -&lt;/external-component-plugins&gt;</programlisting> - </section> - - <section> - <title><envar>AddDependenciesBefore</envar></title> - - <para>This modification adds a list of dependencies before a given - target dependency defined into the list of dependencies of the - <envar>PortalContainerDefinition</envar>. The full qualified name - is - <emphasis>org.exoplatform.container.definition.PortalContainerDefinitionChange$AddDependenciesBefore</emphasis>.</para> - - <table> - <title>Descriptions of the fields of an - <envar>AddDependenciesBefore</envar></title> - - <tgroup cols="2"> - <tbody> - <row> - <entry>dependencies</entry> - - <entry>A list of <emphasis>String</emphasis> corresponding - to the list of name of the dependencies to add. If the - value of this field is empty, the change will be - ignored.</entry> - </row> - - <row> - <entry>target</entry> - - <entry>The name of the dependency before which we would - like to add the new dependencies. If this field is - <envar>null</envar> or the target dependency cannot be - found in the list of dependencies defined into the - <envar>PortalContainerDefinition</envar>, the new - dependencies will be added in first position to the - list.</entry> - </row> - </tbody> - </tgroup> - </table> - - <para>See an example below, that will add <envar>foo</envar> - before <envar>foo2</envar> in the dependency list of the default - portal container:</para> - - <programlisting>&lt;external-component-plugins&gt; - &lt;!-- The full qualified name of the PortalContainerConfig --&gt; - &lt;target-component&gt;org.exoplatform.container.definition.PortalContainerConfig&lt;/target-component&gt; - &lt;component-plugin&gt; - &lt;!-- The name of the plugin --&gt; - &lt;name&gt;Change PortalContainer Definitions&lt;/name&gt; - &lt;!-- The name of the method to call on the PortalContainerConfig in order to register the changes on the PortalContainerDefinitions --&gt; - &lt;set-method&gt;registerChangePlugin&lt;/set-method&gt; - &lt;!-- The full qualified name of the PortalContainerDefinitionChangePlugin --&gt; - &lt;type&gt;org.exoplatform.container.definition.PortalContainerDefinitionChangePlugin&lt;/type&gt; - &lt;init-params&gt; - &lt;value-param&gt; - &lt;name&gt;apply.default&lt;/name&gt; - &lt;value&gt;true&lt;/value&gt; - &lt;/value-param&gt; - &lt;object-param&gt; - &lt;name&gt;change&lt;/name&gt; - &lt;object type="org.exoplatform.container.definition.PortalContainerDefinitionChange$AddDependenciesBefore"&gt; - &lt;!-- The list of name of the dependencies to add --&gt; - &lt;field name="dependencies"&gt; - &lt;collection type="java.util.ArrayList"&gt; - &lt;value&gt; - &lt;string&gt;foo&lt;/string&gt; - &lt;/value&gt; - &lt;/collection&gt; - &lt;/field&gt; - &lt;!-- The name of the target dependency --&gt; - &lt;field name="target"&gt; - &lt;string&gt;foo2&lt;/string&gt; - &lt;/field&gt; - &lt;/object&gt; - &lt;/object-param&gt; - &lt;/init-params&gt; - &lt;/component-plugin&gt; -&lt;/external-component-plugins&gt;</programlisting> - </section> - - <section> - <title><envar>AddDependenciesAfter</envar></title> - - <para>This modification adds a list of dependencies before a given - target dependency defined into the list of dependencies of the - <envar>PortalContainerDefinition</envar>. The full qualified name - is - <emphasis>org.exoplatform.container.definition.PortalContainerDefinitionChange$AddDependenciesAfter</emphasis>.</para> - - <table> - <title>Descriptions of the fields of an - <envar>AddDependenciesAfter</envar></title> - - <tgroup cols="2"> - <tbody> - <row> - <entry>dependencies</entry> - - <entry>A list of <emphasis>String</emphasis> corresponding - to the list of name of the dependencies to add. If the - value of this field is empty, the change will be - ignored.</entry> - </row> - - <row> - <entry>target</entry> - - <entry>The name of the dependency after which we would - like to add the new dependencies. If this field is - <envar>null</envar> or the target dependency cannot be - found in the list of dependencies defined into the - <envar>PortalContainerDefinition</envar>, the new - dependencies will be added in last position to the - list.</entry> - </row> - </tbody> - </tgroup> - </table> - - <para>See an example below, that will add <envar>foo</envar> after - <envar>foo2</envar> in the dependency list of the default portal - container:</para> - - <programlisting>&lt;external-component-plugins&gt; - &lt;!-- The full qualified name of the PortalContainerConfig --&gt; - &lt;target-component&gt;org.exoplatform.container.definition.PortalContainerConfig&lt;/target-component&gt; - &lt;component-plugin&gt; - &lt;!-- The name of the plugin --&gt; - &lt;name&gt;Change PortalContainer Definitions&lt;/name&gt; - &lt;!-- The name of the method to call on the PortalContainerConfig in order to register the changes on the PortalContainerDefinitions --&gt; - &lt;set-method&gt;registerChangePlugin&lt;/set-method&gt; - &lt;!-- The full qualified name of the PortalContainerDefinitionChangePlugin --&gt; - &lt;type&gt;org.exoplatform.container.definition.PortalContainerDefinitionChangePlugin&lt;/type&gt; - &lt;init-params&gt; - &lt;value-param&gt; - &lt;name&gt;apply.default&lt;/name&gt; - &lt;value&gt;true&lt;/value&gt; - &lt;/value-param&gt; - &lt;object-param&gt; - &lt;name&gt;change&lt;/name&gt; - &lt;object type="org.exoplatform.container.definition.PortalContainerDefinitionChange$AddDependenciesAfter"&gt; - &lt;!-- The list of name of the dependencies to add --&gt; - &lt;field name="dependencies"&gt; - &lt;collection type="java.util.ArrayList"&gt; - &lt;value&gt; - &lt;string&gt;foo&lt;/string&gt; - &lt;/value&gt; - &lt;/collection&gt; - &lt;/field&gt; - &lt;!-- The name of the target dependency --&gt; - &lt;field name="target"&gt; - &lt;string&gt;foo2&lt;/string&gt; - &lt;/field&gt; - &lt;/object&gt; - &lt;/object-param&gt; - &lt;/init-params&gt; - &lt;/component-plugin&gt; -&lt;/external-component-plugins&gt;</programlisting> - </section> - - <section> - <title><envar>AddSettings</envar></title> - - <para>This modification adds new settings to a - <envar>PortalContainerDefinition</envar>. The full qualified name - is - <emphasis>org.exoplatform.container.definition.PortalContainerDefinitionChange$AddSettings</emphasis>.</para> - - <table> - <title>Descriptions of the fields of an - <envar>AddSettings</envar></title> - - <tgroup cols="2"> - <tbody> - <row> - <entry>settings</entry> - - <entry>A map of <emphasis>&lt;String, - Object&gt;</emphasis> corresponding to the settings to - add. If the value of this field is empty, the change will - be ignored.</entry> - </row> - </tbody> - </tgroup> - </table> - - <para>See an example below, that will add the settings - <envar>string</envar> and <envar>stringX</envar> to the settings - of the default portal container:</para> - - <programlisting>&lt;external-component-plugins&gt; - &lt;!-- The full qualified name of the PortalContainerConfig --&gt; - &lt;target-component&gt;org.exoplatform.container.definition.PortalContainerConfig&lt;/target-component&gt; - &lt;component-plugin&gt; - &lt;!-- The name of the plugin --&gt; - &lt;name&gt;Change PortalContainer Definitions&lt;/name&gt; - &lt;!-- The name of the method to call on the PortalContainerConfig in order to register the changes on the PortalContainerDefinitions --&gt; - &lt;set-method&gt;registerChangePlugin&lt;/set-method&gt; - &lt;!-- The full qualified name of the PortalContainerDefinitionChangePlugin --&gt; - &lt;type&gt;org.exoplatform.container.definition.PortalContainerDefinitionChangePlugin&lt;/type&gt; - &lt;init-params&gt; - &lt;value-param&gt; - &lt;name&gt;apply.default&lt;/name&gt; - &lt;value&gt;true&lt;/value&gt; - &lt;/value-param&gt; - &lt;object-param&gt; - &lt;name&gt;change&lt;/name&gt; - &lt;object type="org.exoplatform.container.definition.PortalContainerDefinitionChange$AddSettings"&gt; - &lt;!-- The settings to add to the to the portal containers --&gt; - &lt;field name="settings"&gt; - &lt;map type="java.util.HashMap"&gt; - &lt;entry&gt; - &lt;key&gt; - &lt;string&gt;string&lt;/string&gt; - &lt;/key&gt; - &lt;value&gt; - &lt;string&gt;value1&lt;/string&gt; - &lt;/value&gt; - &lt;/entry&gt; - &lt;entry&gt; - &lt;key&gt; - &lt;string&gt;stringX&lt;/string&gt; - &lt;/key&gt; - &lt;value&gt; - &lt;string&gt;value1&lt;/string&gt; - &lt;/value&gt; - &lt;/entry&gt; - &lt;/map&gt; - &lt;/field&gt; - &lt;/object&gt; - &lt;/object-param&gt; - &lt;/init-params&gt; - &lt;/component-plugin&gt; -&lt;/external-component-plugins&gt;</programlisting> - </section> - </section> - </section> - </section> - </section> - - <section> - <title>System property configuration</title> - - <para>A new property configurator service has been developed for taking - care of configuring system properties from the inline kernel configuration - or from specified property files.</para> - - <para>The services is scoped at the root container level because it is - used by all the services in the different portal containers in the - application runtime.</para> - - <section> - <title>Properties init param</title> - - <para>The properties init param takes a property declared to configure - various properties.</para> - - <programlisting>&lt;component&gt; - &lt;key&gt;PropertyManagerConfigurator&lt;/key&gt; - &lt;type&gt;org.exoplatform.container.PropertyConfigurator&lt;/type&gt; - &lt;init-params&gt; - &lt;properties-param&gt; - &lt;name&gt;properties&lt;/name&gt; - &lt;property name="foo" value="bar"/&gt; - &lt;/properties-param&gt; - &lt;/init-params&gt; -&lt;/component&gt;</programlisting> - </section> - - <section> - <title>Properties URL init param</title> - - <para>The properties URL init param allow to load an external file by - specifying its URL. Both property and XML format are supported, see the - javadoc of the <emphasis><envar>java.util.Properties</envar></emphasis> - class for more information. When a property file is loaded the various - property declarations are loaded in the order in which the properties - are declared sequentially in the file.</para> - - <programlisting>&lt;component&gt; - &lt;key&gt;PropertyManagerConfigurator&lt;/key&gt; - &lt;type&gt;org.exoplatform.container.PropertyConfigurator&lt;/type&gt; - &lt;init-params&gt; - &lt;value-param&gt; - &lt;name&gt;properties.url&lt;/name&gt; - &lt;value&gt;classpath:configuration.properties&lt;/value&gt; - &lt;/value-param&gt; - &lt;/init-params&gt; -&lt;/component&gt;</programlisting> - - <para>In the properties file corresponding to the external properties, - you can reuse variables previously defined to create a new variable. In - this case the prefix "<emphasis>portal.container.</emphasis>" is not - needed, see an example below:<programlisting>my-var1=value 1 -my-var2=value 2 -complex-value=${my-var1}-${my-var2}</programlisting></para> - </section> - - <section> - <title>System Property configuration of the properties URL</title> - - <para>It is possible to replace the properties URL init param by a - system property that overwrites it. The name of that property is - <emphasis>exo.properties.url</emphasis>.</para> - </section> - </section> - - <section> - <title>Runtime configuration profiles</title> - - <para>The kernel configuration is able to handle configuration profiles at - runtime (as opposed to packaging time).</para> - - <section> - <title>Profiles activation</title> - - <para>An active profile list is obtained during the boot of the root - container and is composed of the system property - <emphasis>exo.profiles</emphasis> sliced according the "," delimiter and - also a server specific profile value (tomcat for tomcat, jboss for - jboss, etc...).</para> - - <programlisting># runs GateIn on Tomcat with the profiles tomcat and foo -sh gatein.sh -Dexo.profiles=foo - -# runs GateIn on JBoss with the profiles jboss, foo and bar -sh run.sh -Dexo.profiles=foo,bar</programlisting> - </section> - - <section> - <title>Profiles configuration</title> - - <para>Profiles are configured in the configuration files of the eXo - kernel.</para> - - <section> - <title>Profiles definition</title> - - <para>Profile activation occurs at XML to configuration object - unmarshalling time. It is based on an "profile" attribute that is - present on some of the XML element of the configuration files. To - enable this the kernel configuration schema has been upgraded to - kernel_1_1.xsd. The configuration is based on the following - rules:</para> - - <orderedlist> - <listitem> - <para>Any kernel element with the no <emphasis>profiles</emphasis> - attribute will create a configuration object</para> - </listitem> - - <listitem> - <para>Any kernel element having a <emphasis>profiles</emphasis> - attribute containing at least one of the active profiles will - create a configuration object</para> - </listitem> - - <listitem> - <para>Any kernel element having a <emphasis>profiles</emphasis> - attribute matching none of the active profile will not create a - configuration object</para> - </listitem> - - <listitem> - <para>Resolution of duplicates (such as two components with same - type) is left up to the kernel</para> - </listitem> - </orderedlist> - </section> - - <section> - <title>Profiles capable configuration elements</title> - - <para>A configuration element is <emphasis>profiles</emphasis> capable - when it carries a profiles element.</para> - - <section> - <title>Component element</title> - - <para>The component element declares a component when activated. It - will shadow any element with the same key declared before in the - same configuration file:</para> - - <programlisting>&lt;component&gt; - &lt;key&gt;Component&lt;/key&gt; - &lt;type&gt;Component&lt;/type&gt; -&lt;/component&gt; - -&lt;component profiles="foo"&gt; - &lt;key&gt;Component&lt;/key&gt; - &lt;type&gt;FooComponent&lt;/type&gt; -&lt;/component&gt;</programlisting> - </section> - - <section> - <title>Component plugin element</title> - - <para>The component-plugin element is used to dynamically extend the - configuration of a given component. Thanks to the profiles the - component-plugins could be enabled or disabled:</para> - - <programlisting>&lt;external-component-plugins&gt; - &lt;target-component&gt;Component&lt;/target-component&gt; - &lt;component-plugin profiles="foo"&gt; - &lt;name&gt;foo&lt;/name&gt; - &lt;set-method&gt;addPlugin&lt;/set-method&gt; - &lt;type&gt;type&lt;/type&gt; - &lt;init-params&gt; - &lt;value-param&gt; - &lt;name&gt;param&lt;/name&gt; - &lt;value&gt;empty&lt;/value&gt; - &lt;/value-param&gt; - &lt;/init-params&gt; - &lt;/component-plugin&gt; -&lt;/external-component-plugins&gt;</programlisting> - </section> - - <section> - <title>Import element</title> - - <para>The import element imports a referenced configuration file - when activated:</para> - - <programlisting>&lt;import&gt;empty&lt;/import&gt; -&lt;import profiles="foo"&gt;foo&lt;/import&gt; -&lt;import profiles="bar"&gt;bar&lt;/import&gt;</programlisting> - </section> - - <section> - <title>Init param element</title> - - <para>The init param element configures the parameter argument of - the construction of a component service:</para> - - <programlisting>&lt;component&gt; - &lt;key&gt;Component&lt;/key&gt; - &lt;type&gt;ComponentImpl&lt;/type&gt; - &lt;init-params&gt; - &lt;value-param&gt; - &lt;name&gt;param&lt;/name&gt; - &lt;value&gt;empty&lt;/value&gt; - &lt;/value-param&gt; - &lt;value-param profiles="foo"&gt; - &lt;name&gt;param&lt;/name&gt; - &lt;value&gt;foo&lt;/value&gt; - &lt;/value-param&gt; - &lt;value-param profiles="bar"&gt; - &lt;name&gt;param&lt;/name&gt; - &lt;value&gt;bar&lt;/value&gt; - &lt;/value-param&gt; - &lt;/init-params&gt; -&lt;/component&gt;</programlisting> - </section> - - <section> - <title>Value collection element</title> - - <para>The value collection element configures one of the value of - collection data:</para> - - <programlisting>&lt;object type="org.exoplatform.container.configuration.ConfigParam"&gt; - &lt;field name="role"&gt; - &lt;collection type="java.util.ArrayList"&gt; - &lt;value&gt;&lt;string&gt;manager&lt;/string&gt;&lt;/value&gt; - &lt;value profiles="foo"&gt;&lt;string&gt;foo_manager&lt;/string&gt;&lt;/value&gt; - &lt;value profiles="foo,bar"&gt;&lt;string&gt;foo_bar_manager&lt;/string&gt;&lt;/value&gt; - &lt;/collection&gt; - &lt;/field&gt; -&lt;/object&gt;</programlisting> - </section> - - <section> - <title>Field configuration element</title> - - <para>The field configuration element configures the field of an - object:</para> - - <programlisting>&lt;object-param&gt; - &lt;name&gt;test.configuration&lt;/name&gt; - &lt;object type="org.exoplatform.container.configuration.ConfigParam"&gt; - &lt;field name="role"&gt; - &lt;collection type="java.util.ArrayList"&gt; - &lt;value&gt;&lt;string&gt;manager&lt;/string&gt;&lt;/value&gt; - &lt;/collection&gt; - &lt;/field&gt; - &lt;field name="role" profiles="foo,bar"&gt; - &lt;collection type="java.util.ArrayList"&gt; - &lt;value&gt;&lt;string&gt;foo_bar_manager&lt;/string&gt;&lt;/value&gt; - &lt;/collection&gt; - &lt;/field&gt; - &lt;field name="role" profiles="foo"&gt; - &lt;collection type="java.util.ArrayList"&gt; - &lt;value&gt;&lt;string&gt;foo_manager&lt;/string&gt;&lt;/value&gt; - &lt;/collection&gt; - &lt;/field&gt; - &lt;/object&gt; -&lt;/object-param&gt;</programlisting> - </section> - </section> - </section> - </section> - - <section> - <title>Component request life cycle</title> - - <section> - <title>Component request life cycle contract</title> - - <para>The component request life cycle is an interface that defines a - contract for a component for being involved into a - request:<programlisting>public interface ComponentRequestLifecycle -{ - /** - * Start a request. - * @param container the related container - */ - void startRequest(ExoContainer container); - - /** - * Ends a request. - * @param container the related container - */ - void endRequest(ExoContainer container); -}</programlisting></para> - - <para>The container passed is the container to which the component is - related. This contract is often used to setup a thread local based - context that will be demarcated by a request.</para> - - <para>For instance in the GateIn portal context, a component request - life cycle is triggered for user requests. Another example is the - initial data import in GateIn that demarcates using callbacks made to - that interface.</para> - </section> - - <section> - <title>Request life cycle</title> - - <para>The <envar>RequestLifeCycle</envar> class has several statics - methods that are used to schedule the component request life cycle of - components. Its main responsability is to perform scheduling while - respecting the constraint to execute the request life cycle of a - component only once even if it can be scheduled several times.</para> - - <section> - <title>Scheduling a component request life cycle</title> - - <programlisting>RequestLifeCycle.begin(component); -try -{ - // Do something -} -finally -{ - RequestLifeCycle.end(); -}</programlisting> - </section> - - <section> - <title>Scheduling a container request life cycle</title> - - <para>Scheduling a container triggers the component request life cyle - of all the components that implement the interface - <envar>ComponentRequestLifeCycle</envar>. If one of the component has - already been scheduled before then that component will not be - scheduled again. When the local value is true then the looked - components will be those of the container, when it is false then the - scheduler will also look at the components in the ancestor - containers.<programlisting>RequestLifeCycle.begin(container, local); -try -{ - // Do something -} -finally -{ - RequestLifeCycle.end(); -}</programlisting></para> - </section> - </section> - - <section> - <title>When request life cycle is triggered</title> - - <section> - <title>Portal request life cycle</title> - - <para>Each portal request triggers the life cycle of the associated - portal container.</para> - </section> - - <section> - <title>JMX request Life Cycle</title> - - <para>When a JMX bean is invoked, the request life cycle of the - container to which it belongs it scheduled. Indeed JMX is an entry - point of the system that may need component to have a request life - cycle triggered.</para> - </section> - </section> - </section> -</chapter> Modified: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/container-configuration.xml =================================================================== --- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/container-configuration.xml 2010-08-05 09:16:13 UTC (rev 2880) +++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/container-configuration.xml 2010-08-05 10:25:35 UTC (rev 2881) @@ -1,1837 +1,1837 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" -"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<chapter id="Kernel.ContainerConfiguration"> - <?dbhtml filename="ch-kernel-container-configuration.html"?> - - <title>Container Configuration</title> - - <section> - <title>Intro</title> - - <para>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.</para> - - <para>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.</para> - - <para>Confused? - You might be interested in the <link - linkend="KernelServiceConfigurationforBeginners">Service Configuration for - Beginners</link> article, which explains the basics.</para> - </section> - - <section id="Kernel.ContainerConfiguration.ConfigurationNamespace"> - <title>Kernel configuration namespace</title> - - <para>To be effective the namespace URI - <uri>http://www.exoplaform.org/xml/ns/kernel_1_1.xsd</uri> must be target - namespace of the XML configuration file.</para> - - <programlisting>&lt;xsd:schema - targetNamespace="http://www.exoplaform.org/xml/ns/kernel_1_1.xsd" - xmlns="http://www.exoplaform.org/xml/ns/kernel_1_1.xsd" - xmlns:xsd="http://www.w3.org/2001/XMLSchema" - elementFormDefault="qualified" - attributeFormDefault="unqualified" - version="1.0"&gt; - - ... -&lt;/xsd:schema&gt;</programlisting> - </section> - - <section> - <title>Understanding How configuration files are loaded</title> - - <para>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.</para> - - <para>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.</para> - - <section> - <title>Configuration Retrieval</title> - - <para>The container performs the following steps making eXo Container - configuration retrieval depending on the container type.</para> - - <section> - <title>Configuration retrieval order for the - <envar>PortalContainer</envar></title> - - <para>The container is initialized by looking into different - locations. This container is used by portal applications. - Configurations are overloaded in the following lookup sequence:</para> - - <orderedlist> - <listitem> - <para>Services default <envar>RootContainer</envar> configurations - from JAR files <emphasis>/conf/configuration.xml</emphasis></para> - </listitem> - - <listitem> - <para>External <envar>RootContainer</envar> configuration, if will - be found at - <emphasis>$AS_HOME/exo-conf/configuration.xml</emphasis></para> - </listitem> - - <listitem> - <para>Services default <envar>PortalContainer</envar> - configurations from JAR files - <emphasis>/conf/portal/configuration.xml</emphasis></para> - </listitem> - - <listitem> - <para>Web applications configurations from WAR files - <emphasis>/WEB-INF/conf/configuration.xml</emphasis></para> - </listitem> - - <listitem> - <para>External configuration for services of named portal, if will - be found at - <emphasis>$AS_HOME/exo-conf/portal/$PORTAL_NAME/configuration.xml</emphasis></para> - </listitem> - </orderedlist> - </section> - - <section> - <title>Configuration retrieval for a - <envar>StandaloneContainer</envar></title> - - <para>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:</para> - - <orderedlist> - <listitem> - <para>Services default <envar>RootContainer</envar> configurations - from JAR files <emphasis>/conf/configuration.xml</emphasis></para> - </listitem> - - <listitem> - <para>External <envar>RootContainer</envar> configuration, if will - be found at - <emphasis>$AS_HOME/exo-conf/configuration.xml</emphasis></para> - </listitem> - - <listitem> - <para>Services default <envar>StandaloneContainer</envar> - configurations from JAR files - <emphasis>/conf/portal/configuration.xml</emphasis></para> - </listitem> - - <listitem> - <para>Web applications configurations from WAR files - <emphasis>/WEB-INF/conf/configuration.xml</emphasis></para> - </listitem> - - <listitem> - <para>Then depending on the <envar>StandaloneContainer</envar> - configuration URL initialization:</para> - - <itemizedlist> - <listitem> - <para>if configuration URL was initialized to be added to - services defaults, as below:<programlisting>// add configuration to the default services configurations from JARs/WARs -StandaloneContainer.addConfigurationURL(containerConf);</programlisting></para> - - <para>Configuration from added URL - <emphasis>containerConf</emphasis> will override only services - configured in the file</para> - </listitem> - - <listitem> - <para>if configuration URL not initialized at all, it will be - found at <emphasis>$AS_HOME/exo-configuration.xml</emphasis>. - If <emphasis>$AS_HOME/exo-configuration.xml</emphasis> doesn't - exist the container will try find it at - <emphasis>$AS_HOME/exo-conf/exo-configuration.xml</emphasis> - location and if it's still not found and the - <envar>StandaloneContainer</envar> instance obtained with the - dedicated configuration <envar>ClassLoader</envar> the - container will try to retrieve the resource - <emphasis>conf/exo-configuration.xml</emphasis> within the - given <envar>ClassLoader</envar>.</para> - </listitem> - </itemizedlist> - </listitem> - </orderedlist> - </section> - - <section> - <title>General notes about the configuration retrieval</title> - - <note> - <para><emphasis>$AS_HOME</emphasis> - application server home - directory, or <emphasis>user.dir</emphasis> JVM system property - value in case of Java Standalone application.</para> - </note> - - <note> - <para><emphasis>$PORTAL_NAME</emphasis> - portal web application - name.</para> - </note> - - <note> - <para>External configuration location can be overridden with System - property <emphasis>exo.conf.dir</emphasis>. If the property exists - its value will be used as path to eXo configuration directory, i.e. - to <emphasis>$AS_HOME/exo-conf</emphasis> alternative. E.g. put - property in command line java - <emphasis>-Dexo.conf.dir=/path/to/exo/conf</emphasis>. In this - particular use case, you have no need to use any prefix to import - other files. For instance, if your configuration file is - <emphasis>$AS_HOME/exo-conf/portal/PORTAL_NAME/configuration.xml</emphasis> - and you want to import the configuration file - <emphasis>$AS_HOME/exo-conf/portal/PORTAL_NAME/mySubConfDir/myConfig.xml</emphasis>, - you can do it by adding - <emphasis>&lt;import&gt;mySubConfDir/myConfig.xml&lt;/import&gt;</emphasis> - to your configuration file.</para> - </note> - - <note> - <para>The name of the configuration folder that is by default - <emphasis>"exo-conf"</emphasis>, can be changed thanks to the System - property <emphasis>exo.conf.dir.name</emphasis>.</para> - </note> - - <note> - <para>Under JBoss application server <emphasis>exo-conf</emphasis> - will be looked up in directory described by JBoss System property - <emphasis>jboss.server.config.url</emphasis>. If the property is not - found or empty <emphasis>$AS_HOME/exo-conf</emphasis> will be - asked.</para> - </note> - - <note> - <para>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.</para> - </note> - - <warning> - <para>Take care to have no dependencies between configurations from - JAR files (<emphasis>/conf/portal/configuration.xml</emphasis> and - <emphasis>/conf/configuration.xml</emphasis>) 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 <emphasis>/conf/portal/configuration.xml</emphasis> of a - given JAR file, you must not do it from the file - <emphasis>/conf/portal/configuration.xml</emphasis> of another JAR - file but from another configuration file loaded after configurations - from JAR files - <emphasis>/conf/portal/configuration.xml.</emphasis></para> - </warning> - - <para>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).</para> - - <para>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.</para> - - <para>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).</para> - </section> - - <section> - <title>Configuration retrieval log</title> - - <para>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 - <emphasis>org.exoplatform.container.configuration.debug</emphasis> can - be used.<programlisting>java -Dorg.exoplatform.container.configuration.debug ...</programlisting></para> - - <para>If the property is enabled the container configuration manager - will log the configuration adding process at <emphasis>INFO</emphasis> - level.<programlisting>...... - 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 - ......</programlisting></para> - </section> - - <section> - <title>Get the effective configuration at Runtime</title> - - <para>The effective configuration of the StandaloneContainer, - RootContainer and/or PortalContainer can be known thanks to the method - <emphasis>getConfigurationXML</emphasis>() 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 the - kernel. This could be helpful to understand how a given component or - plugin has been initialized.</para> - </section> - </section> - - <section> - <title>Advanced concepts for the - <emphasis>PortalContainers</emphasis></title> - - <para>Since eXo JCR 1.12, we added a set of new features that have been - designed to extend portal applications such as GateIn.</para> - - <section> - <title>Add new configuration files from a WAR file</title> - - <para>A <envar>ServletContextListener</envar> called - <envar>org.exoplatform.container.web.PortalContainerConfigOwner</envar> - has been added in order to notify the application that a given web - application provides some configuration to the portal container, and - this configuration file is the file - <emphasis>WEB-INF/conf/configuration.xml</emphasis> available in the - web application itself.</para> - - <para>If your war file contains some configuration to add to the - <envar>PortalContainer</envar> simply add the following lines in your - <emphasis>web.xml</emphasis> file.</para> - - <programlisting>&lt;?xml version="1.0" encoding="ISO-8859-1" ?&gt; -&lt;!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN" - "http://java.sun.com/dtd/web-app_2_3.dtd"&gt; -&lt;web-app&gt; -... - &lt;!-- ================================================================== --&gt; - &lt;!-- LISTENER --&gt; - &lt;!-- ================================================================== --&gt; - &lt;listener&gt; - &lt;listener-class&gt;org.exoplatform.container.web.PortalContainerConfigOwner&lt;/listener-class&gt; - &lt;/listener&gt; -... -&lt;/web-app&gt;</programlisting> - </section> - - <section> - <title>Create your <emphasis>PortalContainers</emphasis> from a WAR - file</title> - - <para>A <envar>ServletContextListener</envar> called - <envar>org.exoplatform.container.web.PortalContainerCreator</envar> - has been added in order to create the current portal containers that - have been registered. We assume that all the web applications have - already been loaded before calling - <envar>PortalContainerCreator.contextInitialized<replaceable><optional>.</optional></replaceable></envar></para> - - <para><note> - <para>In GateIn, the <envar>PortalContainerCreator</envar> is - already managed by the file - <emphasis>starter.war/ear.</emphasis></para> - </note></para> - </section> - - <section> - <title>Define a <emphasis>PortalContainer</emphasis> with its - dependencies and its settings</title> - - <para>Now we can define precisely a portal container and its - dependencies and settings thanks to the - <envar>PortalContainerDefinition</envar> that currently contains the - name of the portal container, the name of the rest context, the name - of the realm he web application dependencies ordered by loading - priority (i.e. the first dependency must be loaded at first and so - on..) and the settings.</para> - - <para>To be able to define a <envar>PortalContainerDefinition</envar>, - we need to ensure first of all that a - <envar>PortalContainerConfig</envar> has been defined at the - <envar>RootContainer</envar> level, see below an example:</para> - - <programlisting> &lt;component&gt; - &lt;!-- The full qualified name of the PortalContainerConfig --&gt; - &lt;type&gt;org.exoplatform.container.definition.PortalContainerConfig&lt;/type&gt; - &lt;init-params&gt; - &lt;!-- The name of the default portal container --&gt; - &lt;value-param&gt; - &lt;name&gt;default.portal.container&lt;/name&gt; - &lt;value&gt;myPortal&lt;/value&gt; - &lt;/value-param&gt; - &lt;!-- The name of the default rest ServletContext --&gt; - &lt;value-param&gt; - &lt;name&gt;default.rest.context&lt;/name&gt; - &lt;value&gt;myRest&lt;/value&gt; - &lt;/value-param&gt; - &lt;!-- The name of the default realm --&gt; - &lt;value-param&gt; - &lt;name&gt;default.realm.name&lt;/name&gt; - &lt;value&gt;my-exo-domain&lt;/value&gt; - &lt;/value-param&gt; - &lt;!-- The default portal container definition --&gt; - &lt;!-- It cans be used to avoid duplicating configuration --&gt; - &lt;object-param&gt; - &lt;name&gt;default.portal.definition&lt;/name&gt; - &lt;object type="org.exoplatform.container.definition.PortalContainerDefinition"&gt; - &lt;!-- All the dependencies of the portal container ordered by loading priority --&gt; - &lt;field name="dependencies"&gt; - &lt;collection type="java.util.ArrayList"&gt; - &lt;value&gt; - &lt;string&gt;foo&lt;/string&gt; - &lt;/value&gt; - &lt;value&gt; - &lt;string&gt;foo2&lt;/string&gt; - &lt;/value&gt; - &lt;value&gt; - &lt;string&gt;foo3&lt;/string&gt; - &lt;/value&gt; - &lt;/collection&gt; - &lt;/field&gt; - &lt;!-- A map of settings tied to the default portal container --&gt; - &lt;field name="settings"&gt; - &lt;map type="java.util.HashMap"&gt; - &lt;entry&gt; - &lt;key&gt; - &lt;string&gt;foo5&lt;/string&gt; - &lt;/key&gt; - &lt;value&gt; - &lt;string&gt;value&lt;/string&gt; - &lt;/value&gt; - &lt;/entry&gt; - &lt;entry&gt; - &lt;key&gt; - &lt;string&gt;string&lt;/string&gt; - &lt;/key&gt; - &lt;value&gt; - &lt;string&gt;value0&lt;/string&gt; - &lt;/value&gt; - &lt;/entry&gt; - &lt;entry&gt; - &lt;key&gt; - &lt;string&gt;int&lt;/string&gt; - &lt;/key&gt; - &lt;value&gt; - &lt;int&gt;100&lt;/int&gt; - &lt;/value&gt; - &lt;/entry&gt; - &lt;/map&gt; - &lt;/field&gt; - &lt;!-- The path to the external properties file --&gt; - &lt;field name="externalSettingsPath"&gt; - &lt;string&gt;classpath:/org/exoplatform/container/definition/default-settings.properties&lt;/string&gt; - &lt;/field&gt; - &lt;/object&gt; - &lt;/object-param&gt; - &lt;/init-params&gt; - &lt;/component&gt;</programlisting> - - <table> - <title>Descriptions of the fields of - <envar>PortalContainerConfig</envar></title> - - <tgroup cols="2"> - <tbody> - <row> - <entry>default.portal.container</entry> - - <entry>The name of the default portal container. This field is - optional.</entry> - </row> - - <row> - <entry>default.rest.context</entry> - - <entry>The name of the default rest - <envar>ServletContext</envar>. This field is optional.</entry> - </row> - - <row> - <entry>default.realm.name</entry> - - <entry>The name of the default realm. This field is - optional.</entry> - </row> - - <row> - <entry>default.portal.definition</entry> - - <entry>The definition of the default portal container. This - field is optional. The expected type is - <envar>org.exoplatform.container.definition.PortalContainerDefinition</envar> - that is described below. Allow the parameters defined in this - default <envar>PortalContainerDefinition</envar> will be the - default values.</entry> - </row> - </tbody> - </tgroup> - </table> - - <para>A new <envar>PortalContainerDefinition</envar> can be defined at - the <envar>RootContainer</envar> level thanks to an external plugin, - see below an example:<programlisting> &lt;external-component-plugins&gt; - &lt;!-- The full qualified name of the PortalContainerConfig --&gt; - &lt;target-component&gt;org.exoplatform.container.definition.PortalContainerConfig&lt;/target-component&gt; - &lt;component-plugin&gt; - &lt;!-- The name of the plugin --&gt; - &lt;name&gt;Add PortalContainer Definitions&lt;/name&gt; - &lt;!-- The name of the method to call on the PortalContainerConfig in order to register the PortalContainerDefinitions --&gt; - &lt;set-method&gt;registerPlugin&lt;/set-method&gt; - &lt;!-- The full qualified name of the PortalContainerDefinitionPlugin --&gt; - &lt;type&gt;org.exoplatform.container.definition.PortalContainerDefinitionPlugin&lt;/type&gt; - &lt;init-params&gt; - &lt;object-param&gt; - &lt;name&gt;portal&lt;/name&gt; - &lt;object type="org.exoplatform.container.definition.PortalContainerDefinition"&gt; - &lt;!-- The name of the portal container --&gt; - &lt;field name="name"&gt; - &lt;string&gt;myPortal&lt;/string&gt; - &lt;/field&gt; - &lt;!-- The name of the context name of the rest web application --&gt; - &lt;field name="restContextName"&gt; - &lt;string&gt;myRest&lt;/string&gt; - &lt;/field&gt; - &lt;!-- The name of the realm --&gt; - &lt;field name="realmName"&gt; - &lt;string&gt;my-domain&lt;/string&gt; - &lt;/field&gt; - &lt;!-- All the dependencies of the portal container ordered by loading priority --&gt; - &lt;field name="dependencies"&gt; - &lt;collection type="java.util.ArrayList"&gt; - &lt;value&gt; - &lt;string&gt;foo&lt;/string&gt; - &lt;/value&gt; - &lt;value&gt; - &lt;string&gt;foo2&lt;/string&gt; - &lt;/value&gt; - &lt;value&gt; - &lt;string&gt;foo3&lt;/string&gt; - &lt;/value&gt; - &lt;/collection&gt; - &lt;/field&gt; - &lt;!-- A map of settings tied to the portal container --&gt; - &lt;field name="settings"&gt; - &lt;map type="java.util.HashMap"&gt; - &lt;entry&gt; - &lt;key&gt; - &lt;string&gt;foo&lt;/string&gt; - &lt;/key&gt; - &lt;value&gt; - &lt;string&gt;value&lt;/string&gt; - &lt;/value&gt; - &lt;/entry&gt; - &lt;entry&gt; - &lt;key&gt; - &lt;string&gt;int&lt;/string&gt; - &lt;/key&gt; - &lt;value&gt; - &lt;int&gt;10&lt;/int&gt; - &lt;/value&gt; - &lt;/entry&gt; - &lt;entry&gt; - &lt;key&gt; - &lt;string&gt;long&lt;/string&gt; - &lt;/key&gt; - &lt;value&gt; - &lt;long&gt;10&lt;/long&gt; - &lt;/value&gt; - &lt;/entry&gt; - &lt;entry&gt; - &lt;key&gt; - &lt;string&gt;double&lt;/string&gt; - &lt;/key&gt; - &lt;value&gt; - &lt;double&gt;10&lt;/double&gt; - &lt;/value&gt; - &lt;/entry&gt; - &lt;entry&gt; - &lt;key&gt; - &lt;string&gt;boolean&lt;/string&gt; - &lt;/key&gt; - &lt;value&gt; - &lt;boolean&gt;true&lt;/boolean&gt; - &lt;/value&gt; - &lt;/entry&gt; - &lt;/map&gt; - &lt;/field&gt; - &lt;!-- The path to the external properties file --&gt; - &lt;field name="externalSettingsPath"&gt; - &lt;string&gt;classpath:/org/exoplatform/container/definition/settings.properties&lt;/string&gt; - &lt;/field&gt; - &lt;/object&gt; - &lt;/object-param&gt; - &lt;/init-params&gt; - &lt;/component-plugin&gt; - &lt;/external-component-plugins&gt;</programlisting></para> - - <table> - <title>Descriptions of the fields of a - <envar>PortalContainerDefinition</envar> when it is used to define a - new portal container</title> - - <tgroup cols="2"> - <tbody> - <row> - <entry>name</entry> - - <entry>The name of the portal container. This field is - mandatory .</entry> - </row> - - <row> - <entry>restContextName</entry> - - <entry>The name of the context name of the rest web - application. This field is optional. The default value will - the value define at the <envar>PortalContainerConfig</envar> - level.</entry> - </row> - - <row> - <entry>realmName</entry> - - <entry>The name of the realm. This field is optional. The - default value will the value define at the - <envar>PortalContainerConfig</envar> level.</entry> - </row> - - <row> - <entry>dependencies</entry> - - <entry>All the dependencies of the portal container ordered by - loading priority. This field is optional. The default value - will the value define at the - <envar>PortalContainerConfig</envar> level. The dependencies - are in fact the list of the context names of the web - applications from which the portal container depends. This - field is optional. The dependency order is really crucial - since it will be interpreted the same way by several - components of the platform. All those components, will - consider the 1st element in the list less important than the - second element and so on. It is currently used - to:<itemizedlist> - <listitem> - <para>Know the loading order of all the - dependencies.</para> - </listitem> - - <listitem> - <para>If we have several - <envar>PortalContainerConfigOwner</envar><itemizedlist> - <listitem> - <para>The <envar>ServletContext</envar> of all the - <envar>PortalContainerConfigOwner</envar> will be - unified, if we use the unified - <envar>ServletContext</envar> - (<emphasis>PortalContainer.getPortalContext()</emphasis>) - to get a resource, it will try to get the resource - in the <envar>ServletContext</envar> of the most - important <envar>PortalContainerConfigOwner</envar> - (i.e. last in the dependency list) and if it cans - find it, it will try with the second most important - <envar>PortalContainerConfigOwner</envar> and so - on.</para> - </listitem> - - <listitem> - <para>The <envar>ClassLoader</envar> of all the - <envar>PortalContainerConfigOwner</envar> will be - unified, if we use the unified - <envar>ClassLoader</envar> - (<emphasis>PortalContainer.getPortalClassLoader()</emphasis>) - to get a resource, it will try to get the resource - in the <envar>ClassLoader</envar> of the most - important <envar>PortalContainerConfigOwner</envar> - (i.e. last in the dependency list) and if it cans - find it, it will try with the second most important - <envar>PortalContainerConfigOwner</envar> and so - on.</para> - </listitem> - </itemizedlist></para> - </listitem> - </itemizedlist></entry> - </row> - - <row> - <entry>settings</entry> - - <entry>A <envar>java.util.Map</envar> of internal parameters - that we would like to tie the portal container. Those - parameters could have any type of value. This field is - optional. If some internal settings are defined at the - <envar>PortalContainerConfig</envar> level, the two maps of - settings will be merged. If a setting with the same name is - defined in both maps, it will keep the value defined at the - <envar>PortalContainerDefinition</envar> level.</entry> - </row> - - <row> - <entry>externalSettingsPath</entry> - - <entry>The path of the external properties file to load as - default settings to the portal container. This field is - optional. If some external settings are defined at the - <envar>PortalContainerConfig</envar> level, the two maps of - settings will be merged. If a setting with the same name is - defined in both maps, it will keep the value defined at the - <envar>PortalContainerDefinition</envar> level. The external - properties files can be either of type "properties" or of type - "xml". The path will be interpreted as follows:<orderedlist> - <listitem> - <para>The path doesn't contain any prefix of type - "classpath:", "jar:" or "file:", we assume that the file - could be externalized so we apply the following - rules:<orderedlist> - <listitem> - <para>A file exists at - <emphasis>${exo-conf-dir}/portal/${portalContainerName}/${externalSettingsPath}</emphasis>, - we will load this file.</para> - </listitem> - - <listitem> - <para>No file exists at the previous path, we then - assume that the path cans be interpreted by the - <envar>ConfigurationManager</envar>.</para> - </listitem> - </orderedlist></para> - </listitem> - - <listitem> - <para>The path contains a prefix, we then assume that - the path cans be interpreted by the - <envar>ConfigurationManager</envar>.</para> - </listitem> - </orderedlist></entry> - </row> - </tbody> - </tgroup> - </table> - - <table> - <title>Descriptions of the fields of a - <envar>PortalContainerDefinition</envar> when it is used to define - the default portal container</title> - - <tgroup cols="2"> - <tbody> - <row> - <entry>name</entry> - - <entry>The name of the portal container. This field is - optional. The default portal name will be:<orderedlist> - <listitem> - <para>If this field is not empty, then the default value - will be the value of this field.</para> - </listitem> - - <listitem> - <para>If this field is empty and the value of the - parameter <emphasis>default.portal.container</emphasis> - is not empty, then the default value will be the value - of the parameter.</para> - </listitem> - - <listitem> - <para>If this field and the parameter - <emphasis>default.portal.container</emphasis> are both - empty, the default value will be - <emphasis>"portal".</emphasis></para> - </listitem> - </orderedlist></entry> - </row> - - <row> - <entry>restContextName</entry> - - <entry>The name of the context name of the rest web - application. This field is optional. The default value wil - be:<orderedlist> - <listitem> - <para>If this field is not empty, then the default value - will be the value of this field.</para> - </listitem> - - <listitem> - <para>f this field is empty and the value of the - parameter <emphasis>default.rest.context</emphasis> is - not empty, then the default value will be the value of - the parameter.</para> - </listitem> - - <listitem> - <para>f this field and the parameter - <emphasis>default.rest.context</emphasis> are both - empty, the default value will be - <emphasis>"rest".</emphasis></para> - </listitem> - </orderedlist></entry> - </row> - - <row> - <entry>realmName</entry> - - <entry>The name of the realm. This field is optional. The - default value wil be:<orderedlist> - <listitem> - <para>If this field is not empty, then the default value - will be the value of this field.</para> - </listitem> - - <listitem> - <para>f this field is empty and the value of the - parameter <emphasis>default.realm.name</emphasis> is not - empty, then the default value will be the value of the - parameter.</para> - </listitem> - - <listitem> - <para>f this field and the parameter - <emphasis>default.realm.name</emphasis> are both empty, - the default value will be - <emphasis>"exo-domain".</emphasis></para> - </listitem> - </orderedlist></entry> - </row> - - <row> - <entry>dependencies</entry> - - <entry>All the dependencies of the portal container ordered by - loading priority. This field is optional. If this field has a - non empty value, it will be the default list of - dependencies.</entry> - </row> - - <row> - <entry>settings</entry> - - <entry>A <envar>java.util.Map</envar> of internal parameters - that we would like to tie the default portal container. Those - parameters could have any type of value. This field is - optional.</entry> - </row> - - <row> - <entry>externalSettingsPath</entry> - - <entry>The path of the external properties file to load as - default settings to the default portal container. This field - is optional. The external properties files can be either of - type "properties" or of type "xml". The path will be - interpreted as follows:<orderedlist> - <listitem> - <para>The path doesn't contain any prefix of type - "classpath:", "jar:" or "file:", we assume that the file - could be externalized so we apply the following - rules:<orderedlist> - <listitem> - <para>A file exists at - <emphasis>${exo-conf-dir}/portal/${externalSettingsPath}</emphasis>, - we will load this file.</para> - </listitem> - - <listitem> - <para>No file exists at the previous path, we then - assume that the path cans be interpreted by the - <envar>ConfigurationManager</envar>.</para> - </listitem> - </orderedlist></para> - </listitem> - - <listitem> - <para>The path contains a prefix, we then assume that - the path cans be interpreted by the - <envar>ConfigurationManager</envar>.</para> - </listitem> - </orderedlist></entry> - </row> - </tbody> - </tgroup> - </table> - - <para>Internal and external settings are both optional, but if we give - a non empty value for both the application will merge the settings. If - the same setting name exists in both settings, we apply the following - rules:</para> - - <orderedlist> - <listitem> - <para>The value of the external setting is - <emphasis>null</emphasis>, we ignore the value.</para> - </listitem> - - <listitem> - <para>The value of the external setting is not - <emphasis>null</emphasis> and the value of the internal setting is - <emphasis>null</emphasis>, the final value will be the external - setting value that is of type <envar>String</envar>.</para> - </listitem> - - <listitem> - <para>Both values are not <envar>null</envar>, we will have to - convert the external setting value into the target type which is - the type of the internal setting value, thanks to the static - method <emphasis>valueOf(String)</emphasis>, the following - sub-rules are then applied:</para> - - <orderedlist> - <listitem> - <para>The method cannot be found, the final value will be the - external setting value that is of type - <envar>String</envar>.</para> - </listitem> - - <listitem> - <para>The method can be found and the external setting value - is an empty <envar>String</envar>, we ignore the external - setting value.</para> - </listitem> - - <listitem> - <para>The method can be found and the external setting value - is not an empty <envar>String</envar> but the method call - fails, we ignore the external setting value.</para> - </listitem> - - <listitem> - <para>The method can be found and the external setting value - is not an empty <envar>String</envar> and the method call - succeeds, the final value will be the external setting value - that is of type of the internal setting value.</para> - </listitem> - </orderedlist> - </listitem> - </orderedlist> - </section> - - <section> - <title><envar>PortalContainer</envar> settings</title> - - <para>We can inject the value of the portal container settings into - the portal container configuration files thanks to the variables which - name start with "<emphasis>portal.container.</emphasis>", so to get - the value of a setting called "<emphasis>foo</emphasis>" just use the - following syntax <emphasis>${portal.container.foo}</emphasis>. You can - also use internal variables, such as:</para> - - <table> - <title>Definition of the internal variables</title> - - <tgroup cols="2"> - <tbody> - <row> - <entry>portal.container.name</entry> - - <entry>Gives the name of the current portal container.</entry> - </row> - - <row> - <entry>portal.container.rest</entry> - - <entry>Gives the context name of the rest web application of - the current portal container.</entry> - </row> - - <row> - <entry>portal.container.realm</entry> - - <entry>Gives the realm name of the current portal - container.</entry> - </row> - </tbody> - </tgroup> - </table> - - <para>You can find below an example of how to use the - variables:<programlisting>&lt;configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.exoplaform.org/xml/ns/kernel_1_1.xsd http://www.exoplaform.org/xml/ns/kernel_1_1.xsd" - xmlns="http://www.exoplaform.org/xml/ns/kernel_1_1.xsd"&gt; - &lt;component&gt; - &lt;type&gt;org.exoplatform.container.TestPortalContainer$MyComponent&lt;/type&gt; - &lt;init-params&gt; - &lt;!-- The name of the portal container --&gt; - &lt;value-param&gt; - &lt;name&gt;portal&lt;/name&gt; - &lt;value&gt;${portal.container.name}&lt;/value&gt; - &lt;/value-param&gt; - &lt;!-- The name of the rest ServletContext --&gt; - &lt;value-param&gt; - &lt;name&gt;rest&lt;/name&gt; - &lt;value&gt;${portal.container.rest}&lt;/value&gt; - &lt;/value-param&gt; - &lt;!-- The name of the realm --&gt; - &lt;value-param&gt; - &lt;name&gt;realm&lt;/name&gt; - &lt;value&gt;${portal.container.realm}&lt;/value&gt; - &lt;/value-param&gt; - &lt;value-param&gt; - &lt;name&gt;foo&lt;/name&gt; - &lt;value&gt;${portal.container.foo}&lt;/value&gt; - &lt;/value-param&gt; - &lt;value-param&gt; - &lt;name&gt;before foo after&lt;/name&gt; - &lt;value&gt;before ${portal.container.foo} after&lt;/value&gt; - &lt;/value-param&gt; - &lt;/init-params&gt; - &lt;/component&gt; -&lt;/configuration&gt;</programlisting></para> - - <para>In the properties file corresponding to the external settings, - you can reuse variables previously defined (in the external settings - or in the internal settings) to create a new variable. In this case - the prefix "<emphasis>portal.container.</emphasis>" is not needed, see - an example below:<programlisting>my-var1=value 1 -my-var2=value 2 -complex-value=${my-var1}-${my-var2}</programlisting></para> - - <para>In the external and internal settings, you can also use create - variables based on value of System paramaters. The System parameters - can either be defined at launch time or thanks to the - <envar>PropertyConfigurator</envar> (see next section for more - details). See an example below:</para> - - <programlisting>temp-dir=${java.io.tmpdir}${file.separator}my-temp</programlisting> - - <para>However, for the internal settings you can use System parameters - only to define settings of type - <envar>java.lang.String</envar>.</para> - - <para>It cans be also very usefull to define a generic variable in the - settings of the default portal container, the value of this variable - will change according to the current portal container. See below an - example:<programlisting>my-generic-var=value of the portal container "${name}"</programlisting></para> - - <para>If this variable is defined at the default portal container - level, the value of this variable for a portal container called - <emphasis>"foo"</emphasis> will be <emphasis>value of the portal - container "foo"</emphasis>.</para> - </section> - - <section> - <title>Add dynamically settings and/or dependencies to a - <envar>PortalContainer</envar></title> - - <para>It is possible to use <envar>component-plugin</envar> elements - in order to dynamically change a PortalContainerDefinition. In the - example below, we add the dependency <envar>foo</envar> to the default - portal container and to the portal containers called - <envar>foo1</envar> and <envar>foo2</envar>:</para> - - <programlisting>&lt;external-component-plugins&gt; - &lt;!-- The full qualified name of the PortalContainerConfig --&gt; - &lt;target-component&gt;org.exoplatform.container.definition.PortalContainerConfig&lt;/target-component&gt; - &lt;component-plugin&gt; - &lt;!-- The name of the plugin --&gt; - &lt;name&gt;Change PortalContainer Definitions&lt;/name&gt; - &lt;!-- The name of the method to call on the PortalContainerConfig in order to register the changes on the PortalContainerDefinitions --&gt; - &lt;set-method&gt;registerChangePlugin&lt;/set-method&gt; - &lt;!-- The full qualified name of the PortalContainerDefinitionChangePlugin --&gt; - &lt;type&gt;org.exoplatform.container.definition.PortalContainerDefinitionChangePlugin&lt;/type&gt; - &lt;init-params&gt; - &lt;value-param&gt; - &lt;name&gt;apply.default&lt;/name&gt; - &lt;value&gt;true&lt;/value&gt; - &lt;/value-param&gt; - &lt;values-param&gt; - &lt;name&gt;apply.specific&lt;/name&gt; - &lt;value&gt;foo1&lt;/value&gt; - &lt;value&gt;foo2&lt;/value&gt; - &lt;/values-param&gt; - &lt;object-param&gt; - &lt;name&gt;change&lt;/name&gt; - &lt;object type="org.exoplatform.container.definition.PortalContainerDefinitionChange$AddDependencies"&gt; - &lt;!-- The list of name of the dependencies to add --&gt; - &lt;field name="dependencies"&gt; - &lt;collection type="java.util.ArrayList"&gt; - &lt;value&gt; - &lt;string&gt;foo&lt;/string&gt; - &lt;/value&gt; - &lt;/collection&gt; - &lt;/field&gt; - &lt;/object&gt; - &lt;/object-param&gt; - &lt;/init-params&gt; - &lt;/component-plugin&gt; -&lt;/external-component-plugins&gt;</programlisting> - - <table> - <title>Descriptions of the fields of a - <envar>PortalContainerDefinitionChangePlugin</envar></title> - - <tgroup cols="2"> - <tbody> - <row> - <entry>apply.all</entry> - - <entry>Indicates whether the changes have to be applied to all - the portal containers or not. The default value of this field - is <envar>false</envar>. This field is a - <envar>ValueParam</envar> and is not mandatory.</entry> - </row> - - <row> - <entry>apply.default</entry> - - <entry>Indicates whether the changes have to be applied to the - default portal container or not. The default value of this - field is <envar>false</envar>. This field is a - <envar>ValueParam</envar> and is not mandatory.</entry> - </row> - - <row> - <entry>apply.specific</entry> - - <entry>A set of specific portal container names to which we - want to apply the changes. This field is a - <envar>ValuesParam</envar> and is not mandatory.</entry> - </row> - - <row> - <entry><envar>Rest of the expected parameters </envar></entry> - - <entry>The rest of the expected paramaters are - <envar>ObjectParam</envar> of type - <envar>PortalContainerDefinitionChange</envar>. Those - parameters are in fact the list of changes that we want to - apply to one or several portal containers. If the list of - changes is empty, the component plugin will be ignored. The - supported implementations of PortalContainerDefinitionChange - are described later in this section.</entry> - </row> - </tbody> - </tgroup> - </table> - - <para>To identify the portal containers to which the changes have to - be applied, we use the follwing algorithm:</para> - - <orderedlist> - <listitem> - <para>The parameter <envar>apply.all</envar> has been set to - <envar>true</envar>. The corresponding changes will be applied to - all the portal containers. The other parameters will be - ignored.</para> - </listitem> - - <listitem> - <para>The parameter <envar>apply.default</envar> has been set to - <envar>true</envar> and the parameter - <envar>apply.specific</envar> is <envar>null</envar>. The - corresponding changes will be applied to the default portal - container only.</para> - </listitem> - - <listitem> - <para>The parameter <envar>apply.default</envar> has been set to - <envar>true</envar> and the parameter - <envar>apply.specific</envar> is not <envar>null</envar>. The - corresponding changes will be applied to the default portal - container and the given list of specific portal containers.</para> - </listitem> - - <listitem> - <para>The parameter <envar>apply.default</envar> has been set to - <envar>false</envar> or has not been set and the parameter - <envar>apply.specific</envar> is <envar>null</envar>. The - corresponding changes will be applied to the default portal - container only.</para> - </listitem> - - <listitem> - <para>The parameter <envar>apply.default</envar> has been set to - <envar>false</envar> or has not been set and the parameter - <envar>apply.specific</envar> is not <envar>null</envar>. The - corresponding changes will be applied to the given list of - specific portal containers.</para> - </listitem> - </orderedlist> - - <section> - <title>The existing implementations of - <envar>PortalContainerDefinitionChange</envar></title> - - <para>The modifications that can be applied to a - <envar>PortalContainerDefinition</envar> must be a class of type - <envar>PortalContainerDefinitionChange</envar>. The product proposes - out of the box some implementations that we describe in the next sub - sections.</para> - - <section> - <title><envar>AddDependencies</envar></title> - - <para>This modification adds a list of dependencies at the end of - the list of dependencies defined into the - <envar>PortalContainerDefinition</envar>. The full qualified name - is - <emphasis>org.exoplatform.container.definition.PortalContainerDefinitionChange$AddDependencies</emphasis>.</para> - - <table> - <title>Descriptions of the fields of an - <envar>AddDependencies</envar></title> - - <tgroup cols="2"> - <tbody> - <row> - <entry>dependencies</entry> - - <entry>A list of <emphasis>String</emphasis> corresponding - to the list of name of the dependencies to add. If the - value of this field is empty, the change will be - ignored.</entry> - </row> - </tbody> - </tgroup> - </table> - - <para>See an example below, that will add <envar>foo</envar> at - the end of the dependency list of the default portal - container:</para> - - <programlisting>&lt;external-component-plugins&gt; - &lt;!-- The full qualified name of the PortalContainerConfig --&gt; - &lt;target-component&gt;org.exoplatform.container.definition.PortalContainerConfig&lt;/target-component&gt; - &lt;component-plugin&gt; - &lt;!-- The name of the plugin --&gt; - &lt;name&gt;Change PortalContainer Definitions&lt;/name&gt; - &lt;!-- The name of the method to call on the PortalContainerConfig in order to register the changes on the PortalContainerDefinitions --&gt; - &lt;set-method&gt;registerChangePlugin&lt;/set-method&gt; - &lt;!-- The full qualified name of the PortalContainerDefinitionChangePlugin --&gt; - &lt;type&gt;org.exoplatform.container.definition.PortalContainerDefinitionChangePlugin&lt;/type&gt; - &lt;init-params&gt; - &lt;value-param&gt; - &lt;name&gt;apply.default&lt;/name&gt; - &lt;value&gt;true&lt;/value&gt; - &lt;/value-param&gt; - &lt;object-param&gt; - &lt;name&gt;change&lt;/name&gt; - &lt;object type="org.exoplatform.container.definition.PortalContainerDefinitionChange$AddDependencies"&gt; - &lt;!-- The list of name of the dependencies to add --&gt; - &lt;field name="dependencies"&gt; - &lt;collection type="java.util.ArrayList"&gt; - &lt;value&gt; - &lt;string&gt;foo&lt;/string&gt; - &lt;/value&gt; - &lt;/collection&gt; - &lt;/field&gt; - &lt;/object&gt; - &lt;/object-param&gt; - &lt;/init-params&gt; - &lt;/component-plugin&gt; -&lt;/external-component-plugins&gt;</programlisting> - </section> - - <section> - <title><envar>AddDependenciesBefore</envar></title> - - <para>This modification adds a list of dependencies before a given - target dependency defined into the list of dependencies of the - <envar>PortalContainerDefinition</envar>. The full qualified name - is - <emphasis>org.exoplatform.container.definition.PortalContainerDefinitionChange$AddDependenciesBefore</emphasis>.</para> - - <table> - <title>Descriptions of the fields of an - <envar>AddDependenciesBefore</envar></title> - - <tgroup cols="2"> - <tbody> - <row> - <entry>dependencies</entry> - - <entry>A list of <emphasis>String</emphasis> corresponding - to the list of name of the dependencies to add. If the - value of this field is empty, the change will be - ignored.</entry> - </row> - - <row> - <entry>target</entry> - - <entry>The name of the dependency before which we would - like to add the new dependencies. If this field is - <envar>null</envar> or the target dependency cannot be - found in the list of dependencies defined into the - <envar>PortalContainerDefinition</envar>, the new - dependencies will be added in first position to the - list.</entry> - </row> - </tbody> - </tgroup> - </table> - - <para>See an example below, that will add <envar>foo</envar> - before <envar>foo2</envar> in the dependency list of the default - portal container:</para> - - <programlisting>&lt;external-component-plugins&gt; - &lt;!-- The full qualified name of the PortalContainerConfig --&gt; - &lt;target-component&gt;org.exoplatform.container.definition.PortalContainerConfig&lt;/target-component&gt; - &lt;component-plugin&gt; - &lt;!-- The name of the plugin --&gt; - &lt;name&gt;Change PortalContainer Definitions&lt;/name&gt; - &lt;!-- The name of the method to call on the PortalContainerConfig in order to register the changes on the PortalContainerDefinitions --&gt; - &lt;set-method&gt;registerChangePlugin&lt;/set-method&gt; - &lt;!-- The full qualified name of the PortalContainerDefinitionChangePlugin --&gt; - &lt;type&gt;org.exoplatform.container.definition.PortalContainerDefinitionChangePlugin&lt;/type&gt; - &lt;init-params&gt; - &lt;value-param&gt; - &lt;name&gt;apply.default&lt;/name&gt; - &lt;value&gt;true&lt;/value&gt; - &lt;/value-param&gt; - &lt;object-param&gt; - &lt;name&gt;change&lt;/name&gt; - &lt;object type="org.exoplatform.container.definition.PortalContainerDefinitionChange$AddDependenciesBefore"&gt; - &lt;!-- The list of name of the dependencies to add --&gt; - &lt;field name="dependencies"&gt; - &lt;collection type="java.util.ArrayList"&gt; - &lt;value&gt; - &lt;string&gt;foo&lt;/string&gt; - &lt;/value&gt; - &lt;/collection&gt; - &lt;/field&gt; - &lt;!-- The name of the target dependency --&gt; - &lt;field name="target"&gt; - &lt;string&gt;foo2&lt;/string&gt; - &lt;/field&gt; - &lt;/object&gt; - &lt;/object-param&gt; - &lt;/init-params&gt; - &lt;/component-plugin&gt; -&lt;/external-component-plugins&gt;</programlisting> - </section> - - <section> - <title><envar>AddDependenciesAfter</envar></title> - - <para>This modification adds a list of dependencies before a given - target dependency defined into the list of dependencies of the - <envar>PortalContainerDefinition</envar>. The full qualified name - is - <emphasis>org.exoplatform.container.definition.PortalContainerDefinitionChange$AddDependenciesAfter</emphasis>.</para> - - <table> - <title>Descriptions of the fields of an - <envar>AddDependenciesAfter</envar></title> - - <tgroup cols="2"> - <tbody> - <row> - <entry>dependencies</entry> - - <entry>A list of <emphasis>String</emphasis> corresponding - to the list of name of the dependencies to add. If the - value of this field is empty, the change will be - ignored.</entry> - </row> - - <row> - <entry>target</entry> - - <entry>The name of the dependency after which we would - like to add the new dependencies. If this field is - <envar>null</envar> or the target dependency cannot be - found in the list of dependencies defined into the - <envar>PortalContainerDefinition</envar>, the new - dependencies will be added in last position to the - list.</entry> - </row> - </tbody> - </tgroup> - </table> - - <para>See an example below, that will add <envar>foo</envar> after - <envar>foo2</envar> in the dependency list of the default portal - container:</para> - - <programlisting>&lt;external-component-plugins&gt; - &lt;!-- The full qualified name of the PortalContainerConfig --&gt; - &lt;target-component&gt;org.exoplatform.container.definition.PortalContainerConfig&lt;/target-component&gt; - &lt;component-plugin&gt; - &lt;!-- The name of the plugin --&gt; - &lt;name&gt;Change PortalContainer Definitions&lt;/name&gt; - &lt;!-- The name of the method to call on the PortalContainerConfig in order to register the changes on the PortalContainerDefinitions --&gt; - &lt;set-method&gt;registerChangePlugin&lt;/set-method&gt; - &lt;!-- The full qualified name of the PortalContainerDefinitionChangePlugin --&gt; - &lt;type&gt;org.exoplatform.container.definition.PortalContainerDefinitionChangePlugin&lt;/type&gt; - &lt;init-params&gt; - &lt;value-param&gt; - &lt;name&gt;apply.default&lt;/name&gt; - &lt;value&gt;true&lt;/value&gt; - &lt;/value-param&gt; - &lt;object-param&gt; - &lt;name&gt;change&lt;/name&gt; - &lt;object type="org.exoplatform.container.definition.PortalContainerDefinitionChange$AddDependenciesAfter"&gt; - &lt;!-- The list of name of the dependencies to add --&gt; - &lt;field name="dependencies"&gt; - &lt;collection type="java.util.ArrayList"&gt; - &lt;value&gt; - &lt;string&gt;foo&lt;/string&gt; - &lt;/value&gt; - &lt;/collection&gt; - &lt;/field&gt; - &lt;!-- The name of the target dependency --&gt; - &lt;field name="target"&gt; - &lt;string&gt;foo2&lt;/string&gt; - &lt;/field&gt; - &lt;/object&gt; - &lt;/object-param&gt; - &lt;/init-params&gt; - &lt;/component-plugin&gt; -&lt;/external-component-plugins&gt;</programlisting> - </section> - - <section> - <title><envar>AddSettings</envar></title> - - <para>This modification adds new settings to a - <envar>PortalContainerDefinition</envar>. The full qualified name - is - <emphasis>org.exoplatform.container.definition.PortalContainerDefinitionChange$AddSettings</emphasis>.</para> - - <table> - <title>Descriptions of the fields of an - <envar>AddSettings</envar></title> - - <tgroup cols="2"> - <tbody> - <row> - <entry>settings</entry> - - <entry>A map of <emphasis>&lt;String, - Object&gt;</emphasis> corresponding to the settings to - add. If the value of this field is empty, the change will - be ignored.</entry> - </row> - </tbody> - </tgroup> - </table> - - <para>See an example below, that will add the settings - <envar>string</envar> and <envar>stringX</envar> to the settings - of the default portal container:</para> - - <programlisting>&lt;external-component-plugins&gt; - &lt;!-- The full qualified name of the PortalContainerConfig --&gt; - &lt;target-component&gt;org.exoplatform.container.definition.PortalContainerConfig&lt;/target-component&gt; - &lt;component-plugin&gt; - &lt;!-- The name of the plugin --&gt; - &lt;name&gt;Change PortalContainer Definitions&lt;/name&gt; - &lt;!-- The name of the method to call on the PortalContainerConfig in order to register the changes on the PortalContainerDefinitions --&gt; - &lt;set-method&gt;registerChangePlugin&lt;/set-method&gt; - &lt;!-- The full qualified name of the PortalContainerDefinitionChangePlugin --&gt; - &lt;type&gt;org.exoplatform.container.definition.PortalContainerDefinitionChangePlugin&lt;/type&gt; - &lt;init-params&gt; - &lt;value-param&gt; - &lt;name&gt;apply.default&lt;/name&gt; - &lt;value&gt;true&lt;/value&gt; - &lt;/value-param&gt; - &lt;object-param&gt; - &lt;name&gt;change&lt;/name&gt; - &lt;object type="org.exoplatform.container.definition.PortalContainerDefinitionChange$AddSettings"&gt; - &lt;!-- The settings to add to the to the portal containers --&gt; - &lt;field name="settings"&gt; - &lt;map type="java.util.HashMap"&gt; - &lt;entry&gt; - &lt;key&gt; - &lt;string&gt;string&lt;/string&gt; - &lt;/key&gt; - &lt;value&gt; - &lt;string&gt;value1&lt;/string&gt; - &lt;/value&gt; - &lt;/entry&gt; - &lt;entry&gt; - &lt;key&gt; - &lt;string&gt;stringX&lt;/string&gt; - &lt;/key&gt; - &lt;value&gt; - &lt;string&gt;value1&lt;/string&gt; - &lt;/value&gt; - &lt;/entry&gt; - &lt;/map&gt; - &lt;/field&gt; - &lt;/object&gt; - &lt;/object-param&gt; - &lt;/init-params&gt; - &lt;/component-plugin&gt; -&lt;/external-component-plugins&gt;</programlisting> - </section> - </section> - </section> - </section> - </section> - - <section> - <title>System property configuration</title> - - <para>A new property configurator service has been developed for taking - care of configuring system properties from the inline kernel configuration - or from specified property files.</para> - - <para>The services is scoped at the root container level because it is - used by all the services in the different portal containers in the - application runtime.</para> - - <section> - <title>Properties init param</title> - - <para>The properties init param takes a property declared to configure - various properties.</para> - - <programlisting>&lt;component&gt; - &lt;key&gt;PropertyManagerConfigurator&lt;/key&gt; - &lt;type&gt;org.exoplatform.container.PropertyConfigurator&lt;/type&gt; - &lt;init-params&gt; - &lt;properties-param&gt; - &lt;name&gt;properties&lt;/name&gt; - &lt;property name="foo" value="bar"/&gt; - &lt;/properties-param&gt; - &lt;/init-params&gt; -&lt;/component&gt;</programlisting> - </section> - - <section> - <title>Properties URL init param</title> - - <para>The properties URL init param allow to load an external file by - specifying its URL. Both property and XML format are supported, see the - javadoc of the <emphasis><envar>java.util.Properties</envar></emphasis> - class for more information. When a property file is loaded the various - property declarations are loaded in the order in which the properties - are declared sequentially in the file.</para> - - <programlisting>&lt;component&gt; - &lt;key&gt;PropertyManagerConfigurator&lt;/key&gt; - &lt;type&gt;org.exoplatform.container.PropertyConfigurator&lt;/type&gt; - &lt;init-params&gt; - &lt;value-param&gt; - &lt;name&gt;properties.url&lt;/name&gt; - &lt;value&gt;classpath:configuration.properties&lt;/value&gt; - &lt;/value-param&gt; - &lt;/init-params&gt; -&lt;/component&gt;</programlisting> - - <para>In the properties file corresponding to the external properties, - you can reuse variables previously defined to create a new variable. In - this case the prefix "<emphasis>portal.container.</emphasis>" is not - needed, see an example below:<programlisting>my-var1=value 1 -my-var2=value 2 -complex-value=${my-var1}-${my-var2}</programlisting></para> - </section> - - <section> - <title>System Property configuration of the properties URL</title> - - <para>It is possible to replace the properties URL init param by a - system property that overwrites it. The name of that property is - <emphasis>exo.properties.url</emphasis>.</para> - </section> - </section> - - <section> - <title>Runtime configuration profiles</title> - - <para>The kernel configuration is able to handle configuration profiles at - runtime (as opposed to packaging time).</para> - - <section> - <title>Profiles activation</title> - - <para>An active profile list is obtained during the boot of the root - container and is composed of the system property - <emphasis>exo.profiles</emphasis> sliced according the "," delimiter and - also a server specific profile value (tomcat for tomcat, jboss for - jboss, etc...).</para> - - <programlisting># runs GateIn on Tomcat with the profiles tomcat and foo -sh gatein.sh -Dexo.profiles=foo - -# runs GateIn on JBoss with the profiles jboss, foo and bar -sh run.sh -Dexo.profiles=foo,bar</programlisting> - </section> - - <section> - <title>Profiles configuration</title> - - <para>Profiles are configured in the configuration files of the eXo - kernel.</para> - - <section> - <title>Profiles definition</title> - - <para>Profile activation occurs at XML to configuration object - unmarshalling time. It is based on an "profile" attribute that is - present on some of the XML element of the configuration files. To - enable this the kernel configuration schema has been upgraded to - kernel_1_1.xsd. The configuration is based on the following - rules:</para> - - <orderedlist> - <listitem> - <para>Any kernel element with the no <emphasis>profiles</emphasis> - attribute will create a configuration object</para> - </listitem> - - <listitem> - <para>Any kernel element having a <emphasis>profiles</emphasis> - attribute containing at least one of the active profiles will - create a configuration object</para> - </listitem> - - <listitem> - <para>Any kernel element having a <emphasis>profiles</emphasis> - attribute matching none of the active profile will not create a - configuration object</para> - </listitem> - - <listitem> - <para>Resolution of duplicates (such as two components with same - type) is left up to the kernel</para> - </listitem> - </orderedlist> - </section> - - <section> - <title>Profiles capable configuration elements</title> - - <para>A configuration element is <emphasis>profiles</emphasis> capable - when it carries a profiles element.</para> - - <section> - <title>Component element</title> - - <para>The component element declares a component when activated. It - will shadow any element with the same key declared before in the - same configuration file:</para> - - <programlisting>&lt;component&gt; - &lt;key&gt;Component&lt;/key&gt; - &lt;type&gt;Component&lt;/type&gt; -&lt;/component&gt; - -&lt;component profiles="foo"&gt; - &lt;key&gt;Component&lt;/key&gt; - &lt;type&gt;FooComponent&lt;/type&gt; -&lt;/component&gt;</programlisting> - </section> - - <section> - <title>Component plugin element</title> - - <para>The component-plugin element is used to dynamically extend the - configuration of a given component. Thanks to the profiles the - component-plugins could be enabled or disabled:</para> - - <programlisting>&lt;external-component-plugins&gt; - &lt;target-component&gt;Component&lt;/target-component&gt; - &lt;component-plugin profiles="foo"&gt; - &lt;name&gt;foo&lt;/name&gt; - &lt;set-method&gt;addPlugin&lt;/set-method&gt; - &lt;type&gt;type&lt;/type&gt; - &lt;init-params&gt; - &lt;value-param&gt; - &lt;name&gt;param&lt;/name&gt; - &lt;value&gt;empty&lt;/value&gt; - &lt;/value-param&gt; - &lt;/init-params&gt; - &lt;/component-plugin&gt; -&lt;/external-component-plugins&gt;</programlisting> - </section> - - <section> - <title>Import element</title> - - <para>The import element imports a referenced configuration file - when activated:</para> - - <programlisting>&lt;import&gt;empty&lt;/import&gt; -&lt;import profiles="foo"&gt;foo&lt;/import&gt; -&lt;import profiles="bar"&gt;bar&lt;/import&gt;</programlisting> - </section> - - <section> - <title>Init param element</title> - - <para>The init param element configures the parameter argument of - the construction of a component service:</para> - - <programlisting>&lt;component&gt; - &lt;key&gt;Component&lt;/key&gt; - &lt;type&gt;ComponentImpl&lt;/type&gt; - &lt;init-params&gt; - &lt;value-param&gt; - &lt;name&gt;param&lt;/name&gt; - &lt;value&gt;empty&lt;/value&gt; - &lt;/value-param&gt; - &lt;value-param profiles="foo"&gt; - &lt;name&gt;param&lt;/name&gt; - &lt;value&gt;foo&lt;/value&gt; - &lt;/value-param&gt; - &lt;value-param profiles="bar"&gt; - &lt;name&gt;param&lt;/name&gt; - &lt;value&gt;bar&lt;/value&gt; - &lt;/value-param&gt; - &lt;/init-params&gt; -&lt;/component&gt;</programlisting> - </section> - - <section> - <title>Value collection element</title> - - <para>The value collection element configures one of the value of - collection data:</para> - - <programlisting>&lt;object type="org.exoplatform.container.configuration.ConfigParam"&gt; - &lt;field name="role"&gt; - &lt;collection type="java.util.ArrayList"&gt; - &lt;value&gt;&lt;string&gt;manager&lt;/string&gt;&lt;/value&gt; - &lt;value profiles="foo"&gt;&lt;string&gt;foo_manager&lt;/string&gt;&lt;/value&gt; - &lt;value profiles="foo,bar"&gt;&lt;string&gt;foo_bar_manager&lt;/string&gt;&lt;/value&gt; - &lt;/collection&gt; - &lt;/field&gt; -&lt;/object&gt;</programlisting> - </section> - - <section> - <title>Field configuration element</title> - - <para>The field configuration element configures the field of an - object:</para> - - <programlisting>&lt;object-param&gt; - &lt;name&gt;test.configuration&lt;/name&gt; - &lt;object type="org.exoplatform.container.configuration.ConfigParam"&gt; - &lt;field name="role"&gt; - &lt;collection type="java.util.ArrayList"&gt; - &lt;value&gt;&lt;string&gt;manager&lt;/string&gt;&lt;/value&gt; - &lt;/collection&gt; - &lt;/field&gt; - &lt;field name="role" profiles="foo,bar"&gt; - &lt;collection type="java.util.ArrayList"&gt; - &lt;value&gt;&lt;string&gt;foo_bar_manager&lt;/string&gt;&lt;/value&gt; - &lt;/collection&gt; - &lt;/field&gt; - &lt;field name="role" profiles="foo"&gt; - &lt;collection type="java.util.ArrayList"&gt; - &lt;value&gt;&lt;string&gt;foo_manager&lt;/string&gt;&lt;/value&gt; - &lt;/collection&gt; - &lt;/field&gt; - &lt;/object&gt; -&lt;/object-param&gt;</programlisting> - </section> - </section> - </section> - </section> - - <section> - <title>Component request life cycle</title> - - <section> - <title>Component request life cycle contract</title> - - <para>The component request life cycle is an interface that defines a - contract for a component for being involved into a - request:<programlisting>public interface ComponentRequestLifecycle -{ - /** - * Start a request. - * @param container the related container - */ - void startRequest(ExoContainer container); - - /** - * Ends a request. - * @param container the related container - */ - void endRequest(ExoContainer container); -}</programlisting></para> - - <para>The container passed is the container to which the component is - related. This contract is often used to setup a thread local based - context that will be demarcated by a request.</para> - - <para>For instance in the GateIn portal context, a component request - life cycle is triggered for user requests. Another example is the - initial data import in GateIn that demarcates using callbacks made to - that interface.</para> - </section> - - <section> - <title>Request life cycle</title> - - <para>The <envar>RequestLifeCycle</envar> class has several statics - methods that are used to schedule the component request life cycle of - components. Its main responsability is to perform scheduling while - respecting the constraint to execute the request life cycle of a - component only once even if it can be scheduled several times.</para> - - <section> - <title>Scheduling a component request life cycle</title> - - <programlisting>RequestLifeCycle.begin(component); -try -{ - // Do something -} -finally -{ - RequestLifeCycle.end(); -}</programlisting> - </section> - - <section> - <title>Scheduling a container request life cycle</title> - - <para>Scheduling a container triggers the component request life cyle - of all the components that implement the interface - <envar>ComponentRequestLifeCycle</envar>. If one of the component has - already been scheduled before then that component will not be - scheduled again. When the local value is true then the looked - components will be those of the container, when it is false then the - scheduler will also look at the components in the ancestor - containers.<programlisting>RequestLifeCycle.begin(container, local); -try -{ - // Do something -} -finally -{ - RequestLifeCycle.end(); -}</programlisting></para> - </section> - </section> - - <section> - <title>When request life cycle is triggered</title> - - <section> - <title>Portal request life cycle</title> - - <para>Each portal request triggers the life cycle of the associated - portal container.</para> - </section> - - <section> - <title>JMX request Life Cycle</title> - - <para>When a JMX bean is invoked, the request life cycle of the - container to which it belongs it scheduled. Indeed JMX is an entry - point of the system that may need component to have a request life - cycle triggered.</para> - </section> - </section> - </section> -</chapter> +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<chapter id="Kernel.ContainerConfiguration"> + <?dbhtml filename="ch-kernel-container-configuration.html"?> + + <title>Container Configuration</title> + + <section> + <title>Intro</title> + + <para>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.</para> + + <para>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.</para> + + <para>Confused? - You might be interested in the <link + linkend="Kernel.ServiceConfigurationforBeginners">Service Configuration + for Beginners</link> article, which explains the basics.</para> + </section> + + <section id="Kernel.ContainerConfiguration.ConfigurationNamespace"> + <title>Kernel configuration namespace</title> + + <para>To be effective the namespace URI + <uri>http://www.exoplaform.org/xml/ns/kernel_1_1.xsd</uri> must be target + namespace of the XML configuration file.</para> + + <programlisting>&lt;xsd:schema + targetNamespace="http://www.exoplaform.org/xml/ns/kernel_1_1.xsd" + xmlns="http://www.exoplaform.org/xml/ns/kernel_1_1.xsd" + xmlns:xsd="http://www.w3.org/2001/XMLSchema" + elementFormDefault="qualified" + attributeFormDefault="unqualified" + version="1.0"&gt; + + ... +&lt;/xsd:schema&gt;</programlisting> + </section> + + <section> + <title>Understanding How configuration files are loaded</title> + + <para>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.</para> + + <para>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.</para> + + <section> + <title>Configuration Retrieval</title> + + <para>The container performs the following steps making eXo Container + configuration retrieval depending on the container type.</para> + + <section> + <title>Configuration retrieval order for the + <envar>PortalContainer</envar></title> + + <para>The container is initialized by looking into different + locations. This container is used by portal applications. + Configurations are overloaded in the following lookup sequence:</para> + + <orderedlist> + <listitem> + <para>Services default <envar>RootContainer</envar> configurations + from JAR files <emphasis>/conf/configuration.xml</emphasis></para> + </listitem> + + <listitem> + <para>External <envar>RootContainer</envar> configuration, if will + be found at + <emphasis>$AS_HOME/exo-conf/configuration.xml</emphasis></para> + </listitem> + + <listitem> + <para>Services default <envar>PortalContainer</envar> + configurations from JAR files + <emphasis>/conf/portal/configuration.xml</emphasis></para> + </listitem> + + <listitem> + <para>Web applications configurations from WAR files + <emphasis>/WEB-INF/conf/configuration.xml</emphasis></para> + </listitem> + + <listitem> + <para>External configuration for services of named portal, if will + be found at + <emphasis>$AS_HOME/exo-conf/portal/$PORTAL_NAME/configuration.xml</emphasis></para> + </listitem> + </orderedlist> + </section> + + <section> + <title>Configuration retrieval for a + <envar>StandaloneContainer</envar></title> + + <para>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:</para> + + <orderedlist> + <listitem> + <para>Services default <envar>RootContainer</envar> configurations + from JAR files <emphasis>/conf/configuration.xml</emphasis></para> + </listitem> + + <listitem> + <para>External <envar>RootContainer</envar> configuration, if will + be found at + <emphasis>$AS_HOME/exo-conf/configuration.xml</emphasis></para> + </listitem> + + <listitem> + <para>Services default <envar>StandaloneContainer</envar> + configurations from JAR files + <emphasis>/conf/portal/configuration.xml</emphasis></para> + </listitem> + + <listitem> + <para>Web applications configurations from WAR files + <emphasis>/WEB-INF/conf/configuration.xml</emphasis></para> + </listitem> + + <listitem> + <para>Then depending on the <envar>StandaloneContainer</envar> + configuration URL initialization:</para> + + <itemizedlist> + <listitem> + <para>if configuration URL was initialized to be added to + services defaults, as below:<programlisting>// add configuration to the default services configurations from JARs/WARs +StandaloneContainer.addConfigurationURL(containerConf);</programlisting></para> + + <para>Configuration from added URL + <emphasis>containerConf</emphasis> will override only services + configured in the file</para> + </listitem> + + <listitem> + <para>if configuration URL not initialized at all, it will be + found at <emphasis>$AS_HOME/exo-configuration.xml</emphasis>. + If <emphasis>$AS_HOME/exo-configuration.xml</emphasis> doesn't + exist the container will try find it at + <emphasis>$AS_HOME/exo-conf/exo-configuration.xml</emphasis> + location and if it's still not found and the + <envar>StandaloneContainer</envar> instance obtained with the + dedicated configuration <envar>ClassLoader</envar> the + container will try to retrieve the resource + <emphasis>conf/exo-configuration.xml</emphasis> within the + given <envar>ClassLoader</envar>.</para> + </listitem> + </itemizedlist> + </listitem> + </orderedlist> + </section> + + <section> + <title>General notes about the configuration retrieval</title> + + <note> + <para><emphasis>$AS_HOME</emphasis> - application server home + directory, or <emphasis>user.dir</emphasis> JVM system property + value in case of Java Standalone application.</para> + </note> + + <note> + <para><emphasis>$PORTAL_NAME</emphasis> - portal web application + name.</para> + </note> + + <note> + <para>External configuration location can be overridden with System + property <emphasis>exo.conf.dir</emphasis>. If the property exists + its value will be used as path to eXo configuration directory, i.e. + to <emphasis>$AS_HOME/exo-conf</emphasis> alternative. E.g. put + property in command line java + <emphasis>-Dexo.conf.dir=/path/to/exo/conf</emphasis>. In this + particular use case, you have no need to use any prefix to import + other files. For instance, if your configuration file is + <emphasis>$AS_HOME/exo-conf/portal/PORTAL_NAME/configuration.xml</emphasis> + and you want to import the configuration file + <emphasis>$AS_HOME/exo-conf/portal/PORTAL_NAME/mySubConfDir/myConfig.xml</emphasis>, + you can do it by adding + <emphasis>&lt;import&gt;mySubConfDir/myConfig.xml&lt;/import&gt;</emphasis> + to your configuration file.</para> + </note> + + <note> + <para>The name of the configuration folder that is by default + <emphasis>"exo-conf"</emphasis>, can be changed thanks to the System + property <emphasis>exo.conf.dir.name</emphasis>.</para> + </note> + + <note> + <para>Under JBoss application server <emphasis>exo-conf</emphasis> + will be looked up in directory described by JBoss System property + <emphasis>jboss.server.config.url</emphasis>. If the property is not + found or empty <emphasis>$AS_HOME/exo-conf</emphasis> will be + asked.</para> + </note> + + <note> + <para>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.</para> + </note> + + <warning> + <para>Take care to have no dependencies between configurations from + JAR files (<emphasis>/conf/portal/configuration.xml</emphasis> and + <emphasis>/conf/configuration.xml</emphasis>) 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 <emphasis>/conf/portal/configuration.xml</emphasis> of a + given JAR file, you must not do it from the file + <emphasis>/conf/portal/configuration.xml</emphasis> of another JAR + file but from another configuration file loaded after configurations + from JAR files + <emphasis>/conf/portal/configuration.xml.</emphasis></para> + </warning> + + <para>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).</para> + + <para>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.</para> + + <para>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).</para> + </section> + + <section> + <title>Configuration retrieval log</title> + + <para>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 + <emphasis>org.exoplatform.container.configuration.debug</emphasis> can + be used.<programlisting>java -Dorg.exoplatform.container.configuration.debug ...</programlisting></para> + + <para>If the property is enabled the container configuration manager + will log the configuration adding process at <emphasis>INFO</emphasis> + level.<programlisting>...... + 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 + ......</programlisting></para> + </section> + + <section> + <title>Get the effective configuration at Runtime</title> + + <para>The effective configuration of the StandaloneContainer, + RootContainer and/or PortalContainer can be known thanks to the method + <emphasis>getConfigurationXML</emphasis>() 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 the + kernel. This could be helpful to understand how a given component or + plugin has been initialized.</para> + </section> + </section> + + <section> + <title>Advanced concepts for the + <emphasis>PortalContainers</emphasis></title> + + <para>Since eXo JCR 1.12, we added a set of new features that have been + designed to extend portal applications such as GateIn.</para> + + <section> + <title>Add new configuration files from a WAR file</title> + + <para>A <envar>ServletContextListener</envar> called + <envar>org.exoplatform.container.web.PortalContainerConfigOwner</envar> + has been added in order to notify the application that a given web + application provides some configuration to the portal container, and + this configuration file is the file + <emphasis>WEB-INF/conf/configuration.xml</emphasis> available in the + web application itself.</para> + + <para>If your war file contains some configuration to add to the + <envar>PortalContainer</envar> simply add the following lines in your + <emphasis>web.xml</emphasis> file.</para> + + <programlisting>&lt;?xml version="1.0" encoding="ISO-8859-1" ?&gt; +&lt;!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN" + "http://java.sun.com/dtd/web-app_2_3.dtd"&gt; +&lt;web-app&gt; +... + &lt;!-- ================================================================== --&gt; + &lt;!-- LISTENER --&gt; + &lt;!-- ================================================================== --&gt; + &lt;listener&gt; + &lt;listener-class&gt;org.exoplatform.container.web.PortalContainerConfigOwner&lt;/listener-class&gt; + &lt;/listener&gt; +... +&lt;/web-app&gt;</programlisting> + </section> + + <section> + <title>Create your <emphasis>PortalContainers</emphasis> from a WAR + file</title> + + <para>A <envar>ServletContextListener</envar> called + <envar>org.exoplatform.container.web.PortalContainerCreator</envar> + has been added in order to create the current portal containers that + have been registered. We assume that all the web applications have + already been loaded before calling + <envar>PortalContainerCreator.contextInitialized<replaceable><optional>.</optional></replaceable></envar></para> + + <para><note> + <para>In GateIn, the <envar>PortalContainerCreator</envar> is + already managed by the file + <emphasis>starter.war/ear.</emphasis></para> + </note></para> + </section> + + <section> + <title>Define a <emphasis>PortalContainer</emphasis> with its + dependencies and its settings</title> + + <para>Now we can define precisely a portal container and its + dependencies and settings thanks to the + <envar>PortalContainerDefinition</envar> that currently contains the + name of the portal container, the name of the rest context, the name + of the realm he web application dependencies ordered by loading + priority (i.e. the first dependency must be loaded at first and so + on..) and the settings.</para> + + <para>To be able to define a <envar>PortalContainerDefinition</envar>, + we need to ensure first of all that a + <envar>PortalContainerConfig</envar> has been defined at the + <envar>RootContainer</envar> level, see below an example:</para> + + <programlisting> &lt;component&gt; + &lt;!-- The full qualified name of the PortalContainerConfig --&gt; + &lt;type&gt;org.exoplatform.container.definition.PortalContainerConfig&lt;/type&gt; + &lt;init-params&gt; + &lt;!-- The name of the default portal container --&gt; + &lt;value-param&gt; + &lt;name&gt;default.portal.container&lt;/name&gt; + &lt;value&gt;myPortal&lt;/value&gt; + &lt;/value-param&gt; + &lt;!-- The name of the default rest ServletContext --&gt; + &lt;value-param&gt; + &lt;name&gt;default.rest.context&lt;/name&gt; + &lt;value&gt;myRest&lt;/value&gt; + &lt;/value-param&gt; + &lt;!-- The name of the default realm --&gt; + &lt;value-param&gt; + &lt;name&gt;default.realm.name&lt;/name&gt; + &lt;value&gt;my-exo-domain&lt;/value&gt; + &lt;/value-param&gt; + &lt;!-- The default portal container definition --&gt; + &lt;!-- It cans be used to avoid duplicating configuration --&gt; + &lt;object-param&gt; + &lt;name&gt;default.portal.definition&lt;/name&gt; + &lt;object type="org.exoplatform.container.definition.PortalContainerDefinition"&gt; + &lt;!-- All the dependencies of the portal container ordered by loading priority --&gt; + &lt;field name="dependencies"&gt; + &lt;collection type="java.util.ArrayList"&gt; + &lt;value&gt; + &lt;string&gt;foo&lt;/string&gt; + &lt;/value&gt; + &lt;value&gt; + &lt;string&gt;foo2&lt;/string&gt; + &lt;/value&gt; + &lt;value&gt; + &lt;string&gt;foo3&lt;/string&gt; + &lt;/value&gt; + &lt;/collection&gt; + &lt;/field&gt; + &lt;!-- A map of settings tied to the default portal container --&gt; + &lt;field name="settings"&gt; + &lt;map type="java.util.HashMap"&gt; + &lt;entry&gt; + &lt;key&gt; + &lt;string&gt;foo5&lt;/string&gt; + &lt;/key&gt; + &lt;value&gt; + &lt;string&gt;value&lt;/string&gt; + &lt;/value&gt; + &lt;/entry&gt; + &lt;entry&gt; + &lt;key&gt; + &lt;string&gt;string&lt;/string&gt; + &lt;/key&gt; + &lt;value&gt; + &lt;string&gt;value0&lt;/string&gt; + &lt;/value&gt; + &lt;/entry&gt; + &lt;entry&gt; + &lt;key&gt; + &lt;string&gt;int&lt;/string&gt; + &lt;/key&gt; + &lt;value&gt; + &lt;int&gt;100&lt;/int&gt; + &lt;/value&gt; + &lt;/entry&gt; + &lt;/map&gt; + &lt;/field&gt; + &lt;!-- The path to the external properties file --&gt; + &lt;field name="externalSettingsPath"&gt; + &lt;string&gt;classpath:/org/exoplatform/container/definition/default-settings.properties&lt;/string&gt; + &lt;/field&gt; + &lt;/object&gt; + &lt;/object-param&gt; + &lt;/init-params&gt; + &lt;/component&gt;</programlisting> + + <table> + <title>Descriptions of the fields of + <envar>PortalContainerConfig</envar></title> + + <tgroup cols="2"> + <tbody> + <row> + <entry>default.portal.container</entry> + + <entry>The name of the default portal container. This field is + optional.</entry> + </row> + + <row> + <entry>default.rest.context</entry> + + <entry>The name of the default rest + <envar>ServletContext</envar>. This field is optional.</entry> + </row> + + <row> + <entry>default.realm.name</entry> + + <entry>The name of the default realm. This field is + optional.</entry> + </row> + + <row> + <entry>default.portal.definition</entry> + + <entry>The definition of the default portal container. This + field is optional. The expected type is + <envar>org.exoplatform.container.definition.PortalContainerDefinition</envar> + that is described below. Allow the parameters defined in this + default <envar>PortalContainerDefinition</envar> will be the + default values.</entry> + </row> + </tbody> + </tgroup> + </table> + + <para>A new <envar>PortalContainerDefinition</envar> can be defined at + the <envar>RootContainer</envar> level thanks to an external plugin, + see below an example:<programlisting> &lt;external-component-plugins&gt; + &lt;!-- The full qualified name of the PortalContainerConfig --&gt; + &lt;target-component&gt;org.exoplatform.container.definition.PortalContainerConfig&lt;/target-component&gt; + &lt;component-plugin&gt; + &lt;!-- The name of the plugin --&gt; + &lt;name&gt;Add PortalContainer Definitions&lt;/name&gt; + &lt;!-- The name of the method to call on the PortalContainerConfig in order to register the PortalContainerDefinitions --&gt; + &lt;set-method&gt;registerPlugin&lt;/set-method&gt; + &lt;!-- The full qualified name of the PortalContainerDefinitionPlugin --&gt; + &lt;type&gt;org.exoplatform.container.definition.PortalContainerDefinitionPlugin&lt;/type&gt; + &lt;init-params&gt; + &lt;object-param&gt; + &lt;name&gt;portal&lt;/name&gt; + &lt;object type="org.exoplatform.container.definition.PortalContainerDefinition"&gt; + &lt;!-- The name of the portal container --&gt; + &lt;field name="name"&gt; + &lt;string&gt;myPortal&lt;/string&gt; + &lt;/field&gt; + &lt;!-- The name of the context name of the rest web application --&gt; + &lt;field name="restContextName"&gt; + &lt;string&gt;myRest&lt;/string&gt; + &lt;/field&gt; + &lt;!-- The name of the realm --&gt; + &lt;field name="realmName"&gt; + &lt;string&gt;my-domain&lt;/string&gt; + &lt;/field&gt; + &lt;!-- All the dependencies of the portal container ordered by loading priority --&gt; + &lt;field name="dependencies"&gt; + &lt;collection type="java.util.ArrayList"&gt; + &lt;value&gt; + &lt;string&gt;foo&lt;/string&gt; + &lt;/value&gt; + &lt;value&gt; + &lt;string&gt;foo2&lt;/string&gt; + &lt;/value&gt; + &lt;value&gt; + &lt;string&gt;foo3&lt;/string&gt; + &lt;/value&gt; + &lt;/collection&gt; + &lt;/field&gt; + &lt;!-- A map of settings tied to the portal container --&gt; + &lt;field name="settings"&gt; + &lt;map type="java.util.HashMap"&gt; + &lt;entry&gt; + &lt;key&gt; + &lt;string&gt;foo&lt;/string&gt; + &lt;/key&gt; + &lt;value&gt; + &lt;string&gt;value&lt;/string&gt; + &lt;/value&gt; + &lt;/entry&gt; + &lt;entry&gt; + &lt;key&gt; + &lt;string&gt;int&lt;/string&gt; + &lt;/key&gt; + &lt;value&gt; + &lt;int&gt;10&lt;/int&gt; + &lt;/value&gt; + &lt;/entry&gt; + &lt;entry&gt; + &lt;key&gt; + &lt;string&gt;long&lt;/string&gt; + &lt;/key&gt; + &lt;value&gt; + &lt;long&gt;10&lt;/long&gt; + &lt;/value&gt; + &lt;/entry&gt; + &lt;entry&gt; + &lt;key&gt; + &lt;string&gt;double&lt;/string&gt; + &lt;/key&gt; + &lt;value&gt; + &lt;double&gt;10&lt;/double&gt; + &lt;/value&gt; + &lt;/entry&gt; + &lt;entry&gt; + &lt;key&gt; + &lt;string&gt;boolean&lt;/string&gt; + &lt;/key&gt; + &lt;value&gt; + &lt;boolean&gt;true&lt;/boolean&gt; + &lt;/value&gt; + &lt;/entry&gt; + &lt;/map&gt; + &lt;/field&gt; + &lt;!-- The path to the external properties file --&gt; + &lt;field name="externalSettingsPath"&gt; + &lt;string&gt;classpath:/org/exoplatform/container/definition/settings.properties&lt;/string&gt; + &lt;/field&gt; + &lt;/object&gt; + &lt;/object-param&gt; + &lt;/init-params&gt; + &lt;/component-plugin&gt; + &lt;/external-component-plugins&gt;</programlisting></para> + + <table> + <title>Descriptions of the fields of a + <envar>PortalContainerDefinition</envar> when it is used to define a + new portal container</title> + + <tgroup cols="2"> + <tbody> + <row> + <entry>name</entry> + + <entry>The name of the portal container. This field is + mandatory .</entry> + </row> + + <row> + <entry>restContextName</entry> + + <entry>The name of the context name of the rest web + application. This field is optional. The default value will + the value define at the <envar>PortalContainerConfig</envar> + level.</entry> + </row> + + <row> + <entry>realmName</entry> + + <entry>The name of the realm. This field is optional. The + default value will the value define at the + <envar>PortalContainerConfig</envar> level.</entry> + </row> + + <row> + <entry>dependencies</entry> + + <entry>All the dependencies of the portal container ordered by + loading priority. This field is optional. The default value + will the value define at the + <envar>PortalContainerConfig</envar> level. The dependencies + are in fact the list of the context names of the web + applications from which the portal container depends. This + field is optional. The dependency order is really crucial + since it will be interpreted the same way by several + components of the platform. All those components, will + consider the 1st element in the list less important than the + second element and so on. It is currently used + to:<itemizedlist> + <listitem> + <para>Know the loading order of all the + dependencies.</para> + </listitem> + + <listitem> + <para>If we have several + <envar>PortalContainerConfigOwner</envar><itemizedlist> + <listitem> + <para>The <envar>ServletContext</envar> of all the + <envar>PortalContainerConfigOwner</envar> will be + unified, if we use the unified + <envar>ServletContext</envar> + (<emphasis>PortalContainer.getPortalContext()</emphasis>) + to get a resource, it will try to get the resource + in the <envar>ServletContext</envar> of the most + important <envar>PortalContainerConfigOwner</envar> + (i.e. last in the dependency list) and if it cans + find it, it will try with the second most important + <envar>PortalContainerConfigOwner</envar> and so + on.</para> + </listitem> + + <listitem> + <para>The <envar>ClassLoader</envar> of all the + <envar>PortalContainerConfigOwner</envar> will be + unified, if we use the unified + <envar>ClassLoader</envar> + (<emphasis>PortalContainer.getPortalClassLoader()</emphasis>) + to get a resource, it will try to get the resource + in the <envar>ClassLoader</envar> of the most + important <envar>PortalContainerConfigOwner</envar> + (i.e. last in the dependency list) and if it cans + find it, it will try with the second most important + <envar>PortalContainerConfigOwner</envar> and so + on.</para> + </listitem> + </itemizedlist></para> + </listitem> + </itemizedlist></entry> + </row> + + <row> + <entry>settings</entry> + + <entry>A <envar>java.util.Map</envar> of internal parameters + that we would like to tie the portal container. Those + parameters could have any type of value. This field is + optional. If some internal settings are defined at the + <envar>PortalContainerConfig</envar> level, the two maps of + settings will be merged. If a setting with the same name is + defined in both maps, it will keep the value defined at the + <envar>PortalContainerDefinition</envar> level.</entry> + </row> + + <row> + <entry>externalSettingsPath</entry> + + <entry>The path of the external properties file to load as + default settings to the portal container. This field is + optional. If some external settings are defined at the + <envar>PortalContainerConfig</envar> level, the two maps of + settings will be merged. If a setting with the same name is + defined in both maps, it will keep the value defined at the + <envar>PortalContainerDefinition</envar> level. The external + properties files can be either of type "properties" or of type + "xml". The path will be interpreted as follows:<orderedlist> + <listitem> + <para>The path doesn't contain any prefix of type + "classpath:", "jar:" or "file:", we assume that the file + could be externalized so we apply the following + rules:<orderedlist> + <listitem> + <para>A file exists at + <emphasis>${exo-conf-dir}/portal/${portalContainerName}/${externalSettingsPath}</emphasis>, + we will load this file.</para> + </listitem> + + <listitem> + <para>No file exists at the previous path, we then + assume that the path cans be interpreted by the + <envar>ConfigurationManager</envar>.</para> + </listitem> + </orderedlist></para> + </listitem> + + <listitem> + <para>The path contains a prefix, we then assume that + the path cans be interpreted by the + <envar>ConfigurationManager</envar>.</para> + </listitem> + </orderedlist></entry> + </row> + </tbody> + </tgroup> + </table> + + <table> + <title>Descriptions of the fields of a + <envar>PortalContainerDefinition</envar> when it is used to define + the default portal container</title> + + <tgroup cols="2"> + <tbody> + <row> + <entry>name</entry> + + <entry>The name of the portal container. This field is + optional. The default portal name will be:<orderedlist> + <listitem> + <para>If this field is not empty, then the default value + will be the value of this field.</para> + </listitem> + + <listitem> + <para>If this field is empty and the value of the + parameter <emphasis>default.portal.container</emphasis> + is not empty, then the default value will be the value + of the parameter.</para> + </listitem> + + <listitem> + <para>If this field and the parameter + <emphasis>default.portal.container</emphasis> are both + empty, the default value will be + <emphasis>"portal".</emphasis></para> + </listitem> + </orderedlist></entry> + </row> + + <row> + <entry>restContextName</entry> + + <entry>The name of the context name of the rest web + application. This field is optional. The default value wil + be:<orderedlist> + <listitem> + <para>If this field is not empty, then the default value + will be the value of this field.</para> + </listitem> + + <listitem> + <para>f this field is empty and the value of the + parameter <emphasis>default.rest.context</emphasis> is + not empty, then the default value will be the value of + the parameter.</para> + </listitem> + + <listitem> + <para>f this field and the parameter + <emphasis>default.rest.context</emphasis> are both + empty, the default value will be + <emphasis>"rest".</emphasis></para> + </listitem> + </orderedlist></entry> + </row> + + <row> + <entry>realmName</entry> + + <entry>The name of the realm. This field is optional. The + default value wil be:<orderedlist> + <listitem> + <para>If this field is not empty, then the default value + will be the value of this field.</para> + </listitem> + + <listitem> + <para>f this field is empty and the value of the + parameter <emphasis>default.realm.name</emphasis> is not + empty, then the default value will be the value of the + parameter.</para> + </listitem> + + <listitem> + <para>f this field and the parameter + <emphasis>default.realm.name</emphasis> are both empty, + the default value will be + <emphasis>"exo-domain".</emphasis></para> + </listitem> + </orderedlist></entry> + </row> + + <row> + <entry>dependencies</entry> + + <entry>All the dependencies of the portal container ordered by + loading priority. This field is optional. If this field has a + non empty value, it will be the default list of + dependencies.</entry> + </row> + + <row> + <entry>settings</entry> + + <entry>A <envar>java.util.Map</envar> of internal parameters + that we would like to tie the default portal container. Those + parameters could have any type of value. This field is + optional.</entry> + </row> + + <row> + <entry>externalSettingsPath</entry> + + <entry>The path of the external properties file to load as + default settings to the default portal container. This field + is optional. The external properties files can be either of + type "properties" or of type "xml". The path will be + interpreted as follows:<orderedlist> + <listitem> + <para>The path doesn't contain any prefix of type + "classpath:", "jar:" or "file:", we assume that the file + could be externalized so we apply the following + rules:<orderedlist> + <listitem> + <para>A file exists at + <emphasis>${exo-conf-dir}/portal/${externalSettingsPath}</emphasis>, + we will load this file.</para> + </listitem> + + <listitem> + <para>No file exists at the previous path, we then + assume that the path cans be interpreted by the + <envar>ConfigurationManager</envar>.</para> + </listitem> + </orderedlist></para> + </listitem> + + <listitem> + <para>The path contains a prefix, we then assume that + the path cans be interpreted by the + <envar>ConfigurationManager</envar>.</para> + </listitem> + </orderedlist></entry> + </row> + </tbody> + </tgroup> + </table> + + <para>Internal and external settings are both optional, but if we give + a non empty value for both the application will merge the settings. If + the same setting name exists in both settings, we apply the following + rules:</para> + + <orderedlist> + <listitem> + <para>The value of the external setting is + <emphasis>null</emphasis>, we ignore the value.</para> + </listitem> + + <listitem> + <para>The value of the external setting is not + <emphasis>null</emphasis> and the value of the internal setting is + <emphasis>null</emphasis>, the final value will be the external + setting value that is of type <envar>String</envar>.</para> + </listitem> + + <listitem> + <para>Both values are not <envar>null</envar>, we will have to + convert the external setting value into the target type which is + the type of the internal setting value, thanks to the static + method <emphasis>valueOf(String)</emphasis>, the following + sub-rules are then applied:</para> + + <orderedlist> + <listitem> + <para>The method cannot be found, the final value will be the + external setting value that is of type + <envar>String</envar>.</para> + </listitem> + + <listitem> + <para>The method can be found and the external setting value + is an empty <envar>String</envar>, we ignore the external + setting value.</para> + </listitem> + + <listitem> + <para>The method can be found and the external setting value + is not an empty <envar>String</envar> but the method call + fails, we ignore the external setting value.</para> + </listitem> + + <listitem> + <para>The method can be found and the external setting value + is not an empty <envar>String</envar> and the method call + succeeds, the final value will be the external setting value + that is of type of the internal setting value.</para> + </listitem> + </orderedlist> + </listitem> + </orderedlist> + </section> + + <section> + <title><envar>PortalContainer</envar> settings</title> + + <para>We can inject the value of the portal container settings into + the portal container configuration files thanks to the variables which + name start with "<emphasis>portal.container.</emphasis>", so to get + the value of a setting called "<emphasis>foo</emphasis>" just use the + following syntax <emphasis>${portal.container.foo}</emphasis>. You can + also use internal variables, such as:</para> + + <table> + <title>Definition of the internal variables</title> + + <tgroup cols="2"> + <tbody> + <row> + <entry>portal.container.name</entry> + + <entry>Gives the name of the current portal container.</entry> + </row> + + <row> + <entry>portal.container.rest</entry> + + <entry>Gives the context name of the rest web application of + the current portal container.</entry> + </row> + + <row> + <entry>portal.container.realm</entry> + + <entry>Gives the realm name of the current portal + container.</entry> + </row> + </tbody> + </tgroup> + </table> + + <para>You can find below an example of how to use the + variables:<programlisting>&lt;configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.exoplaform.org/xml/ns/kernel_1_1.xsd http://www.exoplaform.org/xml/ns/kernel_1_1.xsd" + xmlns="http://www.exoplaform.org/xml/ns/kernel_1_1.xsd"&gt; + &lt;component&gt; + &lt;type&gt;org.exoplatform.container.TestPortalContainer$MyComponent&lt;/type&gt; + &lt;init-params&gt; + &lt;!-- The name of the portal container --&gt; + &lt;value-param&gt; + &lt;name&gt;portal&lt;/name&gt; + &lt;value&gt;${portal.container.name}&lt;/value&gt; + &lt;/value-param&gt; + &lt;!-- The name of the rest ServletContext --&gt; + &lt;value-param&gt; + &lt;name&gt;rest&lt;/name&gt; + &lt;value&gt;${portal.container.rest}&lt;/value&gt; + &lt;/value-param&gt; + &lt;!-- The name of the realm --&gt; + &lt;value-param&gt; + &lt;name&gt;realm&lt;/name&gt; + &lt;value&gt;${portal.container.realm}&lt;/value&gt; + &lt;/value-param&gt; + &lt;value-param&gt; + &lt;name&gt;foo&lt;/name&gt; + &lt;value&gt;${portal.container.foo}&lt;/value&gt; + &lt;/value-param&gt; + &lt;value-param&gt; + &lt;name&gt;before foo after&lt;/name&gt; + &lt;value&gt;before ${portal.container.foo} after&lt;/value&gt; + &lt;/value-param&gt; + &lt;/init-params&gt; + &lt;/component&gt; +&lt;/configuration&gt;</programlisting></para> + + <para>In the properties file corresponding to the external settings, + you can reuse variables previously defined (in the external settings + or in the internal settings) to create a new variable. In this case + the prefix "<emphasis>portal.container.</emphasis>" is not needed, see + an example below:<programlisting>my-var1=value 1 +my-var2=value 2 +complex-value=${my-var1}-${my-var2}</programlisting></para> + + <para>In the external and internal settings, you can also use create + variables based on value of System paramaters. The System parameters + can either be defined at launch time or thanks to the + <envar>PropertyConfigurator</envar> (see next section for more + details). See an example below:</para> + + <programlisting>temp-dir=${java.io.tmpdir}${file.separator}my-temp</programlisting> + + <para>However, for the internal settings you can use System parameters + only to define settings of type + <envar>java.lang.String</envar>.</para> + + <para>It cans be also very usefull to define a generic variable in the + settings of the default portal container, the value of this variable + will change according to the current portal container. See below an + example:<programlisting>my-generic-var=value of the portal container "${name}"</programlisting></para> + + <para>If this variable is defined at the default portal container + level, the value of this variable for a portal container called + <emphasis>"foo"</emphasis> will be <emphasis>value of the portal + container "foo"</emphasis>.</para> + </section> + + <section> + <title>Add dynamically settings and/or dependencies to a + <envar>PortalContainer</envar></title> + + <para>It is possible to use <envar>component-plugin</envar> elements + in order to dynamically change a PortalContainerDefinition. In the + example below, we add the dependency <envar>foo</envar> to the default + portal container and to the portal containers called + <envar>foo1</envar> and <envar>foo2</envar>:</para> + + <programlisting>&lt;external-component-plugins&gt; + &lt;!-- The full qualified name of the PortalContainerConfig --&gt; + &lt;target-component&gt;org.exoplatform.container.definition.PortalContainerConfig&lt;/target-component&gt; + &lt;component-plugin&gt; + &lt;!-- The name of the plugin --&gt; + &lt;name&gt;Change PortalContainer Definitions&lt;/name&gt; + &lt;!-- The name of the method to call on the PortalContainerConfig in order to register the changes on the PortalContainerDefinitions --&gt; + &lt;set-method&gt;registerChangePlugin&lt;/set-method&gt; + &lt;!-- The full qualified name of the PortalContainerDefinitionChangePlugin --&gt; + &lt;type&gt;org.exoplatform.container.definition.PortalContainerDefinitionChangePlugin&lt;/type&gt; + &lt;init-params&gt; + &lt;value-param&gt; + &lt;name&gt;apply.default&lt;/name&gt; + &lt;value&gt;true&lt;/value&gt; + &lt;/value-param&gt; + &lt;values-param&gt; + &lt;name&gt;apply.specific&lt;/name&gt; + &lt;value&gt;foo1&lt;/value&gt; + &lt;value&gt;foo2&lt;/value&gt; + &lt;/values-param&gt; + &lt;object-param&gt; + &lt;name&gt;change&lt;/name&gt; + &lt;object type="org.exoplatform.container.definition.PortalContainerDefinitionChange$AddDependencies"&gt; + &lt;!-- The list of name of the dependencies to add --&gt; + &lt;field name="dependencies"&gt; + &lt;collection type="java.util.ArrayList"&gt; + &lt;value&gt; + &lt;string&gt;foo&lt;/string&gt; + &lt;/value&gt; + &lt;/collection&gt; + &lt;/field&gt; + &lt;/object&gt; + &lt;/object-param&gt; + &lt;/init-params&gt; + &lt;/component-plugin&gt; +&lt;/external-component-plugins&gt;</programlisting> + + <table> + <title>Descriptions of the fields of a + <envar>PortalContainerDefinitionChangePlugin</envar></title> + + <tgroup cols="2"> + <tbody> + <row> + <entry>apply.all</entry> + + <entry>Indicates whether the changes have to be applied to all + the portal containers or not. The default value of this field + is <envar>false</envar>. This field is a + <envar>ValueParam</envar> and is not mandatory.</entry> + </row> + + <row> + <entry>apply.default</entry> + + <entry>Indicates whether the changes have to be applied to the + default portal container or not. The default value of this + field is <envar>false</envar>. This field is a + <envar>ValueParam</envar> and is not mandatory.</entry> + </row> + + <row> + <entry>apply.specific</entry> + + <entry>A set of specific portal container names to which we + want to apply the changes. This field is a + <envar>ValuesParam</envar> and is not mandatory.</entry> + </row> + + <row> + <entry><envar>Rest of the expected parameters </envar></entry> + + <entry>The rest of the expected paramaters are + <envar>ObjectParam</envar> of type + <envar>PortalContainerDefinitionChange</envar>. Those + parameters are in fact the list of changes that we want to + apply to one or several portal containers. If the list of + changes is empty, the component plugin will be ignored. The + supported implementations of PortalContainerDefinitionChange + are described later in this section.</entry> + </row> + </tbody> + </tgroup> + </table> + + <para>To identify the portal containers to which the changes have to + be applied, we use the follwing algorithm:</para> + + <orderedlist> + <listitem> + <para>The parameter <envar>apply.all</envar> has been set to + <envar>true</envar>. The corresponding changes will be applied to + all the portal containers. The other parameters will be + ignored.</para> + </listitem> + + <listitem> + <para>The parameter <envar>apply.default</envar> has been set to + <envar>true</envar> and the parameter + <envar>apply.specific</envar> is <envar>null</envar>. The + corresponding changes will be applied to the default portal + container only.</para> + </listitem> + + <listitem> + <para>The parameter <envar>apply.default</envar> has been set to + <envar>true</envar> and the parameter + <envar>apply.specific</envar> is not <envar>null</envar>. The + corresponding changes will be applied to the default portal + container and the given list of specific portal containers.</para> + </listitem> + + <listitem> + <para>The parameter <envar>apply.default</envar> has been set to + <envar>false</envar> or has not been set and the parameter + <envar>apply.specific</envar> is <envar>null</envar>. The + corresponding changes will be applied to the default portal + container only.</para> + </listitem> + + <listitem> + <para>The parameter <envar>apply.default</envar> has been set to + <envar>false</envar> or has not been set and the parameter + <envar>apply.specific</envar> is not <envar>null</envar>. The + corresponding changes will be applied to the given list of + specific portal containers.</para> + </listitem> + </orderedlist> + + <section> + <title>The existing implementations of + <envar>PortalContainerDefinitionChange</envar></title> + + <para>The modifications that can be applied to a + <envar>PortalContainerDefinition</envar> must be a class of type + <envar>PortalContainerDefinitionChange</envar>. The product proposes + out of the box some implementations that we describe in the next sub + sections.</para> + + <section> + <title><envar>AddDependencies</envar></title> + + <para>This modification adds a list of dependencies at the end of + the list of dependencies defined into the + <envar>PortalContainerDefinition</envar>. The full qualified name + is + <emphasis>org.exoplatform.container.definition.PortalContainerDefinitionChange$AddDependencies</emphasis>.</para> + + <table> + <title>Descriptions of the fields of an + <envar>AddDependencies</envar></title> + + <tgroup cols="2"> + <tbody> + <row> + <entry>dependencies</entry> + + <entry>A list of <emphasis>String</emphasis> corresponding + to the list of name of the dependencies to add. If the + value of this field is empty, the change will be + ignored.</entry> + </row> + </tbody> + </tgroup> + </table> + + <para>See an example below, that will add <envar>foo</envar> at + the end of the dependency list of the default portal + container:</para> + + <programlisting>&lt;external-component-plugins&gt; + &lt;!-- The full qualified name of the PortalContainerConfig --&gt; + &lt;target-component&gt;org.exoplatform.container.definition.PortalContainerConfig&lt;/target-component&gt; + &lt;component-plugin&gt; + &lt;!-- The name of the plugin --&gt; + &lt;name&gt;Change PortalContainer Definitions&lt;/name&gt; + &lt;!-- The name of the method to call on the PortalContainerConfig in order to register the changes on the PortalContainerDefinitions --&gt; + &lt;set-method&gt;registerChangePlugin&lt;/set-method&gt; + &lt;!-- The full qualified name of the PortalContainerDefinitionChangePlugin --&gt; + &lt;type&gt;org.exoplatform.container.definition.PortalContainerDefinitionChangePlugin&lt;/type&gt; + &lt;init-params&gt; + &lt;value-param&gt; + &lt;name&gt;apply.default&lt;/name&gt; + &lt;value&gt;true&lt;/value&gt; + &lt;/value-param&gt; + &lt;object-param&gt; + &lt;name&gt;change&lt;/name&gt; + &lt;object type="org.exoplatform.container.definition.PortalContainerDefinitionChange$AddDependencies"&gt; + &lt;!-- The list of name of the dependencies to add --&gt; + &lt;field name="dependencies"&gt; + &lt;collection type="java.util.ArrayList"&gt; + &lt;value&gt; + &lt;string&gt;foo&lt;/string&gt; + &lt;/value&gt; + &lt;/collection&gt; + &lt;/field&gt; + &lt;/object&gt; + &lt;/object-param&gt; + &lt;/init-params&gt; + &lt;/component-plugin&gt; +&lt;/external-component-plugins&gt;</programlisting> + </section> + + <section> + <title><envar>AddDependenciesBefore</envar></title> + + <para>This modification adds a list of dependencies before a given + target dependency defined into the list of dependencies of the + <envar>PortalContainerDefinition</envar>. The full qualified name + is + <emphasis>org.exoplatform.container.definition.PortalContainerDefinitionChange$AddDependenciesBefore</emphasis>.</para> + + <table> + <title>Descriptions of the fields of an + <envar>AddDependenciesBefore</envar></title> + + <tgroup cols="2"> + <tbody> + <row> + <entry>dependencies</entry> + + <entry>A list of <emphasis>String</emphasis> corresponding + to the list of name of the dependencies to add. If the + value of this field is empty, the change will be + ignored.</entry> + </row> + + <row> + <entry>target</entry> + + <entry>The name of the dependency before which we would + like to add the new dependencies. If this field is + <envar>null</envar> or the target dependency cannot be + found in the list of dependencies defined into the + <envar>PortalContainerDefinition</envar>, the new + dependencies will be added in first position to the + list.</entry> + </row> + </tbody> + </tgroup> + </table> + + <para>See an example below, that will add <envar>foo</envar> + before <envar>foo2</envar> in the dependency list of the default + portal container:</para> + + <programlisting>&lt;external-component-plugins&gt; + &lt;!-- The full qualified name of the PortalContainerConfig --&gt; + &lt;target-component&gt;org.exoplatform.container.definition.PortalContainerConfig&lt;/target-component&gt; + &lt;component-plugin&gt; + &lt;!-- The name of the plugin --&gt; + &lt;name&gt;Change PortalContainer Definitions&lt;/name&gt; + &lt;!-- The name of the method to call on the PortalContainerConfig in order to register the changes on the PortalContainerDefinitions --&gt; + &lt;set-method&gt;registerChangePlugin&lt;/set-method&gt; + &lt;!-- The full qualified name of the PortalContainerDefinitionChangePlugin --&gt; + &lt;type&gt;org.exoplatform.container.definition.PortalContainerDefinitionChangePlugin&lt;/type&gt; + &lt;init-params&gt; + &lt;value-param&gt; + &lt;name&gt;apply.default&lt;/name&gt; + &lt;value&gt;true&lt;/value&gt; + &lt;/value-param&gt; + &lt;object-param&gt; + &lt;name&gt;change&lt;/name&gt; + &lt;object type="org.exoplatform.container.definition.PortalContainerDefinitionChange$AddDependenciesBefore"&gt; + &lt;!-- The list of name of the dependencies to add --&gt; + &lt;field name="dependencies"&gt; + &lt;collection type="java.util.ArrayList"&gt; + &lt;value&gt; + &lt;string&gt;foo&lt;/string&gt; + &lt;/value&gt; + &lt;/collection&gt; + &lt;/field&gt; + &lt;!-- The name of the target dependency --&gt; + &lt;field name="target"&gt; + &lt;string&gt;foo2&lt;/string&gt; + &lt;/field&gt; + &lt;/object&gt; + &lt;/object-param&gt; + &lt;/init-params&gt; + &lt;/component-plugin&gt; +&lt;/external-component-plugins&gt;</programlisting> + </section> + + <section> + <title><envar>AddDependenciesAfter</envar></title> + + <para>This modification adds a list of dependencies before a given + target dependency defined into the list of dependencies of the + <envar>PortalContainerDefinition</envar>. The full qualified name + is + <emphasis>org.exoplatform.container.definition.PortalContainerDefinitionChange$AddDependenciesAfter</emphasis>.</para> + + <table> + <title>Descriptions of the fields of an + <envar>AddDependenciesAfter</envar></title> + + <tgroup cols="2"> + <tbody> + <row> + <entry>dependencies</entry> + + <entry>A list of <emphasis>String</emphasis> corresponding + to the list of name of the dependencies to add. If the + value of this field is empty, the change will be + ignored.</entry> + </row> + + <row> + <entry>target</entry> + + <entry>The name of the dependency after which we would + like to add the new dependencies. If this field is + <envar>null</envar> or the target dependency cannot be + found in the list of dependencies defined into the + <envar>PortalContainerDefinition</envar>, the new + dependencies will be added in last position to the + list.</entry> + </row> + </tbody> + </tgroup> + </table> + + <para>See an example below, that will add <envar>foo</envar> after + <envar>foo2</envar> in the dependency list of the default portal + container:</para> + + <programlisting>&lt;external-component-plugins&gt; + &lt;!-- The full qualified name of the PortalContainerConfig --&gt; + &lt;target-component&gt;org.exoplatform.container.definition.PortalContainerConfig&lt;/target-component&gt; + &lt;component-plugin&gt; + &lt;!-- The name of the plugin --&gt; + &lt;name&gt;Change PortalContainer Definitions&lt;/name&gt; + &lt;!-- The name of the method to call on the PortalContainerConfig in order to register the changes on the PortalContainerDefinitions --&gt; + &lt;set-method&gt;registerChangePlugin&lt;/set-method&gt; + &lt;!-- The full qualified name of the PortalContainerDefinitionChangePlugin --&gt; + &lt;type&gt;org.exoplatform.container.definition.PortalContainerDefinitionChangePlugin&lt;/type&gt; + &lt;init-params&gt; + &lt;value-param&gt; + &lt;name&gt;apply.default&lt;/name&gt; + &lt;value&gt;true&lt;/value&gt; + &lt;/value-param&gt; + &lt;object-param&gt; + &lt;name&gt;change&lt;/name&gt; + &lt;object type="org.exoplatform.container.definition.PortalContainerDefinitionChange$AddDependenciesAfter"&gt; + &lt;!-- The list of name of the dependencies to add --&gt; + &lt;field name="dependencies"&gt; + &lt;collection type="java.util.ArrayList"&gt; + &lt;value&gt; + &lt;string&gt;foo&lt;/string&gt; + &lt;/value&gt; + &lt;/collection&gt; + &lt;/field&gt; + &lt;!-- The name of the target dependency --&gt; + &lt;field name="target"&gt; + &lt;string&gt;foo2&lt;/string&gt; + &lt;/field&gt; + &lt;/object&gt; + &lt;/object-param&gt; + &lt;/init-params&gt; + &lt;/component-plugin&gt; +&lt;/external-component-plugins&gt;</programlisting> + </section> + + <section> + <title><envar>AddSettings</envar></title> + + <para>This modification adds new settings to a + <envar>PortalContainerDefinition</envar>. The full qualified name + is + <emphasis>org.exoplatform.container.definition.PortalContainerDefinitionChange$AddSettings</emphasis>.</para> + + <table> + <title>Descriptions of the fields of an + <envar>AddSettings</envar></title> + + <tgroup cols="2"> + <tbody> + <row> + <entry>settings</entry> + + <entry>A map of <emphasis>&lt;String, + Object&gt;</emphasis> corresponding to the settings to + add. If the value of this field is empty, the change will + be ignored.</entry> + </row> + </tbody> + </tgroup> + </table> + + <para>See an example below, that will add the settings + <envar>string</envar> and <envar>stringX</envar> to the settings + of the default portal container:</para> + + <programlisting>&lt;external-component-plugins&gt; + &lt;!-- The full qualified name of the PortalContainerConfig --&gt; + &lt;target-component&gt;org.exoplatform.container.definition.PortalContainerConfig&lt;/target-component&gt; + &lt;component-plugin&gt; + &lt;!-- The name of the plugin --&gt; + &lt;name&gt;Change PortalContainer Definitions&lt;/name&gt; + &lt;!-- The name of the method to call on the PortalContainerConfig in order to register the changes on the PortalContainerDefinitions --&gt; + &lt;set-method&gt;registerChangePlugin&lt;/set-method&gt; + &lt;!-- The full qualified name of the PortalContainerDefinitionChangePlugin --&gt; + &lt;type&gt;org.exoplatform.container.definition.PortalContainerDefinitionChangePlugin&lt;/type&gt; + &lt;init-params&gt; + &lt;value-param&gt; + &lt;name&gt;apply.default&lt;/name&gt; + &lt;value&gt;true&lt;/value&gt; + &lt;/value-param&gt; + &lt;object-param&gt; + &lt;name&gt;change&lt;/name&gt; + &lt;object type="org.exoplatform.container.definition.PortalContainerDefinitionChange$AddSettings"&gt; + &lt;!-- The settings to add to the to the portal containers --&gt; + &lt;field name="settings"&gt; + &lt;map type="java.util.HashMap"&gt; + &lt;entry&gt; + &lt;key&gt; + &lt;string&gt;string&lt;/string&gt; + &lt;/key&gt; + &lt;value&gt; + &lt;string&gt;value1&lt;/string&gt; + &lt;/value&gt; + &lt;/entry&gt; + &lt;entry&gt; + &lt;key&gt; + &lt;string&gt;stringX&lt;/string&gt; + &lt;/key&gt; + &lt;value&gt; + &lt;string&gt;value1&lt;/string&gt; + &lt;/value&gt; + &lt;/entry&gt; + &lt;/map&gt; + &lt;/field&gt; + &lt;/object&gt; + &lt;/object-param&gt; + &lt;/init-params&gt; + &lt;/component-plugin&gt; +&lt;/external-component-plugins&gt;</programlisting> + </section> + </section> + </section> + </section> + </section> + + <section> + <title>System property configuration</title> + + <para>A new property configurator service has been developed for taking + care of configuring system properties from the inline kernel configuration + or from specified property files.</para> + + <para>The services is scoped at the root container level because it is + used by all the services in the different portal containers in the + application runtime.</para> + + <section> + <title>Properties init param</title> + + <para>The properties init param takes a property declared to configure + various properties.</para> + + <programlisting>&lt;component&gt; + &lt;key&gt;PropertyManagerConfigurator&lt;/key&gt; + &lt;type&gt;org.exoplatform.container.PropertyConfigurator&lt;/type&gt; + &lt;init-params&gt; + &lt;properties-param&gt; + &lt;name&gt;properties&lt;/name&gt; + &lt;property name="foo" value="bar"/&gt; + &lt;/properties-param&gt; + &lt;/init-params&gt; +&lt;/component&gt;</programlisting> + </section> + + <section> + <title>Properties URL init param</title> + + <para>The properties URL init param allow to load an external file by + specifying its URL. Both property and XML format are supported, see the + javadoc of the <emphasis><envar>java.util.Properties</envar></emphasis> + class for more information. When a property file is loaded the various + property declarations are loaded in the order in which the properties + are declared sequentially in the file.</para> + + <programlisting>&lt;component&gt; + &lt;key&gt;PropertyManagerConfigurator&lt;/key&gt; + &lt;type&gt;org.exoplatform.container.PropertyConfigurator&lt;/type&gt; + &lt;init-params&gt; + &lt;value-param&gt; + &lt;name&gt;properties.url&lt;/name&gt; + &lt;value&gt;classpath:configuration.properties&lt;/value&gt; + &lt;/value-param&gt; + &lt;/init-params&gt; +&lt;/component&gt;</programlisting> + + <para>In the properties file corresponding to the external properties, + you can reuse variables previously defined to create a new variable. In + this case the prefix "<emphasis>portal.container.</emphasis>" is not + needed, see an example below:<programlisting>my-var1=value 1 +my-var2=value 2 +complex-value=${my-var1}-${my-var2}</programlisting></para> + </section> + + <section> + <title>System Property configuration of the properties URL</title> + + <para>It is possible to replace the properties URL init param by a + system property that overwrites it. The name of that property is + <emphasis>exo.properties.url</emphasis>.</para> + </section> + </section> + + <section> + <title>Runtime configuration profiles</title> + + <para>The kernel configuration is able to handle configuration profiles at + runtime (as opposed to packaging time).</para> + + <section> + <title>Profiles activation</title> + + <para>An active profile list is obtained during the boot of the root + container and is composed of the system property + <emphasis>exo.profiles</emphasis> sliced according the "," delimiter and + also a server specific profile value (tomcat for tomcat, jboss for + jboss, etc...).</para> + + <programlisting># runs GateIn on Tomcat with the profiles tomcat and foo +sh gatein.sh -Dexo.profiles=foo + +# runs GateIn on JBoss with the profiles jboss, foo and bar +sh run.sh -Dexo.profiles=foo,bar</programlisting> + </section> + + <section> + <title>Profiles configuration</title> + + <para>Profiles are configured in the configuration files of the eXo + kernel.</para> + + <section> + <title>Profiles definition</title> + + <para>Profile activation occurs at XML to configuration object + unmarshalling time. It is based on an "profile" attribute that is + present on some of the XML element of the configuration files. To + enable this the kernel configuration schema has been upgraded to + kernel_1_1.xsd. The configuration is based on the following + rules:</para> + + <orderedlist> + <listitem> + <para>Any kernel element with the no <emphasis>profiles</emphasis> + attribute will create a configuration object</para> + </listitem> + + <listitem> + <para>Any kernel element having a <emphasis>profiles</emphasis> + attribute containing at least one of the active profiles will + create a configuration object</para> + </listitem> + + <listitem> + <para>Any kernel element having a <emphasis>profiles</emphasis> + attribute matching none of the active profile will not create a + configuration object</para> + </listitem> + + <listitem> + <para>Resolution of duplicates (such as two components with same + type) is left up to the kernel</para> + </listitem> + </orderedlist> + </section> + + <section> + <title>Profiles capable configuration elements</title> + + <para>A configuration element is <emphasis>profiles</emphasis> capable + when it carries a profiles element.</para> + + <section> + <title>Component element</title> + + <para>The component element declares a component when activated. It + will shadow any element with the same key declared before in the + same configuration file:</para> + + <programlisting>&lt;component&gt; + &lt;key&gt;Component&lt;/key&gt; + &lt;type&gt;Component&lt;/type&gt; +&lt;/component&gt; + +&lt;component profiles="foo"&gt; + &lt;key&gt;Component&lt;/key&gt; + &lt;type&gt;FooComponent&lt;/type&gt; +&lt;/component&gt;</programlisting> + </section> + + <section> + <title>Component plugin element</title> + + <para>The component-plugin element is used to dynamically extend the + configuration of a given component. Thanks to the profiles the + component-plugins could be enabled or disabled:</para> + + <programlisting>&lt;external-component-plugins&gt; + &lt;target-component&gt;Component&lt;/target-component&gt; + &lt;component-plugin profiles="foo"&gt; + &lt;name&gt;foo&lt;/name&gt; + &lt;set-method&gt;addPlugin&lt;/set-method&gt; + &lt;type&gt;type&lt;/type&gt; + &lt;init-params&gt; + &lt;value-param&gt; + &lt;name&gt;param&lt;/name&gt; + &lt;value&gt;empty&lt;/value&gt; + &lt;/value-param&gt; + &lt;/init-params&gt; + &lt;/component-plugin&gt; +&lt;/external-component-plugins&gt;</programlisting> + </section> + + <section> + <title>Import element</title> + + <para>The import element imports a referenced configuration file + when activated:</para> + + <programlisting>&lt;import&gt;empty&lt;/import&gt; +&lt;import profiles="foo"&gt;foo&lt;/import&gt; +&lt;import profiles="bar"&gt;bar&lt;/import&gt;</programlisting> + </section> + + <section> + <title>Init param element</title> + + <para>The init param element configures the parameter argument of + the construction of a component service:</para> + + <programlisting>&lt;component&gt; + &lt;key&gt;Component&lt;/key&gt; + &lt;type&gt;ComponentImpl&lt;/type&gt; + &lt;init-params&gt; + &lt;value-param&gt; + &lt;name&gt;param&lt;/name&gt; + &lt;value&gt;empty&lt;/value&gt; + &lt;/value-param&gt; + &lt;value-param profiles="foo"&gt; + &lt;name&gt;param&lt;/name&gt; + &lt;value&gt;foo&lt;/value&gt; + &lt;/value-param&gt; + &lt;value-param profiles="bar"&gt; + &lt;name&gt;param&lt;/name&gt; + &lt;value&gt;bar&lt;/value&gt; + &lt;/value-param&gt; + &lt;/init-params&gt; +&lt;/component&gt;</programlisting> + </section> + + <section> + <title>Value collection element</title> + + <para>The value collection element configures one of the value of + collection data:</para> + + <programlisting>&lt;object type="org.exoplatform.container.configuration.ConfigParam"&gt; + &lt;field name="role"&gt; + &lt;collection type="java.util.ArrayList"&gt; + &lt;value&gt;&lt;string&gt;manager&lt;/string&gt;&lt;/value&gt; + &lt;value profiles="foo"&gt;&lt;string&gt;foo_manager&lt;/string&gt;&lt;/value&gt; + &lt;value profiles="foo,bar"&gt;&lt;string&gt;foo_bar_manager&lt;/string&gt;&lt;/value&gt; + &lt;/collection&gt; + &lt;/field&gt; +&lt;/object&gt;</programlisting> + </section> + + <section> + <title>Field configuration element</title> + + <para>The field configuration element configures the field of an + object:</para> + + <programlisting>&lt;object-param&gt; + &lt;name&gt;test.configuration&lt;/name&gt; + &lt;object type="org.exoplatform.container.configuration.ConfigParam"&gt; + &lt;field name="role"&gt; + &lt;collection type="java.util.ArrayList"&gt; + &lt;value&gt;&lt;string&gt;manager&lt;/string&gt;&lt;/value&gt; + &lt;/collection&gt; + &lt;/field&gt; + &lt;field name="role" profiles="foo,bar"&gt; + &lt;collection type="java.util.ArrayList"&gt; + &lt;value&gt;&lt;string&gt;foo_bar_manager&lt;/string&gt;&lt;/value&gt; + &lt;/collection&gt; + &lt;/field&gt; + &lt;field name="role" profiles="foo"&gt; + &lt;collection type="java.util.ArrayList"&gt; + &lt;value&gt;&lt;string&gt;foo_manager&lt;/string&gt;&lt;/value&gt; + &lt;/collection&gt; + &lt;/field&gt; + &lt;/object&gt; +&lt;/object-param&gt;</programlisting> + </section> + </section> + </section> + </section> + + <section> + <title>Component request life cycle</title> + + <section> + <title>Component request life cycle contract</title> + + <para>The component request life cycle is an interface that defines a + contract for a component for being involved into a + request:<programlisting>public interface ComponentRequestLifecycle +{ + /** + * Start a request. + * @param container the related container + */ + void startRequest(ExoContainer container); + + /** + * Ends a request. + * @param container the related container + */ + void endRequest(ExoContainer container); +}</programlisting></para> + + <para>The container passed is the container to which the component is + related. This contract is often used to setup a thread local based + context that will be demarcated by a request.</para> + + <para>For instance in the GateIn portal context, a component request + life cycle is triggered for user requests. Another example is the + initial data import in GateIn that demarcates using callbacks made to + that interface.</para> + </section> + + <section> + <title>Request life cycle</title> + + <para>The <envar>RequestLifeCycle</envar> class has several statics + methods that are used to schedule the component request life cycle of + components. Its main responsability is to perform scheduling while + respecting the constraint to execute the request life cycle of a + component only once even if it can be scheduled several times.</para> + + <section> + <title>Scheduling a component request life cycle</title> + + <programlisting>RequestLifeCycle.begin(component); +try +{ + // Do something +} +finally +{ + RequestLifeCycle.end(); +}</programlisting> + </section> + + <section> + <title>Scheduling a container request life cycle</title> + + <para>Scheduling a container triggers the component request life cyle + of all the components that implement the interface + <envar>ComponentRequestLifeCycle</envar>. If one of the component has + already been scheduled before then that component will not be + scheduled again. When the local value is true then the looked + components will be those of the container, when it is false then the + scheduler will also look at the components in the ancestor + containers.<programlisting>RequestLifeCycle.begin(container, local); +try +{ + // Do something +} +finally +{ + RequestLifeCycle.end(); +}</programlisting></para> + </section> + </section> + + <section> + <title>When request life cycle is triggered</title> + + <section> + <title>Portal request life cycle</title> + + <para>Each portal request triggers the life cycle of the associated + portal container.</para> + </section> + + <section> + <title>JMX request Life Cycle</title> + + <para>When a JMX bean is invoked, the request life cycle of the + container to which it belongs it scheduled. Indeed JMX is an entry + point of the system that may need component to have a request life + cycle triggered.</para> + </section> + </section> + </section> +</chapter> Modified: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/services-wiring.xml =================================================================== --- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/services-wiring.xml 2010-08-05 09:16:13 UTC (rev 2880) +++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/services-wiring.xml 2010-08-05 10:25:35 UTC (rev 2881) @@ -43,7 +43,7 @@ important to be able to configure the loaded services per instance. Therefore all the default configuration files located in the service impl jar can be overridden from the portal war. For more information refer to - <link linkend="KernelServiceConfigurationforBeginners">Service + <link linkend="Kernel.ServiceConfigurationforBeginners">Service Configuration for Beginners</link>.</para> </section> @@ -145,7 +145,7 @@ <title>JMX auto wiring</title> <para>For JMX wiring please refer to <link - linkend="KernelJMXMBeanServer">JMX MBean Server</link>.</para> + linkend="Kernel.JMXMBeanServer">JMX MBean Server</link>.</para> </section> <section> Modified: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/understanding-listnerservice.xml =================================================================== --- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/understanding-listnerservice.xml 2010-08-05 09:16:13 UTC (rev 2880) +++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/understanding-listnerservice.xml 2010-08-05 10:25:35 UTC (rev 2881) @@ -10,17 +10,17 @@ <itemizedlist> <listitem> - <para><link linkend="KernelServiceConfigurationforBeginners">Service + <para><link linkend="Kernel.ServiceConfigurationforBeginners">Service Configuration for Beginners</link></para> </listitem> <listitem> - <para><link linkend="KernelServiceConfigurationinDetail">Service + <para><link linkend="Kernel.ServiceConfigurationinDetail">Service Configuration in Detail</link></para> </listitem> <listitem> - <para><link linkend="KernelContainerConfiguration">Container + <para><link linkend="Kernel.ContainerConfiguration">Container Configuration</link></para> </listitem> </itemizedlist>