<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<section id="Kernel.ServiceConfigurationforBeginners">
  <title>Service Configuration for Beginners</title>

  <para>This section provides you the basic knowledge about modes, services
  and containers. You will find out where the service configuration files
  should be placed, and you will also see the overriding mechanism of
  configurations.</para>

  <para>Finally, you will understand how the container creates the services
  one after the other and what <emphasis>Inversion of Control</emphasis>
  really means.</para>

  <para><emphasis role="bold">Related documents</emphasis></para>

  <itemizedlist>
    <listitem>
      <para><link linkend="Kernel.ServiceConfigurationinDetail">Service
      Configuration in Detail</link></para>
    </listitem>

    <listitem>
      <para><link endterm="KernelServicesWiring.Title"
      linkend="Kernel.ServicesWiring">Services Wiring</link></para>
    </listitem>

    <listitem>
      <para><link linkend="Kernel.ContainerConfiguration">Container
      Configuration</link></para>
    </listitem>
  </itemizedlist>

  <section id="Kernel.ServiceConfigurationforBeginners.Requirements">
    <title>Requirements</title>

    <para>By reading this article you are already glancing at the heart of eXo
    Kernel.</para>

    <para>Even you will read in this article to open the directory
    "exo-tomcat", you may have installed GateIn on any application server,
    just replace "exo-tomcat" by your folder name.</para>

    <note>
      <para>If you only installed Gatein or eXo Platform, the folder paths are
      a slightly different. You wil need to replace exo-tomcat with your
      tomcat home directory.</para>
    </note>
  </section>

  <section id="Kernel.ServiceConfigurationforBeginners.Services">
    <title>Services</title>

    <para>Nearly everything could be considered a service! To get a better
    idea, let's look into the <emphasis>exo-tomcat/lib</emphasis> folder where
    you find all deployed jar files.</para>

    <mediaobject>
      <imageobject>
        <imagedata fileref="images/TomcatLibFolder.png" />
      </imageobject>
    </mediaobject>

    <para>For example you find services for databases, caching, ldap and
    ftp:</para>

    <itemizedlist>
      <listitem>
        <para>exo.core.component.database-2.1.3.jar</para>
      </listitem>

      <listitem>
        <para>exo.kernel.component.cache-2.0.5.jar</para>
      </listitem>

      <listitem>
        <para>exo.core.component.organization.ldap-2.1.3.jar</para>
      </listitem>

      <listitem>
        <para>exo.jcr.component.ftp-1.10.1.jar</para>
      </listitem>
    </itemizedlist>

    <para>Of course, there are many more services, in fact a lot of these jar
    files are services. To find out you have to open the jar file and then
    look into its <emphasis>/conf</emphasis> or
    <emphasis>/conf/portal</emphasis> directory. Only if there is a file named
    <emphasis>configuration.xml</emphasis>, you are sure to have found a
    service.</para>

    <note>
      <para>Why are there 2 different places to look for the
      configuration.xml? Because the <emphasis>/conf</emphasis> directory is
      used by the <classname>RootContainer</classname> and the
      /<emphasis>conf/portal</emphasis> directory is used by the
      <classname>PortalContainer</classname>. Later you will see more details
      about these containers.</para>
    </note>

    <para><emphasis role="bold">Interface - Implementation</emphasis> It's
    important to get the idea that you separate the interface and
    implementation for a service. That is a good concept to reduce
    dependencies on specific implementations. This concept is well known for
    JDBC. If you use standard JDBC (=interface), you can connect any database
    (=implementation) to your application. In a similar way any service in eXo
    is defined by a java interface and may have many different
    implementations. The service implementation is then
    <emphasis>injected</emphasis> by a <emphasis>container</emphasis> into the
    application.</para>

    <para><emphasis role="bold">Singleton</emphasis> Each service has to be
    implemented as a <ulink
    url="http://en.wikipedia.org/wiki/Singleton_pattern">singleton</ulink>,
    which means that each service is created only once - in one single
    instance.</para>

    <para><emphasis role="bold">Service = Component</emphasis> You always read
    about services, and you imagine a service as a large application which
    does big things, but that's not true, a service can be just a little
    <emphasis>component</emphasis> that reads or transforms a document,
    therefore the term component is often used instead of service - so bear in
    mind: <emphasis>a service and a component can safely be considered to be
    the same thing</emphasis>.</para>
  </section>

  <section id="Kernel.ServiceConfigurationforBeginners.ConfigurationFile">
    <title>Configuration File</title>

    <para>The jar file of a service should contain a default configuration,
    you find this configuration in the configuration.xml file which comes with
    the jar. A configuration file can specify several services, as well as
    there can be several services in one jar file.</para>

    <para>For example open the
    <package>exo.kernel.component.cache-2.0.5.jar</package> file and inside
    this jar open /conf/portal/configuration.xml. You will see:</para>

    <programlisting language="xml"> 
