Author: jaredmorgs Date: 2012-07-06 01:00:36 -0400 (Fri, 06 Jul 2012) New Revision: 8775 Modified: epp/docs/branches/5.2/Reference_Guide/en-US/Author_Group.xml epp/docs/branches/5.2/Reference_Guide/en-US/Book_Info.xml epp/docs/branches/5.2/Reference_Guide/en-US/Reference_Guide.xml epp/docs/branches/5.2/Reference_Guide/en-US/Revision_History.xml epp/docs/branches/5.2/Reference_Guide/en-US/extras/Advanced_Development_JCR_Configuration/example-1.xml epp/docs/branches/5.2/Reference_Guide/en-US/images/AuthenticationAndIdentity/Overview/loginScreen.png epp/docs/branches/5.2/Reference_Guide/en-US/modules/Advanced/Foundations/Advanced_Concepts.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/Advanced/Foundations/Config_Retrieval.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/Advanced/Foundations/Configuring_Services.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/Advanced/Foundations/Profiles.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/Advanced/Foundations/Specific_Services.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/AuthenticationAuthorizationOverview.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/CoreOrganizationInitializer.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/LDAP.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/PredefinedUserConfiguration.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/SSO.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/Introduction.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortalDevelopment/DataImportStrategy.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortalDevelopment/DefaultPortalNavigationConfiguration.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortalDevelopment/NavigationController.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr-with-gtn/managed-datasources-under-jboss-as.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/configuration/exo-jcr-configuration.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/configuration/workspace-persistence-storage.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/data-container.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/jbosscache-configuration-templates.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/lock-manager-config.xml Log: BZ#812412 cumulative minor corrections Modified: epp/docs/branches/5.2/Reference_Guide/en-US/Author_Group.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/Author_Group.xml 2012-07-05 19:41:59 UTC (rev 8774) +++ epp/docs/branches/5.2/Reference_Guide/en-US/Author_Group.xml 2012-07-06 05:00:36 UTC (rev 8775) @@ -1,67 +1,34 @@ -<?xml version='1.0' encoding='utf-8' ?> +<?xml version='1.0' encoding='UTF-8'?> <!DOCTYPE authorgroup PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!ENTITY % BOOK_ENTITIES SYSTEM "Reference_Guide.ent"> %BOOK_ENTITIES; ]> <authorgroup> - <editor> - <firstname>Luc</firstname> - <surname>Texier</surname> - <affiliation> - <shortaffil>Red Hat</shortaffil> - <orgdiv>JBoss Engineering</orgdiv> - - </affiliation> - - </editor> - <editor> - <firstname>Thomas</firstname> - <surname>Heute</surname> - <affiliation> - <shortaffil>Red Hat</shortaffil> - <orgdiv>JBoss Engineering</orgdiv> - - </affiliation> - - </editor> - <editor> - <firstname>Wesley</firstname> - <surname>Hales</surname> - <affiliation> - <shortaffil>Red Hat</shortaffil> - <orgdiv>JBoss Engineering</orgdiv> - - </affiliation> - - </editor> - <editor> - <firstname>Chris</firstname> - <surname>Laprun</surname> - <affiliation> - <shortaffil>Red Hat</shortaffil> - <orgdiv>JBoss Engineering</orgdiv> - - </affiliation> - - </editor> - <editor> - <firstname>Scott</firstname> - <surname>Mumford</surname> - <affiliation> - <shortaffil>Red Hat</shortaffil> - <orgdiv>Engineering Content Services</orgdiv> - - </affiliation> - - </editor> - <othercredit> - <affiliation> - <orgname><emphasis role="bold"><ulink type="http" url="http://www.jboss.org/gatein/">GateIn</ulink></... and <emphasis role="bold"><ulink type="http" url="http://www.exoplatform.com">eXo Platform</ulink></emphasis></orgname> - <orgdiv>Documentation Teams</orgdiv> - - </affiliation> - <contrib>Based on original product documentation by:</contrib> - - </othercredit> + <editor> + <firstname>Thomas</firstname> + <surname>Heute</surname> + <affiliation> + <shortaffil>Red Hat</shortaffil> + <orgdiv>JBoss Engineering</orgdiv> + </affiliation> + </editor> + <editor> + <firstname>Chris</firstname> + <surname>Laprun</surname> + <affiliation> + <shortaffil>Red Hat</shortaffil> + <orgdiv>JBoss Engineering</orgdiv> + </affiliation> + </editor> + <othercredit> + <affiliation> + <orgname><emphasis role="bold"> + <ulink url="http://www.jboss.org/gatein/" type="http">GateIn</ulink> + </emphasis> and <emphasis role="bold"> + <ulink url="http://www.exoplatform.com" type="http">eXo Platform</ulink> + </emphasis></orgname> + <orgdiv>Documentation Teams</orgdiv> + </affiliation> + <contrib>Based on original product documentation by:</contrib> + </othercredit> </authorgroup> - Modified: epp/docs/branches/5.2/Reference_Guide/en-US/Book_Info.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/Book_Info.xml 2012-07-05 19:41:59 UTC (rev 8774) +++ epp/docs/branches/5.2/Reference_Guide/en-US/Book_Info.xml 2012-07-06 05:00:36 UTC (rev 8775) @@ -9,7 +9,7 @@ <productname>JBoss Enterprise Portal Platform</productname> <productnumber>5.2</productnumber> <edition>5.2.2</edition> - <pubsnumber>1</pubsnumber> + <pubsnumber>2</pubsnumber> <abstract> <para> This Reference Guide is a high-level usage document. It deals with more advanced topics than the Installation and User Guides, adding new content or taking concepts discussed in the earlier documents further. It aims to provide supporting documentation for advanced users of the JBoss Enterprise Portal Platform product. Its primary focus is on advanced use of the product and it assumes an intermediate or advanced knowledge of the technology and terms. Modified: epp/docs/branches/5.2/Reference_Guide/en-US/Reference_Guide.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/Reference_Guide.xml 2012-07-05 19:41:59 UTC (rev 8774) +++ epp/docs/branches/5.2/Reference_Guide/en-US/Reference_Guide.xml 2012-07-06 05:00:36 UTC (rev 8775) @@ -1,6 +1,5 @@ <?xml version='1.0' encoding='UTF-8'?> -<!-- This document was created with Syntext Serna Free. --> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!-- This document was created with Syntext Serna Free. --><!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!ENTITY % BOOK_ENTITIES SYSTEM "Reference_Guide.ent"> %BOOK_ENTITIES; ]> Modified: epp/docs/branches/5.2/Reference_Guide/en-US/Revision_History.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/Revision_History.xml 2012-07-05 19:41:59 UTC (rev 8774) +++ epp/docs/branches/5.2/Reference_Guide/en-US/Revision_History.xml 2012-07-06 05:00:36 UTC (rev 8775) @@ -8,8 +8,8 @@ <simpara> <revhistory> <revision> - <revnumber>5.2.2-1</revnumber> - <date>Tue Jul 3 2012</date> + <revnumber>5.2.2-2</revnumber> + <date>Thu Jul 5 2012</date> <author> <firstname>Jared</firstname> <surname>Morgan</surname> Modified: epp/docs/branches/5.2/Reference_Guide/en-US/extras/Advanced_Development_JCR_Configuration/example-1.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/extras/Advanced_Development_JCR_Configuration/example-1.xml 2012-07-05 19:41:59 UTC (rev 8774) +++ epp/docs/branches/5.2/Reference_Guide/en-US/extras/Advanced_Development_JCR_Configuration/example-1.xml 2012-07-06 05:00:36 UTC (rev 8775) @@ -1,69 +1,59 @@ -<component> - <key>org.exoplatform.services.naming.InitialContextInitializer</key> - <type>org.exoplatform.services.naming.InitialContextInitializer</type> - <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> - <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>jdbcjcr1</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="com.mysql.jdbc.Driver"/> - <property name="url" value="jdbc:mysql://exoua.dnsalias.net/jcr"/> - <property name="username" value="exoadmin"/> - <property name="password" value="exo12321"/> - <property name="maxActive" value="50"/> - <property name="maxIdle" value="5"/> - <property name="initialSize" value="5"/> - </properties-param> - </init-params> - </component-plugin> - <component-plugins> - <init-params> - <value-param> - <name>default-context-factory</name> - <value>org.exoplatform.services.naming.SimpleContextFactory</value> - </value-param> - </init-params> - </component> \ No newline at end of file + <external-component-plugins> + <target-component>org.exoplatform.services.naming.InitialContextInitializer</target-component> + <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="${all.driverClassName:org.hsqldb.jdbcDriver}"/> + <!-- MVCC configured to prevent possible deadlocks when a global Tx is active --> + <property name="url" value="${jdbcjcr.url:jdbc:hsqldb:file:target/temp/data/portal;hsqldb.tx=mvcc}"/> + <property name="username" value="${jdbcjcr.username:sa}"/> + <property name="password" value="${jdbcjcr.password:}"/> + </properties-param> + </init-params> + </component-plugin> + <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>jdbcjcr1</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="${all.driverClassName:org.hsqldb.jdbcDriver}"/> + <property name="url" value="${jdbcjcr1.url:jdbc:hsqldb:file:target/temp/data/jcr}"/> + <property name="username" value="${jdbcjcr1.username:sa}"/> + <property name="password" value="${jdbcjcr1.password:}"/> + </properties-param> + </init-params> + </component-plugin> + <!-- Unnecessary plugins not relevant to this section removed for clarity --> + </external-component-plugins> Modified: epp/docs/branches/5.2/Reference_Guide/en-US/images/AuthenticationAndIdentity/Overview/loginScreen.png =================================================================== (Binary files differ) Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/Advanced/Foundations/Advanced_Concepts.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/Advanced/Foundations/Advanced_Concepts.xml 2012-07-05 19:41:59 UTC (rev 8774) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/Advanced/Foundations/Advanced_Concepts.xml 2012-07-06 05:00:36 UTC (rev 8775) @@ -1,25 +1,24 @@ -<?xml version='1.0' encoding='utf-8' ?> +<?xml version='1.0' encoding='UTF-8'?> <!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!ENTITY % BOOK_ENTITIES SYSTEM "Reference_Guide.ent"> %BOOK_ENTITIES; ]> <section id="sect-Reference_Guide-Advanced_concepts_for_the_PortalContainers"> - <title>Advanced concepts for the <emphasis>PortalContainers</emphasis></title> - <para> - Since eXo JCR 1.12, we added a set of new features that have been designed to extend portal applications such as GateIn. - </para> - <section id="sect-Reference_Guide-Advanced_concepts_for_the_PortalContainers-Add_new_configuration_files_from_a_WAR_file"> - <title>Add new configuration files from a WAR file</title> - <para> - A <envar>ServletContextListener</envar> called <envar>org.exoplatform.container.web.PortalContainerConfigOwner</envar> has been added in order to notify the application that a given web application provides some configuration to the portal container, and this configuration file is the file <emphasis>WEB-INF/conf/configuration.xml</emphasis> available in the web application itself. - </para> - <para> - If your war file contains some configuration to add to the <envar>PortalContainer</envar> simply add the following lines in your <emphasis>web.xml</emphasis> file. - </para> - -<programlisting language="XML" role="XML">&lt;?xml version="1.0" encoding="ISO-8859-1" ?&gt; -&lt;!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN" - "http://java.sun.com/dtd/web-app_2_3.dtd"&gt; + <title>Advanced concepts for the <emphasis>PortalContainers</emphasis></title> + <para> + Since eXo JCR 1.12, we added a set of new features that have been designed to extend portal applications such as GateIn. + </para> + <section id="sect-Reference_Guide-Advanced_concepts_for_the_PortalContainers-Add_new_configuration_files_from_a_WAR_file"> + <title>Add new configuration files from a WAR file</title> + <para> + A <envar>ServletContextListener</envar> called <envar>org.exoplatform.container.web.PortalContainerConfigOwner</envar> has been added in order to notify the application that a given web application provides some configuration to the portal container, and this configuration file is the file <emphasis>WEB-INF/conf/configuration.xml</emphasis> available in the web application itself. + </para> + <para> + If your war file contains some configuration to add to the <envar>PortalContainer</envar> simply add the following lines in your <emphasis>web.xml</emphasis> file. + </para> + <programlisting language="XML" role="XML">&lt;?xml version=&quot;1.0&quot; encoding=&quot;ISO-8859-1&quot; ?&gt; +&lt;!DOCTYPE web-app PUBLIC &quot;-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN&quot; + &quot;http://java.sun.com/dtd/web-app_2_3.dtd&quot;&gt; &lt;web-app&gt; ... &lt;!-- ================================================================== --&gt; @@ -30,36 +29,30 @@ &lt;/listener&gt; ... &lt;/web-app&gt;</programlisting> + </section> + <section id="sect-Reference_Guide-Advanced_concepts_for_the_PortalContainers-Creating_your_PortalContainers_from_a_WAR_file"> + <title>Creating your <emphasis>PortalContainers</emphasis> from a WAR file</title> + <para> + A <envar>ServletContextListener</envar> called <envar>org.exoplatform.container.web.PortalContainerCreator</envar> has been added in order to create the current portal containers that have been registered. We assume that all the web applications have already been loaded before calling <envar>PortalContainerCreator.contextInitialized.</envar> + </para> + <para> + <note> + <para> + In GateIn, the <envar>PortalContainerCreator</envar> is already managed by the file <emphasis>starter.war/ear.</emphasis> + </para> + </note> - </section> - - <section id="sect-Reference_Guide-Advanced_concepts_for_the_PortalContainers-Creating_your_PortalContainers_from_a_WAR_file"> - <title>Creating your <emphasis>PortalContainers</emphasis> from a WAR file</title> - <para> - A <envar>ServletContextListener</envar> called <envar>org.exoplatform.container.web.PortalContainerCreator</envar> has been added in order to create the current portal containers that have been registered. We assume that all the web applications have already been loaded before calling <envar>PortalContainerCreator.contextInitialized.</envar> - </para> - <para> - <note> - <para> - In GateIn, the <envar>PortalContainerCreator</envar> is already managed by the file <emphasis>starter.war/ear.</emphasis> - </para> - - </note> - - </para> - - </section> - - <section id="sect-Reference_Guide-Advanced_concepts_for_the_PortalContainers-Defining_a_PortalContainer_with_its_dependencies_and_its_settings"> - <title>Defining a <emphasis>PortalContainer</emphasis> with its dependencies and its settings</title> - <para> - Now we can define precisely a portal container and its dependencies and settings thanks to the <envar>PortalContainerDefinition</envar> that currently contains the name of the portal container, the name of the rest context, the name of the realm, the web application dependencies ordered by loading priority (i.e. the first dependency must be loaded at first and so on..) and the settings. - </para> - <para> - To be able to define a <envar>PortalContainerDefinition</envar>, we need to ensure first of all that a <envar>PortalContainerConfig</envar> has been defined at the <envar>RootContainer</envar> level, see an example below: - </para> - -<programlisting language="XML" role="XML"> &lt;component&gt; + </para> + </section> + <section id="sect-Reference_Guide-Advanced_concepts_for_the_PortalContainers-Defining_a_PortalContainer_with_its_dependencies_and_its_settings"> + <title>Defining a <emphasis>PortalContainer</emphasis> with its dependencies and its settings</title> + <para> + Now we can define precisely a portal container and its dependencies and settings thanks to the <envar>PortalContainerDefinition</envar> that currently contains the name of the portal container, the name of the rest context, the name of the realm, the web application dependencies ordered by loading priority (i.e. the first dependency must be loaded at first and so on..) and the settings. + </para> + <para> + To be able to define a <envar>PortalContainerDefinition</envar>, we need to ensure first of all that a <envar>PortalContainerConfig</envar> has been defined at the <envar>RootContainer</envar> level, see an example below: + </para> + <programlisting language="XML" role="XML"> &lt;component&gt; &lt;!-- The full qualified name of the PortalContainerConfig --&gt; &lt;type&gt;org.exoplatform.container.definition.PortalContainerConfig&lt;/type&gt; &lt;init-params&gt; @@ -87,10 +80,10 @@ &lt;!-- It cans be used to avoid duplicating configuration --&gt; &lt;object-param&gt; &lt;name&gt;default.portal.definition&lt;/name&gt; - &lt;object type="org.exoplatform.container.definition.PortalContainerDefinition"&gt; + &lt;object type=&quot;org.exoplatform.container.definition.PortalContainerDefinition&quot;&gt; &lt;!-- All the dependencies of the portal container ordered by loading priority --&gt; - &lt;field name="dependencies"&gt; - &lt;collection type="java.util.ArrayList"&gt; + &lt;field name=&quot;dependencies&quot;&gt; + &lt;collection type=&quot;java.util.ArrayList&quot;&gt; &lt;value&gt; &lt;string&gt;foo&lt;/string&gt; &lt;/value&gt; @@ -103,8 +96,8 @@ &lt;/collection&gt; &lt;/field&gt; &lt;!-- A map of settings tied to the default portal container --&gt; - &lt;field name="settings"&gt; - &lt;map type="java.util.HashMap"&gt; + &lt;field name=&quot;settings&quot;&gt; + &lt;map type=&quot;java.util.HashMap&quot;&gt; &lt;entry&gt; &lt;key&gt; &lt;string&gt;foo5&lt;/string&gt; @@ -132,95 +125,60 @@ &lt;/map&gt; &lt;/field&gt; &lt;!-- The path to the external properties file --&gt; - &lt;field name="externalSettingsPath"&gt; + &lt;field name=&quot;externalSettingsPath&quot;&gt; &lt;string&gt;classpath:/org/exoplatform/container/definition/default-settings.properties&lt;/string&gt; &lt;/field&gt; &lt;/object&gt; &lt;/object-param&gt; &lt;/init-params&gt; &lt;/component&gt;</programlisting> - <table id="tabl-Reference_Guide-Defining_a_PortalContainer_with_its_dependencies_and_its_settings-Descriptions_of_the_fields_of_PortalContainerConfig"> - <title>Descriptions of the fields of <envar>PortalContainerConfig</envar></title> - <tgroup cols="2"> - <tbody> - <row> - <entry> - default.portal.container (*) - </entry> - <entry> - The name of the default portal container. This field is optional. - </entry> - - </row> - <row> - <entry> - default.rest.context (*) - </entry> - <entry> - The name of the default rest <envar>ServletContext</envar>. This field is optional. - </entry> - - </row> - <row> - <entry> - default.realm.name (*) - </entry> - <entry> - The name of the default realm. This field is optional. - </entry> - - </row> - <row> - <entry> - ignore.unregistered.webapp (*) - </entry> - <entry> - Indicates whether the unregistered webapps have to be ignored. If a webapp has not been registered as a dependency of any portal container, the application will use the value of this parameter to know what to do: - <itemizedlist> - <listitem> - <para> - If it is set to <emphasis>false</emphasis>, this webapp will be considered by default as a dependency of all the portal containers. - </para> - - </listitem> - <listitem> - <para> - If it is set to <emphasis>true</emphasis>, this webapp won't be considered by default as a dependency of any portal container, it will be simply ignored. - </para> - - </listitem> - - </itemizedlist> - This field is optional and by default this parameter is set to <emphasis>false</emphasis>. - </entry> - - </row> - <row> - <entry> - default.portal.definition - </entry> - <entry> - The definition of the default portal container. This field is optional. The expected type is <envar>org.exoplatform.container.definition.PortalContainerDefinition</envar> that is described below. Allow the parameters defined in this default <envar>PortalContainerDefinition</envar> will be the default values. - </entry> - - </row> - - </tbody> - - </tgroup> - - </table> - <note> - <para> - All the value of the parameters marked with a (*) can be defined thanks to System properties like any values in configuration files but also thanks to variables loaded by the <emphasis>PropertyConfigurator</emphasis>. For example in GateIn by default, it would be all the variables defined in the file <emphasis>configuration.properties</emphasis>. - </para> - - </note> - <para> - A new <envar>PortalContainerDefinition</envar> can be defined at the <envar>RootContainer</envar> level thanks to an external plugin, see an example below: - </para> - -<programlisting language="XML" role="XML"> &lt;external-component-plugins&gt; + <table id="tabl-Reference_Guide-Defining_a_PortalContainer_with_its_dependencies_and_its_settings-Descriptions_of_the_fields_of_PortalContainerConfig"> + <title>Descriptions of the fields of <envar>PortalContainerConfig</envar></title> + <tgroup cols="2"> + <tbody> + <row> + <entry> default.portal.container (*) </entry> + <entry> The name of the default portal container. This field is optional. </entry> + </row> + <row> + <entry> default.rest.context (*) </entry> + <entry> The name of the default rest <envar>ServletContext</envar>. This field is optional. </entry> + </row> + <row> + <entry> default.realm.name (*) </entry> + <entry> The name of the default realm. This field is optional. </entry> + </row> + <row> + <entry> ignore.unregistered.webapp (*) </entry> + <entry> Indicates whether the unregistered webapps have to be ignored. If a webapp has not been registered as a dependency of any portal container, the application will use the value of this parameter to know what to do: <itemizedlist> + <listitem> + <para> + If it is set to <emphasis>false</emphasis>, this webapp will be considered by default as a dependency of all the portal containers. + </para> + </listitem> + <listitem> + <para> + If it is set to <emphasis>true</emphasis>, this webapp won&apos;t be considered by default as a dependency of any portal container, it will be simply ignored. + </para> + </listitem> + </itemizedlist> This field is optional and by default this parameter is set to <emphasis>false</emphasis>. </entry> + </row> + <row> + <entry> default.portal.definition </entry> + <entry> The definition of the default portal container. This field is optional. The expected type is <envar>org.exoplatform.container.definition.PortalContainerDefinition</envar> that is described below. Allow the parameters defined in this default <envar>PortalContainerDefinition</envar> will be the default values. </entry> + </row> + </tbody> + </tgroup> + </table> + <note> + <para> + All the value of the parameters marked with a (*) can be defined thanks to System properties like any values in configuration files but also thanks to variables loaded by the <emphasis>PropertyConfigurator</emphasis>. For example in GateIn by default, it would be all the variables defined in the file <emphasis>configuration.properties</emphasis>. + </para> + </note> + <para> + A new <envar>PortalContainerDefinition</envar> can be defined at the <envar>RootContainer</envar> level thanks to an external plug-in, see an example below: + </para> + <programlisting language="XML" role="XML"> &lt;external-component-plugins&gt; &lt;!-- The full qualified name of the PortalContainerConfig --&gt; &lt;target-component&gt;org.exoplatform.container.definition.PortalContainerConfig&lt;/target-component&gt; &lt;component-plugin&gt; @@ -233,22 +191,22 @@ &lt;init-params&gt; &lt;object-param&gt; &lt;name&gt;portal&lt;/name&gt; - &lt;object type="org.exoplatform.container.definition.PortalContainerDefinition"&gt; + &lt;object type=&quot;org.exoplatform.container.definition.PortalContainerDefinition&quot;&gt; &lt;!-- The name of the portal container --&gt; - &lt;field name="name"&gt; + &lt;field name=&quot;name&quot;&gt; &lt;string&gt;myPortal&lt;/string&gt; &lt;/field&gt; &lt;!-- The name of the context name of the rest web application --&gt; - &lt;field name="restContextName"&gt; + &lt;field name=&quot;restContextName&quot;&gt; &lt;string&gt;myRest&lt;/string&gt; &lt;/field&gt; &lt;!-- The name of the realm --&gt; - &lt;field name="realmName"&gt; + &lt;field name=&quot;realmName&quot;&gt; &lt;string&gt;my-domain&lt;/string&gt; &lt;/field&gt; &lt;!-- All the dependencies of the portal container ordered by loading priority --&gt; - &lt;field name="dependencies"&gt; - &lt;collection type="java.util.ArrayList"&gt; + &lt;field name=&quot;dependencies&quot;&gt; + &lt;collection type=&quot;java.util.ArrayList&quot;&gt; &lt;value&gt; &lt;string&gt;foo&lt;/string&gt; &lt;/value&gt; @@ -261,8 +219,8 @@ &lt;/collection&gt; &lt;/field&gt; &lt;!-- A map of settings tied to the portal container --&gt; - &lt;field name="settings"&gt; - &lt;map type="java.util.HashMap"&gt; + &lt;field name=&quot;settings&quot;&gt; + &lt;map type=&quot;java.util.HashMap&quot;&gt; &lt;entry&gt; &lt;key&gt; &lt;string&gt;foo&lt;/string&gt; @@ -306,7 +264,7 @@ &lt;/map&gt; &lt;/field&gt; &lt;!-- The path to the external properties file --&gt; - &lt;field name="externalSettingsPath"&gt; + &lt;field name=&quot;externalSettingsPath&quot;&gt; &lt;string&gt;classpath:/org/exoplatform/container/definition/settings.properties&lt;/string&gt; &lt;/field&gt; &lt;/object&gt; @@ -314,403 +272,264 @@ &lt;/init-params&gt; &lt;/component-plugin&gt; &lt;/external-component-plugins&gt;</programlisting> - <table id="tabl-Reference_Guide-Defining_a_PortalContainer_with_its_dependencies_and_its_settings-Descriptions_of_the_fields_of_a_PortalContainerDefinition_when_it_is_used_to_define_a_new_portal_container"> - <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> + <table id="tabl-Reference_Guide-Defining_a_PortalContainer_with_its_dependencies_and_its_settings-Descriptions_of_the_fields_of_a_PortalContainerDefinition_when_it_is_used_to_define_a_new_portal_container"> + <title>Descriptions of the fields of a PortalContainerDefinition when it is used to define a new portal container</title> + <tgroup cols="2"> + <tbody> + <row> + <entry> name (*) </entry> + <entry> The name of the portal container. This field is mandatory . </entry> + </row> + <row> + <entry> restContextName (*) </entry> + <entry> The name of the context name of the rest web application. This field is optional. The default value will be defined at the <envar>PortalContainerConfig</envar> level. </entry> + </row> + <row> + <entry> realmName (*) </entry> + <entry> The name of the realm. This field is optional. The default value will be defined at the <envar>PortalContainerConfig</envar> level. </entry> + </row> + <row> + <entry> dependencies </entry> + <entry> All the dependencies of the portal container ordered by loading priority. This field is optional. The default value will be defined at the <envar>PortalContainerConfig</envar> level. The dependencies are in fact the list of the context names of the web applications from which the portal container depends. This field is optional. The dependency order is really crucial since it will be interpreted the same way by several components of the platform. All those components, will consider the 1st element in the list less important than the second element and so on. It is currently used to: <itemizedlist> + <listitem> + <para> + Know the loading order of all the dependencies. + </para> + </listitem> + <listitem> + <para> + If we have several <envar>PortalContainerConfigOwner</envar> <itemizedlist> + <listitem> + <para> + The <envar>ServletContext</envar> of all the <envar>PortalContainerConfigOwner</envar> will be unified, if we use the unified <envar>ServletContext</envar> (<emphasis>PortalContainer.getPortalContext()</emphasis>) to get a resource, it will try to get the resource in the <envar>ServletContext</envar> of the most important <envar>PortalContainerConfigOwner</envar> (i.e. last in the dependency list) and if it cans find it, it will try with the second most important <envar>PortalContainerConfigOwner</envar> and so on. + </para> + </listitem> + <listitem> + <para> + The <envar>ClassLoader</envar> of all the <envar>PortalContainerConfigOwner</envar> will be unified, if we use the unified <envar>ClassLoader</envar> (<emphasis>PortalContainer.getPortalClassLoader()</emphasis>) to get a resource, it will try to get the resource in the <envar>ClassLoader</envar> of the most important <envar>PortalContainerConfigOwner</envar> (i.e. last in the dependency list) and if it can find it, it will try with the second most important <envar>PortalContainerConfigOwner</envar> and so on. + </para> + </listitem> + </itemizedlist> - </row> - <row> - <entry> - restContextName (*) - </entry> - <entry> - The name of the context name of the rest web application. This field is optional. The default value will be defined at the <envar>PortalContainerConfig</envar> level. - </entry> + </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 &quot;properties&quot; or of type &quot;xml&quot;. The path will be interpreted as follows: <orderedlist> + <listitem> + <para> + The path doesn&apos;t contain any prefix of type &quot;classpath:&quot;, &quot;jar:&quot; or &quot;file:&quot;, 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> - </row> - <row> - <entry> - realmName (*) - </entry> - <entry> - The name of the realm. This field is optional. The default value will be defined at the <envar>PortalContainerConfig</envar> level. - </entry> + </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 id="tabl-Reference_Guide-Defining_a_PortalContainer_with_its_dependencies_and_its_settings-Descriptions_of_the_fields_of_a_PortalContainerDefinition_when_it_is_used_to_define_the_default_portal_container"> + <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>&quot;portal&quot;.</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 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.rest.context</emphasis> is not empty, then the default value will be the value of the parameter. + </para> + </listitem> + <listitem> + <para> + If this field and the parameter <emphasis>default.rest.context</emphasis> are both empty, the default value will be <emphasis>&quot;rest&quot;.</emphasis> + </para> + </listitem> + </orderedlist></entry> + </row> + <row> + <entry> realmName (*) </entry> + <entry> The name of the realm. This field is optional. The default value 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.realm.name</emphasis> is not empty, then the default value will be the value of the parameter. + </para> + </listitem> + <listitem> + <para> + If this field and the parameter <emphasis>default.realm.name</emphasis> are both empty, the default value will be <emphasis>&quot;exo-domain&quot;.</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 &quot;properties&quot; or of type &quot;xml&quot;. The path will be interpreted as follows: <orderedlist> + <listitem> + <para> + The path doesn&apos;t contain any prefix of type &quot;classpath:&quot;, &quot;jar:&quot; or &quot;file:&quot;, 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> - </row> - <row> - <entry> - dependencies - </entry> - <entry> - All the dependencies of the portal container ordered by loading priority. This field is optional. The default value will be defined at the <envar>PortalContainerConfig</envar> level. The dependencies are in fact the list of the context names of the web applications from which the portal container depends. This field is optional. The dependency order is really crucial since it will be interpreted the same way by several components of the platform. All those components, will consider the 1st element in the list less important than the second element and so on. It is currently used to: - <itemizedlist> - <listitem> - <para> - Know the loading order of all the dependencies. - </para> - - </listitem> - <listitem> - <para> - If we have several <envar>PortalContainerConfigOwner</envar> <itemizedlist> - <listitem> - <para> - The <envar>ServletContext</envar> of all the <envar>PortalContainerConfigOwner</envar> will be unified, if we use the unified <envar>ServletContext</envar> (<emphasis>PortalContainer.getPortalContext()</emphasis>) to get a resource, it will try to get the resource in the <envar>ServletContext</envar> of the most important <envar>PortalContainerConfigOwner</envar> (i.e. last in the dependency list) and if it cans find it, it will try with the second most important <envar>PortalContainerConfigOwner</envar> and so on. - </para> - - </listitem> - <listitem> - <para> - The <envar>ClassLoader</envar> of all the <envar>PortalContainerConfigOwner</envar> will be unified, if we use the unified <envar>ClassLoader</envar> (<emphasis>PortalContainer.getPortalClassLoader()</emphasis>) to get a resource, it will try to get the resource in the <envar>ClassLoader</envar> of the most important <envar>PortalContainerConfigOwner</envar> (i.e. last in the dependency list) and if it can find it, it will try with the second most important <envar>PortalContainerConfigOwner</envar> and so on. - </para> - - </listitem> - - </itemizedlist> - - </para> - - </listitem> - - </itemizedlist> - - </entry> - - </row> - <row> - <entry> - settings - </entry> - <entry> - A <envar>java.util.Map</envar> of internal parameters that we would like to tie the portal container. Those parameters could have any type of value. This field is optional. If some internal settings are defined at the <envar>PortalContainerConfig</envar> level, the two maps of settings will be merged. If a setting with the same name is defined in both maps, it will keep the value defined at the <envar>PortalContainerDefinition</envar> level. - </entry> - - </row> - <row> - <entry> - externalSettingsPath - </entry> - <entry> - The path of the external properties file to load as default settings to the portal container. This field is optional. If some external settings are defined at the <envar>PortalContainerConfig</envar> level, the two maps of settings will be merged. If a setting with the same name is defined in both maps, it will keep the value defined at the <envar>PortalContainerDefinition</envar> level. The external properties files can be either of type "properties" or of type "xml". The path will be interpreted as follows: - <orderedlist> - <listitem> - <para> - The path doesn't contain any prefix of type "classpath:", "jar:" 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 id="tabl-Reference_Guide-Defining_a_PortalContainer_with_its_dependencies_and_its_settings-Descriptions_of_the_fields_of_a_PortalContainerDefinition_when_it_is_used_to_define_the_default_portal_container"> - <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 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.rest.context</emphasis> is not empty, then the default value will be the value of the parameter. - </para> - - </listitem> - <listitem> - <para> - If this field and the parameter <emphasis>default.rest.context</emphasis> are both empty, the default value will be <emphasis>"rest".</emphasis> - </para> - - </listitem> - - </orderedlist> - - </entry> - - </row> - <row> - <entry> - realmName (*) - </entry> - <entry> - The name of the realm. This field is optional. The default value 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.realm.name</emphasis> is not empty, then the default value will be the value of the parameter. - </para> - - </listitem> - <listitem> - <para> - If this field and the parameter <emphasis>default.realm.name</emphasis> are both empty, the default value will be <emphasis>"exo-domain".</emphasis> - </para> - - </listitem> - - </orderedlist> - - </entry> - - </row> - <row> - <entry> - dependencies - </entry> - <entry> - All the dependencies of the portal container ordered by loading priority. This field is optional. If this field has a non empty value, it will be the default list of dependencies. - </entry> - - </row> - <row> - <entry> - settings - </entry> - <entry> - A <envar>java.util.Map</envar> of internal parameters that we would like to tie the default portal container. Those parameters could have any type of value. This field is optional. - </entry> - - </row> - <row> - <entry> - externalSettingsPath - </entry> - <entry> - The path of the external properties file to load as default settings to the default portal container. This field is optional. The external properties files can be either of type "properties" or of type "xml". The path will be interpreted as follows: - <orderedlist> - <listitem> - <para> - The path doesn't contain any prefix of type "classpath:", "jar:" or "file:", we assume that the file could be externalized so we apply the following rules: - <orderedlist> - <listitem> - <para> - A file exists at <emphasis>${exo-conf-dir}/portal/${externalSettingsPath}</emphasis>, we will load this file. - </para> - - </listitem> - <listitem> - <para> - No file exists at the previous path, we then assume that the path cans be interpreted by the <envar>ConfigurationManager</envar>. - </para> - - </listitem> - - </orderedlist> - - </para> - - </listitem> - <listitem> - <para> - The path contains a prefix, we then assume that the path cans be interpreted by the <envar>ConfigurationManager</envar>. - </para> - - </listitem> - - </orderedlist> - - </entry> - - </row> - - </tbody> - - </tgroup> - - </table> - <note> - <para> - All the value of the parameters marked with a (*) can be defined thanks to System properties like any values in configuration files but also thanks to variables loaded by the <emphasis>PropertyConfigurator</emphasis>. For example in GateIn by default, it would be all the variables defined in the file <emphasis>configuration.properties</emphasis>. - </para> - - </note> - <para> - Internal and external settings are both optional, but if we give a non empty value for both the application will merge the settings. If the same setting name exists in both settings, we apply the following rules: - </para> - <orderedlist> - <listitem> - <para> - The value of the external setting is <emphasis>null</emphasis>, we ignore the value. - </para> - - </listitem> - <listitem> - <para> - The value of the external setting is not <emphasis>null</emphasis> and the value of the internal setting is <emphasis>null</emphasis>, the final value will be the external setting value that is of type <envar>String</envar>. - </para> - - </listitem> - <listitem> - <para> - Both values are not <envar>null</envar>, we will have to convert the external setting value into the target type which is the type of the internal setting value, thanks to the static method <emphasis>valueOf(String)</emphasis>, the following sub-rules are then applied: - </para> - <orderedlist> - <listitem> - <para> - The method cannot be found, the final value will be the external setting value that is of type <envar>String</envar>. - </para> - - </listitem> - <listitem> - <para> - The method can be found and the external setting value is an empty <envar>String</envar>, we ignore the external setting value. - </para> - - </listitem> - <listitem> - <para> - The method can be found and the external setting value is not an empty <envar>String</envar> but the method call fails, we ignore the external setting value. - </para> - - </listitem> - <listitem> - <para> - The method can be found and the external setting value is not an empty <envar>String</envar> and the method call succeeds, the final value will be the external setting value that is of type of the internal setting value. - </para> - - </listitem> - - </orderedlist> - - </listitem> - - </orderedlist> - - </section> - - <section id="sect-Reference_Guide-Advanced_concepts_for_the_PortalContainers-PortalContainer_settings"> - <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 id="tabl-Reference_Guide-PortalContainer_settings-Definition_of_the_internal_variables"> - <title>Definition of the internal variables</title> - <tgroup cols="2"> - <tbody> - <row> - <entry> - portal.container.name - </entry> - <entry> - Gives the name of the current portal container. - </entry> - - </row> - <row> - <entry> - portal.container.rest - </entry> - <entry> - Gives the context name of the rest web application of the current portal container. - </entry> - - </row> - <row> - <entry> - portal.container.realm - </entry> - <entry> - Gives the realm name of the current portal container. - </entry> - - </row> - - </tbody> - - </tgroup> - - </table> - <para> - You can find below an example of how to use the variables: - </para> - -<programlisting language="XML" role="XML">&lt;configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.exoplaform.org/xml/ns/kernel_1_2.xsd http://www.exoplaform.org/xml/ns/kernel_1_2.xsd" - xmlns="http://www.exoplaform.org/xml/ns/kernel_1_2.xsd"&gt; + </para> + </listitem> + <listitem> + <para> + The path contains a prefix, we then assume that the path cans be interpreted by the <envar>ConfigurationManager</envar>. + </para> + </listitem> + </orderedlist></entry> + </row> + </tbody> + </tgroup> + </table> + <note> + <para> + All the value of the parameters marked with a (*) can be defined thanks to System properties like any values in configuration files but also thanks to variables loaded by the <emphasis>PropertyConfigurator</emphasis>. For example in GateIn by default, it would be all the variables defined in the file <emphasis>configuration.properties</emphasis>. + </para> + </note> + <para> + Internal and external settings are both optional, but if we give a non empty value for both the application will merge the settings. If the same setting name exists in both settings, we apply the following rules: + </para> + <orderedlist> + <listitem> + <para> + The value of the external setting is <emphasis>null</emphasis>, we ignore the value. + </para> + </listitem> + <listitem> + <para> + The value of the external setting is not <emphasis>null</emphasis> and the value of the internal setting is <emphasis>null</emphasis>, the final value will be the external setting value that is of type <envar>String</envar>. + </para> + </listitem> + <listitem> + <para> + Both values are not <envar>null</envar>, we will have to convert the external setting value into the target type which is the type of the internal setting value, thanks to the static method <emphasis>valueOf(String)</emphasis>, the following sub-rules are then applied: + </para> + <orderedlist> + <listitem> + <para> + The method cannot be found, the final value will be the external setting value that is of type <envar>String</envar>. + </para> + </listitem> + <listitem> + <para> + The method can be found and the external setting value is an empty <envar>String</envar>, we ignore the external setting value. + </para> + </listitem> + <listitem> + <para> + The method can be found and the external setting value is not an empty <envar>String</envar> but the method call fails, we ignore the external setting value. + </para> + </listitem> + <listitem> + <para> + The method can be found and the external setting value is not an empty <envar>String</envar> and the method call succeeds, the final value will be the external setting value that is of type of the internal setting value. + </para> + </listitem> + </orderedlist> + </listitem> + </orderedlist> + </section> + <section id="sect-Reference_Guide-Advanced_concepts_for_the_PortalContainers-PortalContainer_settings"> + <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 &quot;<emphasis>portal.container.</emphasis>&quot;, so to get the value of a setting called &quot;<emphasis>foo</emphasis>&quot;, just use the following syntax <emphasis>${portal.container.foo}</emphasis>. You can also use internal variables, such as: + </para> + <table id="tabl-Reference_Guide-PortalContainer_settings-Definition_of_the_internal_variables"> + <title>Definition of the internal variables</title> + <tgroup cols="2"> + <tbody> + <row> + <entry> portal.container.name </entry> + <entry> Gives the name of the current portal container. </entry> + </row> + <row> + <entry> portal.container.rest </entry> + <entry> Gives the context name of the rest web application of the current portal container. </entry> + </row> + <row> + <entry> portal.container.realm </entry> + <entry> Gives the realm name of the current portal container. </entry> + </row> + </tbody> + </tgroup> + </table> + <para> + You can find below an example of how to use the variables: + </para> + <programlisting language="XML" role="XML">&lt;configuration xmlns:xsi=&quot;http://www.w3.org/2001/XMLSchema-instance&quot; xsi:schemaLocation=&quot;http://www.exoplaform.org/xml/ns/kernel_1_2.xsd http://www.exoplaform.org/xml/ns/kernel_1_2.xsd&quot; + xmlns=&quot;http://www.exoplaform.org/xml/ns/kernel_1_2.xsd&quot;... &lt;component&gt; &lt;type&gt;org.exoplatform.container.TestPortalContainer$MyComponent&lt;/type&gt; &lt;init-params&gt; @@ -740,39 +559,35 @@ &lt;/init-params&gt; &lt;/component&gt; &lt;/configuration&gt;</programlisting> - <para> - In the properties file corresponding to the external settings, you can reuse variables previously defined (in the external settings or in the internal settings) to create a new variable. In this case, the prefix "<emphasis>portal.container.</emphasis>" is not needed, see an example below: + <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 &quot;<emphasis>portal.container.</emphasis>&quot; 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 parameters. 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 useful 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> + In the external and internal settings, you can also use create variables based on value of System parameters. 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 useful 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 &quot;${name}&quot;</programlisting> - </para> - <para> - If this variable is defined at the default portal container level, the value of this variable for a portal container called <emphasis>"foo"</emphasis> will be <emphasis>value of the portal container "foo"</emphasis>. - </para> - - </section> - - <section id="sect-Reference_Guide-Advanced_concepts_for_the_PortalContainers-Adding_dynamically_settings_andor_dependencies_to_a_PortalContainer"> - <title>Adding dynamically settings and/or dependencies to a <envar>PortalContainer</envar></title> - <para> - It is possible to use <envar>component-plugin</envar> elements in order to dynamically change a PortalContainerDefinition. In the example below, we add the dependency <envar>foo</envar> to the default portal container and to the portal containers called <envar>foo1</envar> and <envar>foo2</envar>: - </para> - -<programlisting language="XML" role="XML">&lt;external-component-plugins&gt; + </para> + <para> + If this variable is defined at the default portal container level, the value of this variable for a portal container called <emphasis>&quot;foo&quot;</emphasis> will be <emphasis>value of the portal container &quot;foo&quot;</emphasis>. + </para> + </section> + <section id="sect-Reference_Guide-Advanced_concepts_for_the_PortalContainers-Adding_dynamically_settings_andor_dependencies_to_a_PortalContainer"> + <title>Adding dynamically settings and/or dependencies to a <envar>PortalContainer</envar></title> + <para> + It is possible to use <envar>component-plugin</envar> elements in order to dynamically change a PortalContainerDefinition. In the example below, we add the dependency <envar>foo</envar> to the default portal container and to the portal containers called <envar>foo1</envar> and <envar>foo2</envar>: + </para> + <programlisting language="XML" role="XML">&lt;external-component-plugins&gt; &lt;!-- The full qualified name of the PortalContainerConfig --&gt; &lt;target-component&gt;org.exoplatform.container.definition.PortalContainerConfig&lt;/target-component&gt; &lt;component-plugin&gt; @@ -794,10 +609,10 @@ &lt;/values-param&gt; &lt;object-param&gt; &lt;name&gt;change&lt;/name&gt; - &lt;object type="org.exoplatform.container.definition.PortalContainerDefinitionChange$AddDependencies"&gt; + &lt;object type=&quot;org.exoplatform.container.definition.PortalContainerDefinitionChange$AddDependencies&quot;&gt; &lt;!-- The list of name of the dependencies to add --&gt; - &lt;field name="dependencies"&gt; - &lt;collection type="java.util.ArrayList"&gt; + &lt;field name=&quot;dependencies&quot;&gt; + &lt;collection type=&quot;java.util.ArrayList&quot;&gt; &lt;value&gt; &lt;string&gt;foo&lt;/string&gt; &lt;/value&gt; @@ -808,128 +623,93 @@ &lt;/init-params&gt; &lt;/component-plugin&gt; &lt;/external-component-plugins&gt;</programlisting> - <table id="tabl-Reference_Guide-Adding_dynamically_settings_andor_dependencies_to_a_PortalContainer-Descriptions_of_the_fields_of_a_PortalContainerDefinitionChangePlugin"> - <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 parameters are <envar>ObjectParam</envar> of type <envar>PortalContainerDefinitionChange</envar>. Those parameters are in fact the list of changes that we want to apply to one or several portal containers. If the list of changes is empty, the component plugin will be ignored. The supported implementations of PortalContainerDefinitionChange are described later in this section. - </entry> - - </row> - - </tbody> - - </tgroup> - - </table> - <note> - <para> - All the value of the parameters marked with a (*) can be defined thanks to System properties like any values in configuration files but also thanks to variables loaded by the <emphasis>PropertyConfigurator</emphasis>. For example in GateIn by default, it would be all the variables defined in the file <emphasis>configuration.properties</emphasis>. - </para> - - </note> - <para> - To identify the portal containers to which the changes have to be applied, we use the following algorithm: - </para> - <orderedlist> - <listitem> - <para> - The parameter <envar>apply.all</envar> has been set to <envar>true</envar>. The corresponding changes will be applied to all the portal containers. The other parameters will be ignored. - </para> - - </listitem> - <listitem> - <para> - The parameter <envar>apply.default</envar> has been set to <envar>true</envar> and the parameter <envar>apply.specific</envar> is <envar>null</envar>. The corresponding changes will be applied to the default portal container only. - </para> - - </listitem> - <listitem> - <para> - The parameter <envar>apply.default</envar> has been set to <envar>true</envar> and the parameter <envar>apply.specific</envar> is not <envar>null</envar>. The corresponding changes will be applied to the default portal container and the given list of specific portal containers. - </para> - - </listitem> - <listitem> - <para> - The parameter <envar>apply.default</envar> has been set to <envar>false</envar> or has not been set and the parameter <envar>apply.specific</envar> is <envar>null</envar>. The corresponding changes will be applied to the default portal container only. - </para> - - </listitem> - <listitem> - <para> - The parameter <envar>apply.default</envar> has been set to <envar>false</envar> or has not been set and the parameter <envar>apply.specific</envar> is not <envar>null</envar>. The corresponding changes will be applied to the given list of specific portal containers. - </para> - - </listitem> - - </orderedlist> - <section id="sect-Reference_Guide-Adding_dynamically_settings_andor_dependencies_to_a_PortalContainer-The_existing_implementations_of_PortalContainerDefinitionChange"> - <title>The existing implementations of <envar>PortalContainerDefinitionChange</envar></title> - <para> - The modifications that can be applied to a <envar>PortalContainerDefinition</envar> must be a class of type <envar>PortalContainerDefinitionChange</envar>. The product proposes out of the box some implementations that we describe in the next sub sections. - </para> - <section id="sect-Reference_Guide-The_existing_implementations_of_PortalContainerDefinitionChange-AddDependencies"> - <title><envar>AddDependencies</envar></title> - <para> - This modification adds a list of dependencies at the end of the list of dependencies defined into the <envar>PortalContainerDefinition</envar>. The full qualified name is <emphasis>org.exoplatform.container.definition.PortalContainerDefinitionChange$AddDependencies</emphasis>. - </para> - <table id="tabl-Reference_Guide-AddDependencies-Descriptions_of_the_fields_of_an_AddDependencies"> - <title>Descriptions of the fields of an <envar>AddDependencies</envar></title> - <tgroup cols="2"> - <tbody> - <row> - <entry> - dependencies - </entry> - <entry> - A list of <emphasis>String</emphasis> corresponding to the list of name of the dependencies to add. If the value of this field is empty, the change will be ignored. - </entry> - - </row> - - </tbody> - - </tgroup> - - </table> - <para> - See an example below, that will add <envar>foo</envar> at the end of the dependency list of the default portal container: - </para> - -<programlisting language="XML" role="XML">&lt;external-component-plugins&gt; + <table id="tabl-Reference_Guide-Adding_dynamically_settings_andor_dependencies_to_a_PortalContainer-Descriptions_of_the_fields_of_a_PortalContainerDefinitionChangePlugin"> + <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 parameters 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 plug-in will be ignored. The supported implementations of PortalContainerDefinitionChange are described later in this section. </entry> + </row> + </tbody> + </tgroup> + </table> + <note> + <para> + All the value of the parameters marked with a (*) can be defined thanks to System properties like any values in configuration files but also thanks to variables loaded by the <emphasis>PropertyConfigurator</emphasis>. For example in GateIn by default, it would be all the variables defined in the file <emphasis>configuration.properties</emphasis>. + </para> + </note> + <para> + To identify the portal containers to which the changes have to be applied, we use the following algorithm: + </para> + <orderedlist> + <listitem> + <para> + The parameter <envar>apply.all</envar> has been set to <envar>true</envar>. The corresponding changes will be applied to all the portal containers. The other parameters will be ignored. + </para> + </listitem> + <listitem> + <para> + The parameter <envar>apply.default</envar> has been set to <envar>true</envar> and the parameter <envar>apply.specific</envar> is <envar>null</envar>. The corresponding changes will be applied to the default portal container only. + </para> + </listitem> + <listitem> + <para> + The parameter <envar>apply.default</envar> has been set to <envar>true</envar> and the parameter <envar>apply.specific</envar> is not <envar>null</envar>. The corresponding changes will be applied to the default portal container and the given list of specific portal containers. + </para> + </listitem> + <listitem> + <para> + The parameter <envar>apply.default</envar> has been set to <envar>false</envar> or has not been set and the parameter <envar>apply.specific</envar> is <envar>null</envar>. The corresponding changes will be applied to the default portal container only. + </para> + </listitem> + <listitem> + <para> + The parameter <envar>apply.default</envar> has been set to <envar>false</envar> or has not been set and the parameter <envar>apply.specific</envar> is not <envar>null</envar>. The corresponding changes will be applied to the given list of specific portal containers. + </para> + </listitem> + </orderedlist> + <section id="sect-Reference_Guide-Adding_dynamically_settings_andor_dependencies_to_a_PortalContainer-The_existing_implementations_of_PortalContainerDefinitionChange"> + <title>The existing implementations of <envar>PortalContainerDefinitionChange</envar></title> + <para> + The modifications that can be applied to a <envar>PortalContainerDefinition</envar> must be a class of type <envar>PortalContainerDefinitionChange</envar>. The product proposes out of the box some implementations that we describe in the next sub sections. + </para> + <section id="sect-Reference_Guide-The_existing_implementations_of_PortalContainerDefinitionChange-AddDependencies"> + <title> + <envar>AddDependencies</envar> + </title> + <para> + This modification adds a list of dependencies at the end of the list of dependencies defined into the <envar>PortalContainerDefinition</envar>. The full qualified name is <emphasis>org.exoplatform.container.definition.PortalContainerDefinitionChange$AddDependencies</emphasis>. + </para> + <table id="tabl-Reference_Guide-AddDependencies-Descriptions_of_the_fields_of_an_AddDependencies"> + <title>Descriptions of the fields of an <envar>AddDependencies</envar></title> + <tgroup cols="2"> + <tbody> + <row> + <entry> dependencies </entry> + <entry> A list of <emphasis>String</emphasis> corresponding to the list of name of the dependencies to add. If the value of this field is empty, the change will be ignored. </entry> + </row> + </tbody> + </tgroup> + </table> + <para> + See an example below, that will add <envar>foo</envar> at the end of the dependency list of the default portal container: + </para> + <programlisting language="XML" role="XML">&lt;external-component-plugins&gt; &lt;!-- The full qualified name of the PortalContainerConfig --&gt; &lt;target-component&gt;org.exoplatform.container.definition.PortalContainerConfig&lt;/target-component&gt; &lt;component-plugin&gt; @@ -946,10 +726,10 @@ &lt;/value-param&gt; &lt;object-param&gt; &lt;name&gt;change&lt;/name&gt; - &lt;object type="org.exoplatform.container.definition.PortalContainerDefinitionChange$AddDependencies"&gt; + &lt;object type=&quot;org.exoplatform.container.definition.PortalContainerDefinitionChange$AddDependencies&quot;&gt; &lt;!-- The list of name of the dependencies to add --&gt; - &lt;field name="dependencies"&gt; - &lt;collection type="java.util.ArrayList"&gt; + &lt;field name=&quot;dependencies&quot;&gt; + &lt;collection type=&quot;java.util.ArrayList&quot;&gt; &lt;value&gt; &lt;string&gt;foo&lt;/string&gt; &lt;/value&gt; @@ -960,47 +740,33 @@ &lt;/init-params&gt; &lt;/component-plugin&gt; &lt;/external-component-plugins&gt;</programlisting> - - </section> - - <section id="sect-Reference_Guide-The_existing_implementations_of_PortalContainerDefinitionChange-AddDependenciesBefore"> - <title><envar>AddDependenciesBefore</envar></title> - <para> - This modification adds a list of dependencies before a given target dependency defined into the list of dependencies of the <envar>PortalContainerDefinition</envar>. The full qualified name is <emphasis>org.exoplatform.container.definition.PortalContainerDefinitionChange$AddDependenciesBefore</emphasis>. - </para> - <table id="tabl-Reference_Guide-AddDependenciesBefore-Descriptions_of_the_fields_of_an_AddDependenciesBefore"> - <title>Descriptions of the fields of an <envar>AddDependenciesBefore</envar></title> - <tgroup cols="2"> - <tbody> - <row> - <entry> - dependencies - </entry> - <entry> - A list of <emphasis>String</emphasis> corresponding to the list of name of the dependencies to add. If the value of this field is empty, the change will be ignored. - </entry> - - </row> - <row> - <entry> - target - </entry> - <entry> - The name of the dependency before which we would like to add the new dependencies. If this field is <envar>null</envar> or the target dependency cannot be found in the list of dependencies defined into the <envar>PortalContainerDefinition</envar>, the new dependencies will be added in first position to the list. - </entry> - - </row> - - </tbody> - - </tgroup> - - </table> - <para> - See an example below, that will add <envar>foo</envar> before <envar>foo2</envar> in the dependency list of the default portal container: - </para> - -<programlisting language="XML" role="XML">&lt;external-component-plugins&gt; + </section> + <section id="sect-Reference_Guide-The_existing_implementations_of_PortalContainerDefinitionChange-AddDependenciesBefore"> + <title> + <envar>AddDependenciesBefore</envar> + </title> + <para> + This modification adds a list of dependencies before a given target dependency defined into the list of dependencies of the <envar>PortalContainerDefinition</envar>. The full qualified name is <emphasis>org.exoplatform.container.definition.PortalContainerDefinitionChange$AddDependenciesBefore</emphasis>. + </para> + <table id="tabl-Reference_Guide-AddDependenciesBefore-Descriptions_of_the_fields_of_an_AddDependenciesBefore"> + <title>Descriptions of the fields of an <envar>AddDependenciesBefore</envar></title> + <tgroup cols="2"> + <tbody> + <row> + <entry> dependencies </entry> + <entry> A list of <emphasis>String</emphasis> corresponding to the list of name of the dependencies to add. If the value of this field is empty, the change will be ignored. </entry> + </row> + <row> + <entry> target </entry> + <entry> The name of the dependency before which we would like to add the new dependencies. If this field is <envar>null</envar> or the target dependency cannot be found in the list of dependencies defined into the <envar>PortalContainerDefinition</envar>, the new dependencies will be added in first position to the list. </entry> + </row> + </tbody> + </tgroup> + </table> + <para> + See an example below, that will add <envar>foo</envar> before <envar>foo2</envar> in the dependency list of the default portal container: + </para> + <programlisting language="XML" role="XML">&lt;external-component-plugins&gt; &lt;!-- The full qualified name of the PortalContainerConfig --&gt; &lt;target-component&gt;org.exoplatform.container.definition.PortalContainerConfig&lt;/target-component&gt; &lt;component-plugin&gt; @@ -1017,17 +783,17 @@ &lt;/value-param&gt; &lt;object-param&gt; &lt;name&gt;change&lt;/name&gt; - &lt;object type="org.exoplatform.container.definition.PortalContainerDefinitionChange$AddDependenciesBefore"&gt; + &lt;object type=&quot;org.exoplatform.container.definition.PortalContainerDefinitionChange$AddDependenciesBefore&quot;&gt; &lt;!-- The list of name of the dependencies to add --&gt; - &lt;field name="dependencies"&gt; - &lt;collection type="java.util.ArrayList"&gt; + &lt;field name=&quot;dependencies&quot;&gt; + &lt;collection type=&quot;java.util.ArrayList&quot;&gt; &lt;value&gt; &lt;string&gt;foo&lt;/string&gt; &lt;/value&gt; &lt;/collection&gt; &lt;/field&gt; &lt;!-- The name of the target dependency --&gt; - &lt;field name="target"&gt; + &lt;field name=&quot;target&quot;&gt; &lt;string&gt;foo2&lt;/string&gt; &lt;/field&gt; &lt;/object&gt; @@ -1035,47 +801,33 @@ &lt;/init-params&gt; &lt;/component-plugin&gt; &lt;/external-component-plugins&gt;</programlisting> - - </section> - - <section id="sect-Reference_Guide-The_existing_implementations_of_PortalContainerDefinitionChange-AddDependenciesAfter"> - <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 id="tabl-Reference_Guide-AddDependenciesAfter-Descriptions_of_the_fields_of_an_AddDependenciesAfter"> - <title>Descriptions of the fields of an <envar>AddDependenciesAfter</envar></title> - <tgroup cols="2"> - <tbody> - <row> - <entry> - dependencies - </entry> - <entry> - A list of <emphasis>String</emphasis> corresponding to the list of name of the dependencies to add. If the value of this field is empty, the change will be ignored. - </entry> - - </row> - <row> - <entry> - target - </entry> - <entry> - The name of the dependency after which we would like to add the new dependencies. If this field is <envar>null</envar> or the target dependency cannot be found in the list of dependencies defined into the <envar>PortalContainerDefinition</envar>, the new dependencies will be added in last position to the list. - </entry> - - </row> - - </tbody> - - </tgroup> - - </table> - <para> - See an example below, that will add <envar>foo</envar> after <envar>foo2</envar> in the dependency list of the default portal container: - </para> - -<programlisting language="XML" role="XML">&lt;external-component-plugins&gt; + </section> + <section id="sect-Reference_Guide-The_existing_implementations_of_PortalContainerDefinitionChange-AddDependenciesAfter"> + <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 id="tabl-Reference_Guide-AddDependenciesAfter-Descriptions_of_the_fields_of_an_AddDependenciesAfter"> + <title>Descriptions of the fields of an <envar>AddDependenciesAfter</envar></title> + <tgroup cols="2"> + <tbody> + <row> + <entry> dependencies </entry> + <entry> A list of <emphasis>String</emphasis> corresponding to the list of name of the dependencies to add. If the value of this field is empty, the change will be ignored. </entry> + </row> + <row> + <entry> target </entry> + <entry> The name of the dependency after which we would like to add the new dependencies. If this field is <envar>null</envar> or the target dependency cannot be found in the list of dependencies defined into the <envar>PortalContainerDefinition</envar>, the new dependencies will be added in last position to the list. </entry> + </row> + </tbody> + </tgroup> + </table> + <para> + See an example below, that will add <envar>foo</envar> after <envar>foo2</envar> in the dependency list of the default portal container: + </para> + <programlisting language="XML" role="XML">&lt;external-component-plugins&gt; &lt;!-- The full qualified name of the PortalContainerConfig --&gt; &lt;target-component&gt;org.exoplatform.container.definition.PortalContainerConfig&lt;/target-component&gt; &lt;component-plugin&gt; @@ -1092,17 +844,17 @@ &lt;/value-param&gt; &lt;object-param&gt; &lt;name&gt;change&lt;/name&gt; - &lt;object type="org.exoplatform.container.definition.PortalContainerDefinitionChange$AddDependenciesAfter"&gt; + &lt;object type=&quot;org.exoplatform.container.definition.PortalContainerDefinitionChange$AddDependenciesAfter&quot;&gt; &lt;!-- The list of name of the dependencies to add --&gt; - &lt;field name="dependencies"&gt; - &lt;collection type="java.util.ArrayList"&gt; + &lt;field name=&quot;dependencies&quot;&gt; + &lt;collection type=&quot;java.util.ArrayList&quot;&gt; &lt;value&gt; &lt;string&gt;foo&lt;/string&gt; &lt;/value&gt; &lt;/collection&gt; &lt;/field&gt; &lt;!-- The name of the target dependency --&gt; - &lt;field name="target"&gt; + &lt;field name=&quot;target&quot;&gt; &lt;string&gt;foo2&lt;/string&gt; &lt;/field&gt; &lt;/object&gt; @@ -1110,38 +862,29 @@ &lt;/init-params&gt; &lt;/component-plugin&gt; &lt;/external-component-plugins&gt;</programlisting> - - </section> - - <section id="sect-Reference_Guide-The_existing_implementations_of_PortalContainerDefinitionChange-AddSettings"> - <title><envar>AddSettings</envar></title> - <para> - This modification adds new settings to a <envar>PortalContainerDefinition</envar>. The full qualified name is <emphasis>org.exoplatform.container.definition.PortalContainerDefinitionChange$AddSettings</emphasis>. - </para> - <table id="tabl-Reference_Guide-AddSettings-Descriptions_of_the_fields_of_an_AddSettings"> - <title>Descriptions of the fields of an <envar>AddSettings</envar></title> - <tgroup cols="2"> - <tbody> - <row> - <entry> - settings - </entry> - <entry> - A map of <emphasis>&lt;String, Object&gt;</emphasis> corresponding to the settings to add. If the value of this field is empty, the change will be ignored. - </entry> - - </row> - - </tbody> - - </tgroup> - - </table> - <para> - See an example below, that will add the settings <envar>string</envar> and <envar>stringX</envar> to the settings of the default portal container: - </para> - -<programlisting language="XML" role="XML">&lt;external-component-plugins&gt; + </section> + <section id="sect-Reference_Guide-The_existing_implementations_of_PortalContainerDefinitionChange-AddSettings"> + <title> + <envar>AddSettings</envar> + </title> + <para> + This modification adds new settings to a <envar>PortalContainerDefinition</envar>. The full qualified name is <emphasis>org.exoplatform.container.definition.PortalContainerDefinitionChange$AddSettings</emphasis>. + </para> + <table id="tabl-Reference_Guide-AddSettings-Descriptions_of_the_fields_of_an_AddSettings"> + <title>Descriptions of the fields of an <envar>AddSettings</envar></title> + <tgroup cols="2"> + <tbody> + <row> + <entry> settings </entry> + <entry> A map of <emphasis>&lt;String, Object&gt;</emphasis> corresponding to the settings to add. If the value of this field is empty, the change will be ignored. </entry> + </row> + </tbody> + </tgroup> + </table> + <para> + See an example below, that will add the settings <envar>string</envar> and <envar>stringX</envar> to the settings of the default portal container: + </para> + <programlisting language="XML" role="XML">&lt;external-component-plugins&gt; &lt;!-- The full qualified name of the PortalContainerConfig --&gt; &lt;target-component&gt;org.exoplatform.container.definition.PortalContainerConfig&lt;/target-component&gt; &lt;component-plugin&gt; @@ -1158,10 +901,10 @@ &lt;/value-param&gt; &lt;object-param&gt; &lt;name&gt;change&lt;/name&gt; - &lt;object type="org.exoplatform.container.definition.PortalContainerDefinitionChange$AddSettings"&gt; + &lt;object type=&quot;org.exoplatform.container.definition.PortalContainerDefinitionChange$AddSettings&quot;&gt; &lt;!-- The settings to add to the to the portal containers --&gt; - &lt;field name="settings"&gt; - &lt;map type="java.util.HashMap"&gt; + &lt;field name=&quot;settings&quot;&gt; + &lt;map type=&quot;java.util.HashMap&quot;&gt; &lt;entry&gt; &lt;key&gt; &lt;string&gt;string&lt;/string&gt; @@ -1185,22 +928,15 @@ &lt;/init-params&gt; &lt;/component-plugin&gt; &lt;/external-component-plugins&gt;</programlisting> - - </section> - - - </section> - - - </section> - - <section id="sect-Reference_Guide-Advanced_concepts_for_the_PortalContainers-Disable_dynamically_a_portal_container"> - <title>Disable dynamically a portal container</title> - <para> - It is possible to use <envar>component-plugin</envar> elements in order to dynamically disable one or several portal containers. In the example below, we disable the portal container named <envar>foo</envar>: - </para> - -<programlisting language="XML" role="XML">&lt;external-component-plugins&gt; + </section> + </section> + </section> + <section id="sect-Reference_Guide-Advanced_concepts_for_the_PortalContainers-Disable_dynamically_a_portal_container"> + <title>Disable dynamically a portal container</title> + <para> + It is possible to use <envar>component-plugin</envar> elements in order to dynamically disable one or several portal containers. In the example below, we disable the portal container named <envar>foo</envar>: + </para> + <programlisting language="XML" role="XML">&lt;external-component-plugins&gt; &lt;!-- The full qualified name of the PortalContainerConfig --&gt; &lt;target-component&gt;org.exoplatform.container.definition.PortalContainerConfig&lt;/target-component&gt; &lt;component-plugin&gt; @@ -1219,36 +955,26 @@ &lt;/init-params&gt; &lt;/component-plugin&gt; &lt;/external-component-plugins&gt;</programlisting> - <table id="tabl-Reference_Guide-Disable_dynamically_a_portal_container-Descriptions_of_the_fields_of_a_PortalContainerDefinitionDisablePlugin"> - <title>Descriptions of the fields of a <envar>PortalContainerDefinitionDisablePlugin</envar></title> - <tgroup cols="2"> - <tbody> - <row> - <entry> - names (*) - </entry> - <entry> - The list of the name of the portal containers to disable. - </entry> - - </row> - - </tbody> - - </tgroup> - - </table> - <note> - <para> - All the value of the parameters marked with a (*) can be defined thanks to System properties like any values in configuration files but also thanks to variables loaded by the <emphasis>PropertyConfigurator</emphasis>. For example in GateIn by default, it would be all the variables defined in the file <emphasis>configuration.properties</emphasis>. - </para> - - </note> - <para> - To prevent any accesses to a web application corresponding to <envar>PortalContainer</envar> that has been disabled, you need to make sure that the following Http Filter (or a sub class of it) has been added to your web.xml in first position as below: - </para> - -<programlisting language="XML" role="XML">&lt;filter&gt; + <table id="tabl-Reference_Guide-Disable_dynamically_a_portal_container-Descriptions_of_the_fields_of_a_PortalContainerDefinitionDisablePlugin"> + <title>Descriptions of the fields of a <envar>PortalContainerDefinitionDisablePlugin</envar></title> + <tgroup cols="2"> + <tbody> + <row> + <entry> names (*) </entry> + <entry> The list of the name of the portal containers to disable. </entry> + </row> + </tbody> + </tgroup> + </table> + <note> + <para> + All the value of the parameters marked with a (*) can be defined thanks to System properties like any values in configuration files but also thanks to variables loaded by the <emphasis>PropertyConfigurator</emphasis>. For example in GateIn by default, it would be all the variables defined in the file <emphasis>configuration.properties</emphasis>. + </para> + </note> + <para> + To prevent any accesses to a web application corresponding to <envar>PortalContainer</envar> that has been disabled, you need to make sure that the following Http Filter (or a sub class of it) has been added to your web.xml in first position as below: + </para> + <programlisting language="XML" role="XML">&lt;filter&gt; &lt;filter-name&gt;PortalContainerFilter&lt;/filter-name&gt; &lt;filter-class&gt;org.exoplatform.container.web.PortalContainerFilter&lt;/filter-class&gt; &lt;/filter&gt; @@ -1257,16 +983,10 @@ &lt;filter-name&gt;PortalContainerFilter&lt;/filter-name&gt; &lt;url-pattern&gt;/*&lt;/url-pattern&gt; &lt;/filter-mapping&gt;</programlisting> - <note> - <para> - It is only possible to disable a portal container when at least one PortalContainerDefinition has been registered. - </para> - - </note> - - </section> - - + <note> + <para> + It is only possible to disable a portal container when at least one PortalContainerDefinition has been registered. + </para> + </note> + </section> </section> - - Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/Advanced/Foundations/Config_Retrieval.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/Advanced/Foundations/Config_Retrieval.xml 2012-07-05 19:41:59 UTC (rev 8774) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/Advanced/Foundations/Config_Retrieval.xml 2012-07-06 05:00:36 UTC (rev 8775) @@ -1,81 +1,70 @@ -<?xml version='1.0' encoding='utf-8' ?> +<?xml version='1.0' encoding='UTF-8'?> <!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!ENTITY % BOOK_ENTITIES SYSTEM "Reference_Guide.ent"> %BOOK_ENTITIES; ]> <section id="sect-Reference_Guide-Configuration_Retrieval"> - <title>Configuration Retrieval</title> - <para> - The container performs the following steps for configuration retrieval, depending on the container type. - </para> - <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> - <procedure> - <step> - <para> - Services default <envar>RootContainer</envar> configurations from JAR files <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/conf/gatein/configuration.xml</filename>. - </para> - - </step> - <step> - <para> - External <envar>RootContainer</envar> configuration can be found at <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/conf/gatein/configuration.xml</filename>. - </para> - - </step> - <step> - <para> - Services default <envar>PortalContainer</envar> configurations from JAR files <filename>/conf/portal/configuration.xml</filename>. - </para> - - </step> - <step> - <para> - Web applications configurations from WAR files <filename>/WEB-INF/conf/configuration.xml</filename> - </para> - - </step> - <step> - <para> - External configuration for services of named portal can be found at <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/conf/gatein/configuration.xml</filename>. - </para> - - </step> - - </procedure> - - <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 (<filename>/conf/portal/configuration.xml</filename> and <filename>/conf/configuration.xml</filename>) 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 <filename>/conf/portal/configuration.xml</filename> of a given JAR file, you must not do it from the file <filename>/conf/portal/configuration.xml</filename> of another JAR file but from another configuration file loaded after configurations from JAR files <filename>/conf/portal/configuration.xml.</filename> - </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> - <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 <literal>org.exoplatform.container.configuration.debug</literal> can be used. - </para> - -<programlisting>java -Dorg.exoplatform.container.configuration.debug ...</programlisting> - <para> - If the property is enabled, the container configuration manager will log the configuration adding process at <emphasis>INFO</emphasis> level. - </para> - -<programlisting>...... + <title>Configuration Retrieval</title> + <para> + The container performs the following steps for configuration retrieval, depending on the container type. + </para> + <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> + <procedure> + <step> + <para> + Services default <envar>RootContainer</envar> configurations from JAR files <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/conf/gatein/configuration.xml</filename>. + </para> + </step> + <step> + <para> + External <envar>RootContainer</envar> configuration can be found at <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/conf/gatein/configuration.xml</filename>. + </para> + </step> + <step> + <para> + Services default <envar>PortalContainer</envar> configurations from JAR files <filename>/conf/portal/configuration.xml</filename>. + </para> + </step> + <step> + <para> + Web applications configurations from WAR files <filename>/WEB-INF/conf/configuration.xml</filename> + </para> + </step> + <step> + <para> + External configuration for services of named portal can be found at <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/conf/gatein/configuration.xml</filename>. + </para> + </step> + </procedure> + <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 (<filename>/conf/portal/configuration.xml</filename> and <filename>/conf/configuration.xml</filename>) 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 <filename>/conf/portal/configuration.xml</filename> of a given JAR file, you must not do it from the file <filename>/conf/portal/configuration.xml</filename> of another JAR file but from another configuration file loaded after configurations from JAR files <filename>/conf/portal/configuration.xml.</filename> + </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&apos;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&apos;s critical who will be the last, i.e. whose configuration will be used. In the second case, it&apos;s no matter who is the first and who is the last (if the parameter objects are independent). + </para> + <para> + In case of problems with service configuration, it&apos;s important to know from which JAR/WAR it comes. For that purpose, the JVM system property <literal>org.exoplatform.container.configuration.debug</literal> can be used. + </para> + <programlisting>java -Dorg.exoplatform.container.configuration.debug ...</programlisting> + <para> + If the property is enabled, the container configuration manager will log the configuration adding process at <emphasis>INFO</emphasis> level. + </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 @@ -84,10 +73,7 @@ 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> - 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> - + <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&apos;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 plug-in has been initialized. + </para> </section> - - Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/Advanced/Foundations/Configuring_Services.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/Advanced/Foundations/Configuring_Services.xml 2012-07-05 19:41:59 UTC (rev 8774) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/Advanced/Foundations/Configuring_Services.xml 2012-07-06 05:00:36 UTC (rev 8775) @@ -1,72 +1,68 @@ -<?xml version='1.0' encoding='utf-8' ?> +<?xml version='1.0' encoding='UTF-8'?> <!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!ENTITY % BOOK_ENTITIES SYSTEM "Reference_Guide.ent"> %BOOK_ENTITIES; ]> <section id="sect-Reference_Guide-Configuring_Services"> - <title>Configuring Services</title> - <para> + <title>Configuring Services</title> + <para> The eXo Kernel uses dependency injection to create services based on <filename>configuration.xml</filename> configuration files. The location of the configuration files determines if services are placed into the <literal>RootContainer</literal> scope, or into the <literal>PortalContainer</literal> scope. </para> - <para> + <para> When creating a service, you also should declare its existence to the <emphasis role="bold">Container</emphasis>. This fan be done by creating a simple configuration file. </para> - <para> + <para> Copy the following code to a <filename>configuration.xml</filename> file and save this file in a <filename>/conf</filename> subdirectory of your service base folder. The container looks for a <filename>/conf/configuration.xml</filename> file in each jar-file. </para> - <para> + <para> All <filename>configuration.xml</filename> files located at <filename>conf/configuration.xml</filename> in the classpath (any directory, or any jar in the classpath) will have their services configured in the <literal>RootContainer</literal> scope. </para> - <para> + <para> All <filename>configuration.xml</filename> files located at <filename>conf/portal/configuration.xml</filename> in the classpath will have their services configured at the <literal>PortalContainer</literal> scope. </para> - <para> + <para> Additionally, <emphasis role="bold">portal extensions</emphasis> can use configuration information stored in <filename><replaceable>JBOSS_HOME</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/configuration.xml</filename>, and will also have their services configured in the <literal>PortalContainer</literal> scope. </para> - <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> - <para> + <note> + <para> <emphasis role="bold">Portal extensions</emphasis> are described later in this document. </para> - - </note> - <section id="sect-Reference_Guide-Configuring_Services-Configuration_syntax"> - <title>Configuration syntax</title> - <section id="sect-Reference_Guide-Configuration_syntax-Components"> - <title>Components</title> - <para> + </note> + <section id="sect-Reference_Guide-Configuring_Services-Configuration_syntax"> + <title>Configuration syntax</title> + <section id="sect-Reference_Guide-Configuration_syntax-Components"> + <title>Components</title> + <para> A service component is defined in <filename>configuration.xml</filename> by using a <emphasis role="bold">&lt;component&gt;</emphasis> element. </para> - <para> + <para> Only one piece of information is required when defining a service; the service implementation class. This is specified using <literal>&lt;type&gt;</literal> </para> - <para> + <para> Every component has a <literal>&lt;key&gt;</literal> that identifies it. If not explicitly set, a key defaults to the value of <literal>&lt;type&gt;</literal>. If a key can be loaded as a class, a class object is used as a key, otherwise a string is used. </para> - <para> + <para> The usual approach is to specify an interface as a key. </para> - -<programlisting language="XML" role="XML"><xi:include href="../../../extras/Advanced_Development_Foundations/default.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <para> - The configuration found 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>. + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/Advanced_Development_Foundations/default.xml" parse="text"/></programlisting> + <para> + The configuration found 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&apos;s call this the <emphasis>configuration override mechanism</emphasis>. </para> - <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 it improves performance. + <para> + After deploying you find the configuration.xml file in webapps/portal/WEB-INF/conf Use component registration tags. Let&apos;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 it improves performance. </para> - -<programlisting language="XML" role="XML">&lt;!-- Portlet container hooks --&gt; + <programlisting language="XML" role="XML">&lt;!-- Portlet container hooks --&gt; &lt;component&gt; &lt;key&gt;org.exoplatform.services.portletcontainer.persistence.PortletPreferencesPersister&lt;/key&gt; &lt;type&gt;org.exoplatform.services.portal.impl.PortletPreferencesPersisterImpl&lt;/type&gt; &lt;/component&gt;</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> + Register plug-ins that can act as listeners or external plug-in to bundle some plug-in 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 language="XML" role="XML">&lt;external-component-plugins&gt; + <programlisting language="XML" role="XML">&lt;external-component-plugins&gt; &lt;target-component&gt;org.exoplatform.services.database.HibernateService&lt;/target-component&gt; &lt;component-plugin&gt; &lt;name&gt;add.hibernate.mapping&lt;/name&gt; @@ -82,17 +78,16 @@ &lt;/init-params&gt; &lt;/component-plugin&gt; &lt;/external-component-plugins&gt;</programlisting> - <para> + <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> + Therefore, it is possible to define services that will be able to receive plug-ins without implementing any framework interface. </para> - <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 language="XML" role="XML">&lt;external-component-plugins&gt; + <programlisting language="XML" role="XML">&lt;external-component-plugins&gt; &lt;target-component&gt;org.exoplatform.services.organization.OrganizationService&lt;/target-component&gt; &lt;component-plugin&gt; &lt;name&gt;portal.new.user.event.listener&lt;/name&gt; @@ -103,9 +98,9 @@ &lt;object-param&gt; &lt;name&gt;configuration&lt;/name&gt; &lt;description&gt;description&lt;/description&gt; - &lt;object type="org.exoplatform.services.portal.impl.NewPortalConfig"&gt; - &lt;field name="predefinedUser"&gt; - &lt;collection type="java.util.HashSet"&gt; + &lt;object type=&quot;org.exoplatform.services.portal.impl.NewPortalConfig&quot;&gt; + &lt;field name=&quot;predefinedUser&quot;&gt; + &lt;collection type=&quot;java.util.HashSet&quot;&gt; &lt;value&gt;&lt;string&gt;admin&lt;/string&gt;&lt;/value&gt; &lt;value&gt;&lt;string&gt;exo&lt;/string&gt;&lt;/value&gt; &lt;value&gt;&lt;string&gt;company&lt;/string&gt;&lt;/value&gt; @@ -114,248 +109,215 @@ &lt;value&gt;&lt;string&gt;exotest&lt;/string&gt;&lt;/value&gt; &lt;/collection&gt; &lt;/field&gt; - &lt;field name="templateUser"&gt;&lt;string&gt;template&lt;/string&gt;&lt;/field&gt; - &lt;field name="templateLocation"&gt;&lt;string&gt;war:/conf/users&lt;/string&gt;&lt;/field&gt; + &lt;field name=&quot;templateUser&quot;&gt;&lt;string&gt;template&lt;/string&gt;&lt;/field&gt; + &lt;field name=&quot;templateLocation&quot;&gt;&lt;string&gt;war:/conf/users&lt;/string&gt;&lt;/field&gt; &lt;/object&gt; &lt;/object-param&gt; &lt;/init-params&gt; &lt;/component-plugin&gt; ...</programlisting> - <para> + <para> In the previous XML configuration, we refer 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> + <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> + <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 id="sect-Reference_Guide-Components-RootContainer"> - <title>RootContainer</title> - <para> + <section id="sect-Reference_Guide-Components-RootContainer"> + <title>RootContainer</title> + <para> As PortalContainer depends on the RootContainer, we will start by looking into this one. </para> - <para> + <para> The retrieval sequence in short: </para> - <orderedlist> - <listitem> - <para> + <orderedlist> + <listitem> + <para> Services default <classname>RootContainer</classname> configurations from JAR files <emphasis>/conf/configuration.xml</emphasis> </para> - - </listitem> - <listitem> - <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> + </listitem> + </orderedlist> + <note> + <para> Naturally you always have to replace <parameter>exo-tomcat</parameter> by your own folder name. </para> - - </note> - <para> + </note> + <para> <emphasis role="bold">HashTable</emphasis> The <classname>RootContainer</classname> creates a java <classname>HashTable</classname> which contains key-value pairs for the services. The qualified interface name of each service is used as key for the hashtable. Hopefully you still remember that the <parameter>&lt;key&gt;</parameter> tag of the configuration file contains the interface name? The value of each hashtable pair is an object that contains the service configuration (yes, this means the whole structure between the <parameter>&lt;component&gt;</parameter> tags of your <filename>configuration.xml</filename> file). </para> - <para> + <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> + <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>. + </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&apos;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> + <para> The further configuration retrieval depends on the container type. </para> - - </section> - - <section id="sect-Reference_Guide-Components-PortalContainer"> - <title>PortalContainer</title> - <para> + </section> + <section id="sect-Reference_Guide-Components-PortalContainer"> + <title>PortalContainer</title> + <para> The PortalContainer takes the hashtable filled by the RootContainer and continues to look in some more places. Here you get the opportunity to replace RootContainer configurations by those which are specific to your portal. Again, the configurations are overridden whenever necessary. </para> - <para> + <para> In short PortalContainer configurations are retrieved in the following lookup sequence : </para> - <orderedlist> - <listitem> - <para> + <orderedlist> + <listitem> + <para> Take over the configurations of the RootContainer </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> Default PortalContainer configurations from all JAR files (folder <emphasis>/conf/portal/configuration.xml</emphasis>) </para> - - </listitem> - <listitem> - <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> + </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> + </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 JBoss Enterprise Portal Platform &VY; 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> + <emphasis role="bold">Multiple Portals</emphasis> Be aware that you might set up several different portals (&quot;admin&quot;, &quot;mexico&quot;, etc.), and each of these portals will use a different PortalContainer. And each of these PortalContainers can be configured separately. As of JBoss Enterprise Portal Platform &VY; 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 &quot;portal&quot; so you use <emphasis>exo-tomcat/exo-conf/portal/portal/configuration.xml</emphasis>. </para> - <note> - <para> + <note> + <para> As of JBoss Enterprise Portal Platform &VY; you can override the external configuration location with the system property <emphasis>exo.conf.dir</emphasis>. If the property exists its value will be used as path to the eXo configuration directory, that means this is an alternative to <emphasis>exo-tomcat/exo-conf</emphasis>. Just put this property in the command line: <emphasis>java -Dexo.conf.dir=/path/to/exo/conf</emphasis> or use eXo.bat or eXo.sh. In this particular use case, you have no need to use any prefixes in your configuration file to import other files. For example, if your configuration file is <emphasis>exo-tomcat/exo-conf/portal/PORTAL_NAME/configuration.xml</emphasis> and you want to import the configuration file <emphasis>exo-tomcat/exo-conf/portal/PORTAL_NAME/mySubConfDir/myConfig.xml</emphasis>, you can do it by adding <emphasis>&lt;import&gt;mySubConfDir/myConfig.xml&lt;/import&gt;</emphasis> to your configuration file. </para> - - </note> - <note> - <para> + </note> + <note> + <para> Under <emphasis role="bold">JBoss</emphasis> application server <emphasis>exo-conf</emphasis> will be looked up in directory described by JBoss System property <emphasis>jboss.server.config.url</emphasis>. If the property is not found or empty <emphasis>exo-jboss/exo-conf</emphasis> will be asked (since kernel 2.0.4). </para> - - </note> - - </section> - - <section id="sect-Reference_Guide-Components-External_Plug_ins"> - <title>External Plug-ins</title> - <para> - The eXo Kernel supports non-component objects that can be configured, instantiated, and injected into registered components using method calls. This '<emphasis>plugin</emphasis>' method allows portal extensions to add additional configurations to core services. + </note> + </section> + <section id="sect-Reference_Guide-Components-External_Plug_ins"> + <title>External Plug-ins</title> + <para> + The eXo Kernel supports non-component objects that can be configured, instantiated, and injected into registered components using method calls. This &apos;<emphasis>plugin</emphasis>&apos; method allows portal extensions to add additional configurations to core services. </para> - <para> - An external plugin is defined by using the <literal>&lt;external-component-plugin&gt;</literal> wrapper element which contains one or more <literal>&lt;component-plugin&gt;</literal> definitions. + <para> + An external plug-in is defined by using the <literal>&lt;external-component-plugin&gt;</literal> wrapper element which contains one or more <literal>&lt;component-plugin&gt;</literal> definitions. </para> - <para> + <para> The <literal>&lt;external-component-plugin&gt;</literal> element uses <literal>&lt;target-component&gt;</literal> to specify a target service component that will receive injected objects. </para> - <para> + <para> Every <literal>&lt;component-plugin&gt;</literal> defines an implementation type, and a method on the target component to use for injection (<literal>&lt;set-method&gt;</literal>). </para> - <para> - A plugin implementation class has to implement the <emphasis role="bold">org.exoplatform.container.component. ComponentPlugin</emphasis> interface. + <para> + A plug-in implementation class has to implement the <emphasis role="bold">org.exoplatform.container.component. ComponentPlugin</emphasis> interface. </para> - <para> + <para> In the following example the <literal>PortalContainerDefinitionPlugin</literal> implements the <literal>ComponentPlugin</literal>: </para> - -<programlisting language="XML" role="XML"><xi:include href="../../../extras/Advanced_Development_Foundations/default1.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <para> - The <emphasis role="bold">&lt;target-component&gt;</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">&lt;set-method&gt;</emphasis>. The method has exactly one argument of the type org.exoplatform.services.cms.categories.impl.TaxonomyPlugin: + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/Advanced_Development_Foundations/default1.xml" parse="text"/></programlisting> + <para> + The <emphasis role="bold">&lt;target-component&gt;</emphasis> defines the service for which the plug-in is defined. The configuration is injected by the container using a method that is defined in <emphasis role="bold">&lt;set-method&gt;</emphasis>. The method has exactly one argument of the type org.exoplatform.services.cms.categories.impl.TaxonomyPlugin: </para> - <itemizedlist> - <listitem> - <para> + <itemizedlist> + <listitem> + <para> addTaxonomyPlugin(org.exoplatform.services.cms.categories.impl.TaxonomyPlugin plugin) </para> - - </listitem> - - </itemizedlist> - <para> + </listitem> + </itemizedlist> + <para> The content of <emphasis role="bold">&lt;init-params&gt;</emphasis> corresponds to the structure of the TaxonomyPlugin object. </para> - <note> - <para> + <note> + <para> 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> - - </note> - - </section> - - <section id="sect-Reference_Guide-Components-Service_instantiation"> - <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. + </note> + </section> + <section id="sect-Reference_Guide-Components-Service_instantiation"> + <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&apos;s easy. </para> - <para> + <para> But now look at <ulink url="https://anonsvn.jboss.org/repos/exo-jcr/core/trunk/exo.core.com... </para> - <para> + <para> This JDBC implementation of BaseOrganizationService interface has only one constructor: </para> - -<programlisting language="Java" role="Java">public OrganizationServiceImpl(ListenerService listenerService, DatabaseService dbService);</programlisting> - <para> + <programlisting language="Java" role="Java">public OrganizationServiceImpl(ListenerService listenerService, DatabaseService dbService);</programlisting> + <para> You see this service depends on two other services. In order to be able to call this constructor the container first needs a <classname>ListenerService</classname> and a <classname>DatabaseService</classname>. Therefore these services must be instantiated before <classname>BaseOrganizationService</classname>, because <classname>BaseOrganizationService</classname> depends on them. </para> - <para> + <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> + <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 id="sect-Reference_Guide-Components-Service_Access"> - <title>Service Access</title> - <para> + </note> + </section> + <section id="sect-Reference_Guide-Components-Service_Access"> + <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> + <para> With this command you get your current container: </para> - <itemizedlist> - <listitem> - <para> + <itemizedlist> + <listitem> + <para> <emphasis role="bold">ExoContainer myContainer = ExoContainerContext.getCurrentContainer();</emphasis> </para> - - </listitem> - - </itemizedlist> - <para> + </listitem> + </itemizedlist> + <para> Whenever you need one of the services that you have configured use the method: </para> - <itemizedlist> - <listitem> - <para> + <itemizedlist> + <listitem> + <para> <emphasis role="bold">myContainer.getComponentInstance(class)</emphasis> </para> - - </listitem> - - </itemizedlist> - <para> + </listitem> + </itemizedlist> + <para> In our case: </para> - <itemizedlist> - <listitem> - <para> + <itemizedlist> + <listitem> + <para> <emphasis role="bold">ArticleStatsService statsService = (ArticleStatsService) myContainer.getComponentInstance(ArticleStatsService.class);</emphasis> </para> - - </listitem> - - </itemizedlist> - <para> + </listitem> + </itemizedlist> + <para> Recapitulation: </para> - -<programlisting language="Java" role="Java">package com.laverdad.common; + <programlisting language="Java" role="Java">package com.laverdad.common; import org.exoplatform.container.ExoContainer; import org.exoplatform.container.ExoContainerContext; @@ -373,175 +335,149 @@ 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)); + String newText = &quot;This is a normal text. The method only counts the number of periods. &quot; + + &quot;You can implement your own implementation with a more exact counting. &quot; + + &quot;Let`s make a last sentence.&quot;; + System.out.println(&quot;Number of sentences: &quot; + stats.makeStatistics(newText)); } }</programlisting> - - </section> - - <section id="sect-Reference_Guide-Components-Includes_and_special_URLs"> - <title>Includes, and special URLs</title> - <para> + </section> + <section id="sect-Reference_Guide-Components-Includes_and_special_URLs"> + <title>Includes, and special URLs</title> + <para> It is possible to divide the <filename>configuration.xml</filename> file into many smaller files, which are then included into the main configuration file. </para> - <para> + <para> The included files must be valid xml files; they cannot be fragments of text. </para> - <para> - Below is an example <filename>configuration.xml</filename> that 'outsources' its content into several files: + <para> + Below is an example <filename>configuration.xml</filename> that &apos;outsources&apos; its content into several files: </para> - <programlistingco> - <areaspec> - <area coords="6" id="area-Reference_Guide-Components-Includes_and_special_URLs-url_schema" /> - - </areaspec> - -<programlisting language="XML" role="XML"><xi:include href="../../../extras/Advanced_Development_Foundations/default2.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <calloutlist> - <callout arearefs="area-Reference_Guide-Components-Includes_and_special_URLs-url_schema"> - <para> - This line is being used to reference another configuration file. The <code>war:</code> URL schema indicates that the following path is to be resolved relative to the current <literal>PortalContainer</literal>'s servlet context resource path, starting with <emphasis role="bold">WEB-INF</emphasis> as a root. + <programlistingco> + <areaspec> + <area coords="6" id="area-Reference_Guide-Components-Includes_and_special_URLs-url_schema"/> + </areaspec> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/Advanced_Development_Foundations/default2.xml" parse="text"/></programlisting> + <calloutlist> + <callout arearefs="area-Reference_Guide-Components-Includes_and_special_URLs-url_schema"> + <para> + This line is being used to reference another configuration file. The <code>war:</code> URL schema indicates that the following path is to be resolved relative to the current <literal>PortalContainer</literal>&apos;s servlet context resource path, starting with <emphasis role="bold">WEB-INF</emphasis> as a root. </para> - - </callout> - - </calloutlist> - - </programlistingco> - - <note> - <para> + </callout> + </calloutlist> + </programlistingco> + <note> + <para> The current <literal>PortalContainer</literal> is really a newly created <literal>PortalContainer</literal>, as <code>war:</code> URLs only make sense for <literal>PortalContainer</literal> scoped configuration. </para> - - </note> - <para> + </note> + <para> Through the extension mechanism the servlet context used for resource loading is a <emphasis role="bold">unified servlet context</emphasis> (this is explained in a later section). </para> - <para> - To have an 'include' path resolved relative to current classpath (context classloader), use a <code>'jar:'</code> URL schema. + <para> + To have an &apos;include&apos; path resolved relative to current classpath (context classloader), use a <code>&apos;jar:&apos;</code> URL schema. </para> - - </section> - - <section id="sect-Reference_Guide-Components-Special_variables"> - <title>Special variables</title> - <para> + </section> + <section id="sect-Reference_Guide-Components-Special_variables"> + <title>Special variables</title> + <para> Configuration files may contain a <emphasis role="bold">special variable</emphasis> reference <emphasis>${container.name.suffix}</emphasis>. This variable resolves to the name of the current portal container, prefixed by underscore (_). </para> - <para> + <para> This facilitates reuse of configuration files in situations where portal-specific unique names need to be assigned to some resources; JNDI names, Database/DataSource names and JCR repository names, for example. </para> - <para> + <para> This variable is only defined when there is a current <literal>PortalContainer</literal> available and is only available for <literal>PortalContainer</literal> scoped services. </para> - <para> + <para> A good example of this is the <emphasis role="bold">HibernateService</emphasis>: </para> - -<programlisting language="XML" role="XML"><xi:include href="../../../extras/Advanced_Development_Foundations/default3.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - - </section> - - - </section> - - <section id="sect-Reference_Guide-Configuration_syntax-InitParams_configuration_element"> - <title>InitParams configuration element</title> - <para> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/Advanced_Development_Foundations/default3.xml" parse="text"/></programlisting> + </section> + </section> + <section id="sect-Reference_Guide-Configuration_syntax-InitParams_configuration_element"> + <title>InitParams configuration element</title> + <para> <parameter>InitParams</parameter> is a configuration element that is essentially a map of key-value pairs, where <emphasis role="bold">key</emphasis> is always a <literal>String</literal>, and <emphasis role="bold">value</emphasis> can be any type that can be described using the kernel XML configuration. </para> - <para> + <para> Service components that form the JBoss Enterprise Portal Platform infrastructure use <parameter>InitParams</parameter> elements to configure themselves. A component can have one instance of <parameter>InitParams</parameter> injected at most. </para> - <para> - If the service component's constructor takes <parameter>InitParams</parameter> as any of the parameters it will automatically be injected at component instantiation time. + <para> + If the service component&apos;s constructor takes <parameter>InitParams</parameter> as any of the parameters it will automatically be injected at component instantiation time. </para> - <para> + <para> The XML configuration for a service component that expects an <parameter>InitParams</parameter> element must have an <parameter>&lt;init-params&gt;</parameter> element present, however this element can be left empty. </para> - <para> + <para> Below is an example of how the kernel XML configuration syntax looks when creating <parameter>InitParams</parameter> instances: </para> - -<programlisting language="XML" role="XML"><xi:include href="../../../extras/Advanced_Development_Foundations/default4.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <para> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/Advanced_Development_Foundations/default4.xml" parse="text"/></programlisting> + <para> An <parameter>InitParams</parameter> element description begins with an <parameter>&lt;init-params&gt;</parameter> element. </para> - <para> + <para> It can have zero or more children elements, each of which is one of the following: </para> - <itemizedlist> - <listitem> - <para> + <itemizedlist> + <listitem> + <para> <parameter>&lt;value-param&gt;</parameter> </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> <parameter>&lt;values-param&gt;</parameter> </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> <parameter>&lt;properties-param&gt;</parameter> </para> - - </listitem> - - </itemizedlist> - <para> + </listitem> + </itemizedlist> + <para> or </para> - <itemizedlist> - <listitem> - <para> + <itemizedlist> + <listitem> + <para> <parameter>&lt;object-param&gt;</parameter> </para> - - </listitem> - - </itemizedlist> - <para> + </listitem> + </itemizedlist> + <para> Each of these child elements takes a <parameter>&lt;name&gt;</parameter> that serves as a map entry key, and an optional <parameter>&lt;description&gt;</parameter>. It also takes a type-specific <emphasis role="bold">value</emphasis> specification. </para> - <para> + <para> The value specification for the <parameter>&lt;properties-param&gt;</parameter> defines one or more <parameter>&lt;property&gt;</parameter> elements, each of which specifies two strings; a property name and a property value. This is evident in the two previous examples. </para> - <para> + <para> Each <parameter>&lt;properties-params&gt;</parameter> defines one <literal>java.util.Properties</literal> instance. </para> - <para> + <para> The value specification for <parameter>&lt;value-param&gt;</parameter> elements is a <parameter>&lt;value&gt;</parameter> element which defines a <literal>String</literal> instance. </para> - -<programlisting language="XML" role="XML"><xi:include href="../../../extras/Advanced_Development_Foundations/default5.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <para> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/Advanced_Development_Foundations/default5.xml" parse="text"/></programlisting> + <para> The value specification for <parameter>&lt;values-param&gt;</parameter> requires one or more <parameter>&lt;value&gt;</parameter> elements. Each <parameter>&lt;value&gt;</parameter> represents one <literal>String</literal> instance. All <literal>String</literal> values are then collected into a <literal>java.util.List</literal> instance. </para> - -<programlisting language="XML" role="XML"><xi:include href="../../../extras/Advanced_Development_Foundations/default6.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <para> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/Advanced_Development_Foundations/default6.xml" parse="text"/></programlisting> + <para> For <parameter>&lt;object-param&gt;</parameter> entries, the value specification consists of an <parameter>&lt;object&gt;</parameter> element which is used for plain Java style object specification (specifying an implementation <emphasis>class - <parameter>&lt;type&gt;</parameter></emphasis>, and <emphasis>property values - <parameter>&lt;field&gt;</parameter></emphasis>). </para> - <para> + <para> The following section has an example of specifying a field of with a <literal>Collection</literal> type. </para> - <para> - The <parameter>InitParams</parameter> structure (the names and types of entries) is specific for each service, as it is the code inside a service components' class that defines which entry names to look up and what types it expects to find. + <para> + The <parameter>InitParams</parameter> structure (the names and types of entries) is specific for each service, as it is the code inside a service components&apos; class that defines which entry names to look up and what types it expects to find. </para> - <section id="sect-Reference_Guide-InitParams_configuration_element-Value_Param"> - <title>Value-Param</title> - <para> + <section id="sect-Reference_Guide-InitParams_configuration_element-Value_Param"> + <title>Value-Param</title> + <para> There is an value-param example: </para> - -<programlisting language="XML" role="XML"> &lt;component&gt; + <programlisting language="XML" role="XML"> &lt;component&gt; &lt;key&gt;org.exoplatform.portal.config.UserACL&lt;/key&gt; &lt;type&gt;org.exoplatform.portal.config.UserACL&lt;/type&gt; &lt;init-params&gt; @@ -553,148 +489,133 @@ &lt;/value-param&gt; ... &lt;/component&gt;</programlisting> - <para> + <para> The UserACL class accesses to the <emphasis role="bold">value-param</emphasis> in its constructor. </para> - -<programlisting language="Java" role="Java">package org.exoplatform.portal.config; + <programlisting language="Java" role="Java">package org.exoplatform.portal.config; public class UserACL { public UserACL(InitParams params) { UserACLMetaData md = new UserACLMetaData(); - ValueParam accessControlWorkspaceParam = params.getValueParam("access.control.workspace"); + ValueParam accessControlWorkspaceParam = params.getValueParam(&quot;access.control.workspace&quot;); if(accessControlWorkspaceParam != null) md.setAccessControlWorkspace(accessControlWorkspaceParam.getValue()); ...</programlisting> - - </section> - - <section id="sect-Reference_Guide-InitParams_configuration_element-Properties_Param"> - <title>Properties-Param</title> - <para> + </section> + <section id="sect-Reference_Guide-InitParams_configuration_element-Properties_Param"> + <title>Properties-Param</title> + <para> Properties are name-value pairs. Both the name and the value are Java Strings. </para> - <para> + <para> Here you see the hibernate configuration example: </para> - -<programlisting language="XML" role="XML"> &lt;component&gt; + <programlisting language="XML" role="XML"> &lt;component&gt; &lt;key&gt;org.exoplatform.services.database.HibernateService&lt;/key&gt; &lt;type&gt;org.exoplatform.services.database.impl.HibernateServiceImpl&lt;/type&gt; &lt;init-params&gt; &lt;properties-param&gt; &lt;name&gt;hibernate.properties&lt;/name&gt; &lt;description&gt;Default Hibernate Service&lt;/description&gt; - &lt;property name="hibernate.show_sql" value="false"/&gt; - &lt;property name="hibernate.cglib.use_reflection_optimizer" value="true"/&gt; - &lt;property name="hibernate.connection.url" value="jdbc:hsqldb:file:../temp/data/exodb"/&gt; - &lt;property name="hibernate.connection.driver_class" value="org.hsqldb.jdbcDriver"/&gt; + &lt;property name=&quot;hibernate.show_sql&quot; value=&quot;false&quot;/&gt; + &lt;property name=&quot;hibernate.cglib.use_reflection_optimizer&quot; value=&quot;true&quot;/&gt; + &lt;property name=&quot;hibernate.connection.url&quot; value=&quot;jdbc:hsqldb:file:../temp/data/exodb&quot;/&gt; + &lt;property name=&quot;hibernate.connection.driver_class&quot; value=&quot;org.hsqldb.jdbcDriver&quot;/&gt; ... &lt;/properties-param&gt; &lt;/init-params&gt; &lt;/component&gt;</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> + In the org.exoplatform.services.database.impl.HibernateServiceImpl you will find that the name &quot;hibernate.properties&quot; of the properties-param is used to access the properties. </para> - -<programlisting language="Java" role="Java">package org.exoplatform.services.database.impl; + <programlisting language="Java" role="Java">package org.exoplatform.services.database.impl; public class HibernateServiceImpl implements HibernateService, ComponentRequestLifecycle { public HibernateServiceImpl(InitParams initParams, CacheService cacheService) { - PropertiesParam param = initParams.getPropertiesParam("hibernate.properties"); + PropertiesParam param = initParams.getPropertiesParam(&quot;hibernate.properties&quot;); ... }</programlisting> - - </section> - - <section id="sect-Reference_Guide-InitParams_configuration_element-Object_Param"> - <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. + </section> + <section id="sect-Reference_Guide-InitParams_configuration_element-Object_Param"> + <title>Object-Param</title> + <para> + Let&apos;s have a look at the configuration of the LDAPService. It&apos;s not important to know LDAP, we only discuss the parameters. </para> - -<programlisting language="XML" role="XML">&lt;component&gt; + <programlisting language="XML" role="XML">&lt;component&gt; &lt;key&gt;org.exoplatform.services.LDAP.LDAPService&lt;/key&gt; &lt;type&gt;org.exoplatform.services.LDAP.impl.LDAPServiceImpl&lt;/type&gt; &lt;init-params&gt; &lt;object-param&gt; &lt;name&gt;LDAP.config&lt;/name&gt; &lt;description&gt;Default LDAP config&lt;/description&gt; - &lt;object type="org.exoplatform.services.LDAP.impl.LDAPConnectionConfig"&gt; - &lt;field name="providerURL"&gt;&lt;string&gt;LDAPs://10.0.0.3:636&lt;/string&gt;&lt;/field&gt; - &lt;field name="rootdn"&gt;&lt;string&gt;CN=Administrator,CN=Users,DC=exoplatform,DC=org&lt;/string&gt;&lt;/field&gt; - &lt;field name="password"&gt;&lt;string&gt;exo&lt;/string&gt;&lt;/field&gt; - &lt;field name="version"&gt;&lt;string&gt;3&lt;/string&gt;&lt;/field&gt; - &lt;field name="minConnection"&gt;&lt;int&gt;5&lt;/int&gt;&lt;/field&gt; - &lt;field name="maxConnection"&gt;&lt;int&gt;10&lt;/int&gt;&lt;/field&gt; - &lt;field name="referralMode"&gt;&lt;string&gt;ignore&lt;/string&gt;&lt;/field&gt; - &lt;field name="serverName"&gt;&lt;string&gt;active.directory&lt;/string&gt;&lt;/field&gt; + &lt;object type=&quot;org.exoplatform.services.LDAP.impl.LDAPConnectionConfig&quot;&gt; + &lt;field name=&quot;providerURL&quot;&gt;&lt;string&gt;LDAPs://10.0.0.3:636&lt;/string&gt;&lt;/field&gt; + &lt;field name=&quot;rootdn&quot;&gt;&lt;string&gt;CN=Administrator,CN=Users,DC=exoplatform,DC=org&lt;/string&gt;&lt;/field&gt; + &lt;field name=&quot;password&quot;&gt;&lt;string&gt;exo&lt;/string&gt;&lt;/field&gt; + &lt;field name=&quot;version&quot;&gt;&lt;string&gt;3&lt;/string&gt;&lt;/field&gt; + &lt;field name=&quot;minConnection&quot;&gt;&lt;int&gt;5&lt;/int&gt;&lt;/field&gt; + &lt;field name=&quot;maxConnection&quot;&gt;&lt;int&gt;10&lt;/int&gt;&lt;/field&gt; + &lt;field name=&quot;referralMode&quot;&gt;&lt;string&gt;ignore&lt;/string&gt;&lt;/field&gt; + &lt;field name=&quot;serverName&quot;&gt;&lt;string&gt;active.directory&lt;/string&gt;&lt;/field&gt; &lt;/object&gt; &lt;/object-param&gt; &lt;/init-params&gt; &lt;/component&gt;</programlisting> - <para> + <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> + <para> Here you see how the service accesses the object: </para> - -<programlisting language="Java" role="Java">package org.exoplatform.services.LDAP.impl; + <programlisting language="Java" role="Java">package org.exoplatform.services.LDAP.impl; public class LDAPServiceImpl implements LDAPService { ... public LDAPServiceImpl(InitParams params) { - LDAPConnectionConfig config = (LDAPConnectionConfig) params.getObjectParam("LDAP.config") + LDAPConnectionConfig config = (LDAPConnectionConfig) params.getObjectParam(&quot;LDAP.config&quot;) .getObject(); ...</programlisting> - <para> + <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 language="Java" role="Java">package org.exoplatform.services.LDAP.impl; + <programlisting language="Java" role="Java">package org.exoplatform.services.LDAP.impl; public class LDAPConnectionConfig { - private String providerURL = "LDAP://127.0.0.1:389"; + private String providerURL = &quot;LDAP://127.0.0.1:389&quot;; private String rootdn; private String password; private String version; - private String authenticationType = "simple"; - private String serverName = "default"; + private String authenticationType = &quot;simple&quot;; + private String serverName = &quot;default&quot;; private int minConnection; private int maxConnection; - private String referralMode = "follow"; + private String referralMode = &quot;follow&quot;; ...</programlisting> - <para> + <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_2.xsd file let us discover more simple types: </para> - <itemizedlist> - <listitem> - <para> + <itemizedlist> + <listitem> + <para> <emphasis role="bold">string, int, long, boolean, date, double</emphasis> </para> - - </listitem> - - </itemizedlist> - <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...;. </para> - - </section> - - <section id="sect-Reference_Guide-InitParams_configuration_element-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 will see that object-param is used again. + </section> + <section id="sect-Reference_Guide-InitParams_configuration_element-Collection"> + <title>Collection</title> + <para> + You also can use java collections to configure your service. In order to see an example, let&apos;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 will see that object-param is used again. </para> - <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> + <para> The second collection is a <emphasis role="bold">HashSet</emphasis> that is a set of strings. </para> - -<programlisting language="XML" role="XML"> &lt;component-plugin&gt; + <programlisting language="XML" role="XML"> &lt;component-plugin&gt; &lt;name&gt;new.user.event.listener&lt;/name&gt; &lt;set-method&gt;addListenerPlugin&lt;/set-method&gt; &lt;type&gt;org.exoplatform.services.organization.impl.NewUserEventListener&lt;/type&gt; @@ -703,19 +624,19 @@ &lt;object-param&gt; &lt;name&gt;configuration&lt;/name&gt; &lt;description&gt;description&lt;/description&gt; - &lt;object type="org.exoplatform.services.organization.impl.NewUserConfig"&gt; - &lt;field name="group"&gt; - &lt;collection type="java.util.ArrayList"&gt; + &lt;object type=&quot;org.exoplatform.services.organization.impl.NewUserConfig&quot;&gt; + &lt;field name=&quot;group&quot;&gt; + &lt;collection type=&quot;java.util.ArrayList&quot;&gt; &lt;value&gt; - &lt;object type="org.exoplatform.services.organization.impl.NewUserConfig$JoinGroup"&gt; - &lt;field name="groupId"&gt;&lt;string&gt;/platform/users&lt;/string&gt;&lt;/field&gt; - &lt;field name="membership"&gt;&lt;string&gt;member&lt;/string&gt;&lt;/field&gt; + &lt;object type=&quot;org.exoplatform.services.organization.impl.NewUserConfig$JoinGroup&quot;&gt; + &lt;field name=&quot;groupId&quot;&gt;&lt;string&gt;/platform/users&lt;/string&gt;&lt;/field&gt; + &lt;field name=&quot;membership&quot;&gt;&lt;string&gt;member&lt;/string&gt;&lt;/field&gt; &lt;/object&gt; &lt;/value&gt; &lt;/collection&gt; &lt;/field&gt; - &lt;field name="ignoredUser"&gt; - &lt;collection type="java.util.HashSet"&gt; + &lt;field name=&quot;ignoredUser&quot;&gt; + &lt;collection type=&quot;java.util.HashSet&quot;&gt; &lt;value&gt;&lt;string&gt;root&lt;/string&gt;&lt;/value&gt; &lt;value&gt;&lt;string&gt;john&lt;/string&gt;&lt;/value&gt; &lt;value&gt;&lt;string&gt;marry&lt;/string&gt;&lt;/value&gt; @@ -727,11 +648,10 @@ &lt;/object-param&gt; &lt;/init-params&gt; &lt;/component-plugin&gt;</programlisting> - <para> - Let's look at the org.exoplatform.services.organization.impl.NewUserConfig bean: + <para> + Let&apos;s look at the org.exoplatform.services.organization.impl.NewUserConfig bean: </para> - -<programlisting language="Java" role="Java">public class NewUserConfig { + <programlisting language="Java" role="Java">public class NewUserConfig { private List role; private List group; private HashSet ignoredUser; @@ -748,28 +668,23 @@ 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> + You see the values of the HashSet are set one by one by the container, and it&apos;s the responsibility of the bean to add these values to its HashSet. </para> - <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="sect-Reference_Guide-Configuration_syntax-Component_Plugin_Priority"> - <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>. + </section> + </section> + <section id="sect-Reference_Guide-Configuration_syntax-Component_Plugin_Priority"> + <title>Component Plug-in Priority</title> + <para> + Since kernel version 2.0.6 it is possible to setup order of loading for ComponentPlugin. Use the &apos; <emphasis role="bold">priority</emphasis>&apos; tag to define plug-in&apos;s load priority. By <emphasis role="bold">default</emphasis> all plug-ins get <emphasis role="bold">priority &apos;0&apos;</emphasis>; they will be loaded in the container&apos;s natural way. If you want one plug-in to be loaded later than the others then just set priority for it <emphasis role="bold">higher than zero</emphasis>. </para> - <para> + <para> Simple example of fragment of a <emphasis role="bold">configuration.xml</emphasis>. </para> - -<programlisting language="XML" role="XML">... + <programlisting language="XML" role="XML">... &lt;component&gt; &lt;type&gt;org.exoplatform.services.Component1&lt;/type&gt; &lt;/component&gt; @@ -805,88 +720,73 @@ &lt;/component-plugin&gt; &lt;/external-component-plugins&gt; ...</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 last one is plugin 'Plugin2'. + <para> + In the above example plug-in &apos;Plugin3&apos; will be loaded first because it has the default priority &apos;0&apos;. Then, plug-in &apos;Plugin1&apos; will be loaded and last one is plug-in &apos;Plugin2&apos;. </para> - - </section> - - <section id="sect-Reference_Guide-Configuration_syntax-Configuration_Logging"> - <title>Configuration Logging</title> - <para> + </section> + <section id="sect-Reference_Guide-Configuration_syntax-Configuration_Logging"> + <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> + <programlisting>set EXO_CONFIG_OPTS=&quot;-Dorg.exoplatform.container.configuration.debug&quot;</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>...... + <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 id="sect-Reference_Guide-Configuration_syntax-Import"> - <title>Import</title> - <para> + </section> + <section id="sect-Reference_Guide-Configuration_syntax-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> + <itemizedlist> + <listitem> + <para> <emphasis role="bold">war</emphasis>: Imports from <emphasis role="bold">portal.war/WEB-INF</emphasis> </para> - - </listitem> - <listitem> - <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> + </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> + </listitem> + <listitem> + <para> <emphasis role="bold">without any prefix</emphasis>: </para> - - </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: + </listitem> + </itemizedlist> + <para> + If you open the &quot;portal/trunk/web/portal/src/main/webapp/WEB-INF/conf.configuration.xml&quot; you will see that it consists only of imports: </para> - -<programlisting language="XML" role="XML">&lt;import&gt;war:/conf/common/common-configuration.xml&lt;/import&gt; + <programlisting language="XML" role="XML">&lt;import&gt;war:/conf/common/common-configuration.xml&lt;/import&gt; &lt;import&gt;war:/conf/common/logs-configuration.xml&lt;/import&gt; &lt;import&gt;war:/conf/database/database-configuration.xml&lt;/import&gt; &lt;import&gt;war:/conf/jcr/jcr-configuration.xml&lt;/import&gt; &lt;import&gt;war:/conf/common/portlet-container-configuration.xml&lt;/import&gt; ...</programlisting> - - </section> - - <section id="sect-Reference_Guide-Configuration_syntax-System_properties"> - <title>System properties</title> - <para> + </section> + <section id="sect-Reference_Guide-Configuration_syntax-System_properties"> + <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> + <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 language="XML" role="XML"> &lt;component&gt; + <programlisting language="XML" role="XML"> &lt;component&gt; &lt;key&gt;org.exoplatform.services.database.HibernateService&lt;/key&gt; &lt;jmx-name&gt;database:type=HibernateService&lt;/jmx-name&gt; &lt;type&gt;org.exoplatform.services.database.impl.HibernateServiceImpl&lt;/type&gt; @@ -895,24 +795,18 @@ &lt;name&gt;hibernate.properties&lt;/name&gt; &lt;description&gt;Default Hibernate Service&lt;/description&gt; ... - &lt;property name="hibernate.connection.url" value="${connectionUrl}"/&gt; - &lt;property name="hibernate.connection.driver_class" value="${driverClass}"/&gt; - &lt;property name="hibernate.connection.username" value="${username}"/&gt; - &lt;property name="hibernate.connection.password" value="${password}"/&gt; - &lt;property name="hibernate.dialect" value="${dialect}"/&gt; + &lt;property name=&quot;hibernate.connection.url&quot; value=&quot;${connectionUrl}&quot;/&gt; + &lt;property name=&quot;hibernate.connection.driver_class&quot; value=&quot;${driverClass}&quot;/&gt; + &lt;property name=&quot;hibernate.connection.username&quot; value=&quot;${username}&quot;/&gt; + &lt;property name=&quot;hibernate.connection.password&quot; value=&quot;${password}&quot;/&gt; + &lt;property name=&quot;hibernate.dialect&quot; value=&quot;${dialect}&quot;/&gt; ... &lt;/properties-param&gt; &lt;/init-params&gt; &lt;/component&gt;</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 JBoss Enterprise Portal Platform: <emphasis role="bold">set EXO_OPTS="-DconnectionUrl=jdbc:hsqldb:file:../temp/data/exodb -DdriverClass=org.hsqldb.jdbcDriver"</emphasis> + <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 JBoss Enterprise Portal Platform: <emphasis role="bold">set EXO_OPTS=&quot;-DconnectionUrl=jdbc:hsqldb:file:../temp/data/exodb -DdriverClass=org.hsqldb.jdbcDriver&quot;</emphasis> </para> - </section> - - </section> - - + </section> </section> - - Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/Advanced/Foundations/Profiles.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/Advanced/Foundations/Profiles.xml 2012-07-05 19:41:59 UTC (rev 8774) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/Advanced/Foundations/Profiles.xml 2012-07-06 05:00:36 UTC (rev 8775) @@ -1,99 +1,85 @@ -<?xml version='1.0' encoding='utf-8' ?> +<?xml version='1.0' encoding='UTF-8'?> <!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!ENTITY % BOOK_ENTITIES SYSTEM "Reference_Guide.ent"> %BOOK_ENTITIES; ]> <section id="sect-Reference_Guide-Runtime_configuration_profiles"> - <title>Runtime configuration profiles</title> - <para> - The kernel configuration is able to handle configuration profiles at runtime (as opposed to packaging time). - </para> - <section id="sect-Reference_Guide-Runtime_configuration_profiles-Profiles_activation"> - <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 + <title>Runtime configuration profiles</title> + <para> + The kernel configuration is able to handle configuration profiles at runtime (as opposed to packaging time). + </para> + <section id="sect-Reference_Guide-Runtime_configuration_profiles-Profiles_activation"> + <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 &quot;,&quot; delimiter and also a server specific profile value (tomcat for tomcat, jboss for jboss, etc...). + </para> + <programlisting># runs GateIn on Tomcat with the profiles tomcat and foo sh gatein.sh -Dexo.profiles=foo # runs GateIn on JBoss with the profiles jboss, foo and bar sh run.sh -Dexo.profiles=foo,bar</programlisting> - - </section> - - <section id="sect-Reference_Guide-Runtime_configuration_profiles-Profiles_configuration"> - <title>Profiles configuration</title> - <para> - Profiles are configured in the configuration files of the eXo kernel. - </para> - <section id="sect-Reference_Guide-Profiles_configuration-Profiles_definition"> - <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_2.xsd. The configuration is based on the following rules: - </para> - <orderedlist> - <listitem> - <para> - Any kernel element with the no <emphasis>profiles</emphasis> attribute will create a configuration object - </para> - - </listitem> - <listitem> - <para> - Any kernel element having a <emphasis>profiles</emphasis> attribute containing at least one of the active profiles will create a configuration object - </para> - - </listitem> - <listitem> - <para> - Any kernel element having a <emphasis>profiles</emphasis> attribute matching none of the active profile will not create a configuration object - </para> - - </listitem> - <listitem> - <para> - Resolution of duplicates (such as two components with same type) is left up to the kernel - </para> - - </listitem> - - </orderedlist> - - </section> - - <section id="sect-Reference_Guide-Profiles_configuration-Profiles_capable_configuration_elements"> - <title>Profiles capable configuration elements</title> - <para> - A configuration element is <emphasis>profiles</emphasis> capable when it carries a profiles element. - </para> - <section id="sect-Reference_Guide-Profiles_capable_configuration_elements-Component_element"> - <title>Component element</title> - <para> - The component element declares a component when activated. It will shadow any element with the same key declared before in the same configuration file: - </para> - -<programlisting language="XML" role="XML">&lt;component&gt; + </section> + <section id="sect-Reference_Guide-Runtime_configuration_profiles-Profiles_configuration"> + <title>Profiles configuration</title> + <para> + Profiles are configured in the configuration files of the eXo kernel. + </para> + <section id="sect-Reference_Guide-Profiles_configuration-Profiles_definition"> + <title>Profiles definition</title> + <para> + Profile activation occurs at XML to configuration object unmarshalling time. It is based on an &quot;profile&quot; 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_2.xsd. The configuration is based on the following rules: + </para> + <orderedlist> + <listitem> + <para> + Any kernel element with the no <emphasis>profiles</emphasis> attribute will create a configuration object + </para> + </listitem> + <listitem> + <para> + Any kernel element having a <emphasis>profiles</emphasis> attribute containing at least one of the active profiles will create a configuration object + </para> + </listitem> + <listitem> + <para> + Any kernel element having a <emphasis>profiles</emphasis> attribute matching none of the active profile will not create a configuration object + </para> + </listitem> + <listitem> + <para> + Resolution of duplicates (such as two components with same type) is left up to the kernel + </para> + </listitem> + </orderedlist> + </section> + <section id="sect-Reference_Guide-Profiles_configuration-Profiles_capable_configuration_elements"> + <title>Profiles capable configuration elements</title> + <para> + A configuration element is <emphasis>profiles</emphasis> capable when it carries a profiles element. + </para> + <section id="sect-Reference_Guide-Profiles_capable_configuration_elements-Component_element"> + <title>Component element</title> + <para> + The component element declares a component when activated. It will shadow any element with the same key declared before in the same configuration file: + </para> + <programlisting language="XML" role="XML">&lt;component&gt; &lt;key&gt;Component&lt;/key&gt; &lt;type&gt;Component&lt;/type&gt; &lt;/component&gt; -&lt;component profiles="foo"&gt; +&lt;component profiles=&quot;foo&quot;&gt; &lt;key&gt;Component&lt;/key&gt; &lt;type&gt;FooComponent&lt;/type&gt; &lt;/component&gt;</programlisting> - - </section> - - <section id="sect-Reference_Guide-Profiles_capable_configuration_elements-Component_plugin_element"> - <title>Component plugin element</title> - <para> - The component-plugin element is used to dynamically extend the configuration of a given component. Thanks to the profiles the component-plugins could be enabled or disabled: - </para> - -<programlisting language="XML" role="XML">&lt;external-component-plugins&gt; + </section> + <section id="sect-Reference_Guide-Profiles_capable_configuration_elements-Component_plugin_element"> + <title>Component plug-in element</title> + <para> + The component-plugin element is used to dynamically extend the configuration of a given component. Thanks to the profiles the component-plugins could be enabled or disabled: + </para> + <programlisting language="XML" role="XML">&lt;external-component-plugins&gt; &lt;target-component&gt;Component&lt;/target-component&gt; - &lt;component-plugin profiles="foo"&gt; + &lt;component-plugin profiles=&quot;foo&quot;&gt; &lt;name&gt;foo&lt;/name&gt; &lt;set-method&gt;addPlugin&lt;/set-method&gt; &lt;type&gt;type&lt;/type&gt; @@ -105,28 +91,22 @@ &lt;/init-params&gt; &lt;/component-plugin&gt; &lt;/external-component-plugins&gt;</programlisting> - - </section> - - <section id="sect-Reference_Guide-Profiles_capable_configuration_elements-Import_element"> - <title>Import element</title> - <para> - The import element imports a referenced configuration file when activated: - </para> - -<programlisting language="XML" role="XML">&lt;import&gt;empty&lt;/import&gt; -&lt;import profiles="foo"&gt;foo&lt;/import&gt; -&lt;import profiles="bar"&gt;bar&lt;/import&gt;</programlisting> - - </section> - - <section id="sect-Reference_Guide-Profiles_capable_configuration_elements-Init_param_element"> - <title>Init param element</title> - <para> - The init param element configures the parameter argument of the construction of a component service: - </para> - -<programlisting language="XML" role="XML">&lt;component&gt; + </section> + <section id="sect-Reference_Guide-Profiles_capable_configuration_elements-Import_element"> + <title>Import element</title> + <para> + The import element imports a referenced configuration file when activated: + </para> + <programlisting language="XML" role="XML">&lt;import&gt;empty&lt;/import&gt; +&lt;import profiles=&quot;foo&quot;&gt;foo&lt;/import&gt; +&lt;import profiles=&quot;bar&quot;&gt;bar&lt;/import&gt;</programlisting> + </section> + <section id="sect-Reference_Guide-Profiles_capable_configuration_elements-Init_param_element"> + <title>Init param element</title> + <para> + The init param element configures the parameter argument of the construction of a component service: + </para> + <programlisting language="XML" role="XML">&lt;component&gt; &lt;key&gt;Component&lt;/key&gt; &lt;type&gt;ComponentImpl&lt;/type&gt; &lt;init-params&gt; @@ -134,73 +114,58 @@ &lt;name&gt;param&lt;/name&gt; &lt;value&gt;empty&lt;/value&gt; &lt;/value-param&gt; - &lt;value-param profiles="foo"&gt; + &lt;value-param profiles=&quot;foo&quot;&gt; &lt;name&gt;param&lt;/name&gt; &lt;value&gt;foo&lt;/value&gt; &lt;/value-param&gt; - &lt;value-param profiles="bar"&gt; + &lt;value-param profiles=&quot;bar&quot;&gt; &lt;name&gt;param&lt;/name&gt; &lt;value&gt;bar&lt;/value&gt; &lt;/value-param&gt; &lt;/init-params&gt; &lt;/component&gt;</programlisting> - - </section> - - <section id="sect-Reference_Guide-Profiles_capable_configuration_elements-Value_collection_element"> - <title>Value collection element</title> - <para> - The value collection element configures one of the value of collection data: - </para> - -<programlisting language="XML" role="XML">&lt;object type="org.exoplatform.container.configuration.ConfigParam"&gt; - &lt;field name="role"&gt; - &lt;collection type="java.util.ArrayList"&gt; + </section> + <section id="sect-Reference_Guide-Profiles_capable_configuration_elements-Value_collection_element"> + <title>Value collection element</title> + <para> + The value collection element configures one of the value of collection data: + </para> + <programlisting language="XML" role="XML">&lt;object type=&quot;org.exoplatform.container.configuration.ConfigParam&quot;&gt; + &lt;field name=&quot;role&quot;&gt; + &lt;collection type=&quot;java.util.ArrayList&quot;&gt; &lt;value&gt;&lt;string&gt;manager&lt;/string&gt;&lt;/value&gt; - &lt;value profiles="foo"&gt;&lt;string&gt;foo_manager&lt;/string&gt;&lt;/value&gt; - &lt;value profiles="foo,bar"&gt;&lt;string&gt;foo_bar_manager&lt;/string&gt;&lt;/value&gt; + &lt;value profiles=&quot;foo&quot;&gt;&lt;string&gt;foo_manager&lt;/string&gt;&lt;/value&gt; + &lt;value profiles=&quot;foo,bar&quot;&gt;&lt;string&gt;foo_bar_manager&lt;/string&gt;&lt;/value&gt; &lt;/collection&gt; &lt;/field&gt; &lt;/object&gt;</programlisting> - - </section> - - <section id="sect-Reference_Guide-Profiles_capable_configuration_elements-Field_configuration_element"> - <title>Field configuration element</title> - <para> - The field configuration element configures the field of an object: - </para> - -<programlisting language="XML" role="XML">&lt;object-param&gt; + </section> + <section id="sect-Reference_Guide-Profiles_capable_configuration_elements-Field_configuration_element"> + <title>Field configuration element</title> + <para> + The field configuration element configures the field of an object: + </para> + <programlisting language="XML" role="XML">&lt;object-param&gt; &lt;name&gt;test.configuration&lt;/name&gt; - &lt;object type="org.exoplatform.container.configuration.ConfigParam"&gt; - &lt;field name="role"&gt; - &lt;collection type="java.util.ArrayList"&gt; + &lt;object type=&quot;org.exoplatform.container.configuration.ConfigParam&quot;&gt; + &lt;field name=&quot;role&quot;&gt; + &lt;collection type=&quot;java.util.ArrayList&quot;&gt; &lt;value&gt;&lt;string&gt;manager&lt;/string&gt;&lt;/value&gt; &lt;/collection&gt; &lt;/field&gt; - &lt;field name="role" profiles="foo,bar"&gt; - &lt;collection type="java.util.ArrayList"&gt; + &lt;field name=&quot;role&quot; profiles=&quot;foo,bar&quot;&gt; + &lt;collection type=&quot;java.util.ArrayList&quot;&gt; &lt;value&gt;&lt;string&gt;foo_bar_manager&lt;/string&gt;&lt;/value&gt; &lt;/collection&gt; &lt;/field&gt; - &lt;field name="role" profiles="foo"&gt; - &lt;collection type="java.util.ArrayList"&gt; + &lt;field name=&quot;role&quot; profiles=&quot;foo&quot;&gt; + &lt;collection type=&quot;java.util.ArrayList&quot;&gt; &lt;value&gt;&lt;string&gt;foo_manager&lt;/string&gt;&lt;/value&gt; &lt;/collection&gt; &lt;/field&gt; &lt;/object&gt; &lt;/object-param&gt;</programlisting> - - </section> - - - </section> - - - </section> - - + </section> + </section> + </section> </section> - - Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/Advanced/Foundations/Specific_Services.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/Advanced/Foundations/Specific_Services.xml 2012-07-05 19:41:59 UTC (rev 8774) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/Advanced/Foundations/Specific_Services.xml 2012-07-06 05:00:36 UTC (rev 8775) @@ -1,34 +1,32 @@ -<?xml version='1.0' encoding='utf-8' ?> +<?xml version='1.0' encoding='UTF-8'?> <!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!ENTITY % BOOK_ENTITIES SYSTEM "Reference_Guide.ent"> %BOOK_ENTITIES; ]> <section id="sect-Reference_Guide-Specific_Services"> - <title>Specific Services</title> - <section id="sect-Reference_Guide-Specific_Services-ListenerService"> - <title>ListenerService</title> - <section id="sect-Reference_Guide-ListenerService-Asynchronous_Event_Broadcast"> - <title>Asynchronous Event Broadcast</title> - <para> - Basically, ListenerService used to store Listeners and broadcast events to them. - </para> - <para> - ListenerService event broadcasting works in next way - it takes a destination listeners and executes event on those listeners. - </para> - <para> - But, some events may take a lot of time, so idea to make event processing asynchronous is useful. - </para> - <blockquote> - <para> - What do I need to make my listener asynchronous? - </para> - - </blockquote> - <para> - - It's very simple, just mark your Listener implementation as <classname>@Asynchronous</classname>. - </para> - -<programlisting language="Java" role="Java">@Asynchronous + <title>Specific Services</title> + <section id="sect-Reference_Guide-Specific_Services-ListenerService"> + <title>ListenerService</title> + <section id="sect-Reference_Guide-ListenerService-Asynchronous_Event_Broadcast"> + <title>Asynchronous Event Broadcast</title> + <para> + Basically, ListenerService used to store Listeners and broadcast events to them. + </para> + <para> + ListenerService event broadcasting works in next way - it takes a destination listeners and executes event on those listeners. + </para> + <para> + But, some events may take a lot of time, so idea to make event processing asynchronous is useful. + </para> + <blockquote> + <para> + What do I need to make my listener asynchronous? + </para> + </blockquote> + <para> + - It&apos;s very simple, just mark your Listener implementation as <classname>@Asynchronous</classname>. + </para> + <programlisting language="Java" role="Java">@Asynchronous class AsynchListenerWithException&lt;S,D&gt; extends Listener&lt;S,D&gt; { @Override @@ -37,14 +35,13 @@ // some expensive operation } }</programlisting> - <para> - Now, our AsynchListener will be executed in separate thread by <classname>ExecutorService</classname>. - </para> - <para> - By default, <classname>ExecutoreService</classname> configured with thread pool size 1, you can change it in configuration: - </para> - -<programlisting language="XML" role="XML"> &lt;component&gt; + <para> + Now, our AsynchListener will be executed in separate thread by <classname>ExecutorService</classname>. + </para> + <para> + By default, <classname>ExecutoreService</classname> configured with thread pool size 1, you can change it in configuration: + </para> + <programlisting language="XML" role="XML"> &lt;component&gt; &lt;key&gt;org.exoplatform.services.listener.ListenerService&lt;/key&gt; &lt;type&gt;org.exoplatform.services.listener.ListenerService&lt;/type&gt; @@ -56,45 +53,36 @@ &lt;/init-params&gt; &lt;/component&gt;</programlisting> - - </section> - - - </section> - - <section id="sect-Reference_Guide-Specific_Services-Understanding_the_ListenerService"> - <title>Understanding the ListenerService</title> - <section id="sect-Reference_Guide-Understanding_the_ListenerService-Objectives"> - <title>Objectives</title> - <para> - This article will first describe how the ListenerService works and then it will show you how to configure the ListenerService. - </para> - - </section> - - <section id="sect-Reference_Guide-Understanding_the_ListenerService-What_is_the_ListenerService_"> - <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 id="sect-Reference_Guide-Understanding_the_ListenerService-How_does_it_work"> - <title>How does it work?</title> - <para> - Listeners must be subclasses of org.exoplatform.services.listener.Listener registered by the ListenerService. - </para> - <section id="sect-Reference_Guide-How_does_it_work-Registering_a_listener"> - <title>Registering a listener</title> - <para> - To register a listener, you need to call the addListener() method. - </para> - -<programlisting language="Java" role="Java">/** + </section> + </section> + <section id="sect-Reference_Guide-Specific_Services-Understanding_the_ListenerService"> + <title>Understanding the ListenerService</title> + <section id="sect-Reference_Guide-Understanding_the_ListenerService-Objectives"> + <title>Objectives</title> + <para> + This article will first describe how the ListenerService works and then it will show you how to configure the ListenerService. + </para> + </section> + <section id="sect-Reference_Guide-Understanding_the_ListenerService-What_is_the_ListenerService_"> + <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 id="sect-Reference_Guide-Understanding_the_ListenerService-How_does_it_work"> + <title>How does it work?</title> + <para> + Listeners must be subclasses of org.exoplatform.services.listener.Listener registered by the ListenerService. + </para> + <section id="sect-Reference_Guide-How_does_it_work-Registering_a_listener"> + <title>Registering a listener</title> + <para> + To register a listener, you need to call the addListener() method. + </para> + <programlisting language="Java" role="Java">/** * 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 + * name, create one if the listener list doesn&apos;t exit 2. Add the new listener * to the listener list * * @param listener @@ -102,19 +90,16 @@ 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 id="sect-Reference_Guide-How_does_it_work-Triggering_an_event"> - <title>Triggering an event</title> - <para> - To trigger an event, an application can call one of the broadcast() methods of ListenerService. - </para> - -<programlisting language="Java" role="Java">/** + <para> + By convention, we use the listener name as the name of the event to listen to. + </para> + </section> + <section id="sect-Reference_Guide-How_does_it_work-Triggering_an_event"> + <title>Triggering an event</title> + <para> + To trigger an event, an application can call one of the broadcast() methods of ListenerService. + </para> + <programlisting language="Java" role="Java">/** * 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 @@ -147,14 +132,13 @@ public &lt;T extends Event&gt; void broadcast(T event) throws Exception { ... }</programlisting> - <para> - The broadcast() 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 language="Java" role="Java">public abstract class Listener&lt;S, D&gt; extends BaseComponentPlugin { + <para> + The broadcast() 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 language="Java" role="Java">public abstract class Listener&lt;S, D&gt; extends BaseComponentPlugin { /** * This method should be invoked when an event with the same name is @@ -162,17 +146,15 @@ */ public abstract void onEvent(Event&lt;S, D&gt; 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 language="Java" role="Java">public interface ComponentPlugin { + <warning> + <para> + As you can see we use generics to limit the source of the event to the type &apos;S&apos; and the data of the event to the type &apos;D&apos;, 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 language="Java" role="Java">public interface ComponentPlugin { public String getName(); public void setName(String name); @@ -181,19 +163,14 @@ public void setDescription(String description); }</programlisting> - - </section> - - - </section> - - <section id="sect-Reference_Guide-Understanding_the_ListenerService-How_to_configure_a_listener"> - <title>How to configure a listener?</title> - <para> - All listeners are in fact a ComponentPlugin so it must be configured as below: - </para> - -<programlisting language="XML" role="XML">&lt;?xml version="1.0" encoding="ISO-8859-1"?&gt; + </section> + </section> + <section id="sect-Reference_Guide-Understanding_the_ListenerService-How_to_configure_a_listener"> + <title>How to configure a listener?</title> + <para> + All listeners are in fact a ComponentPlugin so it must be configured as below: + </para> + <programlisting language="XML" role="XML">&lt;?xml version=&quot;1.0&quot; encoding=&quot;ISO-8859-1&quot;?&gt; &lt;configuration&gt; ... &lt;external-component-plugins&gt; @@ -211,24 +188,20 @@ &lt;/external-component-plugins&gt; &lt;/configuration&gt;</programlisting> - - </section> - - <section id="sect-Reference_Guide-Understanding_the_ListenerService-Concrete_Example"> - <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 language="Java" role="Java">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&lt;ConversationRegistry, ConversationState&gt; 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 language="XML" role="XML">&lt;?xml version="1.0" encoding="ISO-8859-1"?&gt; + </section> + <section id="sect-Reference_Guide-Understanding_the_ListenerService-Concrete_Example"> + <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 language="Java" role="Java">listenerService.broadcast(&quot;exo.core.security.ConversationRegistry.register&quot;, this, state);</programlisting> + <para> + This code will in fact create a new Event which name is &quot;exo.core.security.ConversationRegistry.register&quot;, which source is the current instance of ConversationRegistry and which data is the given state. The ListenerService will call the method onEvent(Event&lt;ConversationRegistry, ConversationState&gt; event) on all the listeners which name is &quot;exo.core.security.ConversationRegistry.register&quot;. + </para> + <para> + In the example below, we define a Listener that will listen the event &quot;exo.core.security.ConversationRegistry.register&quot;. + </para> + <programlisting language="XML" role="XML">&lt;?xml version=&quot;1.0&quot; encoding=&quot;ISO-8859-1&quot;?&gt; &lt;configuration&gt; ... &lt;external-component-plugins&gt; @@ -247,119 +220,97 @@ &lt;/external-component-plugins&gt; &lt;/configuration&gt; ...</programlisting> - - </section> - - - </section> - - <section id="sect-Reference_Guide-Specific_Services-Job_Schedule"> - <title>Job Schedule</title> - <section id="sect-Reference_Guide-Job_Schedule-What_is_Job_Scheduler"> - <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 service that is in charge of unattended background executions, commonly known for historical reasons as batch processing. It is used to create and run jobs automatically and continuously, to schedule event-driven jobs and reports. - </para> - - </section> - - <section id="sect-Reference_Guide-Job_Schedule-How_does_Job_Scheduler_work"> - <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> - <para> - (Source: quartz-scheduler.org) - </para> - <section id="sect-Reference_Guide-How_does_Job_Scheduler_work-How_can_Job_Scheduler_Service_be_used_in_Kernel"> - <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 will 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 language="XML" role="XML">&lt;?xml version="1.0" encoding="UTF-8"?&gt; + </section> + </section> + <section id="sect-Reference_Guide-Specific_Services-Job_Schedule"> + <title>Job Schedule</title> + <section id="sect-Reference_Guide-Job_Schedule-What_is_Job_Scheduler"> + <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 service that is in charge of unattended background executions, commonly known for historical reasons as batch processing. It is used to create and run jobs automatically and continuously, to schedule event-driven jobs and reports. + </para> + </section> + <section id="sect-Reference_Guide-Job_Schedule-How_does_Job_Scheduler_work"> + <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> + <para> + (Source: quartz-scheduler.org) + </para> + <section id="sect-Reference_Guide-How_does_Job_Scheduler_work-How_can_Job_Scheduler_Service_be_used_in_Kernel"> + <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 will 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 language="XML" role="XML">&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt; &lt;configuration - xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" - xsi:schemaLocation="http://www.exoplaform.org/xml/ns/kernel_1_2.xsd http://www.exoplaform.org/xml/ns/kernel_1_2.xsd" - xmlns="http://www.exoplaform.org/xml/ns/kernel_1_2.xsd"&gt; + xmlns:xsi=&quot;http://www.w3.org/2001/XMLSchema-instance&quot; + xsi:schemaLocation=&quot;http://www.exoplaform.org/xml/ns/kernel_1_2.xsd http://www.exoplaform.org/xml/ns/kernel_1_2.xsd&quot; + xmlns=&quot;http://www.exoplaform.org/xml/ns/kernel_1_2.xsd&quot;... &lt;component&gt; &lt;type&gt;org.exoplatform.services.scheduler.impl.QuartzSheduler&lt;/type&gt; @@ -375,68 +326,57 @@ &lt;/component&gt; &lt;/configuration&gt;</programlisting> - - </section> - - <section id="sect-Reference_Guide-How_does_Job_Scheduler_work-Samples"> - <title>Samples</title> - <note> - <para> - You can download the project code from <ulink url="https://github.com/hoatle/job-scheduler-service-tutorial"&... - </para> - - </note> - <para> - 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 by using maven archetype plugin: - </para> - -<programlisting>mvn archetype:generate + </section> + <section id="sect-Reference_Guide-How_does_Job_Scheduler_work-Samples"> + <title>Samples</title> + <note> + <para> + You can download the project code from <ulink url="https://github.com/hoatle/job-scheduler-service-tutorial"&... + </para> + </note> + <para> + 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 by using maven archetype plug-in: + </para> + <programlisting>mvn archetype:generate </programlisting> - <itemizedlist> - <listitem> - <para> - For project type: select <emphasis role="bold">maven-archetype-quickstart </emphasis> - </para> + <itemizedlist> + <listitem> + <para> + For project type: select <emphasis role="bold">maven-archetype-quickstart </emphasis> + </para> + </listitem> + <listitem> + <para> + For groupId: select <emphasis role="bold">org.exoplatform.samples</emphasis> + </para> + </listitem> + <listitem> + <para> + For artifactId: select <emphasis role="bold">exo.samples.scheduler</emphasis> + </para> + </listitem> + <listitem> + <para> + For version: select<emphasis role="bold"> 1.0.0-SNAPSHOT</emphasis> + </para> + </listitem> + <listitem> + <para> + For package: select <emphasis role="bold">org.exoplatform.samples.scheduler</emphasis> + </para> + </listitem> + </itemizedlist> + <para> + Edit the pom.xml as follows: + </para> + <programlisting language="XML" role="XML">&lt;project + xmlns=&quot;http://maven.apache.org/POM/4.0.0&quot; + xmlns:xsi=&quot;http://www.w3.org/2001/XMLSchema-instance&quot; + xsi:schemaLocation=&quot;http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd&quot;&gt; - </listitem> - <listitem> - <para> - For groupId: select <emphasis role="bold">org.exoplatform.samples</emphasis> - </para> - - </listitem> - <listitem> - <para> - For artifactId: select <emphasis role="bold">exo.samples.scheduler</emphasis> - </para> - - </listitem> - <listitem> - <para> - For version: select<emphasis role="bold"> 1.0.0-SNAPSHOT</emphasis> - </para> - - </listitem> - <listitem> - <para> - For package: select <emphasis role="bold">org.exoplatform.samples.scheduler</emphasis> - </para> - - </listitem> - - </itemizedlist> - <para> - Edit the pom.xml as follows: - </para> - -<programlisting language="XML" role="XML">&lt;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"&gt; - &lt;modelVersion&gt;4.0.0&lt;/modelVersion&gt; &lt;parent&gt; @@ -451,24 +391,22 @@ &lt;name&gt;eXo Samples For Scheduler&lt;/name&gt; &lt;description&gt;eXo Samples Code For Scheduler&lt;/description&gt; &lt;/project&gt;</programlisting> - <para> - Generate an eclipse project by using maven eclipse plugin and then import into eclipse: - </para> - -<programlisting>mvn eclipse:eclipse</programlisting> - <para> - eXo Kernel makes it easier to work with job scheduler service. All you need is just to define your "job" class to be performed by implementing <emphasis role="italic">org.quartz.Job</emphasis> interface and add configuration for it. - </para> - <section id="sect-Reference_Guide-Samples-Define_a_job"> - <title>Define a job</title> - <para> - To define a job, do as follows: - </para> - <para> - Define your job to be performed. For example, the job <emphasis role="italic">DumbJob</emphasis> is defined as follows: - </para> - -<programlisting language="Java" role="Java">package org.exoplatform.samples.scheduler.jobs; + <para> + Generate an eclipse project by using maven eclipse plug-in and then import into eclipse: + </para> + <programlisting>mvn eclipse:eclipse</programlisting> + <para> + eXo Kernel makes it easier to work with job scheduler service. All you need is just to define your &quot;job&quot; class to be performed by implementing <emphasis role="italic">org.quartz.Job</emphasis> interface and add configuration for it. + </para> + <section id="sect-Reference_Guide-Samples-Define_a_job"> + <title>Define a job</title> + <para> + To define a job, do as follows: + </para> + <para> + Define your job to be performed. For example, the job <emphasis role="italic">DumbJob</emphasis> is defined as follows: + </para> + <programlisting language="Java" role="Java">package org.exoplatform.samples.scheduler.jobs; import org.exoplatform.services.log.ExoLogger; import org.exoplatform.services.log.Log; @@ -493,27 +431,23 @@ * @throws JobExecutionException */ public void execute(JobExecutionContext context) throws JobExecutionException { - LOG.info("DumbJob is executing..."); + LOG.info(&quot;DumbJob is executing...&quot;); } }</programlisting> - <para> - All jobs are required to implement the method <emphasis role="italic">execute</emphasis> from <emphasis role="italic">org.quartz.Job</emphasis> interface. This method will be called whenever a job is performed. With <emphasis role="italic">DumbJob</emphasis>, you just use logging to see that it will work. By looking at the terminal, you will see the log message: "DumbJob is executing..." - </para> - - </section> - - <section id="sect-Reference_Guide-Samples-Job_configuration"> - <title>Job configuration</title> - <para> - After defining the "job", the only next step is to configure it by using <emphasis role="italic">external-component-plugin</emphasis> configuration for <emphasis role="italic">org.exoplatform.services.scheduler.JobSchedulerService</emphasis>. You can use these methods below for setting component plugin: - </para> - -<programlisting language="Java" role="Java">public void addPeriodJob(ComponentPlugin plugin) throws Exception;</programlisting> - <para> - The component plugin for this method must be the type of <emphasis role="italic">org.exoplatform.services.scheduler.PeriodJob</emphasis>. This type of job is used to perform actions that are executed in a period of time. You have to define when this job is performed, when it ends, when it performs the first action, how many times it is executed and the period of time to perform the action. See the configuration sample below to understand more clearly: - </para> - -<programlisting language="XML" role="XML">&lt;external-component-plugins&gt; + <para> + All jobs are required to implement the method <emphasis role="italic">execute</emphasis> from <emphasis role="italic">org.quartz.Job</emphasis> interface. This method will be called whenever a job is performed. With <emphasis role="italic">DumbJob</emphasis>, you just use logging to see that it will work. By looking at the terminal, you will see the log message: &quot;DumbJob is executing...&quot; + </para> + </section> + <section id="sect-Reference_Guide-Samples-Job_configuration"> + <title>Job configuration</title> + <para> + After defining the &quot;job&quot;, the only next step is to configure it by using <emphasis role="italic">external-component-plugin</emphasis> configuration for <emphasis role="italic">org.exoplatform.services.scheduler.JobSchedulerService</emphasis>. You can use these methods below for setting component plug-in: + </para> + <programlisting language="Java" role="Java">public void addPeriodJob(ComponentPlugin plugin) throws Exception;</programlisting> + <para> + The component plug-in for this method must be the type of <emphasis role="italic">org.exoplatform.services.scheduler.PeriodJob</emphasis>. This type of job is used to perform actions that are executed in a period of time. You have to define when this job is performed, when it ends, when it performs the first action, how many times it is executed and the period of time to perform the action. See the configuration sample below to understand more clearly: + </para> + <programlisting language="XML" role="XML">&lt;external-component-plugins&gt; &lt;target-component&gt;org.exoplatform.services.scheduler.JobSchedulerService&lt;/target-component&gt; &lt;component-plugin&gt; &lt;name&gt;PeriodJob Plugin&lt;/name&gt; @@ -524,24 +458,22 @@ &lt;properties-param&gt; &lt;name&gt;job.info&lt;/name&gt; &lt;description&gt;dumb job executed periodically&lt;/description&gt; - &lt;property name="jobName" value="DumbJob"/&gt; - &lt;property name="groupName" value="DumbJobGroup"/&gt; - &lt;property name="job" value="org.exoplatform.samples.scheduler.jobs.DumbJob"/&gt; - &lt;property name="repeatCount" value="0"/&gt; - &lt;property name="period" value="60000"/&gt; - &lt;property name="startTime" value="+45"/&gt; - &lt;property name="endTime" value=""/&gt; + &lt;property name=&quot;jobName&quot; value=&quot;DumbJob&quot;/&gt; + &lt;property name=&quot;groupName&quot; value=&quot;DumbJobGroup&quot;/&gt; + &lt;property name=&quot;job&quot; value=&quot;org.exoplatform.samples.scheduler.jobs.DumbJob&quot;/&gt; + &lt;property name=&quot;repeatCount&quot; value=&quot;0&quot;/&gt; + &lt;property name=&quot;period&quot; value=&quot;60000&quot;/&gt; + &lt;property name=&quot;startTime&quot; value=&quot;+45&quot;/&gt; + &lt;property name=&quot;endTime&quot; value=&quot;&quot;/&gt; &lt;/properties-param&gt; &lt;/init-params&gt; &lt;/component-plugin&gt; &lt;/external-component-plugins&gt;</programlisting> - -<programlisting language="Java" role="Java">public void addCronJob(ComponentPlugin plugin) throws Exception;</programlisting> - <para> - The component plugin for this method must be the type of <emphasis role="italic">org.exoplatform.services.scheduler.CronJob</emphasis>. This type of job is used to perform actions at specified time with Unix 'cron-like' definitions. The plugin uses "expression" field for specifying the 'cron-like' definitions to execute the job. This is considered as the most powerful and flexible job to define when it will execute. For example, at 12pm every day =&gt; "0 0 12 * * ?"; or at 10:15am every Monday, Tuesday, Wednesday, Thursday and Friday =&gt; "0 15 10 ? * MON-FRI". To see more about Cron expression, please refer to this article: <ulink url="http://en.wikipedia.org/wiki/CRON_expression">CRON expression</ulink>. See the configuration sample below to understand more clearly: - </para> - -<programlisting language="XML" role="XML">&lt;external-component-plugins&gt; + <programlisting language="Java" role="Java">public void addCronJob(ComponentPlugin plugin) throws Exception;</programlisting> + <para> + The component plug-in for this method must be the type of <emphasis role="italic">org.exoplatform.services.scheduler.CronJob</emphasis>. This type of job is used to perform actions at specified time with Unix &apos;cron-like&apos; definitions. The plug-in uses &quot;expression&quot; field for specifying the &apos;cron-like&apos; definitions to execute the job. This is considered as the most powerful and flexible job to define when it will execute. For example, at 12pm every day =&gt; &quot;0 0 12 * * ?&quot;; or at 10:15am every Monday, Tuesday, Wednesday, Thursday and Friday =&gt; &quot;0 15 10 ? * MON-FRI&quot;. To see more about Cron expression, please refer to this article: <ulink url="http://en.wikipedia.org/wiki/CRON_expression">CRON expression</ulink>. See the configuration sample below to understand more clearly: + </para> + <programlisting language="XML" role="XML">&lt;external-component-plugins&gt; &lt;target-component&gt;org.exoplatform.services.scheduler.JobSchedulerService&lt;/target-component&gt; &lt;component-plugin&gt; &lt;name&gt;CronJob Plugin&lt;/name&gt; @@ -552,43 +484,36 @@ &lt;properties-param&gt; &lt;name&gt;job.info&lt;/name&gt; &lt;description&gt;dumb job executed by cron expression&lt;/description&gt; - &lt;property name="jobName" value="DumbJob"/&gt; - &lt;property name="groupName" value="DumbJobGroup"/&gt; - &lt;property name="job" value="org.exoplatform.samples.scheduler.jobs.DumbJob"/&gt; + &lt;property name=&quot;jobName&quot; value=&quot;DumbJob&quot;/&gt; + &lt;property name=&quot;groupName&quot; value=&quot;DumbJobGroup&quot;/&gt; + &lt;property name=&quot;job&quot; value=&quot;org.exoplatform.samples.scheduler.jobs.DumbJob&quot;/&gt; &lt;!-- The job will be performed at 10:15am every day --&gt; - &lt;property name="expression" value="0 15 10 * * ?"/&gt; + &lt;property name=&quot;expression&quot; value=&quot;0 15 10 * * ?&quot;/&gt; &lt;/properties-param&gt; &lt;/init-params&gt; &lt;/component-plugin&gt; &lt;/external-component-plugins&gt;</programlisting> - -<programlisting language="Java" role="Java">public void addGlobalJobListener(ComponentPlugin plugin) throws Exception;</programlisting> - -<programlisting language="Java" role="Java">public void addJobListener(ComponentPlugin plugin) throws Exception;</programlisting> - <para> - The component plugin for two methods above must be the type of <emphasis role="italic">org.quartz.JobListener.</emphasis> This job listener is used so that it will be informed when a <emphasis role="italic">org.quartz.JobDetail</emphasis> executes. - </para> - -<programlisting language="Java" role="Java">public void addGlobalTriggerListener(ComponentPlugin plugin) throws Exception;</programlisting> - -<programlisting language="Java" role="Java">public void addTriggerListener(ComponentPlugin plugin) throws Exception;</programlisting> - <para> - The component plugin for two methods above must be the type of <emphasis role="italic">org.quartz.TriggerListener</emphasis>. This trigger listener is used so that it will be informed when a <emphasis role="italic">org.quartz.Trigger</emphasis> fires. - </para> - - </section> - - <section id="sect-Reference_Guide-Samples-Run_the_project"> - <title>Run the project</title> - <para> - Create <emphasis role="italic">conf.portal</emphasis> package in your sample project. Add the configuration.xml file with the content as follows: - </para> - -<programlisting language="XML" role="XML">&lt;?xml version="1.0" encoding="UTF-8"?&gt; + <programlisting language="Java" role="Java">public void addGlobalJobListener(ComponentPlugin plugin) throws Exception;</programlisting> + <programlisting language="Java" role="Java">public void addJobListener(ComponentPlugin plugin) throws Exception;</programlisting> + <para> + The component plug-in for two methods above must be the type of <emphasis role="italic">org.quartz.JobListener.</emphasis> This job listener is used so that it will be informed when a <emphasis role="italic">org.quartz.JobDetail</emphasis> executes. + </para> + <programlisting language="Java" role="Java">public void addGlobalTriggerListener(ComponentPlugin plugin) throws Exception;</programlisting> + <programlisting language="Java" role="Java">public void addTriggerListener(ComponentPlugin plugin) throws Exception;</programlisting> + <para> + The component plug-in for two methods above must be the type of <emphasis role="italic">org.quartz.TriggerListener</emphasis>. This trigger listener is used so that it will be informed when a <emphasis role="italic">org.quartz.Trigger</emphasis> fires. + </para> + </section> + <section id="sect-Reference_Guide-Samples-Run_the_project"> + <title>Run the project</title> + <para> + Create <emphasis role="italic">conf.portal</emphasis> package in your sample project. Add the configuration.xml file with the content as follows: + </para> + <programlisting language="XML" role="XML">&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt; &lt;configuration - xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" - xsi:schemaLocation="http://www.exoplaform.org/xml/ns/kernel_1_2.xsd http://www.exoplaform.org/xml/ns/kernel_1_2.xsd" - xmlns="http://www.exoplaform.org/xml/ns/kernel_1_2.xsd"&gt; + xmlns:xsi=&quot;http://www.w3.org/2001/XMLSchema-instance&quot; + xsi:schemaLocation=&quot;http://www.exoplaform.org/xml/ns/kernel_1_2.xsd http://www.exoplaform.org/xml/ns/kernel_1_2.xsd&quot; + xmlns=&quot;http://www.exoplaform.org/xml/ns/kernel_1_2.xsd&quot;... &lt;component&gt; &lt;type&gt;org.exoplatform.services.scheduler.impl.QuartzSheduler&lt;/type&gt; @@ -612,119 +537,88 @@ &lt;properties-param&gt; &lt;name&gt;job.info&lt;/name&gt; &lt;description&gt;dumb job executed periodically&lt;/description&gt; - &lt;property name="jobName" value="DumbJob"/&gt; - &lt;property name="groupName" value="DumbJobGroup"/&gt; - &lt;property name="job" value="org.exoplatform.samples.scheduler.jobs.DumbJob"/&gt; - &lt;property name="repeatCount" value="0"/&gt; - &lt;property name="period" value="60000"/&gt; - &lt;property name="startTime" value="+45"/&gt; - &lt;property name="endTime" value=""/&gt; + &lt;property name=&quot;jobName&quot; value=&quot;DumbJob&quot;/&gt; + &lt;property name=&quot;groupName&quot; value=&quot;DumbJobGroup&quot;/&gt; + &lt;property name=&quot;job&quot; value=&quot;org.exoplatform.samples.scheduler.jobs.DumbJob&quot;/&gt; + &lt;property name=&quot;repeatCount&quot; value=&quot;0&quot;/&gt; + &lt;property name=&quot;period&quot; value=&quot;60000&quot;/&gt; + &lt;property name=&quot;startTime&quot; value=&quot;+45&quot;/&gt; + &lt;property name=&quot;endTime&quot; value=&quot;&quot;/&gt; &lt;/properties-param&gt; &lt;/init-params&gt; &lt;/component-plugin&gt; &lt;/external-component-plugins&gt; &lt;/configuration&gt;</programlisting> - <para> - <emphasis role="italic">mvn clean install </emphasis>the project. Copy .jar file to<emphasis role="italic"> lib</emphasis> in tomcat bundled with GateIn-3.1.0-GA. Run <emphasis role="italic">bin/gatein.sh</emphasis> to see the <emphasis role="italic">DumbJob</emphasis> to be executed on the terminal when portal containers are initialized. Please look at the terminal to see the log message of <emphasis role="italic">DumbJob</emphasis>. - </para> - <para> - From now on, you can easily create any job to be executed in GateIn's portal by defining your job and configuring it. - </para> + <para> + <emphasis role="italic">mvn clean install </emphasis>the project. Copy .jar file to<emphasis role="italic"> lib</emphasis> in tomcat bundled with GateIn-3.1.0-GA. Run <emphasis role="italic">bin/gatein.sh</emphasis> to see the <emphasis role="italic">DumbJob</emphasis> to be executed on the terminal when portal containers are initialized. Please look at the terminal to see the log message of <emphasis role="italic">DumbJob</emphasis>. + </para> + <para> + From now on, you can easily create any job to be executed in GateIn&apos;s portal by defining your job and configuring it. + </para> + </section> + </section> + </section> + <section id="sect-Reference_Guide-Job_Schedule-Reference"> + <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... + </para> + </listitem> + <listitem> + <para> + <ulink url="http://en.wikipedia.org/wiki/Job_scheduler">http://en.w... + </para> + </listitem> + <listitem> + <para> + <ulink url="http://www.theserverside.com/news/1364726/Job-Scheduling-in-J2E... + </para> + </listitem> + <listitem> + <para> + <ulink url="http://technet.microsoft.com/en-us/library/cc720070%28WS.10%29.... + </para> + </listitem> + </itemizedlist> + </section> + </section> + <section id="sect-Reference_Guide-Specific_Services-The_data_source_provider"> + <title>The data source provider</title> + <section id="sect-Reference_Guide-The_data_source_provider-Description"> + <title>Description</title> + <para> + The <emphasis>DataSourceProvider</emphasis> is a service used to give access to a data source in an uniform manner in order to be able to support data sources that are managed by the application server. + </para> + <para> + <table id="tabl-Reference_Guide-Description-List_methods"> + <title>List methods</title> + <tgroup cols="2"> + <tbody> + <row> + <entry> getDataSource(String dataSourceName) </entry> + <entry> Tries to get the data source from a JNDI lookup. If it can be found and the data source is defined as managed, the service will wrap the original <emphasis>DataSource</emphasis> instance in a new <emphasis>DataSource</emphasis> instance that is aware of its <emphasis>managed</emphasis> state otherwise it will return the original <emphasis>DataSource</emphasis> instance. </entry> + </row> + <row> + <entry> isManaged(String dataSourceName) </entry> + <entry> Indicates whether or not the given data source is managed. </entry> + </row> + </tbody> + </tgroup> + </table> - </section> - - - </section> - - - </section> - - <section id="sect-Reference_Guide-Job_Schedule-Reference"> - <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... - </para> - - </listitem> - <listitem> - <para> - <ulink url="http://en.wikipedia.org/wiki/Job_scheduler">http://en.w... - </para> - - </listitem> - <listitem> - <para> - <ulink url="http://www.theserverside.com/news/1364726/Job-Scheduling-in-J2E... - </para> - - </listitem> - <listitem> - <para> - <ulink url="http://technet.microsoft.com/en-us/library/cc720070%28WS.10%29.... - </para> - - </listitem> - - </itemizedlist> - - </section> - - - </section> - - <section id="sect-Reference_Guide-Specific_Services-The_data_source_provider"> - <title>The data source provider</title> - <section id="sect-Reference_Guide-The_data_source_provider-Description"> - <title>Description</title> - <para> - The <emphasis>DataSourceProvider</emphasis> is a service used to give access to a data source in an uniform manner in order to be able to support data sources that are managed by the application server. - </para> - <para> - <table id="tabl-Reference_Guide-Description-List_methods"> - <title>List methods</title> - <tgroup cols="2"> - <tbody> - <row> - <entry> - getDataSource(String dataSourceName) - </entry> - <entry> - Tries to get the data source from a JNDI lookup. If it can be found and the data source is defined as managed, the service will wrap the original <emphasis>DataSource</emphasis> instance in a new <emphasis>DataSource</emphasis> instance that is aware of its <emphasis>managed</emphasis> state otherwise it will return the original <emphasis>DataSource</emphasis> instance. - </entry> - - </row> - <row> - <entry> - isManaged(String dataSourceName) - </entry> - <entry> - Indicates whether or not the given data source is managed. - </entry> - - </row> - - </tbody> - - </tgroup> - - </table> - - </para> - - </section> - - <section id="sect-Reference_Guide-The_data_source_provider-Configuration"> - <title>Configuration</title> - <para> - The configuration of the <emphasis>DataSourceProvider</emphasis> should be defined only if you use managed data sources since by default all the data sources are considered as not managed. See below the default configuration - </para> - -<programlisting>&lt;configuration&gt; + </para> + </section> + <section id="sect-Reference_Guide-The_data_source_provider-Configuration"> + <title>Configuration</title> + <para> + The configuration of the <emphasis>DataSourceProvider</emphasis> should be defined only if you use managed data sources since by default all the data sources are considered as not managed. See below the default configuration + </para> + <programlisting>&lt;configuration&gt; .... &lt;component&gt; &lt;key&gt;org.exoplatform.services.jdbc.DataSourceProvider&lt;/key&gt; @@ -760,50 +654,31 @@ &lt;/component&gt; ... &lt;/configuration&gt;</programlisting> - <table id="tabl-Reference_Guide-Configuration-Fields_description"> - <title>Fields description</title> - <tgroup cols="2"> - <tbody> - <row> - <entry> - <emphasis>check-tx-active</emphasis> - </entry> - <entry> - This parameter indicates that the data source needs to check if a transaction is active to decide if the provided connection needs to be managed or not. If it is set to <emphasis>false</emphasis>, the data source will provide only managed connections if the data source itself is managed. By default, this parameter is set to <emphasis>true</emphasis>. If this parameter is set to <emphasis>true</emphasis>, it will need the <emphasis>TransactionService</emphasis> to work properly, so please ensure that the <emphasis>TransactionService</emphasis> is defined in your configuration. - </entry> - - </row> - <row> - <entry> - <emphasis>always-managed</emphasis> - </entry> - <entry> - This parameter indicates that all the data sources are managed. If set to <emphasis>true</emphasis> the parameter <emphasis>never-managed</emphasis> and <emphasis>managed-data-sources</emphasis> will be ignored, so it will consider all the data sources as managed. By default, this parameter is set to <emphasis>false</emphasis>. - </entry> - - </row> - <row> - <entry> - <emphasis>managed-data-sources</emphasis> - </entry> - <entry> - This parameter indicates the list of all the data sources that are managed, each value tag can contain a list of data source names separated by a comma. If <emphasis>always-managed</emphasis> and/or <emphasis>never-managed</emphasis> is set <emphasis>true</emphasis> this parameter is ignored. - </entry> - - </row> - - </tbody> - - </tgroup> - - </table> - - </section> - - - </section> - - + <table id="tabl-Reference_Guide-Configuration-Fields_description"> + <title>Fields description</title> + <tgroup cols="2"> + <tbody> + <row> + <entry> + <emphasis>check-tx-active</emphasis> + </entry> + <entry> This parameter indicates that the data source needs to check if a transaction is active to decide if the provided connection needs to be managed or not. If it is set to <emphasis>false</emphasis>, the data source will provide only managed connections if the data source itself is managed. By default, this parameter is set to <emphasis>true</emphasis>. If this parameter is set to <emphasis>true</emphasis>, it will need the <emphasis>TransactionService</emphasis> to work properly, so please ensure that the <emphasis>TransactionService</emphasis> is defined in your configuration. </entry> + </row> + <row> + <entry> + <emphasis>always-managed</emphasis> + </entry> + <entry> This parameter indicates that all the data sources are managed. If set to <emphasis>true</emphasis> the parameter <emphasis>never-managed</emphasis> and <emphasis>managed-data-sources</emphasis> will be ignored, so it will consider all the data sources as managed. By default, this parameter is set to <emphasis>false</emphasis>. </entry> + </row> + <row> + <entry> + <emphasis>managed-data-sources</emphasis> + </entry> + <entry> This parameter indicates the list of all the data sources that are managed, each value tag can contain a list of data source names separated by a comma. If <emphasis>always-managed</emphasis> and/or <emphasis>never-managed</emphasis> is set <emphasis>true</emphasis> this parameter is ignored. </entry> + </row> + </tbody> + </tgroup> + </table> + </section> + </section> </section> - - Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/AuthenticationAuthorizationOverview.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/AuthenticationAuthorizationOverview.xml 2012-07-05 19:41:59 UTC (rev 8774) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/AuthenticationAuthorizationOverview.xml 2012-07-06 05:00:36 UTC (rev 8775) @@ -1,62 +1,52 @@ -<?xml version='1.0' encoding='utf-8' ?> +<?xml version='1.0' encoding='UTF-8'?> <!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!ENTITY % BOOK_ENTITIES SYSTEM "../../Reference_Guide.ent"> %BOOK_ENTITIES; ]> - <section id="sect-Reference_Guide-Authentication_Authorization_Intro"> - <title>Authentication and Authorization intro</title> - - <section id="sect-Reference_Guide-Authentication_Authorization_Intro-Authentication"> - <title>Authentication Overview</title> - - <para> - Authentication in JBoss Enterprise Portal Platform is based on <ulink type="http" url="http://docs.oracle.com/javase/6/docs/technotes/guides/security/... and by default it is a standard J2EE FORM based authentication. +<section id="sect-Reference_Guide-Authentication_Authorization_Intro"> + <title>Authentication and Authorization intro</title> + <section id="sect-Reference_Guide-Authentication_Authorization_Intro-Authentication"> + <title>Authentication Overview</title> + <para> + Authentication in JBoss Enterprise Portal Platform is based on <ulink url="http://docs.oracle.com/javase/6/docs/technotes/guides/security/... type="http">JAAS</ulink> and by default it is a standard J2EE FORM based authentication. </para> - - <para> + <para> JBoss Enterprise Portal Platform supports the following authentication methods: </para> - - <itemizedlist> - <listitem> - <para> + <itemizedlist> + <listitem> + <para> J2EE FORM based authentication </para> - </listitem> - - <listitem> - <para> + </listitem> + <listitem> + <para> The <literal>RememberMe</literal> authentication method (wherein the user checks the <guilabel>Remember my login</guilabel> checkbox on the log in form). </para> - </listitem> - - <listitem> - <para> - SSO server integration (CAS, JOSSO, OpenSSO). Refer to <xref linkend="sect-Reference_Guide-SSO_Single_Sign_On" /> for more information. + </listitem> + <listitem> + <para> + SSO server integration (CAS, JOSSO, OpenSSO). Refer to <xref linkend="sect-Reference_Guide-SSO_Single_Sign_On"/> for more information. </para> - </listitem> - - <listitem> - <para> - SPNEGO authentication with a Kerberos ticket. Refer to <xref linkend="sect-Reference_Guide-SSO_Single_Sign_On_-SPNEGO_Simple_and_Protected_GSSAPI_Negotiation_Mechanism" /> for more information. + </listitem> + <listitem> + <para> + SPNEGO authentication with a Kerberos ticket. Refer to <xref linkend="sect-Reference_Guide-SSO_Single_Sign_On_-SPNEGO_Simple_and_Protected_GSSAPI_Negotiation_Mechanism"/> for more information. </para> - </listitem> - - <listitem> - <para> - Cluster authentication with loadbalancer or with JBoss SSO valve. Refer to <xref linkend="sect-Reference_Guide-SSO_Single_Sign_On_-Enabling_SSO_using_JBoss_SSO_Valve" /> for more information. + </listitem> + <listitem> + <para> + Cluster authentication with loadbalancer or with JBoss SSO valve. Refer to <xref linkend="sect-Reference_Guide-SSO_Single_Sign_On_-Enabling_SSO_using_JBoss_SSO_Valve"/> for more information. </para> - </listitem> - </itemizedlist> - - <para> - Authentication workflow consists of HTTP requests and redirects which include handshakes. Source code related to authentication is partially included in the WCI module, as the authentication process differs on <ulink type="http" url="http://www.jcp.org/en/jsr/detail?id=154">Servlet 2.5</ulink> containers and <ulink type="http" url="http://www.jcp.org/en/jsr/detail?id=315">Servlet 3.0</ulink> containers. + </listitem> + </itemizedlist> + <para> + Authentication workflow consists of HTTP requests and redirects which include handshakes. Source code related to authentication is partially included in the WCI module, as the authentication process differs on <ulink url="http://www.jcp.org/en/jsr/detail?id=154" type="http">Servlet 2.5</ulink> containers and <ulink url="http://www.jcp.org/en/jsr/detail?id=315" type="http">Servlet 3.0</ulink> containers. </para> - - <para> + <para> First you can see in <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/web.xml</filename> that authentication is triggered by accessing a secured URL: </para> -<programlisting language="XML" role="XML"> + <programlisting language="XML" role="XML"> <![CDATA[ <security-constraint> <web-resource-collection> @@ -75,17 +65,16 @@ </security-constraint> ]]> </programlisting> - <para> - This means that access to some URLs (such as <ulink type="http" url="http://localhost:8080/portal/dologin">http://localhost:8080/portal/dologin</ulink>) will directly trigger J2EE authentication in the case that the user is not already logged in. + <para> + This means that access to some URLs (such as <ulink url="http://localhost:8080/portal/dologin" type="http">http://localhost:8080/portal/dologin</ulink>) will directly trigger J2EE authentication in the case that the user is not already logged in. </para> - <para> + <para> Access to this URL also means that the user needs to be in the JAAS group <emphasis>users</emphasis>, otherwise they can authenticate but will receive an HTTP error; <emphasis>403 Forbidden</emphasis>, for example. </para> - - <para> + <para> In the next part of the file we can see that authentication is FORM based and it starts by redirection to <emphasis>/initiatelogin</emphasis> URL, which is actually mapped to <literal>InitiateLoginServlet</literal>. </para> -<programlisting language="XML" role="XML"> + <programlisting language="XML" role="XML"> <![CDATA[ <login-config> <auth-method>FORM</auth-method> @@ -97,58 +86,51 @@ </login-config> ]]> </programlisting> - <para> + <para> <literal>InitiateLoginServlet</literal> simply redirects user to login page placed in <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/02portal.war/login/jsp/login.jsp</filename>. <mediaobject> - <imageobject role="html"> - <imagedata fileref="images/AuthenticationAndIdentity/Overview/loginScreen.png" format="PNG" align="center"/> - </imageobject> - - <imageobject role="fo"> - <imagedata fileref="images/AuthenticationAndIdentity/Overview/loginScreen.png" scalefit="1" format="PNG" align="center"/> - </imageobject> - </mediaobject> + <imageobject role="html"> + <imagedata align="center" fileref="images/AuthenticationAndIdentity/Overview/loginScreen.png" format="PNG"/> + </imageobject> + <imageobject role="fo"> + <imagedata align="center" scalefit="1" fileref="images/AuthenticationAndIdentity/Overview/loginScreen.png" format="PNG"/> + </imageobject> + </mediaobject> </para> - - <para> + <para> Changes to the appearance of this login page can be made in this JSP file. You can also change image or CSS placed in <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/login/skin</filename> . </para> - - <para> - After a user submits the login form, they are redirected to the login URL; <ulink type="http" url="http://localhost:8080/portal/login?username=root&amp;password=gtn&amp;initialURI=/portal/classic">http://localhost:8080/portal/login?username=root&amp;password=gtn&amp;initialURI=/portal/private/classic</ulink>. + <para> + After a user submits the login form, they are redirected to the login URL; <ulink url="http://localhost:8080/portal/login?username=root&amp;password=gtn&amp;initialURI=/portal/classic" type="http">http://localhost:8080/portal/login?username=root&amp;password=gtn&amp;initialURI=/portal/private/classic</ulink>. </para> - <para> + <para> This URL is mapped to <literal>PortalLoginController</literal> servlet, which stores credentials and redirects again to <literal>InitiateLoginServlet</literal>, which performs a WCI login. </para> - <para> + <para> The WCI layer can recognize the current servlet container to determine if it is the old container with Servlet API 2.5 (JBoss 5, Tomcat 6) or the newer container with Servlet API 3.0 (JBoss 6, JBoss 7, Tomcat 7). </para> - - <formalpara> - <title>Servlet 3.0</title> - <para> + <formalpara> + <title>Servlet 3.0</title> + <para> The newer servlet API supports programmatic authentication by calling method <literal>HttpServletRequest.login(String username, String password)</literal>. This will directly call JAAS authentication without needing to perform any redirects. </para> - </formalpara> - - <formalpara> - <title>Servlet 2.5</title> - <para> - The older API does not support programmatic authentication, so a redirection to a URL which will trigger JAAS authentication (such as; <ulink type="http" url="http://localhost:8080/portal/j_security_check?j_username=root&amp;j_password=wci-ticket-1385113882&amp;initialURI=/portal/private/classic/"></ulink>) is required. In this case, JAAS authentication is not triggered with a user password but with a WCI ticket which is created by <literal>InitiateLoginServlet</literal> during WCI login and saved into WCI <emphasis>TicketService</emphasis>. The purpose of this ticket is to avoid using a password during the URL redirection. + </formalpara> + <formalpara> + <title>Servlet 2.5</title> + <para> + The older API does not support programmatic authentication, so a redirection to a URL which will trigger JAAS authentication (such as; <ulink url="http://localhost:8080/portal/j_security_check?j_username=root&amp;j_password=wci-ticket-1385113882&amp;initialURI=/portal/private/classic/" type="http"/>) is required. In this case, JAAS authentication is not triggered with a user password but with a WCI ticket which is created by <literal>InitiateLoginServlet</literal> during WCI login and saved into WCI <emphasis>TicketService</emphasis>. The purpose of this ticket is to avoid using a password during the URL redirection. </para> - </formalpara> - </section> - - <section id="sect-Reference_Guide-Authentication_Authorization_Intro-LoginModules"> - <title>Login modules</title> - - <para> + </formalpara> + </section> + <section id="sect-Reference_Guide-Authentication_Authorization_Intro-LoginModules"> + <title>Login modules</title> + <para> JBoss Enterprise Portal Platform uses its own security domain (<emphasis role="bold">gatein-domain</emphasis>) with a set of predefined login modules. Login module configuration for <emphasis>gatein-domain</emphasis> is contained in the <filename>deploy/gatein.ear/META-INF/gatein-jboss-beans.xml</filename> file. </para> - <para> + <para> Below is the default login modules stack: </para> -<programlisting language="XML" role="XML"><![CDATA[ + <programlisting language="XML" role="XML"><![CDATA[ <login-module code="org.gatein.wci.security.WCILoginModule" flag="optional"> <module-option name="portalContainerName">portal</module-option> <module-option name="realmName">gatein-domain</module-option> @@ -177,197 +159,173 @@ <module-option name="portalContainerName">portal</module-option> <module-option name="realmName">gatein-domain</module-option> </login-module>]]></programlisting> - <para> + <para> New login modules can be added or the stack completely replaced with custom modules. </para> - <para> + <para> Some points to consider are: </para> - - <itemizedlist> - <listitem> - <para> + <itemizedlist> + <listitem> + <para> It is possible to log a user in through existing login modules with their credentials (username: <literal>root</literal>/ password: <literal>gtn</literal>, for example) but also with a WCI ticket (username: <literal>root</literal>/password: <literal>wci-ticket-458791</literal>). The login modules stack supports both of these methods of authentication. </para> - </listitem> - - <listitem> - <para> - Authentication through a WCI ticket is used for FORM based authentication in Servlet 2.5 containers (JBoss 5 or Tomcat 6). The majority of other cases (Servlet 3.0 login, JBoss SSO valve login, login through <ulink type="http" url="http://code.google.com/p/crsh/">Crash</ulink>;, BASIC authentication) are using an actual password. + </listitem> + <listitem> + <para> + Authentication through a WCI ticket is used for FORM based authentication in Servlet 2.5 containers (JBoss 5 or Tomcat 6). The majority of other cases (Servlet 3.0 login, JBoss SSO valve login, login through <ulink url="http://code.google.com/p/crsh/" type="http">Crash</ulink>, BASIC authentication) are using an actual password. </para> - </listitem> - - <listitem> - <para> + </listitem> + <listitem> + <para> Authentication starts with the invocation of the <emphasis>login</emphasis> method on each login module. Once all <emphasis>login</emphasis> methods are invoked, then authentication continues by invoking the <emphasis>commit</emphasis> method on each login module. </para> - <para> + <para> Either method (<emphasis>login</emphasis> or <emphasis>commit</emphasis>) can throw <literal>LoginException</literal>. If this happens, the whole authentication process ends unsuccessfully, which in turn, invokes the <emphasis>abort</emphasis> method on each login module. </para> - <para> - By returning "false" from the login method ensures that login module is ignored. This is not specific to JBoss Enterprise Portal Platform but generic to JAAS. More info about login modules in general can be found at <ulink type="http" url="http://docs.oracle.com/javase/6/docs/technotes/guides/security/...;. + <para> + By returning &quot;false&quot; from the login method ensures that login module is ignored. This is not specific to JBoss Enterprise Portal Platform but generic to JAAS. More info about login modules in general can be found at <ulink url="http://docs.oracle.com/javase/6/docs/technotes/guides/security/... type="http"/>. </para> - </listitem> - </itemizedlist> - - <section id="sect-Authentication_Authorization_Intro-existingLM"> - <title>Existing login modules</title> - - <para> + </listitem> + </itemizedlist> + <section id="sect-Authentication_Authorization_Intro-existingLM"> + <title>Existing login modules</title> + <para> Here is a brief description of existing login modules: </para> - <variablelist> - <title>Modules</title> - <varlistentry> - <term>WCILoginModule</term> - <listitem> - <para> + <variablelist> + <title>Modules</title> + <varlistentry> + <term>WCILoginModule</term> + <listitem> + <para> This login module validates WCI login tickets and then finds the actual username and password of the user from WCI <emphasis>TicketService</emphasis>. It saves these details into <literal>sharedState</literal> map. The username is saved under the key <literal>javax.security.auth.login.name</literal> and the password is saved under the key <literal>javax.security.auth.login.password</literal>. </para> - <note> - <title>Note</title> - <para> - If you trigger JAAS authentication with a literal username and password and not with a WCI ticket credential, the <literal>WCILoginModule</literal> throws a <literal>LoginException</literal>. However <literal>WCILoginModule</literal> is declared as "<emphasis>optional</emphasis>", meaning that a login failure in <literal>WCILoginModule</literal> is not a critical error to the full login process. + <note> + <title>Note</title> + <para> + If you trigger JAAS authentication with a literal username and password and not with a WCI ticket credential, the <literal>WCILoginModule</literal> throws a <literal>LoginException</literal>. However <literal>WCILoginModule</literal> is declared as &quot;<emphasis>optional</emphasis>&quot;, meaning that a login failure in <literal>WCILoginModule</literal> is not a critical error to the full login process. </para> - </note> - </listitem> - </varlistentry> - <varlistentry> - <term>PortalLoginModule</term> - <listitem> - <para> - This login module is actually used mainly in cluster environments. It uses session replication between cluster nodes. After a successful authentication on cluster <emphasis>node1</emphasis> the <emphasis>commit</emphasis> method adds a flag (with the attribute <emphasis>AUTHENTICATED_CREDENTIALS</emphasis>) to the HTTP session and this flag can then be used to re-authenticate on <emphasis>node2</emphasis> when it executes method <emphasis>login</emphasis>. Refer to <xref linkend="sect-Authentication_Authorization_Intro-ClusterLogin" /> for more information. + </note> + </listitem> + </varlistentry> + <varlistentry> + <term>PortalLoginModule</term> + <listitem> + <para> + This login module is actually used mainly in cluster environments. It uses session replication between cluster nodes. After a successful authentication on cluster <emphasis>node1</emphasis> the <emphasis>commit</emphasis> method adds a flag (with the attribute <emphasis>AUTHENTICATED_CREDENTIALS</emphasis>) to the HTTP session and this flag can then be used to re-authenticate on <emphasis>node2</emphasis> when it executes method <emphasis>login</emphasis>. Refer to <xref linkend="sect-Authentication_Authorization_Intro-ClusterLogin"/> for more information. </para> - </listitem> - </varlistentry> - <varlistentry> - <term>SharedStateLoginModule</term> - <listitem> - <para> + </listitem> + </varlistentry> + <varlistentry> + <term>SharedStateLoginModule</term> + <listitem> + <para> This login module triggers authentication using the <emphasis>Authenticator</emphasis> interface. It takes the username and password from the <literal>javax.security.auth.login.name</literal> and <literal>javax.security.auth.login.password</literal> attributes of the <literal>sharedState</literal> map. </para> - <para> - Then it calls <literal>Authenticator.validateUser(Credential[] credentials)</literal>, which performs real authentication of username and password against OrganizationService and portal identity database. Result of successful authentication is object <emphasis>Identity</emphasis>, which is saved to sharedState map under key <literal>exo.security.identity</literal>. More info in <xref linkend="sect-Authentication_Authorization_Intro-authenticatorAndRolesExtractor" />. + <para> + Then it calls <literal>Authenticator.validateUser(Credential[] credentials)</literal>, which performs real authentication of username and password against OrganizationService and portal identity database. Result of successful authentication is object <emphasis>Identity</emphasis>, which is saved to sharedState map under key <literal>exo.security.identity</literal>. More info in <xref linkend="sect-Authentication_Authorization_Intro-authenticatorAndRolesExtractor"/>. </para> - <para> - SharedStateLoginModule assumes that mentioned attributes for username and password are already placed in sharedState map, which was actually done by WCILoginModule. If attributes are not in sharedState map, SharedStateLoginModule is simply ignored (method "login" returns false). + <para> + SharedStateLoginModule assumes that mentioned attributes for username and password are already placed in sharedState map, which was actually done by WCILoginModule. If attributes are not in sharedState map, SharedStateLoginModule is simply ignored (method &quot;login&quot; returns false). </para> - </listitem> - </varlistentry> - <varlistentry> - <term>JbossLoginModule</term> - <listitem> - <para> + </listitem> + </varlistentry> + <varlistentry> + <term>JbossLoginModule</term> + <listitem> + <para> Previous login modules (like <literal>WCILoginModule</literal> and <literal>SharedStateLoginModule</literal>) are useful for authentication flow with WCI ticket. <literal>DefaultLoginModule</literal> (superclass of <literal>JbossLoginModule</literal>) is used for second case (authentication with real password instead of WCI ticket). </para> - <para> + <para> First it checks if Identity object has been already created and saved into <literal>sharedState</literal> map by <literal>SharedStateLoginModule</literal>. If not, then it means that WCI ticket authentication was not successful and so it tries to login with real password of user. It also uses <literal>Authentication.validateUser(Credential[] credentials)</literal> for authentication check. </para> - <para> + <para> In method <literal>JbossLoginModule.commit</literal>, we need to assign our Identity object to <literal>IdentityRegistry</literal>, which will be used later for authorization. We also need to create JAAS principals (<literal>UserPrincipal</literal> and <literal>RolesPrincipal</literal>) and assign them to our authenticated Subject. This is needed for JBoss AS server, so that it can properly recognize name of logged user and their role on JBoss AS level. </para> - </listitem> - </varlistentry> - <varlistentry> - <term>CustomMembershipLoginModule</term> - <listitem> - <para> + </listitem> + </varlistentry> + <varlistentry> + <term>CustomMembershipLoginModule</term> + <listitem> + <para> Special login module, which is disabled (commented) by default. It can be used to add user to some existing group during successful login of this user. Name of group is configurable, by default it is <emphasis>/platform/users</emphasis> group. </para> - <para> + <para> This login module is commented because in normal environment, users are already in <emphasis>/platform/users</emphasis> group. It is useful only for some special setups like read-only LDAP, where groups of ldap user are taken from ldap tree and so that users may not be in <emphasis>/platform/users</emphasis> group, which is needed for successful authorization. </para> - </listitem> - </varlistentry> - </variablelist> - - <section id="sect-Authentication_Authorization_Intro-LoginModuleLocations"> - <title>SVN location of login modules</title> - - <para> + </listitem> + </varlistentry> + </variablelist> + <section id="sect-Authentication_Authorization_Intro-LoginModuleLocations"> + <title>SVN location of login modules</title> + <para> Some modules are specific for portal, but some are used also by eXo JCR and so they are part of eXo core module. </para> - - <itemizedlist> - <listitem> - <para> - <emphasis>PortalLoginModule</emphasis> - is located in JBoss Enterprise Portal Platform sources in <ulink type="http" url="http://anonsvn.jboss.org/repos/gatein/portal/trunk/component/we... + <itemizedlist> + <listitem> + <para> + <emphasis>PortalLoginModule</emphasis> - is located in JBoss Enterprise Portal Platform sources in <ulink url="http://anonsvn.jboss.org/repos/gatein/portal/trunk/component/we... type="http">http://anonsvn.jboss.org/repos/gatein/portal/tru... </para> - </listitem> - - <listitem> - <para> - <emphasis>SharedStateLoginModule, JbossLoginModule</emphasis> - these are located in eXo core sources in <ulink type="http" url="http://anonsvn.jboss.org/repos/exo-jcr/core/trunk/exo.core.comp... + </listitem> + <listitem> + <para> + <emphasis>SharedStateLoginModule, JbossLoginModule</emphasis> - these are located in eXo core sources in <ulink url="http://anonsvn.jboss.org/repos/exo-jcr/core/trunk/exo.core.comp... type="http">http://anonsvn.jboss.org/repos/exo-jcr/core/trun... </para> - </listitem> - - <listitem> - <para> - <emphasis>CustomMembershipLoginModule</emphasis> - located in JBoss Enterprise Portal Platform sources in module for identity integration - <ulink type="http" url="http://anonsvn.jboss.org/repos/gatein/portal/trunk/component/id... - </para> - </listitem> - </itemizedlist> - </section> - </section> -<!-- Ending section with existing login modules --> - <section id="sect-Authentication_Authorization_Intro-createNewLM"> - <title>Creating your own login module</title> - + </listitem> + <listitem> <para> + <emphasis>CustomMembershipLoginModule</emphasis> - located in JBoss Enterprise Portal Platform sources in module for identity integration - <ulink url="http://anonsvn.jboss.org/repos/gatein/portal/trunk/component/id... type="http">http://anonsvn.jboss.org/repos/gatein/portal/tru... + </para> + </listitem> + </itemizedlist> + </section> + </section> +<!-- Ending section with existing login modules --> <section id="sect-Authentication_Authorization_Intro-createNewLM"> + <title>Creating your own login module</title> + <para> Before creating your own login module, it is recommended that you study the source code of existing login modules to better understand the JAAS authentication process. You need to have good knowledge so that you can properly decide where your login module should be placed and if you need to replace some existing login modules or simply attach your own module to existing chain. </para> - - <para> + <para> We have actually two levels of authentication and overall result of JAAS authentication should properly handle both these cases: </para> - - <itemizedlist> - <listitem> - <para> + <itemizedlist> + <listitem> + <para> Authentication on application server level </para> - </listitem> - - <listitem> - <para> + </listitem> + <listitem> + <para> Authentication on JBoss Enterprise Portal Platform level </para> - </listitem> - </itemizedlist> - - <formalpara id="form-Authentication_Authorization_Intro-authenticationAppServerLevel"> - <title>Authentication on application server level</title> - - <para> - Application server needs to properly recognize that user is successfully logged and it has assigned his JAAS roles. Unfortunately this part is not standardized and is specific for each AS. For example in JBoss AS, you need to ensure that JAAS Subject has assigned principal with username (UserPrincipal) and also RolesPrincipal, which has name "Roles" and it contains list of JAAS roles. This part is actually done in <code>JbossLoginModule.commit()</code>. In Tomcat, this flow is little different, which means Tomcat has it is own <literal>TomcatLoginModule</literal>. + </listitem> + </itemizedlist> + <formalpara id="form-Authentication_Authorization_Intro-authenticationAppServerLevel"> + <title>Authentication on application server level</title> + <para> + Application server needs to properly recognize that user is successfully logged and it has assigned his JAAS roles. Unfortunately this part is not standardized and is specific for each AS. For example in JBoss AS, you need to ensure that JAAS Subject has assigned principal with username (UserPrincipal) and also RolesPrincipal, which has name &quot;Roles&quot; and it contains list of JAAS roles. This part is actually done in <code>JbossLoginModule.commit()</code>. In Tomcat, this flow is little different, which means Tomcat has it is own <literal>TomcatLoginModule</literal>. </para> - </formalpara> - - <para> - After successful authentication, user needs to be at least in JAAS role "users" because this role is declared in web.xml as you saw above. JAAS roles are extracted by special algorithm from JBoss Enterprise Portal Platform memberships. See below in section with RolesExtractor. + </formalpara> + <para> + After successful authentication, user needs to be at least in JAAS role &quot;users&quot; because this role is declared in web.xml as you saw above. JAAS roles are extracted by special algorithm from JBoss Enterprise Portal Platform memberships. See below in section with RolesExtractor. </para> - - - <formalpara id="form-Authentication_Authorization_Intro-authenticationGateInServerLevel"> - <title>Authentication on JBoss Enterprise Portal Platform level</title> - - <para> + <formalpara id="form-Authentication_Authorization_Intro-authenticationGateInServerLevel"> + <title>Authentication on JBoss Enterprise Portal Platform level</title> + <para> Login process needs to create special object <literal>org.exoplatform.services.security.Identity</literal> and register this object into JBoss Enterprise Portal Platform component <literal>IdentityRegistry</literal>. This Identity object should encapsulate username of authenticated user, Memberships of this user and also JAAS roles. Identity object can be easily created with interface <literal>Authenticator</literal> as can be seen below. </para> - </formalpara> - - <para> + </formalpara> + <para> So have this in mind, if you will extend or replace existing login modules. </para> - </section> -<!-- Ending section with your own login module --> - <section id="sect-Authentication_Authorization_Intro-authenticatorAndRolesExtractor"> - <title>Authenticator and RolesExtractor</title> - - <para> + </section> +<!-- Ending section with your own login module --> <section id="sect-Authentication_Authorization_Intro-authenticatorAndRolesExtractor"> + <title>Authenticator and RolesExtractor</title> + <para> Authenticator is important component in authentication process. Actually interface <emphasis>org.exoplatform.services.security.Authenticator</emphasis> looks like this: </para> -<programlisting language="Java" role="Java"> + <programlisting language="Java" role="Java"> <![CDATA[ public interface Authenticator { @@ -390,34 +348,30 @@ } ]]> </programlisting> - <para> + <para> Method <emphasis>validateUser</emphasis> is used to check whether given credentials (username and password) are really valid. So it performs real authentication. It returns back username if credentials are correct. Otherwise LoginException is thrown. </para> - - <para> + <para> Method <emphasis>createIdentity</emphasis> is used to create instance of object <emphasis>org.exoplatform.services.security.Identity</emphasis>, which encapsulates all important information about single user like: </para> - - <itemizedlist> - <listitem> - <para> + <itemizedlist> + <listitem> + <para> username </para> - </listitem> - - <listitem> - <para> + </listitem> + <listitem> + <para> set of Memberships (MembershipEntry objects) which user belongs to. <emphasis>Membership</emphasis> is object, which contains information about <emphasis>membershipType</emphasis> (manager, member, validator, ... ) and about <emphasis>group</emphasis> (/platform/users, /platform/administrators, /partners, /organization/management/executiveBoard, ... ). </para> - </listitem> - - <listitem> - <para> + </listitem> + <listitem> + <para> Set of Strings with JAAS roles of given user. JAAS roles are simple Strings, which are mapped from MembershipEntry objects. There is another special component <emphasis>org.exoplatform.services.security.RolesExtractor</emphasis>, which is used to map JAAS roles from MembershipEntry objects. RolesExtractor interface looks like this: </para> - </listitem> - </itemizedlist> -<programlisting language="Java" role="Java"> + </listitem> + </itemizedlist> + <programlisting language="Java" role="Java"> <![CDATA[ public interface RolesExtractor { @@ -433,103 +387,83 @@ } ]]> </programlisting> - <para> - Default implementation <emphasis>DefaultRolesExtractorImpl</emphasis> is based on special algorithm, which uses name of role from the root of the group (for example for role "/organization/management/something" we have JAAS role "organization"). Only exception is group "platform" where we use second level as name of group. For example from group "/platform/users" we have JAAS role "users". + <para> + Default implementation <emphasis>DefaultRolesExtractorImpl</emphasis> is based on special algorithm, which uses name of role from the root of the group (for example for role &quot;/organization/management/something&quot; we have JAAS role &quot;organization&quot;). Only exception is group &quot;platform&quot; where we use second level as name of group. For example from group &quot;/platform/users&quot; we have JAAS role &quot;users&quot;. </para> - - <para> + <para> <emphasis role="bold">Example: </emphasis> We have user <emphasis>root</emphasis>, which has memberships <emphasis>member:/platform/users</emphasis>, <emphasis>manager:/platform/administrators</emphasis>, <emphasis>validator:/platform/managers</emphasis>, <emphasis>member:/partners</emphasis>, <emphasis>member:/customers/acme</emphasis>, <emphasis>member:/organization/management/board</emphasis>. In this case we will have JAAS roles: <emphasis>users</emphasis>, <emphasis>administrators</emphasis>, <emphasis>managers</emphasis>, <emphasis>partners</emphasis>, <emphasis>customers</emphasis>, <emphasis>organization</emphasis>. </para> - - <para> + <para> Default implementation of Authenticator is <emphasis>OrganizationAuthenticatorImpl</emphasis>, which is implementation based on <emphasis>OrganizationService</emphasis>. See <xref linkend="sect-Reference_Guide-Organization_API"/> . </para> - - <para> + <para> You can override default implementation of mentioned interfaces Authenticator and RolesExtractor if default behavior is not suitable for your needs. Consult documentation of <emphasis>eXo kernel</emphasis> for more info. </para> - </section> -<!-- Ending section Authenticator and RolesExtractor --> - </section> -<!-- Ending section with login modules --> - <section id="sect-Authentication_Authorization_Intro-differentAuthWorkflows"> - <title>Different authentication workflows</title> - - <section id="sect-Authentication_Authorization_Intro-RememberMeAuthentication"> - <title>RememberMe authentication</title> - - <para> - In default login dialog, you can notice that there is "Remember my login" checkbox, which users can use to persist their login on his workstation. Default validity period of RememberMe cookie is one day (it is configurable), and so user can be logged for whole day before he need to re-authenticate again with his credentials. + </section> +<!-- Ending section Authenticator and RolesExtractor --> </section> +<!-- Ending section with login modules --> <section id="sect-Authentication_Authorization_Intro-differentAuthWorkflows"> + <title>Different authentication workflows</title> + <section id="sect-Authentication_Authorization_Intro-RememberMeAuthentication"> + <title>RememberMe authentication</title> + <para> + In default login dialog, you can notice that there is &quot;Remember my login&quot; checkbox, which users can use to persist their login on his workstation. Default validity period of RememberMe cookie is one day (it is configurable), and so user can be logged for whole day before he need to re-authenticate again with his credentials. </para> - - <section id="sect-Authentication_Authorization_Intro-RememberMeAuthentication-howDoesItWork"> - <title>How does it work</title> - - <itemizedlist> - <listitem> - <para> - User checks the checkbox "Remember my login" on login screen of JBoss Enterprise Portal Platform . Then submits the form. + <section id="sect-Authentication_Authorization_Intro-RememberMeAuthentication-howDoesItWork"> + <title>How does it work</title> + <itemizedlist> + <listitem> + <para> + User checks the checkbox &quot;Remember my login&quot; on login screen of JBoss Enterprise Portal Platform . Then submits the form. </para> - </listitem> - - <listitem> - <para> - HTTP request like <uri>http://localhost:8080/portal/login?initialURI=/portal/classic&amp;username=root&amp;password=gtn&amp;rememberme=true</uri> is sent to server. + </listitem> + <listitem> + <para> + HTTP request like <ulink url="http://localhost:8080/portal/login?initialURI=/portal/classic&amp;amp;username=root&amp;amp;password=gtn&amp;amp;rememberme=true"/> is sent to server. </para> - </listitem> - - <listitem> - <para> + </listitem> + <listitem> + <para> Request is processed by PortalLoginController servlet. Servlet obtains instance of <emphasis>RemindPasswordTokenService</emphasis> and save user credentials into JCR. It generates and returns special token (key) for later use. Then it creates cookie called <emphasis>RememberMe</emphasis> and use returned token as value of cookie. </para> - </listitem> - </itemizedlist> - </section> - - <section id="sect-Authentication_Authorization_Intro-RememberMeAuthentication-reauthentication"> - <title>Reauthentication</title> - - <itemizedlist> - <listitem> - <para> - After some time, user wants to re-authenticate. Let's assume that his HTTP Session is already expired but his RememberMe cookie is still active. + </listitem> + </itemizedlist> + </section> + <section id="sect-Authentication_Authorization_Intro-RememberMeAuthentication-reauthentication"> + <title>Reauthentication</title> + <itemizedlist> + <listitem> + <para> + After some time, user wants to re-authenticate. Let&apos;s assume that his HTTP Session is already expired but his RememberMe cookie is still active. </para> - </listitem> - - <listitem> - <para> - User send HTTP request to some portal page (<filename>http://localhost:8080/portal/classic</filename> ). + </listitem> + <listitem> + <para> + User send HTTP request to some portal page (<ulink url="http://localhost:8080/portal/classic"/>). </para> - </listitem> - - <listitem> - <para> + </listitem> + <listitem> + <para> There is special HTTP Filter <emphasis role="bold">RememberMeFilter</emphasis> configured in web.xml, which checks RememberMe cookie and then it retrieves credentials of user from RemindPasswordTokenService. Now filter redirects request to PortalLoginController and authentication process goes in same way as for normal FORM based authentication. </para> - </listitem> - </itemizedlist> - </section> - - <section id="sect-Authentication_Authorization_Intro-RememberMeAuthentication-RemindPasswordTokenService"> - <title>RemindPasswordTokenService</title> - - <para> - This is special service used during RememberMe authentication workflow. It is configurable in file <filename>deploy/gatein.ear/02portal.war/WEB-INF/conf/common/remindpwd-configuration.xml</filename> . For more info, look at section <xref linkend="sect-Reference_Guide-Authentication_Token_Configuration" /> + </listitem> + </itemizedlist> + </section> + <section id="sect-Authentication_Authorization_Intro-RememberMeAuthentication-RemindPasswordTokenService"> + <title>RemindPasswordTokenService</title> + <para> + This is special service used during RememberMe authentication workflow. It is configurable in file <filename>deploy/gatein.ear/02portal.war/WEB-INF/conf/common/remindpwd-configuration.xml</filename> . For more info, look at section <xref linkend="sect-Reference_Guide-Authentication_Token_Configuration"/> </para> - - <para> - Another thing is that you can encrypt passwords before store them into JCR. More info is in section <xref linkend="sect-Reference_Guide-Authentication_and_Identity-Password_Encryption" />. + <para> + Another thing is that you can encrypt passwords before store them into JCR. More info is in section <xref linkend="sect-Reference_Guide-Authentication_and_Identity-Password_Encryption"/>. </para> - </section> - </section> - - <section id="sect-Authentication_Authorization_Intro-BASICAuthentication"> - <title>BASIC authentication</title> - - <para> + </section> + </section> + <section id="sect-Authentication_Authorization_Intro-BASICAuthentication"> + <title>BASIC authentication</title> + <para> JBoss Enterprise Portal Platform is using FORM based authentication by default but it is not a problem with switch to different authentication type like BASIC. Only needed thing is to configure it properly in <filename>deploy/gatein.ear/02portal.war/WEB-INF/web.xml</filename> like this: </para> -<programlisting language="XML" role="XML"> + <programlisting language="XML" role="XML"> <![CDATA[ <!-- <login-config> @@ -547,164 +481,134 @@ </login-config ]]> </programlisting> - <para> + <para> In this case user will see login dialog from browser instead of JBoss Enterprise Portal Platform login.jsp page. JAAS authentication will be performed with real credentials of user (<emphasis>root</emphasis>/<emphasis>gtn</emphasis>). WCI ticket is not used with BASIC authentication. </para> - </section> - - <section id="sect-Authentication_Authorization_Intro-ClusterLogin"> - <title>Cluster login</title> - - <para> - JBoss Enterprise Portal Platform supports automatic login propagation in cluster environment. Cluster login relies on HTTP session replication. It's useful for situations like this: + </section> + <section id="sect-Authentication_Authorization_Intro-ClusterLogin"> + <title>Cluster login</title> + <para> + JBoss Enterprise Portal Platform supports automatic login propagation in cluster environment. Cluster login relies on HTTP session replication. It&apos;s useful for situations like this: </para> - - <procedure> - <step> - <para> + <procedure> + <step> + <para> You have Apache loadbalancer and two portal nodes <emphasis>node1</emphasis> and <emphasis>node2</emphasis> </para> - </step> - - <step> - <para> + </step> + <step> + <para> User will send request to loadbalancer and he will be redirected to <emphasis>node1</emphasis>. All his requests will be then processed on <emphasis>node1</emphasis> (sticky session). </para> - </step> - - <step> - <para> + </step> + <step> + <para> User login on loadbalancer (which is redirected to <emphasis>node1</emphasis>) </para> - </step> - - <step> - <para> + </step> + <step> + <para> node1 is killed </para> - </step> - - <step> - <para> - User will send another HTTP request. He will now be redirected to <emphasis>node2</emphasis> because <emphasis>node1</emphasis> is killed. Now user will be automatically logged on <emphasis>node2</emphasis> as well thanks to session replication, because he still has same HTTP session, which was replicated from <emphasis>node1</emphasis> to <emphasis>node2</emphasis>. So end user shouldn't recognize any change even if his work is now done on different node of cluster. + </step> + <step> + <para> + User will send another HTTP request. He will now be redirected to <emphasis>node2</emphasis> because <emphasis>node1</emphasis> is killed. Now user will be automatically logged on <emphasis>node2</emphasis> as well thanks to session replication, because he still has same HTTP session, which was replicated from <emphasis>node1</emphasis> to <emphasis>node2</emphasis>. So end user shouldn&apos;t recognize any change even if his work is now done on different node of cluster. </para> - </step> - </procedure> - - <para> + </step> + </procedure> + <para> This login workflow works thanks to <emphasis>PortalLoginModule</emphasis>, which is able to save special attribute into HTTP session as flag that user is already logged. Then reauthentication on <emphasis>node2</emphasis> is working thanks to servlet filter <emphasis>ClusteredSSOFilter</emphasis>, which is able to automatically trigger programmatic authentication. </para> - - <note> - <title>Note</title> - <para> + <note> + <title>Note</title> + <para> <literal>ClusteredSSOFilter</literal> is using proprietary JBossWeb API for trigger programmatic authentication and so it is working only on JBoss AS. It is not working on other servers like Tomcat or Jetty. </para> - </note> - - <para> - There is also possibility for integration with JBoss clustered SSO valve (See <xref linkend="sect-Reference_Guide-SSO_Single_Sign_On_-Enabling_SSO_using_JBoss_SSO_Valve" />). + </note> + <para> + There is also possibility for integration with JBoss clustered SSO valve (See <xref linkend="sect-Reference_Guide-SSO_Single_Sign_On_-Enabling_SSO_using_JBoss_SSO_Valve"/>). </para> - </section> - - <section id="sect-Authentication_Authorization_Intro-SSOLogin"> - <title>SSO login</title> - - <para> + </section> + <section id="sect-Authentication_Authorization_Intro-SSOLogin"> + <title>SSO login</title> + <para> JBoss Enterprise Portal Platform also supports integration with couple of well-known SSO frameworks (CAS, JOSSO, OpenSSO). When user wants login, he is not redirected to portal login form but to SSO server login form. After successful login with SSO server, he gains ticket represented by special cookie (name of cookie differs for each SSO server). Then user is redirected back to JBoss Enterprise Portal Platform, where we need to perform agent validation of SSO ticket against SSO server. We still need to create Identity object and bind it to IdentityRegistry (this is same as in default authentication), which is done thanks to Authenticator component. </para> - - <para> - In other words, you need to ensure that users, which are logged successfully through SSO, needs to be also in JBoss Enterprise Portal Platform identity database because SSO server is used only for authentication, but authorization is handled completely by JBoss Enterprise Portal Platform, which assumes that user exists in portal DB. If users are not in DB, Identity object won't be created and you will have 403 Forbidden errors even if you authenticate successfully. For details about SSO integration, see <xref linkend="sect-Reference_Guide-SSO_Single_Sign_On" />. + <para> + In other words, you need to ensure that users, which are logged successfully through SSO, needs to be also in JBoss Enterprise Portal Platform identity database because SSO server is used only for authentication, but authorization is handled completely by JBoss Enterprise Portal Platform, which assumes that user exists in portal DB. If users are not in DB, Identity object won&apos;t be created and you will have 403 Forbidden errors even if you authenticate successfully. For details about SSO integration, see <xref linkend="sect-Reference_Guide-SSO_Single_Sign_On"/>. </para> - - <para> + <para> Same applies for SPNEGO authentication (See <xref linkend="sect-Reference_Guide-SSO_Single_Sign_On_-SPNEGO_Simple_and_Protected_GSSAPI_Negotiation_Mechanism"/>). In this case, you need to ensure that your Kerberos users are also created in JBoss Enterprise Portal Platform database. </para> - </section> - </section> -<!-- Ending section different authentication workflows --> - <section id="sect-Authentication_Authorization_Intro-authorization"> - <title>Authorization overview</title> - - <para> + </section> + </section> +<!-- Ending section different authentication workflows --> <section id="sect-Authentication_Authorization_Intro-authorization"> + <title>Authorization overview</title> + <para> In previous section, we learned about JAAS authentication and about login modules. So we know that result of authentication are: </para> - - <itemizedlist> - <listitem> - <para> + <itemizedlist> + <listitem> + <para> JAAS Subject with principals for username (UserPrincipal) and for JAAS roles (RolesPrincipal). </para> - </listitem> - - <listitem> - <para> + </listitem> + <listitem> + <para> Identity object, which encapsulates username, all memberships and all JAAS roles. This Identity object is bound to IdentityRegistry component. </para> - </listitem> - </itemizedlist> - - <para> + </listitem> + </itemizedlist> + <para> Authorization in JBoss Enterprise Portal Platform actually happens on two levels: </para> - - <section id="sect-Authentication_Authorization_Intro-servletContainerAuthorization"> - <title>Servlet container authorization</title> - - <para> + <section id="sect-Authentication_Authorization_Intro-servletContainerAuthorization"> + <title>Servlet container authorization</title> + <para> First round of authorization is servlet container authorization based on secured URL from <filename>web.xml</filename>. We saw above in web.xml snippet that secured URL are accessible only for users from role <emphasis>users</emphasis>: </para> -<programlisting language="XML" role="XML"><![CDATA[ + <programlisting language="XML" role="XML"><![CDATA[ <auth-constraint> <role-name>users</role-name> </auth-constraint>]]></programlisting> - <para> - This actually means that our user needs to be in JBoss Enterprise Portal Platform role <emphasis>/platform/users</emphasis> (For details see <xref linkend="sect-Authentication_Authorization_Intro-authenticatorAndRolesExtractor" />). In other words, if we successfully authenticate but our user is not in group <emphasis>/platform/users</emphasis>, then it means that he is not in JAAS role <emphasis>users</emphasis>, which in next turn means that he will have authorization error <emphasis role="bold">403 Forbidden</emphasis> thrown by servlet container. + <para> + This actually means that our user needs to be in JBoss Enterprise Portal Platform role <emphasis>/platform/users</emphasis> (For details see <xref linkend="sect-Authentication_Authorization_Intro-authenticatorAndRolesExtractor"/>). In other words, if we successfully authenticate but our user is not in group <emphasis>/platform/users</emphasis>, then it means that he is not in JAAS role <emphasis>users</emphasis>, which in next turn means that he will have authorization error <emphasis role="bold">403 Forbidden</emphasis> thrown by servlet container. </para> - - <para> + <para> You can change the behavior and possibly add some more <emphasis>auth-constraint</emphasis> elements into <filename>web.xml</filename>. However this protection of resources based on web.xml is not standard JBoss Enterprise Portal Platform way and it is mentioned here mainly for illustration purposes. </para> - </section> - - <section id="sect-Authentication_Authorization_Intro-gateInAuthorization"> - <title>Portal level authorization</title> - - <para> - Second round of authorization is based on component <emphasis role="bold">UserACL</emphasis> (See <xref linkend="chap-Reference_Guide-Portal_Default_Permission_Configuration" />). We can declare access and edit permissions for portals, pages and/or portlets. UserACL is then used to check if our user has particular permissions to access or edit specified resource. Important object with information about roles of our user is mentioned <emphasis>Identity</emphasis> object created during JAAS authentication. + </section> + <section id="sect-Authentication_Authorization_Intro-gateInAuthorization"> + <title>Portal level authorization</title> + <para> + Second round of authorization is based on component <emphasis role="bold">UserACL</emphasis> (See <xref linkend="chap-Reference_Guide-Portal_Default_Permission_Configuration"/>). We can declare access and edit permissions for portals, pages and/or portlets. UserACL is then used to check if our user has particular permissions to access or edit specified resource. Important object with information about roles of our user is mentioned <emphasis>Identity</emphasis> object created during JAAS authentication. </para> - - <para> + <para> Authorization on portal level looks like this: </para> - - <itemizedlist> - <listitem> - <para> + <itemizedlist> + <listitem> + <para> user send HTTP request to some URL in portal </para> - </listitem> - - <listitem> - <para> + </listitem> + <listitem> + <para> HTTP request is processed through <literal>SetCurrentIdentityFilter</literal>, which is declared in <filename>deploy/gatein.ear/02portal.war/WEB-INF/web.xml</filename>. </para> - </listitem> - - <listitem> - <para> + </listitem> + <listitem> + <para> SetCurrentIdentityFilter reads username of current user from <emphasis>HttpServletRequest.getRemoteUser()</emphasis>. Then it looks for Identity of this user in IdentityRegistry, where Identity has been saved during authentication. Found Identity is then encapsulated into <emphasis role="bold">ConversationState</emphasis> object and bound into ThreadLocal variable. </para> - </listitem> - - <listitem> - <para> + </listitem> + <listitem> + <para> UserACL is able to obtain Identity of current user from method <emphasis>UserACL.getIdentity()</emphasis>, which simply calls <emphasis>ConversationState.getCurrent().getIdentity()</emphasis> for find current Identity bound to ThreadLocal. Now UserACL has identity of user and so that it can performs any security checks. </para> - </listitem> - </itemizedlist> - </section> - </section> -<!-- Ending section Authorization overview --> - </section> + </listitem> + </itemizedlist> + </section> + </section> +<!-- Ending section Authorization overview --></section> Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/CoreOrganizationInitializer.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/CoreOrganizationInitializer.xml 2012-07-05 19:41:59 UTC (rev 8774) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/CoreOrganizationInitializer.xml 2012-07-06 05:00:36 UTC (rev 8775) @@ -6,7 +6,7 @@ <section id="sect-CoreOrganizationInitializer"> <title><remark>BZ#801424 </remark>Create Users and Groups without Organization API</title> <para>CoreOrganizationInitializer is a plug-in that creates users and groups outside the portal user interface, without the Organization API. The plug-in performs the function of the Organization API with regard to triggering listeners for users and groups at creation time. The plug-in prevents issues with missing JCR objects, resulting from incorrectly provisioned users and groups.</para> - <para>The plug-in is particularly useful when using the Site Publisher add-on, and directly adding users or groups to a LDAP server through ldif files, or into a database using SQL. </para> + <para>The plug-in is particularly useful when using the Site Publisher add-on, and directly adding users or groups to a LDAP server through LDIF files, or into a database using SQL. </para> <section> <title>Enable Initializer</title> <para>The initializer is disabled by default. To activate it, uncomment the block containing the path to the <filename>initializer-configuration.xml</filename> file in <filename><replaceable>EPP_HOME</replaceable>/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/conf/configuration.xml</filename>. @@ -21,8 +21,8 @@ <para>There are a number of operations supported by CoreOrganizationInitializer.</para> <table frame="all" pgwide="1" id="table-Supported_Operations"> <title>Supported Operations</title> - <tgroup colsep="1" cols="3"> - <colspec colname="c1"/> + <tgroup cols="3" colsep="1"> + <colspec colname="c1" colwidth=""/> <colspec colname="c2"/> <colspec colname="c3"/> <thead> @@ -40,13 +40,13 @@ <entry>username</entry> <entry> <para>String value containing the user name to query.</para> - </entry> + </entry> </row> <row> <entry/> <entry>checkFolders</entry> <entry> - <para>Boolean value (<literal>true | false</literal>) used by <parameter>treatUser</parameter>, <parameter>treatGroup</parameter>, and <parameter>launchAll</parameter> to control when listeners are triggered for a user or group.</para> + <para>Boolean value (<literal>true | false</literal>) used by <parameter>treatUser</parameter>, <parameter>treatGroup</parameter>, and <parameter>launchAll</parameter> to control when listeners are triggered for a user or group.</para> <para>Detects whether JCR folders are already present for the specified user, or group (in the case of <parameter>launchAll</parameter>). The presence of the folder indicates to the operation that listeners are already triggered for the user or group.</para> <para>If set to true (recommended), listeners will not be triggered for the user.</para> <para>If set to false, all listeners are re-triggered for the specified user or group.</para> @@ -56,8 +56,11 @@ <entry> <command>treatGroup(groupName, checkFolders)</command> </entry> - <entry>groupName</entry> <entry> + <para>groupName</para> + <para>(See checkFolders above for usage.)</para> + </entry> + <entry> <para>String value containing the group name to query.</para> </entry> </row> @@ -65,20 +68,16 @@ <entry> <command>launchAll(checkFolders)</command> </entry> - <entry/> + <entry>See checkFolders above for usage.</entry> <entry> <para>Finds all users and groups and triggers <parameter>treatUser</parameter> and <parameter>treatGroup</parameter> as appropriate.</para> <para>Read the following advice for <parameter>checkFolders</parameter> when using this operation. </para> + <warning> + <para>To avoid significant performance impacts, only use <parameter>checkFolders=true</parameter> for this operation.</para> + <para>If this operation is used with <parameter>checkFolders=false</parameter>, all listeners will be restarted for all users and groups. This will have a definite impact on performance.</para> + </warning> </entry> </row> - <row> - <entry/> - <entry>checkFolders</entry> - <entry> - <para>To avoid significant performance impacts, only use <parameter>checkFolder=true</parameter> for this operation.</para> - <para>If this operation is used with <parameter>checkFolders=false</parameter>, all listeners will be restarted for all users and groups. This will have a definite impact on performance.</para> - </entry> - </row> </tbody> </tgroup> </table> Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/LDAP.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/LDAP.xml 2012-07-05 19:41:59 UTC (rev 8774) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/LDAP.xml 2012-07-06 05:00:36 UTC (rev 8775) @@ -81,117 +81,113 @@ <procedure id="proc-Reference_Guide-LDAP_Integration-LDAP_Set_Up"> <title>LDAP Set Up</title> <step> - <substeps> - <step> - <para> + <para> Install your <application>LDAP</application> server by following the installation instructions provided for the product you are using. </para> - <para> + <para> If you are installing the <application>Red Hat Directory Server</application> (RHDS), you should refer to the Installation Guide at <ulink url="http://docs.redhat.com/docs/en-US/Red_Hat_Directory_Server/inde... type="http"/>. </para> - <para> - If you are using a third party directory server (<application>OpenDS</application>, <application>OpenLDAP</application> or <application>Miscrosoft Active Directory</application> (MSAD)), refer the appropriate documentation for that product. + <para> + If you are using a third party directory server (<application>OpenDS</application>, <application>OpenLDAP</application> or <application>Microsoft Active Directory</application> (MSAD)), refer the appropriate documentation for that product. </para> - <para> + <para> The following values provide an example of working configuration settings for the different Directory Servers: </para> - <table> - <title/> - <tgroup cols="8"> - <colspec colname="1"/> - <colspec colname="2"/> - <colspec colname="3"/> - <colspec colname="4"/> - <colspec colname="5"/> - <colspec colname="6"/> - <colspec colname="7"/> - <colspec colname="8"/> - <spanspec namest="2" nameend="8" spanname="vspan"/> - <thead> - <row> - <entry> Directory Server </entry> - <entry spanname="vspan"> Value </entry> - </row> - </thead> - <tbody> - <row> - <entry/> - <entry> - <emphasis role="bold">root user Distinguished Name (DN)</emphasis> - </entry> - <entry> - <emphasis role="bold">Password</emphasis> - </entry> - <entry> - <emphasis role="bold">Port</emphasis> - </entry> - <entry> - <emphasis role="bold">Admin Port</emphasis> - </entry> - <entry> - <emphasis role="bold">Base DN</emphasis> - </entry> - <entry> - <emphasis role="bold">Database Population</emphasis> - </entry> - <entry> - <emphasis role="bold">SSO/TLS</emphasis> - </entry> - </row> - <row> - <entry> - <emphasis role="bold">RHDS and OpenDS</emphasis> - </entry> - <entry> cn=Directory Manager </entry> - <entry> password </entry> - <entry> 1389 </entry> - <entry> 4444 </entry> - <entry> dc=example,dc=com </entry> - <entry> &quot;Only create the base entry&quot; </entry> - <entry> no SSO, no TLS </entry> - </row> - <row> - <entry> - <emphasis role="bold">MSAD</emphasis> - </entry> - <entry> CN=Users </entry> - <entry/> - <entry/> - <entry/> - <entry/> - <entry/> - <entry/> - </row> - <row> - <entry> - <emphasis role="bold">OpenLDAP</emphasis> - </entry> - <entry> cn=Manager,dc=example,dc=com </entry> - <entry> secret </entry> - <entry> 1389 </entry> - <entry/> - <entry> dc=example,dc=com </entry> - <entry/> - <entry/> - </row> - </tbody> - </tgroup> - </table> - <para> + <table> + <title/> + <tgroup cols="8"> + <colspec colname="1"/> + <colspec colname="2"/> + <colspec colname="3"/> + <colspec colname="4"/> + <colspec colname="5"/> + <colspec colname="6"/> + <colspec colname="7"/> + <colspec colname="8"/> + <spanspec namest="2" nameend="8" spanname="vspan"/> + <thead> + <row> + <entry> Directory Server </entry> + <entry spanname="vspan"> Value </entry> + </row> + </thead> + <tbody> + <row> + <entry/> + <entry> + <emphasis role="bold">root user Distinguished Name (DN)</emphasis> + </entry> + <entry> + <emphasis role="bold">Password</emphasis> + </entry> + <entry> + <emphasis role="bold">Port</emphasis> + </entry> + <entry> + <emphasis role="bold">Admin Port</emphasis> + </entry> + <entry> + <emphasis role="bold">Base DN</emphasis> + </entry> + <entry> + <emphasis role="bold">Database Population</emphasis> + </entry> + <entry> + <emphasis role="bold">SSO/TLS</emphasis> + </entry> + </row> + <row> + <entry> + <emphasis role="bold">RHDS and OpenDS</emphasis> + </entry> + <entry> cn=Directory Manager </entry> + <entry> password </entry> + <entry> 1389 </entry> + <entry> 4444 </entry> + <entry> dc=example,dc=com </entry> + <entry> &quot;Only create the base entry&quot; </entry> + <entry> no SSO, no TLS </entry> + </row> + <row> + <entry> + <emphasis role="bold">MSAD</emphasis> + </entry> + <entry> CN=Users </entry> + <entry/> + <entry/> + <entry/> + <entry/> + <entry/> + <entry/> + </row> + <row> + <entry> + <emphasis role="bold">OpenLDAP</emphasis> + </entry> + <entry> cn=Manager,dc=example,dc=com </entry> + <entry> secret </entry> + <entry> 1389 </entry> + <entry/> + <entry> dc=example,dc=com </entry> + <entry/> + <entry/> + </row> + </tbody> + </tgroup> + </table> + <para> These, and other appropriate settings, should be adjusted to suit your circumstances. </para> - </step> - <step> - <para> + </step> + <step> + <para> <emphasis role="bold">Optional</emphasis>: Import an <filename>ldif</filename> file and populate the Directory Server. </para> - </step> - <step> - <para> + </step> + <step> + <para> Start the Directory Server. </para> - </step> - </substeps> </step> </procedure> <section id="sect-Reference_Guide_eXo_JCR_1.14-LDAP_Integration-LDAP_in_Read-only_Mode"> Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/PredefinedUserConfiguration.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/PredefinedUserConfiguration.xml 2012-07-05 19:41:59 UTC (rev 8774) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/PredefinedUserConfiguration.xml 2012-07-06 05:00:36 UTC (rev 8775) @@ -1,104 +1,81 @@ -<?xml version='1.0' encoding='utf-8' ?> +<?xml version='1.0' encoding='UTF-8'?> <!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!ENTITY % BOOK_ENTITIES SYSTEM "Reference_Guide.ent"> %BOOK_ENTITIES; ]> <section id="sect-Reference_Guide-Predefined_User_Configuration"> - <title>Predefined User Configuration</title> - <section id="sect-Reference_Guide-Predefined_User_Configuration-Overview"> - <title>Overview</title> - <para> - The initial Organization configuration should be specified by editing the content of <filename><replaceable>JBOSS_HOME</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/02portal.war:/WEB-INF/conf/organization/organization-configuration.xml</filename>. This file uses the portal XML configuration schema. It lists several configuration plug-ins. - </para> - - </section> - - <section id="sect-Reference_Guide-Predefined_User_Configuration-Plugin_for_adding_users_groups_and_membership_types"> - <title>Plugin for adding users, groups and membership types</title> - <para> - The plugin type <literal>org.exoplatform.services.organization.OrganizationDatabaseInitializer</literal> is used to specify a list of membership types, a list of groups and a list of users to be created. - </para> - <para> - The <emphasis role="bold">checkDatabaseAlgorithm</emphasis> initialization parameter determines how the database update is performed. - </para> - <para> - If its value is set to <emphasis role="bold">entry</emphasis> it means that each user, group and membership listed in the configuration is checked each time JBoss Enterprise Portal Platform is started. If the entry does not yet exist in the database, it is created. - </para> - <para> - If <emphasis role="bold">checkDatabaseAlgorithm</emphasis> parameter value is set to <emphasis role="bold">empty</emphasis>, the configuration data will be updated to the database only if the database is empty. - </para> - - </section> - - <section id="sect-Reference_Guide-Predefined_User_Configuration-Membership_types"> - <title>Membership types</title> - <para> - The predefined membership types are specified in the <emphasis role="bold">membershipType</emphasis> field of the <emphasis role="bold">OrganizationConfig</emphasis> plugin parameter. - </para> - <note> - <para> - See <literal>02portal.war:/WEB-INF/conf/organization/organization-configuration.xml</literal> for the full content. - </para> - - </note> - -<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_PredefinedUserConfiguration/default98.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - - </section> - - <section id="sect-Reference_Guide-Predefined_User_Configuration-Groups"> - <title>Groups</title> - <para> - The predefined groups are specified in the <emphasis role="bold">group</emphasis> field of the <emphasis role="bold">OrganizationConfig</emphasis> plugin parameter. - </para> - <note> - <para> - See <literal>02portal.war:/WEB-INF/conf/organization/organization-configuration.xml</literal> for the full content. - </para> - - </note> - -<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_PredefinedUserConfiguration/default99.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - - </section> - - <section id="sect-Reference_Guide-Predefined_User_Configuration-Users"> - <title>Users</title> - <para> - The predefined users are specified in the <emphasis role="bold">user</emphasis> field of the <emphasis role="bold">OrganizationConfig</emphasis> plugin parameter. - </para> - <note> - <para> - See <literal>02portal.war:/WEB-INF/conf/organization/organization-configuration.xml</literal> for the full content. - </para> - - </note> - -<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_PredefinedUserConfiguration/default100.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - - </section> - - <section id="sect-Reference_Guide-Predefined_User_Configuration-Plugin_for_managing_user_creation"> - <title>Plugin for managing user creation</title> - <para> - The plugin type <literal>org.exoplatform.services.organization.impl.NewUserEventListener</literal> specifies which groups all newly created users should become members of. - </para> - <para> - It specifies the group memberships and the membership types to use (while a <emphasis>group</emphasis> is just a set of users, a membership <emphasis>type</emphasis> represents a user's role within a group). It also specifies a list of users that should not be processed (such as administrative users like '<literal>root</literal>'). - </para> - <note> - <title>Terminology</title> - <para> - The terms '<emphasis role="bold">membership</emphasis>' and '<emphasis role="bold">membership type</emphasis>' refer to the same thing, and are used interchangeably. - </para> - - </note> - -<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_PredefinedUserConfiguration/default101.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - - </section> - - + <title>Predefined User Configuration</title> + <section id="sect-Reference_Guide-Predefined_User_Configuration-Overview"> + <title>Overview</title> + <para> + The initial Organization configuration should be specified by editing the content of <filename><replaceable>JBOSS_HOME</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/02portal.war:/WEB-INF/conf/organization/organization-configuration.xml</filename>. This file uses the portal XML configuration schema. It lists several configuration plug-ins. + </para> + </section> + <section id="sect-Reference_Guide-Predefined_User_Configuration-Plugin_for_adding_users_groups_and_membership_types"> + <title>Plug-in for adding users, groups and membership types</title> + <para> + The plug-in type <literal>org.exoplatform.services.organization.OrganizationDatabaseInitializer</literal> is used to specify a list of membership types, a list of groups and a list of users to be created. + </para> + <para> + The <emphasis role="bold">checkDatabaseAlgorithm</emphasis> initialization parameter determines how the database update is performed. + </para> + <para> + If its value is set to <emphasis role="bold">entry</emphasis> it means that each user, group and membership listed in the configuration is checked each time JBoss Enterprise Portal Platform is started. If the entry does not yet exist in the database, it is created. + </para> + <para> + If <emphasis role="bold">checkDatabaseAlgorithm</emphasis> parameter value is set to <emphasis role="bold">empty</emphasis>, the configuration data will be updated to the database only if the database is empty. + </para> + </section> + <section id="sect-Reference_Guide-Predefined_User_Configuration-Membership_types"> + <title>Membership types</title> + <para> + The predefined membership types are specified in the <emphasis role="bold">membershipType</emphasis> field of the <emphasis role="bold">OrganizationConfig</emphasis> plug-in parameter. + </para> + <note> + <para> + See <literal>02portal.war:/WEB-INF/conf/organization/organization-configuration.xml</literal> for the full content. + </para> + </note> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_PredefinedUserConfiguration/default98.xml" parse="text"/></programlisting> + </section> + <section id="sect-Reference_Guide-Predefined_User_Configuration-Groups"> + <title>Groups</title> + <para> + The predefined groups are specified in the <emphasis role="bold">group</emphasis> field of the <emphasis role="bold">OrganizationConfig</emphasis> plug-in parameter. + </para> + <note> + <para> + See <literal>02portal.war:/WEB-INF/conf/organization/organization-configuration.xml</literal> for the full content. + </para> + </note> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_PredefinedUserConfiguration/default99.xml" parse="text"/></programlisting> + </section> + <section id="sect-Reference_Guide-Predefined_User_Configuration-Users"> + <title>Users</title> + <para> + The predefined users are specified in the <emphasis role="bold">user</emphasis> field of the <emphasis role="bold">OrganizationConfig</emphasis> plug-in parameter. + </para> + <note> + <para> + See <literal>02portal.war:/WEB-INF/conf/organization/organization-configuration.xml</literal> for the full content. + </para> + </note> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_PredefinedUserConfiguration/default100.xml" parse="text"/></programlisting> + </section> + <section id="sect-Reference_Guide-Predefined_User_Configuration-Plugin_for_managing_user_creation"> + <title>Plug-in for managing user creation</title> + <para> + The plug-in type <literal>org.exoplatform.services.organization.impl.NewUserEventListener</literal> specifies which groups all newly created users should become members of. + </para> + <para> + It specifies the group memberships and the membership types to use (while a <emphasis>group</emphasis> is just a set of users, a membership <emphasis>type</emphasis> represents a user&apos;s role within a group). It also specifies a list of users that should not be processed (such as administrative users like &apos;<literal>root</literal>&apos;). + </para> + <note> + <title>Terminology</title> + <para> + The terms &apos;<emphasis role="bold">membership</emphasis>&apos; and &apos;<emphasis role="bold">membership type</emphasis>&apos; refer to the same thing, and are used interchangeably. + </para> + </note> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_PredefinedUserConfiguration/default101.xml" parse="text"/></programlisting> + </section> </section> - - Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/SSO.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/SSO.xml 2012-07-05 19:41:59 UTC (rev 8774) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/SSO.xml 2012-07-06 05:00:36 UTC (rev 8775) @@ -329,7 +329,7 @@ <section id="sect-Reference_Guide-SSO_Single_Sign_On_-Central_Authentication_Service"> <title>Central Authentication Service</title> <para> - This Single Sign On plugin enables seamless integration between JBoss Enterprise Portal Platform and the Central Authentication Service (<emphasis role="bold">CAS</emphasis>) Single Sign On Framework. Details about CAS can be found <ulink url="http://www.ja-sig.org/cas/"> here </ulink> . + This Single Sign On plug-in enables seamless integration between JBoss Enterprise Portal Platform and the Central Authentication Service (<emphasis role="bold">CAS</emphasis>) Single Sign On Framework. Details about CAS can be found <ulink url="http://www.ja-sig.org/cas/"> here </ulink> . </para> <para> The integration consists of two parts; the first part consists of installing or configuring a CAS server, the second part consists of setting up the portal to use the CAS server. @@ -367,10 +367,10 @@ Change the default authentication handler with the one provided by JBoss Enterprise Portal Platform. </para> <para> - The CAS Server Plugin makes secure callbacks to a RESTful service installed on the remote JBoss Enterprise Portal Platform server to authenticate a user. + The CAS Server Plug-in makes secure callbacks to a RESTful service installed on the remote JBoss Enterprise Portal Platform server to authenticate a user. </para> <para> - In order for the plugin to function correctly, it needs to be properly configured to connect to this service. This configuration is controlled by the <filename>cas.war/WEB-INF/deployerConfigContext.xml </filename> file. + In order for the plug-in to function correctly, it needs to be properly configured to connect to this service. This configuration is controlled by the <filename>cas.war/WEB-INF/deployerConfigContext.xml </filename> file. </para> <procedure id="proc-Reference_Guide-Central_Authentication_Service-Modifying_CAS_server"> <title>Modifying CAS server</title> @@ -531,7 +531,7 @@ <section id="sect-Reference_Guide-SSO_Single_Sign_On_-Java_Open_Single_Sign_On_Project"> <title>Java Open Single Sign-On Project</title> <para> - This Single Sign On plugin enables seamless integration between JBoss Enterprise Portal Platform and the Java Open Single Sign-On Project (<emphasis role="bold">JOSSO</emphasis>) Single Sign On Framework. Details about JOSSO can be found at <ulink url="http://www.josso.org"> www.josso.org </ulink> . + This Single Sign On plug-in enables seamless integration between JBoss Enterprise Portal Platform and the Java Open Single Sign-On Project (<emphasis role="bold">JOSSO</emphasis>) Single Sign On Framework. Details about JOSSO can be found at <ulink url="http://www.josso.org"> www.josso.org </ulink> . </para> <para> This section details setting up the JOSSO server to authenticate against the JBoss Enterprise Portal Platform login module. @@ -729,10 +729,10 @@ The first step is to add the JBoss Enterprise Portal Platform Authentication Plugin. </para> <para> - The plugin makes secure callbacks to a RESTful service installed on the remote JBoss Enterprise Portal Platform server to authenticate a user. + The plug-in makes secure callbacks to a RESTful service installed on the remote JBoss Enterprise Portal Platform server to authenticate a user. </para> <para> - In order for the plugin to function correctly, it needs to be properly configured to connect to this service. This configuration is done via the <filename>opensso.war/config/auth/default/AuthenticationPlugin.xml</filename> file. + In order for the plug-in to function correctly, it needs to be properly configured to connect to this service. This configuration is done via the <filename>opensso.war/config/auth/default/AuthenticationPlugin.xml</filename> file. </para> <procedure id="proc-Reference_Guide-Modifying_the_OpenSSO_server-Modifying_OpenSSO_server"> <title>Modifying OpenSSO server</title> Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/Introduction.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/Introduction.xml 2012-07-05 19:41:59 UTC (rev 8774) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/Introduction.xml 2012-07-06 05:00:36 UTC (rev 8775) @@ -1,122 +1,106 @@ -<?xml version='1.0' encoding='utf-8' ?> +<?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" [ <!ENTITY % BOOK_ENTITIES SYSTEM "Reference_Guide.ent"> %BOOK_ENTITIES; ]> <chapter id="chap-Reference_Guide-Introduction"> - <title>Introduction</title> - <para> - JBoss Enterprise Portal Platform is based on the GateIn project which is the merge of two mature Java projects; JBoss Portal and eXo Portal. This new community project takes the best of both offerings and incorporates them into a single portal framework. The aim is to provide an intuitive user-friendly portal, and a framework to address the needs of today's Web 2.0 applications. - </para> - <mediaobject> - <imageobject role="html"> - <imagedata align="center" fileref="images/Common/Frontpage.png" format="PNG" scale="100" width="444" /> - </imageobject> - <imageobject role="fo"> - <imagedata align="center" contentwidth="150mm" fileref="images/Common/Frontpage.png" format="PNG" width="444" /> - </imageobject> + <title>Introduction</title> + <para> + JBoss Enterprise Portal Platform is based on the GateIn project, which is the merge of two mature Java projects: JBoss Portal and eXo Portal. This new community project takes the best of both offerings and incorporates them into a single portal framework. The aim is to provide an intuitive user-friendly portal, and a framework to address the needs of today&apos;s Web 2.0 applications. + </para> + <mediaobject> + <imageobject role="html"> + <imagedata width="444" align="center" scale="100" fileref="images/Common/Frontpage.png" format="PNG"/> + </imageobject> + <imageobject role="fo"> + <imagedata width="444" contentwidth="150mm" align="center" fileref="images/Common/Frontpage.png" format="PNG"/> + </imageobject> + </mediaobject> + <para> + This book provides a deep-dive information about installation and configuration of the services provided by JBoss Enterprise Portal Platform. + </para> + <note> + <title>Notational Devices</title> + <para> + Along with the <emphasis>Document Conventions</emphasis> outlined in the <xref linkend="pref-Reference_Guide-Preface"/>, this document will also use the following notational devices: + <variablelist id="vari-Reference_Guide-Introduction-Devices"> + <title>Devices</title> + <varlistentry> + <term> + <replaceable>&lt;JBOSS_HOME&gt;</replaceable> + </term> + <listitem> + <para> + This device will refer to the <application>JBoss Application Server</application> (<filename>jboss-as</filename>) directory deployed in JBoss Enterprise Portal Platform by default. + </para> + <para> + Therefore, if your JBoss Enterprise Portal Platform instance is deployed into a directory called <filename>jboss-epp-&VY;/</filename>, your <replaceable>&lt;JBOSS_HOME&gt;</replaceable> directory would be <filename>jboss-epp-&VY;/jboss-as/</filename>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <replaceable>&lt;PROFILE&gt;</replaceable> + </term> + <listitem> + <para> + This device will usually follow an instance of <replaceable>&lt;JBOSS_HOME&gt;</replaceable> in a file path and refers to the directory that contains the server profile your JBoss Enterprise Portal Platform instance is configured to use. + </para> + <para> + JBoss Enterprise Portal Platform comes with six profiles by default; <emphasis role="bold">all</emphasis>, <emphasis role="bold">default</emphasis>, <emphasis role="bold">minimal</emphasis>, <emphasis role="bold">production</emphasis>, <emphasis role="bold">standard</emphasis> and <emphasis role="bold">web</emphasis>. These profiles are found in the <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/</filename> directory. + </para> + <para> + Therefore, if you are using the <emphasis>default</emphasis> profile, your <replaceable>&lt;PROFILE&gt;</replaceable> directory would be <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/default/</filename> + </para> + </listitem> + </varlistentry> + </variablelist> - </mediaobject> - <para> - This book provides a deep-dive information about installation and configuration of the services provided by JBoss Enterprise Portal Platform. - </para> - <note> - <title>Notational Devices</title> - <para> - Along with the <emphasis>Document Conventions</emphasis> outlined in the <xref linkend="pref-Reference_Guide-Preface" />, this document will also use the following notational devices: - <variablelist id="vari-Reference_Guide-Introduction-Devices"> - <title>Devices</title> - <varlistentry> - <term><replaceable>&lt;JBOSS_HOME&gt;</replaceable></term> - <listitem> - <para> - This device will refer to the <application>JBoss Application Server</application> (<filename>jboss-as</filename>) directory deployed in JBoss Enterprise Portal Platform by default. - </para> - <para> - Therefore, if your JBoss Enterprise Portal Platform instance is deployed into a directory called <filename>jboss-epp-&VY;/</filename>, your <replaceable>&lt;JBOSS_HOME&gt;</replaceable> directory would be <filename>jboss-epp-&VY;/jboss-as/</filename>. - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term><replaceable>&lt;PROFILE&gt;</replaceable></term> - <listitem> - <para> - This device will usually follow an instance of <replaceable>&lt;JBOSS_HOME&gt;</replaceable> in a file path and refers to the directory that contains the server profile your JBoss Enterprise Portal Platform instance is configured to use. - </para> - <para> - JBoss Enterprise Portal Platform comes with six profiles by default; <emphasis role="bold">all</emphasis>, <emphasis role="bold">default</emphasis>, <emphasis role="bold">minimal</emphasis>, <emphasis role="bold">production</emphasis>, <emphasis role="bold">standard</emphasis> and <emphasis role="bold">web</emphasis>. These profiles are found in the <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/</filename> directory. - </para> - <para> - Therefore, if you are using the <emphasis>default</emphasis> profile, your <replaceable>&lt;PROFILE&gt;</replaceable> directory would be <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/default/</filename> - </para> - - </listitem> - - </varlistentry> - - </variablelist> - - </para> - - </note> - <section id="sect-Reference_Guide-Introduction-Related_Links"> - <title>Related Links</title> - <variablelist> - <varlistentry> - <term>Technical documentation</term> - <listitem> - <para> - Other technical documentation, including an <emphasis role="bold">Installation Guide</emphasis>, and a <emphasis role="bold">User Guide</emphasis> can be found at <ulink type="http" url="http://www.redhat.com/docs/en-US/JBoss_Enterprise_Portal_Platfo... - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Non-technical documentation</term> - <listitem> - <para> - Links to non-technical documents are included on the front page of the portal: - </para> - <mediaobject> - <imageobject role="html"> - <imagedata align="center" fileref="images/Common/Non-tech-docs.png" format="PNG" scale="90" width="444" /> - </imageobject> - <imageobject role="fo"> - <imagedata align="center" contentwidth="130mm" fileref="images/Common/Non-tech-docs.png" format="PNG" width="444" /> - </imageobject> - - </mediaobject> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Videos</term> - <listitem> - <para> - A link to <ulink type="http" url="http://vimeo.com/channels/gatein">videos</ulink> related to the JBoss Enterprise Portal Platform is also included on the front page: - </para> - <mediaobject> - <imageobject role="html"> - <imagedata align="center" fileref="images/Common/Videos.png" format="PNG" scale="90" width="444" /> - </imageobject> - <imageobject role="fo"> - <imagedata align="center" contentwidth="130mm" fileref="images/Common/Videos.png" format="PNG" width="444" /> - </imageobject> - - </mediaobject> - - </listitem> - - </varlistentry> - - </variablelist> - - </section> - - + </para> + </note> + <section id="sect-Reference_Guide-Introduction-Related_Links"> + <title>Related Links</title> + <variablelist> + <varlistentry> + <term>Technical documentation</term> + <listitem> + <para> + Other technical documentation, including an <emphasis role="bold">Installation Guide</emphasis>, and a <emphasis role="bold">User Guide</emphasis> can be found at <ulink url="http://www.redhat.com/docs/en-US/JBoss_Enterprise_Portal_Platfo... type="http">www.redhat.com/docs</ulink> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Non-technical documentation</term> + <listitem> + <para> + Links to non-technical documents are included on the front page of the portal: + </para> + <mediaobject> + <imageobject role="html"> + <imagedata width="444" align="center" scale="90" fileref="images/Common/Non-tech-docs.png" format="PNG"/> + </imageobject> + <imageobject role="fo"> + <imagedata width="444" contentwidth="130mm" align="center" fileref="images/Common/Non-tech-docs.png" format="PNG"/> + </imageobject> + </mediaobject> + </listitem> + </varlistentry> + <varlistentry> + <term>Videos</term> + <listitem> + <para> + A link to <ulink url="http://vimeo.com/channels/gatein" type="http">videos</ulink> related to the JBoss Enterprise Portal Platform is also included on the front page: + </para> + <mediaobject> + <imageobject role="html"> + <imagedata width="444" align="center" scale="90" fileref="images/Common/Videos.png" format="PNG"/> + </imageobject> + <imageobject role="fo"> + <imagedata width="444" contentwidth="130mm" align="center" fileref="images/Common/Videos.png" format="PNG"/> + </imageobject> + </mediaobject> + </listitem> + </varlistentry> + </variablelist> + </section> </chapter> - Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortalDevelopment/DataImportStrategy.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortalDevelopment/DataImportStrategy.xml 2012-07-05 19:41:59 UTC (rev 8774) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortalDevelopment/DataImportStrategy.xml 2012-07-06 05:00:36 UTC (rev 8775) @@ -1,58 +1,50 @@ -<?xml version='1.0' encoding='utf-8' ?> +<?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" [ <!ENTITY % BOOK_ENTITIES SYSTEM "Reference_Guide.ent"> %BOOK_ENTITIES; ]> <chapter id="chap-Reference_Guide-Data_Import_Strategy"> - <title>Data Import Strategy</title> - <section id="sect-Reference_Guide-Data_Import_Strategy-Introduction"> - <title>Introduction</title> - <para> + <title>Data Import Strategy</title> + <section id="sect-Reference_Guide-Data_Import_Strategy-Introduction"> + <title>Introduction</title> + <para> In the Portal extension mechanism, developers can define an extension that Portal data can be customized by configurations in the extension. There are several cases which an extension developer wants to define how to customize the Portal data, for example modifying, overwriting or just inserting a bit into the data defined by the portal. Therefore, GateIn also defines several modes for each case and the only thing which a developer has to do is to clarify the usecase and reasonably configure extensions. </para> - <para> + <para> This section shows you how data are changes in each mode. </para> - - </section> - - <section id="sect-Reference_Guide-Data_Import_Strategy-Import_Mode"> - <title>Import Mode</title> - <para> + </section> + <section id="sect-Reference_Guide-Data_Import_Strategy-Import_Mode"> + <title>Import Mode</title> + <para> In this section, the following modes for the import strategy are introduced: </para> - <itemizedlist> - <listitem> - <para> + <itemizedlist> + <listitem> + <para> <literal>CONSERVE</literal> </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> <literal>MERGE</literal> </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> <literal>INSERT</literal> </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> <literal>OVERWRITE</literal> </para> - - </listitem> - - </itemizedlist> - <para> + </listitem> + </itemizedlist> + <para> Each mode indicates how the Portal data are imported. The import mode value is set whenever <literal>NewPortalConfigListener</literal> is initiated. If the mode is not set, the default value will be used in this case. The default value is configurable as a UserPortalConfigService initial param. For example, the bellow configuration means that default value is <literal>MERGE</literal>. </para> - -<programlisting language="XML" role="XML"> + <programlisting language="XML" role="XML"> &lt;component&gt; &lt;key&gt;org.exoplatform.portal.config.UserPortalConfigService&lt;/key&gt; &lt;type&gt;org.exoplatform.portal.config.UserPortalConfigService&lt;/type&gt; @@ -68,82 +60,69 @@ &lt;/component&gt; </programlisting> - <para> + <para> The way that the import strategy works with the import mode will be clearly demonstrated in next sections for each type of data. </para> - - </section> - - <section id="sect-Reference_Guide-Data_Import_Strategy-Data_Import_Strategy"> - <title>Data Import Strategy</title> - <para> - The 'Portal Data' term which has been referred in the previous sections can be classified into three types of object data: Portal Config, Page Data and Navigation Data; each of which has some differences in the import strategy. + </section> + <section id="sect-Reference_Guide-Data_Import_Strategy-Data_Import_Strategy"> + <title>Data Import Strategy</title> + <para> + The &apos;Portal Data&apos; term which has been referred in the previous sections can be classified into three types of object data: Portal Config, Page Data and Navigation Data; each of which has some differences in the import strategy. </para> - <section id="sect-Reference_Guide-Data_Import_Strategy-Navigation_Data"> - <title>Navigation Data</title> - <para> + <section id="sect-Reference_Guide-Data_Import_Strategy-Navigation_Data"> + <title>Navigation Data</title> + <para> The navigation data import strategy will be processed to the import mode level as the followings: </para> - <itemizedlist> - <listitem> - <para> + <itemizedlist> + <listitem> + <para> <literal>CONSERVE</literal>: If the navigation exists, leave it untouched. Otherwise, import data. </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> <literal>INSERT</literal>: Insert the missing description data, but add only new nodes. Other modifications remains untouched. </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> <literal>MERGE</literal>: Merge the description data, add missing nodes and update same name nodes. </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> <literal>OVERWRITE</literal>: Always destroy the previous data and recreate it. </para> - - </listitem> - - </itemizedlist> - <para> + </listitem> + </itemizedlist> + <para> In the GateIn navigation structure, each navigation can be referred to a tree which each node links to a page content. Each node contains some description data, such as label, icon, page reference, and more. Therefore, GateIn provides a way to insert or merge new data to the initiated navigation tree or a sub-tree. </para> - <para> + <para> The merge strategy performs the recursive comparison of child nodes between the existing persistent nodes of a navigation and the transient nodes provided by a descriptor: </para> - <procedure> - <step> - <para> + <procedure> + <step> + <para> Start with the root nodes (which is the effective root node or another node if the parent URI is specified). </para> - - </step> - <step> - <para> + </step> + <step> + <para> Compare the set of child nodes and insert the missing nodes in the persistent nodes. </para> - - </step> - <step> - <para> + </step> + <step> + <para> Proceed recursively for each child having the same name. </para> - - </step> - - </procedure> - - <para> - Let's see the example with two navigation nodes in each import mode. In this case, there are 2 navigation definitions: + </step> + </procedure> + <para> + Let&apos;s see the example with two navigation nodes in each import mode. In this case, there are 2 navigation definitions: </para> - -<programlisting language="XML" role="XML">&lt;node-navigation&gt; + <programlisting language="XML" role="XML">&lt;node-navigation&gt; &lt;page-nodes&gt; &lt;node&gt; &lt;name&gt;foo&lt;/name&gt; @@ -159,156 +138,126 @@ &lt;/node&gt; &lt;/page-nodes&gt; &lt;/node-navigation&gt;</programlisting> - <mediaobject> - <imageobject> - <imagedata align="center" fileref="images/DataImportStrategy/navigation1.png" format="PNG" width="444" /> - </imageobject> - - </mediaobject> - -<programlisting language="XML" role="XML">&lt;node-navigation&gt; + <mediaobject> + <imageobject> + <imagedata width="444" align="center" fileref="images/DataImportStrategy/navigation1.png" format="PNG"/> + </imageobject> + </mediaobject> + <programlisting language="XML" role="XML">&lt;node-navigation&gt; &lt;page-nodes&gt; &lt;node&gt; &lt;name&gt;foo&lt;/name&gt; &lt;icon&gt;foo_icon_2&lt;/icon&gt; &lt;/node&gt; &lt;node&gt; - &lt;name&gt;bar&lt;/name&gt; - &lt;icon&gt;bar_icon&lt;/icon&gt; + &lt;name&gt;daa&lt;/name&gt; + &lt;icon&gt;daa_icon&lt;/icon&gt; &lt;/node&gt; &lt;/page-nodes&gt; &lt;/node-navigation&gt;</programlisting> - <mediaobject> - <imageobject> - <imagedata align="center" fileref="images/DataImportStrategy/navigation2.png" format="PNG" width="444" /> - </imageobject> - - </mediaobject> - <para> + <mediaobject> + <imageobject> + <imagedata width="444" align="center" fileref="images/DataImportStrategy/navigation2.png" format="PNG"/> + </imageobject> + </mediaobject> + <para> For example, the <emphasis>navigation1</emphasis> is loaded before <emphasis>navigation2</emphasis>. The Navigation Importer processes on two navigation definitions, depending on the Import Mode defined in portal configuration. </para> - <variablelist id="vari-Reference_Guide-Navigation_Data-Import_Mode_Cases"> - <title>Import Mode Cases</title> - <varlistentry> - <term>Case 1: <literal>CONSERVE</literal></term> - <listitem> - <para> + <variablelist id="vari-Reference_Guide-Navigation_Data-Import_Mode_Cases"> + <title>Import Mode Cases</title> + <varlistentry> + <term>Case 1: <literal>CONSERVE</literal></term> + <listitem> + <para> With the <literal>CONSERVE</literal> mode, data are only imported when they do not exist. So, if the navigation has been created by the <emphasis>navigation1</emphasis> definition, the <emphasis>navigation2</emphasis> definition does not affect anything on it. We have the result as following </para> - <mediaobject> - <imageobject role="html"> - <imagedata fileref="images/DataImportStrategy/navigation1.png" format="PNG" align="center"/> - </imageobject> - <imageobject role="fo"> - <imagedata fileref="images/DataImportStrategy/navigation1.png" format="PNG" align="center" width="100mm"/> - </imageobject> - </mediaobject> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Case 2: <literal>INSERT</literal></term> - <listitem> - <para> + <mediaobject> + <imageobject role="html"> + <imagedata align="center" fileref="images/DataImportStrategy/navigation1.png" format="PNG"/> + </imageobject> + <imageobject role="fo"> + <imagedata width="100mm" align="center" fileref="images/DataImportStrategy/navigation1.png" format="PNG"/> + </imageobject> + </mediaobject> + </listitem> + </varlistentry> + <varlistentry> + <term>Case 2: <literal>INSERT</literal></term> + <listitem> + <para> If a node does not exist, the importer will add new nodes to the navigation tree. You will see the following result: </para> - <mediaobject> - <imageobject> - <imagedata align="center" fileref="images/DataImportStrategy/navigation_insert.png" format="PNG" width="444" /> - </imageobject> - - </mediaobject> - <para> - Hereafter, the node 'bar' is added to the navigation tree, because it does not exist in the initiated data. Other nodes are kept in the import process. + <mediaobject> + <imageobject> + <imagedata width="444" align="center" fileref="images/DataImportStrategy/navigation_insert.png" format="PNG"/> + </imageobject> + </mediaobject> + <para> + Hereafter, the node &apos;bar&apos; is added to the navigation tree, because it does not exist in the initiated data. Other nodes are kept in the import process. </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Case 3: <literal>MERGE</literal></term> - <listitem> - <para> + </listitem> + </varlistentry> + <varlistentry> + <term>Case 3: <literal>MERGE</literal></term> + <listitem> + <para> The <literal>MERGE</literal> mode indicates that a new node is added to the navigation tree, and updates the node data (such node label and node icon in the example) if it exists. </para> - <mediaobject> - <imageobject> - <imagedata align="center" fileref="images/DataImportStrategy/navigation_merge.png" format="PNG" width="444" /> - </imageobject> - - </mediaobject> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Case 4: <literal>OVERWRITE</literal></term> - <listitem> - <para> + <mediaobject> + <imageobject> + <imagedata width="444" align="center" fileref="images/DataImportStrategy/navigation_merge.png" format="PNG"/> + </imageobject> + </mediaobject> + </listitem> + </varlistentry> + <varlistentry> + <term>Case 4: <literal>OVERWRITE</literal></term> + <listitem> + <para> Everything will be destroyed and replaced with new data if the <literal>OVERWRITE</literal> mode is used. </para> - <mediaobject> - <imageobject> - <imagedata align="center" fileref="images/DataImportStrategy/navigation2.png" format="PNG" width="444" /> - </imageobject> - - </mediaobject> - - </listitem> - - </varlistentry> - - </variablelist> - - </section> - - <section id="sect-Reference_Guide-Data_Import_Strategy-Portal_Config"> - <title>Portal Config</title> - <para> - PortalConfig defines the portal name, permission, layout and some properties of a site. These information are configured in the <emphasis>portal.xml</emphasis>, <emphasis>group.xml</emphasis> or <emphasis>user.xml</emphasis>, depending on the site type. The PortalConfig importer performs a strategy that is based on the mode defined in NewPortalConfigListener, including <literal>CONSERVE</literal>, <literal>INSERT</literal>, <literal>MERGE</literal> or <literal>OVERWRITE</literal>. Let's see how the import mode affects in the process of portal data performance: + <mediaobject> + <imageobject> + <imagedata width="444" align="center" fileref="images/DataImportStrategy/navigation2.png" format="PNG"/> + </imageobject> + </mediaobject> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="sect-Reference_Guide-Data_Import_Strategy-Portal_Config"> + <title>Portal Config</title> + <para> + PortalConfig defines the portal name, permission, layout and some properties of a site. These information are configured in the <emphasis>portal.xml</emphasis>, <emphasis>group.xml</emphasis> or <emphasis>user.xml</emphasis>, depending on the site type. The PortalConfig importer performs a strategy that is based on the mode defined in NewPortalConfigListener, including <literal>CONSERVE</literal>, <literal>INSERT</literal>, <literal>MERGE</literal> or <literal>OVERWRITE</literal>. Let&apos;s see how the import mode affects in the process of portal data performance: </para> - <itemizedlist> - <listitem> - <para> + <itemizedlist> + <listitem> + <para> <literal>CONSERVE</literal>: There is nothing to be imported. The existing data will be kept without any changes. </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> <literal>INSERT</literal>: When the portal config does not exist, create the new portal defined by the portal config definition. Otherwise, do nothing. </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> <literal>MERGE</literal> and <literal>OVERWRITE</literal> have the same behavior. The new portal config will be created if it does not exist or update portal properties defined by the portal config definition. </para> - - </listitem> - - </itemizedlist> - - </section> - - <section id="sect-Reference_Guide-Data_Import_Strategy-Page_Data"> - <title>Page Data</title> - <para> + </listitem> + </itemizedlist> + </section> + <section id="sect-Reference_Guide-Data_Import_Strategy-Page_Data"> + <title>Page Data</title> + <para> The import mode affects the page data import as the same as Portal Config. </para> - <note> - <para> + <note> + <para> If the Import mode is <literal>CONSERVE</literal> or <literal>INSERT</literal>, the data import strategy always performs as the <literal>MERGE</literal> mode in the first data initialization of the Portal. </para> - - </note> - - </section> - - + </note> </section> - - + </section> </chapter> - Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortalDevelopment/DefaultPortalNavigationConfiguration.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortalDevelopment/DefaultPortalNavigationConfiguration.xml 2012-07-05 19:41:59 UTC (rev 8774) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortalDevelopment/DefaultPortalNavigationConfiguration.xml 2012-07-06 05:00:36 UTC (rev 8775) @@ -1,294 +1,247 @@ -<?xml version='1.0' encoding='utf-8' ?> +<?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" [ <!ENTITY % BOOK_ENTITIES SYSTEM "Reference_Guide.ent"> %BOOK_ENTITIES; ]> <chapter id="chap-Reference_Guide-Portal_Navigation_Configuration"> - <title>Portal Navigation Configuration</title> - <section id="sect-Reference_Guide-Portal_Navigation_Configuration-Overview"> - <title>Overview</title> - <para> + <title>Portal Navigation Configuration</title> + <section id="sect-Reference_Guide-Portal_Navigation_Configuration-Overview"> + <title>Overview</title> + <para> There are three types of navigation available to portal users: </para> - <itemizedlist> - <listitem> - <para> - <xref linkend="sect-Reference_Guide-Portal_Navigation_Configuration-Portal_Navigation" /> + <itemizedlist> + <listitem> + <para> + <xref linkend="sect-Reference_Guide-Portal_Navigation_Configuration-Portal_Navigation"/> </para> - - </listitem> - <listitem> - <para> - <xref linkend="sect-Reference_Guide-Portal_Navigation_Configuration-Group_Navigation" /> + </listitem> + <listitem> + <para> + <xref linkend="sect-Reference_Guide-Portal_Navigation_Configuration-Group_Navigation"/> </para> - - </listitem> - <listitem> - <para> - <xref linkend="sect-Reference_Guide-Portal_Navigation_Configuration-User_Navigation" /> + </listitem> + <listitem> + <para> + <xref linkend="sect-Reference_Guide-Portal_Navigation_Configuration-User_Navigation"/> </para> - - </listitem> - - </itemizedlist> - <para> - These navigations are configured using the standard XML syntax in the file; <filename>02portal.war:/WEB-INF/conf/portal/portal-configuration.xml</filename>. + </listitem> + </itemizedlist> + <para> + These navigations are configured using the standard XML syntax in the file: <filename>02portal.war/WEB-INF/conf/portal/portal-configuration.xml</filename>. </para> - -<programlisting language="XML" role="XML"><xi:include href="../../extras/PortalDevelopment_DefaultPortalNavigationConfiguration/default144.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <para> - This XML configuration defines where in the portal's <literal>WAR</literal> to look for configuration settings, and which portals, groups, and user specific views to include in <emphasis>portal/group/user</emphasis> navigation. + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/PortalDevelopment_DefaultPortalNavigationConfiguration/default144.xml" parse="text"/></programlisting> + <para> + This XML configuration defines where in the portal&apos;s <literal>WAR</literal> to look for configuration settings, and which portals, groups, and user specific views to include in <emphasis>portal/group/user</emphasis> navigation. </para> - <para> + <para> The first time the portal is launched those files will be used to create an initial navigation. That information will then be stored in the JCR content repository and can be modified and managed from the portal UI. </para> - <!-- DOC NOTE: Added based on Gatein revision 6987 --> <para> +<!-- DOC NOTE: Added based on Gatein revision 6987 --> <para> Each portal, groups and users navigation is indicated by a configuration paragraph, for example: </para> - <programlistingco> - <areaspec> - <area coords="5" id="area-Reference_Guide-Portal_Navigation_Configuration-Overview-predifinedOwner" /> - <area coords="10" id="area-Reference_Guide-Portal_Navigation_Configuration-Overview-ownerType" /> - <area coords="13" id="area-Reference_Guide-Portal_Navigation_Configuration-Overview-templateLocation" /> - <area coords="16" id="area-Reference_Guide-Portal_Navigation_Configuration-Overview-importMode" /> - - </areaspec> - -<programlisting language="XML" role="XML">&lt;object-param&gt; + <programlistingco> + <areaspec> + <area coords="5" id="area-Reference_Guide-Portal_Navigation_Configuration-Overview-predifinedOwner"/> + <area coords="10" id="area-Reference_Guide-Portal_Navigation_Configuration-Overview-ownerType"/> + <area coords="13" id="area-Reference_Guide-Portal_Navigation_Configuration-Overview-templateLocation"/> + <area coords="16" id="area-Reference_Guide-Portal_Navigation_Configuration-Overview-importMode"/> + </areaspec> + <programlisting language="XML" role="XML">&lt;object-param&gt; &lt;name&gt;portal.configuration&lt;/name&gt; &lt;description&gt;description&lt;/description&gt; - &lt;object type="org.exoplatform.portal.config.NewPortalConfig"&gt; - &lt;field name="predefinedOwner"&gt; - &lt;collection type="java.util.HashSet"&gt; + &lt;object type=&quot;org.exoplatform.portal.config.NewPortalConfig&quot;&gt; + &lt;field name=&quot;predefinedOwner&quot;&gt; + &lt;collection type=&quot;java.util.HashSet&quot;&gt; &lt;value&gt;&lt;string&gt;classic&lt;/string&gt;&lt;/value&gt; &lt;/collection&gt; &lt;/field&gt; - &lt;field name="ownerType"&gt; + &lt;field name=&quot;ownerType&quot;&gt; &lt;string&gt;portal&lt;/string&gt; &lt;/field&gt; - &lt;field name="templateLocation"&gt; + &lt;field name=&quot;templateLocation&quot;&gt; &lt;string&gt;war:/conf/portal/&lt;/string&gt; &lt;/field&gt; - &lt;field name="importMode"&gt; + &lt;field name=&quot;importMode&quot;&gt; &lt;string&gt;conserve&lt;/string&gt; &lt;/field&gt; &lt;/object&gt; &lt;/object-param&gt; </programlisting> - - </programlistingco> - - <calloutlist> - <callout arearefs="area-Reference_Guide-Portal_Navigation_Configuration-Overview-predifinedOwner"> - <para> + </programlistingco> + <calloutlist> + <callout arearefs="area-Reference_Guide-Portal_Navigation_Configuration-Overview-predifinedOwner"> + <para> <parameter>predefinedOwner</parameter> defines the navigation owner, portal will look for the configuration files in folder with this name, if there is no suitable folder, a default portal will be created with name is this value. </para> - - </callout> - <callout arearefs="area-Reference_Guide-Portal_Navigation_Configuration-Overview-ownerType"> - <para> + </callout> + <callout arearefs="area-Reference_Guide-Portal_Navigation_Configuration-Overview-ownerType"> + <para> <parameter>ownerType</parameter> define the type of portal navigation. It may be a portal, group or user </para> - - </callout> - <callout arearefs="area-Reference_Guide-Portal_Navigation_Configuration-Overview-templateLocation"> - <para> + </callout> + <callout arearefs="area-Reference_Guide-Portal_Navigation_Configuration-Overview-templateLocation"> + <para> <parameter>templateLocation</parameter> the classpath where contains all portal configuration files </para> - - </callout> - <callout arearefs="area-Reference_Guide-Portal_Navigation_Configuration-Overview-importMode"> - <para> + </callout> + <callout arearefs="area-Reference_Guide-Portal_Navigation_Configuration-Overview-importMode"> + <para> <parameter>importMode</parameter> The mode for navigation import. There are 4 types of import mode: </para> - <itemizedlist> - <listitem> - <para> + <itemizedlist> + <listitem> + <para> <parameter>conserve</parameter>: Import data when it does not exist, otherwise do nothing. </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> <parameter>insert</parameter>: Import data when it does not exist, otherwise performs a strategy that adds new data only. </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> <parameter>merge</parameter>: Import data when it does not exist, update data when it exists. </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> <parameter>rewrite</parameter>: Overwrite data whatsoever. </para> - - </listitem> - - </itemizedlist> - - </callout> - - </calloutlist> - <para> + </listitem> + </itemizedlist> + </callout> + </calloutlist> + <para> Based on these parameters, the portal will look for the configuration files and create a relevant portal navigation, pages and data import strategy. </para> - <para> + <para> The portal configuration files will be stored in folders with path look like <filename>{templateLocation}/{ownerType}/{predefinedOwner}</filename>, all navigations are defined in the <filename>navigation.xml</filename> file, pages are defined in <filename>pages.xml</filename> and portal configuration is defined in <filename>portal.xml</filename>. </para> - <para> + <para> For example, with the above configuration, portal will look for all configuration files from <filename>war:/conf/portal/portal/classic path.</filename> </para> - - </section> - - <section id="sect-Reference_Guide-Portal_Navigation_Configuration-Portal_Navigation"> - <title>Portal Navigation</title> - <!-- Updated based on Gatein revision 6987 --> <para> + </section> + <section id="sect-Reference_Guide-Portal_Navigation_Configuration-Portal_Navigation"> + <title>Portal Navigation</title> +<!-- Updated based on Gatein revision 6987 --> <para> The portal navigation incorporates the pages that can be accessed even when a user is not logged in (assuming the applicable permissions allow public access). For example; several portal navigations could be used when a company has multiple trademarks, and websites are set up for each of them. </para> - <para> + <para> The <emphasis>Classic</emphasis> portal is configured by three XML files in the <filename>02portal.war:/WEB-INF/conf/portal/portal/classic</filename> directory: </para> - <variablelist> - <varlistentry> - <term>portal.xml</term> - <listitem> - <para> + <variablelist> + <varlistentry> + <term>portal.xml</term> + <listitem> + <para> This file describes the layout and portlets that will be shown on all pages. Usually the layout contains the banner, footer, menu and breadcrumbs portlets. JBoss Enterprise Portal Platform is extremely configurable as every view element (even the banner and footer) is a portlet. </para> - -<programlisting language="XML" role="XML"><xi:include href="../../extras/PortalDevelopment_DefaultPortalNavigationConfiguration/portal.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <para> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/PortalDevelopment_DefaultPortalNavigationConfiguration/portal.xml" parse="text"/></programlisting> + <para> It is also possible to apply a nested container that can also contain portlets. Row, column or tab containers are then responsible for the layout of their child portlets. </para> - <!-- Updated based on Gatein revision 6987 --> <para> +<!-- Updated based on Gatein revision 6987 --> <para> Each application references a portlet using the id <literal>portal#{portalName}:/{portletWarName}/{portletName}/{uniqueId}</literal>. </para> - <para> + <para> Use the <literal>page-body</literal> tag to define where JBoss Enterprise Portal Platform should render the current page. </para> - <para> - The defined <emphasis>classic</emphasis> portal is accessible to "Everyone" (at <literal>/portal/public/classic</literal>) but only members of the group <literal>/platform/administrators</literal> can edit it. + <para> + The defined <emphasis>classic</emphasis> portal is accessible to &quot;Everyone&quot; (at <literal>/portal/classic</literal>) but only members of the group <literal>/platform/administrators</literal> can edit it. </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>navigation.xml</term> - <listitem> - <para> + </listitem> + </varlistentry> + <varlistentry> + <term>navigation.xml</term> + <listitem> + <para> This file defines all the navigation nodes the portal will have. The syntax is simple and uses nested node tags. Each node references a page defined in <filename>pages.xml</filename> file. </para> - <!-- Updated based on Gatein revision 6987 --> <para> +<!-- Updated based on Gatein revision 6987 --> <para> If the administrator wants to create node labels for each language, they will have to use <literal>xml:lang</literal> attribute in the label tag with value of <literal>xml:lang</literal> is the relevant locale. </para> - <para> + <para> Otherwise, if they want the node label is localized by resource bundle files, the <literal>#{...}</literal> syntax will be used, the enclosed property name serves as a key that is automatically passed to internationalization mechanism which replaces the literal property name with a localized value taken from the associated properties file matching the current locale. </para> - <!-- DOC NOTE: Replaced code navigation.xml with code from GateIn commit r3831 (as per instruction from theute) --> -<programlisting language="XML" role="XML"><xi:include href="../../extras/PortalDevelopment_DefaultPortalNavigationConfiguration/navigation.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <para> +<!-- DOC NOTE: Replaced code navigation.xml with code from GateIn commit r3831 (as per instruction from theute) --> <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/PortalDevelopment_DefaultPortalNavigationConfiguration/navigation.xml" parse="text"/></programlisting> + <para> This navigation tree can have multiple views inside portlets (such as the breadcrumbs portlet) that render the current view node, the site map or the menu portlets. </para> - <warning> - <para> + <warning> + <para> For top nodes, the <emphasis role="bold">uri</emphasis> and the <emphasis role="bold">name</emphasis> of your navigation nodes must have the <emphasis>same</emphasis> value. For other nodes the <emphasis role="bold">uri</emphasis> is a relative path. </para> - <para> - For example; <emphasis><uri>contentmanagement/fileexplorer</uri></emphasis> where '<literal>contentmanagement</literal> ' is the name of the parent node and '<literal>fileexplorer</literal>' is the name of the node (<emphasis>&lt;name&gt;fileexplorer&lt;/name&gt; </emphasis>). + <para> + For example; <emphasis> + <uri>contentmanagement/fileexplorer</uri> + </emphasis> where &apos;<literal>contentmanagement</literal> &apos; is the name of the parent node and &apos;<literal>fileexplorer</literal>&apos; is the name of the node (<emphasis>&lt;name&gt;fileexplorer&lt;/name&gt; </emphasis>). </para> - - </warning> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Subnodes</term> - <listitem> - <para> + </warning> + </listitem> + </varlistentry> + <varlistentry> + <term>Subnodes</term> + <listitem> + <para> Subnodes can also be created using the following XML structure </para> - <programlistingco> - <areaspec> - <area coords="9 40" id="area-Reference_Guide-Portal_Navigation_Configuration-Portal_Navigation-subpage" /> - - </areaspec> - -<programlisting language="XML" role="XML"><xi:include href="../../extras/PortalDevelopment_DefaultPortalNavigationConfiguration/subpage.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <calloutlist> - <callout arearefs="area-Reference_Guide-Portal_Navigation_Configuration-Portal_Navigation-subpage"> - <para> - This element defines the parent/child relationship between a page and a subnode. + <programlistingco> + <areaspec> + <area coords="9 40" id="area-Reference_Guide-Portal_Navigation_Configuration-Portal_Navigation-subpage"/> + </areaspec> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/PortalDevelopment_DefaultPortalNavigationConfiguration/subpage.xml" parse="text"/></programlisting> + <calloutlist> + <callout arearefs="area-Reference_Guide-Portal_Navigation_Configuration-Portal_Navigation-subpage"> + <para> + This element defines the parent/child relationship between a node and a subnode. </para> - - </callout> - - </calloutlist> - - </programlistingco> - - - </listitem> - - </varlistentry> - <varlistentry> - <term>pages.xml</term> - <listitem> - <para> + </callout> + </calloutlist> + </programlistingco> + </listitem> + </varlistentry> + <varlistentry> + <term>pages.xml</term> + <listitem> + <para> This configuration file structure is very similar to <filename>portal.xml</filename> and it can also contain container tags (some usage examples of container tags can be found in <filename>02portal.war/WEB-INF/conf/portal/portal/sharedlayout.xml</filename>). </para> - <para> - Each application can decide whether to render the portlet border, the window state, the icons or portlet's mode. + <para> + Each application can decide whether to render the portlet border, the window state, the icons or portlet&apos;s mode. </para> - <!-- DOC NOTE: look into including some actual examples of 'container tags' from sharedlayout.xml in place here. --> -<programlisting language="XML" role="XML"><xi:include href="../../extras/PortalDevelopment_DefaultPortalNavigationConfiguration/pages.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - - </listitem> - - </varlistentry> - - </variablelist> - - </section> - - <section id="sect-Reference_Guide-Portal_Navigation_Configuration-Group_Navigation"> - <title>Group Navigation</title> - <para> +<!-- DOC NOTE: look into including some actual examples of 'container tags' from sharedlayout.xml in place here. --> <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/PortalDevelopment_DefaultPortalNavigationConfiguration/pages.xml" parse="text"/></programlisting> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="sect-Reference_Guide-Portal_Navigation_Configuration-Group_Navigation"> + <title>Group Navigation</title> + <para> Group navigations are dynamically added to the user navigation at login. This allows users to see the pages assigned to any groups they belong to in the menu. </para> - <para> - The group navigation menu is configured by two XML files (<filename>navigation.xml</filename> and <filename>pages.xml</filename>). The syntax used in these files is the same as those covered in <xref linkend="sect-Reference_Guide-Portal_Navigation_Configuration-Portal_Navigation" />. + <para> + The group navigation menu is configured by two XML files (<filename>navigation.xml</filename> and <filename>pages.xml</filename>). The syntax used in these files is the same as those covered in <xref linkend="sect-Reference_Guide-Portal_Navigation_Configuration-Portal_Navigation"/>. </para> - <para> + <para> They are located in <filename>02portal.war/WEB-INF/conf/portal/group<replaceable>/group-name-path/</replaceable></filename> directory (For example; <filename>02portal.war/WEB-INF/conf/portal/group/platform/administrators/</filename>). </para> - - </section> - - <section id="sect-Reference_Guide-Portal_Navigation_Configuration-User_Navigation"> - <title>User Navigation</title> - <para> - User navigation is the set of nodes and pages that are owned by a user. They are part of the user's dashboard. + </section> + <section id="sect-Reference_Guide-Portal_Navigation_Configuration-User_Navigation"> + <title>User Navigation</title> + <para> + User navigation is the set of nodes and pages that are owned by a user. They are part of the user&apos;s dashboard. </para> - <!-- DOC NOTE: Get an answer on the below! --> <!-- This Paragraph: --> <para> - Two files configure the user navigation (<filename>navigation.xml</filename> and <filename>pages.xml</filename>). They are located in the directory "<filename>02portal.war/WEB-INF/conf/portal/users/{userName}</filename>". +<!-- DOC NOTE: Get an answer on the below! --><!-- This Paragraph: --> <para> + Two files configure the user navigation (<filename>navigation.xml</filename> and <filename>pages.xml</filename>). They are located in the directory &quot;<filename>02portal.war/WEB-INF/conf/portal/users/{userName}</filename>&quot;. </para> - <para> + <para> The file <filename>eXoGadgets.war/WEB-INF/gadget.xml</filename> defines the gadgets that will be available on a user dashboard. </para> - <para> - The example below shows a dashboard with all of the default gadgets included, as well as an extra currency converter gadget sourced from <ulink type="http" url="http://www.google.com/ig/directory?synd=open">Google Gadgets</ulink>. + <para> + The example below shows a dashboard with all of the default gadgets included, as well as an extra currency converter gadget sourced from <ulink url="http://www.google.com/ig/directory?synd=open" type="http">Google Gadgets</ulink>. </para> - -<programlisting language="XML" role="XML"><xi:include href="../../extras/PortalDevelopment_DefaultPortalNavigationConfiguration/gadgets.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - - </section> - - + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/PortalDevelopment_DefaultPortalNavigationConfiguration/gadgets.xml" parse="text"/></programlisting> + </section> </chapter> - Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortalDevelopment/NavigationController.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortalDevelopment/NavigationController.xml 2012-07-05 19:41:59 UTC (rev 8774) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortalDevelopment/NavigationController.xml 2012-07-06 05:00:36 UTC (rev 8775) @@ -1,86 +1,74 @@ -<?xml version='1.0' encoding='utf-8' ?> +<?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" [ <!ENTITY % BOOK_ENTITIES SYSTEM "Reference_Guide.ent"> %BOOK_ENTITIES; ]> <chapter id="chap-Reference_Guide-Navigation_Controller_"> - <title>Navigation Controller </title> - <section id="sect-Reference_Guide-Navigation_Controller_-Description"> - <title>Description</title> - <para> + <title>Navigation Controller </title> + <section id="sect-Reference_Guide-Navigation_Controller_-Description"> + <title>Description</title> + <para> The navigation controller is a major enhancement of JBoss Enterprise Portal Platform that has several goals: </para> - <itemizedlist> - <listitem> - <para> - Provide non ambiguous URLs for portal managed resources such as navigation. Previously different resources were possible for a single URL, even worse, the set of resources available for an URL was depending on one's private navigation (groups and dashboard) + <itemizedlist> + <listitem> + <para> + Provide non ambiguous URLs for portal managed resources such as navigation. Previously different resources were possible for a single URL, even worse, the set of resources available for an URL was depending on one&apos;s private navigation (groups and dashboard) </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> Decouple the <literal>http</literal> request from the portal request. Previously both were tightly coupled, for instance the URL for a site had to begin with <uri>/public/{sitename}</uri> or <uri>/private/{sitename}</uri>. The navigation controller provides a flexible and configurable mapping. </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> Provide more friendly URL and give a degree of freedom for portal administrators by letting them configure how <literal>http</literal> request should look. </para> - - </listitem> - - </itemizedlist> - - </section> - - <section id="sect-Reference_Guide-Navigation_Controller_-Controller_in_Action"> - <title>Controller in Action</title> - <section id="sect-Reference_Guide-Controller_in_Action-Controller"> - <title>Controller</title> - <para> + </listitem> + </itemizedlist> + </section> + <section id="sect-Reference_Guide-Navigation_Controller_-Controller_in_Action"> + <title>Controller in Action</title> + <section id="sect-Reference_Guide-Controller_in_Action-Controller"> + <title>Controller</title> + <para> The <application>WebAppController</application> is the component of JBoss Enterprise Portal Platform that process <literal>http</literal> invocations and transforms them into a portal request. It has been improved with the addition of a request mapping engine (<emphasis role="bold">controller</emphasis>) whose role is to make the decoupling of the <literal>http</literal> request and create a portal request. </para> - <para> + <para> The mapping engine makes two essential tasks: </para> - <itemizedlist> - <listitem> - <para> + <itemizedlist> + <listitem> + <para> Create a Map&lt;QualifiedName, String&gt; from an incoming <literal>http</literal> request </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> Render a Map&lt;QualifiedName, String&gt; as an <literal>http</literal> URL </para> - - </listitem> - - </itemizedlist> - <para> + </listitem> + </itemizedlist> + <para> The goal of the controller (mapping engine) is to <emphasis role="bold">decouple</emphasis> the request processed by JBoss Enterprise Portal Platform from the incoming <literal>HTTP</literal> request. </para> - <para> + <para> Indeed a request contain data that determines how the request will be processed and such data can be encoded in various places in the request such as the request path or a query parameter. The controller allows JBoss Enterprise Portal Platform route a request according to a set of parameters (a map) instead of the servlet request. </para> - <para> + <para> The controller configuration is declarative in an XML file, allowing easy reconfiguration of the routing table and it is processed into an internal data structure that is used to perform resolution (routing or rendering) </para> - - </section> - - <section id="sect-Reference_Guide-Controller_in_Action-Building_Controller"> - <title>Building Controller</title> - <para> + </section> + <section id="sect-Reference_Guide-Controller_in_Action-Building_Controller"> + <title>Building Controller</title> + <para> The controller configuration that contains the routing rules is loaded from a file named <filename>controller.xml</filename> that is retrieved in the JBoss Enterprise Portal Platform configuration directory. Its location is determined by the <parameter>gatein.controller.config</parameter> property. </para> - <para> - <application>WebAppController</application> loads and initializes the mapping engine + <para> + <application>WebAppController</application> loads and initializes the mapping engine. </para> - -<programlisting language="XML"> + <programlisting language="XML"> &lt;!-- conf/portal/controller-configuration.xml of portal.war --&gt; &lt;component&gt; &lt;type&gt;org.exoplatform.web.WebAppController&lt;/type&gt; @@ -92,686 +80,577 @@ &lt;/init-params&gt; &lt;/component&gt; </programlisting> - <para> - JBoss Enterprise Portal Platform's extension project can define their own routing table, because of the extension mechanism. + <para> + JBoss Enterprise Portal Platform&apos;s extension project can define their own routing table, because of the extension mechanism. </para> - <para> + <para> The <filename>controller.xml</filename> can be changed and reloaded at runtime, this helps the testing of different configurations easily (configuration loading operations) and provide more insight into the routing engine (the <literal>findRoutes</literal> operation). see <emphasis role="bold">Rebuiding controller</emphasis> for more detail </para> - <itemizedlist> - <listitem> - <para> - <emphasis role="bold">ReBuilding controller</emphasis> - </para> - - </listitem> - - </itemizedlist> - <para> - The <application>WebAppController</application> is annotated with <code>@Managed</code> annotations and is bound under the <code>view=portal,service=controller</code> JMX name and under the "portalcontroller" REST name. + <para> + The <application>WebAppController</application> is annotated with <code>@Managed</code> annotations and is bound under the <code>view=portal,service=controller</code> JMX name and under the &quot;portalcontroller&quot; REST name. </para> - <para> + <para> It provides the following attributes and operations </para> - <itemizedlist> - <listitem> - <para> - Attribute configurationPath: the read only the configuration path of the controller xml file + <itemizedlist> + <listitem> + <para> + Attribute configurationPath: the read only configuration path of the controller xml file </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> Operation loadConfiguration: load a new configuration file from a specified xml path </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> Operation reloadConfiguration: reload the configuration file </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> Operation findRoutes: route the request argument through the controller and returns a list of all parameter map resolution. The argument is a request uri such as <uri>/g/:platform:administrators/administration/registry</uri>. It returns a string representation (<code>List&lt;Map&gt;</code>) of the matched routes. </para> - - </listitem> - - </itemizedlist> - - </section> - - <section id="sect-Reference_Guide-Controller_in_Action-Controller_Configuration_controller.xml"> - <title>Controller Configuration (controller.xml)</title> - <para> - Most of the controller configuration cares about defining rules (Routing table - contains routes object) that will drive the resolution. Routes are processed during the controller initialization to give a tree of node. Each node - </para> - <itemizedlist> - <listitem> - <para> + </listitem> + </itemizedlist> + </section> + <section id="sect-Reference_Guide-Controller_in_Action-Controller_Configuration_controller.xml"> + <title>Controller Configuration (controller.xml)</title> + <para> + Most of the controller configuration cares about defining rules (Routing table - contains routes object) that will drive the resolution. Routes are processed during the controller initialization to give a tree of node. Each node: </para> + <itemizedlist> + <listitem> + <para> is related to its parent with a matching rule that can either be an <emphasis role="bold">exact string matching</emphasis> or a <emphasis role="bold">regular expression matching</emphasis> </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> is associated with a set of parameters </para> - - </listitem> - - </itemizedlist> - <para> - A parameter is defined by a qualified name and there are three kind of parameters + </listitem> + </itemizedlist> + <para> A parameter is defined by a qualified name and there are three kind of parameters: Route, Path, and Request. </para> - <section id="sect-Reference_Guide-Controller_Configuration_controller.xml-_Route_parameters_"> - <title> <emphasis role="bold">Route parameters</emphasis> </title> - <para> + <section id="sect-Reference_Guide-Controller_Configuration_controller.xml-_Route_parameters_"> + <title> + <emphasis role="bold">Route parameters</emphasis> + </title> + <para> Route parameters defines a fixed value associate with a qualified name. </para> - <itemizedlist> - <listitem> - <para> + <itemizedlist> + <listitem> + <para> Routing: route parameters allow the controller to distinguish branches easily and route the request accordingly. </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> Rendering: selection occurs when always. </para> - - </listitem> - - </itemizedlist> - <para> + </listitem> + </itemizedlist> + <para> <emphasis role="bold">Example:</emphasis> </para> - -<programlisting language="XML"> -&lt;route path="/foo"&gt; - &lt;route-param qname="gtn:handler"&gt; + <programlisting language="XML"> +&lt;route path=&quot;/foo&quot;&gt; + &lt;route-param qname=&quot;gtn:handler&quot;&gt; &lt;value&gt;portal&lt;/value&gt; &lt;/route-param&gt; &lt;/route&gt; </programlisting> - <para> - This configuration matches the request path "/foo" to the map (gtn:handler=portal). Conversely it renders the (gtn:handler=portal) map as the "/foo" URL. In this example we see two concepts + <para> + This configuration matches the request path &quot;/foo&quot; to the map (gtn:handler=portal). Conversely it renders the (gtn:handler=portal) map as the &quot;/foo&quot; URL. In this example we see two concepts </para> - <itemizedlist> - <listitem> - <para> - exact path matching ("/foo") + <itemizedlist> + <listitem> + <para> + exact path matching (&quot;/foo&quot;) </para> - - </listitem> - <listitem> - <para> - route parameters ("gtn:handler") + </listitem> + <listitem> + <para> + route parameters (&quot;gtn:handler&quot;) </para> - - </listitem> - - </itemizedlist> - - </section> - - <section id="sect-Reference_Guide-Controller_Configuration_controller.xml-_Path_parameters_Regular_expression_support_"> - <title> <emphasis role="bold">Path parameters - <emphasis role="italic">Regular expression support</emphasis> </emphasis> </title> - <para> + </listitem> + </itemizedlist> + </section> + <section id="sect-Reference_Guide-Controller_Configuration_controller.xml-_Path_parameters_Regular_expression_support_"> + <title> + <emphasis role="bold">Path parameters - <emphasis role="italic">Regular expression support</emphasis></emphasis> + </title> + <para> Path parameters allow to associate a portion of the request path with a parameter. Such parameter will match any non empty portion of text except the <emphasis role="bold">/</emphasis> character (that is the [^/]+ regular expression) otherwise they can be associated with a regular expression for matching specific patterns. Path parameters are mandatory for matching since they are part of the request path, however it is allowed to write regular expression matching an empty value. </para> - <itemizedlist> - <listitem> - <para> + <itemizedlist> + <listitem> + <para> Routing: route is accepted if the regular expression is matched. </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> Rendering: selection occurs when the regular expression matches the parameter. </para> - - </listitem> - - </itemizedlist> - <para> + </listitem> + </itemizedlist> + <para> <emphasis role="bold">Encoding</emphasis> </para> - <para> - Path parameters may contain '/' character which is a reserved char for URI path. This case is specially handled by the navigation controller by using a special character to replace '/' literals. By default the character is the semi colon <emphasis role="bold">:</emphasis> and can be changed to other possible values (see controller XML schema for possible values) to give a greater amount of flexibility. + <para> + Path parameters may contain &apos;/&apos; character which is a reserved char for URI path. This case is specially handled by the navigation controller by using a special character to replace &apos;/&apos; literals. By default the character is the semi colon <emphasis role="bold">:</emphasis> and can be changed to other possible values (see controller XML schema for possible values) to give a greater amount of flexibility. </para> - <para> - This encoding is applied only when the encoding performed for parameter having a mode set to the <code>default-form</code> value, for instance it does not happen for navigation node URI (for which <emphasis role="bold">/</emphasis> are encoded literally). The separator escape char can still be used but under it's percent escaped form, so by default a path parameter value containing <emphasis role="bold">:</emphasis> would be encoded as <code>%3A</code> and conversely the <code>%3A</code> value will be decoded as <emphasis role="bold">:</emphasis>. + <para> + This encoding is applied only when the encoding performed for parameter having a mode set to the <code>default-form</code> value, for instance it does not happen for navigation node URI (for which <emphasis role="bold">/</emphasis> are encoded literally). The separator escape char can still be used but under it&apos;s percent escaped form, so by default a path parameter value containing <emphasis role="bold">:</emphasis> would be encoded as <code>%3A</code> and conversely the <code>%3A</code> value will be decoded as <emphasis role="bold">:</emphasis>. </para> - <para> + <para> <emphasis role="bold">Example:</emphasis> </para> - -<programlisting language="XML"> -&lt;route path="/{gtn:path}"&gt; + <programlisting language="XML"> +&lt;route path=&quot;/{gtn:path}&quot;&gt; &lt;/route&gt; </programlisting> - <para> + <para> No pattern defined, used the default one [^/]+ </para> - -<programlisting> + <programlisting> Routing and Rendering -Path "/foo" &lt;--&gt; the map (gtn:path=foo) +Path &quot;/foo&quot; &lt;--&gt; the map (gtn:path=foo) -Path "/foo:bar" &lt;--&gt; the map (gtn:path=foo/bar) +Path &quot;/foo:bar&quot; &lt;--&gt; the map (gtn:path=foo/bar) </programlisting> - <para> - If the request path contains another "/" char it will not work,default encoding mode is: <emphasis role="bold">default-form</emphasis>. For example:"/foo/bar" --&gt; not matched, return empty parameter map + <para> + If the request path contains another &quot;/&quot; char it will not work,default encoding mode is: <emphasis role="bold">default-form</emphasis>. For example:&quot;/foo/bar&quot; --&gt; not matched, return empty parameter map </para> - <para> + <para> However this could be solved with the following configuration: </para> - -<programlisting language="XML"> -&lt;route path="/{gtn:path}"&gt; - &lt;path-param encoding="preserve-path" qname="gtn:path"&gt; + <programlisting language="XML"> +&lt;route path=&quot;/{gtn:path}&quot;&gt; + &lt;path-param encoding=&quot;preserve-path&quot; qname=&quot;gtn:path&quot;&gt; &lt;pattern&gt;.*&lt;/pattern&gt; &lt;/path-param&gt; &lt;/route&gt; </programlisting> - <orderedlist> - <listitem> - <para> + <orderedlist> + <listitem> + <para> The .* declaration allows to match any char sequence. </para> - - </listitem> - <listitem> - <para> - The <emphasis role="italic">preserve-path</emphasis> <emphasis role="bold">encoding</emphasis> tells the engine that the "/" chars should be handled by the path parameter itself as they have a special meaning for the router. Without this special encoding, "/" would be rendered as the ":<emphasis role="italic">" character and conversely the ":</emphasis>" character would be matched as the "/" character. + </listitem> + <listitem> + <para> + The <emphasis role="italic">preserve-path</emphasis> <emphasis role="bold">encoding</emphasis> tells the engine that the &quot;/&quot; chars should be handled by the path parameter itself as they have a special meaning for the router. Without this special encoding, &quot;/&quot; would be rendered as the &quot;:<emphasis role="italic">&quot; character and conversely the &quot;:</emphasis>&quot; character would be matched as the &quot;/&quot; character. </para> - - </listitem> - - </orderedlist> - - </section> - - <section id="sect-Reference_Guide-Controller_Configuration_controller.xml-Request_parameters"> - <title>Request parameters</title> - <para> + </listitem> + </orderedlist> + </section> + <section id="sect-Reference_Guide-Controller_Configuration_controller.xml-Request_parameters"> + <title>Request parameters</title> + <para> Request parameters are matched from the request parameters (GET or POST). The match can be optional as their representation in the request allows it. </para> - <itemizedlist> - <listitem> - <para> + <itemizedlist> + <listitem> + <para> Routing </para> - <itemizedlist> - <listitem> - <para> + <itemizedlist> + <listitem> + <para> route is accepted when a required parameter is present and matched in the request. </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> route is accepted when an optional parameter is absent or matched in the request. </para> - - </listitem> - - </itemizedlist> - - </listitem> - <listitem> - <para> + </listitem> + </itemizedlist> + </listitem> + <listitem> + <para> Rendering: </para> - <itemizedlist> - <listitem> - <para> + <itemizedlist> + <listitem> + <para> selection occurs for required parameters when is the parameter is present and matched in the map. </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> selection occurs for optional parameters when is the parameter is absent or matched in the map. </para> - - </listitem> - - </itemizedlist> - - </listitem> - - </itemizedlist> - <para> + </listitem> + </itemizedlist> + </listitem> + </itemizedlist> + <para> <emphasis role="bold">Example:</emphasis> </para> - -<programlisting language="XML"> -&lt;route path="/"&gt; - &lt;request-param name="path" qname="gtn:path"/&gt; + <programlisting language="XML"> +&lt;route path=&quot;/&quot;&gt; + &lt;request-param name=&quot;path&quot; qname=&quot;gtn:path&quot;/&gt; &lt;/route&gt; </programlisting> - <para> - Request parameters are declared by a <code>request-param</code> element and by default will match any value. A request like "/?path=foo" is mapped to the (gtn:path=foo) map. The <code>name</code> attribute of the <code>request-param</code> tag defines the request parameter value. This element accepts more configuration + <para> + Request parameters are declared by a <code>request-param</code> element and by default will match any value. A request like &quot;/?path=foo&quot; is mapped to the (gtn:path=foo) map. The <code>name</code> attribute of the <code>request-param</code> tag defines the request parameter value. This element accepts more configuration </para> - <itemizedlist> - <listitem> - <para> + <itemizedlist> + <listitem> + <para> a <code>value</code> or a <code>pattern</code> element a child element to match a constant or a pattern </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> a <code>control-mode</code> attribute with the value <code>optional</code> or <code>required</code> to indicate if matching is mandatory or not </para> - - </listitem> - <listitem> - <para> - a <code>value-mapping</code> attribute with the possible values <code>canonical</code>, <code>never-empty</code>, <code>never-null</code> can be used to filter values after matching is done. For instance a parameter configured with <code>value-mapping="never-empty"</code> and matching the empty string value will not put the empty string in the map. + </listitem> + <listitem> + <para> + a <code>value-mapping</code> attribute with the possible values <code>canonical</code>, <code>never-empty</code>, <code>never-null</code> can be used to filter values after matching is done. For instance a parameter configured with <code>value-mapping=&quot;never-empty&quot;</code> and matching the empty string value will not put the empty string in the map. </para> - - </listitem> - - </itemizedlist> - - </section> - - <section id="sect-Reference_Guide-Controller_Configuration_controller.xml-Route_precedence"> - <title>Route precedence</title> - <para> + </listitem> + </itemizedlist> + </section> + <section id="sect-Reference_Guide-Controller_Configuration_controller.xml-Route_precedence"> + <title>Route precedence</title> + <para> The order of route declaration is important as it influence how rules are matched. Sometimes the same request could be matched by several routes and the routing table is ambiguous. </para> - -<programlisting language="XML"> -&lt;route path="/foo"&gt; - &lt;route-param qname="gtn:handler"&gt; + <programlisting language="XML"> +&lt;route path=&quot;/foo&quot;&gt; + &lt;route-param qname=&quot;gtn:handler&quot;&gt; &lt;value&gt;portal&lt;/value&gt; &lt;/route-param&gt; &lt;/route&gt; -&lt;route path="/{gtn:path}"&gt; - &lt;path-param encoding="preserve-path" qname="gtn:path"&gt; +&lt;route path=&quot;/{gtn:path}&quot;&gt; + &lt;path-param encoding=&quot;preserve-path&quot; qname=&quot;gtn:path&quot;&gt; &lt;pattern&gt;.*&lt;/pattern&gt; &lt;/path-param&gt; &lt;/route&gt; </programlisting> - <para> - In that case, the request path "/foo" will always be matched by the first rule before the second rule. This can be misleading since the map (gtn:path=foo) would be rendered as "/foo" as well and would not be matched by the first rule. Such ambiguity can happen, it can be desirable or not. + <para> + In that case, the request path &quot;/foo&quot; will always be matched by the first rule before the second rule. This can be misleading since the map (gtn:path=foo) would be rendered as &quot;/foo&quot; as well and would not be matched by the first rule. Such ambiguity can happen, it can be desirable or not. </para> - - </section> - - <section id="sect-Reference_Guide-Controller_Configuration_controller.xml-Route_nesting"> - <title>Route nesting</title> - <para> + </section> + <section id="sect-Reference_Guide-Controller_Configuration_controller.xml-Route_nesting"> + <title>Route nesting</title> + <para> Route nesting is possible and often desirable as it helps to </para> - <itemizedlist> - <listitem> - <para> + <itemizedlist> + <listitem> + <para> factor common parameters in a common rule </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> perform more efficient matching as the match of the common rule is done once for all the sub routes </para> - - </listitem> - - </itemizedlist> - -<programlisting language="XML"> -&lt;route path="/foo"&gt; - &lt;route-param qname="gtn:handler"&gt; + </listitem> + </itemizedlist> + <programlisting language="XML"> +&lt;route path=&quot;/foo&quot;&gt; + &lt;route-param qname=&quot;gtn:handler&quot;&gt; &lt;value&gt;portal&lt;/value&gt; &lt;/route-param&gt; - &lt;route path="/bar"&gt; - &lt;route-param qname="gtn:path"&gt; + &lt;route path=&quot;/bar&quot;&gt; + &lt;route-param qname=&quot;gtn:path&quot;&gt; &lt;value&gt;bar&lt;/value&gt; &lt;/route-param&gt; &lt;/route&gt; - &lt;route path="/juu"&gt; - &lt;route-param qname="gtn:path"&gt; + &lt;route path=&quot;/juu&quot;&gt; + &lt;route-param qname=&quot;gtn:path&quot;&gt; &lt;value&gt;juu&lt;/value&gt; &lt;/route-param&gt; &lt;/route&gt; &lt;/route&gt; </programlisting> - <itemizedlist> - <listitem> - <para> - The request path "/foo/bar" is mapped to the (gtn:handler=portal,gtn:path=bar) map + <itemizedlist> + <listitem> + <para> + The request path &quot;/foo/bar&quot; is mapped to the (gtn:handler=portal,gtn:path=bar) map </para> - - </listitem> - <listitem> - <para> - The request path "/foo/juu" is mapped to the (gtn:handler=portal,gtn:path=juu) map + </listitem> + <listitem> + <para> + The request path &quot;/foo/juu&quot; is mapped to the (gtn:handler=portal,gtn:path=juu) map </para> - - </listitem> - <listitem> - <para> - The request path "/foo" is not mapped as non leaf routes do not perform matches. + </listitem> + <listitem> + <para> + The request path &quot;/foo&quot; is not mapped as non leaf routes do not perform matches. </para> - - </listitem> - - </itemizedlist> - - </section> - - - </section> - - + </listitem> + </itemizedlist> + </section> </section> - - <section id="sect-Reference_Guide-Navigation_Controller_-Integrate_to_JBoss_Enterprise_Portal_Platform_WebUI_framework"> - <title>Integrate to JBoss Enterprise Portal Platform WebUI framework</title> - <section id="sect-Reference_Guide-Integrate_to_JBoss_Enterprise_Portal_Platform_WebUI_framework-Routing"> - <title>Routing</title> - <para> + </section> + <section id="sect-Reference_Guide-Navigation_Controller_-Integrate_to_JBoss_Enterprise_Portal_Platform_WebUI_framework"> + <title>Integrate to JBoss Enterprise Portal Platform WebUI framework</title> + <section id="sect-Reference_Guide-Integrate_to_JBoss_Enterprise_Portal_Platform_WebUI_framework-Routing"> + <title>Routing</title> + <para> JBoss Enterprise Portal Platform defines a set of parameters in its routing table, for each client request, the mapping engine processes the request path and return the defined parameters with their values as a Map&lt;QualifiedName, String&gt; </para> - <para> + <para> <emphasis role="bold">gtn:handler</emphasis> </para> - <para> - The gtn:handler names is one of the most important qualified name as it determines which handler will take care of the request processing just after the controller has determined the parameter map. The handler value is used to make a lookup in the handler map of the controller. An handler is a class that extends the <code>WebRequestHandler</code> class and implements the <code>execute(ControllerContext)</code> method. Several handlers are available by default: + <para> + The gtn:handler name is one of the most important qualified names as it determines which handler will take care of the request processing just after the controller has determined the parameter map. The handler value is used to make a lookup in the handler map of the controller. A handler is a class that extends the <code>WebRequestHandler</code> class and implements the <code>execute(ControllerContext)</code> method. Several handlers are available by default: </para> - <itemizedlist> - <listitem> - <para> + <itemizedlist> + <listitem> + <para> portal: process aggregated portal requests </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> upload / download: process file upload and file download </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> legacy: handle legacy URL redirection (see <emphasis role="bold">Legacy handler</emphasis> section) </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> default: <literal>http</literal> redirection to the default portal of the container </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> staticResource: serve static resources like image, css or javascript... files in portal.war (see <emphasis role="bold">Static Resource Handler</emphasis> section) </para> - - </listitem> - - </itemizedlist> - <para> + </listitem> + </itemizedlist> + <para> <emphasis role="bold">gtn:sitetype / gtn:sitename / gtn:path</emphasis> </para> - <para> + <para> Those qualified names drives a request for the portal handler. They are used to determine which site to show and which path to resolve against a navigation. For instance the (gtn:sitetype=portal,gtn:sitename=classic,gtn:path=home) instruct the portal handler to show the home page of the classic portal site. </para> - <para> + <para> <emphasis role="bold">gtn:lang</emphasis> </para> - <para> + <para> The language in the URL for the portal handler. This is a new feature offered, now language can be specified on URL. that mean user can bookmark that URL (with the information about language) or he can changed language simply by modifying the URL address </para> - <para> + <para> <emphasis role="bold">gtn:componentid / gtn:action / gtn:objectid</emphasis> </para> - <para> + <para> The webui parameters used by the portal handler for managing webui component URLs for portal applications (and not for portlet applications). </para> - - </section> - - <section id="sect-Reference_Guide-Integrate_to_JBoss_Enterprise_Portal_Platform_WebUI_framework-Rendering"> - <title>Rendering</title> - <para> + </section> + <section id="sect-Reference_Guide-Integrate_to_JBoss_Enterprise_Portal_Platform_WebUI_framework-Rendering"> + <title>Rendering</title> + <para> The <emphasis role="bold">controller</emphasis> is designed to render a Map&lt;QualifiedName, String&gt; as an <literal>http</literal> URL according to its routing table. But to integrate it for using easily in WebUI Framework of JBoss Enterprise Portal Platform, we need some more components </para> - <section id="sect-Reference_Guide-Rendering-_PortalURL_"> - <title> <emphasis role="bold">PortalURL</emphasis> </title> - <para> + <section id="sect-Reference_Guide-Rendering-_PortalURL_"> + <title> + <emphasis role="bold">PortalURL</emphasis> + </title> + <para> <code>PortalURL</code> play a similar role at the portal level, its main role is to abstract the creation of an URL for a resource managed by the portal. </para> - -<programlisting language="Java"> + <programlisting language="Java"> public abstract class PortalURL&lt;R, U extends PortalURL&lt;U&gt;&gt; { ... } </programlisting> - <para> - The <code>PortalURL</code> declaration may seem a bit strange at first sight with two generic types <code>U</code> and <code>R</code> and the circular recursion of the <code>U</code> generic parameter, but it's because most of the time you will not use the <code>PortalURL</code> object but instead subclasses. + <para> + The <code>PortalURL</code> declaration may seem a bit strange at first sight with two generic types <code>U</code> and <code>R</code> and the circular recursion of the <code>U</code> generic parameter, but it&apos;s because most of the time you will not use the <code>PortalURL</code> object but instead subclasses. </para> - <itemizedlist> - <listitem> - <para> + <itemizedlist> + <listitem> + <para> The <code>R</code> generic type represents the type of the resource managed by the portal </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> The <code>U</code> generic type is also described as <emphasis role="bold">self bound generic type</emphasis>. This design pattern allows a class to return subtypes of itself in the class declaring the generic type. Java Enums are based on this principle (<code>class Enum&lt;E extends Enum&lt;E&gt;&gt;</code>) </para> - - </listitem> - - </itemizedlist> - <para> + </listitem> + </itemizedlist> + <para> A portal URL has various methods but certainly the most important method is the <code>toString()</code> method that generates an URL representing that will target the resource associated with the URL. The remaining methods are getter and setter for mutating the URL configuration, those options will affect the URL representation when it is generated. </para> - <itemizedlist> - <listitem> - <para> + <itemizedlist> + <listitem> + <para> resource: the mandatory resource associated with the URL </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> locale: the optional locale used in the URL allowing the creation of bookmarkable URL containing a language </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> confirm: the optional confirm message displayed by the portal in the context of the portal UI </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> ajax: the optional Ajax option allowing an Ajax invocation of the URL </para> - - </listitem> - - </itemizedlist> - <para> + </listitem> + </itemizedlist> + <para> <emphasis role="bold">Obtaining a PortalURL</emphasis> </para> - <para> + <para> <code>PortalURL</code> objects are obtained from <code>RequestContext</code> instance such as the <code>PortalRequestContext</code> or the PortletRequestContext. Usually those are obtained thanks to <code>getCurrentInstance</code> method of the <code>RequestContext</code> class: </para> - -<programlisting language="Java"> + <programlisting language="Java"> RequestContext ctx = RequestContext.getCurrentInstance(); </programlisting> - <para> + <para> <code>PortalURL</code> are created via to the <code>createURL</code> method that takes as input a resource type. A resource type is usually a constant and is a type safe object that allow to retrieve <code>PortalURL</code> subclasses: </para> - -<programlisting language="Java"> + <programlisting language="Java"> RequestContext ctx = RequestContext.getCurrentInstance(); PortalURL&lt;R, U&gt; URL = ctx.createURL(type); </programlisting> - <para> + <para> In reality you will use a concrete type constant and have instead more concrete code like: </para> - -<programlisting language="Java"> + <programlisting language="Java"> RequestContext ctx = RequestContext.getCurrentInstance(); NodeURL URL = ctx.createURL(NodeURL.TYPE); </programlisting> - <note> - <para> - The <code>NodeURL.TYPE</code> is actually declared as <code>new ResourceType&lt;NavigationResource, NodeURL&gt;()</code> that can be described as a <emphasis role="bold">type literal</emphasis> object emulated by a Java anonymous inner class. Such literal were introduced by Neil Gafter as Super Type Token and popularized by Google Guice as Type Literal. It's an interesting way to create a literal representing a kind of Java type. + <note> + <para> + The <code>NodeURL.TYPE</code> is actually declared as <code>new ResourceType&lt;NavigationResource, NodeURL&gt;()</code> that can be described as a <emphasis role="bold">type literal</emphasis> object emulated by a Java anonymous inner class. Such literal were introduced by Neil Gafter as Super Type Token and popularized by Google Guice as Type Literal. It&apos;s an interesting way to create a literal representing a kind of Java type. </para> - - </note> - - </section> - - <section id="sect-Reference_Guide-Rendering-_Node_URL_"> - <title> <emphasis role="bold">Node URL</emphasis> </title> - <para> + </note> + </section> + <section id="sect-Reference_Guide-Rendering-_Node_URL_"> + <title> + <emphasis role="bold">Node URL</emphasis> + </title> + <para> The class <code>NodeURL</code> is one of the subclass of <code>PortalURL</code> that is specialized for navigation node resources: </para> - -<programlisting language="Java"> + <programlisting language="Java"> public class NodeURL extends PortalURL&lt;NavigationResource, NodeURL&gt; { ... } </programlisting> - <para> + <para> The good news is that the NodeURL does not carry any generic type of its super class, which means that a NodeURL is type safe and one does not have to worry about generic types. </para> - <para> + <para> Using a NodeURL is pretty straightforward: </para> - -<programlisting language="Java"> + <programlisting language="Java"> NodeURL URL = RequestContext.getCurrentInstance().createURL(NodeURL.TYPE); -URL.setResource(new NavigationResource("portal", "classic, "home")); +URL.setResource(new NavigationResource(&quot;portal&quot;, &quot;classic, &quot;home&quot;)); String s = URL.toString(); </programlisting> - <para> + <para> The <code>NodeURL</code> subclass contains specialized setter to make its usage even easier: </para> - -<programlisting language="Java"> + <programlisting language="Java"> UserNode node = ...; NodeURL URL = RequestContext.getCurrentInstance().createURL(NodeURL.TYPE); URL.setNode(node); String s = URL.toString(); </programlisting> - - </section> - - <section id="sect-Reference_Guide-Rendering-_Component_URL_"> - <title> <emphasis role="bold">Component URL</emphasis> </title> - <para> + </section> + <section id="sect-Reference_Guide-Rendering-_Component_URL_"> + <title> + <emphasis role="bold">Component URL</emphasis> + </title> + <para> The <code>ComponentURL</code> subclass is another specialization of <code>PortalURL</code> that allows the creation of WebUI components URLs. <code>ComponentURL</code> is commonly used to trigger WebUI events from client side: </para> - -<programlisting> + <programlisting> &lt;% def componentURL = uicomponent.event(...); /*or uicomponent.URL(...) */ %&gt; &lt;a href=$componentURL&gt;Click me&lt;/a&gt; </programlisting> - <para> + <para> Normally you should not have to deal with it as the WebUI framework has already an abstraction for managing URL known as <code>URLBuilder</code>. The <code>URLBuilder</code> implementation delegates URL creation to <code>ComponentURL</code> objects. </para> - - </section> - - <section id="sect-Reference_Guide-Rendering-Portlet_URLs"> - <title>Portlet URLs</title> - <para> + </section> + <section id="sect-Reference_Guide-Rendering-Portlet_URLs"> + <title>Portlet URLs</title> + <para> Portlet URLs API implementation delegates to the portal <code>ComponentURL</code> (via the portlet container SPI). It is possible to control the language in the URL from a <code>PortletURL</code> object by setting a property named <code>gtn:lang</code>: </para> - <itemizedlist> - <listitem> - <para> + <itemizedlist> + <listitem> + <para> when the property value is set to a value returned by <code>Locale#toString()</code> method for locale objects having a non null language value and a null variant value, the URL generated by the <code>PortletURL#toString()</code> method will contain the locale in the URL. </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> when the property value is set to an empty string, the generated URL will not contain a language. If the incoming URL was carrying a language, this language will be erased. </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> when the property value is not set, it will not affect the generated URL. </para> - - </listitem> - - </itemizedlist> - -<programlisting language="Java"> + </listitem> + </itemizedlist> + <programlisting language="Java"> PortletURL URL = resp.createRenderURL(); -URL.setProperty("gtn:lang", "fr"); -writer.print("&lt;a href='" + URL + "'&gt;French&lt;/a&gt;"); +URL.setProperty(&quot;gtn:lang&quot;, &quot;fr&quot;); +writer.print(&quot;&lt;a href=&apos;&quot; + URL + &quot;&apos;&gt;French&lt;/a&gt;&quot;); </programlisting> - - </section> - - <section id="sect-Reference_Guide-Rendering-Webui_URLBuilder_"> - <title>Webui <code>URLBuilder</code> </title> - <para> + </section> + <section id="sect-Reference_Guide-Rendering-Webui_URLBuilder_"> + <title>Webui <code>URLBuilder</code></title> + <para> This internal API for creating URL works as before and delegates to the <code>PortletURL</code> API when the framework is executed in a portlet and to a <code>ComponentURL</code> API when the framework is executed in the portal context. The API has been modified to take in account the language in URL with two properties on the builder: </para> - <itemizedlist> - <listitem> - <para> + <itemizedlist> + <listitem> + <para> locale: a locale for setting on the URL </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> removeLocale: a boolean for removing the locale present on the URL </para> - - </listitem> - - </itemizedlist> - - </section> - - <section id="sect-Reference_Guide-Rendering-Groovy_Templates"> - <title>Groovy Templates</title> - <para> + </listitem> + </itemizedlist> + </section> + <section id="sect-Reference_Guide-Rendering-Groovy_Templates"> + <title>Groovy Templates</title> + <para> Within a Groovy template the mechanism is the same, however a splash of integration has been done to make creation of NodeURL simpler. A closure is bound under the <code>nodeurl</code> name and is available for invocation anytime. It will simply create a NodeURL object and return it: </para> - -<programlisting language="Java"> + <programlisting language="Java"> UserNode node = ...; NodeURL URL = nodeurl(); URL.setNode(node); String s = URL.toString(); </programlisting> - <para> + <para> The closure <code>nodeurl</code> is bound to Groovy template in <code>WebuiBindingContext</code> </para> - -<programlisting language="Java"> + <programlisting language="Java"> // Closure nodeurl() -put("nodeurl", new Closure(this) +put(&quot;nodeurl&quot;, new Closure(this) { @Override public Object call(Object[] args) @@ -780,16 +659,10 @@ } }); </programlisting> - - </section> - - - </section> - - + </section> </section> - - <!-- <section id="sect-Reference_Guide-Navigation_Controller_-Changes_and_migration_from_JBoss_Enterprise_Portal_Platform_3.1.x"> + </section> +<!-- <section id="sect-Reference_Guide-Navigation_Controller_-Changes_and_migration_from_JBoss_Enterprise_Portal_Platform_3.1.x"> <title>Changes and migration from JBoss Enterprise Portal Platform 5</title> <para> The navigation controller implies a migration of the client code that is coupled to several internal APIs of JBoss Enterprise Portal Platform. As far as we know the major impact is related to anything dealing with URL: @@ -1069,6 +942,4 @@ </section> - </section> --> -</chapter> - + </section> --></chapter> Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/configuration/exo-jcr-configuration.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/configuration/exo-jcr-configuration.xml 2012-07-05 19:41:59 UTC (rev 8774) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/configuration/exo-jcr-configuration.xml 2012-07-06 05:00:36 UTC (rev 8775) @@ -1,14 +1,14 @@ -<?xml version='1.0' encoding='utf-8' ?> +<?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" [ <!ENTITY % BOOK_ENTITIES SYSTEM "Reference_Guide.ent"> %BOOK_ENTITIES; ]> <chapter id="chap-Reference_Guide-JCR_configuration"> - <title>JCR configuration</title> - <para> + <title>JCR configuration</title> + <para> The JCR configuration is defined in an XML file which is constructed as per the DTD below: </para> -<programlisting language="XML" role="XML">&lt;!ELEMENT repository-service (repositories)&gt; + <programlisting language="XML" role="XML">&lt;!ELEMENT repository-service (repositories)&gt; &lt;!ATTLIST repository-service default-repository NMTOKEN #REQUIRED&gt; &lt;!ELEMENT repositories (repository)&gt; &lt;!ELEMENT repository (security-domain,access-control,session-max-age,authentication-policy,workspaces)&gt; @@ -48,738 +48,603 @@ &lt;!ELEMENT persister (properties)&gt; &lt;!ELEMENT properties (property+)&gt; &lt;!ELEMENT property EMPTY&gt;</programlisting> - - <section id="sect-Reference_Guide-JCR_configuration-Portal_configuration"> - <title>Portal configuration</title> - <para> + <section id="sect-Reference_Guide-JCR_configuration-Portal_configuration"> + <title><remark>BZ#812412 </remark>Portal configuration</title> + <para> JCR services are registered in the Portal container. </para> - <para> + <para> Below is an example configuration from the <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/jcr/jcr-configuration.xml</filename> file. </para> - <programlistingco> - <areaspec> - <area coords="10" id="area-Reference_Guide-JCR_configuration-conf-path" /> - <area coords="15" id="area-Reference_Guide-JCR_configuration-working-conf" /> - - </areaspec> - -<programlisting language="XML" role="XML">&lt;component&gt; - &lt;key&gt;org.exoplatform.services.jcr.RepositoryService&lt;/key&gt; - &lt;type&gt;org.exoplatform.services.jcr.impl.RepositoryServiceImpl&lt;/type&gt; -&lt;/component&gt; -&lt;component&gt; - &lt;key&gt;org.exoplatform.services.jcr.config.RepositoryServiceConfiguration&lt;/key&gt; - &lt;type&gt;org.exoplatform.services.jcr.impl.config.RepositoryServiceConfigurationImpl&lt;/type&gt; - &lt;init-params&gt; - &lt;value-param&gt; - &lt;name&gt;conf-path&lt;/name&gt; - &lt;description&gt;JCR repositories configuration file&lt;/description&gt; - &lt;value&gt;jar:/conf/standalone/exo-jcr-config.xml&lt;/value&gt; - &lt;/value-param&gt; - &lt;properties-param&gt; - &lt;name&gt;working-conf&lt;/name&gt; - &lt;description&gt;working-conf&lt;/description&gt; - &lt;property name="source-name" value="jdbcjcr" /&gt; - &lt;property name="dialect" value="hsqldb" /&gt; - &lt;property name="persister-class-name" value="org.exoplatform.services.jcr.impl.config.JDBCConfigurationPersister" /&gt; - &lt;/properties-param&gt; - &lt;/init-params&gt; -&lt;/component&gt;</programlisting> - <calloutlist> - <callout arearefs="area-Reference_Guide-JCR_configuration-conf-path"> - <para> - A path to a RepositoryService JCR Configuration. - </para> - - </callout> - <callout arearefs="area-Reference_Guide-JCR_configuration-working-conf"> - <para> - JCR configuration persister configuration. If no <parameter>working-conf</parameter> is found, the persister will be disabled. - </para> - - </callout> - - </calloutlist> - - </programlistingco> - - <section id="sect-Reference_Guide-Portal_configuration-JCR_Configuration"> - <title>JCR Configuration</title> - <para> + <programlisting linenumbering="numbered" language="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../../code_samples/jcr-configuration.xml_code" parse="text"/></programlisting> + <section id="sect-Reference_Guide-Portal_configuration-JCR_Configuration"> + <title>JCR Configuration</title> + <para> The JCR Service can use multiple <emphasis>Repositories</emphasis> and each repository can have multiple <emphasis>Workspaces</emphasis>. </para> - <para> + <para> Configure the workspaces by locating the workspace you need to modify in <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/jcr/repository-configuration.xml</filename>. </para> - <para> + <para> The repository configuration supports human-readable values. They are not case-sensitive. </para> - <para> + <para> Complete the appropriate element fields using the following value formats: </para> - <variablelist> - <varlistentry> - <term>Number formats:</term> - <listitem> - <para> + <variablelist> + <varlistentry> + <term>Number formats:</term> + <listitem> + <para> <itemizedlist> - <listitem> - <para> + <listitem> + <para> <emphasis role="bold">K</emphasis> or <emphasis role="bold">KB</emphasis> for kilobytes. </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> <emphasis role="bold">M</emphasis> or <emphasis role="bold">MB</emphasis> for megabytes. </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> <emphasis role="bold">G</emphasis> or <emphasis role="bold">GB</emphasis> for gigabytes. </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> <emphasis role="bold">T</emphasis> or <emphasis role="bold">TB</emphasis> for terabytes. </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> Examples: 200K or 200KB; 4M or 4MB; 1.4G or 1.4GB; 10T or 10TB. </para> + </listitem> + </itemizedlist> - </listitem> - - </itemizedlist> - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Time formats:</term> - <listitem> - <para> + </listitem> + </varlistentry> + <varlistentry> + <term>Time formats:</term> + <listitem> + <para> <itemizedlist> - <listitem> - <para> + <listitem> + <para> <emphasis role="bold">ms</emphasis> for milliseconds. </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> <emphasis role="bold">s</emphasis> for seconds. </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> <emphasis role="bold">m</emphasis> for minutes. </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> <emphasis role="bold">h</emphasis> for hours. </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> <emphasis role="bold">d</emphasis> for days. </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> <emphasis role="bold">w</emphasis> for weeks. </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> The default time format is seconds if no other format is specified. </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> Examples: 500ms or 500 milliseconds; 20, 20s or 20 seconds; 30m or 30 minutes; 12h or 12 hours; 5d or 5 days; 4w or 4 weeks. </para> + </listitem> + </itemizedlist> - </listitem> - - </itemizedlist> - </para> - - </listitem> - - </varlistentry> - - </variablelist> - - </section> - - <section id="sect-Reference_Guide-Portal_configuration-Repository_service_configuration_JCR_repositories_configuration"> - <title>Repository service configuration (JCR repositories configuration)</title> - <programlistingco> - <areaspec> - <!-- 1 --> <area coords="1 60" id="area-Reference_Guide-JCR_configuration-Example_of_the_portal_system_workspace-default-repository" /> - <!-- 2 --> <area coords="2 60" id="area-Reference_Guide-JCR_configuration-Example_of_the_portal_system_workspace-repositories" /> - <!-- 3 --> <area coords="3 125" id="area-Reference_Guide-JCR_configuration-Example_of_the_portal_system_workspace-name" /> - <!-- 4 --> <area coords="3 125" id="area-Reference_Guide-JCR_configuration-Example_of_the_portal_system_workspace-default-workspace" /> - <!-- 5 --> <area coords="3 125" id="area-Reference_Guide-JCR_configuration-Example_of_the_portal_system_workspace-system-workspace" /> - <!-- 6 --> <area coords="4 60" id="area-Reference_Guide-JCR_configuration-Example_of_the_portal_system_workspace-security-domain" /> - <!-- 7 --> <area coords="5 60" id="area-Reference_Guide-JCR_configuration-Example_of_the_portal_system_workspace-access-control" /> - <!-- 8 --> <area coords="6 165" id="area-Reference_Guide-JCR_configuration-Example_of_the_portal_system_workspace-authentication-policy" /> - <!-- 9 --> <area coords="9 60" id="area-Reference_Guide-JCR_configuration-Example_of_the_portal_system_workspace-workspaces" /> - <!-- 10 --> <area coords="13 60" id="area-Reference_Guide-JCR_configuration-Example_of_the_portal_system_workspace-workspace-name" /> - <!-- 11 --> <area coords="14 165" id="area-Reference_Guide-JCR_configuration-Example_of_the_portal_system_workspace-container" /> - <!-- 12 --> <area coords="34 165" id="area-Reference_Guide-JCR_configuration-Example_of_the_portal_system_workspace-service_initializer" /> - <!-- 13 --> <area coords="40 165" id="area-Reference_Guide-JCR_configuration-Example_of_the_portal_system_workspace-service_cache" /> - <!-- 14 --> <area coords="48 165" id="area-Reference_Guide-JCR_configuration-Example_of_the_portal_system_workspace-service_query-handler" /> - <!-- 15 --> <area coords="61 60" id="area-Reference_Guide-JCR_configuration-Example_of_the_portal_system_workspace-service_lock-manager-timeout" /> - - </areaspec> - -<programlisting language="XML" role="XML"><xi:include href="../../../../extras/Advanced_Development_JCR_Configuration/orig.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <calloutlist> - <!-- 1 --> <callout arearefs="area-Reference_Guide-JCR_configuration-Example_of_the_portal_system_workspace-default-repository"> - <para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="sect-Reference_Guide-Portal_configuration-Repository_service_configuration_JCR_repositories_configuration"> + <title>Repository service configuration (JCR repositories configuration)</title> + <programlistingco> + <areaspec> +<!-- 1 --> <area coords="1 60" id="area-Reference_Guide-JCR_configuration-Example_of_the_portal_system_workspace-default-repository"/> +<!-- 2 --> <area coords="2 60" id="area-Reference_Guide-JCR_configuration-Example_of_the_portal_system_workspace-repositories"/> +<!-- 3 --> <area coords="3 125" id="area-Reference_Guide-JCR_configuration-Example_of_the_portal_system_workspace-name"/> +<!-- 4 --> <area coords="3 125" id="area-Reference_Guide-JCR_configuration-Example_of_the_portal_system_workspace-default-workspace"/> +<!-- 5 --> <area coords="3 125" id="area-Reference_Guide-JCR_configuration-Example_of_the_portal_system_workspace-system-workspace"/> +<!-- 6 --> <area coords="4 60" id="area-Reference_Guide-JCR_configuration-Example_of_the_portal_system_workspace-security-domain"/> +<!-- 7 --> <area coords="5 60" id="area-Reference_Guide-JCR_configuration-Example_of_the_portal_system_workspace-access-control"/> +<!-- 8 --> <area coords="6 165" id="area-Reference_Guide-JCR_configuration-Example_of_the_portal_system_workspace-authentication-policy"/> +<!-- 9 --> <area coords="9 60" id="area-Reference_Guide-JCR_configuration-Example_of_the_portal_system_workspace-workspaces"/> +<!-- 10 --> <area coords="13 60" id="area-Reference_Guide-JCR_configuration-Example_of_the_portal_system_workspace-workspace-name"/> +<!-- 11 --> <area coords="14 165" id="area-Reference_Guide-JCR_configuration-Example_of_the_portal_system_workspace-container"/> +<!-- 12 --> <area coords="34 165" id="area-Reference_Guide-JCR_configuration-Example_of_the_portal_system_workspace-service_initializer"/> +<!-- 13 --> <area coords="40 165" id="area-Reference_Guide-JCR_configuration-Example_of_the_portal_system_workspace-service_cache"/> +<!-- 14 --> <area coords="48 165" id="area-Reference_Guide-JCR_configuration-Example_of_the_portal_system_workspace-service_query-handler"/> +<!-- 15 --> <area coords="61 60" id="area-Reference_Guide-JCR_configuration-Example_of_the_portal_system_workspace-service_lock-manager-timeout"/> + </areaspec> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../../extras/Advanced_Development_JCR_Configuration/orig.xml" parse="text"/></programlisting> + <calloutlist> +<!-- 1 --> <callout arearefs="area-Reference_Guide-JCR_configuration-Example_of_the_portal_system_workspace-default-repository"> + <para> <emphasis>default-repository</emphasis>: The name of a default repository (one returned by <parameter> RepositoryService.getRepository() </parameter> ). </para> - - </callout> - <!-- 2 --> <callout arearefs="area-Reference_Guide-JCR_configuration-Example_of_the_portal_system_workspace-repositories"> - <para> + </callout> +<!-- 2 --> <callout arearefs="area-Reference_Guide-JCR_configuration-Example_of_the_portal_system_workspace-repositories"> + <para> <emphasis>repositories</emphasis>: The list of repositories. </para> - - </callout> - <!-- 3 --> <callout arearefs="area-Reference_Guide-JCR_configuration-Example_of_the_portal_system_workspace-name"> - <para> + </callout> +<!-- 3 --> <callout arearefs="area-Reference_Guide-JCR_configuration-Example_of_the_portal_system_workspace-name"> + <para> <emphasis>name</emphasis>: The name of a repository. </para> - - </callout> - <!-- 4 --> <callout arearefs="area-Reference_Guide-JCR_configuration-Example_of_the_portal_system_workspace-default-workspace"> - <para> - <emphasis>default-workspace</emphasis>: The name of a workspace obtained using Session's login() or login(Credentials) methods (ones without an explicit workspace name). + </callout> +<!-- 4 --> <callout arearefs="area-Reference_Guide-JCR_configuration-Example_of_the_portal_system_workspace-default-workspace"> + <para> + <emphasis>default-workspace</emphasis>: The name of a workspace obtained using Session&apos;s login() or login(Credentials) methods (ones without an explicit workspace name). </para> - - </callout> - <!-- 5 --> <callout arearefs="area-Reference_Guide-JCR_configuration-Example_of_the_portal_system_workspace-system-workspace"> - <para> + </callout> +<!-- 5 --> <callout arearefs="area-Reference_Guide-JCR_configuration-Example_of_the_portal_system_workspace-system-workspace"> + <para> <emphasis>system-workspace</emphasis>: The name of workspace where <emphasis>/jcr:system</emphasis> node is placed. </para> - - </callout> - <!-- 6 --> <callout arearefs="area-Reference_Guide-JCR_configuration-Example_of_the_portal_system_workspace-security-domain"> - <para> + </callout> +<!-- 6 --> <callout arearefs="area-Reference_Guide-JCR_configuration-Example_of_the_portal_system_workspace-security-domain"> + <para> <emphasis>security-domain</emphasis>: The name of a security domain for JAAS authentication. </para> - - </callout> - <!-- 7 --> <callout arearefs="area-Reference_Guide-JCR_configuration-Example_of_the_portal_system_workspace-access-control"> - <para> + </callout> +<!-- 7 --> <callout arearefs="area-Reference_Guide-JCR_configuration-Example_of_the_portal_system_workspace-access-control"> + <para> <emphasis>access-control</emphasis>: The name of an access control policy. There can be 3 types: optional - ACL is created on-demand(default), disable - no access control, mandatory - an ACL is created for each added node(not supported yet). </para> - - </callout> - <!-- 8 --> <callout arearefs="area-Reference_Guide-JCR_configuration-Example_of_the_portal_system_workspace-authentication-policy"> - <para> + </callout> +<!-- 8 --> <callout arearefs="area-Reference_Guide-JCR_configuration-Example_of_the_portal_system_workspace-authentication-policy"> + <para> <emphasis>authentication-policy</emphasis>: The name of an authentication policy class. </para> - - </callout> - <!-- 9 --> <callout arearefs="area-Reference_Guide-JCR_configuration-Example_of_the_portal_system_workspace-workspaces"> - <para> + </callout> +<!-- 9 --> <callout arearefs="area-Reference_Guide-JCR_configuration-Example_of_the_portal_system_workspace-workspaces"> + <para> <emphasis>workspaces</emphasis>: The list of workspaces. </para> - - </callout> - <!-- 10 --> <callout arearefs="area-Reference_Guide-JCR_configuration-Example_of_the_portal_system_workspace-workspace-name"> - <para> + </callout> +<!-- 10 --> <callout arearefs="area-Reference_Guide-JCR_configuration-Example_of_the_portal_system_workspace-workspace-name"> + <para> The name of the workspace. </para> - - </callout> - <!-- 11 --> <callout arearefs="area-Reference_Guide-JCR_configuration-Example_of_the_portal_system_workspace-container"> - <para> + </callout> +<!-- 11 --> <callout arearefs="area-Reference_Guide-JCR_configuration-Example_of_the_portal_system_workspace-container"> + <para> Workspace data container (physical storage) configuration. </para> - - </callout> - <!-- 12 --> <callout arearefs="area-Reference_Guide-JCR_configuration-Example_of_the_portal_system_workspace-service_initializer"> - <para> + </callout> +<!-- 12 --> <callout arearefs="area-Reference_Guide-JCR_configuration-Example_of_the_portal_system_workspace-service_initializer"> + <para> Workspace initializer configuration. </para> - - </callout> - <!-- 13 --> <callout arearefs="area-Reference_Guide-JCR_configuration-Example_of_the_portal_system_workspace-service_cache"> - <para> + </callout> +<!-- 13 --> <callout arearefs="area-Reference_Guide-JCR_configuration-Example_of_the_portal_system_workspace-service_cache"> + <para> Workspace storage cache configuration. </para> - - </callout> - <!-- 14 --> <callout arearefs="area-Reference_Guide-JCR_configuration-Example_of_the_portal_system_workspace-service_query-handler"> - <para> + </callout> +<!-- 14 --> <callout arearefs="area-Reference_Guide-JCR_configuration-Example_of_the_portal_system_workspace-service_query-handler"> + <para> Query handler configuration. </para> - - </callout> - <!-- 15 --> <callout arearefs="area-Reference_Guide-JCR_configuration-Example_of_the_portal_system_workspace-service_lock-manager-timeout"> - <para> + </callout> +<!-- 15 --> <callout arearefs="area-Reference_Guide-JCR_configuration-Example_of_the_portal_system_workspace-service_lock-manager-timeout"> + <para> The amount of time before the unused global lock is removed. </para> - - </callout> - - </calloutlist> - - </programlistingco> - - <note> - <title><parameter> session-max-age </parameter></title> - <para> + </callout> + </calloutlist> + </programlistingco> + <note> + <title> + <parameter> session-max-age </parameter> + </title> + <para> <emphasis>session-max-age</emphasis>: This parameter is not shown in the example file above as it is not a required setting. It sets the time after which an idle session will be removed (called logout). If it is not set up, an idle session will never be removed. </para> - - </note> - <para> + </note> + <para> <emphasis role="bold">lock-remover-max-threads</emphasis>: Number of threads that can serve LockRemover tasks. Default value is 1. Repository may have many workspaces, each workspace have own LockManager. JCR supports Locks with defined lifetime. Such a lock must be removed is it become expired. That is what LockRemovers does. But LockRemovers is not an independent timer-threads, its a task that executed each 30 seconds. Such a task is served by ThreadPoolExecutor which may use different number of threads. </para> - - </section> - - <section id="sect-Reference_Guide-Portal_configuration-Workspace_configuration"> - <title>Workspace configuration:</title> - <variablelist> - <title></title> - <varlistentry> - <term>name</term> - <listitem> - <para> + </section> + <section id="sect-Reference_Guide-Portal_configuration-Workspace_configuration"> + <title>Workspace configuration:</title> + <variablelist> + <title/> + <varlistentry> + <term>name</term> + <listitem> + <para> The name of a workspace. </para> - </listitem> - </varlistentry> - <varlistentry> - <term>auto-init-root-nodetype</term> - <listitem> - <para> + </listitem> + </varlistentry> + <varlistentry> + <term>auto-init-root-nodetype</term> + <listitem> + <para> DEPRECATED in JCR 1.9 (use initializer). The node type for root node initialization. </para> - </listitem> - </varlistentry> - <varlistentry> - <term>container</term> - <listitem> - <para> + </listitem> + </varlistentry> + <varlistentry> + <term>container</term> + <listitem> + <para> Workspace data container (physical storage) configuration. </para> - </listitem> - </varlistentry> - <varlistentry> - <term>initializer</term> - <listitem> - <para> + </listitem> + </varlistentry> + <varlistentry> + <term>initializer</term> + <listitem> + <para> Workspace initializer configuration. </para> - </listitem> - </varlistentry> - <varlistentry> - <term>cache</term> - <listitem> - <para> + </listitem> + </varlistentry> + <varlistentry> + <term>cache</term> + <listitem> + <para> Workspace storage cache configuration. </para> - </listitem> - </varlistentry> - <varlistentry> - <term>query-handler</term> - <listitem> - <para> + </listitem> + </varlistentry> + <varlistentry> + <term>query-handler</term> + <listitem> + <para> Query handler configuration. </para> - </listitem> - </varlistentry> - <varlistentry> - <term>auto-init-permissions</term> - <listitem> - <para> + </listitem> + </varlistentry> + <varlistentry> + <term>auto-init-permissions</term> + <listitem> + <para> DEPRECATED in JCR 1.9 (use initializer). Default permissions of the root node. It is defined as a set of semicolon-delimited permissions containing a group of space-delimited identities and the type of permission. </para> - <para> - For example, any read; <literal>:/admin read;</literal>:/admin add_node; <literal>:/admin set_property;</literal>:/admin remove means that users from group <literal>admin</literal> have all permissions and other users have only a 'read' permission. + <para> + For example, any read; <literal>:/admin read;</literal>:/admin add_node; <literal>:/admin set_property;</literal>:/admin remove means that users from group <literal>admin</literal> have all permissions and other users have only a &apos;read&apos; permission. </para> - </listitem> - </varlistentry> - </variablelist> - - </section> - - <section id="sect-Reference_Guide-Portal_configuration-Workspace_data_container_configuration"> - <title>Workspace data container configuration:</title> - <variablelist> - <title></title> - <varlistentry> - <term>class</term> - <listitem> - <para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="sect-Reference_Guide-Portal_configuration-Workspace_data_container_configuration"> + <title>Workspace data container configuration:</title> + <variablelist> + <title/> + <varlistentry> + <term>class</term> + <listitem> + <para> A workspace data container class name. </para> - </listitem> - </varlistentry> - <varlistentry> - <term>properties</term> - <listitem> - <para> + </listitem> + </varlistentry> + <varlistentry> + <term>properties</term> + <listitem> + <para> The list of properties (name-value pairs) for the concrete Workspace data container. </para> - </listitem> - </varlistentry> - </variablelist> - - <table id="tabl-Reference_Guide-Workspace_data_container_configuration-Parameter_Descriptions"> - <title>Parameter Descriptions</title> - <tgroup cols="2"> - <thead> - <row> - <entry> - Parameter - </entry> - <entry> - Description - </entry> - - </row> - - </thead> - <tbody> - <row> - <entry> - trigger_events_for_descendents_on_rename - </entry> - <entry> - indicates if need to trigger events for descendants on rename or not. It allows to increase performance on rename operation but in same time Observation is not notified, has default value true - </entry> - - </row> - <row> - <entry> - lazy-node-iterator-page-size - </entry> - <entry> - the page size for lazy iterator. Indicates how many nodes can be retrieved from storage per request. The default value is 100 - </entry> - - </row> - <row> - <entry> - acl-bloomfilter-false-positive-probability - </entry> - <entry> - ACL Bloom-filter desired false positive probability. Range [0..1]. Default value 0.1d. (See the note below) - </entry> - - </row> - <row> - <entry> - acl-bloomfilter-elements-number - </entry> - <entry> - Expected number of ACL-elements in the Bloom-filter. Default value 1000000. (See the note below) - </entry> - - </row> - - </tbody> - - </tgroup> - - </table> - <note> - <para> + </listitem> + </varlistentry> + </variablelist> + <table id="tabl-Reference_Guide-Workspace_data_container_configuration-Parameter_Descriptions"> + <title>Parameter Descriptions</title> + <tgroup cols="2"> + <thead> + <row> + <entry> Parameter </entry> + <entry> Description </entry> + </row> + </thead> + <tbody> + <row> + <entry> trigger_events_for_descendents_on_rename </entry> + <entry> indicates if need to trigger events for descendants on rename or not. It allows to increase performance on rename operation but in same time Observation is not notified, has default value true </entry> + </row> + <row> + <entry> lazy-node-iterator-page-size </entry> + <entry> the page size for lazy iterator. Indicates how many nodes can be retrieved from storage per request. The default value is 100 </entry> + </row> + <row> + <entry> acl-bloomfilter-false-positive-probability </entry> + <entry> ACL Bloom-filter desired false positive probability. Range [0..1]. Default value 0.1d. (See the note below) </entry> + </row> + <row> + <entry> acl-bloomfilter-elements-number </entry> + <entry> Expected number of ACL-elements in the Bloom-filter. Default value 1000000. (See the note below) </entry> + </row> + </tbody> + </tgroup> + </table> + <note> + <para> Bloom filters are not supported by all the cache implementations so far only the implementation for infinispan supports it. </para> - - </note> - <variablelist> - <title></title> - <varlistentry> - <term>value-storage</term> - <listitem> - <para> - The list of value storage plugins. + </note> + <variablelist> + <title/> + <varlistentry> + <term>value-storage</term> + <listitem> + <para> + The list of value storage plug-ins. </para> - </listitem> - </varlistentry> - </variablelist> - - </section> - - <section id="sect-Reference_Guide-Portal_configuration-Value_Storage_plugin_configuration_for_data_container"> - <title>Value Storage plugin configuration (for data container):</title> - <note> - <para> - The value-storage element is optional. If you don't include it, the values will be stored as BLOBs inside the database. + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="sect-Reference_Guide-Portal_configuration-Value_Storage_plugin_configuration_for_data_container"> + <title>Value Storage plug-in configuration (for data container):</title> + <note> + <para> + The value-storage element is optional. If you don&apos;t include it, the values will be stored as BLOBs inside the database. </para> - </note> - <variablelist> - <title></title> - <varlistentry> - <term>value-storage</term> - <listitem> - <para> - Optional value Storage plugin definition. + </note> + <variablelist> + <title/> + <varlistentry> + <term>value-storage</term> + <listitem> + <para> + Optional value Storage plug-in definition. </para> - </listitem> - </varlistentry> - <varlistentry> - <term>class</term> - <listitem> - <para> - A value storage plugin class name (attribute). + </listitem> + </varlistentry> + <varlistentry> + <term>class</term> + <listitem> + <para> + A value storage plug-in class name (attribute). </para> - </listitem> - </varlistentry> - <varlistentry> - <term>properties</term> - <listitem> - <para> - The list of properties (name-value pairs) for a concrete Value Storage plugin. + </listitem> + </varlistentry> + <varlistentry> + <term>properties</term> + <listitem> + <para> + The list of properties (name-value pairs) for a concrete Value Storage plug-in. </para> - </listitem> - </varlistentry> - <varlistentry> - <term>filters</term> - <listitem> - <para> - The list of filters defining conditions when this plugin is applicable. + </listitem> + </varlistentry> + <varlistentry> + <term>filters</term> + <listitem> + <para> + The list of filters defining conditions when this plug-in is applicable. </para> - </listitem> - </varlistentry> - </variablelist> - - </section> - - <section id="sect-Reference_Guide-Portal_configuration-Initializer_configuration_optional"> - <title>Initializer configuration (optional):</title> - <variablelist> - <title></title> - <varlistentry> - <term>class</term> - <listitem> - <para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="sect-Reference_Guide-Portal_configuration-Initializer_configuration_optional"> + <title>Initializer configuration (optional):</title> + <variablelist> + <title/> + <varlistentry> + <term>class</term> + <listitem> + <para> Initializer implementation class. </para> - </listitem> - </varlistentry> - <varlistentry> - <term>properties</term> - <listitem> - <para> + </listitem> + </varlistentry> + <varlistentry> + <term>properties</term> + <listitem> + <para> The list of properties (name-value pairs). Properties are supported. </para> - </listitem> - </varlistentry> - <varlistentry> - <term>root-nodetype</term> - <listitem> - <para> + </listitem> + </varlistentry> + <varlistentry> + <term>root-nodetype</term> + <listitem> + <para> The node type for root node initialization. </para> - </listitem> - </varlistentry> - <varlistentry> - <term>root-permissions</term> - <listitem> - <para> - Default permissions of the root node. It is defined as a set of semicolon-delimited permissions containing a group of space-delimited identities (user, group etc, see Organization service documentation for details) and the type of permission. For example any read; <emphasis role="bold">:/admin read;</emphasis>:/admin add_node; <emphasis role="bold">:/admin set_property;</emphasis>:/admin remove means that users from group <emphasis>admin</emphasis> have all permissions and other users have only a 'read' permission. + </listitem> + </varlistentry> + <varlistentry> + <term>root-permissions</term> + <listitem> + <para> + Default permissions of the root node. It is defined as a set of semicolon-delimited permissions containing a group of space-delimited identities (user, group etc, see Organization service documentation for details) and the type of permission. For example any read; <emphasis role="bold">:/admin read;</emphasis>:/admin add_node; <emphasis role="bold">:/admin set_property;</emphasis>:/admin remove means that users from group <emphasis>admin</emphasis> have all permissions and other users have only a &apos;read&apos; permission. </para> - <para> + <para> Configurable initializer adds a capability to override workspace initial startup procedure (used for Clustering). Also it replaces workspace element parameters auto-init-root-nodetype and auto-init-permissions with root-nodetype and root-permissions. </para> - </listitem> - </varlistentry> - </variablelist> - - </section> - - <section id="sect-Reference_Guide-Portal_configuration-Cache_configuration"> - <title>Cache configuration:</title> - <variablelist> - <title></title> - <varlistentry> - <term>enabled</term> - <listitem> - <para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="sect-Reference_Guide-Portal_configuration-Cache_configuration"> + <title>Cache configuration:</title> + <variablelist> + <title/> + <varlistentry> + <term>enabled</term> + <listitem> + <para> If workspace cache is enabled or not. </para> - </listitem> - </varlistentry> - <varlistentry> - <term>class</term> - <listitem> - <para> + </listitem> + </varlistentry> + <varlistentry> + <term>class</term> + <listitem> + <para> Cache implementation class, optional from 1.9. Default value is. <literal>org.exoplatform.services.jcr.impl.dataflow.persistent.LinkedWorkspaceStorageCacheImpl</literal>. </para> - <para> + <para> Cache can be configured to use concrete implementation of WorkspaceStorageCache interface. JCR core has two implementation to use: </para> - <itemizedlist> - <listitem> - <para> + <itemizedlist> + <listitem> + <para> LinkedWorkspaceStorageCacheImpl - default, with configurable read behavior and statistic. </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> WorkspaceStorageCacheImpl - pre 1.9, still can be used. </para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - <varlistentry> - <term>properties</term> - <listitem> - <para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>properties</term> + <listitem> + <para> The list of properties (name-value pairs) for Workspace cache. </para> - </listitem> - </varlistentry> - <varlistentry> - <term>max-size</term> - <listitem> - <para> + </listitem> + </varlistentry> + <varlistentry> + <term>max-size</term> + <listitem> + <para> Cache maximum size (maxSize prior to v.1.9). </para> - </listitem> - </varlistentry> - <varlistentry> - <term>live-time</term> - <listitem> - <para> + </listitem> + </varlistentry> + <varlistentry> + <term>live-time</term> + <listitem> + <para> Cached item live time (liveTime prior to v.1.9). </para> - <para> + <para> From 1.9 <literal>LinkedWorkspaceStorageCacheImpl</literal> supports additional optional parameters. </para> - </listitem> - </varlistentry> - <varlistentry> - <term>statistic-period</term> - <listitem> - <para> + </listitem> + </varlistentry> + <varlistentry> + <term>statistic-period</term> + <listitem> + <para> Period (time format) of cache statistic thread execution, 5 minutes by default. </para> - </listitem> - </varlistentry> - <varlistentry> - <term>statistic-log</term> - <listitem> - <para> + </listitem> + </varlistentry> + <varlistentry> + <term>statistic-log</term> + <listitem> + <para> If true cache statistic will be printed to default logger (log.info), false by default or not. </para> - </listitem> - </varlistentry> - <varlistentry> - <term>statistic-clean</term> - <listitem> - <para> + </listitem> + </varlistentry> + <varlistentry> + <term>statistic-clean</term> + <listitem> + <para> If true cache statistic will be cleaned after was gathered, false by default or not. </para> - </listitem> - </varlistentry> - <varlistentry> - <term>cleaner-period</term> - <listitem> - <para> + </listitem> + </varlistentry> + <varlistentry> + <term>cleaner-period</term> + <listitem> + <para> Period of the eldest items remover execution, 20 minutes by default. </para> - </listitem> - </varlistentry> - <varlistentry> - <term>blocking-users-count</term> - <listitem> - <para> + </listitem> + </varlistentry> + <varlistentry> + <term>blocking-users-count</term> + <listitem> + <para> Number of concurrent users allowed to read cache storage, 0 - unlimited by default. </para> - </listitem> - </varlistentry> - </variablelist> - - </section> - - <section id="sect-Reference_Guide-Portal_configuration-Query_Handler_configuration"> - <title>Query Handler configuration:</title> - <variablelist> - <title></title> - <varlistentry> - <term>class</term> - <listitem> - <para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="sect-Reference_Guide-Portal_configuration-Query_Handler_configuration"> + <title>Query Handler configuration:</title> + <variablelist> + <title/> + <varlistentry> + <term>class</term> + <listitem> + <para> A Query Handler class name. </para> - </listitem> - </varlistentry> - <varlistentry> - <term>properties</term> - <listitem> - <para> + </listitem> + </varlistentry> + <varlistentry> + <term>properties</term> + <listitem> + <para> The list of properties (name-value pairs) for a Query Handler (indexDir). </para> - <para> + <para> Properties and advanced features described in Search Configuration. </para> - </listitem> - </varlistentry> - </variablelist> - - </section> - - <section id="sect-Reference_Guide-Portal_configuration-Lock_Manager_configuration"> - <title>Lock Manager configuration:</title> - <variablelist> - <title></title> - <varlistentry> - <term>time-out</term> - <listitem> - <para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="sect-Reference_Guide-Portal_configuration-Lock_Manager_configuration"> + <title>Lock Manager configuration:</title> + <variablelist> + <title/> + <varlistentry> + <term>time-out</term> + <listitem> + <para> Time after which the unused global lock will be removed. </para> - </listitem> - </varlistentry> - <varlistentry> - <term>persister</term> - <listitem> - <para> + </listitem> + </varlistentry> + <varlistentry> + <term>persister</term> + <listitem> + <para> A class for storing lock information for future use. For example, remove lock after jcr restart. </para> - </listitem> - </varlistentry> - <varlistentry> - <term>path</term> - <listitem> - <para> + </listitem> + </varlistentry> + <varlistentry> + <term>path</term> + <listitem> + <para> A lock folder. Each workspace has its own one. </para> - </listitem> - </varlistentry> - </variablelist> - </section> - + </listitem> + </varlistentry> + </variablelist> + </section> <!-- <section id="sect-Reference_Guide-Portal_configuration-Help_application_to_prohibit_the_use_of_closed_sessions"> <title>Help application to prohibit the use of closed sessions</title> <para> @@ -807,11 +672,5 @@ </orderedlist> - </section> --> - - - </section> - - + </section> --> </section> </chapter> - Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/configuration/workspace-persistence-storage.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/configuration/workspace-persistence-storage.xml 2012-07-05 19:41:59 UTC (rev 8774) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/configuration/workspace-persistence-storage.xml 2012-07-06 05:00:36 UTC (rev 8775) @@ -1,159 +1,136 @@ -<?xml version='1.0' encoding='utf-8' ?> +<?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" [ <!ENTITY % BOOK_ENTITIES SYSTEM "Reference_Guide.ent"> %BOOK_ENTITIES; ]> <chapter id="chap-Reference_Guide-Workspace_Data_Container"> - <title>Workspace Data Container</title> - <para> - Each Workspace of the JCR has its own persistent storage to hold that workspace's items data. The eXo JCR can be configured so that it can use one or more workspaces that are logical units of the repository content. + <title>Workspace Data Container</title> + <para> + Each Workspace of the JCR has its own persistent storage to hold that workspace&apos;s items data. The eXo JCR can be configured so that it can use one or more workspaces that are logical units of the repository content. </para> - <para> + <para> The physical data storage mechanism is configured using mandatory element <emphasis role="bold">container</emphasis>. The type of container is described in the attribute <parameter>class = <replaceable>fully_qualified_name_of_org.exoplatform.services.jcr.storage.WorkspaceDataContainer_subclass</replaceable></parameter>. For example: </para> - <programlistingco> - <areaspec> - <area coords="3" id="area-Reference_Guide-Workspace_Data_Container-source_name" /> - <area coords="4" id="area-Reference_Guide-Workspace_Data_Container-dialect" /> - <area coords="5" id="area-Reference_Guide-Workspace_Data_Container-multidb" /> - <area coords="6" id="area-Reference_Guide-Workspace_Data_Container-maxbuffer" /> - <area coords="7" id="area-Reference_Guide-Workspace_Data_Container-swap" /> - <area coords="8" id="area-Reference_Guide-Workspace_Data_Container-lazy-node-iterator-page-size" /> - <area coords="9" id="area-Reference_Guide-Workspace_Data_Container-acl-bloomfilter-false-positive-probability" /> - <area coords="10" id="area-Reference_Guide-Workspace_Data_Container-acl-bloomfilter-elements-number" /> - - </areaspec> - -<programlisting language="XML" role="XML">&lt;container class="org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer"&gt; + <programlistingco> + <areaspec> + <area coords="3" id="area-Reference_Guide-Workspace_Data_Container-source_name"/> + <area coords="4" id="area-Reference_Guide-Workspace_Data_Container-dialect"/> + <area coords="5" id="area-Reference_Guide-Workspace_Data_Container-multidb"/> + <area coords="6" id="area-Reference_Guide-Workspace_Data_Container-maxbuffer"/> + <area coords="7" id="area-Reference_Guide-Workspace_Data_Container-swap"/> + <area coords="8" id="area-Reference_Guide-Workspace_Data_Container-lazy-node-iterator-page-size"/> + <area coords="9" id="area-Reference_Guide-Workspace_Data_Container-acl-bloomfilter-false-positive-probability"/> + <area coords="10" id="area-Reference_Guide-Workspace_Data_Container-acl-bloomfilter-elements-number"/> + </areaspec> + <programlisting language="XML" role="XML">&lt;container class=&quot;org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer&quot;&gt; &lt;properties&gt; - &lt;property name="source-name" value="jdbcjcr1"/&gt; - &lt;property name="dialect" value="hsqldb"/&gt; - &lt;property name="multi-db" value="true"/&gt; - &lt;property name="max-buffer-size" value="200K"/&gt; - &lt;property name="swap-directory" value="target/temp/swap/ws"/&gt; - &lt;property name="lazy-node-iterator-page-size" value="50"/&gt; - &lt;property name="acl-bloomfilter-false-positive-probability" value="0.1d"/&gt; - &lt;property name="acl-bloomfilter-elements-number" value="1000000"/&gt; + &lt;property name=&quot;source-name&quot; value=&quot;jdbcjcr1&quot;/&gt; + &lt;property name=&quot;dialect&quot; value=&quot;hsqldb&quot;/&gt; + &lt;property name=&quot;multi-db&quot; value=&quot;true&quot;/&gt; + &lt;property name=&quot;max-buffer-size&quot; value=&quot;200K&quot;/&gt; + &lt;property name=&quot;swap-directory&quot; value=&quot;target/temp/swap/ws&quot;/&gt; + &lt;property name=&quot;lazy-node-iterator-page-size&quot; value=&quot;50&quot;/&gt; + &lt;property name=&quot;acl-bloomfilter-false-positive-probability&quot; value=&quot;0.1d&quot;/&gt; + &lt;property name=&quot;acl-bloomfilter-elements-number&quot; value=&quot;1000000&quot;/&gt; &lt;/properties&gt;</programlisting> - <calloutlist> - <!-- # --> <callout arearefs="area-Reference_Guide-Workspace_Data_Container-source_name"> - <para> + <calloutlist> +<!-- # --> <callout arearefs="area-Reference_Guide-Workspace_Data_Container-source_name"> + <para> <literal>source-name</literal>: The JDBC data source name which is registered in JDNI by InitialContextInitializer. This was known as <literal>sourceName</literal> in versions prior to 1.9. </para> - - </callout> - <!-- # --> <callout arearefs="area-Reference_Guide-Workspace_Data_Container-dialect"> - <para> + </callout> +<!-- # --> <callout arearefs="area-Reference_Guide-Workspace_Data_Container-dialect"> + <para> <literal>dialect</literal>: The database dialect. Must be one of the following: <literal>hsqldb</literal>, <literal>mysql</literal>, <literal>mysql-utf8</literal>, <literal>pgsql</literal>, <literal>oracle</literal>, <literal>oracle-oci</literal>, <literal>mssql</literal>, <literal>sybase</literal>, <literal>derby</literal>, <literal>db2</literal> or <literal>db2v8</literal>). </para> - - </callout> - <!-- # --> <callout arearefs="area-Reference_Guide-Workspace_Data_Container-multidb"> - <para> + </callout> +<!-- # --> <callout arearefs="area-Reference_Guide-Workspace_Data_Container-multidb"> + <para> <literal>multi-db</literal>: This parameter, if <literal>true</literal>, enables multi-database container. </para> - - </callout> - <!-- # --> <callout arearefs="area-Reference_Guide-Workspace_Data_Container-maxbuffer"> - <para> + </callout> +<!-- # --> <callout arearefs="area-Reference_Guide-Workspace_Data_Container-maxbuffer"> + <para> <literal>max-buffer-size</literal>: A threshold in bytes. If a value size is greater than this setting, then it will be spooled to a temporary file. </para> - - </callout> - <!-- # --> <callout arearefs="area-Reference_Guide-Workspace_Data_Container-swap"> - <para> + </callout> +<!-- # --> <callout arearefs="area-Reference_Guide-Workspace_Data_Container-swap"> + <para> <literal>swap-directory</literal>: A location where the value will be spooled if no value storage is configured but a <literal>max-buffer-size</literal> is exceeded. </para> - - </callout> - <!-- # --> <callout arearefs="area-Reference_Guide-Workspace_Data_Container-lazy-node-iterator-page-size"> - <para> - <emphasis role="bold">lazy-node-iterator-page-size</emphasis>: "Lazy" child nodes iterator settings. Defines size of page, the number of nodes that are retrieved from persistent storage at once. + </callout> +<!-- # --> <callout arearefs="area-Reference_Guide-Workspace_Data_Container-lazy-node-iterator-page-size"> + <para> + <emphasis role="bold">lazy-node-iterator-page-size</emphasis>: &quot;Lazy&quot; child nodes iterator settings. Defines size of page, the number of nodes that are retrieved from persistent storage at once. </para> - - </callout> - <!-- # --> <callout arearefs="area-Reference_Guide-Workspace_Data_Container-acl-bloomfilter-false-positive-probability"> - <para> + </callout> +<!-- # --> <callout arearefs="area-Reference_Guide-Workspace_Data_Container-acl-bloomfilter-false-positive-probability"> + <para> <emphasis role="bold">acl-bloomfilter-false-positive-probability</emphasis>: ACL Bloom-filter settings. ACL Bloom-filter desired false positive probability. Range [0..1]. Default value 0.1d. </para> - - </callout> - <!-- # --> <callout arearefs="area-Reference_Guide-Workspace_Data_Container-acl-bloomfilter-elements-number"> - <para> + </callout> +<!-- # --> <callout arearefs="area-Reference_Guide-Workspace_Data_Container-acl-bloomfilter-elements-number"> + <para> <emphasis role="bold">acl-bloomfilter-elements-number</emphasis>: ACL Bloom-filter settings. Expected number of ACL-elements in the Bloom-filter. Default value 1000000. </para> - - </callout> - - </calloutlist> - - </programlistingco> - - <note> - <para> + </callout> + </calloutlist> + </programlistingco> + <note> + <para> Bloom filters are not supported by all the cache implementations so far only the inplementation for infinispan supports it. </para> - <para> + <para> Bloom-filter used to avoid read nodes that definitely do not have ACL. <emphasis role="bold">acl-bloomfilter-false-positive-probability</emphasis> and <emphasis role="bold">acl-bloomfilter-elements-number</emphasis> used to configure such filters. Bloom filters are not supported by all the cache implementations so far only the inplementation for infinispan supports it. </para> - <para> + <para> More about Bloom filters you can read here <ulink url="http://en.wikipedia.org/wiki/Bloom_filter">http://en.wi...;. </para> - - </note> - <para> + </note> + <para> The eXo JCR has a JDBC-based, relational database, production ready <emphasis role="bold">Workspace Data Container</emphasis>. </para> - <para> + <para> Workspace Data Container <emphasis>may</emphasis> support external storages for <literal>javax.jcr.Value</literal> (which can be the case for BLOB values for example) using the optional element <literal>value-storages</literal>. </para> - <para> - The Data Container will try to read or write a Value using the underlying value storage plugin if the filter criteria (see below) match the current property. + <para> + The Data Container will try to read or write a Value using the underlying value storage plug-in if the filter criteria (see below) match the current property. </para> - <programlistingco> - <areaspec> - <area coords="2" id="area-Reference_Guide-Workspace_Data_Container-value_storage" /> - <area coords="6" id="area-Reference_Guide-Workspace_Data_Container-filters" /> - - </areaspec> - -<programlisting language="XML" role="XML">&lt;value-storages&gt; - &lt;value-storage id="Storage #1" class="org.exoplatform.services.jcr.impl.storage.value.fs.TreeFileValueStorage"&gt; + <programlistingco> + <areaspec> + <area coords="2" id="area-Reference_Guide-Workspace_Data_Container-value_storage"/> + <area coords="6" id="area-Reference_Guide-Workspace_Data_Container-filters"/> + </areaspec> + <programlisting language="XML" role="XML">&lt;value-storages&gt; + &lt;value-storage id=&quot;Storage #1&quot; class=&quot;org.exoplatform.services.jcr.impl.storage.value.fs.TreeFileValueStorage&quot;&gt; &lt;properties&gt; - &lt;property name="path" value="data/values"/&gt; + &lt;property name=&quot;path&quot; value=&quot;data/values&quot;/&gt; &lt;/properties&gt; &lt;filters&gt; - &lt;filter property-type="Binary" min-value-size="1M"/&gt;&lt;!-- Values large of 1Mbyte --&gt; + &lt;filter property-type=&quot;Binary&quot; min-value-size=&quot;1M&quot;/&gt;&lt;!-- Values large of 1Mbyte --&gt; &lt;/filters&gt; ......... &lt;/value-storages&gt;</programlisting> - <calloutlist> - <!-- # --> <callout arearefs="area-Reference_Guide-Workspace_Data_Container-value_storage"> - <para> - <literal>value-storage</literal> is the subclass of <literal>org.exoplatform.services.jcr.storage.value.ValueStoragePlugin</literal> and <literal>properties</literal> are optional plugin specific parameters. + <calloutlist> +<!-- # --> <callout arearefs="area-Reference_Guide-Workspace_Data_Container-value_storage"> + <para> + <literal>value-storage</literal> is the subclass of <literal>org.exoplatform.services.jcr.storage.value.ValueStoragePlugin</literal> and <literal>properties</literal> are optional plug-in specific parameters. </para> - - </callout> - <!-- # --> <callout arearefs="area-Reference_Guide-Workspace_Data_Container-filters"> - <para> + </callout> +<!-- # --> <callout arearefs="area-Reference_Guide-Workspace_Data_Container-filters"> + <para> <literal>filters</literal>: Each file value storage can have the filter(s) for incoming values. If there are several filter criteria, they all have to match (AND-Condition). </para> - <para> + <para> A filter can match values by property type (property-type), property name (property-name), ancestor path (ancestor-path) and/or the size of values stored (min-value-size, e.g. 1M, 4.2G, 100 (bytes)). </para> - <para> + <para> In a code sample, we use a filter with property-type and min-value-size only. That means that the storage is only for binary values whose size is greater than 1Mbyte. </para> - <para> + <para> It is recommended that you store properties with large values in a file value storage only. </para> - - </callout> - - </calloutlist> - - </programlistingco> - - + </callout> + </calloutlist> + </programlistingco> </chapter> - Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/data-container.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/data-container.xml 2012-07-05 19:41:59 UTC (rev 8774) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/data-container.xml 2012-07-06 05:00:36 UTC (rev 8775) @@ -1,588 +1,464 @@ -<?xml version='1.0' encoding='utf-8' ?> +<?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" [ <!ENTITY % BOOK_ENTITIES SYSTEM "Reference_Guide.ent"> %BOOK_ENTITIES; ]> <chapter id="chap-Reference_Guide-JCR_Workspace_Data_Container"> - <title>JCR Workspace Data Container</title> - <para> - The JCR Workspace Data Container: - </para> - <itemizedlist> - <listitem> - <para> - Covers the requirements on Workspace Data Container implementation. - </para> - - </listitem> - <listitem> - <para> - Describes container life cycle. - </para> - - </listitem> - <listitem> - <para> - Describes relations between container and high-level DataManagers. - </para> - - </listitem> - - </itemizedlist> - <variablelist id="vari-Reference_Guide-JCR_Workspace_Data_Container-Concepts"> - <title>Concepts</title> - <varlistentry> - <term>Container and connection</term> - <listitem> - <para> - The Workspace Data Container (container) serves Repository Workspace persistent storage. - </para> - <para> - <literal>WorkspacePersistentDataManager</literal> (data manager) uses the container to perform <abbrev>CRUD</abbrev> (Create, Read, Update and Delete) operations on the persistent storage. - </para> - <para> - Access to the storage in the data manager is implemented via a storage connection obtained from the container (<literal>WorkspaceDataContainer</literal> interface implementation). - </para> - <para> - Each connection represents a transaction on the storage. Storage Connection (connection) should be an implementation of <literal>WorkspaceStorageConnection</literal>. - </para> - <itemizedlist> - <listitem> - <para> - The Container acts as a factory of a new storage connections. Usually, this method is designed to be synchronized to avoid possible concurrent issues. - </para> - -<programlisting language="Java" role="Java">WorkspaceStorageConnection openConnection() throws RepositoryException; + <title>JCR Workspace Data Container</title> + <para> + The JCR Workspace Data Container: + </para> + <itemizedlist> + <listitem> + <para> + Covers the requirements on Workspace Data Container implementation. + </para> + </listitem> + <listitem> + <para> + Describes container life cycle. + </para> + </listitem> + <listitem> + <para> + Describes relations between container and high-level DataManagers. + </para> + </listitem> + </itemizedlist> + <variablelist id="vari-Reference_Guide-JCR_Workspace_Data_Container-Concepts"> + <title>Concepts</title> + <varlistentry> + <term>Container and connection</term> + <listitem> + <para> + The Workspace Data Container (container) serves Repository Workspace persistent storage. + </para> + <para> + <literal>WorkspacePersistentDataManager</literal> (data manager) uses the container to perform <abbrev>CRUD</abbrev> (Create, Read, Update and Delete) operations on the persistent storage. + </para> + <para> + Access to the storage in the data manager is implemented via a storage connection obtained from the container (<literal>WorkspaceDataContainer</literal> interface implementation). + </para> + <para> + Each connection represents a transaction on the storage. Storage Connection (connection) should be an implementation of <literal>WorkspaceStorageConnection</literal>. + </para> + <itemizedlist> + <listitem> + <para> + The Container acts as a factory of a new storage connections. Usually, this method is designed to be synchronized to avoid possible concurrent issues. + </para> + <programlisting language="Java" role="Java">WorkspaceStorageConnection openConnection() throws RepositoryException; </programlisting> - - </listitem> - <listitem> - <para> - The Storage connection might also be reused. This means reuse of a physical resource (JDBC Connection, for example) allocated by one connection in another. - </para> - <para> - This feature is used in a data manager for saving ordinary and system changes on the system Workspace. But the reuse is an optional feature. If it is not used, a new connection will open. - </para> - -<programlisting language="Java" role="Java">WorkspaceStorageConnection reuseConnection(WorkspaceStorageConnection original) throws RepositoryException; + </listitem> + <listitem> + <para> + The Storage connection might also be reused. This means reuse of a physical resource (JDBC Connection, for example) allocated by one connection in another. + </para> + <para> + This feature is used in a data manager for saving ordinary and system changes on the system Workspace. But the reuse is an optional feature. If it is not used, a new connection will open. + </para> + <programlisting language="Java" role="Java">WorkspaceStorageConnection reuseConnection(WorkspaceStorageConnection original) throws RepositoryException; </programlisting> - - </listitem> - <listitem> - <para> - When checking for the existence of <literal>Same-Name Siblings</literal> (SNS), JCR Core can use either a new connection or an existing one. This behavior is defined via the Workspace Data Container configuration and is retrieved by using the special method: - </para> - -<programlisting language="Java" role="Java">boolean isCheckSNSNewConnection(); + </listitem> + <listitem> + <para> + When checking for the existence of <literal>Same-Name Siblings</literal> (SNS), JCR Core can use either a new connection or an existing one. This behavior is defined via the Workspace Data Container configuration and is retrieved by using the special method: + </para> + <programlisting language="Java" role="Java">boolean isCheckSNSNewConnection(); </programlisting> - - </listitem> - <listitem> - <para> - As container initialization is based solely on a written configuration, it is not possible to change a container's parameters after it has been created. This configuration consists of implementation class(s) and a set of properties and Value Storages configuration. - </para> - - </listitem> - - </itemizedlist> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Value storages</term> - <listitem> - <para> - The container provides an optional special mechanism for <emphasis role="bold">Value</emphasis> storing. It is possible to configure external Value Storages via the container configuration. - </para> - <para> - Value Storage works as fully independent pluggable storage (however some storages are possible for a single container). All required parameters are obtained from the configuration, including the <literal>ValueStoragePluginimplementation</literal> class and a set of implementation specific properties and filters. - </para> - <para> - Filters declare criteria which dictate what Values are stored. This means that the storage might only contain some of the Workspace content. - </para> - <para> - The container obtains Values from Storages with the <literal>ValueStoragePluginProvider</literal> component. This component acts as a factory of Value channels (<literal>ValueIOChannel</literal>). Value Channels provide all CRUD operations for Value Storage, while respecting the transaction manner of work (based on implementation specifics of the storages). - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Lifecycle</term> - <listitem> - <para> - The Container is used for <emphasis>read</emphasis> and <emphasis>write</emphasis> operations by the data manager. - </para> - <para> - Read operations (<emphasis>getters</emphasis>) use the connection once and then closes it. - </para> - <para> - Write operations use the commit method as a sequence of creating and/or updating calls and the final commit (or rollback if an error is encountered). Writes use one connection (plus one for the system workspace) per commit call. One connection guarantees transaction support for write operations. The commit or rollback action should free and/or clean all resources consumed by the container (connection). - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Value storage life-cycle</term> - <listitem> - <para> - Value storage is used from within the container. <emphasis>Read</emphasis> actions are related to container reads while <emphasis>write</emphasis> actions are commit-related. The container (connection) implementation should use transaction capabilities of the storages in the same way as for other operations. - </para> - - </listitem> - - </varlistentry> - - </variablelist> - <section id="sect-Reference_Guide-JCR_Workspace_Data_Container-Requirements"> - <title>Requirements</title> - <para> - Connection creation and reuse should be a thread safe operation. The connection provides <abbrev>CRUD</abbrev> operations support on the storage. - </para> - <itemizedlist id="item-Reference_Guide-Requirements-Read_Operations"> - <title>Read Operations</title> - <listitem> - <para> - Read <literal>ItemData</literal> from the storage by item identifier: - </para> - -<programlisting language="Java" role="Java">ItemData getItemData(String identifier) throws RepositoryException, IllegalStateException; + </listitem> + <listitem> + <para> + As container initialization is based solely on a written configuration, it is not possible to change a container&apos;s parameters after it has been created. This configuration consists of implementation class(s) and a set of properties and Value Storages configuration. + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>Value storages</term> + <listitem> + <para> + The container provides an optional special mechanism for <emphasis role="bold">Value</emphasis> storing. It is possible to configure external Value Storages via the container configuration. + </para> + <para> + Value Storage works as fully independent pluggable storage (however some storages are possible for a single container). All required parameters are obtained from the configuration, including the <literal>ValueStoragePluginimplementation</literal> class and a set of implementation specific properties and filters. + </para> + <para> + Filters declare criteria which dictate what Values are stored. This means that the storage might only contain some of the Workspace content. + </para> + <para> + The container obtains Values from Storages with the <literal>ValueStoragePluginProvider</literal> component. This component acts as a factory of Value channels (<literal>ValueIOChannel</literal>). Value Channels provide all CRUD operations for Value Storage, while respecting the transaction manner of work (based on implementation specifics of the storages). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Lifecycle</term> + <listitem> + <para> + The Container is used for <emphasis>read</emphasis> and <emphasis>write</emphasis> operations by the data manager. + </para> + <para> + Read operations (<emphasis>getters</emphasis>) use the connection once and then closes it. + </para> + <para> + Write operations use the commit method as a sequence of creating and/or updating calls and the final commit (or rollback if an error is encountered). Writes use one connection (plus one for the system workspace) per commit call. One connection guarantees transaction support for write operations. The commit or rollback action should free and/or clean all resources consumed by the container (connection). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Value storage life-cycle</term> + <listitem> + <para> + Value storage is used from within the container. <emphasis>Read</emphasis> actions are related to container reads while <emphasis>write</emphasis> actions are commit-related. The container (connection) implementation should use transaction capabilities of the storages in the same way as for other operations. + </para> + </listitem> + </varlistentry> + </variablelist> + <section id="sect-Reference_Guide-JCR_Workspace_Data_Container-Requirements"> + <title>Requirements</title> + <para> + Connection creation and reuse should be a thread safe operation. The connection provides <abbrev>CRUD</abbrev> operations support on the storage. + </para> + <itemizedlist id="item-Reference_Guide-Requirements-Read_Operations"> + <title>Read Operations</title> + <listitem> + <para> + Read <literal>ItemData</literal> from the storage by item identifier: + </para> + <programlisting language="Java" role="Java">ItemData getItemData(String identifier) throws RepositoryException, IllegalStateException; </programlisting> - - </listitem> - <listitem> - <para> - Read <literal>ItemData</literal> from the storage by using the parent and name of the item, related to the parent location: - </para> - -<programlisting language="Java" role="Java">ItemData getItemData(NodeData parentData, QPathEntry name) throws RepositoryException,IllegalStateException; + </listitem> + <listitem> + <para> + Read <literal>ItemData</literal> from the storage by using the parent and name of the item, related to the parent location: + </para> + <programlisting language="Java" role="Java">ItemData getItemData(NodeData parentData, QPathEntry name) throws RepositoryException,IllegalStateException; </programlisting> - - </listitem> - <listitem> - <para> - Read List of <literal>NodeData</literal> from the storage by using the parent location of the item: - </para> - -<programlisting language="Java" role="Java">List&lt;NodeData&gt; getChildNodesData(NodeData parent) throws RepositoryException, IllegalStateException; + </listitem> + <listitem> + <para> + Read List of <literal>NodeData</literal> from the storage by using the parent location of the item: + </para> + <programlisting language="Java" role="Java">List&lt;NodeData&gt; getChildNodesData(NodeData parent) throws RepositoryException, IllegalStateException; </programlisting> - - </listitem> - <listitem> - <para> - Read List of <literal>PropertyData</literal> from the storage by using the parent location of the item: - </para> - -<programlisting language="Java" role="Java">List&lt;PropertyData&gt; getChildPropertiesData(NodeData parent) throws RepositoryException, IllegalStateException; + </listitem> + <listitem> + <para> + Read List of <literal>PropertyData</literal> from the storage by using the parent location of the item: + </para> + <programlisting language="Java" role="Java">List&lt;PropertyData&gt; getChildPropertiesData(NodeData parent) throws RepositoryException, IllegalStateException; </programlisting> - - </listitem> - <listitem> - <para> - Read List of <literal>PropertyData</literal> with empty <literal>ValueData</literal> from the storage by using the parent location of the item: - </para> - <para> - This method is specifically dedicated to non-content modification operations (Items delete, for example). - </para> - -<programlisting language="Java" role="Java">List&lt;PropertyData&gt; listChildPropertiesData(NodeData parent) throws RepositoryException, IllegalStateException; + </listitem> + <listitem> + <para> + Read List of <literal>PropertyData</literal> with empty <literal>ValueData</literal> from the storage by using the parent location of the item: + </para> + <para> + This method is specifically dedicated to non-content modification operations (Items delete, for example). + </para> + <programlisting language="Java" role="Java">List&lt;PropertyData&gt; listChildPropertiesData(NodeData parent) throws RepositoryException, IllegalStateException; </programlisting> - - </listitem> - <listitem> - <para> - Read List of <literal>PropertyData</literal> from the storage by using the parent location of the item: - </para> - <para> - It's REFERENCE type: Properties referencing Node with given <literal>nodeIdentifier</literal>. See more in <literal>javax.jcr.Node.getReferences()</literal> - </para> - -<programlisting language="Java" role="Java">List&lt;PropertyData&gt; getReferencesData(String nodeIdentifier) throws RepositoryException,IllegalStateException,UnsupportedOperationException; + </listitem> + <listitem> + <para> + Read List of <literal>PropertyData</literal> from the storage by using the parent location of the item: + </para> + <para> + It&apos;s REFERENCE type: Properties referencing Node with given <literal>nodeIdentifier</literal>. See more in <literal>javax.jcr.Node.getReferences()</literal> + </para> + <programlisting language="Java" role="Java">List&lt;PropertyData&gt; getReferencesData(String nodeIdentifier) throws RepositoryException,IllegalStateException,UnsupportedOperationException; </programlisting> - - </listitem> - - </itemizedlist> - <itemizedlist id="item-Reference_Guide-Requirements-Write_Operations"> - <title>Write Operations</title> - <listitem> - <para> - Add single <literal>NodeData</literal>. - </para> - -<programlisting language="Java" role="Java">void add(NodeData data) throws RepositoryException,UnsupportedOperationException,InvalidItemStateException,IllegalStateException; + </listitem> + </itemizedlist> + <itemizedlist id="item-Reference_Guide-Requirements-Write_Operations"> + <title>Write Operations</title> + <listitem> + <para> + Add single <literal>NodeData</literal>. + </para> + <programlisting language="Java" role="Java">void add(NodeData data) throws RepositoryException,UnsupportedOperationException,InvalidItemStateException,IllegalStateException; </programlisting> - - </listitem> - <listitem> - <para> - Add single <literal>PropertyData</literal>: - </para> - -<programlisting language="Java" role="Java">void add(PropertyData data) throws RepositoryException,UnsupportedOperationException,InvalidItemStateException,IllegalStateException; + </listitem> + <listitem> + <para> + Add single <literal>PropertyData</literal>: + </para> + <programlisting language="Java" role="Java">void add(PropertyData data) throws RepositoryException,UnsupportedOperationException,InvalidItemStateException,IllegalStateException; </programlisting> - - </listitem> - <listitem> - <para> - Update <literal>NodeData</literal>: - </para> - -<programlisting language="Java" role="Java">void update(NodeData data) throws RepositoryException,UnsupportedOperationException,InvalidItemStateException,IllegalStateException; + </listitem> + <listitem> + <para> + Update <literal>NodeData</literal>: + </para> + <programlisting language="Java" role="Java">void update(NodeData data) throws RepositoryException,UnsupportedOperationException,InvalidItemStateException,IllegalStateException; </programlisting> - - </listitem> - <listitem> - <para> - Update <literal>PropertyData</literal>: - </para> - -<programlisting language="Java" role="Java">void update(PropertyData data) throws RepositoryException,UnsupportedOperationException,InvalidItemStateException,IllegalStateException; + </listitem> + <listitem> + <para> + Update <literal>PropertyData</literal>: + </para> + <programlisting language="Java" role="Java">void update(PropertyData data) throws RepositoryException,UnsupportedOperationException,InvalidItemStateException,IllegalStateException; </programlisting> - - </listitem> - <listitem> - <para> - Rename <literal>NodeData</literal> by using Node identifier and new name and indexing from the data: - </para> - -<programlisting language="Java" role="Java">void rename(NodeData data) throws RepositoryException,UnsupportedOperationException,InvalidItemStateException,IllegalStateException; + </listitem> + <listitem> + <para> + Rename <literal>NodeData</literal> by using Node identifier and new name and indexing from the data: + </para> + <programlisting language="Java" role="Java">void rename(NodeData data) throws RepositoryException,UnsupportedOperationException,InvalidItemStateException,IllegalStateException; </programlisting> - - </listitem> - <listitem> - <para> - Delete <literal>NodeData</literal>: - </para> - -<programlisting language="Java" role="Java">void delete(NodeData data) throws RepositoryException,UnsupportedOperationException,InvalidItemStateException,IllegalStateException; + </listitem> + <listitem> + <para> + Delete <literal>NodeData</literal>: + </para> + <programlisting language="Java" role="Java">void delete(NodeData data) throws RepositoryException,UnsupportedOperationException,InvalidItemStateException,IllegalStateException; </programlisting> - - </listitem> - <listitem> - <para> - Delete <literal>PropertyData</literal>: - </para> - -<programlisting language="Java" role="Java">void delete(PropertyData data) throws RepositoryException,UnsupportedOperationException,InvalidItemStateException,IllegalStateException; + </listitem> + <listitem> + <para> + Delete <literal>PropertyData</literal>: + </para> + <programlisting language="Java" role="Java">void delete(PropertyData data) throws RepositoryException,UnsupportedOperationException,InvalidItemStateException,IllegalStateException; </programlisting> - - </listitem> - <listitem> - <para> - Persist changes and closes connection. It can be database transaction commit for instance etc. - </para> - -<programlisting language="Java" role="Java">void commit() throws IllegalStateException, RepositoryException; + </listitem> + <listitem> + <para> + Persist changes and closes connection. It can be database transaction commit for instance etc. + </para> + <programlisting language="Java" role="Java">void commit() throws IllegalStateException, RepositoryException; </programlisting> - - </listitem> - <listitem> - <para> - Refuse persistent changes and closes connection. It can be database transaction rollback for instance etc. - </para> - -<programlisting language="Java" role="Java">void rollback() throws IllegalStateException, RepositoryException; + </listitem> + <listitem> + <para> + Refuse persistent changes and closes connection. It can be database transaction rollback for instance etc. + </para> + <programlisting language="Java" role="Java">void rollback() throws IllegalStateException, RepositoryException; </programlisting> - <para> - All methods throw <literal>IllegalStateException</literal> if the connection is closed, <literal>UnsupportedOperationException</literal> if the method is not supported and <literal>RepositoryException</literal> if some errors occur during preparation, validation or persistence. - </para> - - </listitem> - - </itemizedlist> - <itemizedlist id="item-Reference_Guide-Requirements-State_Operations"> - <title>State Operations</title> - <listitem> - <para> - Return true if connection can be used: - </para> - -<programlisting language="Java" role="Java">boolean isOpened(); + <para> + All methods throw <literal>IllegalStateException</literal> if the connection is closed, <literal>UnsupportedOperationException</literal> if the method is not supported and <literal>RepositoryException</literal> if some errors occur during preparation, validation or persistence. + </para> + </listitem> + </itemizedlist> + <itemizedlist id="item-Reference_Guide-Requirements-State_Operations"> + <title>State Operations</title> + <listitem> + <para> + Return true if connection can be used: + </para> + <programlisting language="Java" role="Java">boolean isOpened(); </programlisting> - - </listitem> - - </itemizedlist> - <itemizedlist id="item-Reference_Guide-Requirements-Validation_of_write_operations"> - <title>Validation of write operations</title> - <listitem> - <para> - As the container has to care about storage consistency (JCR constraints) on write operations: (InvalidItemStateException should be thrown according the spec). At least, the following checks should be performed: - </para> - - </listitem> - <listitem> - <itemizedlist id="item-Reference_Guide-Validation_of_write_operations-On_ADD_errors"> - <title>On ADD errors</title> - <listitem> - <itemizedlist> - <listitem> - <para> - Parent not found. Condition: Parent ID (Item with ID is not exists). - </para> - - </listitem> - <listitem> - <para> - Item already exists. Condition: ID (Item with ID already exists). - </para> - - </listitem> - <listitem> - <para> - Item already exists. Condition: Parent ID, Name, Index (Item with parent ID, name and index already exists). - </para> - - </listitem> - - </itemizedlist> - - </listitem> - - </itemizedlist> - - </listitem> - <listitem> - <itemizedlist id="item-Reference_Guide-Validation_of_write_operations-On_DELETE_errors"> - <title>On DELETE errors</title> - <listitem> - <itemizedlist> - <listitem> - <para> - Item not found. Condition ID. - </para> - - </listitem> - <listitem> - <para> - Can not delete parent till children exists. - </para> - - </listitem> - - </itemizedlist> - - </listitem> - - </itemizedlist> - - </listitem> - <listitem> - <itemizedlist id="item-Reference_Guide-Validation_of_write_operations-On_UPDATE_errors"> - <title>On UPDATE errors</title> - <listitem> - <itemizedlist> - <listitem> - <para> - Item not found. Condition ID. - </para> - - </listitem> - <listitem> - <para> - Item already exists with higher Version. Condition: ID, Version (Some Session had updated Item with ID prior this update). - </para> - - </listitem> - - </itemizedlist> - - </listitem> - - </itemizedlist> - - </listitem> - - </itemizedlist> - <itemizedlist id="item-Reference_Guide-Requirements-Consistency_of_save"> - <title>Consistency of save</title> - <listitem> - <para> - The container (connection) should implement consistency of Commit (Rollback) to allow a reversion of applied changes should an operation fail before a commit. - </para> - - </listitem> - - </itemizedlist> - <itemizedlist id="item-Reference_Guide-Requirements-Value_storages_API"> - <title>Value storages API</title> - <listitem> - <itemizedlist id="item-Reference_Guide-Value_storages_API-Storages_provider"> - <title>Storages provider:</title> - <listitem> - <para> - The container implementation obtains Values Storages options via the <literal>ValueStoragePluginProvider</literal> component. The <literal>ValueStoragePluginProvider</literal> acts as a factory for Value channels (ValueIOChannel) and has two methods for this purpose: - </para> - <itemizedlist> - <listitem> - <para> - Return <literal>ValueIOChannel</literal> matched this property and <literal>valueOrderNumer</literal>. Null will be returned if no channel matches. - </para> - -<programlisting language="Java" role="Java">ValueIOChannel getApplicableChannel(PropertyData property, int valueOrderNumer) throws IOException; + </listitem> + </itemizedlist> + <itemizedlist id="item-Reference_Guide-Requirements-Validation_of_write_operations"> + <title>Validation of write operations</title> + <listitem> + <para> + As the container has to care about storage consistency (JCR constraints) on write operations: (InvalidItemStateException should be thrown according the spec). At least, the following checks should be performed: + </para> + </listitem> + <listitem> + <itemizedlist id="item-Reference_Guide-Validation_of_write_operations-On_ADD_errors"> + <title>On ADD errors</title> + <listitem> + <itemizedlist> + <listitem> + <para> + Parent not found. Condition: Parent ID (Item with ID is not exists). + </para> + </listitem> + <listitem> + <para> + Item already exists. Condition: ID (Item with ID already exists). + </para> + </listitem> + <listitem> + <para> + Item already exists. Condition: Parent ID, Name, Index (Item with parent ID, name and index already exists). + </para> + </listitem> + </itemizedlist> + </listitem> + </itemizedlist> + </listitem> + <listitem> + <itemizedlist id="item-Reference_Guide-Validation_of_write_operations-On_DELETE_errors"> + <title>On DELETE errors</title> + <listitem> + <itemizedlist> + <listitem> + <para> + Item not found. Condition ID. + </para> + </listitem> + <listitem> + <para> + Can not delete parent till children exists. + </para> + </listitem> + </itemizedlist> + </listitem> + </itemizedlist> + </listitem> + <listitem> + <itemizedlist id="item-Reference_Guide-Validation_of_write_operations-On_UPDATE_errors"> + <title>On UPDATE errors</title> + <listitem> + <itemizedlist> + <listitem> + <para> + Item not found. Condition ID. + </para> + </listitem> + <listitem> + <para> + Item already exists with higher Version. Condition: ID, Version (Some Session had updated Item with ID prior this update). + </para> + </listitem> + </itemizedlist> + </listitem> + </itemizedlist> + </listitem> + </itemizedlist> + <itemizedlist id="item-Reference_Guide-Requirements-Consistency_of_save"> + <title>Consistency of save</title> + <listitem> + <para> + The container (connection) should implement consistency of Commit (Rollback) to allow a reversion of applied changes should an operation fail before a commit. + </para> + </listitem> + </itemizedlist> + <itemizedlist id="item-Reference_Guide-Requirements-Value_storages_API"> + <title>Value storages API</title> + <listitem> + <itemizedlist id="item-Reference_Guide-Value_storages_API-Storages_provider"> + <title>Storages provider:</title> + <listitem> + <para> + The container implementation obtains Values Storages options via the <literal>ValueStoragePluginProvider</literal> component. The <literal>ValueStoragePluginProvider</literal> acts as a factory for Value channels (ValueIOChannel) and has two methods for this purpose: + </para> + <itemizedlist> + <listitem> + <para> + Return <literal>ValueIOChannel</literal> matched this property and <literal>valueOrderNumer</literal>. Null will be returned if no channel matches. + </para> + <programlisting language="Java" role="Java">ValueIOChannel getApplicableChannel(PropertyData property, int valueOrderNumer) throws IOException; </programlisting> - - </listitem> - <listitem> - <para> - Return <literal>ValueIOChannel</literal> associated with given storageId. - </para> - -<programlisting language="Java" role="Java">ValueIOChannel getChannel(String storageId) throws IOException, ValueStorageNotFoundException; + </listitem> + <listitem> + <para> + Return <literal>ValueIOChannel</literal> associated with given storageId. + </para> + <programlisting language="Java" role="Java">ValueIOChannel getChannel(String storageId) throws IOException, ValueStorageNotFoundException; </programlisting> - - </listitem> - - </itemizedlist> - - </listitem> - <listitem> - <para> - There is also a method for a consistency check, however this method is not used in this storage implementation. - </para> - - </listitem> - - </itemizedlist> - - </listitem> - <listitem> - <itemizedlist id="item-Reference_Guide-Value_storages_API-Value_storage_plugin"> - <title>Value storage plugin</title> - <listitem> - <para> - The provider implementation should use the <literal>ValueStoragePlugin</literal> abstract class as a base for all storage implementations. Plugins provide support for provider implementation methods. A plugin's methods should be implemented as follows: - </para> - - </listitem> - <listitem> - <itemizedlist> - <listitem> - <para> - Initialize the plugin to be used at start up in <literal>ValueStoragePluginProvider</literal>. - </para> - -<programlisting language="Java" role="Java">public abstract void init(Properties props, ValueDataResourceHolder resources) throws RepositoryConfigurationException, IOException; + </listitem> + </itemizedlist> + </listitem> + <listitem> + <para> + There is also a method for a consistency check, however this method is not used in this storage implementation. + </para> + </listitem> + </itemizedlist> + </listitem> + <listitem> + <itemizedlist id="item-Reference_Guide-Value_storages_API-Value_storage_plugin"> + <title>Value storage plug-in</title> + <listitem> + <para> + The provider implementation should use the <literal>ValueStoragePlugin</literal> abstract class as a base for all storage implementations. Plug-ins provide support for provider implementation methods. A plug-in&apos;s methods should be implemented as follows: + </para> + </listitem> + <listitem> + <itemizedlist> + <listitem> + <para> + Initialize the plug-in to be used at start up in <literal>ValueStoragePluginProvider</literal>. + </para> + <programlisting language="Java" role="Java">public abstract void init(Properties props, ValueDataResourceHolder resources) throws RepositoryConfigurationException, IOException; </programlisting> - - </listitem> - <listitem> - <para> - Open <literal>ValueIOChannel</literal>. Used in <literal>ValueStoragePluginProvider.getApplicableChannel(PropertyData, int)</literal> and <literal>getChannel(String)</literal>: - </para> - -<programlisting language="Java" role="Java">public abstract ValueIOChannel openIOChannel() throws IOException; + </listitem> + <listitem> + <para> + Open <literal>ValueIOChannel</literal>. Used in <literal>ValueStoragePluginProvider.getApplicableChannel(PropertyData, int)</literal> and <literal>getChannel(String)</literal>: + </para> + <programlisting language="Java" role="Java">public abstract ValueIOChannel openIOChannel() throws IOException; </programlisting> - - </listitem> - <listitem> - <para> - Return <literal>true</literal> if this storage has the same <literal>storageId</literal>. - </para> - -<programlisting language="Java" role="Java">public abstract boolean isSame(String valueDataDescriptor); + </listitem> + <listitem> + <para> + Return <literal>true</literal> if this storage has the same <literal>storageId</literal>. + </para> + <programlisting language="Java" role="Java">public abstract boolean isSame(String valueDataDescriptor); </programlisting> - - </listitem> - - </itemizedlist> - - </listitem> - - </itemizedlist> - - </listitem> - <listitem> - <itemizedlist id="item-Reference_Guide-Value_storages_API-Value_IO_channel"> - <title>Value I/O channel</title> - <listitem> - <para> - The channel should implement an <literal>ValueIOChannel</literal> interface. The CRUD operation for Value Storage are: - </para> - - </listitem> - <listitem> - <itemizedlist> - <listitem> - <para> - Read Property value: - </para> - -<programlisting language="Java" role="Java">ValueData read(String propertyId, int orderNumber, int maxBufferSize) throws IOException; + </listitem> + </itemizedlist> + </listitem> + </itemizedlist> + </listitem> + <listitem> + <itemizedlist id="item-Reference_Guide-Value_storages_API-Value_IO_channel"> + <title>Value I/O channel</title> + <listitem> + <para> + The channel should implement an <literal>ValueIOChannel</literal> interface. The CRUD operation for Value Storage are: + </para> + </listitem> + <listitem> + <itemizedlist> + <listitem> + <para> + Read Property value: + </para> + <programlisting language="Java" role="Java">ValueData read(String propertyId, int orderNumber, int maxBufferSize) throws IOException; </programlisting> - - </listitem> - <listitem> - <para> - Add or update Property value: - </para> - -<programlisting language="Java" role="Java">void write(String propertyId, ValueData data) throws IOException; + </listitem> + <listitem> + <para> + Add or update Property value: + </para> + <programlisting language="Java" role="Java">void write(String propertyId, ValueData data) throws IOException; </programlisting> - - </listitem> - <listitem> - <para> - Delete All Property values: - </para> - -<programlisting language="Java" role="Java">void delete(String propertyId) throws IOException; + </listitem> + <listitem> + <para> + Delete All Property values: + </para> + <programlisting language="Java" role="Java">void delete(String propertyId) throws IOException; </programlisting> - - </listitem> - - </itemizedlist> - - </listitem> - - </itemizedlist> - - </listitem> - <listitem> - <itemizedlist id="item-Reference_Guide-Value_storages_API-Transaction_support_via_channel"> - <title>Transaction support via channel</title> - <listitem> - <para> - Modification operations should be applied only when committing. Rollback is required for data created cleanup. - </para> - - </listitem> - <listitem> - <itemizedlist> - <listitem> - <para> - Commit channel changes: - </para> - -<programlisting language="Java" role="Java">void commit() throws IOException; + </listitem> + </itemizedlist> + </listitem> + </itemizedlist> + </listitem> + <listitem> + <itemizedlist id="item-Reference_Guide-Value_storages_API-Transaction_support_via_channel"> + <title>Transaction support via channel</title> + <listitem> + <para> + Modification operations should be applied only when committing. Rollback is required for data created cleanup. + </para> + </listitem> + <listitem> + <itemizedlist> + <listitem> + <para> + Commit channel changes: + </para> + <programlisting language="Java" role="Java">void commit() throws IOException; </programlisting> - - </listitem> - <listitem> - <para> - Rollback channel changes: - </para> - -<programlisting language="Java" role="Java">void rollback() throws IOException; + </listitem> + <listitem> + <para> + Rollback channel changes: + </para> + <programlisting language="Java" role="Java">void rollback() throws IOException; </programlisting> - - </listitem> - - </itemizedlist> - - </listitem> - - </itemizedlist> - - </listitem> - - </itemizedlist> - - </section> - - + </listitem> + </itemizedlist> + </listitem> + </itemizedlist> + </listitem> + </itemizedlist> + </section> </chapter> - Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/jbosscache-configuration-templates.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/jbosscache-configuration-templates.xml 2012-07-05 19:41:59 UTC (rev 8774) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/jbosscache-configuration-templates.xml 2012-07-06 05:00:36 UTC (rev 8775) @@ -1,191 +1,118 @@ -<?xml version='1.0' encoding='utf-8' ?> +<?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" [ <!ENTITY % BOOK_ENTITIES SYSTEM "Reference_Guide.ent"> %BOOK_ENTITIES; ]> <chapter id="chap-Reference_Guide-JBoss_Cache_configuration"> - <title>JBoss Cache configuration</title> - <section id="sect-Reference_Guide-JBoss_Cache_configuration-Indexer_lock_manager_and_data_container_configuration"> - <title>Indexer, lock manager and data container configuration</title> - <para> + <title>JBoss Cache configuration</title> + <section id="sect-Reference_Guide-JBoss_Cache_configuration-Indexer_lock_manager_and_data_container_configuration"> + <title>Indexer, lock manager and data container configuration</title> + <para> Each mentioned component uses instances of the JBoss Cache product for caching in clustered environment. So every element has its own transport and has to be configured correctly. As usual, workspaces have similar configuration differing only in cluster-names (and, possibly, some other parameters). The simplest way to configure them is to define their own configuration files for each component in each workspace: </para> - -<programlisting language="XML" role="XML">&lt;property name="jbosscache-configuration" value="conf/standalone - /test-jbosscache-lock-db1-ws1.xml" /&gt;</programlisting> - <para> - But if there are few workspaces, configuring them in such a way can be painful and hard-manageable. eXo JCR offers a template-based configuration for JBoss Cache instances. You can have one template for Lock Manager, one for Indexer and one for data container and use them in all the workspaces, defining the map of substitution parameters in a main configuration file. Just simply define ${jbosscache-&lt;parameter name&gt;} inside xml-template and list correct value in JCR configuration file just below "jbosscache-configuration", as shown: + <programlisting language="XML" role="XML">&lt;property name=&quot;jbosscache-configuration&quot; value=&quot;conf/standalone + /test-jbosscache-lock-db1-ws1.xml&quot; /&gt;</programlisting> + <para> + But if there are few workspaces, configuring them in such a way can be painful and hard-manageable. eXo JCR offers a template-based configuration for JBoss Cache instances. You can have one template for Lock Manager, one for Indexer and one for data container and use them in all the workspaces, defining the map of substitution parameters in a main configuration file. Just simply define ${jbosscache-&lt;parameter name&gt;} inside xml-template and list correct value in JCR configuration file just below &quot;jbosscache-configuration&quot;, as shown: </para> - <para> + <para> Template: </para> - -<programlisting language="XML" role="XML">... -&lt;clustering mode="replication" clusterName="${jbosscache-cluster-name}"&gt; - &lt;stateRetrieval timeout="20000" fetchInMemoryState="false" /&gt; + <programlisting language="XML" role="XML">... +&lt;clustering mode=&quot;replication&quot; clusterName=&quot;${jbosscache-cluster-name}&quot;&gt; + &lt;stateRetrieval timeout=&quot;20000&quot; fetchInMemoryState=&quot;false&quot; /&gt; ...</programlisting> - <para> + <para> and JCR configuration file: </para> - -<programlisting language="XML" role="XML">... -&lt;property name="jbosscache-configuration" value="jar:/conf/portal/jbosscache-lock.xml" /&gt; -&lt;property name="jbosscache-cluster-name" value="JCR-cluster-locks-db1-ws" /&gt; + <programlisting language="XML" role="XML">... +&lt;property name=&quot;jbosscache-configuration&quot; value=&quot;jar:/conf/portal/jbosscache-lock.xml&quot; /&gt; +&lt;property name=&quot;jbosscache-cluster-name&quot; value=&quot;JCR-cluster-locks-db1-ws&quot; /&gt; ...</programlisting> - - </section> - - <section id="sect-Reference_Guide-JBoss_Cache_configuration-JGroups_configuration"> - <title>JGroups configuration</title> - <para> + </section> + <section id="sect-Reference_Guide-JBoss_Cache_configuration-JGroups_configuration"> + <title>JGroups configuration</title> + <para> JGroups is used by JBoss Cache for network communications and transport in a clustered environment. If the property is defined in component configuration, it will be injected into the JBoss Cache instance on start up. </para> - -<programlisting language="XML" role="XML">&lt;property name="jgroups-configuration" value="your/path/to/modified-udp.xml" /&gt;</programlisting> - <para> + <programlisting language="XML" role="XML">&lt;property name=&quot;jgroups-configuration&quot; value=&quot;your/path/to/modified-udp.xml&quot; /&gt;</programlisting> + <para> As outlined above, each component (lock manager, data container and query handler) for each workspace requires its own clustered environment. In other words, they have their own clusters with unique names. </para> - <para> + <para> Each cluster should, by default, perform multi-casts on a separate port. This configuration leads to much unnecessary overhead on cluster. This is why JGroups offers a multiplexer feature, providing ability to use one single channel for set of clusters. </para> - <para> - The multiplexer reduces network overheads and increase performance and stability of application. To enable multiplexer stack, you should define appropriate configuration file (<filename>upd-mux.xml</filename> is pre-shipped one with eXo JCR) and set "jgroups-multiplexer-stack" into "true". + <para> + The multiplexer reduces network overheads and increase performance and stability of application. To enable multiplexer stack, you should define appropriate configuration file (<filename>upd-mux.xml</filename> is pre-shipped one with eXo JCR) and set &quot;jgroups-multiplexer-stack&quot; into &quot;true&quot;. </para> - -<programlisting language="XML" role="XML">&lt;property name="jgroups-configuration" value="jar:/conf/portal/udp-mux.xml" /&gt; -&lt;property name="jgroups-multiplexer-stack" value="true" /&gt;</programlisting> - - </section> - - <section id="sect-Reference_Guide-JBoss_Cache_configuration-Sharing_JBoss_Cache_instances"> - <title>Sharing JBoss Cache instances</title> - <para> + <programlisting language="XML" role="XML">&lt;property name=&quot;jgroups-configuration&quot; value=&quot;jar:/conf/portal/udp-mux.xml&quot; /&gt; +&lt;property name=&quot;jgroups-multiplexer-stack&quot; value=&quot;true&quot; /&gt;</programlisting> + </section> + <section id="sect-Reference_Guide-JBoss_Cache_configuration-Sharing_JBoss_Cache_instances"> + <title>Sharing JBoss Cache instances</title> + <para> As a single JBoss Cache instance can be demanding on resources, and the default setup will have an instance each for the indexer, the lock manager and the data container on each workspace, an environment that uses multiple workspace may benefit from sharing a JBoss Cache instance between several instances of the same type (the lock manager instance, for example). </para> - <para> + <para> This feature is disabled by default and can be enabled at the component configuration level by setting the <parameter>jbosscache-shareable</parameter> property to <literal>true</literal>: </para> - -<programlisting language="XML" role="XML">&lt;property name="jbosscache-shareable" value="true" /&gt;</programlisting> - <para> + <programlisting language="XML" role="XML">&lt;property name=&quot;jbosscache-shareable&quot; value=&quot;true&quot; /&gt;</programlisting> + <para> Once enabled, this feature will allow the JBoss Cache instance used by a component to be re-used by another components of the same type with the same JBoss Cache configuration (with the exception of the eviction configuration, which can differ). </para> - <para> + <para> This means that all the parameters of type <parameter>jbosscache-<replaceable>&lt;PARAM_NAME&gt;</replaceable></parameter> must be identical between the components of same type of different workspaces. </para> - <para> + <para> Therefore, if you can use the same values for the parameters in each workspace, you only need three JBoss Cache instances (one instance each for the indexer, lock manager and data container) running at once. This can relieve resource stress significantly. </para> - - </section> - - <section id="sect-Reference_Guide-JBoss_Cache_configuration-Shipped_JBoss_Cache_configuration_templates"> - <title>Shipped JBoss Cache configuration templates</title> - <para> - The eXo JCR implementation is shipped with ready-to-use JBoss Cache configuration templates for JCR's components. They are located in <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/jcr/jbosscache</filename> directory, inside either the <filename>cluster</filename> or <filename>local</filename> directory. + </section> + <section id="sect-Reference_Guide-JBoss_Cache_configuration-Shipped_JBoss_Cache_configuration_templates"> + <title>Shipped JBoss Cache configuration templates</title> + <para> + The eXo JCR implementation is shipped with ready-to-use JBoss Cache configuration templates for JCR&apos;s components. They are located in <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/jcr/jbosscache</filename> directory, inside either the <filename>cluster</filename> or <filename>local</filename> directory. </para> - <section id="sect-Reference_Guide-Shipped_JBoss_Cache_configuration_templates-Data_container_template"> - <title>Data container template</title> - <para> + <section id="sect-Reference_Guide-Shipped_JBoss_Cache_configuration_templates-Data_container_template"> + <title>Data container template</title> + <para> The data container template is <filename>config.xml</filename>: </para> - -<programlisting language="XML" role="XML">&lt;?xml version="1.0" encoding="UTF-8"?&gt; -&lt;jbosscache xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="urn:jboss:jbosscache-core:config:3.1"&gt; + <programlisting language="XML" role="XML">&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt; +&lt;jbosscache xmlns:xsi=&quot;http://www.w3.org/2001/XMLSchema-instance&quot; xmlns=&quot;urn:jboss:jbosscache-core:config:3.1&quot;&gt; - &lt;locking useLockStriping="false" concurrencyLevel="50000" lockParentForChildInsertRemove="false" - lockAcquisitionTimeout="20000" /&gt; + &lt;locking useLockStriping=&quot;false&quot; concurrencyLevel=&quot;50000&quot; lockParentForChildInsertRemove=&quot;false&quot; + lockAcquisitionTimeout=&quot;20000&quot; /&gt; - &lt;clustering mode="replication" clusterName="${jbosscache-cluster-name}"&gt; - &lt;stateRetrieval timeout="20000" fetchInMemoryState="false" /&gt; - &lt;jgroupsConfig multiplexerStack="jcr.stack" /&gt; + &lt;clustering mode=&quot;replication&quot; clusterName=&quot;${jbosscache-cluster-name}&quot;&gt; + &lt;stateRetrieval timeout=&quot;20000&quot; fetchInMemoryState=&quot;false&quot; /&gt; + &lt;jgroupsConfig multiplexerStack=&quot;jcr.stack&quot; /&gt; &lt;sync /&gt; &lt;/clustering&gt; &lt;!-- Eviction configuration --&gt; - &lt;eviction wakeUpInterval="5000"&gt; - &lt;default algorithmClass="org.jboss.cache.eviction.LRUAlgorithm" - actionPolicyClass="org.exoplatform.services.jcr.impl.dataflow.persistent.jbosscache.ParentNodeEvictionActionPolicy" - eventQueueSize="1000000"&gt; - &lt;property name="maxNodes" value="1000000" /&gt; - &lt;property name="timeToLive" value="120000" /&gt; + &lt;eviction wakeUpInterval=&quot;5000&quot;&gt; + &lt;default algorithmClass=&quot;org.jboss.cache.eviction.LRUAlgorithm&quot; + actionPolicyClass=&quot;org.exoplatform.services.jcr.impl.dataflow.persistent.jbosscache.ParentNodeEvictionActionPolicy&quot; + eventQueueSize=&quot;1000000&quot;&gt; + &lt;property name=&quot;maxNodes&quot; value=&quot;1000000&quot; /&gt; + &lt;property name=&quot;timeToLive&quot; value=&quot;120000&quot; /&gt; &lt;/default&gt; &lt;/eviction&gt; &lt;/jbosscache&gt;</programlisting> - - </section> - - <section id="sect-Reference_Guide-Shipped_JBoss_Cache_configuration_templates-Lock_manager_template"> - <title>Lock manager template</title> - <para> + </section> + <section id="sect-Reference_Guide-Shipped_JBoss_Cache_configuration_templates-Lock_manager_template"> + <title>Lock manager template</title> + <para> The lock manager template is <filename>lock-config.xml</filename>: </para> - -<programlisting language="XML" role="XML">&lt;?xml version="1.0" encoding="UTF-8"?&gt; -&lt;jbosscache xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="urn:jboss:jbosscache-core:config:3.1"&gt; - - &lt;locking useLockStriping="false" concurrencyLevel="50000" lockParentForChildInsertRemove="false" - lockAcquisitionTimeout="20000" /&gt; - &lt;clustering mode="replication" clusterName="${jbosscache-cluster-name}"&gt; - &lt;stateRetrieval timeout="20000" fetchInMemoryState="false" /&gt; - &lt;jgroupsConfig multiplexerStack="jcr.stack" /&gt; - &lt;sync /&gt; - &lt;/clustering&gt; - &lt;loaders passivation="false" shared="true"&gt; - &lt;preload&gt; - &lt;node fqn="/" /&gt; - &lt;/preload&gt; - &lt;loader class="org.jboss.cache.loader.JDBCCacheLoader" async="false" fetchPersistentState="false" - ignoreModifications="false" purgeOnStartup="false"&gt; - &lt;properties&gt; - cache.jdbc.table.name=${jbosscache-cl-cache.jdbc.table.name} - cache.jdbc.table.create=${jbosscache-cl-cache.jdbc.table.create} - cache.jdbc.table.drop=${jbosscache-cl-cache.jdbc.table.drop} - cache.jdbc.table.primarykey=${jbosscache-cl-cache.jdbc.table.primarykey} - cache.jdbc.fqn.column=${jbosscache-cl-cache.jdbc.fqn.column} - cache.jdbc.fqn.type=${jbosscache-cl-cache.jdbc.fqn.type} - cache.jdbc.node.column=${jbosscache-cl-cache.jdbc.node.column} - cache.jdbc.node.type=${jbosscache-cl-cache.jdbc.node.type} - cache.jdbc.parent.column=${jbosscache-cl-cache.jdbc.parent.column} - cache.jdbc.datasource=${jbosscache-cl-cache.jdbc.datasource} - &lt;/properties&gt; - &lt;/loader&gt; - &lt;/loaders&gt; -&lt;/jbosscache&gt;</programlisting> - - </section> - - <section id="sect-Reference_Guide-Shipped_JBoss_Cache_configuration_templates-Query_handler_indexer_template"> - <title>Query handler (indexer) template</title> - <para> + <programlisting language="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../extras/Advanced_Development_JCR_lock-manager-config/lock-config.xml_code"/></programlisting> + </section> + <section id="sect-Reference_Guide-Shipped_JBoss_Cache_configuration_templates-Query_handler_indexer_template"> + <title>Query handler (indexer) template</title> + <para> The query handler template is called <filename>indexer-config.xml</filename>: </para> - - -<programlisting language="XML" role="XML">&lt;?xml version="1.0" encoding="UTF-8"?&gt; -&lt;jbosscache xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="urn:jboss:jbosscache-core:config:3.1"&gt; - &lt;locking useLockStriping="false" concurrencyLevel="50000" lockParentForChildInsertRemove="false" - lockAcquisitionTimeout="20000" /&gt; - &lt;clustering mode="replication" clusterName="${jbosscache-cluster-name}"&gt; - &lt;stateRetrieval timeout="20000" fetchInMemoryState="false" /&gt; - &lt;jgroupsConfig multiplexerStack="jcr.stack" /&gt; - &lt;sync /&gt; - &lt;/clustering&gt; - &lt;!-- Eviction configuration --&gt; - &lt;eviction wakeUpInterval="5000"&gt; - &lt;default algorithmClass="org.jboss.cache.eviction.FIFOAlgorithm" eventQueueSize="1000000"&gt; - &lt;property name="maxNodes" value="10000" /&gt; - &lt;property name="minTimeToLive" value="60000" /&gt; - &lt;/default&gt; - &lt;/eviction&gt; -&lt;/jbosscache&gt;</programlisting> - - - </section> - - + <programlisting language="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/Advanced_Development_JCR_cluster-config/indexer-config.xml_code" parse="text"/></programlisting> </section> - - + </section> </chapter> - Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/lock-manager-config.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/lock-manager-config.xml 2012-07-05 19:41:59 UTC (rev 8774) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr/lock-manager-config.xml 2012-07-06 05:00:36 UTC (rev 8775) @@ -1,41 +1,39 @@ -<?xml version='1.0' encoding='utf-8' ?> +<?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" [ <!ENTITY % BOOK_ENTITIES SYSTEM "Reference_Guide.ent"> %BOOK_ENTITIES; ]> <chapter id="chap-Reference_Guide-LockManager"> - <title>LockManager</title> - <para> + <title>LockManager</title> + <para> The LockManager stores lock objects. It can lock or release objects as required. It is also responsible for removing stale locks. </para> - <para> + <para> The LockManager in JBoss Enterprise Portal Platform is implemented with <classname>org.exoplatform.services.jcr.impl.core.lock.jbosscache.CacheableLockManagerImpl</classname>. </para> - <para> + <para> It is enabled by adding <literal>lock-manager-configuration</literal> to <literal>workspace-configuration</literal>. </para> - <para> + <para> For example: </para> - -<programlisting language="XML" role="XML"><xi:include href="../../../extras/Advanced_Development_JCR_lock-manager-config/default47.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <section id="sect-Reference_Guide-LockManager-CacheableLockManagerImpl"> - <title>CacheableLockManagerImpl</title> - <para> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/Advanced_Development_JCR_lock-manager-config/default47.xml" parse="text"/></programlisting> + <section id="sect-Reference_Guide-LockManager-CacheableLockManagerImpl"> + <title>CacheableLockManagerImpl</title> + <para> <classname>CacheableLockManagerImpl</classname> stores lock objects in JBoss-cache (which implements JDBCCacheLoader to store locks in a database). This means its locks are replicable and can affect an entire cluster rather than just a single node. </para> - <para> - The length of time LockManager allows a lock to remain in place can be configured with the "<literal>time-out</literal>" property. + <para> + The length of time LockManager allows a lock to remain in place can be configured with the &quot;<literal>time-out</literal>&quot; property. </para> - <para> + <para> The LockRemover thread periodically polls LockManager for locks that have passed the time-out limit and must be removed. </para> - <para> + <para> The time-out for LockRemover is set as follows (the default value is 30m): </para> - -<programlisting language="XML" role="XML"><xi:include href="../../../extras/Advanced_Development_JCR_lock-manager-config/default48.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <!-- Doesn't seem necessary + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/Advanced_Development_JCR_lock-manager-config/default48.xml" parse="text"/></programlisting> +<!-- Doesn't seem necessary <formalpara> <title>Configuration</title> <para> @@ -61,432 +59,293 @@ The <parameter>cache.jdbc.fqn.type</parameter> and <parameter>cache.jdbc.node.type</parameter> parameters must be configured according to the database being used. </para> </listitem> -</itemizedlist> --> <para> +</itemizedlist> --> <para> There are a number of ways to configure <classname>CacheableLockManagerImpl</classname>. Each involves configuring JBoss Cache and JDBCCacheLoader. </para> - <itemizedlist> - <listitem> - <para> - <xref linkend="sect-Reference_Guide-CacheableLockManagerImpl-Simple_JBoss_Cache_Configuration" /> + <itemizedlist> + <listitem> + <para> + <xref linkend="sect-Reference_Guide-CacheableLockManagerImpl-Simple_JBoss_Cache_Configuration"/> </para> - - </listitem> - <listitem> - <para> - <xref linkend="sect-Reference_Guide-CacheableLockManagerImpl-Template_JBoss_Cache_Configuration" /> + </listitem> + <listitem> + <para> + <xref linkend="sect-Reference_Guide-CacheableLockManagerImpl-Template_JBoss_Cache_Configuration"/> </para> - - </listitem> - - </itemizedlist> - <para> + </listitem> + </itemizedlist> + <para> Refer to <ulink url="http://community.jboss.org/wiki/JBossCacheJDBCCacheLoader"... for more information about JBoss Cache and JDBCCacheLoader. </para> - <section id="sect-Reference_Guide-CacheableLockManagerImpl-Simple_JBoss_Cache_Configuration"> - <title>Simple JBoss Cache Configuration</title> - <para> + <section id="sect-Reference_Guide-CacheableLockManagerImpl-Simple_JBoss_Cache_Configuration"> + <title>Simple JBoss Cache Configuration</title> + <para> One method to configure the LockManager is to put a JBoss Cache configuration file path into <classname>CacheableLockManagerImpl</classname>. </para> - <note> - <para> + <note> + <para> This is not the most efficient method for configuring the LockManager as it requires a JBoss Cache configuration file for each LockManager configuration in each workspace of each repository. The configuration set up can subsequently become quite difficult to manage. </para> - <para> + <para> This method is useful, however, if a single, specially configured LockManager is required. </para> - - </note> - <para> + </note> + <para> The required configuration is shown in the example below: </para> - <programlistingco> - <areaspec> - <area coords="4 90" id="area-Reference_Guide-CacheableLockManagerImpl-Simple_JBoss_Cache_Configuration-jbosscache-lock-config.xml" /> - - </areaspec> - -<programlisting language="XML" role="XML"><xi:include href="../../../extras/Advanced_Development_JCR_lock-manager-config/default49.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <calloutlist> - <callout arearefs="area-Reference_Guide-CacheableLockManagerImpl-Simple_JBoss_Cache_Configuration-jbosscache-lock-config.xml"> - <para> - The <replaceable>test-jbosscache-lock-config.xml</replaceable> is shown below. + <programlistingco> + <areaspec> + <area coords="4 90" id="area-Reference_Guide-CacheableLockManagerImpl-Simple_JBoss_Cache_Configuration-jbosscache-lock-config.xml"/> + </areaspec> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/Advanced_Development_JCR_lock-manager-config/default49.xml" parse="text"/></programlisting> + <calloutlist> + <callout arearefs="area-Reference_Guide-CacheableLockManagerImpl-Simple_JBoss_Cache_Configuration-jbosscache-lock-config.xml"> + <para> + The <replaceable>jbosscache-lock-config.xml</replaceable> is shown below. </para> - - </callout> - - </calloutlist> - - </programlistingco> - - <para> - The <filename>test-jbosscache-lock-config.xml</filename> file: + </callout> + </calloutlist> + </programlistingco> + <para> + The <filename>jbosscache-lock-config.xml</filename> file: </para> - <programlistingco> - <areaspec> - <area coords="6 90" id="area-Reference_Guide-CacheableLockManagerImpl-Simple_JBoss_Cache_Configuration-clusterName" /> - <area coords="41 50" id="area-Reference_Guide-CacheableLockManagerImpl-Simple_JBoss_Cache_Configuration-cache.jdbc.table.name" /> - <areaset coords="" id="area-Reference_Guide-CacheableLockManagerImpl-Simple_JBoss_Cache_Configuration-cache.jdbc.types"> - <area coords="48 50" id="area-Reference_Guide-CacheableLockManagerImpl-Simple_JBoss_Cache_Configuration-cache.jdbc.node.type" /> - <area coords="46 50" id="area-Reference_Guide-CacheableLockManagerImpl-Simple_JBoss_Cache_Configuration-cache.jdbc.fqn.type" /> - - </areaset> - - </areaspec> - -<programlisting language="XML" role="XML"><xi:include href="../../../extras/Advanced_Development_JCR_lock-manager-config/default50.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <calloutlist> - <callout arearefs="area-Reference_Guide-CacheableLockManagerImpl-Simple_JBoss_Cache_Configuration-clusterName"> - <para> - The cluster name at <parameter>clustering mode="replication" clusterName="JBoss-Cache-Lock-Cluster_Name"</parameter> must be unique; + <programlistingco> + <areaspec> + <area coords="6 90" id="area-Reference_Guide-CacheableLockManagerImpl-Simple_JBoss_Cache_Configuration-clusterName"/> + <area coords="41 50" id="area-Reference_Guide-CacheableLockManagerImpl-Simple_JBoss_Cache_Configuration-cache.jdbc.table.name"/> + <areaset coords="" id="area-Reference_Guide-CacheableLockManagerImpl-Simple_JBoss_Cache_Configuration-cache.jdbc.types"> + <area coords="48 50" id="area-Reference_Guide-CacheableLockManagerImpl-Simple_JBoss_Cache_Configuration-cache.jdbc.node.type"/> + <area coords="46 50" id="area-Reference_Guide-CacheableLockManagerImpl-Simple_JBoss_Cache_Configuration-cache.jdbc.fqn.type"/> + </areaset> + </areaspec> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/Advanced_Development_JCR_lock-manager-config/default50.xml" parse="text"/></programlisting> + <calloutlist> + <callout arearefs="area-Reference_Guide-CacheableLockManagerImpl-Simple_JBoss_Cache_Configuration-clusterName"> + <para> + The cluster name at <parameter>clustering mode=&quot;replication&quot; clusterName=&quot;JBoss-Cache-Lock-Cluster_Name&quot;</parameter> must be unique; </para> - - </callout> - <callout arearefs="area-Reference_Guide-CacheableLockManagerImpl-Simple_JBoss_Cache_Configuration-cache.jdbc.table.name"> - <para> + </callout> + <callout arearefs="area-Reference_Guide-CacheableLockManagerImpl-Simple_JBoss_Cache_Configuration-cache.jdbc.table.name"> + <para> The <parameter>cache.jdbc.table.name</parameter> must be unique per datasource. </para> - - </callout> - <callout arearefs="area-Reference_Guide-CacheableLockManagerImpl-Simple_JBoss_Cache_Configuration-cache.jdbc.types"> - <para> + </callout> + <callout arearefs="area-Reference_Guide-CacheableLockManagerImpl-Simple_JBoss_Cache_Configuration-cache.jdbc.types"> + <para> The <parameter>cache.jdbc.node.type</parameter> and <parameter>cache.jdbc.fqn.type</parameter> parameters must be configured according to the database in use. </para> - <para> + <para> Refer to the table below for information about data types. </para> - - </callout> - - </calloutlist> - - </programlistingco> - - <table id="tabl-Reference_Guide-Simple_JBoss_Cache_Configuration-Data_Types_in_Different_Databases"> - <title>Data Types in Different Databases</title> - <tgroup cols="3"> - <thead> - <row> - <entry> - DataBase name - </entry> - <entry> - Node data type - </entry> - <entry> - FQN data type - </entry> - - </row> - - </thead> - <tbody> - <row> - <entry> - default - </entry> - <entry> - BLOB - </entry> - <entry> - VARCHAR(512) - </entry> - - </row> - <row> - <entry> - HSSQL - </entry> - <entry> - OBJECT - </entry> - <entry> - VARCHAR(512) - </entry> - - </row> - <row> - <entry> - MySQL - </entry> - <entry> - LONGBLOB - </entry> - <entry> - VARCHAR(512) - </entry> - - </row> - <row> - <entry> - ORACLE - </entry> - <entry> - BLOB - </entry> - <entry> - VARCHAR2(512) - </entry> - - </row> - <row> - <entry> - PostgreSQL - </entry> - <entry> - bytea - </entry> - <entry> - VARCHAR(512) - </entry> - - </row> - <row> - <entry> - MSSQL - </entry> - <entry> - VARBINARY(MAX) - </entry> - <entry> - VARCHAR(512) - </entry> - - </row> - <row> - <entry> - DB2 - </entry> - <entry> - BLOB - </entry> - <entry> - VARCHAR(512) - </entry> - - </row> - <row> - <entry> - Sybase - </entry> - <entry> - IMAGE - </entry> - <entry> - VARCHAR(512) - </entry> - - </row> - - </tbody> - - </tgroup> - - </table> - - </section> - - <section id="sect-Reference_Guide-CacheableLockManagerImpl-Template_JBoss_Cache_Configuration"> - <title>Template JBoss Cache Configuration</title> - <para> + </callout> + </calloutlist> + </programlistingco> + <table id="tabl-Reference_Guide-Simple_JBoss_Cache_Configuration-Data_Types_in_Different_Databases"> + <title>Data Types in Different Databases</title> + <tgroup cols="3"> + <thead> + <row> + <entry> DataBase name </entry> + <entry> Node data type </entry> + <entry> FQN data type </entry> + </row> + </thead> + <tbody> + <row> + <entry> default </entry> + <entry> BLOB </entry> + <entry> VARCHAR(512) </entry> + </row> + <row> + <entry> HSSQL </entry> + <entry> OBJECT </entry> + <entry> VARCHAR(512) </entry> + </row> + <row> + <entry> MySQL </entry> + <entry> LONGBLOB </entry> + <entry> VARCHAR(512) </entry> + </row> + <row> + <entry> ORACLE </entry> + <entry> BLOB </entry> + <entry> VARCHAR2(512) </entry> + </row> + <row> + <entry> PostgreSQL </entry> + <entry> bytea </entry> + <entry> VARCHAR(512) </entry> + </row> + <row> + <entry> MSSQL </entry> + <entry> VARBINARY(MAX) </entry> + <entry> VARCHAR(512) </entry> + </row> + <row> + <entry> DB2 </entry> + <entry> BLOB </entry> + <entry> VARCHAR(512) </entry> + </row> + <row> + <entry> Sybase </entry> + <entry> IMAGE </entry> + <entry> VARCHAR(512) </entry> + </row> + </tbody> + </tgroup> + </table> + </section> + <section id="sect-Reference_Guide-CacheableLockManagerImpl-Template_JBoss_Cache_Configuration"> + <title>Template JBoss Cache Configuration</title> + <para> Another method to configure LockManager is to use a JBoss Cache configuration template for all LockManagers. </para> - <para> + <para> Below is an example <filename>test-jbosscache-lock.xml</filename> template file: </para> - <programlistingco> - <areaspec> - <areaset coords="" id="area-Reference_Guide-CacheableLockManagerImpl-Template_JBoss_Cache_Configuration-cache.jdbc.templates"> - <area coords="24 50" id="area-Reference_Guide-CacheableLockManagerImpl-Template_JBoss_Cache_Configuration-cache.jdbc.table.name" /> - <area coords="35 50" id="area-Reference_Guide-CacheableLockManagerImpl-Template_JBoss_Cache_Configuration-cache.jdbc.datasource" /> - - </areaset> - - </areaspec> - -<programlisting language="XML" role="XML"><xi:include href="../../../extras/Advanced_Development_JCR_lock-manager-config/you.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <calloutlist> - <callout arearefs="area-Reference_Guide-CacheableLockManagerImpl-Template_JBoss_Cache_Configuration-cache.jdbc.templates"> - <para> - All the configurable parameters in this file are populated with templates which will be replaced with LockManager's configuration parameters. + <programlistingco> + <areaspec> + <areaset coords="" id="area-Reference_Guide-CacheableLockManagerImpl-Template_JBoss_Cache_Configuration-cache.jdbc.templates"> + <area coords="24 50" id="area-Reference_Guide-CacheableLockManagerImpl-Template_JBoss_Cache_Configuration-cache.jdbc.table.name"/> + <area coords="35 50" id="area-Reference_Guide-CacheableLockManagerImpl-Template_JBoss_Cache_Configuration-cache.jdbc.datasource"/> + </areaset> + </areaspec> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/Advanced_Development_JCR_lock-manager-config/you.xml" parse="text"/></programlisting> + <calloutlist> + <callout arearefs="area-Reference_Guide-CacheableLockManagerImpl-Template_JBoss_Cache_Configuration-cache.jdbc.templates"> + <para> + All the configurable parameters in this file are populated with templates which will be replaced with LockManager&apos;s configuration parameters. </para> - - </callout> - - </calloutlist> - - </programlistingco> - - <para> + </callout> + </calloutlist> + </programlistingco> + <para> The parameters that will populate the above file are shown below: </para> - <programlistingco> - <areaspec> - <area coords="5 90" id="area-Reference_Guide-CacheableLockManagerImpl-Template_JBoss_Cache_Configuration-udp-mux.xml" /> - <areaset coords="" id="area-Reference_Guide-CacheableLockManagerImpl-Template_JBoss_Cache_Configuration-jbosscache-cl-cache.jdbc.parameters"> - <area coords="12 90" id="area-Reference_Guide-CacheableLockManagerImpl-Template_JBoss_Cache_Configuration-jbosscache-cl-cache.jdbc.fqn.column" /> - <area coords="15 90" id="area-Reference_Guide-CacheableLockManagerImpl-Template_JBoss_Cache_Configuration-jbosscache-cl-cache.jdbc.node.type" /> - - </areaset> - - </areaspec> - -<programlisting language="XML" role="XML"><xi:include href="../../../extras/Advanced_Development_JCR_lock-manager-config/default51.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <calloutlist> - <callout arearefs="area-Reference_Guide-CacheableLockManagerImpl-Template_JBoss_Cache_Configuration-udp-mux.xml"> - <para> + <programlistingco> + <areaspec> + <area coords="5 90" id="area-Reference_Guide-CacheableLockManagerImpl-Template_JBoss_Cache_Configuration-udp-mux.xml"/> + <areaset coords="" id="area-Reference_Guide-CacheableLockManagerImpl-Template_JBoss_Cache_Configuration-jbosscache-cl-cache.jdbc.parameters"> + <area coords="12 90" id="area-Reference_Guide-CacheableLockManagerImpl-Template_JBoss_Cache_Configuration-jbosscache-cl-cache.jdbc.fqn.column"/> + <area coords="15 90" id="area-Reference_Guide-CacheableLockManagerImpl-Template_JBoss_Cache_Configuration-jbosscache-cl-cache.jdbc.node.type"/> + </areaset> + </areaspec> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/Advanced_Development_JCR_lock-manager-config/default51.xml" parse="text"/></programlisting> + <calloutlist> + <callout arearefs="area-Reference_Guide-CacheableLockManagerImpl-Template_JBoss_Cache_Configuration-udp-mux.xml"> + <para> The <literal>jgroups-configuration</literal> has been moved to a separate configuration file (<filename>udp-mux.xml</filename>, shown below). </para> - <para> + <para> In this case the <filename>udp-mux.xml</filename> is a common configuration for all JGroup components (QueryHandler, cache, LockManager), but this is not a requirement of the configuration method. </para> - - </callout> - <callout arearefs="area-Reference_Guide-CacheableLockManagerImpl-Template_JBoss_Cache_Configuration-jbosscache-cl-cache.jdbc.parameters"> - <para> + </callout> + <callout arearefs="area-Reference_Guide-CacheableLockManagerImpl-Template_JBoss_Cache_Configuration-jbosscache-cl-cache.jdbc.parameters"> + <para> The <parameter>jbosscache-cl-cache.jdbc.fqn.column</parameter> and <parameter>jbosscache-cl-cache.jdbc.node.type</parameter> parameters are not explicitly defined as <parameter>cache.jdbc.fqn.type</parameter> and <parameter>cache.jdbc.node.type</parameter> are defined in the JBoss Cache configuration. </para> - <para> - Refer to <xref linkend="tabl-Reference_Guide-Simple_JBoss_Cache_Configuration-Data_Types_in_Different_Databases" /> for information about setting these parameters or set them as <parameter>AUTO</parameter> and the data type will by detected automatically. + <para> + Refer to <xref linkend="tabl-Reference_Guide-Simple_JBoss_Cache_Configuration-Data_Types_in_Different_Databases"/> for information about setting these parameters or set them as <parameter>AUTO</parameter> and the data type will by detected automatically. </para> - - </callout> - - </calloutlist> - - </programlistingco> - - <para> + </callout> + </calloutlist> + </programlistingco> + <para> <filename>udp-mux.xml</filename>: </para> - -<programlisting language="XML" role="XML"><xi:include href="../../../extras/Advanced_Development_JCR_lock-manager-config/default52.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - - </section> - - <section id="sect-Reference_Guide-CacheableLockManagerImpl-Lock_migration_from_1.12.x"> - <title>Lock Migration</title> - <para> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/Advanced_Development_JCR_lock-manager-config/default52.xml" parse="text"/></programlisting> + </section> + <section id="sect-Reference_Guide-CacheableLockManagerImpl-Lock_migration_from_1.12.x"> + <title>Lock Migration</title> + <para> There are three options available: </para> - <variablelist id="vari-Reference_Guide-Lock_migration_from_1.12.x-Lock_Migration_Options"> - <title>Lock Migration Options</title> - <varlistentry> - <term>When new Shareable Cache feature is not going to be used and all locks should be kept after migration.</term> - <listitem> - <procedure> - <title></title> - <step> - <para> + <variablelist id="vari-Reference_Guide-Lock_migration_from_1.12.x-Lock_Migration_Options"> + <title>Lock Migration Options</title> + <varlistentry> + <term>When new Shareable Cache feature is not going to be used and all locks should be kept after migration.</term> + <listitem> + <procedure> + <title/> + <step> + <para> Ensure that the same lock tables are used in configuration </para> - - </step> - <step> - <para> + </step> + <step> + <para> Start the server </para> - - </step> - - </procedure> - - - </listitem> - - </varlistentry> - <varlistentry> - <term>When new Shareable Cache feature is not going to be used and all locks should be removed after migration.</term> - <listitem> - <procedure> - <title></title> - <step> - <para> + </step> + </procedure> + </listitem> + </varlistentry> + <varlistentry> + <term>When new Shareable Cache feature is not going to be used and all locks should be removed after migration.</term> + <listitem> + <procedure> + <title/> + <step> + <para> Ensure that the same lock tables used in configuration </para> - - </step> - <step> - <para> + </step> + <step> + <para> Start the sever WITH system property: </para> - -<programlisting>-Dorg.exoplatform.jcr.locks.force.remove=true + <programlisting>-Dorg.exoplatform.jcr.locks.force.remove=true </programlisting> - - </step> - <step> - <para> + </step> + <step> + <para> Stop the server </para> - - </step> - <step> - <para> + </step> + <step> + <para> Start the server WITHOUT system property: </para> - -<programlisting>-Dorg.exoplatform.jcr.locks.force.remove + <programlisting>-Dorg.exoplatform.jcr.locks.force.remove </programlisting> - - </step> - - </procedure> - - - </listitem> - - </varlistentry> - <varlistentry> - <term>When new Shareable Cache feature will be used (in this case all locks are removed after migration).</term> - <listitem> - <procedure> - <title></title> - <step> - <para> + </step> + </procedure> + </listitem> + </varlistentry> + <varlistentry> + <term>When new Shareable Cache feature will be used (in this case all locks are removed after migration).</term> + <listitem> + <procedure> + <title/> + <step> + <para> Start the sever WITH system property: </para> - -<programlisting>-Dorg.exoplatform.jcr.locks.force.remove=true + <programlisting>-Dorg.exoplatform.jcr.locks.force.remove=true </programlisting> - - </step> - <step> - <para> + </step> + <step> + <para> Stop the server. </para> - - </step> - <step> - <para> + </step> + <step> + <para> Start the server WITHOUT system property: </para> - -<programlisting>-Dorg.exoplatform.jcr.locks.force.remove + <programlisting>-Dorg.exoplatform.jcr.locks.force.remove </programlisting> - - </step> - <step> - <title>Optional:</title> - <para> + </step> + <step> + <title>Optional:</title> + <para> Manually remove old tables for lock. </para> - - </step> - - </procedure> - - - </listitem> - - </varlistentry> - - </variablelist> - - </section> - - + </step> + </procedure> + </listitem> + </varlistentry> + </variablelist> </section> - - + </section> </chapter> - Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr-with-gtn/managed-datasources-under-jboss-as.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr-with-gtn/managed-datasources-under-jboss-as.xml 2012-07-05 19:41:59 UTC (rev 8774) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/eXoJCR/jcr-with-gtn/managed-datasources-under-jboss-as.xml 2012-07-06 05:00:36 UTC (rev 8775) @@ -1,25 +1,24 @@ -<?xml version='1.0' encoding='utf-8' ?> +<?xml version='1.0' encoding='UTF-8'?> <!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!ENTITY % BOOK_ENTITIES SYSTEM "Reference_Guide.ent"> %BOOK_ENTITIES; ]> <section id="sect-Reference_Guide-How_to_use_AS_Managed_DataSource_under_JBoss_AS"> - <title>How to use AS Managed DataSource under JBoss AS</title> - <section id="sect-Reference_Guide-How_to_use_AS_Managed_DataSource_under_JBoss_AS-Configurations_Steps"> - <title>Configurations Steps</title> - <section id="sect-Reference_Guide-Configurations_Steps-Declaring_the_datasources_in_the_AS"> - <title>Declaring the datasources in the AS</title> - <para> - To declare the datasources using a JBoss application server, deploy a <literal>ds</literal> file (<filename><replaceable>XXX</replaceable>-ds.xml</filename>) into the <emphasis>deploy</emphasis> directory of the appropriate server profile (<filename>\server\<replaceable>&lt;PROFILE&gt;</replaceable>\deploy</filename>, for example). - </para> - <para> - This file configures all datasources which JBoss Enterprise Portal Platform will need (there should be four specifically named: <emphasis>jdbcjcr_portal</emphasis>, <emphasis>jdbcjcr_portal-sample</emphasis>, <emphasis>jdbcidm_portal</emphasis> and <emphasis>jdbcidm_sample-portal</emphasis>). - </para> - <para> - For example: - </para> - -<programlisting language="XML" role="XML">&lt;?xml version="1.0" encoding="UTF-8"?&gt; + <title>How to use AS Managed DataSource under JBoss AS</title> + <section id="sect-Reference_Guide-How_to_use_AS_Managed_DataSource_under_JBoss_AS-Configurations_Steps"> + <title>Configurations Steps</title> + <section id="sect-Reference_Guide-Configurations_Steps-Declaring_the_datasources_in_the_AS"> + <title>Declaring the datasources in the AS</title> + <para> + To declare the datasources using a JBoss application server, deploy a <literal>ds</literal> file (<filename><replaceable>XXX</replaceable>-ds.xml</filename>) into the <emphasis>deploy</emphasis> directory of the appropriate server profile (<filename>\server\<replaceable>&lt;PROFILE&gt;</replaceable>\deploy</filename>, for example). + </para> + <para> + This file configures all datasources which JBoss Enterprise Portal Platform will need (there should be four specifically named: <emphasis>jdbcjcr_portal</emphasis>, <emphasis>jdbcjcr_portal-sample</emphasis>, <emphasis>jdbcidm_portal</emphasis> and <emphasis>jdbcidm_sample-portal</emphasis>). + </para> + <para> + For example: + </para> + <programlisting language="XML" role="XML">&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt; &lt;datasources&gt; &lt;no-tx-datasource&gt; &lt;jndi-name&gt;jdbcjcr_portal&lt;/jndi-name&gt; @@ -53,47 +52,35 @@ &lt;password&gt;&lt;/password&gt; &lt;/no-tx-datasource&gt; &lt;/datasources&gt;</programlisting> - <para> - The properties can be set for datasource can be found here: <ulink url="http://docs.jboss.org/jbossas/docs/Server_Configuration_Guide/4... JDBC DataSources - The non transactional DataSource configuration schema</ulink> - </para> - - </section> - - <section id="sect-Reference_Guide-Configurations_Steps-Do_not_bind_datasources_explicitly"> - <title>Do not bind datasources explicitly</title> - <para> - Do not let the portal explicitly bind datasources. Edit the <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/conf/gatein/configuration.properties</filename> and comment out the following rows in the JCR section: - </para> - -<programlisting>#gatein.jcr.datasource.driver=org.hsqldb.jdbcDriver + <para> + The properties can be set for datasource can be found here: <ulink url="http://docs.jboss.org/jbossas/docs/Server_Configuration_Guide/4... JDBC DataSources - The non transactional DataSource configuration schema</ulink> + </para> + </section> + <section id="sect-Reference_Guide-Configurations_Steps-Do_not_bind_datasources_explicitly"> + <title>Do not bind datasources explicitly</title> + <para> + Do not let the portal explicitly bind datasources. Edit the <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/conf/gatein/configuration.properties</filename> and comment out the following rows in the JCR section: + </para> + <programlisting>#gatein.jcr.datasource.driver=org.hsqldb.jdbcDriver #gatein.jcr.datasource.url=jdbc:hsqldb:file:${gatein.db.data.dir}/data/jdbcjcr_${name} #gatein.jcr.datasource.username=sa #gatein.jcr.datasource.password=</programlisting> - <para> - Comment out the following lines in the IDM section: - </para> - -<programlisting>#gatein.idm.datasource.driver=org.hsqldb.jdbcDriver + <para> + Comment out the following lines in the IDM section: + </para> + <programlisting>#gatein.idm.datasource.driver=org.hsqldb.jdbcDriver #gatein.idm.datasource.url=jdbc:hsqldb:file:${gatein.db.data.dir}/data/jdbcidm_${name} #gatein.idm.datasource.username=sa #gatein.idm.datasource.password=</programlisting> - <para> - Open the <filename>jcr-configuration.xml</filename> and <filename>idm-configuration.xml</filename> files ans comment out references to the plugin <literal>InitialContextInitializer</literal>. - </para> - -<programlisting language="XML" role="XML">&lt;!-- Commented because, Datasources are declared and bound by AS, not in eXo --&gt; + <para> + Open the <filename>jcr-configuration.xml</filename> and <filename>idm-configuration.xml</filename> files ans comment out references to the plug-in <literal>InitialContextInitializer</literal>. + </para> + <programlisting language="XML" role="XML">&lt;!-- Commented because, Datasources are declared and bound by AS, not in eXo --&gt; &lt;!-- &lt;external-component-plugins&gt; [...] &lt;/external-component-plugins&gt; --&gt;</programlisting> - - </section> - - - </section> - - + </section> + </section> </section> - -