<?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">
<section id="Kernel.ContainerConfiguration">
  <title>Container Configuration</title>

  <para>GateIn 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> section to understand the basics.</para>

  <section id="Kernel.ContainerConfiguration.ConfigurationNamespace">
    <title>Kernel configuration namespace</title>

    <para>To be effective, the namespace URI
    <uri>http://www.exoplatform.org/xml/ns/kernel_1_3.xsd</uri> must be target
    namespace of the XML configuration file.</para>

    <programlisting language="xml">&lt;configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
               xsi:schemaLocation="http://www.exoplatform.org/xml/ns/kernel_1_3.xsd http://www.exoplatform.org/xml/ns/kernel_1_3.xsd"
               xmlns="http://www.exoplatform.org/xml/ns/kernel_1_3.xsd"&gt;


   ...
&lt;/configuration&gt;</programlisting>

    <note>
      <para>Any values in the configuration files can be created thanks to
      variables since the eXo kernel resolves them, for example the following
      configuration will be well interpreted:</para>

      <programlisting language="xml">&lt;configuration
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://www.exoplatform.org/xml/ns/kernel_1_3.xsd http://www.exoplatform.org/xml/ns/kernel_1_3.xsd"
   xmlns="http://www.exoplatform.org/xml/ns/kernel_1_3.xsd"&gt;

  &lt;import&gt;${db.configuration.path}/db.xml&lt;/import&gt;
  &lt;import&gt;${java.io.tmpdir}/bindfile.xml&lt;/import&gt;
  &lt;import&gt;simple.xml&lt;/import&gt;

&lt;/configuration&gt;</programlisting>

      <para>The variables that are supported, are System properties and
      variables that are specific to your portal container, see next sections
      for more details.</para>
    </note>
  </section>

  <section id="Kernel.ContainerConfiguration.UnderstandingHowConfigurationFilesLoaded">
    <title>Understanding how configuration files are loaded</title>

    <para>GateIn 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 of 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 id="Kernel.ContainerConfiguration.UnderstandingHowConfigurationFilesLoaded.ConfigurationRetrieval">
      <title>Configuration Retrieval</title>

      <para>The container performs the following steps to make eXo Container
      configuration retrieval, depending on the container type.</para>

      <section id="Kernel.ContainerConfiguration.UnderstandingHowConfigurationFilesLoaded.ConfigurationRetrieval.OrderForPortalContainer">
        <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 at
            <emphasis>/conf/configuration.xml</emphasis></para>
          </listitem>

          <listitem>
            <para>Configurations from EAR and WAR files at
            <emphasis>/META-INF/exo-conf/configuration.xml</emphasis>. In case
            of an EAR, if the configuration could be found inside the META-INF
            folder, it will use only this file and will ignore configuration
            files in the META-INF folder of the web applications included in
            the EAR file.</para>
          </listitem>

          <listitem>
            <para>External <envar>RootContainer</envar> configuration can 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>at
            /conf/portal/configuration.xml</emphasis></para>
          </listitem>

          <listitem>
            <para>Web applications configurations from WAR files at
            <emphasis>/WEB-INF/conf/configuration.xml</emphasis></para>
          </listitem>

          <listitem>
            <para>External configuration for services of named portal can be
            found at
            <emphasis>$AS_HOME/exo-conf/portal/$PORTAL_NAME/configuration.xml</emphasis></para>
          </listitem>
        </orderedlist>
      </section>

      <section id="Kernel.ContainerConfiguration.UnderstandingHowConfigurationFilesLoaded.ConfigurationRetrieval.StandaloneContainer">
        <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>StandaloneContainer</envar>
            configurations from JAR files <emphasis>at
            /conf/configuration.xml</emphasis></para>
          </listitem>

          <listitem>
            <para>Services default <envar>StandaloneContainer</envar>
            configurations from JAR files at
            <emphasis>/conf/portal/configuration.xml</emphasis></para>
          </listitem>

          <listitem>
            <para>Web applications configurations from WAR files at
            <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:</para>

                <programlisting language="java">// add configuration to the default services configurations from JARs/WARs