&lt;component&gt;
&lt;key&gt;org.exoplatform.services.cache.CacheService&lt;/key&gt; 
&lt;type&gt;org.exoplatform.services.cache.impl.CacheServiceImpl&lt;/type&gt; 
...</programlisting>

    <para>Here you will note that a service is specified between the
    <parameter>&lt;component&gt;</parameter> tags. Each service has got a key,
    which defines the kind of service. As you imagine the content of the
    <parameter>&lt;key&gt;</parameter> tag matches the <emphasis>qualified
    java interface name</emphasis>
    (<classname>org.exoplatform.services.cache.CacheService</classname>) of
    the service. The specific implementation class of the
    <classname>CacheService</classname> is defined in the
    <parameter>&lt;type&gt;</parameter> tag.</para>

    <para><emphasis role="bold">Parameters</emphasis> You have already opened
    some configuration files and seen that there are more than just
    <parameter>&lt;key&gt;</parameter> and <parameter>&lt;type&gt;</parameter>
    tags. You can provide your service with init parameters. The parameters
    can be simple parameters, properties, or object-params. There are also
    <emphasis>plugins</emphasis> and they are special because the container
    calls the setters of your service in order to <emphasis>inject</emphasis>
    your plugin in your service (called <emphasis>setter injection</emphasis>)
    see <link linkend="Kernel.ServiceConfigurationinDetail">Service
    Configuration in Detail</link>. In general your service is free to use
    init parameters, they are not required.</para>

    <para>If you ever need to create your own service, the minimum is to
    create an empty interface, an empty class and a constructor for your class
    - that's all. Ok, you also should put your class and the interface in a
    jar file and add a default configuration file.</para>
  </section>

  <section id="Kernel.ServiceConfigurationinDetail.ExecutionModes">
    <title>Execution Modes</title>

    <para>One important thing to understand concerns execution modes. There
    are only two modes:</para>

    <itemizedlist>
      <listitem>
        <para>Portal mode: The service runs embedded in the GateIn. In this
        mode a <classname>PortalContainer</classname> is used.</para>
      </listitem>

      <listitem>
        <para>Standalone mode: The service runs without the portal. For
        example, the JCR service can run standalone, and also the eXo Portlet
        Container. This mode is used by eXo developers for unit tests. As the
        name suggests a <classname>StandaloneContainer</classname> is
        used.</para>
      </listitem>
    </itemizedlist>
  </section>

  <section id="Kernel.ServiceConfigurationforBeginners.Containers">
    <title>Containers</title>

    <para>In order to access to a service you need to use a Container. Just
    open <ulink
    url="https://github.com/exoplatform/kernel/tree/stable/2.5.x/exo.kernel.container/src/main/java/org/exoplatform/container">https://github.com/exoplatform/kernel/tree/stable/2.5.x/exo.kernel.container/src/main/java/org/exoplatform/container</ulink>.</para>

    <para>Among the classes you see in this directory, you only will be
    interested in these three container types:</para>

    <itemizedlist>
      <listitem>
        <para>RootContainer: This is a base container. This container plays an
        important role during startup, but you should not use it
        directly.</para>
      </listitem>

      <listitem>
        <para>PortalContainer: Created at the startup of the portal web
        application (in the init() method of the PortalController
        servlet)</para>
      </listitem>

      <listitem>
        <para>StandaloneContainer: A context independent eXo Container. The
        <classname>StandaloneContainer</classname> is also used for unit
        tests.</para>
      </listitem>
    </itemizedlist>

    <para><emphasis role="bold">Use only one container</emphasis> Even if
    there are several container types you always use exactly one. The
    RootContainer is never directly used and it depends on the execution mode
    if you use the PortalContainer or the StandaloneContainer. You will ask
    how to find out the execution mode in my application and how to manage
    these two modes. It's easy, you don't have to worry about it because the
    ExoContainerContext class provides a static method that allows you to get
    the right container from anywhere (see info box).</para>

    <para><emphasis role="bold">PicoContainer</emphasis> All containers
    inherit from the ExoContainer class which itself inherits from a
    <classname>PicoContainer</classname>. <ulink
    url="http://picocontainer.codehaus.org/">PicoContainer</ulink> is a
    framework which allows eXo to apply the IoC (<link
    linkend="Kernel.InversionOfControl">Inversion of Control</link>)
    principles. The precise implementations of any service is unknown at
    compile time. Various implementations can be used, eXo supplies different
    implementations but they also may be delivered by other vendors. The
    decision which service to use during runtime is made in configuration
    files.</para>

    <para>These configuration files are read by the container, the container
    adds all services to a list or more exactly a java HashTable. It's
    completely correct to suppose that the configuration.xml you already saw
    plays an important role. But there are more places where a configuration
    for a service can be defined as you see in the next section.</para>

    <note>
      <para>"In your java code you have to use</para>

      <programlisting language="java">ExoContainer myContainer = ExoContainerContext.getCurrentContainer();</programlisting>

      <para>in order to access to the current container. It doesn't greatly
      matter to your application if the current container is a
      <classname>PortalContainer</classname> or a
      <classname>StandaloneContainer</classname>. Once you have your container
      you may access to any service registered in this container using</para>

      <programlisting language="java">MyService myService = (MyService) myContainer.getComponentInstance(MyService.class);</programlisting>

      <para>You easily realize that <classname>MyService.class</classname> is
      the name of the service interface.</para>
    </note>
  </section>

  <section id="Kernel.ServiceConfigurationforBeginners.ConfigurationRetrieval">
    <title>Configuration Retrieval</title>

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

    <section id="RootContainer">
      <title>RootContainer</title>

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

      <para>The retrieval sequence in short:</para>

      <orderedlist>
        <listitem>
          <para>Services default <classname>RootContainer</classname>
          configurations from JAR files <emphasis>at
          /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 file could be found inside the
          META-INF folder, it will use only this file and will ignore
          configuration files in the META-INF folder of the web applications
          included in the EAR file.</para>
        </listitem>

        <listitem>
          <para>External <classname>RootContainer</classname> configuration,
          to be found at
          <emphasis>exo-tomcat/exo-conf/configuration.xml</emphasis></para>
        </listitem>
      </orderedlist>

      <note>
        <para>Naturally you always have to replace
        <parameter>exo-tomcat</parameter> by your own folder name. In case of
        a Java Standalone application you have to use the
        <parameter>user.dir</parameter> JVM system property value.</para>
      </note>

      <para><emphasis role="bold">HashTable</emphasis> The
      <classname>RootContainer</classname> creates a java
      <classname>HashTable</classname> which contains key-value pairs for the
      services. The qualified interface name of each service is used as key
      for the hashtable. Hopefully you still remember that the
      <parameter>&lt;key&gt;</parameter> tag of the configuration file
      contains the interface name? The value of each hashtable pair is an
      object that contains the service configuration (yes, this means the
      whole structure between the <parameter>&lt;component&gt;</parameter>
      tags of your <filename>configuration.xml</filename> file).</para>

      <para>The <classname>RootContainer</classname> runs over all jar files
      you find in <emphasis>exo-tomcat/lib</emphasis> and looks if there is a
      configuration file at <emphasis>/conf/configuration.xml</emphasis>, the
      services configured in this file are added to the hashtable. That way -
      at the end of this process - the default configurations for all services
      are stored in the hashtable.</para>

      <note>
        <para>What happens if the same service - recognized by the same
        qualified interface name - is configured in different jars? As the
        service only can exist one time the configuration of the jar found
        later overrides the previous configuration. You know that the loading
        <emphasis role="bold">order of the jars is unpredictable</emphasis>
        you <emphasis role="bold">must not depend on this</emphasis>.</para>
      </note>

      <para>If you wish to provide your own configurations for one or several
      services, you can do it in a general configuration file that has to be
      placed at <emphasis>exo-tomcat/exo-conf/configuration.xml</emphasis>. Do
      not search for such a file on your computer - you won't find one,
      because this option is not used in the default installation. Here again
      the same rule applies: <emphasis>The posterior configuration replaces
      the previous one</emphasis>.</para>

      <para>The further configuration retrieval depends on the container
      type.</para>
    </section>

    <section id="PortalContainer">
      <title>PortalContainer</title>

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

      <para>In short PortalContainer configurations are retrieved in the
      following lookup sequence :</para>

      <orderedlist>
        <listitem>
          <para>Default PortalContainer configurations from all JAR files
          (folder <emphasis>/conf/portal/configuration.xml</emphasis>)</para>
        </listitem>

        <listitem>
          <para>Web application configurations from the portal.war file - or
          the <emphasis>portal</emphasis> weppapp (folder
          <emphasis>/WEB-INF/conf/configuration.xml</emphasis>)</para>
        </listitem>

        <listitem>
          <para>External configuration for services of a named portal, it will
          be found at
          <emphasis>exo-tomcat/exo-conf/portal/$portal_name/configuration.xml</emphasis>
          (as of GateIn)</para>
        </listitem>
      </orderedlist>

      <para>You see, here the
      <emphasis>/conf/portal/configuration.xml</emphasis> file of each jar
      enters the game, they are searched at first. Next, there is nearly
      always a configuration.xml in the portal.war file (or in the portal
      webapp folder), you find this file at
      <emphasis>/WEB-INF/conf/configuration.xml</emphasis>. If you open it,
      you will find a lot of import statements that point to other
      configuration files in the same portal.war (or portal webapp).</para>

      <para><emphasis role="bold">Multiple Portals</emphasis> Be aware that
      you might set up several different portals ("admin", "mexico", etc.),
      and each of these portals will use a different PortalContainer. And each
      of these PortalContainers can be configured separately. As of GateIn you
      also will be able to provide configurations from outside the jars and
      wars or webapps. Put a configuration file in
      <emphasis>exo-tomcat/exo-conf/portal/$portal_name/configuration.xml</emphasis>
      where <parameter>$portal_name</parameter> is the name of the portal you
      want to configure for . But normally you only have one portal which is
      called "portal" so you use
      <emphasis>exo-tomcat/exo-conf/portal/portal/configuration.xml</emphasis>.</para>

      <note>
        <para>GateIn you can override the external configuration location with
        the system property <emphasis>exo.conf.dir</emphasis>. If the property
        exists its value will be used as path to the eXo configuration
        directory, that means this is an alternative to
        <emphasis>exo-tomcat/exo-conf</emphasis>. Just put this property in
        the command line: <emphasis>java
        -Dexo.conf.dir=/path/to/exo/conf</emphasis> or use eXo.bat or eXo.sh.
        In this particular use case, you have no need to use any prefixes in
        your configuration file to import other files. For example, if your
        configuration file is
        <emphasis>exo-tomcat/exo-conf/portal/PORTAL_NAME/configuration.xml</emphasis>
        and you want to import the configuration file
        <emphasis>exo-tomcat/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>Under <emphasis role="bold">JBoss</emphasis> application server
        <emphasis>exo-conf</emphasis> will be looked up in directory described
        by JBoss System property <emphasis>jboss.server.config.url</emphasis>.
        If the property is not found or empty
        <emphasis>exo-jboss/exo-conf</emphasis> will be asked (since kernel
        2.0.4).</para>
      </note>
    </section>

    <section id="StandaloneContainer">
      <title>StandaloneContainer</title>

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

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

      <itemizedlist>
        <listitem>
          <para><emphasis role="bold">Independent configuration by
          URL</emphasis> No other configuration file is taken in
          consideration. The configuration provided by the URL is used without
          any default configs. That means that the container creates a new
          empty hashtable and not any bit of previous configuration is used.
          Apply the following code to do this:</para>

          <programlisting language="java">StandaloneContainer.setConfigurationURL(containerConf);</programlisting>
        </listitem>

        <listitem>
          <para><emphasis role="bold">Additional configuration by
          URL</emphasis> The StandaloneContainer is initialized very similar
          to the PortalContainer, but the last step is slightly different. A
          configuration file that is provided by the URL is used to replace
          some of the service configurations.The code looks like this:</para>

          <programlisting language="java">StandaloneContainer.addConfigurationURL(containerConf);</programlisting>

          <orderedlist>
            <listitem>
              <para>Default <emphasis>StandaloneContainer</emphasis>
              configurations from JAR files (folder
              <emphasis>/conf/configuration.xml</emphasis>)</para>
            </listitem>

            <listitem>
              <para>Default <emphasis>StandaloneContainer</emphasis>
              configurations from JAR files (folder
              <emphasis>/conf/portal/configuration.xml</emphasis>)</para>
            </listitem>

            <listitem>
              <para>Web application configurations from WAR files (folder
              <emphasis>/WEB-INF/conf/configuration.xml</emphasis>)</para>
            </listitem>

            <listitem>
              <para>Configuration from added URL
              <emphasis>containerConf</emphasis> overrides only services
              configured in the file</para>
            </listitem>
          </orderedlist>
        </listitem>

        <listitem>
          <para><emphasis role="bold">File based configuration</emphasis> No
          URL is involved, in this case the sequence is:</para>

          <orderedlist>
            <listitem>
              <para>Default <emphasis>StandaloneContainer</emphasis>
              configurations from JAR files (folder
              <emphasis>/conf/configuration.xml</emphasis>)</para>
            </listitem>

            <listitem>
              <para>Default <emphasis>StandaloneContainer</emphasis>
              configurations from JAR files (folder
              <emphasis>/conf/portal/configuration.xml</emphasis>)</para>
            </listitem>

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

            <listitem>
              <para>External configuration for
              <emphasis>StandaloneContainer</emphasis> services, it will be
              found at <emphasis>$user_home/exo-configuration.xml</emphasis>.
              If <emphasis>$user_home/exo-configuration.xml</emphasis> doesn't
              exist and the <emphasis>StandaloneContainer</emphasis> instance
              obtained with the dedicated configuration classloader the
              container will try to retrieve the resource
              <emphasis>conf/exo-configuration.xml</emphasis> within the given
              classloader (user_home is your home directory like "C:/Documents
              and Settings/Smith").</para>
            </listitem>
          </orderedlist>
        </listitem>
      </itemizedlist>
    </section>
  </section>

  <section id="Kernel.ServiceConfigurationforBeginners.ServiceInstantiation">
    <title>Service instantiation</title>

    <para>As you have already learned the services are all singletons, so that
    the container creates only one single instance of each container. The
    services are created by calling the constructors (called
    <emphasis>constructor injection</emphasis>). If there are only
    zero-arguments constructors (<code>Foo public Foo(){}</code>) there are no
    problems to be expected. That's easy.</para>

    <para>But now look at <ulink
    url="https://github.com/exoplatform/core/tree/stable/2.6.x/exo.core.component.organization.jdbc/src/main/java/org/exoplatform/services/organization/jdbc/OrganizationServiceImpl.java">OrganizationServiceImpl.java</ulink></para>

    <para>This JDBC implementation of BaseOrganizationService interface has
    only one constructor:</para>

    <programlisting language="java">public OrganizationServiceImpl(ListenerService listenerService, DatabaseService dbService);</programlisting>

    <para>You see this service depends on two other services. In order to be
    able to call this constructor the container first needs a
    <classname>ListenerService</classname> and a
    <classname>DatabaseService</classname>. Therefore these services must be
    instantiated before <classname>BaseOrganizationService</classname>,
    because <classname>BaseOrganizationService</classname> depends on
    them.</para>

    <para>For this purpose the container first looks at the constructors of
    all services and creates a matrix of service dependencies in order to call
    the services in a proper order. If for any reason there are
    interdependencies or circular dependencies you will get a java
    <classname>Exception</classname>. <emphasis>In this way the dependencies
    are injected by the container</emphasis>.</para>

    <note>
      <para>What happens if one service has more than one constructor? The
      container always tries first to use the constructor with a maximum
      number of arguments, if this is not possible the container continues
      step by step with constructors that have less arguments until arriving
      at the zero-argument constructor (if there is any).</para>
    </note>
  </section>

  <section id="Kernel.ServiceConfigurationforBeginners.Miscellaneous">
    <title>Miscellaneous</title>

    <section id="Startableinterface">
      <title>Startable interface</title>

      <para>Your service can implement the <emphasis>startable</emphasis>
      interface which defines a <emphasis>start()</emphasis> and a
      <emphasis>stop()</emphasis> method. These methods are called by the
      container at the beginning and the end of the container's lifecycle.
      This way the lifecycle of your service is managed by the
      container.</para>
    </section>

    <section id="InversionOfControl">
      <title>Inversion of Control</title>

      <para><emphasis role="bold">Retrospection</emphasis>. Do you remember
      your last project where you had some small components and several larger
      services? How was this organized? Some services had their own
      configuration files, others had static values in the source code. Most
      components were probably tightly coupled to the main application, or you
      called static methods whenever you needed a service in your java class.
      Presumably you even copied the source code of an earlier project in
      order to adapt the implementation to your needs. In short:</para>

      <itemizedlist>
        <listitem>
          <para>Each of your service had a proprietary configuration
          mechanism.</para>
        </listitem>

        <listitem>
          <para>The service lifecycles were managed inside of each service or
          were arbitrary.</para>
        </listitem>

        <listitem>
          <para>The dependencies between your services were
          implementation-dependent and tightly coupled in your source
          code.</para>
        </listitem>
      </itemizedlist>

      <para><emphasis role="bold">New Approach</emphasis>. You have seen that
      eXo uses the <emphasis>Inversion of Control</emphasis> (IoC) pattern
      which means that the control of the services is given to an independent
      outside entity, in this case a <emphasis>container</emphasis>. Now the
      container takes care of everything:</para>

      <itemizedlist>
        <listitem>
          <para>The <emphasis>configuration is injected</emphasis> by external
          configuration files.</para>
        </listitem>

        <listitem>
          <para>The <emphasis>lifecycle is managed from outside</emphasis>,
          because the constructors are called by the container. You can
          achieve an even finer lifecycle management if you use the startable
          interface.</para>
        </listitem>

        <listitem>
          <para>The <emphasis>dependencies are injected</emphasis> by the
          service instantiation process.</para>
        </listitem>
      </itemizedlist>

      <para><emphasis role="bold">Dependency Injection</emphasis>. You also
      saw two types of dependency injections:</para>

      <itemizedlist>
        <listitem>
          <para>Constructor injection: The constructor is called by the
          container.</para>
        </listitem>

        <listitem>
          <para>Setter injection: Whenever you use
          <emphasis>external-plugins</emphasis> to provide your service with
          plugins (see <link
          linkend="Kernel.ServiceConfigurationinDetail">Service Configuration
          in Detail</link>.</para>
        </listitem>
      </itemizedlist>
    </section>

    <section id="MoreContainers">
      <title>More Containers</title>

      <para>There are two more Containers called
      <classname>RepositoryContainer</classname> and
      <classname>WorkspaceContainer</classname>. These are specificities of
      eXo JCR, for the sake of simplicity. You don't need them.</para>
    </section>

    <section id="SingleImplementationServices">
      <title>Single Implementation Services</title>

      <para>In some case the developer of a service does not expect that there
      will be several implementations for his service. Therefore he does not
      create an interface. In this case the configuration looks like
      this:</para>

      <programlisting language="xml">&lt;key&gt;org.exoplatform.services.database.jdbc.DBSchemaCreator&lt;/key&gt;
&lt;type&gt;org.exoplatform.services.database.jdbc.DBSchemaCreator&lt;/type&gt;</programlisting>

      <para>The key and type tags contain equally the qualified class
      name.</para>
    </section>

    <section id="ConfigurationProperties">
      <title>Configuration properties</title>

      <para>Since kernel 2.0.7 and 2.1, it is possible to use system
      properties in literal values of component configuration meta data. Thus
      it is possible to resolve properties at runtime instead of providing a
      value at packaging time.</para>

      <programlisting language="xml">&lt;component&gt;
  ...
  &lt;init-params&gt;
    &lt;value-param&gt;
      &lt;name&gt;simple_param&lt;/name&gt;
      &lt;value&gt;${simple_param_value}&lt;/value&gt;
    &lt;/value-param&gt;
    &lt;properties-param&gt;
      &lt;name&gt;properties_param&lt;/name&gt;
      &lt;property name="value_1" value="properties_param_value_1"/&gt;
      &lt;property name="value_2" value="${properties_param_value_2}"/&gt;
    &lt;/properties-param&gt;
    &lt;object-param&gt;
      &lt;name&gt;object_param&lt;/name&gt;
      &lt;object type="org.exoplatform.xml.test.Person"&gt;
        &lt;field name="address"&gt;&lt;string&gt;${person_address}&lt;/string&gt;&lt;/field&gt;
        &lt;field name="male"&gt;&lt;boolean&gt;${person_male}&lt;/boolean&gt;&lt;/field&gt;
        &lt;field name="age"&gt;&lt;int&gt;${age_value}&lt;/int&gt;&lt;/field&gt;
        &lt;field name="size"&gt;&lt;double&gt;${size_value}&lt;/double&gt;&lt;/field&gt;
      &lt;/object&gt;
    &lt;/object-param&gt;
  &lt;/init-params&gt;
&lt;/component&gt;</programlisting>
    </section>

    <section id="ConfigurationLogging">
      <title>Configuration Logging</title>

      <para>In case you need to solve problems with your service
      configuration, you have to know from which JAR/WAR causes your troubles.
      Add the JVM system property
      <parameter>org.exoplatform.container.configuration.debug</parameter> to
      your eXo.bat or eXo.sh file (exo-tomcat/bin/).</para>

      <programlisting>set EXO_CONFIG_OPTS="-Dorg.exoplatform.container.configuration.debug"</programlisting>

      <para>If this property is set the container configuration manager
      reports during startup the configuration retrieval process to the
      standard output (System.out).</para>

      <programlisting>......
Add configuration jar:file:/D:/Projects/eXo/dev/exo-working/exo-tomcat/lib/exo.kernel.container-trunk.jar!/conf/portal/configuration.xml
Add configuration jar:file:/D:/Projects/eXo/dev/exo-working/exo-tomcat/lib/exo.kernel.component.cache-trunk.jar!/conf/portal/configuration.xml
Add configuration jndi:/localhost/portal/WEB-INF/conf/configuration.xml import jndi:/localhost/portal/WEB-INF/conf/common/common-configuration.xml
import jndi:/localhost/portal/WEB-INF/conf/database/database-configuration.xml import jndi:/localhost/portal/WEB-INF/conf/ecm/jcr-component-plugins-configuration.xml
import jndi:/localhost/portal/WEB-INF/conf/jcr/jcr-configuration.xml
......</programlisting>
    </section>
  </section>

  <section id="Kernel.ServiceConfigurationforBeginners.FurtherReading">
    <title>Further Reading</title>

    <para>Do you feel yourself to be an expert now? Not yet? Get a deeper look
    and read this <link linkend="Kernel.ServicesWiring">Services Wiring</link>
    article. You read so much about configuration, that you should wonder what
    the <link
    linkend="Kernel.ContainerConfiguration.ConfigurationNamespace">XML Schema
    of the configuration file</link> looks like.</para>

    <para>If you wish to see examples of service configurations you should
    study the <ulink
    url="https://github.com/exoplatform/core/tree/stable/2.6.x">Core.</ulink>
    Where you find descriptions of some eXo's core services. Finally you might
    wish to read more about <ulink
    url="http://picocontainer.codehaus.org/">PicoContainer</ulink>.</para>
  </section>
</section>
