4:15 a.m.
Author: sergiykarpenko
Date: 2010-08-02 05:15:04 -0400 (Mon, 02 Aug 2010)
New Revision: 2849
Added:
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/component-plugin-priority.xml
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/container-configuration.xml
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/exo-container.xml
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/initialcontext-binder-service.xml
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/inversion-of-control.xml
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/jmx-bean-server.xml
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/job-scheduler-service.xml
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/service-configuration-for-beginners.xml
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/service-configuration-in-detail.xml
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/services-wiring.xml
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/understanding-listnerservice.xml
Modified:
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/core/core.xml
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel.xml
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/cache.xml
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/jndi-naming.xml
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/kernel.xml
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/logging.xml
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/transaction-service.xml
Log:
EXOJCR-867: Port documentation for Kernel from wiki to docbook
Modified:
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/core/core.xml
===================================================================
---
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/core/core.xml 2010-08-01
15:20:33 UTC (rev 2848)
+++
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/core/core.xml 2010-08-02
09:15:04 UTC (rev 2849)
@@ -1,7 +1,7 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
-<chapter>
+<chapter id="Core">
<?dbhtml filename="ch-core.html"?>
<title>eXo Core</title>
Modified:
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/cache.xml
===================================================================
---
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/cache.xml 2010-08-01
15:20:33 UTC (rev 2848)
+++
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/cache.xml 2010-08-02
09:15:04 UTC (rev 2849)
@@ -2,7 +2,7 @@
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter>
- <?dbhtml filename="ch-cache.html"?>
+ <?dbhtml filename="ch-kernel-cache.html"?>
<title>eXo Cache</title>
<section>
Added:
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/component-plugin-priority.xml
===================================================================
---
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/component-plugin-priority.xml
(rev 0)
+++
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/component-plugin-priority.xml 2010-08-02
09:15:04 UTC (rev 2849)
@@ -0,0 +1,60 @@
+<?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">
+<chapter id="KernelComponentPluginPriority">
+ <?dbhtml filename="ch-kernel-component-plugin-priority.html"?>
+ <title>Component Plugin Priority</title>
+
+ <para>Since kernel version 2.0.6 it is possible to setup order of loading
+ for ComponentPlugin. Use the ' <emphasis
role="bold">priority</emphasis>'
+ tag to define plugin's load priority. By <emphasis
+ role="bold">default</emphasis> all plugins get <emphasis
+ role="bold">priority '0'</emphasis>; they will be loaded in
the container's
+ natural way. If you want one plugin to be loaded later than the others then
+ just set priority for it <emphasis role="bold">higher than
+ zero</emphasis>.</para>
+
+ <para>Simple example of fragment of a <emphasis
+ role="bold">configuration.xml</emphasis>.</para>
+
+ <programlisting>...
+<component>
+ <type>org.exoplatform.services.Component1</type>
+</component>
+
+<external-component-plugins>
+
<target-component>org.exoplatform.services.Component1</target-component>
+
+ <component-plugin>
+ <name>Plugin1</name>
+ <set-method>addPlugin</set-method>
+ <type>org.exoplatform.services.plugins.Plugin1</type>
+ <description>description</description>
+ <priority>1</priority>
+ </component-plugin>
+
+ <component-plugin>
+ <name>Plugin2</name>
+ <set-method>addPlugin</set-method>
+ <type>org.exoplatform.services.plugins.Plugin2</type>
+ <description>description</description>
+ <priority>2</priority>
+ </component-plugin>
+
+</external-component-plugins>
+
+<external-component-plugins>
+
<target-component>org.exoplatform.services.Component1</target-component>
+ <component-plugin>
+ <name>Plugin3</name>
+ <set-method>addPlugin</set-method>
+ <type>org.exoplatform.services.plugins.Plugin3</type>
+ <description>description</description>
+ </component-plugin>
+</external-component-plugins>
+...</programlisting>
+
+ <para>In the above example plugin 'Plugin3' will be loaded first because
it
+ has the default priority '0'. Then plugin 'Plugin1' will be loaded and
as
+ last one plugin 'Plugin2'.</para>
+</chapter>
Added:
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/container-configuration.xml
===================================================================
---
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/container-configuration.xml
(rev 0)
+++
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/container-configuration.xml 2010-08-02
09:15:04 UTC (rev 2849)
@@ -0,0 +1,1837 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<chapter id="KernelContainerConfiguration">
+ <?dbhtml filename="ch-kernel-container-configuration.html"?>
+
+ <title>Container Configuration</title>
+
+ <section>
+ <title>Intro</title>
+
+ <para>eXo Portal uses PicoContainer, which implements the Inversion of
+ Control (IoC) design pattern. All eXo containers inherit from a
+ PicoContainer. There are mainly two eXo containers used, each of them can
+ provide one or several services. Each container service is delivered in a
+ JAR file. This JAR file may contain a default configuration. The use of
+ default configurations is recommended and most services provide it.</para>
+
+ <para>When a Pico Container searches for services and its configurations,
+ each configurable service may be reconfigured to override default values
+ or set additional parameters. If the service is configured in two or more
+ places the configuration override mechanism will be used.</para>
+
+ <para>Confused? - You might be interested in the <link
+ linkend="KernelServiceConfigurationforBeginners">Service Configuration
for
+ Beginners</link> article, which explains the basics.</para>
+ </section>
+
+ <section id="KernelConfigurationNamespace">
+ <title>Kernel configuration namespace</title>
+
+ <para>To be effective the namespace URI
+ <uri>http://www.exoplaform.org/xml/ns/kernel_1_1.xsd</uri> must be
target
+ namespace of the XML configuration file.</para>
+
+ <programlisting><xsd:schema
+ targetNamespace="http://www.exoplaform.org/xml/ns/kernel_1_1.xsd"
+ xmlns="http://www.exoplaform.org/xml/ns/kernel_1_1.xsd"
+ xmlns:xsd="http://www.w3.org/2001/XMLSchema"
+ elementFormDefault="qualified"
+ attributeFormDefault="unqualified"
+ version="1.0">
+
+ ...
+</xsd:schema></programlisting>
+ </section>
+
+ <section>
+ <title>Understanding How configuration files are loaded</title>
+
+ <para>eXo Portal uses PicoContainer, which implements the Inversion of
+ Control (IoC) design pattern. All eXo containers inherit from a
+ PicoContainer. There are mainly two eXo containers used, each of them can
+ provide one or several services. Each container service is delivered in a
+ JAR file. This JAR file may contain a default configuration. The use of
+ default configurations is recommended and most services provide it.</para>
+
+ <para>When a Pico Container searches for services and its configurations,
+ each configurable service may be reconfigured to override default values
+ or set additional parameters. If the service is configured in two or more
+ places the configuration override mechanism will be used.</para>
+
+ <section>
+ <title>Configuration Retrieval</title>
+
+ <para>The container performs the following steps making eXo Container
+ configuration retrieval depending on the container type.</para>
+
+ <section>
+ <title>Configuration retrieval order for the
+ <envar>PortalContainer</envar></title>
+
+ <para>The container is initialized by looking into different
+ locations. This container is used by portal applications.
+ Configurations are overloaded in the following lookup sequence:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>Services default <envar>RootContainer</envar>
configurations
+ from JAR files
<emphasis>/conf/configuration.xml</emphasis></para>
+ </listitem>
+
+ <listitem>
+ <para>External <envar>RootContainer</envar> configuration,
if will
+ be found at
+
<emphasis>$AS_HOME/exo-conf/configuration.xml</emphasis></para>
+ </listitem>
+
+ <listitem>
+ <para>Services default <envar>PortalContainer</envar>
+ configurations from JAR files
+ <emphasis>/conf/portal/configuration.xml</emphasis></para>
+ </listitem>
+
+ <listitem>
+ <para>Web applications configurations from WAR files
+
<emphasis>/WEB-INF/conf/configuration.xml</emphasis></para>
+ </listitem>
+
+ <listitem>
+ <para>External configuration for services of named portal, if will
+ be found at
+
<emphasis>$AS_HOME/exo-conf/portal/$PORTAL_NAME/configuration.xml</emphasis></para>
+ </listitem>
+ </orderedlist>
+ </section>
+
+ <section>
+ <title>Configuration retrieval for a
+ <envar>StandaloneContainer</envar></title>
+
+ <para>The container is initialized by looking into different
+ locations. This container is used by non portal applications.
+ Configurations are overloaded in the following lookup sequence:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>Services default <envar>RootContainer</envar>
configurations
+ from JAR files
<emphasis>/conf/configuration.xml</emphasis></para>
+ </listitem>
+
+ <listitem>
+ <para>External <envar>RootContainer</envar> configuration,
if will
+ be found at
+
<emphasis>$AS_HOME/exo-conf/configuration.xml</emphasis></para>
+ </listitem>
+
+ <listitem>
+ <para>Services default <envar>StandaloneContainer</envar>
+ configurations from JAR files
+ <emphasis>/conf/portal/configuration.xml</emphasis></para>
+ </listitem>
+
+ <listitem>
+ <para>Web applications configurations from WAR files
+
<emphasis>/WEB-INF/conf/configuration.xml</emphasis></para>
+ </listitem>
+
+ <listitem>
+ <para>Then depending on the
<envar>StandaloneContainer</envar>
+ configuration URL initialization:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>if configuration URL was initialized to be added to
+ services defaults, as below:<programlisting>// add configuration to
the default services configurations from JARs/WARs
+StandaloneContainer.addConfigurationURL(containerConf);</programlisting></para>
+
+ <para>Configuration from added URL
+ <emphasis>containerConf</emphasis> will override only
services
+ configured in the file</para>
+ </listitem>
+
+ <listitem>
+ <para>if configuration URL not initialized at all, it will be
+ found at
<emphasis>$AS_HOME/exo-configuration.xml</emphasis>.
+ If <emphasis>$AS_HOME/exo-configuration.xml</emphasis>
doesn't
+ exist the container will try find it at
+ <emphasis>$AS_HOME/exo-conf/exo-configuration.xml</emphasis>
+ location and if it's still not found and the
+ <envar>StandaloneContainer</envar> instance obtained with
the
+ dedicated configuration <envar>ClassLoader</envar> the
+ container will try to retrieve the resource
+ <emphasis>conf/exo-configuration.xml</emphasis> within the
+ given <envar>ClassLoader</envar>.</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </orderedlist>
+ </section>
+
+ <section>
+ <title>General notes about the configuration retrieval</title>
+
+ <note>
+ <para><emphasis>$AS_HOME</emphasis> - application server
home
+ directory, or <emphasis>user.dir</emphasis> JVM system property
+ value in case of Java Standalone application.</para>
+ </note>
+
+ <note>
+ <para><emphasis>$PORTAL_NAME</emphasis> - portal web
application
+ name.</para>
+ </note>
+
+ <note>
+ <para>External configuration location can be overridden with System
+ property <emphasis>exo.conf.dir</emphasis>. If the property exists
+ its value will be used as path to eXo configuration directory, i.e.
+ to <emphasis>$AS_HOME/exo-conf</emphasis> alternative. E.g. put
+ property in command line java
+ <emphasis>-Dexo.conf.dir=/path/to/exo/conf</emphasis>. In this
+ particular use case, you have no need to use any prefix to import
+ other files. For instance, if your configuration file is
+
<emphasis>$AS_HOME/exo-conf/portal/PORTAL_NAME/configuration.xml</emphasis>
+ and you want to import the configuration file
+
<emphasis>$AS_HOME/exo-conf/portal/PORTAL_NAME/mySubConfDir/myConfig.xml</emphasis>,
+ you can do it by adding
+
<emphasis><import>mySubConfDir/myConfig.xml</import></emphasis>
+ to your configuration file.</para>
+ </note>
+
+ <note>
+ <para>The name of the configuration folder that is by default
+ <emphasis>"exo-conf"</emphasis>, can be changed thanks to
the System
+ property <emphasis>exo.conf.dir.name</emphasis>.</para>
+ </note>
+
+ <note>
+ <para>Under JBoss application server
<emphasis>exo-conf</emphasis>
+ will be looked up in directory described by JBoss System property
+ <emphasis>jboss.server.config.url</emphasis>. If the property is
not
+ found or empty <emphasis>$AS_HOME/exo-conf</emphasis> will be
+ asked.</para>
+ </note>
+
+ <note>
+ <para>The search looks for a configuration file in each JAR/WAR
+ available from the classpath using the current thread context
+ classloader. During the search these configurations are added to a
+ set. If the service was configured previously and the current JAR
+ contains a new configuration of that service the latest (from the
+ current JAR/WAR) will replace the previous one. The last one will be
+ applied to the service during the services start phase.</para>
+ </note>
+
+ <warning>
+ <para>Take care to have no dependencies between configurations from
+ JAR files (<emphasis>/conf/portal/configuration.xml</emphasis> and
+ <emphasis>/conf/configuration.xml</emphasis>) since we have no way
+ to know in advance the loading order of those configurations. In
+ other words, if you want to overload some configuration located in
+ the file <emphasis>/conf/portal/configuration.xml</emphasis> of a
+ given JAR file, you must not do it from the file
+ <emphasis>/conf/portal/configuration.xml</emphasis> of another JAR
+ file but from another configuration file loaded after configurations
+ from JAR files
+ <emphasis>/conf/portal/configuration.xml.</emphasis></para>
+ </warning>
+
+ <para>After the processing of all configurations available in system
+ the container will initialize it and start each service in order of
+ the dependency injection (DI).</para>
+
+ <para>The user/developer should be careful when configuring the same
+ service in different configuration files. It's recommended to
+ configure a service in its own JAR only. Or, in case of a portal
+ configuration, strictly reconfigure the services in portal WAR files
+ or in an external configuration.</para>
+
+ <para>There are services that can be (or should be) configured more
+ than one time. This depends on business logic of the service. A
+ service may initialize the same resource (shared with other services)
+ or may add a particular object to a set of objects (shared with other
+ services too). In the first case it's critical who will be the last,
+ i.e. whose configuration will be used. In the second case it's no
+ matter who is the first and who is the last (if the parameter objects
+ are independent).</para>
+ </section>
+
+ <section>
+ <title>Configuration retrieval log</title>
+
+ <para>In case of problems with service configuration it's important to
+ know from which JAR/WAR it comes. For that purpose the JVM system
+ property
+ <emphasis>org.exoplatform.container.configuration.debug</emphasis>
can
+ be used.<programlisting>java
-Dorg.exoplatform.container.configuration.debug ...</programlisting></para>
+
+ <para>If the property is enabled the container configuration manager
+ will log the configuration adding process at
<emphasis>INFO</emphasis>
+ level.<programlisting>......
+ Add configuration
jar:file:/D:/Projects/eXo/dev/exo-working/exo-tomcat/lib/exo.kernel.container-trunk.jar!/conf/portal/configuration.xml
+ Add configuration
jar:file:/D:/Projects/eXo/dev/exo-working/exo-tomcat/lib/exo.kernel.component.cache-trunk.jar!/conf/portal/configuration.xml
+ Add configuration jndi:/localhost/portal/WEB-INF/conf/configuration.xml
+ import jndi:/localhost/portal/WEB-INF/conf/common/common-configuration.xml
+ import jndi:/localhost/portal/WEB-INF/conf/database/database-configuration.xml
+ import
jndi:/localhost/portal/WEB-INF/conf/ecm/jcr-component-plugins-configuration.xml
+ import jndi:/localhost/portal/WEB-INF/conf/jcr/jcr-configuration.xml
+ ......</programlisting></para>
+ </section>
+
+ <section>
+ <title>Get the effective configuration at Runtime</title>
+
+ <para>The effective configuration of the StandaloneContainer,
+ RootContainer and/or PortalContainer can be known thanks to the method
+ <emphasis>getConfigurationXML</emphasis>() that is exposed through
JMX
+ at the container's level. This method will give you the effective
+ configuration in XML format that has been really interpreted by the
+ kernel. This could be helpful to understand how a given component or
+ plugin has been initialized.</para>
+ </section>
+ </section>
+
+ <section>
+ <title>Advanced concepts for the
+ <emphasis>PortalContainers</emphasis></title>
+
+ <para>Since eXo JCR 1.12, we added a set of new features that have been
+ designed to extend portal applications such as GateIn.</para>
+
+ <section>
+ <title>Add new configuration files from a WAR file</title>
+
+ <para>A <envar>ServletContextListener</envar> called
+
<envar>org.exoplatform.container.web.PortalContainerConfigOwner</envar>
+ has been added in order to notify the application that a given web
+ application provides some configuration to the portal container, and
+ this configuration file is the file
+ <emphasis>WEB-INF/conf/configuration.xml</emphasis> available in the
+ web application itself.</para>
+
+ <para>If your war file contains some configuration to add to the
+ <envar>PortalContainer</envar> simply add the following lines in
your
+ <emphasis>web.xml</emphasis> file.</para>
+
+ <programlisting><?xml version="1.0"
encoding="ISO-8859-1" ?>
+<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application
2.3//EN"
+ "http://java.sun.com/dtd/web-app_2_3.dtd">
+<web-app>
+...
+ <!-- ==================================================================
-->
+ <!-- LISTENER
-->
+ <!-- ==================================================================
-->
+ <listener>
+
<listener-class>org.exoplatform.container.web.PortalContainerConfigOwner</listener-class>
+ </listener>
+...
+</web-app></programlisting>
+ </section>
+
+ <section>
+ <title>Create your <emphasis>PortalContainers</emphasis> from a
WAR
+ file</title>
+
+ <para>A <envar>ServletContextListener</envar> called
+ <envar>org.exoplatform.container.web.PortalContainerCreator</envar>
+ has been added in order to create the current portal containers that
+ have been registered. We assume that all the web applications have
+ already been loaded before calling
+
<envar>PortalContainerCreator.contextInitialized<replaceable><optional>.</optional></replaceable></envar></para>
+
+ <para><note>
+ <para>In GateIn, the <envar>PortalContainerCreator</envar>
is
+ already managed by the file
+ <emphasis>starter.war/ear.</emphasis></para>
+ </note></para>
+ </section>
+
+ <section>
+ <title>Define a <emphasis>PortalContainer</emphasis> with its
+ dependencies and its settings</title>
+
+ <para>Now we can define precisely a portal container and its
+ dependencies and settings thanks to the
+ <envar>PortalContainerDefinition</envar> that currently contains the
+ name of the portal container, the name of the rest context, the name
+ of the realm he web application dependencies ordered by loading
+ priority (i.e. the first dependency must be loaded at first and so
+ on..) and the settings.</para>
+
+ <para>To be able to define a
<envar>PortalContainerDefinition</envar>,
+ we need to ensure first of all that a
+ <envar>PortalContainerConfig</envar> has been defined at the
+ <envar>RootContainer</envar> level, see below an
example:</para>
+
+ <programlisting> <component>
+ <!-- The full qualified name of the PortalContainerConfig -->
+
<type>org.exoplatform.container.definition.PortalContainerConfig</type>
+ <init-params>
+ <!-- The name of the default portal container -->
+ <value-param>
+ <name>default.portal.container</name>
+ <value>myPortal</value>
+ </value-param>
+ <!-- The name of the default rest ServletContext -->
+ <value-param>
+ <name>default.rest.context</name>
+ <value>myRest</value>
+ </value-param>
+ <!-- The name of the default realm -->
+ <value-param>
+ <name>default.realm.name</name>
+ <value>my-exo-domain</value>
+ </value-param>
+ <!-- The default portal container definition -->
+ <!-- It cans be used to avoid duplicating configuration -->
+ <object-param>
+ <name>default.portal.definition</name>
+ <object
type="org.exoplatform.container.definition.PortalContainerDefinition">
+ <!-- All the dependencies of the portal container ordered by loading
priority -->
+ <field name="dependencies">
+ <collection type="java.util.ArrayList">
+ <value>
+ <string>foo</string>
+ </value>
+ <value>
+ <string>foo2</string>
+ </value>
+ <value>
+ <string>foo3</string>
+ </value>
+ </collection>
+ </field>
+ <!-- A map of settings tied to the default portal container -->
+ <field name="settings">
+ <map type="java.util.HashMap">
+ <entry>
+ <key>
+ <string>foo5</string>
+ </key>
+ <value>
+ <string>value</string>
+ </value>
+ </entry>
+ <entry>
+ <key>
+ <string>string</string>
+ </key>
+ <value>
+ <string>value0</string>
+ </value>
+ </entry>
+ <entry>
+ <key>
+ <string>int</string>
+ </key>
+ <value>
+ <int>100</int>
+ </value>
+ </entry>
+ </map>
+ </field>
+ <!-- The path to the external properties file -->
+ <field name="externalSettingsPath">
+
<string>classpath:/org/exoplatform/container/definition/default-settings.properties</string>
+ </field>
+ </object>
+ </object-param>
+ </init-params>
+ </component></programlisting>
+
+ <table>
+ <title>Descriptions of the fields of
+ <envar>PortalContainerConfig</envar></title>
+
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>default.portal.container</entry>
+
+ <entry>The name of the default portal container. This field is
+ optional.</entry>
+ </row>
+
+ <row>
+ <entry>default.rest.context</entry>
+
+ <entry>The name of the default rest
+ <envar>ServletContext</envar>. This field is
optional.</entry>
+ </row>
+
+ <row>
+ <entry>default.realm.name</entry>
+
+ <entry>The name of the default realm. This field is
+ optional.</entry>
+ </row>
+
+ <row>
+ <entry>default.portal.definition</entry>
+
+ <entry>The definition of the default portal container. This
+ field is optional. The expected type is
+
<envar>org.exoplatform.container.definition.PortalContainerDefinition</envar>
+ that is described below. Allow the parameters defined in this
+ default <envar>PortalContainerDefinition</envar> will be the
+ default values.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>A new <envar>PortalContainerDefinition</envar> can be
defined at
+ the <envar>RootContainer</envar> level thanks to an external plugin,
+ see below an example:<programlisting>
<external-component-plugins>
+ <!-- The full qualified name of the PortalContainerConfig -->
+
<target-component>org.exoplatform.container.definition.PortalContainerConfig</target-component>
+ <component-plugin>
+ <!-- The name of the plugin -->
+ <name>Add PortalContainer Definitions</name>
+ <!-- The name of the method to call on the PortalContainerConfig in order to
register the PortalContainerDefinitions -->
+ <set-method>registerPlugin</set-method>
+ <!-- The full qualified name of the PortalContainerDefinitionPlugin
-->
+
<type>org.exoplatform.container.definition.PortalContainerDefinitionPlugin</type>
+ <init-params>
+ <object-param>
+ <name>portal</name>
+ <object
type="org.exoplatform.container.definition.PortalContainerDefinition">
+ <!-- The name of the portal container -->
+ <field name="name">
+ <string>myPortal</string>
+ </field>
+ <!-- The name of the context name of the rest web application
-->
+ <field name="restContextName">
+ <string>myRest</string>
+ </field>
+ <!-- The name of the realm -->
+ <field name="realmName">
+ <string>my-domain</string>
+ </field>
+ <!-- All the dependencies of the portal container ordered by loading
priority -->
+ <field name="dependencies">
+ <collection type="java.util.ArrayList">
+ <value>
+ <string>foo</string>
+ </value>
+ <value>
+ <string>foo2</string>
+ </value>
+ <value>
+ <string>foo3</string>
+ </value>
+ </collection>
+ </field>
+ <!-- A map of settings tied to the portal container -->
+ <field name="settings">
+ <map type="java.util.HashMap">
+ <entry>
+ <key>
+ <string>foo</string>
+ </key>
+ <value>
+ <string>value</string>
+ </value>
+ </entry>
+ <entry>
+ <key>
+ <string>int</string>
+ </key>
+ <value>
+ <int>10</int>
+ </value>
+ </entry>
+ <entry>
+ <key>
+ <string>long</string>
+ </key>
+ <value>
+ <long>10</long>
+ </value>
+ </entry>
+ <entry>
+ <key>
+ <string>double</string>
+ </key>
+ <value>
+ <double>10</double>
+ </value>
+ </entry>
+ <entry>
+ <key>
+ <string>boolean</string>
+ </key>
+ <value>
+ <boolean>true</boolean>
+ </value>
+ </entry>
+ </map>
+ </field>
+ <!-- The path to the external properties file -->
+ <field name="externalSettingsPath">
+
<string>classpath:/org/exoplatform/container/definition/settings.properties</string>
+ </field>
+ </object>
+ </object-param>
+ </init-params>
+ </component-plugin>
+ </external-component-plugins></programlisting></para>
+
+ <table>
+ <title>Descriptions of the fields of a
+ <envar>PortalContainerDefinition</envar> when it is used to define
a
+ new portal container</title>
+
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>name</entry>
+
+ <entry>The name of the portal container. This field is
+ mandatory .</entry>
+ </row>
+
+ <row>
+ <entry>restContextName</entry>
+
+ <entry>The name of the context name of the rest web
+ application. This field is optional. The default value will
+ the value define at the <envar>PortalContainerConfig</envar>
+ level.</entry>
+ </row>
+
+ <row>
+ <entry>realmName</entry>
+
+ <entry>The name of the realm. This field is optional. The
+ default value will the value define at the
+ <envar>PortalContainerConfig</envar> level.</entry>
+ </row>
+
+ <row>
+ <entry>dependencies</entry>
+
+ <entry>All the dependencies of the portal container ordered by
+ loading priority. This field is optional. The default value
+ will the value define at the
+ <envar>PortalContainerConfig</envar> level. The dependencies
+ are in fact the list of the context names of the web
+ applications from which the portal container depends. This
+ field is optional. The dependency order is really crucial
+ since it will be interpreted the same way by several
+ components of the platform. All those components, will
+ consider the 1st element in the list less important than the
+ second element and so on. It is currently used
+ to:<itemizedlist>
+ <listitem>
+ <para>Know the loading order of all the
+ dependencies.</para>
+ </listitem>
+
+ <listitem>
+ <para>If we have several
+
<envar>PortalContainerConfigOwner</envar><itemizedlist>
+ <listitem>
+ <para>The <envar>ServletContext</envar> of
all the
+ <envar>PortalContainerConfigOwner</envar> will
be
+ unified, if we use the unified
+ <envar>ServletContext</envar>
+
(<emphasis>PortalContainer.getPortalContext()</emphasis>)
+ to get a resource, it will try to get the resource
+ in the <envar>ServletContext</envar> of the most
+ important
<envar>PortalContainerConfigOwner</envar>
+ (i.e. last in the dependency list) and if it cans
+ find it, it will try with the second most important
+ <envar>PortalContainerConfigOwner</envar> and so
+ on.</para>
+ </listitem>
+
+ <listitem>
+ <para>The <envar>ClassLoader</envar> of all
the
+ <envar>PortalContainerConfigOwner</envar> will
be
+ unified, if we use the unified
+ <envar>ClassLoader</envar>
+
(<emphasis>PortalContainer.getPortalClassLoader()</emphasis>)
+ to get a resource, it will try to get the resource
+ in the <envar>ClassLoader</envar> of the most
+ important
<envar>PortalContainerConfigOwner</envar>
+ (i.e. last in the dependency list) and if it cans
+ find it, it will try with the second most important
+ <envar>PortalContainerConfigOwner</envar> and so
+ on.</para>
+ </listitem>
+ </itemizedlist></para>
+ </listitem>
+ </itemizedlist></entry>
+ </row>
+
+ <row>
+ <entry>settings</entry>
+
+ <entry>A <envar>java.util.Map</envar> of internal
parameters
+ that we would like to tie the portal container. Those
+ parameters could have any type of value. This field is
+ optional. If some internal settings are defined at the
+ <envar>PortalContainerConfig</envar> level, the two maps of
+ settings will be merged. If a setting with the same name is
+ defined in both maps, it will keep the value defined at the
+ <envar>PortalContainerDefinition</envar>
level.</entry>
+ </row>
+
+ <row>
+ <entry>externalSettingsPath</entry>
+
+ <entry>The path of the external properties file to load as
+ default settings to the portal container. This field is
+ optional. If some external settings are defined at the
+ <envar>PortalContainerConfig</envar> level, the two maps of
+ settings will be merged. If a setting with the same name is
+ defined in both maps, it will keep the value defined at the
+ <envar>PortalContainerDefinition</envar> level. The external
+ properties files can be either of type "properties" or of type
+ "xml". The path will be interpreted as
follows:<orderedlist>
+ <listitem>
+ <para>The path doesn't contain any prefix of type
+ "classpath:", "jar:" or "file:", we
assume that the file
+ could be externalized so we apply the following
+ rules:<orderedlist>
+ <listitem>
+ <para>A file exists at
+
<emphasis>${exo-conf-dir}/portal/${portalContainerName}/${externalSettingsPath}</emphasis>,
+ we will load this file.</para>
+ </listitem>
+
+ <listitem>
+ <para>No file exists at the previous path, we then
+ assume that the path cans be interpreted by the
+
<envar>ConfigurationManager</envar>.</para>
+ </listitem>
+ </orderedlist></para>
+ </listitem>
+
+ <listitem>
+ <para>The path contains a prefix, we then assume that
+ the path cans be interpreted by the
+ <envar>ConfigurationManager</envar>.</para>
+ </listitem>
+ </orderedlist></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <table>
+ <title>Descriptions of the fields of a
+ <envar>PortalContainerDefinition</envar> when it is used to define
+ the default portal container</title>
+
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>name</entry>
+
+ <entry>The name of the portal container. This field is
+ optional. The default portal name will be:<orderedlist>
+ <listitem>
+ <para>If this field is not empty, then the default value
+ will be the value of this field.</para>
+ </listitem>
+
+ <listitem>
+ <para>If this field is empty and the value of the
+ parameter
<emphasis>default.portal.container</emphasis>
+ is not empty, then the default value will be the value
+ of the parameter.</para>
+ </listitem>
+
+ <listitem>
+ <para>If this field and the parameter
+ <emphasis>default.portal.container</emphasis> are both
+ empty, the default value will be
+ <emphasis>"portal".</emphasis></para>
+ </listitem>
+ </orderedlist></entry>
+ </row>
+
+ <row>
+ <entry>restContextName</entry>
+
+ <entry>The name of the context name of the rest web
+ application. This field is optional. The default value wil
+ be:<orderedlist>
+ <listitem>
+ <para>If this field is not empty, then the default value
+ will be the value of this field.</para>
+ </listitem>
+
+ <listitem>
+ <para>f this field is empty and the value of the
+ parameter <emphasis>default.rest.context</emphasis> is
+ not empty, then the default value will be the value of
+ the parameter.</para>
+ </listitem>
+
+ <listitem>
+ <para>f this field and the parameter
+ <emphasis>default.rest.context</emphasis> are both
+ empty, the default value will be
+ <emphasis>"rest".</emphasis></para>
+ </listitem>
+ </orderedlist></entry>
+ </row>
+
+ <row>
+ <entry>realmName</entry>
+
+ <entry>The name of the realm. This field is optional. The
+ default value wil be:<orderedlist>
+ <listitem>
+ <para>If this field is not empty, then the default value
+ will be the value of this field.</para>
+ </listitem>
+
+ <listitem>
+ <para>f this field is empty and the value of the
+ parameter <emphasis>default.realm.name</emphasis> is
not
+ empty, then the default value will be the value of the
+ parameter.</para>
+ </listitem>
+
+ <listitem>
+ <para>f this field and the parameter
+ <emphasis>default.realm.name</emphasis> are both
empty,
+ the default value will be
+
<emphasis>"exo-domain".</emphasis></para>
+ </listitem>
+ </orderedlist></entry>
+ </row>
+
+ <row>
+ <entry>dependencies</entry>
+
+ <entry>All the dependencies of the portal container ordered by
+ loading priority. This field is optional. If this field has a
+ non empty value, it will be the default list of
+ dependencies.</entry>
+ </row>
+
+ <row>
+ <entry>settings</entry>
+
+ <entry>A <envar>java.util.Map</envar> of internal
parameters
+ that we would like to tie the default portal container. Those
+ parameters could have any type of value. This field is
+ optional.</entry>
+ </row>
+
+ <row>
+ <entry>externalSettingsPath</entry>
+
+ <entry>The path of the external properties file to load as
+ default settings to the default portal container. This field
+ is optional. The external properties files can be either of
+ type "properties" or of type "xml". The path will be
+ interpreted as follows:<orderedlist>
+ <listitem>
+ <para>The path doesn't contain any prefix of type
+ "classpath:", "jar:" or "file:", we
assume that the file
+ could be externalized so we apply the following
+ rules:<orderedlist>
+ <listitem>
+ <para>A file exists at
+
<emphasis>${exo-conf-dir}/portal/${externalSettingsPath}</emphasis>,
+ we will load this file.</para>
+ </listitem>
+
+ <listitem>
+ <para>No file exists at the previous path, we then
+ assume that the path cans be interpreted by the
+
<envar>ConfigurationManager</envar>.</para>
+ </listitem>
+ </orderedlist></para>
+ </listitem>
+
+ <listitem>
+ <para>The path contains a prefix, we then assume that
+ the path cans be interpreted by the
+ <envar>ConfigurationManager</envar>.</para>
+ </listitem>
+ </orderedlist></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>Internal and external settings are both optional, but if we give
+ a non empty value for both the application will merge the settings. If
+ the same setting name exists in both settings, we apply the following
+ rules:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>The value of the external setting is
+ <emphasis>null</emphasis>, we ignore the value.</para>
+ </listitem>
+
+ <listitem>
+ <para>The value of the external setting is not
+ <emphasis>null</emphasis> and the value of the internal setting
is
+ <emphasis>null</emphasis>, the final value will be the external
+ setting value that is of type
<envar>String</envar>.</para>
+ </listitem>
+
+ <listitem>
+ <para>Both values are not <envar>null</envar>, we will have
to
+ convert the external setting value into the target type which is
+ the type of the internal setting value, thanks to the static
+ method <emphasis>valueOf(String)</emphasis>, the following
+ sub-rules are then applied:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>The method cannot be found, the final value will be the
+ external setting value that is of type
+ <envar>String</envar>.</para>
+ </listitem>
+
+ <listitem>
+ <para>The method can be found and the external setting value
+ is an empty <envar>String</envar>, we ignore the external
+ setting value.</para>
+ </listitem>
+
+ <listitem>
+ <para>The method can be found and the external setting value
+ is not an empty <envar>String</envar> but the method call
+ fails, we ignore the external setting value.</para>
+ </listitem>
+
+ <listitem>
+ <para>The method can be found and the external setting value
+ is not an empty <envar>String</envar> and the method call
+ succeeds, the final value will be the external setting value
+ that is of type of the internal setting value.</para>
+ </listitem>
+ </orderedlist>
+ </listitem>
+ </orderedlist>
+ </section>
+
+ <section>
+ <title><envar>PortalContainer</envar> settings</title>
+
+ <para>We can inject the value of the portal container settings into
+ the portal container configuration files thanks to the variables which
+ name start with "<emphasis>portal.container.</emphasis>",
so to get
+ the value of a setting called "<emphasis>foo</emphasis>"
just use the
+ following syntax <emphasis>${portal.container.foo}</emphasis>. You
can
+ also use internal variables, such as:</para>
+
+ <table>
+ <title>Definition of the internal variables</title>
+
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>portal.container.name</entry>
+
+ <entry>Gives the name of the current portal
container.</entry>
+ </row>
+
+ <row>
+ <entry>portal.container.rest</entry>
+
+ <entry>Gives the context name of the rest web application of
+ the current portal container.</entry>
+ </row>
+
+ <row>
+ <entry>portal.container.realm</entry>
+
+ <entry>Gives the realm name of the current portal
+ container.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>You can find below an example of how to use the
+ variables:<programlisting><configuration
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.exoplaform.org/xml/ns/kernel_1_1.xsd
http://www.exoplaform.org/xml/ns/kernel_1_1.xsd"
+ xmlns="http://www.exoplaform.org/xml/ns/kernel_1_1.xsd">
+ <component>
+
<type>org.exoplatform.container.TestPortalContainer$MyComponent</type>
+ <init-params>
+ <!-- The name of the portal container -->
+ <value-param>
+ <name>portal</name>
+ <value>${portal.container.name}</value>
+ </value-param>
+ <!-- The name of the rest ServletContext -->
+ <value-param>
+ <name>rest</name>
+ <value>${portal.container.rest}</value>
+ </value-param>
+ <!-- The name of the realm -->
+ <value-param>
+ <name>realm</name>
+ <value>${portal.container.realm}</value>
+ </value-param>
+ <value-param>
+ <name>foo</name>
+ <value>${portal.container.foo}</value>
+ </value-param>
+ <value-param>
+ <name>before foo after</name>
+ <value>before ${portal.container.foo} after</value>
+ </value-param>
+ </init-params>
+ </component>
+</configuration></programlisting></para>
+
+ <para>In the properties file corresponding to the external settings,
+ you can reuse variables previously defined (in the external settings
+ or in the internal settings) to create a new variable. In this case
+ the prefix "<emphasis>portal.container.</emphasis>" is not
needed, see
+ an example below:<programlisting>my-var1=value 1
+my-var2=value 2
+complex-value=${my-var1}-${my-var2}</programlisting></para>
+
+ <para>In the external and internal settings, you can also use create
+ variables based on value of System paramaters. The System parameters
+ can either be defined at launch time or thanks to the
+ <envar>PropertyConfigurator</envar> (see next section for more
+ details). See an example below:</para>
+
+
<programlisting>temp-dir=${java.io.tmpdir}${file.separator}my-temp</programlisting>
+
+ <para>However, for the internal settings you can use System parameters
+ only to define settings of type
+ <envar>java.lang.String</envar>.</para>
+
+ <para>It cans be also very usefull to define a generic variable in the
+ settings of the default portal container, the value of this variable
+ will change according to the current portal container. See below an
+ example:<programlisting>my-generic-var=value of the portal container
"${name}"</programlisting></para>
+
+ <para>If this variable is defined at the default portal container
+ level, the value of this variable for a portal container called
+ <emphasis>"foo"</emphasis> will be <emphasis>value of
the portal
+ container "foo"</emphasis>.</para>
+ </section>
+
+ <section>
+ <title>Add dynamically settings and/or dependencies to a
+ <envar>PortalContainer</envar></title>
+
+ <para>It is possible to use <envar>component-plugin</envar>
elements
+ in order to dynamically change a PortalContainerDefinition. In the
+ example below, we add the dependency <envar>foo</envar> to the
default
+ portal container and to the portal containers called
+ <envar>foo1</envar> and
<envar>foo2</envar>:</para>
+
+ <programlisting><external-component-plugins>
+ <!-- The full qualified name of the PortalContainerConfig -->
+
<target-component>org.exoplatform.container.definition.PortalContainerConfig</target-component>
+ <component-plugin>
+ <!-- The name of the plugin -->
+ <name>Change PortalContainer Definitions</name>
+ <!-- The name of the method to call on the PortalContainerConfig in order to
register the changes on the PortalContainerDefinitions -->
+ <set-method>registerChangePlugin</set-method>
+ <!-- The full qualified name of the PortalContainerDefinitionChangePlugin
-->
+
<type>org.exoplatform.container.definition.PortalContainerDefinitionChangePlugin</type>
+ <init-params>
+ <value-param>
+ <name>apply.default</name>
+ <value>true</value>
+ </value-param>
+ <values-param>
+ <name>apply.specific</name>
+ <value>foo1</value>
+ <value>foo2</value>
+ </values-param>
+ <object-param>
+ <name>change</name>
+ <object
type="org.exoplatform.container.definition.PortalContainerDefinitionChange$AddDependencies">
+ <!-- The list of name of the dependencies to add -->
+ <field name="dependencies">
+ <collection type="java.util.ArrayList">
+ <value>
+ <string>foo</string>
+ </value>
+ </collection>
+ </field>
+ </object>
+ </object-param>
+ </init-params>
+ </component-plugin>
+</external-component-plugins></programlisting>
+
+ <table>
+ <title>Descriptions of the fields of a
+ <envar>PortalContainerDefinitionChangePlugin</envar></title>
+
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>apply.all</entry>
+
+ <entry>Indicates whether the changes have to be applied to all
+ the portal containers or not. The default value of this field
+ is <envar>false</envar>. This field is a
+ <envar>ValueParam</envar> and is not
mandatory.</entry>
+ </row>
+
+ <row>
+ <entry>apply.default</entry>
+
+ <entry>Indicates whether the changes have to be applied to the
+ default portal container or not. The default value of this
+ field is <envar>false</envar>. This field is a
+ <envar>ValueParam</envar> and is not
mandatory.</entry>
+ </row>
+
+ <row>
+ <entry>apply.specific</entry>
+
+ <entry>A set of specific portal container names to which we
+ want to apply the changes. This field is a
+ <envar>ValuesParam</envar> and is not
mandatory.</entry>
+ </row>
+
+ <row>
+ <entry><envar>Rest of the expected parameters
</envar></entry>
+
+ <entry>The rest of the expected paramaters are
+ <envar>ObjectParam</envar> of type
+ <envar>PortalContainerDefinitionChange</envar>. Those
+ parameters are in fact the list of changes that we want to
+ apply to one or several portal containers. If the list of
+ changes is empty, the component plugin will be ignored. The
+ supported implementations of PortalContainerDefinitionChange
+ are described later in this section.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>To identify the portal containers to which the changes have to
+ be applied, we use the follwing algorithm:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>The parameter <envar>apply.all</envar> has been set
to
+ <envar>true</envar>. The corresponding changes will be applied
to
+ all the portal containers. The other parameters will be
+ ignored.</para>
+ </listitem>
+
+ <listitem>
+ <para>The parameter <envar>apply.default</envar> has been
set to
+ <envar>true</envar> and the parameter
+ <envar>apply.specific</envar> is <envar>null</envar>.
The
+ corresponding changes will be applied to the default portal
+ container only.</para>
+ </listitem>
+
+ <listitem>
+ <para>The parameter <envar>apply.default</envar> has been
set to
+ <envar>true</envar> and the parameter
+ <envar>apply.specific</envar> is not
<envar>null</envar>. The
+ corresponding changes will be applied to the default portal
+ container and the given list of specific portal containers.</para>
+ </listitem>
+
+ <listitem>
+ <para>The parameter <envar>apply.default</envar> has been
set to
+ <envar>false</envar> or has not been set and the parameter
+ <envar>apply.specific</envar> is <envar>null</envar>.
The
+ corresponding changes will be applied to the default portal
+ container only.</para>
+ </listitem>
+
+ <listitem>
+ <para>The parameter <envar>apply.default</envar> has been
set to
+ <envar>false</envar> or has not been set and the parameter
+ <envar>apply.specific</envar> is not
<envar>null</envar>. The
+ corresponding changes will be applied to the given list of
+ specific portal containers.</para>
+ </listitem>
+ </orderedlist>
+
+ <section>
+ <title>The existing implementations of
+ <envar>PortalContainerDefinitionChange</envar></title>
+
+ <para>The modifications that can be applied to a
+ <envar>PortalContainerDefinition</envar> must be a class of type
+ <envar>PortalContainerDefinitionChange</envar>. The product
proposes
+ out of the box some implementations that we describe in the next sub
+ sections.</para>
+
+ <section>
+ <title><envar>AddDependencies</envar></title>
+
+ <para>This modification adds a list of dependencies at the end of
+ the list of dependencies defined into the
+ <envar>PortalContainerDefinition</envar>. The full qualified
name
+ is
+
<emphasis>org.exoplatform.container.definition.PortalContainerDefinitionChange$AddDependencies</emphasis>.</para>
+
+ <table>
+ <title>Descriptions of the fields of an
+ <envar>AddDependencies</envar></title>
+
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>dependencies</entry>
+
+ <entry>A list of <emphasis>String</emphasis>
corresponding
+ to the list of name of the dependencies to add. If the
+ value of this field is empty, the change will be
+ ignored.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>See an example below, that will add
<envar>foo</envar> at
+ the end of the dependency list of the default portal
+ container:</para>
+
+ <programlisting><external-component-plugins>
+ <!-- The full qualified name of the PortalContainerConfig -->
+
<target-component>org.exoplatform.container.definition.PortalContainerConfig</target-component>
+ <component-plugin>
+ <!-- The name of the plugin -->
+ <name>Change PortalContainer Definitions</name>
+ <!-- The name of the method to call on the PortalContainerConfig in order to
register the changes on the PortalContainerDefinitions -->
+ <set-method>registerChangePlugin</set-method>
+ <!-- The full qualified name of the PortalContainerDefinitionChangePlugin
-->
+
<type>org.exoplatform.container.definition.PortalContainerDefinitionChangePlugin</type>
+ <init-params>
+ <value-param>
+ <name>apply.default</name>
+ <value>true</value>
+ </value-param>
+ <object-param>
+ <name>change</name>
+ <object
type="org.exoplatform.container.definition.PortalContainerDefinitionChange$AddDependencies">
+ <!-- The list of name of the dependencies to add -->
+ <field name="dependencies">
+ <collection type="java.util.ArrayList">
+ <value>
+ <string>foo</string>
+ </value>
+ </collection>
+ </field>
+ </object>
+ </object-param>
+ </init-params>
+ </component-plugin>
+</external-component-plugins></programlisting>
+ </section>
+
+ <section>
+ <title><envar>AddDependenciesBefore</envar></title>
+
+ <para>This modification adds a list of dependencies before a given
+ target dependency defined into the list of dependencies of the
+ <envar>PortalContainerDefinition</envar>. The full qualified
name
+ is
+
<emphasis>org.exoplatform.container.definition.PortalContainerDefinitionChange$AddDependenciesBefore</emphasis>.</para>
+
+ <table>
+ <title>Descriptions of the fields of an
+ <envar>AddDependenciesBefore</envar></title>
+
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>dependencies</entry>
+
+ <entry>A list of <emphasis>String</emphasis>
corresponding
+ to the list of name of the dependencies to add. If the
+ value of this field is empty, the change will be
+ ignored.</entry>
+ </row>
+
+ <row>
+ <entry>target</entry>
+
+ <entry>The name of the dependency before which we would
+ like to add the new dependencies. If this field is
+ <envar>null</envar> or the target dependency cannot be
+ found in the list of dependencies defined into the
+ <envar>PortalContainerDefinition</envar>, the new
+ dependencies will be added in first position to the
+ list.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>See an example below, that will add
<envar>foo</envar>
+ before <envar>foo2</envar> in the dependency list of the default
+ portal container:</para>
+
+ <programlisting><external-component-plugins>
+ <!-- The full qualified name of the PortalContainerConfig -->
+
<target-component>org.exoplatform.container.definition.PortalContainerConfig</target-component>
+ <component-plugin>
+ <!-- The name of the plugin -->
+ <name>Change PortalContainer Definitions</name>
+ <!-- The name of the method to call on the PortalContainerConfig in order to
register the changes on the PortalContainerDefinitions -->
+ <set-method>registerChangePlugin</set-method>
+ <!-- The full qualified name of the PortalContainerDefinitionChangePlugin
-->
+
<type>org.exoplatform.container.definition.PortalContainerDefinitionChangePlugin</type>
+ <init-params>
+ <value-param>
+ <name>apply.default</name>
+ <value>true</value>
+ </value-param>
+ <object-param>
+ <name>change</name>
+ <object
type="org.exoplatform.container.definition.PortalContainerDefinitionChange$AddDependenciesBefore">
+ <!-- The list of name of the dependencies to add -->
+ <field name="dependencies">
+ <collection type="java.util.ArrayList">
+ <value>
+ <string>foo</string>
+ </value>
+ </collection>
+ </field>
+ <!-- The name of the target dependency -->
+ <field name="target">
+ <string>foo2</string>
+ </field>
+ </object>
+ </object-param>
+ </init-params>
+ </component-plugin>
+</external-component-plugins></programlisting>
+ </section>
+
+ <section>
+ <title><envar>AddDependenciesAfter</envar></title>
+
+ <para>This modification adds a list of dependencies before a given
+ target dependency defined into the list of dependencies of the
+ <envar>PortalContainerDefinition</envar>. The full qualified
name
+ is
+
<emphasis>org.exoplatform.container.definition.PortalContainerDefinitionChange$AddDependenciesAfter</emphasis>.</para>
+
+ <table>
+ <title>Descriptions of the fields of an
+ <envar>AddDependenciesAfter</envar></title>
+
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>dependencies</entry>
+
+ <entry>A list of <emphasis>String</emphasis>
corresponding
+ to the list of name of the dependencies to add. If the
+ value of this field is empty, the change will be
+ ignored.</entry>
+ </row>
+
+ <row>
+ <entry>target</entry>
+
+ <entry>The name of the dependency after which we would
+ like to add the new dependencies. If this field is
+ <envar>null</envar> or the target dependency cannot be
+ found in the list of dependencies defined into the
+ <envar>PortalContainerDefinition</envar>, the new
+ dependencies will be added in last position to the
+ list.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>See an example below, that will add
<envar>foo</envar> after
+ <envar>foo2</envar> in the dependency list of the default portal
+ container:</para>
+
+ <programlisting><external-component-plugins>
+ <!-- The full qualified name of the PortalContainerConfig -->
+
<target-component>org.exoplatform.container.definition.PortalContainerConfig</target-component>
+ <component-plugin>
+ <!-- The name of the plugin -->
+ <name>Change PortalContainer Definitions</name>
+ <!-- The name of the method to call on the PortalContainerConfig in order to
register the changes on the PortalContainerDefinitions -->
+ <set-method>registerChangePlugin</set-method>
+ <!-- The full qualified name of the PortalContainerDefinitionChangePlugin
-->
+
<type>org.exoplatform.container.definition.PortalContainerDefinitionChangePlugin</type>
+ <init-params>
+ <value-param>
+ <name>apply.default</name>
+ <value>true</value>
+ </value-param>
+ <object-param>
+ <name>change</name>
+ <object
type="org.exoplatform.container.definition.PortalContainerDefinitionChange$AddDependenciesAfter">
+ <!-- The list of name of the dependencies to add -->
+ <field name="dependencies">
+ <collection type="java.util.ArrayList">
+ <value>
+ <string>foo</string>
+ </value>
+ </collection>
+ </field>
+ <!-- The name of the target dependency -->
+ <field name="target">
+ <string>foo2</string>
+ </field>
+ </object>
+ </object-param>
+ </init-params>
+ </component-plugin>
+</external-component-plugins></programlisting>
+ </section>
+
+ <section>
+ <title><envar>AddSettings</envar></title>
+
+ <para>This modification adds new settings to a
+ <envar>PortalContainerDefinition</envar>. The full qualified
name
+ is
+
<emphasis>org.exoplatform.container.definition.PortalContainerDefinitionChange$AddSettings</emphasis>.</para>
+
+ <table>
+ <title>Descriptions of the fields of an
+ <envar>AddSettings</envar></title>
+
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>settings</entry>
+
+ <entry>A map of <emphasis><String,
+ Object></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><external-component-plugins>
+ <!-- The full qualified name of the PortalContainerConfig -->
+
<target-component>org.exoplatform.container.definition.PortalContainerConfig</target-component>
+ <component-plugin>
+ <!-- The name of the plugin -->
+ <name>Change PortalContainer Definitions</name>
+ <!-- The name of the method to call on the PortalContainerConfig in order to
register the changes on the PortalContainerDefinitions -->
+ <set-method>registerChangePlugin</set-method>
+ <!-- The full qualified name of the PortalContainerDefinitionChangePlugin
-->
+
<type>org.exoplatform.container.definition.PortalContainerDefinitionChangePlugin</type>
+ <init-params>
+ <value-param>
+ <name>apply.default</name>
+ <value>true</value>
+ </value-param>
+ <object-param>
+ <name>change</name>
+ <object
type="org.exoplatform.container.definition.PortalContainerDefinitionChange$AddSettings">
+ <!-- The settings to add to the to the portal containers -->
+ <field name="settings">
+ <map type="java.util.HashMap">
+ <entry>
+ <key>
+ <string>string</string>
+ </key>
+ <value>
+ <string>value1</string>
+ </value>
+ </entry>
+ <entry>
+ <key>
+ <string>stringX</string>
+ </key>
+ <value>
+ <string>value1</string>
+ </value>
+ </entry>
+ </map>
+ </field>
+ </object>
+ </object-param>
+ </init-params>
+ </component-plugin>
+</external-component-plugins></programlisting>
+ </section>
+ </section>
+ </section>
+ </section>
+ </section>
+
+ <section>
+ <title>System property configuration</title>
+
+ <para>A new property configurator service has been developed for taking
+ care of configuring system properties from the inline kernel configuration
+ or from specified property files.</para>
+
+ <para>The services is scoped at the root container level because it is
+ used by all the services in the different portal containers in the
+ application runtime.</para>
+
+ <section>
+ <title>Properties init param</title>
+
+ <para>The properties init param takes a property declared to configure
+ various properties.</para>
+
+ <programlisting><component>
+ <key>PropertyManagerConfigurator</key>
+
<type>org.exoplatform.container.PropertyConfigurator</type>
+ <init-params>
+ <properties-param>
+ <name>properties</name>
+ <property name="foo" value="bar"/>
+ </properties-param>
+ </init-params>
+</component></programlisting>
+ </section>
+
+ <section>
+ <title>Properties URL init param</title>
+
+ <para>The properties URL init param allow to load an external file by
+ specifying its URL. Both property and XML format are supported, see the
+ javadoc of the
<emphasis><envar>java.util.Properties</envar></emphasis>
+ class for more information. When a property file is loaded the various
+ property declarations are loaded in the order in which the properties
+ are declared sequentially in the file.</para>
+
+ <programlisting><component>
+ <key>PropertyManagerConfigurator</key>
+
<type>org.exoplatform.container.PropertyConfigurator</type>
+ <init-params>
+ <value-param>
+ <name>properties.url</name>
+ <value>classpath:configuration.properties</value>
+ </value-param>
+ </init-params>
+</component></programlisting>
+
+ <para>In the properties file corresponding to the external properties,
+ you can reuse variables previously defined to create a new variable. In
+ this case the prefix "<emphasis>portal.container.</emphasis>"
is not
+ needed, see an example below:<programlisting>my-var1=value 1
+my-var2=value 2
+complex-value=${my-var1}-${my-var2}</programlisting></para>
+ </section>
+
+ <section>
+ <title>System Property configuration of the properties URL</title>
+
+ <para>It is possible to replace the properties URL init param by a
+ system property that overwrites it. The name of that property is
+ <emphasis>exo.properties.url</emphasis>.</para>
+ </section>
+ </section>
+
+ <section>
+ <title>Runtime configuration profiles</title>
+
+ <para>The kernel configuration is able to handle configuration profiles at
+ runtime (as opposed to packaging time).</para>
+
+ <section>
+ <title>Profiles activation</title>
+
+ <para>An active profile list is obtained during the boot of the root
+ container and is composed of the system property
+ <emphasis>exo.profiles</emphasis> sliced according the ","
delimiter and
+ also a server specific profile value (tomcat for tomcat, jboss for
+ jboss, etc...).</para>
+
+ <programlisting># runs GateIn on Tomcat with the profiles tomcat and foo
+sh gatein.sh -Dexo.profiles=foo
+
+# runs GateIn on JBoss with the profiles jboss, foo and bar
+sh run.sh -Dexo.profiles=foo,bar</programlisting>
+ </section>
+
+ <section>
+ <title>Profiles configuration</title>
+
+ <para>Profiles are configured in the configuration files of the eXo
+ kernel.</para>
+
+ <section>
+ <title>Profiles definition</title>
+
+ <para>Profile activation occurs at XML to configuration object
+ unmarshalling time. It is based on an "profile" attribute that is
+ present on some of the XML element of the configuration files. To
+ enable this the kernel configuration schema has been upgraded to
+ kernel_1_1.xsd. The configuration is based on the following
+ rules:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>Any kernel element with the no
<emphasis>profiles</emphasis>
+ attribute will create a configuration object</para>
+ </listitem>
+
+ <listitem>
+ <para>Any kernel element having a
<emphasis>profiles</emphasis>
+ attribute containing at least one of the active profiles will
+ create a configuration object</para>
+ </listitem>
+
+ <listitem>
+ <para>Any kernel element having a
<emphasis>profiles</emphasis>
+ attribute matching none of the active profile will not create a
+ configuration object</para>
+ </listitem>
+
+ <listitem>
+ <para>Resolution of duplicates (such as two components with same
+ type) is left up to the kernel</para>
+ </listitem>
+ </orderedlist>
+ </section>
+
+ <section>
+ <title>Profiles capable configuration elements</title>
+
+ <para>A configuration element is <emphasis>profiles</emphasis>
capable
+ when it carries a profiles element.</para>
+
+ <section>
+ <title>Component element</title>
+
+ <para>The component element declares a component when activated. It
+ will shadow any element with the same key declared before in the
+ same configuration file:</para>
+
+ <programlisting><component>
+ <key>Component</key>
+ <type>Component</type>
+</component>
+
+<component profiles="foo">
+ <key>Component</key>
+ <type>FooComponent</type>
+</component></programlisting>
+ </section>
+
+ <section>
+ <title>Component plugin element</title>
+
+ <para>The component-plugin element is used to dynamically extend the
+ configuration of a given component. Thanks to the profiles the
+ component-plugins could be enabled or disabled:</para>
+
+ <programlisting><external-component-plugins>
+ <target-component>Component</target-component>
+ <component-plugin profiles="foo">
+ <name>foo</name>
+ <set-method>addPlugin</set-method>
+ <type>type</type>
+ <init-params>
+ <value-param>
+ <name>param</name>
+ <value>empty</value>
+ </value-param>
+ </init-params>
+ </component-plugin>
+</external-component-plugins></programlisting>
+ </section>
+
+ <section>
+ <title>Import element</title>
+
+ <para>The import element imports a referenced configuration file
+ when activated:</para>
+
+ <programlisting><import>empty</import>
+<import profiles="foo">foo</import>
+<import
profiles="bar">bar</import></programlisting>
+ </section>
+
+ <section>
+ <title>Init param element</title>
+
+ <para>The init param element configures the parameter argument of
+ the construction of a component service:</para>
+
+ <programlisting><component>
+ <key>Component</key>
+ <type>ComponentImpl</type>
+ <init-params>
+ <value-param>
+ <name>param</name>
+ <value>empty</value>
+ </value-param>
+ <value-param profiles="foo">
+ <name>param</name>
+ <value>foo</value>
+ </value-param>
+ <value-param profiles="bar">
+ <name>param</name>
+ <value>bar</value>
+ </value-param>
+ </init-params>
+</component></programlisting>
+ </section>
+
+ <section>
+ <title>Value collection element</title>
+
+ <para>The value collection element configures one of the value of
+ collection data:</para>
+
+ <programlisting><object
type="org.exoplatform.container.configuration.ConfigParam">
+ <field name="role">
+ <collection type="java.util.ArrayList">
+
<value><string>manager</string></value>
+ <value
profiles="foo"><string>foo_manager</string></value>
+ <value
profiles="foo,bar"><string>foo_bar_manager</string></value>
+ </collection>
+ </field>
+</object></programlisting>
+ </section>
+
+ <section>
+ <title>Field configuration element</title>
+
+ <para>The field configuration element configures the field of an
+ object:</para>
+
+ <programlisting><object-param>
+ <name>test.configuration</name>
+ <object
type="org.exoplatform.container.configuration.ConfigParam">
+ <field name="role">
+ <collection type="java.util.ArrayList">
+
<value><string>manager</string></value>
+ </collection>
+ </field>
+ <field name="role" profiles="foo,bar">
+ <collection type="java.util.ArrayList">
+
<value><string>foo_bar_manager</string></value>
+ </collection>
+ </field>
+ <field name="role" profiles="foo">
+ <collection type="java.util.ArrayList">
+
<value><string>foo_manager</string></value>
+ </collection>
+ </field>
+ </object>
+</object-param></programlisting>
+ </section>
+ </section>
+ </section>
+ </section>
+
+ <section>
+ <title>Component request life cycle</title>
+
+ <section>
+ <title>Component request life cycle contract</title>
+
+ <para>The component request life cycle is an interface that defines a
+ contract for a component for being involved into a
+ request:<programlisting>public interface ComponentRequestLifecycle
+{
+ /**
+ * Start a request.
+ * @param container the related container
+ */
+ void startRequest(ExoContainer container);
+
+ /**
+ * Ends a request.
+ * @param container the related container
+ */
+ void endRequest(ExoContainer container);
+}</programlisting></para>
+
+ <para>The container passed is the container to which the component is
+ related. This contract is often used to setup a thread local based
+ context that will be demarcated by a request.</para>
+
+ <para>For instance in the GateIn portal context, a component request
+ life cycle is triggered for user requests. Another example is the
+ initial data import in GateIn that demarcates using callbacks made to
+ that interface.</para>
+ </section>
+
+ <section>
+ <title>Request life cycle</title>
+
+ <para>The <envar>RequestLifeCycle</envar> class has several
statics
+ methods that are used to schedule the component request life cycle of
+ components. Its main responsability is to perform scheduling while
+ respecting the constraint to execute the request life cycle of a
+ component only once even if it can be scheduled several times.</para>
+
+ <section>
+ <title>Scheduling a component request life cycle</title>
+
+ <programlisting>RequestLifeCycle.begin(component);
+try
+{
+ // Do something
+}
+finally
+{
+ RequestLifeCycle.end();
+}</programlisting>
+ </section>
+
+ <section>
+ <title>Scheduling a container request life cycle</title>
+
+ <para>Scheduling a container triggers the component request life cyle
+ of all the components that implement the interface
+ <envar>ComponentRequestLifeCycle</envar>. If one of the component
has
+ already been scheduled before then that component will not be
+ scheduled again. When the local value is true then the looked
+ components will be those of the container, when it is false then the
+ scheduler will also look at the components in the ancestor
+ containers.<programlisting>RequestLifeCycle.begin(container, local);
+try
+{
+ // Do something
+}
+finally
+{
+ RequestLifeCycle.end();
+}</programlisting></para>
+ </section>
+ </section>
+
+ <section>
+ <title>When request life cycle is triggered</title>
+
+ <section>
+ <title>Portal request life cycle</title>
+
+ <para>Each portal request triggers the life cycle of the associated
+ portal container.</para>
+ </section>
+
+ <section>
+ <title>JMX request Life Cycle</title>
+
+ <para>When a JMX bean is invoked, the request life cycle of the
+ container to which it belongs it scheduled. Indeed JMX is an entry
+ point of the system that may need component to have a request life
+ cycle triggered.</para>
+ </section>
+ </section>
+ </section>
+</chapter>
Added:
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/exo-container.xml
===================================================================
---
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/exo-container.xml
(rev 0)
+++
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/exo-container.xml 2010-08-02
09:15:04 UTC (rev 2849)
@@ -0,0 +1,25 @@
+<?xml version='1.0' ?><!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook
XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<chapter id="KernelExoContainer">
+ <?dbhtml filename="ch-kernel-exo_container.html"?>
+ <title>ExoContainer info</title>
+ <para>ExoContainer is the main IoC kernel object. The container is responsible
for loading services/components.</para>
+<section>
+ <title>Container hierarchy</title>
+ <itemizedlist>
+ <listitem>
+ <para>Behaves like class loaders</para>
+ </listitem>
+ <listitem>
+ <para>a child container sees parent container components</para>
+ </listitem>
+ <listitem>
+ <para>Extensively used in eXo Platform</para>
+ </listitem>
+ </itemizedlist>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/hierarchy.png" />
+ </imageobject>
+ </mediaobject>
+</section>
+ </chapter>
Added:
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/initialcontext-binder-service.xml
===================================================================
---
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/initialcontext-binder-service.xml
(rev 0)
+++
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/initialcontext-binder-service.xml 2010-08-02
09:15:04 UTC (rev 2849)
@@ -0,0 +1,59 @@
+<?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">
+<chapter id="InitialContextBinderservice">
+ <?dbhtml filename="ch-kenel-initialcontext-binder-service.html"?>
+ <title>Initial Context Binder service</title>
+
+ <para>Initial Context Binder is responsible for binding references at
+ runtime, persisting in file and automatically rebinding after restart. Java
+ temp directory is used to persist references in bind-references.xml
+ file.</para>
+
+ <note>
+ <para>Available since Kernel 2.2.1-GA</para>
+ </note>
+
+ <section>
+ <title>API</title>
+
+ <para>Service provide methods for binding reference.</para>
+
+ <programlisting>public void bind(String bindName, String className, String
factory, String factoryLocation, Map<String, String> refAddr) throws
NamingException, FileNotFoundException, XMLStreamExcept</programlisting>
+
+ <itemizedlist>
+ <listitem>
+ <para>bindName - name of binding</para>
+ </listitem>
+
+ <listitem>
+ <para>className - the fully-qualified name of the class of the object
+ to which this Reference refers</para>
+ </listitem>
+
+ <listitem>
+ <para>factory - the name of the factory class for creating an instance
+ of the object to which this Reference refers</para>
+ </listitem>
+
+ <listitem>
+ <para>factoryLocation - the location of the factory class</para>
+ </listitem>
+
+ <listitem>
+ <para>refAddr - object's properties map</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>Configuration</title>
+
+ <para>A configuration example</para>
+
+ <programlisting><component>
+
<key>org.exoplatform.services.naming.InitialContextBinder</key>
+
<type>org.exoplatform.services.naming.InitialContextBinder</type>
+</component></programlisting>
+ </section>
+</chapter>
Added:
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/inversion-of-control.xml
===================================================================
---
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/inversion-of-control.xml
(rev 0)
+++
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/inversion-of-control.xml 2010-08-02
09:15:04 UTC (rev 2849)
@@ -0,0 +1,91 @@
+<?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">
+<chapter id="KernelInversionOfControl">
+ <?dbhtml filename="ch-kenel-inversion-of-control.html"?>
+ <title>Inversion Of Control</title>
+
+ <section>
+ <title>Overview</title>
+
+ <para>The services are not responsible for the instantiation of the
+ components they depend on.</para>
+
+ <para>This architecture provides a loosely coupled design where the
+ implementation of dependant services can be transparently
+ exchanged.</para>
+
+ <para>This pattern has several names :</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Hollywood principle : "don't call me, I will call
you"</para>
+ </listitem>
+
+ <listitem>
+ <para>Inversion of Control</para>
+ </listitem>
+
+ <listitem>
+ <para>Dependency injection</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>How</title>
+
+ <para>Not to let the object create itself the instances of the object it
+ references. This job is delegated to the container (assembler in the
+ picture).</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/ioc.gif" />
+ </imageobject>
+ </mediaobject>
+ </section>
+
+ <section>
+ <title>Injection</title>
+
+ <para>There are two ways to inject a dependency :</para>
+
+ <para>using a constructor:</para>
+
+ <programlisting>public ServiceA(ServiceB serviceB)</programlisting>
+
+ <para>using setter methods:</para>
+
+ <programlisting>public void setServiceB(ServiceB
serviceB)</programlisting>
+
+ <para>When a client service can not be stored in the container then the
+ service locator pattern is used:</para>
+
+ <programlisting>public ServiceA(){
+ this.serviceB =Container.getSInstance().getService(ServiceB.class);
+}</programlisting>
+ </section>
+
+ <section>
+ <title>Side effects</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>Ease Unit test (use of Mock objects)</para>
+ </listitem>
+
+ <listitem>
+ <para>Ease Maintainability </para>
+ </listitem>
+
+ <listitem>
+ <para>Ease Refactoring</para>
+ </listitem>
+
+ <listitem>
+ <para>Component reuse ( POJOs != EJBs)</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+</chapter>
Added:
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/jmx-bean-server.xml
===================================================================
---
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/jmx-bean-server.xml
(rev 0)
+++
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/jmx-bean-server.xml 2010-08-02
09:15:04 UTC (rev 2849)
@@ -0,0 +1,183 @@
+<?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">
+<chapter id="KernelJMXMBeanServer">
+ <?dbhtml filename="ch-kenel-jmxbeanserver.html"?>
+ <title>JMX MBean Server</title>
+
+ <section>
+ <title>JMX MBean Server</title>
+
+ <para>Each component loaded in the container will be automatically wrapped
+ by a MBean that will be registered in an associated MBean server. There
+ exist one MBean server per eXo container and you can get the instance from
+ the ExoContainer class using the method</para>
+
+ <programlisting>public MBeanServer getMBeanServer()</programlisting>
+
+ <para>By default the created MBean will be given a conventional name that
+ you can override from the configuration.xml file using the jmx-name XML
+ tag:</para>
+
+ <programlisting><component>
+
<key>org.exoplatform.services.database.HibernateService</key>
+ <jmx-name>exo-service:type=HibernateService</jmx-name>
+
<type>org.exoplatform.services.database.impl.HibernateServiceImpl</type>
+ [...]
+</component></programlisting>
+
+ <para><emphasis role="bold">Before kernel
2.0.7</emphasis>, you can access
+ to your MBeanServers by adding the patch jar attached to this page to your
+ classpath. By default this new component will bind your MBean servers to a
+ RMI registry on localhost at 9999. You will be able to access your MBeans
+ from any JMX Console which supports remote access like the JConsole by
+ using the following URLs :</para>
+
+ <table>
+ <title>Container Type and Access URLs</title>
+
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Container Type</entry>
+
+ <entry>Access URL</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>RootContainer or StandaloneContainer</entry>
+
+
<entry>service:jmx:rmi:///jndi/rmi://localhost:9999/eXo/root</entry>
+ </row>
+
+ <row>
+ <entry>PortalContainer (in Portal mode)</entry>
+
+
<entry>service:jmx:rmi:///jndi/rmi://localhost:9999/eXo/root/PORTAL_NAME</entry>
+ </row>
+
+ <row>
+ <entry>RepositoryContainer</entry>
+
+
<entry>service:jmx:rmi:///jndi/rmi://localhost:9999/eXo/root/PORTAL_NAME/REPOSITORY_NAME
+ in Portal mode or
+ service:jmx:rmi:///jndi/rmi://localhost:9999/eXo/root/REPOSITORY_NAME
+ in Standalone mode</entry>
+ </row>
+
+ <row>
+ <entry>WorkspaceContainer</entry>
+
+
<entry>service:jmx:rmi:///jndi/rmi://localhost:9999/eXo/root/PORTAL_NAME/REPOSITORY_NAME/WORKSPACE_NAME
+ in Portal mode or
+
service:jmx:rmi:///jndi/rmi://localhost:9999/eXo/root/REPOSITORY_NAME/WORKSPACE_NAME
+ in Standalone mode</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>You can of course change these properties by overloading them. Here
+ are all the parameters</para>
+
+ <programlisting><init-params>
+ <value-param>
+ <name>protocol</name>
+ <description>protocol is a short string that represent the protocol
such as "rmi", "iiop", "jmxmp" or
"soap"</description>
+ <value>rmi:///jndi/rmi</value>
+ </value-param>
+ <value-param>
+ <name>host</name>
+ <description>optional hostname</description>
+ <value>localhost</value>
+ </value-param>
+ <value-param>
+ <name>port</name>
+ <description>optional port</description>
+ <value>9999</value>
+ </value-param>
+ <value-param>
+ <name>path-prefix</name>
+ <description>optional path prefix</description>
+ <value>eXo/</value>
+ </value-param>
+ <value-param>
+ <name>name-separator</name>
+ <description>the separator used between the container
names</description>
+ <value>/</value>
+ </value-param>
+ <properties-param>
+ <name>environment</name>
+ <description>a set of attributes to control the new connector
server's behaviour</description>
+ <property name="jmx.remote.jndi.rebind"
value="true"/>
+ </properties-param>
+</init-params></programlisting>
+
+ <note>
+ <para>Please, make sure that an RMI registry has been properly started
+ (locally on 9999) before launching eXo. If you use the RMI registry
+ provided in JDK 1.5, you can just launch rmiregistry 9999.</para>
+ </note>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/jconsole2.png" />
+ </imageobject>
+ </mediaobject>
+
+ <para><emphasis role="bold">Since kernel
2.0.7</emphasis>, it is possible
+ to register all eXo MBeans in a single local MBeanServer in order to be
+ able to manage them through the JConsole or any another JMX
+ Console.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>The JVM system property <emphasis
+
role="bold">org.exoplatform.container.jmx.useExistingServer</emphasis>
+ can set to specify that we would like to use a local MBean server. By
+ default, the default behavior will be preserved.</para>
+ </listitem>
+ </itemizedlist>
+
+ <programlisting>java -Dorg.exoplatform.container.jmx.useExistingServer
...</programlisting>
+
+ <itemizedlist>
+ <listitem>
+ <para>The JVM system property <emphasis
+
role="bold">org.exoplatform.container.jmx.findExistingServer</emphasis>
+ can set to specify that we would like to find a specific local MBean
+ server. The value of this parameter is the MBean server agent id. By
+ default, the platform MBean Server will be used.</para>
+ </listitem>
+ </itemizedlist>
+
+ <programlisting>java
-Dorg.exoplatform.container.jmx.findExistingServer=${agent_id} ...</programlisting>
+
+ <para>If you have no agent id to set just set the JVM system property
+ without any value as below:</para>
+
+ <programlisting>java -Dorg.exoplatform.container.jmx.findExistingServer
...</programlisting>
+
+ <itemizedlist>
+ <listitem>
+ <para>The JVM system property <emphasis
+
role="bold">org.exoplatform.container.jmx.findExistingServerFromDefaultDomain</emphasis>
+ can set to specify our local MBean server research. The value of this
+ parameter is the MBean server default domain name. By default, only
+ the agent id is used to find the local MBean server so if several
+ MBean servers have the same agent id, the first one will be
+ used.</para>
+ </listitem>
+ </itemizedlist>
+
+ <programlisting>java
-Dorg.exoplatform.container.jmx.findExistingServerFromDefaultDomain=${default_domain}
...</programlisting>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/jconsole.png" />
+ </imageobject>
+ </mediaobject>
+ </section>
+</chapter>
Modified:
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/jndi-naming.xml
===================================================================
---
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/jndi-naming.xml 2010-08-01
15:20:33 UTC (rev 2848)
+++
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/jndi-naming.xml 2010-08-02
09:15:04 UTC (rev 2849)
@@ -1,248 +1,248 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
-"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
-<chapter>
- <?dbhtml filename="ch-jndi-naming.html"?>
-
- <title>JNDI naming</title>
-
- <section>
- <title>Prerequisites</title>
-
- <para>We need to configure JNDI environment properties and Reference
- binding with the eXo container standard mechanism.</para>
-
- <para>The Naming service covers:</para>
-
- <para><itemizedlist>
- <listitem>
- <para>Configuring the current Naming Context Factory implemented as
- an ExoContainer Component
-
<envar>org.exoplatform.services.naming.InitialContextInitializer</envar>.</para>
- </listitem>
-
- <listitem>
- <para>Binding Objects (References) to the current Context using
- <envar>org.exoplatform.services.naming.BindReferencePlugin</envar>
- component plugin.</para>
- </listitem>
- </itemizedlist></para>
- </section>
-
- <section>
- <title>How it works</title>
-
- <para>Make sure you understand the <ulink
- url="http://java.sun.com/products/jndi/1.2/javadoc/index.html"&...
Naming
- and Directory InterfaceTM (JNDI)</ulink> concepts before using this
- service.</para>
-
- <section>
- <title>JNDI System property initialization</title>
-
- <para>After the start time the Context Initializer
- (org.exoplatform.services.naming.InitialContextInitializer) traverses
- all initial parameters (that concern the Naming Context) configured in
- <envar>default-properties</envar> and
- <envar>mandatory-properties</envar> (see Configuration examples)
- and:</para>
-
- <itemizedlist>
- <listitem>
- <para>for <envar>default-properties</envar> checks if this
property
- is already set as a System property
- (<envar>System.getProperty(name)</envar>) and sets this property
if
- it's not found. Using those properties is recommended with a third
- party Naming service provider</para>
- </listitem>
-
- <listitem>
- <para>for <envar>mandatory-properties</envar> it just sets
the
- property without checking</para>
- </listitem>
- </itemizedlist>
-
- <para>Standard JNDI properties:</para>
-
- <itemizedlist>
- <listitem>
-
<para><envar>java.naming.factory.initial</envar></para>
- </listitem>
-
- <listitem>
- <para><envar>java.naming.provider.url</envar></para>
- </listitem>
- </itemizedlist>
-
- <para>and others (see JNDI docs)</para>
- </section>
-
- <section>
- <title>JNDI reference binding</title>
-
- <para>Another responsibility of Context Initializer
-
<envar>org.exoplatform.services.naming.InitialContextInitializer</envar>
- is binding of preconfigured references to the naming context. For this
- purpose it uses a standard eXo component plugin mechanism and in
- particular the
- <envar>org.exoplatform.services.naming.BindReferencePlugin</envar>
- component plugin. The configuration of this plugin includes three
- mandatory value parameters:</para>
-
- <itemizedlist>
- <listitem>
- <para><envar>bind-name</envar> - the name of binding
- reference</para>
- </listitem>
-
- <listitem>
- <para><envar>class-name</envar> - the type of binding
- reference</para>
- </listitem>
-
- <listitem>
- <para><envar>factory</envar> - the object factory
type</para>
- </listitem>
- </itemizedlist>
-
- <para>And also <envar>ref-addresses</envar> property parameter
with a
- set of references' properties. (see Configuration examples) Context
- Initializer uses those parameters to bind the neccessary reference
- automatically.</para>
- </section>
- </section>
-
- <section>
- <title>Configuration examples</title>
-
- <para>The <envar>InitialContextInitializer</envar> configuration
- example:</para>
-
- <para><programlisting> <component>
-
<type>org.exoplatform.services.naming.InitialContextInitializer</type>
- <init-params>
- <properties-param>
- <name>default-properties</name>
- <description>Default initial context
properties</description>
- <property name="java.naming.factory.initial"
value="org.exoplatform.services.naming.SimpleContextFactory"/>
- </properties-param>
- <properties-param>
- <name>mandatory-properties</name>
- <description>Mandatory initial context
properties</description>
- <property name="java.naming.provider.url"
value="rmi://localhost:9999"/>
- </properties-param>
- </init-params>
- </component></programlisting></para>
-
- <para>The <envar>BindReferencePlugin</envar> component plugin
- configuration example (for JDBC datasource):</para>
-
- <para><programlisting> <component-plugins>
- <component-plugin>
- <name>bind.datasource</name>
- <set-method>addPlugin</set-method>
-
<type>org.exoplatform.services.naming.BindReferencePlugin</type>
- <init-params>
- <value-param>
- <name>bind-name</name>
- <value>jdbcjcr</value>
- </value-param>
- <value-param>
- <name>class-name</name>
- <value>javax.sql.DataSource</value>
- </value-param>
- <value-param>
- <name>factory</name>
-
<value>org.apache.commons.dbcp.BasicDataSourceFactory</value>
- </value-param>
- <properties-param>
- <name>ref-addresses</name>
- <description>ref-addresses</description>
- <property name="driverClassName"
value="org.hsqldb.jdbcDriver"/>
- <property name="url"
value="jdbc:hsqldb:file:target/temp/data/portal"/>
- <property name="username" value="sa"/>
- <property name="password" value=""/>
- </properties-param>
- </init-params>
- </component-plugin></programlisting></para>
- </section>
-
- <section>
- <title>Recommendations for Application Developers</title>
-
- <para><itemizedlist>
- <listitem>
- <para><envar>SimpleContextFactory</envar> is created for
testing
- purposes only, do not use it for production.</para>
- </listitem>
-
- <listitem>
- <para>In J2EE environment use Naming Factory objects provided with
- the Application Server.</para>
- </listitem>
- </itemizedlist></para>
- </section>
-
- <section>
- <title>InitialContextInitializer API</title>
-
- <para><envar>InitialContextInitalizer</envar> also provides feature
of
- references binding in runtime. References have bind in runtime will be
- persisted and automatically rebinded on a next system start. Java temp
- directory is used to persist references in bind-references.xml
- file.</para>
-
- <para>Service provide methods for binding reference.</para>
-
- <programlisting>
- public void bind(String bindName,
- String className,
- String factory,
- String factoryLocation,
- Map<String, String> refAddr)
- throws NamingException, FileNotFoundException,
XMLStreamException;</programlisting>
-
- <itemizedlist>
- <listitem>
- <para><envar>bindName</envar> - name of binding</para>
- </listitem>
-
- <listitem>
- <para><envar>className</envar> - the fully-qualified name of
the class
- of the object to which this Reference refers</para>
- </listitem>
-
- <listitem>
- <para><envar>factory</envar> - the name of the factory class
for
- creating an instance of the object to which this Reference
- refers</para>
- </listitem>
-
- <listitem>
- <para><envar>factoryLocation</envar> - the location of the
factory
- class</para>
- </listitem>
-
- <listitem>
- <para><envar>refAddr</envar> - object's properties
map</para>
- </listitem>
- </itemizedlist>
-
- <para>Example of usage:</para>
-
- <programlisting>
- // obtain InitialContextInitializer instance from ExoContainer (e.g.
PortalContainer)
- InitialContextInitializer initContext =
(InitialContextInitializer)container.getComponentInstanceOfType(InitialContextInitializer.class);
-
- Map<String, String> refAddr = new HashMap<String,
String>();
- refAddr.put("driverClassName", "oracle.jdbc.OracleDriver");
- refAddr.put("url", "jdbc:oracle:thin:@oraclehost:1521:orcl");
- refAddr.put("username", "exouser");
- refAddr.put("password", "exopassword");
-
- initContext.bind("jdbcexco", "javax.sql.DataSource",
"org.apache.commons.dbcp.BasicDataSourceFactory", null, refAddr);
-
- // try to get just bound DataSource
- DataSource ds = (DataSource)new
InitialContext().lookup("jdbcexo");</programlisting>
- </section>
-</chapter>
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<chapter id="KernelJNDINaming">
+ <?dbhtml filename="ch-jndi-naming.html"?>
+
+ <title>JNDI naming</title>
+
+ <section>
+ <title>Prerequisites</title>
+
+ <para>We need to configure JNDI environment properties and Reference
+ binding with the eXo container standard mechanism.</para>
+
+ <para>The Naming service covers:</para>
+
+ <para><itemizedlist>
+ <listitem>
+ <para>Configuring the current Naming Context Factory implemented as
+ an ExoContainer Component
+
<envar>org.exoplatform.services.naming.InitialContextInitializer</envar>.</para>
+ </listitem>
+
+ <listitem>
+ <para>Binding Objects (References) to the current Context using
+ <envar>org.exoplatform.services.naming.BindReferencePlugin</envar>
+ component plugin.</para>
+ </listitem>
+ </itemizedlist></para>
+ </section>
+
+ <section>
+ <title>How it works</title>
+
+ <para>Make sure you understand the <ulink
+ url="http://java.sun.com/products/jndi/1.2/javadoc/index.html"&...
Naming
+ and Directory InterfaceTM (JNDI)</ulink> concepts before using this
+ service.</para>
+
+ <section>
+ <title>JNDI System property initialization</title>
+
+ <para>After the start time the Context Initializer
+ (org.exoplatform.services.naming.InitialContextInitializer) traverses
+ all initial parameters (that concern the Naming Context) configured in
+ <envar>default-properties</envar> and
+ <envar>mandatory-properties</envar> (see Configuration examples)
+ and:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>for <envar>default-properties</envar> checks if this
property
+ is already set as a System property
+ (<envar>System.getProperty(name)</envar>) and sets this property
if
+ it's not found. Using those properties is recommended with a third
+ party Naming service provider</para>
+ </listitem>
+
+ <listitem>
+ <para>for <envar>mandatory-properties</envar> it just sets
the
+ property without checking</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Standard JNDI properties:</para>
+
+ <itemizedlist>
+ <listitem>
+
<para><envar>java.naming.factory.initial</envar></para>
+ </listitem>
+
+ <listitem>
+ <para><envar>java.naming.provider.url</envar></para>
+ </listitem>
+ </itemizedlist>
+
+ <para>and others (see JNDI docs)</para>
+ </section>
+
+ <section>
+ <title>JNDI reference binding</title>
+
+ <para>Another responsibility of Context Initializer
+
<envar>org.exoplatform.services.naming.InitialContextInitializer</envar>
+ is binding of preconfigured references to the naming context. For this
+ purpose it uses a standard eXo component plugin mechanism and in
+ particular the
+ <envar>org.exoplatform.services.naming.BindReferencePlugin</envar>
+ component plugin. The configuration of this plugin includes three
+ mandatory value parameters:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><envar>bind-name</envar> - the name of binding
+ reference</para>
+ </listitem>
+
+ <listitem>
+ <para><envar>class-name</envar> - the type of binding
+ reference</para>
+ </listitem>
+
+ <listitem>
+ <para><envar>factory</envar> - the object factory
type</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>And also <envar>ref-addresses</envar> property parameter
with a
+ set of references' properties. (see Configuration examples) Context
+ Initializer uses those parameters to bind the neccessary reference
+ automatically.</para>
+ </section>
+ </section>
+
+ <section>
+ <title>Configuration examples</title>
+
+ <para>The <envar>InitialContextInitializer</envar> configuration
+ example:</para>
+
+ <para><programlisting> <component>
+
<type>org.exoplatform.services.naming.InitialContextInitializer</type>
+ <init-params>
+ <properties-param>
+ <name>default-properties</name>
+ <description>Default initial context
properties</description>
+ <property name="java.naming.factory.initial"
value="org.exoplatform.services.naming.SimpleContextFactory"/>
+ </properties-param>
+ <properties-param>
+ <name>mandatory-properties</name>
+ <description>Mandatory initial context
properties</description>
+ <property name="java.naming.provider.url"
value="rmi://localhost:9999"/>
+ </properties-param>
+ </init-params>
+ </component></programlisting></para>
+
+ <para>The <envar>BindReferencePlugin</envar> component plugin
+ configuration example (for JDBC datasource):</para>
+
+ <para><programlisting> <component-plugins>
+ <component-plugin>
+ <name>bind.datasource</name>
+ <set-method>addPlugin</set-method>
+
<type>org.exoplatform.services.naming.BindReferencePlugin</type>
+ <init-params>
+ <value-param>
+ <name>bind-name</name>
+ <value>jdbcjcr</value>
+ </value-param>
+ <value-param>
+ <name>class-name</name>
+ <value>javax.sql.DataSource</value>
+ </value-param>
+ <value-param>
+ <name>factory</name>
+
<value>org.apache.commons.dbcp.BasicDataSourceFactory</value>
+ </value-param>
+ <properties-param>
+ <name>ref-addresses</name>
+ <description>ref-addresses</description>
+ <property name="driverClassName"
value="org.hsqldb.jdbcDriver"/>
+ <property name="url"
value="jdbc:hsqldb:file:target/temp/data/portal"/>
+ <property name="username" value="sa"/>
+ <property name="password" value=""/>
+ </properties-param>
+ </init-params>
+ </component-plugin></programlisting></para>
+ </section>
+
+ <section>
+ <title>Recommendations for Application Developers</title>
+
+ <para><itemizedlist>
+ <listitem>
+ <para><envar>SimpleContextFactory</envar> is created for
testing
+ purposes only, do not use it for production.</para>
+ </listitem>
+
+ <listitem>
+ <para>In J2EE environment use Naming Factory objects provided with
+ the Application Server.</para>
+ </listitem>
+ </itemizedlist></para>
+ </section>
+
+ <section>
+ <title>InitialContextInitializer API</title>
+
+ <para><envar>InitialContextInitalizer</envar> also provides feature
of
+ references binding in runtime. References have bind in runtime will be
+ persisted and automatically rebinded on a next system start. Java temp
+ directory is used to persist references in bind-references.xml
+ file.</para>
+
+ <para>Service provide methods for binding reference.</para>
+
+ <programlisting>
+ public void bind(String bindName,
+ String className,
+ String factory,
+ String factoryLocation,
+ Map<String, String> refAddr)
+ throws NamingException, FileNotFoundException,
XMLStreamException;</programlisting>
+
+ <itemizedlist>
+ <listitem>
+ <para><envar>bindName</envar> - name of binding</para>
+ </listitem>
+
+ <listitem>
+ <para><envar>className</envar> - the fully-qualified name of
the class
+ of the object to which this Reference refers</para>
+ </listitem>
+
+ <listitem>
+ <para><envar>factory</envar> - the name of the factory class
for
+ creating an instance of the object to which this Reference
+ refers</para>
+ </listitem>
+
+ <listitem>
+ <para><envar>factoryLocation</envar> - the location of the
factory
+ class</para>
+ </listitem>
+
+ <listitem>
+ <para><envar>refAddr</envar> - object's properties
map</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Example of usage:</para>
+
+ <programlisting>
+ // obtain InitialContextInitializer instance from ExoContainer (e.g.
PortalContainer)
+ InitialContextInitializer initContext =
(InitialContextInitializer)container.getComponentInstanceOfType(InitialContextInitializer.class);
+
+ Map<String, String> refAddr = new HashMap<String,
String>();
+ refAddr.put("driverClassName", "oracle.jdbc.OracleDriver");
+ refAddr.put("url", "jdbc:oracle:thin:@oraclehost:1521:orcl");
+ refAddr.put("username", "exouser");
+ refAddr.put("password", "exopassword");
+
+ initContext.bind("jdbcexco", "javax.sql.DataSource",
"org.apache.commons.dbcp.BasicDataSourceFactory", null, refAddr);
+
+ // try to get just bound DataSource
+ DataSource ds = (DataSource)new
InitialContext().lookup("jdbcexo");</programlisting>
+ </section>
+</chapter>
Added:
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/job-scheduler-service.xml
===================================================================
---
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/job-scheduler-service.xml
(rev 0)
+++
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/job-scheduler-service.xml 2010-08-02
09:15:04 UTC (rev 2849)
@@ -0,0 +1,477 @@
+<?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">
+<chapter id="KernelJobSchedulerService">
+ <?dbhtml filename="ch-kenel-job-scheduler-service.html"?>
+
+ <title>Job Scheduler Service</title>
+
+ <section>
+ <title>What is Job Scheduler</title>
+
+ <para><emphasis role="bold">Job scheduler</emphasis>
defines a job to
+ execute a given number of times during a given period. It is a a software
+ application that is in charge of unattended background executions,
+ commonly known for historical reasons as batch processing.</para>
+
+ <para>Today's job schedulers typically provide a graphical user interface
+ and a single point of control for definition and monitoring of background
+ executions in a distributed network of computers. Increasingly job
+ schedulers are required to orchestrate the integration of real-time
+ business activities with traditional background IT processing, across
+ different operating system platforms and business application
+ environments.</para>
+
+ <para>Some features that may be found in a job scheduler include:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Continuously automatic monitoring of jobs and completion
+ notification</para>
+ </listitem>
+ </itemizedlist>
+
+ <itemizedlist>
+ <listitem>
+ <para>Event-driven job scheduling</para>
+ </listitem>
+ </itemizedlist>
+
+ <itemizedlist>
+ <listitem>
+ <para>Performance monitoring</para>
+ </listitem>
+ </itemizedlist>
+
+ <itemizedlist>
+ <listitem>
+ <para>Report scheduling</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>How does Job Scheduler work?</title>
+
+ <para>Jobs are scheduled to run when a given Trigger occurs. Triggers can
+ be created with nearly any combination of the following directives:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>at a certain time of day (to the millisecond)</para>
+ </listitem>
+
+ <listitem>
+ <para>on certain days of the week</para>
+ </listitem>
+ </itemizedlist>
+
+ <itemizedlist>
+ <listitem>
+ <para>on certain days of the month</para>
+ </listitem>
+
+ <listitem>
+ <para>on certain days of the year</para>
+ </listitem>
+ </itemizedlist>
+
+ <itemizedlist>
+ <listitem>
+ <para>not on certain days listed within a registered Calendar (such as
+ business holidays)</para>
+ </listitem>
+ </itemizedlist>
+
+ <itemizedlist>
+ <listitem>
+ <para>repeated a specific number of times</para>
+ </listitem>
+ </itemizedlist>
+
+ <itemizedlist>
+ <listitem>
+ <para>repeated until a specific time/date</para>
+ </listitem>
+
+ <listitem>
+ <para>repeated indefinitely</para>
+ </listitem>
+ </itemizedlist>
+
+ <itemizedlist>
+ <listitem>
+ <para>repeated with a delay interval</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Jobs are given names by their creator and can also be organized into
+ named groups. Triggers may also be given names and placed into groups, in
+ order to easily organize them within the scheduler. Jobs can be added to
+ the scheduler once, but registered with multiple Triggers. Within a J2EE
+ environment, Jobs can perform their work as part of a distributed (XA)
+ transaction.</para>
+
+ <section>
+ <title>How can Job Scheduler Service be used in Kernel?</title>
+
+ <para>Kernel leverages <ulink
+ url="http://www.quartz-scheduler.org">Quartz</ulink> for its
scheduler
+ service and wraps <classname>org.quartz.Scheduler</classname> in
+
<classname>org.exoplatform.services.scheduler.impl.QuartzSheduler</classname>
+ for easier service wiring and configuration like any other services. To
+ work with Quartz in Kernel, you'll mostly work with
+
<classname>org.exoplatform.services.scheduler.JobSchedulerService</classname>
+ (implemented by
+
<classname>org.exoplatform.services.scheduler.impl.JobSchedulerServiceImpl</classname>.</para>
+
+ <para>To use <classname>JobSchedulerService</classname>, you can
+ configure it as a component in the configuration.xml. Because
+ <classname>JobSchedulerService</classname> requires
+ <classname>QuartzSheduler</classname> and
+ <classname>QueueTasks</classname>, you also have to configure these
two
+ components.</para>
+
+ <programlisting><?xml version="1.0"
encoding="UTF-8"?>
+<configuration
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://www.exoplaform.org/xml/ns/kernel_1_0.xsd
http://www.exoplaform.org/xml/ns/kernel_1_0.xsd"
+ xmlns="http://www.exoplaform.org/xml/ns/kernel_1_0.xsd">
+
+ <component>
+
<type>org.exoplatform.services.scheduler.impl.QuartzSheduler</type>
+ </component>
+
+ <component>
+
<type>org.exoplatform.services.scheduler.QueueTasks</type>
+ </component>
+
+ <component>
+
<key>org.exoplatform.services.scheduler.JobSchedulerService</key>
+
<type>org.exoplatform.services.scheduler.impl.JobSchedulerServiceImpl</type>
+ </component>
+
+</configuration></programlisting>
+ </section>
+
+ <section>
+ <title>Samples</title>
+
+ <para>We will work with
<classname>JobSchedulerService</classname> by
+ creating a sample project and use GateIn-3.1.0-GA for testing.</para>
+
+ <para>Firstly, create a project:</para>
+
+ <programlisting>mvn archetype:generate
+//....
+Choose version:
+1: 1.0
+2: 1.0-alpha-1
+3: 1.0-alpha-2
+4: 1.0-alpha-3
+5: 1.0-alpha-4
+Choose a number: : 1
+Define value for property 'groupId': : org.exoplatform.samples
+Define value for property 'artifactId': : exo.samples.scheduler
+Define value for property 'version': 1.0-SNAPSHOT: 1.0-SNAPSHOT
+Define value for property 'package': org.exoplatform.samples: jar
+Confirm properties configuration:
+groupId: org.exoplatform.samples
+artifactId: exo.samples.scheduler
+version: 1.0-SNAPSHOT
+package: jar
+Y: Y</programlisting>
+
+ <para>Choose version as <emphasis
role="bold">1.0-SNAPSHOT</emphasis>,
+ groupId as <emphasis
role="bold">org.exoplatform.samples</emphasis>,
+ artifactId as <emphasis
role="bold">exo.samples.scheduler</emphasis> and
+ package as <emphasis role="bold">jar</emphasis>. Edit the
pom.xml as
+ following:</para>
+
+ <programlisting><project
+ xmlns="http://maven.apache.org/POM/4.0.0"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
http://maven.apache.org/maven-v4_0_0.xsd">
+
+ <modelVersion>4.0.0</modelVersion>
+
+ <parent>
+ <artifactId>exo.portal.parent</artifactId>
+ <groupId>org.exoplatform.portal</groupId>
+ <version>3.1.0-GA</version>
+ </parent>
+
+ <groupId>org.exoplatform.samples</groupId>
+ <artifactId>exo.samples.scheduler</artifactId>
+ <version>1.0-SNAPSHOT</version>
+ <name>eXo Samples For Scheduler</name>
+ <description>eXo Samples Code For Scheduler</description>
+ <dependencies>
+
+ <dependency>
+ <groupId>quartz</groupId>
+ <artifactId>quartz</artifactId>
+ <version>1.5.2</version>
+ <scope>provided</scope>
+ </dependency>
+
+ <dependency>
+ <groupId>picocontainer</groupId>
+ <artifactId>picocontainer</artifactId>
+ <version>1.1</version>
+ <scope>provided</scope>
+ </dependency>
+
+ <dependency>
+ <groupId>org.exoplatform.kernel</groupId>
+ <artifactId>exo.kernel.commons</artifactId>
+ <scope>provided</scope>
+ </dependency>
+
+ <dependency>
+ <groupId>org.exoplatform.kernel</groupId>
+ <artifactId>exo.kernel.component.common</artifactId>
+ <scope>provided</scope>
+ </dependency>
+
+ </dependencies>
+</project></programlisting>
+
+ <para>After that, create a eclipse project and then import into
+ eclipse:</para>
+
+ <programlisting>mvn eclipse:eclipse</programlisting>
+
+ <para>We'll work with this project all the time through
samples.</para>
+
+ <section>
+ <title>StartableScheduler for DumbJob example</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>See how it works on Quartz at: <ulink
+
url="http://www.quartz-scheduler.org/docs/tutorial/TutorialLesson03....
+ </listitem>
+ </itemizedlist>
+
+ <itemizedlist>
+ <listitem>
+ <para>Create a package in created project: conf/portal and add a
+ configuration configuration.xml as follows:</para>
+ </listitem>
+ </itemizedlist>
+
+ <programlisting><?xml version="1.0"
encoding="UTF-8"?>
+<configuration
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://www.exoplaform.org/xml/ns/kernel_1_0.xsd
http://www.exoplaform.org/xml/ns/kernel_1_0.xsd"
+ xmlns="http://www.exoplaform.org/xml/ns/kernel_1_0.xsd">
+
+ <component>
+
<type>org.exoplatform.services.scheduler.impl.QuartzSheduler</type>
+ </component>
+
+ <component>
+
<type>org.exoplatform.services.scheduler.QueueTasks</type>
+ </component>
+
+ <component>
+
<key>org.exoplatform.services.scheduler.JobSchedulerService</key>
+
<type>org.exoplatform.services.scheduler.impl.JobSchedulerServiceImpl</type>
+ </component>
+
+ <component>
+
<type>org.exoplatform.samples.scheduler.StartableScheduler</type>
+ </component>
+
+</configuration></programlisting>
+
+ <itemizedlist>
+ <listitem>
+ <para>Note: You can see a component: StartableSheduler to be
+ defined. It's a component startable when portal containers are
+ initialized.</para>
+ </listitem>
+ </itemizedlist>
+
+ <programlisting>package org.exoplatform.samples.scheduler;
+
+import java.util.Date;
+
+import org.exoplatform.samples.scheduler.jobs.DumbJob;
+import org.exoplatform.services.log.ExoLogger;
+import org.exoplatform.services.log.Log;
+import org.exoplatform.services.scheduler.impl.QuartzSheduler;
+import org.picocontainer.Startable;
+import org.quartz.JobDetail;
+import org.quartz.Scheduler;
+import org.quartz.SchedulerException;
+import org.quartz.Trigger;
+import org.quartz.TriggerUtils;
+
+/**
+ * Created by The eXo Platform SAS
+ * Author : eXoPlatform
+ * exo(a)exoplatform.com
+ * Jul 1, 2010
+ */
+public class StartableScheduler implements Startable {
+ private static final Log LOG = ExoLogger.getLogger(StartableScheduler.class);
+
+ public StartableScheduler(QuartzSheduler quartzScheduler) throws SchedulerException {
+ LOG.info("Init StartableScheduler");
+ JobDetail jobDetail = new JobDetail("myJob",
+ Scheduler.DEFAULT_GROUP,
+ DumbJob.class);
+ Trigger trigger = TriggerUtils.makeImmediateTrigger(3, 5000);
+ trigger.setStartTime(new Date());
+ trigger.setName("myTrigger");
+
+ Scheduler scheduler = quartzScheduler.getQuartzSheduler();
+
+ scheduler.scheduleJob(jobDetail, trigger);
+ }
+
+ @Override
+ public void start() {
+ // TODO Auto-generated method stub
+
+ }
+ @Override
+ public void stop() {
+ // TODO Auto-generated method stub
+
+ }
+}</programlisting>
+
+ <itemizedlist>
+ <listitem>
+ <para>DumbJob is defined as a job:</para>
+ </listitem>
+ </itemizedlist>
+
+ <programlisting>package org.exoplatform.samples.scheduler.jobs;
+
+import org.exoplatform.services.log.ExoLogger;
+import org.exoplatform.services.log.Log;
+import org.quartz.Job;
+import org.quartz.JobExecutionContext;
+import org.quartz.JobExecutionException;
+
+/**
+ * DumbJob.java
+ *
+ * @author <a href="http://hoatle.net">hoatle (hoatlevan at
gmail dot com)</a>
+ * @since Jul 1, 2010
+ * @copyright eXo SAS
+ */
+public class DumbJob implements Job {
+ private static final Log LOG = ExoLogger.getLogger(DumbJob.class);
+ @Override
+ public void execute(JobExecutionContext context) throws JobExecutionException {
+ LOG.info("DumbJob is executing!");
+ }
+
+}</programlisting>
+
+ <para>mvn clean install the project. Copy jar file to lib in tomcat
+ bundled with GateIn-3.1.0-GA. Run bin/gatein.sh to see the DumbJob
+ executed on the terminal when portal containers are
+ initialized.</para>
+ </section>
+ </section>
+
+ <section>
+ <title>Where is Job Scheduler Service used in eXo Products?</title>
+
+ <para>Job Service Scheduler (JSS) is used in many eXo products such as
+ Social, DMS, WCM, KS and CS.</para>
+
+ <para>For example: It is used in Schedule lifecycle in DMS.</para>
+
+ <para>Also, it is used for News Letter Email Job in ECM, Reminder Job
+ for calendar and History Job for chat in CS, Auto-count Active Users in
+ KS.</para>
+
+ <para>By using Job Scheduler Service in eXo kernel, many kinds of job
+ can be configured to run. You can addPeriodJob, addCronJob,
+ addGlobalJobListener, addJobListener and many more. Just write a job (a
+ class implements Job interface of quartz library and config plugin for
+ JobSchedulerService and you're done.</para>
+ </section>
+ </section>
+
+ <section>
+ <title>Advantages of Job Scheduler</title>
+
+ <para>It's very useful to use Job Scheduler to create schedules for a lot
+ of work, especially if they are spread across multiple machines. It's a
+ tool to make that task a lot easier. Job Schedule is also widely used in
+ almost eXo products such as: WCM, DMS, KS, CS, Social thanks to its
+ benefits and advantages.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>The Job Scheduler provides automatically log files for running
+ programs</para>
+ </listitem>
+
+ <listitem>
+ <para>The execution status of programs is automatically checked and an
+ administrator will receive protocols by eMail</para>
+ </listitem>
+
+ <listitem>
+ <para>The sequence of job starts can be organized depending on their
+ execution status</para>
+ </listitem>
+
+ <listitem>
+ <para>Job Schedulers are controlled by a graphical user
+ interface</para>
+ </listitem>
+
+ <listitem>
+ <para>Job Schedulers can be used to create complex job chains and job
+ dependencies</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Also, a wide variety of enterprise applications can take advantage
+ of job schedulers. Job schedulers can enhance the functionality of
+ enterprise applications as well as simplify their design. Furthermore, job
+ scheduling components allow software development teams to focus on their
+ applications and not on the intricate details of scheduling. By using
+ server-side components, software teams can reduce development costs and
+ bring their applications to market sooner.</para>
+ </section>
+
+ <section>
+ <title>Reference</title>
+
+ <para>To further understand about Job Scheduler, you can refer the
+ following links:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><ulink
+
url="http://www.quartz-scheduler.org/">http://www.quartz-sch...
+ </listitem>
+
+ <listitem>
+ <para><ulink
+
url="http://en.wikipedia.org/wiki/Job_scheduler">http://en.w...
+ </listitem>
+
+ <listitem>
+ <para><ulink
+
url="http://www.theserverside.com/news/1364726/Job-Scheduling-in-J2E...
+ </listitem>
+
+ <listitem>
+ <para><ulink
+
url="http://technet.microsoft.com/en-us/library/cc720070%28WS.10%29....
+ </listitem>
+ </itemizedlist>
+ </section>
+</chapter>
Modified:
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/kernel.xml
===================================================================
---
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/kernel.xml 2010-08-01
15:20:33 UTC (rev 2848)
+++
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/kernel.xml 2010-08-02
09:15:04 UTC (rev 2849)
@@ -1,7 +1,7 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
-<chapter>
+<chapter id="Kernel">
<?dbhtml filename="ch-kernel.html"?>
<title>eXo Kernel</title>
Modified:
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/logging.xml
===================================================================
---
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/logging.xml 2010-08-01
15:20:33 UTC (rev 2848)
+++
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/logging.xml 2010-08-02
09:15:04 UTC (rev 2849)
@@ -1,234 +1,234 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
-"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
-<chapter id="ch_log_configuration">
- <?dbhtml filename="ch-log-configuration.html"?>
-
- <title>Logs configuration</title>
-
- <section>
- <title>Introdution</title>
-
- <para>In order to accommodate to the different target runtime where it can
- be deployed, eXo is capable of leveraging several logging systems. eXo
- let's you choose the underlying logging engine to use and even configure
- that engine (as a quick alternative to doing it directly in your runtime
- environment).</para>
-
- <para>The currently supported logging engines are : <itemizedlist>
- <listitem>
- <para>Apache Log4J</para>
- </listitem>
-
- <listitem>
- <para>JDK's logging</para>
- </listitem>
-
- <listitem>
- <para>Apache Commons logging (which is itself a pluggable logging
- abstraction)</para>
- </listitem>
- </itemizedlist></para>
- </section>
-
- <section>
- <title>Logs configuration initializer</title>
-
- <para>eXo lets you choose whatever logging engine you want as this is
- generally influences by the AS runtime or internal policy.</para>
-
- <para>This is done through an eXo component called
- <classname>LogConfigurationInitializer</classname>.</para>
-
-
<para><classname>org.exoplatform.services.log.LogConfigurationInitializer</classname>
- that reads init parameters and configures logging system according to
- them. The parameters:<itemizedlist>
- <listitem>
- <para><firstterm>configurator</firstterm> - an implementation
of the
- <classname>LogConfigurator</classname> interface with one method
- configure() that accepts a list of properties (3rd init parameter)
- to configure the underlying log system using the concrete mechanism.
- Again there are three configurators for the most known log systems
- (commons, log4j, jdk).</para>
- </listitem>
-
- <listitem>
- <para><firstterm>properties</firstterm> - properties to
configure
- the concrete log system (system properties for commons,
- log4j.properties or logging.properties for commons, log4j and jdk
- respectively) Look at the configuration examples below.</para>
- </listitem>
-
- <listitem>
- <para><firstterm>logger</firstterm> - an implementation of
- commons-logging Log interface. It is possible to use commons
- wrappers but to support buffering required by the log portlet three
- kinds of loggers were added:
- <classname>BufferedSimpleLog</classname>,
- <classname>BufferedLog4JLogger</classname> and
- <classname>BufferedJdk14Logger</classname> (they contain
BufferedLog
- and extend SimpleLog, Log4JLogger and Jdk14Logger commons-logging
- wrappers respectively).</para>
- </listitem>
- </itemizedlist></para>
- </section>
-
- <section>
- <title>Configuration examples</title>
-
- <section>
- <title>Log4J</title>
-
- <para><ulink
url="http://logging.apache.org/log4j/">Log4J</ulink> is a
- very popular and flexible logging system. It is a good option for
- JBoss.<programlisting> <component>
-
<type>org.exoplatform.services.log.LogConfigurationInitializer</type>
- <init-params>
- <value-param>
- <name>logger</name>
-
<value>org.exoplatform.services.log.impl.BufferedLog4JLogger</value>
- </value-param>
- <value-param>
- <name>configurator</name>
-
<value>org.exoplatform.services.log.impl.Log4JConfigurator</value>
- </value-param>
- <properties-param>
- <name>properties</name>
- <description>Log4J properties</description>
- <property name="log4j.rootLogger" value="DEBUG, stdout,
file"/>
- <property name="log4j.appender.stdout"
value="org.apache.log4j.ConsoleAppender"/>
- <property name="log4j.appender.stdout.layout"
value="org.apache.log4j.PatternLayout"/>
- <property name="log4j.appender.stdout.layout.ConversionPattern"
value="%d {dd.MM.yyyy HH:mm:ss} %c {1}: %m (%F, line %L) %n"/>
- <property name="log4j.appender.file"
value="org.apache.log4j.FileAppender"/>
- <property name="log4j.appender.file.File"
value="jcr.log"/>
- <property name="log4j.appender.file.layout"
value="org.apache.log4j.PatternLayout"/>
- <property name="log4j.appender.file.layout.ConversionPattern"
value="%d{dd.MM.yyyy HH:mm:ss} %m (%F, line %L) %n"/>
- </properties-param >
- </init-params>
- </component></programlisting></para>
-
- <section>
- <title>Assigning logger level for classes or components</title>
-
- <para>You can set logger level for class or group of classes by
- setting next property:<programlisting><property
name="log4j.category.{component or class name}"
value="DEBUG"/></programlisting></para>
-
- <para>For example:<itemizedlist>
- <listitem>
- <para>we want log all debug messages for class
-
<classname>org.exoplatform.services.jcr.impl.core.SessionDataManager</classname>,
- that lies in <package>exo.jcr.component.core</package>
- component<programlisting><property
name="log4j.category.exo.jcr.component.core.SessionDataManager"
value="DEBUG"/></programlisting></para>
- </listitem>
-
- <listitem>
- <para>or we want log all debug messages for all classes in in
- <package>exo.jcr.component.core</package>
- component<programlisting><property
name="log4j.category.exo.jcr.component.core"
value="DEBUG"/></programlisting></para>
- </listitem>
-
- <listitem>
- <para>or we want log all messages for all kernel
- components<programlisting><property
name="log4j.category.exo.kernel"
value="DEBUG"/></programlisting></para>
- </listitem>
- </itemizedlist></para>
- </section>
- </section>
-
- <section>
- <title>JDK Logging</title>
-
- <para>JDK logging (aka JUL) is the builtin logging framework introduced
- in JDK 1.4. It is a good option for Tomcat AS.<itemizedlist>
- <listitem>
- <para>edit the variable <varname>LOG_OPTS</varname> in
your
- <filename>eXo.sh</filename> or
<filename>eXo.bat</filename>
-
:<programlisting>LOG_OPTS="-Dorg.apache.commons.logging.Log=org.apache.commons.logging.impl.Jdk14Logger"</programlisting></para>
- </listitem>
-
- <listitem>
- <para>Edit your
<filename>logs-configuration.xml</filename>
- :<programlisting><component>
-
<type>org.exoplatform.services.log.LogConfigurationInitializer</type>
- <init-params>
- <value-param>
- <name>logger</name>
-
<value>org.exoplatform.services.log.impl.BufferedJdk14Logger</value>
- </value-param>
- <value-param>
- <name>configurator</name>
-
<value>org.exoplatform.services.log.impl.Jdk14Configurator</value>
- </value-param>
- <properties-param>
- <name>properties</name>
- <description>jdk1.4 Logger properties</description>
- <property name="handlers"
value="java.util.logging.ConsoleHandler"/>
- <property name=".level" value="FINE"/>
- <property name="java.util.logging.ConsoleHandler.level"
value="FINE"/>
- </properties-param>
- </init-params>
- </component></programlisting></para>
- </listitem>
- </itemizedlist></para>
- </section>
-
- <section>
- <title>Commons Logging SimpleLog</title>
-
- <para>SimpleLog is a minimal logging system distributed with Commons
- Logging. To be used when nothing else is available or when you seek
- simplicity.<programlisting> <component>
-
<type>org.exoplatform.services.log.LogConfigurationInitializer</type>
- <init-params>
- <value-param>
- <name>logger</name>
-
<value>org.exoplatform.services.log.impl.BufferedSimpleLog</value>
- </value-param>
- <value-param>
- <name>configurator</name>
-
<value>org.exoplatform.services.log.impl.SimpleLogConfigurator</value>
- </value-param>
- <properties-param>
- <name>properties</name>
- <description>SimpleLog properties</description>
- <property name="org.apache.commons.logging.simplelog.defaultlog"
value="debug"/>
- <property
name="org.apache.commons.logging.simplelog.showdatetime"
value="true"/>
- </properties-param>
- </init-params>
- </component></programlisting></para>
- </section>
- </section>
-
- <section>
- <title>Tips and Troubleshooting</title>
-
- <section>
- <title>JBoss tips</title>
-
- <para>If you use log4j configuration, you can change the log
- configuration directly at runtime in:
-
<filename>JBOSS_HOME/server/default/conf/jboss-log4j.xml</filename>.<itemizedlist>
- <listitem>
- <para>To enable debug logs :<programlisting> <param
name="Threshold" value="DEBUG"/>
</programlisting></para>
- </listitem>
-
- <listitem>
- <para>To exclude messages from unnecessary classes (server's
- internal) modify the threshold of these classes to
"FATAL".</para>
- </listitem>
- </itemizedlist><tip>
- <para>If you see only ERROR level logs while starting ear on jboss
- (4.2.2), you have to remove log4j*.jar from your ear and
- application.xml.</para>
- </tip></para>
- </section>
-
- <section>
- <title>Other tips</title>
-
- <para>If you see only ERROR level logs while starting ear on jboss
- (4.2.2), you have to remove log4j*.jar from your ear and
- application.xml.</para>
- </section>
- </section>
-</chapter>
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<chapter id="KernleLogConfiguration">
+ <?dbhtml filename="ch-log-configuration.html"?>
+
+ <title>Logs configuration</title>
+
+ <section>
+ <title>Introdution</title>
+
+ <para>In order to accommodate to the different target runtime where it can
+ be deployed, eXo is capable of leveraging several logging systems. eXo
+ let's you choose the underlying logging engine to use and even configure
+ that engine (as a quick alternative to doing it directly in your runtime
+ environment).</para>
+
+ <para>The currently supported logging engines are : <itemizedlist>
+ <listitem>
+ <para>Apache Log4J</para>
+ </listitem>
+
+ <listitem>
+ <para>JDK's logging</para>
+ </listitem>
+
+ <listitem>
+ <para>Apache Commons logging (which is itself a pluggable logging
+ abstraction)</para>
+ </listitem>
+ </itemizedlist></para>
+ </section>
+
+ <section>
+ <title>Logs configuration initializer</title>
+
+ <para>eXo lets you choose whatever logging engine you want as this is
+ generally influences by the AS runtime or internal policy.</para>
+
+ <para>This is done through an eXo component called
+ <classname>LogConfigurationInitializer</classname>.</para>
+
+
<para><classname>org.exoplatform.services.log.LogConfigurationInitializer</classname>
+ that reads init parameters and configures logging system according to
+ them. The parameters:<itemizedlist>
+ <listitem>
+ <para><firstterm>configurator</firstterm> - an implementation
of the
+ <classname>LogConfigurator</classname> interface with one method
+ configure() that accepts a list of properties (3rd init parameter)
+ to configure the underlying log system using the concrete mechanism.
+ Again there are three configurators for the most known log systems
+ (commons, log4j, jdk).</para>
+ </listitem>
+
+ <listitem>
+ <para><firstterm>properties</firstterm> - properties to
configure
+ the concrete log system (system properties for commons,
+ log4j.properties or logging.properties for commons, log4j and jdk
+ respectively) Look at the configuration examples below.</para>
+ </listitem>
+
+ <listitem>
+ <para><firstterm>logger</firstterm> - an implementation of
+ commons-logging Log interface. It is possible to use commons
+ wrappers but to support buffering required by the log portlet three
+ kinds of loggers were added:
+ <classname>BufferedSimpleLog</classname>,
+ <classname>BufferedLog4JLogger</classname> and
+ <classname>BufferedJdk14Logger</classname> (they contain
BufferedLog
+ and extend SimpleLog, Log4JLogger and Jdk14Logger commons-logging
+ wrappers respectively).</para>
+ </listitem>
+ </itemizedlist></para>
+ </section>
+
+ <section>
+ <title>Configuration examples</title>
+
+ <section>
+ <title>Log4J</title>
+
+ <para><ulink
url="http://logging.apache.org/log4j/">Log4J</ulink> is a
+ very popular and flexible logging system. It is a good option for
+ JBoss.<programlisting> <component>
+
<type>org.exoplatform.services.log.LogConfigurationInitializer</type>
+ <init-params>
+ <value-param>
+ <name>logger</name>
+
<value>org.exoplatform.services.log.impl.BufferedLog4JLogger</value>
+ </value-param>
+ <value-param>
+ <name>configurator</name>
+
<value>org.exoplatform.services.log.impl.Log4JConfigurator</value>
+ </value-param>
+ <properties-param>
+ <name>properties</name>
+ <description>Log4J properties</description>
+ <property name="log4j.rootLogger" value="DEBUG, stdout,
file"/>
+ <property name="log4j.appender.stdout"
value="org.apache.log4j.ConsoleAppender"/>
+ <property name="log4j.appender.stdout.layout"
value="org.apache.log4j.PatternLayout"/>
+ <property name="log4j.appender.stdout.layout.ConversionPattern"
value="%d {dd.MM.yyyy HH:mm:ss} %c {1}: %m (%F, line %L) %n"/>
+ <property name="log4j.appender.file"
value="org.apache.log4j.FileAppender"/>
+ <property name="log4j.appender.file.File"
value="jcr.log"/>
+ <property name="log4j.appender.file.layout"
value="org.apache.log4j.PatternLayout"/>
+ <property name="log4j.appender.file.layout.ConversionPattern"
value="%d{dd.MM.yyyy HH:mm:ss} %m (%F, line %L) %n"/>
+ </properties-param >
+ </init-params>
+ </component></programlisting></para>
+
+ <section>
+ <title>Assigning logger level for classes or components</title>
+
+ <para>You can set logger level for class or group of classes by
+ setting next property:<programlisting><property
name="log4j.category.{component or class name}"
value="DEBUG"/></programlisting></para>
+
+ <para>For example:<itemizedlist>
+ <listitem>
+ <para>we want log all debug messages for class
+
<classname>org.exoplatform.services.jcr.impl.core.SessionDataManager</classname>,
+ that lies in <package>exo.jcr.component.core</package>
+ component<programlisting><property
name="log4j.category.exo.jcr.component.core.SessionDataManager"
value="DEBUG"/></programlisting></para>
+ </listitem>
+
+ <listitem>
+ <para>or we want log all debug messages for all classes in in
+ <package>exo.jcr.component.core</package>
+ component<programlisting><property
name="log4j.category.exo.jcr.component.core"
value="DEBUG"/></programlisting></para>
+ </listitem>
+
+ <listitem>
+ <para>or we want log all messages for all kernel
+ components<programlisting><property
name="log4j.category.exo.kernel"
value="DEBUG"/></programlisting></para>
+ </listitem>
+ </itemizedlist></para>
+ </section>
+ </section>
+
+ <section>
+ <title>JDK Logging</title>
+
+ <para>JDK logging (aka JUL) is the builtin logging framework introduced
+ in JDK 1.4. It is a good option for Tomcat AS.<itemizedlist>
+ <listitem>
+ <para>edit the variable <varname>LOG_OPTS</varname> in
your
+ <filename>eXo.sh</filename> or
<filename>eXo.bat</filename>
+
:<programlisting>LOG_OPTS="-Dorg.apache.commons.logging.Log=org.apache.commons.logging.impl.Jdk14Logger"</programlisting></para>
+ </listitem>
+
+ <listitem>
+ <para>Edit your
<filename>logs-configuration.xml</filename>
+ :<programlisting><component>
+
<type>org.exoplatform.services.log.LogConfigurationInitializer</type>
+ <init-params>
+ <value-param>
+ <name>logger</name>
+
<value>org.exoplatform.services.log.impl.BufferedJdk14Logger</value>
+ </value-param>
+ <value-param>
+ <name>configurator</name>
+
<value>org.exoplatform.services.log.impl.Jdk14Configurator</value>
+ </value-param>
+ <properties-param>
+ <name>properties</name>
+ <description>jdk1.4 Logger properties</description>
+ <property name="handlers"
value="java.util.logging.ConsoleHandler"/>
+ <property name=".level" value="FINE"/>
+ <property name="java.util.logging.ConsoleHandler.level"
value="FINE"/>
+ </properties-param>
+ </init-params>
+ </component></programlisting></para>
+ </listitem>
+ </itemizedlist></para>
+ </section>
+
+ <section>
+ <title>Commons Logging SimpleLog</title>
+
+ <para>SimpleLog is a minimal logging system distributed with Commons
+ Logging. To be used when nothing else is available or when you seek
+ simplicity.<programlisting> <component>
+
<type>org.exoplatform.services.log.LogConfigurationInitializer</type>
+ <init-params>
+ <value-param>
+ <name>logger</name>
+
<value>org.exoplatform.services.log.impl.BufferedSimpleLog</value>
+ </value-param>
+ <value-param>
+ <name>configurator</name>
+
<value>org.exoplatform.services.log.impl.SimpleLogConfigurator</value>
+ </value-param>
+ <properties-param>
+ <name>properties</name>
+ <description>SimpleLog properties</description>
+ <property name="org.apache.commons.logging.simplelog.defaultlog"
value="debug"/>
+ <property
name="org.apache.commons.logging.simplelog.showdatetime"
value="true"/>
+ </properties-param>
+ </init-params>
+ </component></programlisting></para>
+ </section>
+ </section>
+
+ <section>
+ <title>Tips and Troubleshooting</title>
+
+ <section>
+ <title>JBoss tips</title>
+
+ <para>If you use log4j configuration, you can change the log
+ configuration directly at runtime in:
+
<filename>JBOSS_HOME/server/default/conf/jboss-log4j.xml</filename>.<itemizedlist>
+ <listitem>
+ <para>To enable debug logs :<programlisting> <param
name="Threshold" value="DEBUG"/>
</programlisting></para>
+ </listitem>
+
+ <listitem>
+ <para>To exclude messages from unnecessary classes (server's
+ internal) modify the threshold of these classes to
"FATAL".</para>
+ </listitem>
+ </itemizedlist><tip>
+ <para>If you see only ERROR level logs while starting ear on jboss
+ (4.2.2), you have to remove log4j*.jar from your ear and
+ application.xml.</para>
+ </tip></para>
+ </section>
+
+ <section>
+ <title>Other tips</title>
+
+ <para>If you see only ERROR level logs while starting ear on jboss
+ (4.2.2), you have to remove log4j*.jar from your ear and
+ application.xml.</para>
+ </section>
+ </section>
+</chapter>
Added:
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/service-configuration-for-beginners.xml
===================================================================
---
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/service-configuration-for-beginners.xml
(rev 0)
+++
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/service-configuration-for-beginners.xml 2010-08-02
09:15:04 UTC (rev 2849)
@@ -0,0 +1,767 @@
+<?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">
+<chapter id="KernelServiceConfigurationforBeginners">
+ <?dbhtml
filename="ch-kenel-service-configuration-for-beginners.html"?>
+
+ <title>Service Configuration for Beginners</title>
+
+ <para><emphasis role="bold">Related
documents</emphasis></para>
+
+ <itemizedlist>
+ <listitem>
+ <para><link
linkend="KernelServiceConfigurationinDetail">Service
+ Configuration in Detail</link></para>
+ </listitem>
+
+ <listitem>
+ <para><link endterm="KernelServicesWiring.Title"
+
linkend="KernelServicesWiring">ServicesWiring</link></para>
+ </listitem>
+
+ <listitem>
+ <para><link linkend="KernelContainerConfiguration">Container
+ Configuration</link></para>
+ </listitem>
+ </itemizedlist>
+
+ <section>
+ <title>Objective</title>
+
+ <para>We are going to talk about service configuration. You will learn
+ about modes, services and containers, you will find out where the service
+ configuration files have to be placed and you will also see the overriding
+ mechanism of configurations. Finally you will understand how the container
+ creates the services one after the other and what <emphasis>Inversion of
+ Control</emphasis> really means.</para>
+ </section>
+
+ <section>
+ <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 eXo Portal on any application server,
+ just replace "exo-tomcat" by your folder name.</para>
+
+ <note>
+ <para>If you only installed the all-in-one package for the eXo Portal,
+ the folder paths are a slightly different. You have to replace
+ <emphasis>exo-tomcat</emphasis> by
+ <emphasis>exo-eXoPortal-2.5.1-tomcat</emphasis> (obviously depending
on
+ your version). Furthermore the webapps are delivered as war
+ files.</para>
+ </note>
+
+ <para>You certainly already discovered eXo's fisheye URL (eXo is open
+ source!) - <ulink
+
url="https://anonsvn.jboss.org/repos/exo-jcr/">https://anons...
+ - which allows you to surf in the source code of all classes, if you wish
+ to do so.</para>
+ </section>
+
+ <section>
+ <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">singlet...;,
+ 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>
+ <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>
+<component>
+<key>org.exoplatform.services.cache.CacheService</key>
+<type>org.exoplatform.services.cache.impl.CacheServiceImpl</type>
+...</programlisting>
+
+ <para>Here you will note that a service is specified between the
+ <parameter><component></parameter> tags. Each service has
got a key,
+ which defines the kind of service. As you imagine the content of the
+ <parameter><key></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><type></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><key></parameter> and
<parameter><type></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="KernelServiceConfigurationinDetail">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 eXo Portal. 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>
+ <title>Containers</title>
+
+ <para>In order to access to a service you need to use a Container. Just
+ open <ulink
+
url="https://anonsvn.jboss.org/repos/exo-jcr/kernel/trunk/exo.kernel...
+
+ <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://www.picocontainer.org/">PicoContainer</ulink> is a
framework
+ which allows eXo to apply the IoC (<link
+ linkend="KernelInversionOfControl">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 chapter.</para>
+
+ <note>
+ <para>"In your java code you have to use
<programlisting>ExoContainer myContainer =
ExoContainerContext.getCurrentContainer()</programlisting>
+ 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
+ <programlisting>MyService myService = (MyService)
myContainer.getComponentInstance(MyService.class)</programlisting>
+ You easily realize that <classname>MyService.class</classname> is the
+ name of the service interface.</para>
+ </note>
+ </section>
+
+ <section>
+ <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>/conf/configuration.xml</emphasis></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><key></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><component></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>
+ <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>Take over the configurations of the RootContainer</para>
+ </listitem>
+
+ <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 Portal 2.5)</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 eXo Portal
+ 2.5 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>As of eXo Portal 2.5 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><import>mySubConfDir/myConfig.xml</import></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>
+ <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 chapter.</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>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>StandaloneContainer.addConfigurationURL(containerConf);</programlisting>
+
+ <orderedlist>
+ <listitem>
+ <para>Take over the configurations of the RootContainer</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>Take over the configurations of the RootContainer</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>
+ <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://anonsvn.jboss.org/repos/exo-jcr/core/trunk/exo.core.com...
+
+ <para>This JDBC implementation of BaseOrganizationService interface has
+ only one constructor:</para>
+
+ <para><programlisting>public OrganizationServiceImpl(ListenerService
listenerService, DatabaseService dbService)</programlisting></para>
+
+ <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 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 one).</para>
+ </note>
+ </section>
+
+ <section>
+ <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>
+ <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="KernelServiceConfigurationinDetail">Service
Configuration
+ in Detail</link>.</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <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>
+ <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><key>org.exoplatform.services.database.jdbc.DBSchemaCreator</key>
+<type>org.exoplatform.services.database.jdbc.DBSchemaCreator</type></programlisting>
+
+ <para>The key and type tags contain equally the qualified class
+ name.</para>
+ </section>
+
+ <section>
+ <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><component>
+ ...
+ <init-params>
+ <value-param>
+ <name>simple_param</name>
+ <value>${simple_param_value}</value>
+ </value-param>
+ <properties-param>
+ <name>properties_param</name>
+ <property name="value_1"
value="properties_param_value_1"/>
+ <property name="value_2"
value="${properties_param_value_2}"/>
+ </properties-param>
+ <object-param>
+ <name>object_param</name>
+ <object type="org.exoplatform.xml.test.Person">
+ <field
name="address"><string>${person_address}</string></field>
+ <field
name="male"><boolean>${person_male}</boolean></field>
+ <field
name="age"><int>${age_value}</int></field>
+ <field
name="size"><double>${size_value}</double></field>
+ </object>
+ </object-param>
+ </init-params>
+</component></programlisting>
+ </section>
+
+ <section>
+ <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>
+ <title>Further Reading</title>
+
+ <para>Do you feel an expert now? Not yet. Get a deeper look and read this
+ <link linkend="KernelServicesWiring">Services Wiring</link>
article. You
+ read so much about configuration, that you should wonder what the <link
+ linkend="KernelConfigurationNamespace">XML Schema of the configuration
+ file</link> looks like. </para>
+
+ <para>If you wish to see a examples of service configurations you should
+ study the <link linkend="Core">Core.</link> Where you find
descriptions of
+ some eXo's core services. Finally you might wish to read more about <ulink
+
url="http://www.picocontainer.org/">PicoContainer</ulink&...
+ </section>
+</chapter>
Added:
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/service-configuration-in-detail.xml
===================================================================
---
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/service-configuration-in-detail.xml
(rev 0)
+++
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/service-configuration-in-detail.xml 2010-08-02
09:15:04 UTC (rev 2849)
@@ -0,0 +1,701 @@
+<?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">
+<chapter id="KernelServiceConfigurationinDetail">
+ <?dbhtml filename="ch-kenel-service-configuration-in-detail.html"?>
+
+ <title>Service Configuration in Detail</title>
+
+ <para><emphasis role="bold">Related
documents</emphasis></para>
+
+ <itemizedlist>
+ <listitem>
+ <para><link
linkend="KernelServiceConfigurationforBeginners">Service
+ Configuration for Beginners</link></para>
+ </listitem>
+
+ <listitem>
+ <para><link linkend="KernelServicesWiring">Services
Wiring</link></para>
+ </listitem>
+
+ <listitem>
+ <para><link linkend="KernelConfigurationNamespace">Kernel
Configuration
+ File</link></para>
+ </listitem>
+ </itemizedlist>
+
+ <section id="Objectives">
+ <title>Objectives</title>
+
+ <para>This article shows in the first chapters how to setup a sample
+ service with some configurations and how to access to the configuration
+ parameters. The later chapters describe all details of the configuration
+ file (parameters, object-params, plugins, imports, etc.) it also shows how
+ to access the configuration values. You may consider this article as a
+ <emphasis role="bold">reference</emphasis>, but you can also
use this
+ article as a <emphasis role="bold">tutorial</emphasis> and read
it from
+ the beginning to the end.</para>
+ </section>
+
+ <section id="Requirements">
+ <title>Requirements</title>
+
+ <para>You should have read and understood <link
+ linkend="KernelServiceConfigurationforBeginners">Service Configuration
for
+ Beginners</link>. Obviously you should know java and xml. We are working
+ with examples that are created for teaching reasons only and you will see
+ extracts from the eXo Products default installation. When reading do not
+ forget that the terms service and component are interchangeable in eXo
+ Products.</para>
+ </section>
+
+ <section id="SampleService">
+ <title>Sample Service</title>
+
+ <section id="JavaClass">
+ <title>Java Class</title>
+
+ <para>Imagine you are working for a publishing company called "La
+ Verdad" that is going to use eXo platform. Your boss asks you be able to
+ calculate the number of sentences of an article.</para>
+
+ <para>You remember in eXo product everything is a <emphasis
+ role="bold">service</emphasis> so you decide to create a simple
class.
+ In future you want to be able to plug different implementations of your
+ service, so that you should define an <emphasis
+ role="bold">interface</emphasis> that defines your
service.</para>
+
+ <programlisting>package com.laverdad.services;
+public interface ArticleStatsService {
+ public abstract int calcSentences(String article);
+}</programlisting>
+
+ <para>A very simple implementation:</para>
+
+ <programlisting>public class ArticleStatsServiceImpl implements
ArticleStatsService {
+ public int calcSentences(String article) {
+ throw new RuntimeException("Not implemented");
+ }
+}</programlisting>
+
+ <para>That's it! You see there are no special prerequisites for a
+ service.</para>
+
+ <para>You should already have prepared your working environment, where
+ you have a base folder (let's call it our service base folder). If you
+ wish to try out this example create this class in the
+ com/laverdad/services/ArticleStatsService subfolder.</para>
+ </section>
+
+ <section id="Firstconfigurationfile">
+ <title>First configuration file</title>
+
+ <para>When creating a service you also should declare its existence to
+ the <emphasis role="bold">Container</emphasis>, therefore you
create a
+ first simple configuration file. Copy the following code to a file that
+ is called "configuration.xml" and place this file in a /conf
+ subdirectory of your service base folder. As you already know the
+ container looks for a "/conf/configuration.xml" file in each
+ jar-file.</para>
+
+ <programlisting><?xml version="1.0"
encoding="UTF8"?>
+<configuration
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://www.exoplaform.org/xml/ns/kernel_1_0.xsd
http://www.exoplaform.org/xml/ns/kernel_1_0.xsd"
+ xmlns="http://www.exoplaform.org/xml/ns/kernel_1_0.xsd">
+ <component>
+ <key>com.laverdad.services.ArticleStatsService</key>
+
<type>com.laverdad.services.ArticleStatsServiceImpl</type>
+ </component>
+</configuration></programlisting>
+
+ <note>
+ <para>You are correctly using the namespace of the configuration
+ schema (
<uri>http://www.exoplaform.org/xml/ns/kernel_1_1.xsd</uri>).
+ Most of the configuration schema is explained in this
+ articles,therefore you do not need to open and understand the schema.
+ For backward compatibility it is not necessary to declare the
+ schema.</para>
+
+ <para>When eXo kernel reads a configuration it loads the file from the
+ kernel jar using the classloader and does not use an internet
+ connection to resolve the file.</para>
+ </note>
+ </section>
+
+ <section id="InitParameters">
+ <title>Init Parameters</title>
+
+ <para>You see your service has a configuration file, but you wonder how
+ the file could possibly access to its configuration. Imagine you are
+ asked to implement two different calculation methods: fast and
+ exact.</para>
+
+ <para>You create one init parameter containing the calculation methods.
+ For the exact method you wish to configure more details for the service.
+ Let's enhance the word service configuration file:</para>
+
+ <programlisting> <component>
+ <key>com.laverdad.services.ArticleStatsService</key>
+
<type>com.laverdad.services.ArticleStatsServiceImpl</type>
+ <init-params>
+ <value-param>
+ <name>calc-method</name>
+ <description>calculation method: fast,
exact</description>
+ <value>fast</value>
+ </value-param>
+ <properties-param>
+ <name>details-for-exact-method</name>
+ <description>details for exact phrase
counting</description>
+ <property name="language" value="English" />
+ <property name="variant" value="us" />
+ </properties-param>
+ </init-params>
+ </component></programlisting>
+
+ <note>
+ <para>When configuring your service, you are <emphasis
+ role="bold">totally free</emphasis>. You can provide as many
<emphasis
+ role="bold">value-param</emphasis>, <emphasis
+ role="bold">property-param</emphasis>, and <emphasis
+ role="bold">properties</emphasis> you wish and you can give
them any
+ names or values. You only must respect the xml structure.</para>
+ </note>
+
+ <para>Now let's see how our service can read this configuration. The
+ implementation of the calcSentences() method serves just as a simple
+ example. It's up to your imagination to implement the exact
+ method.</para>
+
+ <programlisting>public class ArticleStatsServiceImpl implements
ArticleStatsService {
+
+ private String calcMethod = "fast";
+ private String variant = "French";
+ private String language = "France";
+
+ public ArticleStatsServiceImpl(InitParams initParams) {
+ super();
+ calcMethod = initParams.getValueParam("calc-method").getValue();
+ PropertiesParam detailsForExactMethod =
initParams.getPropertiesParam("details-for-exact-method");
+ if ( detailsForExactMethod != null) {
+ language = detailsForExactMethod.getProperty("language");
+ variant = detailsForExactMethod.getProperty("variant");
+ }
+ }
+
+ public int calcSentences(String article) {
+ if (calcMethod == "fast") {
+ // just count the number of periods "."
+ int res = 0;
+ int period = article.indexOf('.');
+ while (period != -1) {
+ res++;
+ article = article.substring(period+1);
+ period = article.indexOf('.');
+ }
+ return res;
+ }
+ throw new RuntimeException("Not implemented");
+ }
+}</programlisting>
+
+ <para>You see you just have to declare a parameter of
+ org.exoplatform.container.xml.InitParams in your constructor. The
+ container provides an InitParams object that correspond to the xml tree
+ of init-param.</para>
+ </section>
+
+ <section id="ServiceAccess">
+ <title>Service Access</title>
+
+ <para>As you want to follow the principle of <emphasis
+ role="bold">Inversion of Control</emphasis> you <emphasis
+ role="bold">must not</emphasis> access the service directly. You
need a
+ <emphasis role="bold">Container</emphasis> to access the
service.</para>
+
+ <para>With this command you get your current container:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><emphasis role="bold">ExoContainer myContainer =
+ ExoContainerContext.getCurrentContainer();</emphasis></para>
+ </listitem>
+ </itemizedlist>
+
+ <para>This might be a PortalContainer or a StandaloneContainer,
+ dependant on the <link
+
linkend="Kernel.ServiceConfigurationinDetail.ExecutionModes">execution
+ mode</link> in which you are running your application.</para>
+
+ <para>Whenever you need one of the services that you have configured use
+ the method:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><emphasis
+
role="bold">myContainer.getComponentInstance(class)</emphasis></para>
+ </listitem>
+ </itemizedlist>
+
+ <para>In our case:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><emphasis role="bold">ArticleStatsService
statsService =
+ (ArticleStatsService)
+
myContainer.getComponentInstance(ArticleStatsService.class);</emphasis></para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Recapitulation:</para>
+
+ <programlisting>package com.laverdad.common;
+
+import org.exoplatform.container.ExoContainer;
+import org.exoplatform.container.ExoContainerContext;
+import com.laverdad.services.*;
+
+public class Statistics {
+
+ public int makeStatistics(String articleText) {
+ ExoContainer myContainer = ExoContainerContext.getCurrentContainer();
+ ArticleStatsService statsService = (ArticleStatsService)
+ myContainer.getComponentInstance(ArticleStatsService.class);
+ int numberOfSentences = statsService.calcSentences(articleText);
+ return numberOfSentences;
+ }
+
+ public static void main( String args[]) {
+ Statistics stats = new Statistics();
+ String newText = "This is a normal text. The method only counts the number of
periods. "
+ + "You can implement your own implementation with a more exact counting. "
+ + "Let`s make a last sentence.";
+ System.out.println("Number of sentences: " + stats.makeStatistics(newText));
+ }
+}</programlisting>
+
+ <para>If you test this sample in standalone mode, you need to put all
+ jars of eXo Kernel in your buildpath, furthermore picoContainer is
+ needed.</para>
+ </section>
+ </section>
+
+ <section id="Parameters">
+ <title>Parameters</title>
+
+ <section id="ValueParam">
+ <title>Value-Param</title>
+
+ <para>There is an value-param example:</para>
+
+ <programlisting> <component>
+ <key>org.exoplatform.portal.config.UserACL</key>
+ <type>org.exoplatform.portal.config.UserACL</type>
+ <init-params>
+...
+ <value-param>
+ <name>access.control.workspace</name>
+ <description>groups with memberships that have the right to access
the User Control Workspace</description>
+
<value>*:/platform/administrators,*:/organization/management/executive-board</value>
+ </value-param>
+...
+ </component></programlisting>
+
+ <para>The UserACL class accesses to the <emphasis
+ role="bold">value-param</emphasis> in its
constructor.</para>
+
+ <programlisting>package org.exoplatform.portal.config;
+public class UserACL {
+
+ public UserACL(InitParams params) {
+ UserACLMetaData md = new UserACLMetaData();
+ ValueParam accessControlWorkspaceParam =
params.getValueParam("access.control.workspace");
+ if(accessControlWorkspaceParam != null)
md.setAccessControlWorkspace(accessControlWorkspaceParam.getValue());
+...</programlisting>
+ </section>
+
+ <section id="PropertiesParam">
+ <title>Properties-Param</title>
+
+ <para>Properties are name-value pairs. Both the name and the value are
+ Java Strings.</para>
+
+ <para>Here you see the hibernate configuration example:</para>
+
+ <programlisting> <component>
+
<key>org.exoplatform.services.database.HibernateService</key>
+
<type>org.exoplatform.services.database.impl.HibernateServiceImpl</type>
+ <init-params>
+ <properties-param>
+ <name>hibernate.properties</name>
+ <description>Default Hibernate Service</description>
+ <property name="hibernate.show_sql"
value="false"/>
+ <property name="hibernate.cglib.use_reflection_optimizer"
value="true"/>
+ <property name="hibernate.connection.url"
value="jdbc:hsqldb:file:../temp/data/exodb"/>
+ <property name="hibernate.connection.driver_class"
value="org.hsqldb.jdbcDriver"/>
+...
+ </properties-param>
+ </init-params>
+ </component></programlisting>
+
+ <para>In the org.exoplatform.services.database.impl.HibernateServiceImpl
+ you will find that the name "hibernate.properties" of the
+ properties-param is used to access the properties.</para>
+
+ <programlisting>package org.exoplatform.services.database.impl;
+
+public class HibernateServiceImpl implements HibernateService, ComponentRequestLifecycle
{
+ public HibernateServiceImpl(InitParams initParams, CacheService cacheService) {
+ PropertiesParam param =
initParams.getPropertiesParam("hibernate.properties");
+...
+}</programlisting>
+ </section>
+
+ <section id="ObjectParam">
+ <title>Object-Param</title>
+
+ <para>Let's have a look at the configuration of the LDAPService.
It's
+ not important to know LDAP, we only discuss the parameters.</para>
+
+ <programlisting>
+<component>
+ <key>org.exoplatform.services.ldap.LDAPService</key>
+
<type>org.exoplatform.services.ldap.impl.LDAPServiceImpl</type>
+ <init-params>
+ <object-param>
+ <name>ldap.config</name>
+ <description>Default ldap config</description>
+ <object
type="org.exoplatform.services.ldap.impl.LDAPConnectionConfig">
+ <field
name="providerURL"><string>ldaps://10.0.0.3:636</string></field>
+ <field
name="rootdn"><string>CN=Administrator,CN=Users,DC=exoplatform,DC=org</string></field>
+ <field
name="password"><string>exo</string></field>
+ <field
name="version"><string>3</string></field>
+ <field
name="minConnection"><int>5</int></field>
+ <field
name="maxConnection"><int>10</int></field>
+ <field
name="referralMode"><string>ignore</string></field>
+ <field
name="serverName"><string>active.directory</string></field>
+ </object>
+ </object-param>
+ </init-params>
+</component></programlisting>
+
+ <para>You see here an <emphasis
role="bold">object-param</emphasis> is
+ being used to pass the parameters inside an object (actually a java
+ bean). It consists of a <emphasis
role="bold">name</emphasis>, a
+ <emphasis role="bold">description</emphasis> and exactly one
<emphasis
+ role="bold">object</emphasis>. The object defines the
<emphasis
+ role="bold">type</emphasis> and a number of <emphasis
+ role="bold">fields</emphasis>.</para>
+
+ <para>Here you see how the service accesses the object:</para>
+
+ <programlisting>package org.exoplatform.services.ldap.impl;
+
+public class LDAPServiceImpl implements LDAPService {
+...
+ public LDAPServiceImpl(InitParams params) {
+ LDAPConnectionConfig config = (LDAPConnectionConfig)
params.getObjectParam("ldap.config")
+ .getObject();
+...</programlisting>
+
+ <para>The passed object is LDAPConnectionConfig which is a classic
+ <emphasis role="bold">java bean</emphasis>. It contains all
fields and
+ also the appropriate getters and setters (not listed here). You also can
+ provide default values. The container creates a new instance of your
+ bean and calls all setters whose values are configured in the
+ configuration file.</para>
+
+ <programlisting>package org.exoplatform.services.ldap.impl;
+
+public class LDAPConnectionConfig {
+ private String providerURL = "ldap://127.0.0.1:389";
+ private String rootdn;
+ private String password;
+ private String version;
+ private String authenticationType = "simple";
+ private String serverName = "default";
+ private int minConnection;
+ private int maxConnection;
+ private String referralMode = "follow";
+...</programlisting>
+
+ <para>You see that the types (String, int) of the fields in the
+ configuration correspond with the bean. A short glance in the
+ kernel_1_0.xsd file let us discover more simple types:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><emphasis role="bold">string, int, long, boolean,
date,
+ double</emphasis></para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Have a look on this type test xml file: <ulink
+
url="https://anonsvn.jboss.org/repos/exo-jcr/kernel/trunk/exo.kernel...
+ </section>
+
+ <section id="Collection">
+ <title>Collection</title>
+
+ <para>You also can use java collections to configure your service. In
+ order to see an example let's open the
+ database-organization-configuration.xml file. This file defines a
+ default user organization (users, groups, memberships/roles) of your
+ portal. They use component-plugins which are explained later. You wil
+ see that object-param is used again.</para>
+
+ <para>There are two collections: The first collection is an <emphasis
+ role="bold">ArrayList</emphasis>. This ArrayList contains only
one
+ value, but there could be more. The only value is an object which
+ defines the field of the NewUserConfig$JoinGroup bean.</para>
+
+ <para>The second collection is a <emphasis
+ role="bold">HashSet</emphasis> that is a set of
strings.</para>
+
+ <programlisting> <component-plugin>
+ <name>new.user.event.listener</name>
+ <set-method>addListenerPlugin</set-method>
+
<type>org.exoplatform.services.organization.impl.NewUserEventListener</type>
+ <description>this listener assign group and membership to a new
created user</description>
+ <init-params>
+ <object-param>
+ <name>configuration</name>
+ <description>description</description>
+ <object
type="org.exoplatform.services.organization.impl.NewUserConfig">
+ <field name="group">
+ <collection type="java.util.ArrayList">
+ <value>
+ <object
type="org.exoplatform.services.organization.impl.NewUserConfig$JoinGroup">
+ <field
name="groupId"><string>/platform/users</string></field>
+ <field
name="membership"><string>member</string></field>
+ </object>
+ </value>
+ </collection>
+ </field>
+ <field name="ignoredUser">
+ <collection type="java.util.HashSet">
+
<value><string>root</string></value>
+
<value><string>john</string></value>
+
<value><string>marry</string></value>
+
<value><string>demo</string></value>
+
<value><string>james</string></value>
+ </collection>
+ </field>
+ </object>
+ </object-param>
+ </init-params>
+ </component-plugin></programlisting>
+
+ <para>Let's look at the
+ org.exoplatform.services.organization.impl.NewUserConfig bean:</para>
+
+ <programlisting>public class NewUserConfig {
+ private List role;
+ private List group;
+ private HashSet ignoredUser;
+
+ ...
+
+ public void setIgnoredUser(String user) {
+ ignoredUser.add(user);
+
+ ...
+
+ static public class JoinGroup {
+ public String groupId;
+ public String membership;
+ ...
+}</programlisting>
+
+ <para>You see the values of the HashSet are set one by one by the
+ container, and it's the responsibility of the bean to add these values
+ to its HashSet.</para>
+
+ <para>The JoinGroup object is just an inner class and implements a bean
+ of its own. It can be accessed like any other inner class using
+ NewUserConfig.JoinGroup.</para>
+ </section>
+ </section>
+
+ <section id="ExternalPlugin">
+ <title>External Plugin</title>
+
+ <para>The External Plugin allows you to add configuration on the
+ fly.</para>
+
+ <para>As you have carefully read <link
+ linkend="KernelServiceConfigurationforBeginners">Service Configuration
for
+ Beginners</link> you know that <emphasis
role="bold">normally</emphasis>
+ newer configurations always <emphasis
role="bold">replaces</emphasis>
+ previous configurations. An external plugin allows you to <emphasis
+ role="bold">add</emphasis> configuration without replacing
previous
+ configurations.</para>
+
+ <para>That can be interesting if you adapt a service configuration for
+ your project-specific needs (country, language, branch, project,
+ etc.).</para>
+
+ <para>Let's have a look at the configuration of the TaxonomyPlugin of the
+ CategoriesService:</para>
+
+ <programlisting> <external-component-plugins>
+
<target-component>org.exoplatform.services.cms.categories.CategoriesService</target-component>
+ <component-plugin>
+ <name>predefinedTaxonomyPlugin</name>
+ <set-method>addTaxonomyPlugin</set-method>
+
<type>org.exoplatform.services.cms.categories.impl.TaxonomyPlugin</type>
+ <init-params>
+ <value-param>
+ <name>autoCreateInNewRepository</name>
+ <value>true</value>
+ </value-param>
+ <value-param>
+ <name>repository</name>
+ <value>repository</value>
+ </value-param>
+ <object-param>
+ <name>taxonomy.configuration</name>
+ <description>configuration predefined taxonomies to inject in
jcr</description>
+ <object
type="org.exoplatform.services.cms.categories.impl.TaxonomyConfig">
+ <field name="taxonomies">
+ <collection type="java.util.ArrayList">
+ <!-- cms taxonomy -->
+ <value>
+ <object
type="org.exoplatform.services.cms.categories.impl.TaxonomyConfig$Taxonomy">
+ <field
name="name"><string>cmsTaxonomy</string></field>
+ <field
name="path"><string>/cms</string></field>
+ </object>
+ </value>
+ <value>
+ <object
type="org.exoplatform.services.cms.categories.impl.TaxonomyConfig$Taxonomy">
+ <field
name="name"><string>newsTaxonomy</string></field>
+ <field
name="path"><string>/cms/news</string></field>
+ </object>
+ </value>
+ </field>
+ </object>
+ </object-param>
+ </init-params>
+ </component-plugin>
+<external-component-plugins></programlisting>
+
+ <para>The <emphasis
role="bold"><target-component></emphasis>
+ defines the service for which the plugin is defined. The configuration is
+ injected by the container using a method that is defined in <emphasis
+ role="bold"><set-method></emphasis>. The method has
exactly one
+ argument of the type
+ org.exoplatform.services.cms.categories.impl.TaxonomyPlugin:</para>
+
+ <itemizedlist>
+ <listitem>
+
<para>addTaxonomyPlugin(org.exoplatform.services.cms.categories.impl.TaxonomyPlugin
+ plugin)</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>The content of <emphasis
role="bold"><init-params></emphasis>
+ corresponds to the structure of the TaxonomyPlugin object.</para>
+
+ <para>#info("You can configure the component CategoriesService using the
+ addTaxonomyPlugin as often as you wish, you can also call
+ addTaxonomyPlugin in different configuration files. The method
+ addTaxonomyPlugin is then called several times, everything else depends on
+ the implementation of the method")</para>
+ </section>
+
+ <section id="Import">
+ <title>Import</title>
+
+ <para>The import tag allows to link to other configuration files. These
+ imported files can be placed anywhere. If you write a default
+ configuration which is part of your jar file you should not import files
+ from outside your jar.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><emphasis role="bold">war</emphasis>: Imports
from <emphasis
+ role="bold">portal.war/WEB-INF</emphasis></para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">jar</emphasis> or
<emphasis
+ role="bold">classpath</emphasis>: Uses the <emphasis
+ role="bold">classloader</emphasis>, you can use this prefix in
the
+ default configuration for importing an other configuration file which
+ is accessible by the classloader.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">file</emphasis>: Uses an
<emphasis
+ role="bold">absolute path</emphasis>, you also can put a
<emphasis
+ role="bold">URL</emphasis>.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">without any
prefix</emphasis>:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Standalone mode: <emphasis role="bold">user
+ directory</emphasis></para>
+ </listitem>
+
+ <listitem>
+ <para>Portal mode: $AS-HOME, that means the application server
+ home, for example " <emphasis
+ role="bold">exo-tomcat</emphasis>".</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </itemizedlist>
+
+ <para>If you open the
+ "portal/trunk/web/portal/src/main/webapp/WEB-INF/conf.configuration.xml"
+ you will see that it consists only of imports:
<programlisting><import>war:/conf/common/common-configuration.xml</import>
+<import>war:/conf/common/logs-configuration.xml</import>
+<import>war:/conf/database/database-configuration.xml</import>
+<import>war:/conf/jcr/jcr-configuration.xml</import>
+<import>war:/conf/common/portlet-container-configuration.xml</import>
+... </programlisting></para>
+ </section>
+
+ <section id="Systemproperties">
+ <title>System 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. This makes it
+ possible to resolve properties at runtime instead of providing a value at
+ packaging time.</para>
+
+ <para>In
+
portal/trunk/web/portal/src/main/webapp/WEB-INF/conf/database/database-configuration.tmpl.xml
+ you find an example for system properties:</para>
+
+ <programlisting> <component>
+
<key>org.exoplatform.services.database.HibernateService</key>
+ <jmx-name>database:type=HibernateService</jmx-name>
+
<type>org.exoplatform.services.database.impl.HibernateServiceImpl</type>
+ <init-params>
+ <properties-param>
+ <name>hibernate.properties</name>
+ <description>Default Hibernate Service</description>
+...
+ <property name="hibernate.connection.url"
value="${connectionUrl}"/>
+ <property name="hibernate.connection.driver_class"
value="${driverClass}"/>
+ <property name="hibernate.connection.username"
value="${username}"/>
+ <property name="hibernate.connection.password"
value="${password}"/>
+ <property name="hibernate.dialect"
value="${dialect}"/>
+...
+ </properties-param>
+ </init-params>
+ </component></programlisting>
+
+ <para>As these are system properties you use the -D command: <emphasis
+ role="bold">java -DconnectionUrl=jdbc:hsqldb:file:../temp/data/exodb
+ -DdriverClass=org.hsqldb.jdbcDriver</emphasis> Or better use the
+ parameters of eXo.bat / eXo.sh when you start eXo Portal: <emphasis
+ role="bold">set
+ EXO_OPTS="-DconnectionUrl=jdbc:hsqldb:file:../temp/data/exodb
+ -DdriverClass=org.hsqldb.jdbcDriver"</emphasis></para>
+ </section>
+</chapter>
Added:
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/services-wiring.xml
===================================================================
---
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/services-wiring.xml
(rev 0)
+++
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/services-wiring.xml 2010-08-02
09:15:04 UTC (rev 2849)
@@ -0,0 +1,201 @@
+<?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">
+<chapter id="KernelServicesWiring">
+ <?dbhtml filename="ch-kenel-services-wiring.html"?>
+
+ <title id="KernelServicesWiring.Title">Services Wiring</title>
+
+ <section>
+ <title>Overview</title>
+
+ <para>The container package is responsible of building a hierarchy of
+ containers. Each service will then be registered in one container or the
+ other according to the XML configuration file it is defined in. It is
+ important to understand that there can be several PortalContainer
+ instances that all are children of the RootContainer.</para>
+
+ <para>The behavior of the hierarchy is similar to a class loader one,
+ hence when you will lookup a service that depends on another one, the
+ container will look for it in the current container and if it does not
+ find it then it will look in the parent container. That way you can load
+ all the reusable business logic components in the same container (here the
+ RootContainer) and differentiate the service implementation from one
+ portal instance to the other by just loading different service
+ implementations in two sibling PortalContainers.</para>
+
+ <para>Therefore, if you look at the Portal Container as a service
+ repository for all the business logic in a portal instance then you
+ understand why having several PortalContainers allows you to manage
+ several portals (each one deployed as a single war) in the same server by
+ just changing XML configuration files.</para>
+
+ <para>The default configuration XML files are packaged in the service jar.
+ There are three configuration.xml files, one for each container type. In
+ that XML file, we define the list of services and their init parameters
+ that will be loaded in the corresponding container.</para>
+ </section>
+
+ <section>
+ <title>Portal Instance</title>
+
+ <para>As there can be several portal container instances per JVM it is
+ important to be able to configure the loaded services per instance.
+ Therefore all the default configuration files located in the service impl
+ jar can be overridden from the portal war. For more information refer to
+ <link linkend="KernelServiceConfigurationforBeginners">Service
+ Configuration for Beginners</link>.</para>
+ </section>
+
+ <section>
+ <title>Introduction to the XML schema of the configuration.xml
+ file</title>
+
+ <para>After deploying you find the configuration.xml file in
+ webapps/portal/WEB-INF/conf Use component registration tags. Let's look at
+ the key tag that defines the interface and the type tag that defines the
+ implementation. Note that the key tag is not mandatory, but its use
+ improves performance.</para>
+
+ <programlisting><!-- Portlet container hooks -->
+ <component>
+
<key>org.exoplatform.services.portletcontainer.persistence.PortletPreferencesPersister</key>
+
<type>org.exoplatform.services.portal.impl.PortletPreferencesPersisterImpl</type>
+ </component></programlisting>
+
+ <para>Register plugins that can act as listeners or external plugin to
+ bundle some plugin classes in other jar modules. The usual example is the
+ hibernate service to which we can add hbm mapping files even if those are
+ deployed in an other maven artifact.</para>
+
+ <programlisting><external-component-plugins>
+
<target-component>org.exoplatform.services.database.HibernateService</target-component>
+ <component-plugin>
+ <name>add.hibernate.mapping</name>
+ <set-method>addPlugin</set-method>
+
<type>org.exoplatform.services.database.impl.AddHibernateMappingPlugin</type>
+ <init-params>
+ <values-param>
+ <name>hibernate.mapping</name>
+
<value>org/exoplatform/services/portal/impl/PortalConfigData.hbm.xml</value>
+
<value>org/exoplatform/services/portal/impl/PageData.hbm.xml</value>
+
<value>org/exoplatform/services/portal/impl/NodeNavigationData.hbm.xml</value>
+ </values-param>
+ </init-params>
+ </component-plugin>
+</external-component-plugins></programlisting>
+
+ <para>In that sample we target the HibernateService and we will call its
+ addPlugin() method with an argument of the type AddHibernateMappingPlugin.
+ That object will first have been filled with the init parameters.</para>
+
+ <para>Therefore, it is possible to define services that will be able to
+ receive plugins without implementing any framework interface.</para>
+
+ <para>Another example of use is the case of listeners as in the following
+ code where a listener is added to the OrganisationService and will be
+ called each time a new user is created:</para>
+
+ <programlisting><external-component-plugins>
+
<target-component>org.exoplatform.services.organization.OrganizationService</target-component>
+ <component-plugin>
+ <name>portal.new.user.event.listener</name>
+ <set-method>addListenerPlugin</set-method>
+
<type>org.exoplatform.services.portal.impl.PortalUserEventListenerImpl</type>
+ <description>this listener create the portal configuration for the new
user</description>
+ <init-params>
+ <object-param>
+ <name>configuration</name>
+ <description>description</description>
+ <object
type="org.exoplatform.services.portal.impl.NewPortalConfig">
+ <field name="predefinedUser">
+ <collection type="java.util.HashSet">
+
<value><string>admin</string></value>
+
<value><string>exo</string></value>
+
<value><string>company</string></value>
+
<value><string>community</string></value>
+
<value><string>portal</string></value>
+
<value><string>exotest</string></value>
+ </collection>
+ </field>
+ <field
name="templateUser"><string>template</string></field>
+ <field
name="templateLocation"><string>war:/conf/users</string></field>
+ </object>
+ </object-param>
+ </init-params>
+ </component-plugin>
+...</programlisting>
+
+ <para>In the previous XML configuration we reference the organization
+ service and we will call its method addListenerPlugin with an object of
+ type PortalUserEventListenerImpl. Each time a new user will be created
+ (apart the predefined ones in the list above) methods of the
+ PortalUserEventListenerImpl will be called by the service.</para>
+
+ <para>As you can see there are several types of init parameters, from a
+ simple value param which binds a key with a value to a more complex object
+ mapping that fills a JavaBean with the info defined in the XML.</para>
+
+ <para>Many other examples exist such as for the Scheduler Service where
+ you can add a job with a simple XML configuration or the JCR Service where
+ you can add a NodeType from your own configuration.xml file.</para>
+ </section>
+
+ <section>
+ <title>JMX auto wiring</title>
+
+ <para>For JMX wiring please refer to <link
+ linkend="KernelJMXMBeanServer">JMX MBean
Server</link>.</para>
+ </section>
+
+ <section>
+ <title>Configuration retrieval and log of this retrieval</title>
+
+ <para>When the RootContainer is starting the configuration retrieval looks
+ for configuration files in each jar available from the classpath at jar
+ path /conf/portal/configuration.xml and from each war at path
+ /WEB-INF/conf/configuration.xml. These configurations are added to a set.
+ If a component was configured in a previous jar and the current jar
+ contains a new configuration of that component the latest (from the
+ current jar) will replace the previous configuration.</para>
+
+ <para>After the processing of all configurations available on the system
+ the container will initialize it and start each component in order of the
+ dependency injection (DI).</para>
+
+ <para>So, in general the user/developer should be careful when configuring
+ the same components in different configuration files. It's recommended to
+ configure service in its own jar only. Or, in case of a portal
+ configuration, strictly reconfigure the component in portal files.</para>
+
+ <para>But, there are components that can be (or should be) configured more
+ than one time. This depends on the business logic of the component. A
+ component may initialize the same resource (shared with other players) or
+ may add a particular object to a set of objects (shared with other players
+ too). In the first case it's critical who will be the last, i.e. whose
+ configuration will be used. In second case it doesn't matter who is the
+ first and who is the last (if the parameter objects are
+ independent).</para>
+
+ <para>In case of problems with configuration of component it's important
+ to know from which jar/war it comes. For that purpose user/developer can
+ set JVM system property <emphasis
+
role="bold">org.exoplatform.container.configuration.debug</emphasis>,
in
+ command line:</para>
+
+ <programlisting>java -Dorg.exoplatform.container.configuration.debug
...</programlisting>
+
+ <para>With that property container configuration manager will report
+ configuration adding 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>
+</chapter>
Modified:
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/transaction-service.xml
===================================================================
---
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/transaction-service.xml 2010-08-01
15:20:33 UTC (rev 2848)
+++
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/transaction-service.xml 2010-08-02
09:15:04 UTC (rev 2849)
@@ -1,65 +1,65 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
-"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
-<chapter id="ch_transaction_service">
- <?dbhtml filename="ch-tranasction-service.html"?>
-
- <title>TransactionService</title>
-
- <section>
- <title>Base information</title>
-
- <para>TransactionServices provides acces to XA TransactionManager and
- UserTransaction (See JTA specification for details).</para>
-
- <table>
- <title>List methods</title>
-
- <tgroup cols="2">
- <tbody>
- <row>
- <entry>getTransactionManager()</entry>
-
- <entry>Get used TransactionManager</entry>
- </row>
-
- <row>
- <entry>getUserTransaction()</entry>
-
- <entry>Get UserTransaction on TransactionManager</entry>
- </row>
-
- <row>
- <entry>getDefaultTimeout()</entry>
-
- <entry>Return default TimeOut</entry>
- </row>
-
- <row>
- <entry>setTransactionTimeout(int seconds)</entry>
-
- <entry>Set TimeOut in second</entry>
- </row>
-
- <row>
- <entry>enlistResource(ExoResource xares)</entry>
-
- <entry>Enlist XA resource in TransactionManager</entry>
- </row>
-
- <row>
- <entry>delistResource(ExoResource xares)</entry>
-
- <entry>Delist XA resource from TransactionManager</entry>
- </row>
-
- <row>
- <entry>createXid()</entry>
-
- <entry>Creates unique XA transaction identifier.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
-</chapter>
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<chapter id="KernelTransactionService">
+ <?dbhtml filename="ch-kernel-tranasction-service.html"?>
+
+ <title>TransactionService</title>
+
+ <section>
+ <title>Base information</title>
+
+ <para>TransactionServices provides acces to XA TransactionManager and
+ UserTransaction (See JTA specification for details).</para>
+
+ <table>
+ <title>List methods</title>
+
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>getTransactionManager()</entry>
+
+ <entry>Get used TransactionManager</entry>
+ </row>
+
+ <row>
+ <entry>getUserTransaction()</entry>
+
+ <entry>Get UserTransaction on TransactionManager</entry>
+ </row>
+
+ <row>
+ <entry>getDefaultTimeout()</entry>
+
+ <entry>Return default TimeOut</entry>
+ </row>
+
+ <row>
+ <entry>setTransactionTimeout(int seconds)</entry>
+
+ <entry>Set TimeOut in second</entry>
+ </row>
+
+ <row>
+ <entry>enlistResource(ExoResource xares)</entry>
+
+ <entry>Enlist XA resource in TransactionManager</entry>
+ </row>
+
+ <row>
+ <entry>delistResource(ExoResource xares)</entry>
+
+ <entry>Delist XA resource from TransactionManager</entry>
+ </row>
+
+ <row>
+ <entry>createXid()</entry>
+
+ <entry>Creates unique XA transaction identifier.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+</chapter>
Added:
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/understanding-listnerservice.xml
===================================================================
---
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/understanding-listnerservice.xml
(rev 0)
+++
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel/understanding-listnerservice.xml 2010-08-02
09:15:04 UTC (rev 2849)
@@ -0,0 +1,219 @@
+<?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">
+<chapter id="KernelUnderstandingtheListenerService">
+ <?dbhtml filename="ch-kenel-understanding-listeners-service.html"?>
+
+ <title>Understanding the ListenerService</title>
+
+ <para><emphasis role="bold">Related
documents</emphasis></para>
+
+ <itemizedlist>
+ <listitem>
+ <para><link
linkend="KernelServiceConfigurationforBeginners">Service
+ Configuration for Beginners</link></para>
+ </listitem>
+
+ <listitem>
+ <para><link
linkend="KernelServiceConfigurationinDetail">Service
+ Configuration in Detail</link></para>
+ </listitem>
+
+ <listitem>
+ <para><link linkend="KernelContainerConfiguration">Container
+ Configuration</link></para>
+ </listitem>
+ </itemizedlist>
+
+ <section>
+ <title>Objectives</title>
+
+ <para>This article will first describe how the ListenerService works then
+ it will show you how to configure the ListenerService.</para>
+ </section>
+
+ <section>
+ <title>What is the ListenerService ?</title>
+
+ <para>Inside eXo, an event mechanism allows to trigger and listen to
+ events under specific conditions. This mechanism is used in several places
+ in eXo such as login/logout time.</para>
+ </section>
+
+ <section>
+ <title>How does it work?</title>
+
+ <para>Listeners must be subclasses of
+ org.exoplatform.services.listener.Listener registered by the
+ ListenerService.</para>
+
+ <section>
+ <title>Registering a listener</title>
+
+ <para>To register a listener, you need to call the addListener()
+ method.</para>
+
+ <programlisting>/**
+ * This method is used to register a listener with the service. The method
+ * should: 1. Check to see if there is a list of listener with the listener
+ * name, create one if the listener list doesn't exit 2. Add the new listener
+ * to the listener list
+ *
+ * @param listener
+*/
+public void addListener(Listener listener) {
+ ...
+}</programlisting>
+
+ <para>By convention, we use the listener name as the name of the event
+ to listen to.</para>
+ </section>
+
+ <section>
+ <title>Triggering an event</title>
+
+ <para>To trigger an event, an application can call one of the
+ broadcast() methods of ListenerService.</para>
+
+ <programlisting>/**
+ * This method is used to broadcast an event. This method should: 1. Check if
+ * there is a list of listener that listen to the event name. 2. If there is a
+ * list of listener, create the event object with the given name , source and
+ * data 3. For each listener in the listener list, invoke the method
+ * onEvent(Event)
+ *
+ * @param <S> The type of the source that broadcast the event
+ * @param <D> The type of the data that the source object is working on
+ * @param name The name of the event
+ * @param source The source object instance
+ * @param data The data object instance
+ * @throws Exception
+ */
+public <S, D> void broadcast(String name, S source, D data) throws
Exception {
+ ...
+}
+
+/**
+ * This method is used when a developer want to implement his own event object
+ * and broadcast the event. The method should: 1. Check if there is a list of
+ * listener that listen to the event name. 2. If there is a list of the
+ * listener, For each listener in the listener list, invoke the method
+ * onEvent(Event)
+ *
+ * @param <T> The type of the event object, the type of the event object
has
+ * to be extended from the Event type
+ * @param event The event instance
+ * @throws Exception
+ */
+public <T extends Event> void broadcast(T event) throws Exception {
+ ...
+}</programlisting>
+
+ <para>The boadcast() methods retrieve the name of the event and find the
+ registered listeners with the same name and call the method onEvent() on
+ each listener found.</para>
+
+ <para>Each listener is a class that extends
+ org.exoplatform.services.listener.Listener, as you can see below:</para>
+
+ <programlisting>public abstract class Listener<S, D> extends
BaseComponentPlugin {
+
+ /**
+ * This method should be invoked when an event with the same name is
+ * broadcasted
+ */
+ public abstract void onEvent(Event<S, D> event) throws Exception;
+}</programlisting>
+
+ <warning>
+ <para>As you can see we use generics to limit the source of the event
+ to the type 'S' and the data of the event to the type 'D', so we
+ expect that listeners implement the method onEvent() with the
+ corresponding types</para>
+ </warning>
+
+ <para>Each listener is also a ComponentPlugin with a name and a
+ description, in other words the name of the listener will be the name
+ given in the configuration file, for more details see the next
+ section.</para>
+
+ <programlisting>public interface ComponentPlugin {
+ public String getName();
+
+ public void setName(String name);
+
+ public String getDescription();
+
+ public void setDescription(String description);
+}</programlisting>
+ </section>
+ </section>
+
+ <section>
+ <title>How to configure a listener?</title>
+
+ <para>All listeners are in fact a ComponentPlugin so it must be configured
+ as below:</para>
+
+ <programlisting><?xml version="1.0"
encoding="ISO-8859-1"?>
+<configuration>
+...
+ <external-component-plugins>
+ <!-- The full qualified name of the ListenerService -->
+
<target-component>org.exoplatform.services.listener.ListenerService</target-component>
+
+ <component-plugin>
+ <!-- The name of the listener that is also the name of the target event
-->
+ <name>${name-of-the-target-event}</name>
+ <!-- The name of the method to call on the ListenerService in order to
register the Listener -->
+ <set-method>addListener</set-method>
+ <!-- The full qualified name of the Listener -->
+ <type>${the-FQN-of-the-listener}</type>
+ </component-plugin>
+
+ </external-component-plugins>
+</configuration></programlisting>
+ </section>
+
+ <section>
+ <title>Concrete Example</title>
+
+ <para>The org.exoplatform.services.security.ConversationRegistry uses the
+ ListenerService to notify that a user has just signed in or just left the
+ application. For example, when a new user signs in, the following code is
+ called:</para>
+
+
<programlisting>listenerService.broadcast("exo.core.security.ConversationRegistry.register",
this, state);</programlisting>
+
+ <para>This code will in fact create a new Event which name is
+ "exo.core.security.ConversationRegistry.register", which source is the
+ current instance of ConversationRegistry and which data is the given
+ state. The ListenerService will call the method
+ onEvent(Event<ConversationRegistry, ConversationState> event) on all
+ the listeners which name is
+ "exo.core.security.ConversationRegistry.register".</para>
+
+ <para>In the example below, we define a Listener that will listen the
+ event "exo.core.security.ConversationRegistry.register".</para>
+
+ <programlisting><?xml version="1.0"
encoding="ISO-8859-1"?>
+<configuration>
+...
+ <external-component-plugins>
+ <!-- The full qualified name of the ListenerService -->
+
<target-component>org.exoplatform.services.listener.ListenerService</target-component>
+
+ <component-plugin>
+ <!-- The name of the listener that is also the name of the target event
-->
+
<name>exo.core.security.ConversationRegistry.register</name>
+ <!-- The name of the method to call on the ListenerService in order to
register the Listener -->
+ <set-method>addListener</set-method>
+ <!-- The full qualified name of the Listener -->
+
<type>org.exoplatform.forum.service.AuthenticationLoginListener</type>
+ </component-plugin>
+
+ </external-component-plugins>
+</configuration>
+...</programlisting>
+ </section>
+</chapter>
Modified: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel.xml
===================================================================
---
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel.xml 2010-08-01
15:20:33 UTC (rev 2848)
+++
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/kernel.xml 2010-08-02
09:15:04 UTC (rev 2849)
@@ -9,9 +9,39 @@
<xi:include href="kernel/kernel.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="kernel/configuration.xml"
+ <xi:include href="kernel/exo-container.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="kernel/service-configuration-for-beginners.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <xi:include href="kernel/service-configuration-in-detail.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <xi:include href="kernel/container-configuration.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <xi:include href="kernel/inversion-of-control.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <xi:include href="kernel/services-wiring.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <xi:include href="kernel/jmx-bean-server.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <xi:include href="kernel/component-plugin-priority.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <xi:include href="kernel/understanding-listnerservice.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <xi:include href="kernel/initialcontext-binder-service.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <xi:include href="kernel/job-scheduler-service.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
<xi:include href="kernel/cache.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
@@ -24,4 +54,9 @@
<xi:include href="kernel/logging.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+
+
+
+
</part>