StandaloneContainer.addConfigurationURL(containerConf);</programlisting>

                <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 id="Kernel.ContainerConfiguration.UnderstandingHowConfigurationFilesLoaded.ConfigurationRetrieval.GeneralNotes">
        <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. The application server
          home is:</para>

          <itemizedlist>
            <listitem>
              <para>For <envar>Jonas</envar>, the value of the variable
              <emphasis>${jonas.base}.</emphasis></para>
            </listitem>

            <listitem>
              <para>For <envar>Jetty</envar>, the value of the variable
              <emphasis>${jetty.home}.</emphasis></para>
            </listitem>

            <listitem>
              <para>For <envar>Websphere</envar>, the value of the variable
              <emphasis>${was.install.root}.</emphasis></para>
            </listitem>

            <listitem>
              <para>For <envar>Weblogic</envar>, the value of the variable
              <emphasis>${wls.home}</emphasis>.</para>
            </listitem>

            <listitem>
              <para>For <envar>Glassfish</envar>, the value of the variable
              <emphasis>${com.sun.aas.instanceRoot}</emphasis>.</para>
            </listitem>

            <listitem>
              <para>For <envar>Tomcat</envar>, the value of the variable
              <emphasis>${catalina.home}</emphasis>.</para>
            </listitem>

            <listitem>
              <para>For <envar>JBoss AS</envar>, the value of the variable
              <emphasis>${jboss.server.config.url}</emphasis> or
              <emphasis>${jboss.server.config.dir}</emphasis> if the exo-conf
              directory can be found there otherwise it will be the value of
              the variable <emphasis>${jboss.home.dir}</emphasis>.</para>
            </listitem>
          </itemizedlist>
        </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 do not 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>. Warning even if we
          modify the configuration folder, it will remain "exo-conf" for the
          files that we retrieve from the META-INF folder. This affects only
          the externalized configuration files.</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>

        <note>
          <para>To be able to retrieve the configuration files inside the EAR
          and WAR files, the kernel does a lookup inside the standard folders
          where we deploy the archives. If for some reasons, you would need to
          redefine the list of folders where the archives are deployed, you
          can use the System property <emphasis>exo.archive.dirs</emphasis>
          and set it to a comma separated list of paths relative to the
          <emphasis>$AS_HOME</emphasis>.</para>
        </note>

        <warning>
          <para>The EAR and WAR files from which the kernel gets the
          configuration files for the RootContainer, are found thanks to a
          lookup inside the standard deployment folders but so far those
          folders are only properly defined in case of JBoss AS, Tomcat and
          Jetty. For other application servers, you will need to use the
          System property described in the previous note.</para>
        </warning>

        <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 id="Kernel.ContainerConfiguration.UnderstandingHowConfigurationFilesLoaded.ConfigurationRetrieval.EffectiveConfigurationAtRuntime">
        <title>Getting 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 id="Kernel.ContainerConfiguration.UnderstandingHowConfigurationFilesLoaded.AdvancedConceptsForPortalContainers">
      <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 id="Kernel.ContainerConfiguration.UnderstandingHowConfigurationFilesLoaded.AdvancedConceptsForPortalContainers.AddNewConfigurationFilesFromWARFile">
        <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 language="xml">&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 id="Kernel.ContainerConfiguration.UnderstandingHowConfigurationFilesLoaded.AdvancedConceptsForPortalContainers.CreatingPortalContainersFromWARFile">
        <title>Creating 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 id="Kernel.ContainerConfiguration.UnderstandingHowConfigurationFilesLoaded.AdvancedConceptsForPortalContainers.DefiningPortalContainerWithDependenciesAndSettings">
        <title>Defining 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, the 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 an example below:</para>

        <programlisting language="xml">  &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;!-- Indicates whether the unregistered webapps have to be ignored --&gt;
     &lt;value-param&gt;
        &lt;name&gt;ignore.unregistered.webapp&lt;/name&gt;
        &lt;value&gt;true&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>ignore.unregistered.webapp (*)</entry>

                <entry>Indicates whether the unregistered webapps have to be
                ignored. If a webapp has not been registered as a dependency
                of any portal container, the application will use the value of
                this parameter to know what to do:<itemizedlist>
                    <listitem>
                      <para>If it is set to <emphasis>false</emphasis>, this
                      webapp will be considered by default as a dependency of
                      all the portal containers.</para>
                    </listitem>

                    <listitem>
                      <para>If it is set to <emphasis>true</emphasis>, this
                      webapp won't be considered by default as a dependency of
                      any portal container, it will be simply ignored.</para>
                    </listitem>
                  </itemizedlist>This field is optional and by default this
                parameter is set to <emphasis>false</emphasis>.</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>

        <note>
          <para>All the value of the parameters marked with a (*) can be
          defined thanks to System properties like any values in configuration
          files but also thanks to variables loaded by the
          <emphasis>PropertyConfigurator</emphasis>. For example in GateIn by
          default, it would be all the variables defined in the file
          <emphasis>configuration.properties</emphasis>.</para>
        </note>

        <para>A new <envar>PortalContainerDefinition</envar> can be defined at
        the <envar>RootContainer</envar> level thanks to an external plugin,
        see an example below:</para>

        <programlisting language="xml">  &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>

        <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 be
                defined 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 be defined 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 be defined 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 can
                            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:", "ar:", 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>If 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>If 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>If 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>If 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:", "ar:" 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>

        <note>
          <para>All the value of the parameters marked with a (*) can be
          defined thanks to System properties like any values in configuration
          files but also thanks to variables loaded by the
          <emphasis>PropertyConfigurator</emphasis>. For example in GateIn by
          default, it would be all the variables defined in the file
          <emphasis>configuration.properties</emphasis>.</para>
        </note>

        <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 id="Kernel.ContainerConfiguration.UnderstandingHowConfigurationFilesLoaded.AdvancedConceptsForPortalContainers.PortalContainerSettings">
        <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:</para>

        <programlisting language="xml">&lt;configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.exoplatform.org/xml/ns/kernel_1_3.xsd http://www.exoplatform.org/xml/ns/kernel_1_3.xsd"
  xmlns="http://www.exoplatform.org/xml/ns/kernel_1_3.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>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 id="Kernel.ContainerConfiguration.UnderstandingHowConfigurationFilesLoaded.AdvancedConceptsForPortalContainers.AddingDynamicallySettingsDependenciesToPortalContainer">
        <title>Adding 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 language="xml">&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>

        <note>
          <para>All the value of the parameters marked with a (*) can be
          defined thanks to System properties like any values in configuration
          files but also thanks to variables loaded by the
          <emphasis>PropertyConfigurator</emphasis>. For example in GateIn by
          default, it would be all the variables defined in the file
          <emphasis>configuration.properties</emphasis>.</para>
        </note>

        <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 id="Kernel.ContainerConfiguration.UnderstandingHowConfigurationFilesLoaded.AdvancedConceptsForPortalContainers.AddingDynamicallySettingsDependenciesToPortalContainer.PortalContainerDefinitionChange">
          <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 id="Kernel.ContainerConfiguration.UnderstandingHowConfigurationFilesLoaded.AdvancedConceptsForPortalContainers.AddingDynamicallySettingsDependenciesToPortalContainer.PortalContainerDefinitionChange.AddDependencies">
            <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 language="xml">&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 id="Kernel.ContainerConfiguration.UnderstandingHowConfigurationFilesLoaded.AdvancedConceptsForPortalContainers.AddingDynamicallySettingsDependenciesToPortalContainer.PortalContainerDefinitionChange.AddDependenciesBefore">
            <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 language="xml">&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 id="Kernel.ContainerConfiguration.UnderstandingHowConfigurationFilesLoaded.AdvancedConceptsForPortalContainers.AddingDynamicallySettingsDependenciesToPortalContainer.PortalContainerDefinitionChange.AddDependenciesAfter">
            <title><envar>AddDependenciesAfter</envar></title>

            <para>This modification adds a list of dependencies after 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 language="xml">&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 id="Kernel.ContainerConfiguration.UnderstandingHowConfigurationFilesLoaded.AdvancedConceptsForPortalContainers.AddingDynamicallySettingsDependenciesToPortalContainer.PortalContainerDefinitionChange.AddSettings">
            <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 language="xml">&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 id="Kernel.ContainerConfiguration.UnderstandingHowConfigurationFilesLoaded.AdvancedConceptsForPortalContainers.GetListDependencies">
        <title>How to get the actual list of dependencies?</title>

        <para>When you have a complex project with a lot of extensions, it
        could be interesting to know the actual list of dependencies ordered
        by priority. You can get this list at server startup by simply adding
        the System property
        <emphasis>org.exoplatform.container.configuration.debug</emphasis> to
        your launch command. You will then get an info message in your log
        file of the next type:</para>

        <para><programlisting>The dependencies ordered by priority of the portal container 'portal' are: portal, dashboard, exoadmin, eXoGadgets, eXoGadgetServer, rest, web</programlisting></para>
      </section>

      <section id="Kernel.ContainerConfiguration.UnderstandingHowConfigurationFilesLoaded.AdvancedConceptsForPortalContainers.DisableDynamicallyPortalContainer">
        <title>Disable dynamically a portal container</title>

        <para>It is possible to use <envar>component-plugin</envar> elements
        in order to dynamically disable one or several portal containers. In
        the example below, we disable the portal container named
        <envar>foo</envar>:</para>

        <programlisting language="xml">&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;Disable a PortalContainer&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;registerDisablePlugin&lt;/set-method&gt;
    &lt;!-- The full qualified name of the PortalContainerDefinitionDisablePlugin --&gt;
    &lt;type&gt;org.exoplatform.container.definition.PortalContainerDefinitionDisablePlugin&lt;/type&gt;
    &lt;init-params&gt;
      &lt;!-- The list of the name of the portal containers to disable --&gt;
      &lt;values-param&gt;
        &lt;name&gt;names&lt;/name&gt;
        &lt;value&gt;foo&lt;/value&gt;
      &lt;/values-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>PortalContainerDefinitionDisablePlugin</envar></title>

          <tgroup cols="2">
            <tbody>
              <row>
                <entry>names (*)</entry>

                <entry>The list of the name of the portal containers to
                disable.</entry>
              </row>
            </tbody>
          </tgroup>
        </table>

        <note>
          <para>All the value of the parameters marked with a (*) can be
          defined thanks to System properties like any values in configuration
          files but also thanks to variables loaded by the
          <emphasis>PropertyConfigurator</emphasis>. For example in GateIn by
          default, it would be all the variables defined in the file
          <emphasis>configuration.properties</emphasis>.</para>
        </note>

        <para>To prevent any accesses to a web application corresponding to
        <envar>PortalContainer</envar> that has been disabled, you need to
        make sure that the following Http Filter (or a sub class of it) has
        been added to your web.xml in first position as below:</para>

        <programlisting language="xml">&lt;filter&gt;
  &lt;filter-name&gt;PortalContainerFilter&lt;/filter-name&gt;
  &lt;filter-class&gt;org.exoplatform.container.web.PortalContainerFilter&lt;/filter-class&gt;
&lt;/filter&gt;  

&lt;filter-mapping&gt;
  &lt;filter-name&gt;PortalContainerFilter&lt;/filter-name&gt;
  &lt;url-pattern&gt;/*&lt;/url-pattern&gt;
&lt;/filter-mapping&gt;</programlisting>

        <note>
          <para>It is only possible to disable a portal container when at
          least one PortalContainerDefinition has been registered.</para>
        </note>
      </section>
    </section>
  </section>

  <section id="Kernel.ContainerConfiguration.HotReloading">
    <title>eXo Container hot reloading</title>

    <para>In developing mode (that you can enable by setting the system
    property <emphasis>exo.product.developing</emphasis> to
    <emphasis>true</emphasis>) when you are in portal mode, it is possible to
    hot reload all the eXo containers, one given portal container or a set of
    portal containers.</para>

    <section id="Kernel.ContainerConfiguration.ManualHotReloading">
      <title>Manual hot reloading</title>

      <para>You can manually hot reload your eXo containers using the JMX
      console and accessing to the MBean
      <emphasis>exo:container=root</emphasis>. This MBean provides 2
      operations related to the hot reloading which are:</para>

      <itemizedlist>
        <listitem>
          <para><emphasis>reload()</emphasis>: This method allows to reload
          all the containers (RootContainer included)</para>
        </listitem>

        <listitem>
          <para><emphasis>reload(String portalContainerName)</emphasis>: This
          method allows to reload only one given portal container</para>
        </listitem>
      </itemizedlist>
    </section>

    <section id="Kernel.ContainerConfiguration.AutoHotReloading">
      <title>Automatic hot reloading</title>

      <para>In developing mode if for some reason a web application is
      redeployed, the eXo kernel will detect it and if this webapp has been
      defined as <emphasis>PortalContainerConfigOwner</emphasis> which means
      that you defined the listener
      <emphasis>org.exoplatform.container.web.PortalContainerConfigOwner</emphasis>
      in the web.xml of this webapp, it will first check if the configuration
      of the RootContainer has changed if so it will automatically reload
      everything otherwise it will reload only the affected portal
      containers.</para>
    </section>
  </section>

  <section id="Kernel.ContainerConfiguration.SystemPropertyConfiguration">
    <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 id="Kernel.ContainerConfiguration.SystemPropertyConfiguration.PropertiesInitParam">
      <title>Properties init param</title>

      <para>The properties init param takes a property declared to configure
      various properties.</para>

      <programlisting language="xml">&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 id="Kernel.ContainerConfiguration.SystemPropertyConfiguration.PropertiesURLInitParam">
      <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 language="xml">&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 before defining 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 id="Kernel.ContainerConfiguration.SystemPropertyConfiguration.SystemPropertyConfigurationOfPropertiesURL">
      <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 id="Kernel.ContainerConfiguration.VariableSyntaxes">
    <title>Variable Syntaxes</title>

    <para>All the variables that we described in the previous sections can be
    defined thanks to 2 possible syntaxes which are
    <emphasis>${variable-name}</emphasis> or
    <emphasis>${variable-name:default-value}</emphasis>. The first syntax
    doesn't define any default value so if the variable has not be set the
    value will be <emphasis>${variable-name}</emphasis> to indicate that it
    could not be resolved. The second syntax allows you to define the default
    value after the semi colon so if the variable has not be set the value
    will be the given default value.</para>
  </section>

  <section id="Kernel.ContainerConfiguration.RuntimeConfigurationProfiles">
    <title>Runtime configuration profiles</title>

    <para>The kernel configuration is able to handle configuration profiles at
    runtime (as opposed to packaging time).</para>

    <section id="Kernel.ContainerConfiguration.RuntimeConfigurationProfiles.ProfilesActivation">
      <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 id="Kernel.ContainerConfiguration.RuntimeConfigurationProfiles.ProfilesConfiguration">
      <title>Profiles configuration</title>

      <para>Profiles are configured in the configuration files of the eXo
      kernel.</para>

      <section id="Kernel.ContainerConfiguration.RuntimeConfigurationProfiles.ProfilesConfiguration.ProfilesDefinition">
        <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_3.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 id="Kernel.ContainerConfiguration.RuntimeConfigurationProfiles.ProfilesConfiguration.ProfilesCapableConfigurationElements">
        <title>Profiles capable configuration elements</title>

        <para>A configuration element is <emphasis>profiles</emphasis> capable
        when it carries a profiles element.</para>

        <section id="Kernel.ContainerConfiguration.RuntimeConfigurationProfiles.ProfilesConfiguration.ProfilesCapableConfigurationElements.ComponentElement">
          <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 language="xml">&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 id="Kernel.ContainerConfiguration.RuntimeConfigurationProfiles.ProfilesConfiguration.ProfilesCapableConfigurationElements.ComponentPluginElement">
          <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 language="xml">&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 id="Kernel.ContainerConfiguration.RuntimeConfigurationProfiles.ProfilesConfiguration.ProfilesCapableConfigurationElements.ImportElement">
          <title>Import element</title>

          <para>The import element imports a referenced configuration file
          when activated:</para>

          <programlisting language="xml">&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 id="Kernel.ContainerConfiguration.RuntimeConfigurationProfiles.ProfilesConfiguration.ProfilesCapableConfigurationElements.InitParamElement">
          <title>Init param element</title>

          <para>The init param element configures the parameter argument of
          the construction of a component service:</para>

          <programlisting language="xml">&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 id="Kernel.ContainerConfiguration.RuntimeConfigurationProfiles.ProfilesConfiguration.ProfilesCapableConfigurationElements.ValueCollectionElement">
          <title>Value collection element</title>

          <para>The value collection element configures one of the value of
          collection data:</para>

          <programlisting language="xml">&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 id="Kernel.ContainerConfiguration.RuntimeConfigurationProfiles.ProfilesConfiguration.ProfilesCapableConfigurationElements.FieldConfigurationElement">
          <title>Field configuration element</title>

          <para>The field configuration element configures the field of an
          object:</para>

          <programlisting language="xml">&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 id="Kernel.ContainerConfiguration.RuntimeConfigurationProfiles.ProfilesConfiguration.ProfilesCapableConfigurationElements.ContainerLifecyclePluginConfigurationElement">
          <title>Container lifecycle plugin configuration element</title>

          <para>The container lifecycle plugin is used to trigger an action on
          container init/start/stop/destroy. Please note that profiles for
          this element are available starting from kernel_1_3.xsd.</para>

          <programlisting language="xml">&lt;container-lifecycle-plugin profiles="all,default,social"&gt;
  &lt;type&gt;org.exoplatform.container.monitor.jvm.AddJVMComponentsToRootContainer&lt;/type&gt;
&lt;/container-lifecycle-plugin&gt;</programlisting>
        </section>

        <section id="Kernel.ContainerConfiguration.RuntimeConfigurationProfiles.ProfilesConfiguration.ProfilesCapableConfigurationElements.ExternalComponentPluginsConfigurationElement">
          <title>External component plugins configuration element</title>

          <para>The external component plugins is used to dynamically add
          plugins to a component that has been configured in another
          configuration file. Please note that profiles for this element are
          available starting from kernel_1_3.xsd.</para>

          <programlisting language="xml">&lt;external-component-plugins profiles="all,default,social"&gt;
  &lt;target-component&gt;org.exoplatform.services.jcr.RepositoryService&lt;/target-component&gt;
  &lt;component-plugin&gt;
    &lt;name&gt;add.namespaces&lt;/name&gt;
    &lt;set-method&gt;addPlugin&lt;/set-method&gt;
    &lt;type&gt;org.exoplatform.services.jcr.impl.AddNamespacesPlugin&lt;/type&gt;
    &lt;init-params&gt;
      &lt;properties-param&gt;
        &lt;name&gt;namespaces&lt;/name&gt;
        &lt;property name="plf" value="http://www.exoplatform.org/jcr/plf/1.0/" /&gt;
      &lt;/properties-param&gt;
    &lt;/init-params&gt;
  &lt;/component-plugin&gt;
  &lt;component-plugin&gt;
    &lt;name&gt;add.space.access.nodeType&lt;/name&gt;
    &lt;set-method&gt;addPlugin&lt;/set-method&gt;
    &lt;type&gt;org.exoplatform.services.jcr.impl.AddNodeTypePlugin&lt;/type&gt;
    &lt;init-params&gt;
      &lt;values-param&gt;
        &lt;name&gt;autoCreatedInNewRepository&lt;/name&gt;
        &lt;description&gt;Node types configuration file&lt;/description&gt;
        &lt;value&gt;jar:/conf/portal/space-access-chromattic-nodetypes.xml&lt;/value&gt;
      &lt;/values-param&gt;
    &lt;/init-params&gt;
  &lt;/component-plugin&gt;
&lt;/external-component-plugins&gt;</programlisting>
        </section>

        <section id="Kernel.ContainerConfiguration.RuntimeConfigurationProfiles.ProfilesConfiguration.ProfilesCapableConfigurationElements.RemoveConfigurationElement">
          <title>Remove configuration element</title>

          <para>The remove configuration element is used when we want to
          unregister a component that has been defined in another
          configuration file. Please note that profiles for this element are
          available starting from kernel_1_3.xsd.</para>

          <programlisting language="xml">&lt;remove-configuration profiles="all,default,social"&gt;org.exoplatform.services.scheduler.JobSchedulerService&lt;/remove-configuration&gt;</programlisting>
        </section>
      </section>
    </section>
  </section>

  <section id="Kernel.ContainerConfiguration.ComponentRequestLifecycle">
    <title>Component request life cycle</title>

    <section id="Kernel.ContainerConfiguration.ComponentRequestLifecycle.ComponentRequestLifeCycleContract">
      <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:</para>

      <programlisting language="java">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>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 id="Kernel.ContainerConfiguration.ComponentRequestLifecycle.RequestLifeCycle">
      <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 id="Kernel.ContainerConfiguration.ComponentRequestLifecycle.RequestLifeCycle.SchedulingComponentRequestLifeCycle">
        <title>Scheduling a component request life cycle</title>

        <programlisting language="java">RequestLifeCycle.begin(component);
try
{
   // Do something
}
finally
{
   RequestLifeCycle.end();
}</programlisting>
      </section>

      <section id="Kernel.ContainerConfiguration.ComponentRequestLifecycle.RequestLifeCycle.SchedulingContainerRequestLifeCycle">
        <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 and 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.</para>

        <programlisting language="java">RequestLifeCycle.begin(container, local);
try
{
   // Do something
}
finally
{
   RequestLifeCycle.end();
}</programlisting>
      </section>
    </section>

    <section id="Kernel.ContainerConfiguration.ComponentRequestLifecycle.RequestLifeCycleTriggered">
      <title>When request life cycle is triggered</title>

      <section id="Kernel.ContainerConfiguration.ComponentRequestLifecycle.RequestLifeCycleTriggered.PortalRequestLifeCycle">
        <title>Portal request life cycle</title>

        <para>Each portal request triggers the life cycle of the associated
        portal container.</para>
      </section>

      <section id="Kernel.ContainerConfiguration.ComponentRequestLifecycle.RequestLifeCycleTriggered.JMXRequestLifeCycle">
        <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>

  <section id="Kernel.ContainerConfiguration.ThreadContextHolder">
    <title>Thread Context Holder</title>

    <section id="Kernel.ContainerConfiguration.ThreadContextHolder.ThreadContextHolderContract">
      <title>Thread Context Holder contract</title>

      <para>A thread context holder defines a component that holds variables
      of type <emphasis>ThreadLocal</emphasis> whose value is required by the
      component to work normally and cannot be recovered. This component is
      mainly used when we want to do a task asynchronously, in that case to
      ensure that the task will be executed in the same conditions as if it
      would be executed synchronously we need to transfer the thread context
      from the original thread to the executor thread.</para>

      <programlisting language="java">public interface ThreadContextHolder
{
   /**
    * Gives the value corresponding to the context of the thread
    * @return a new instance of {@link ThreadContext} if there are some
    * valuable {@link ThreadLocal} variables to share otherwise &lt;code&gt;null&lt;/code&gt;
    * is expected
    */
   ThreadContext getThreadContext();
}</programlisting>

      <note>
        <para>This interface must be used with caution, only the most
        important components that have <emphasis>ThreadLocal</emphasis>
        variables whose value cannot be recovered should implement this
        interface.</para>
      </note>
    </section>

    <section id="Kernel.ContainerConfiguration.ThreadContextHolder.ThreadContextHandler">
      <title>Thread Context Handler</title>

      <para>To be able to transfer the values of all the
      <emphasis>ThreadLocal</emphasis> variables (provided thanks to a
      ThreadContext instance) of all the registered components of type
      <emphasis>ThreadContextHolder</emphasis>, you can simply use a thread
      context handler as below:</para>

      <programlisting language="java">////////////////////////////////////////////////////////
// Steps to be done in the context of the initial thread
////////////////////////////////////////////////////////

// Create a new instance of ThreadContextHandler for a given ExoContainer
ThreadContextHandler handler = new ThreadContextHandler(container);
// Stores into memory the current values of all the Thread Local variables
// of all the registered ThreadContextHolder of the eXo container.
handler.store();

...
////////////////////////////////////////////////////////
// Steps to be done in the context of the executor thread
////////////////////////////////////////////////////////
try {
  // Pushes values stored into memory into all the Thread Local variables
  // of all the registered ThreadContextHolder of the eXo Container
  handler.push();
  ...
} finally {
  // Restores all the Thread Local variables of all the registered ThreadContextHolder
  // of the eXo Container
  handler.restore();
}</programlisting>
    </section>
  </section>
</section>
