[gatein-commits] gatein SVN: r3073 - in portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules: Advanced and 2 other directories.

Author: smumford Date: 2010-05-13 03:06:06 -0400 (Thu, 13 May 2010) New Revision: 3073 Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/Foundations.xml portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/architecture.xml portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/configuration.xml portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/intro.xml portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/PortletDevelopment/Standard.xml portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/WSRP.xml Log: JBEPP-276: Edits to beginning of Part III for Brno QE release Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/Foundations.xml =================================================================== --- portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/Foundations.xml 2010-05-13 06:32:28 UTC (rev 3072) +++ portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/Foundations.xml 2010-05-13 07:06:06 UTC (rev 3073) @@ -11,10 +11,10 @@ &PRODUCT; is built as a set of services on top of a dependency injection kernel. The kernel provides configuration, lifecycle handling, component scopes, and some core services. </para> <para> - Service components exist in two scopes. The first scope is represented by the <emphasis role="bold">RootContainer</emphasis>. It contains services that exist independently of any portal, and can be accessed by all portals. + Service components exist in two scopes. The first scope is represented by the <literal>RootContainer</literal>. It contains services that exist independently of any portal, and can be accessed by all portals. </para> <para> - The second scope, the <emphasis role="bold">PortalContainer</emphasis>, is portal-private. Each portal exists in an instance of PortalContainer. This scope contains services that are common for a set of portals, and services which should not be shared by all portals. + The second scope, the <literal>PortalContainer</literal>, is portal-private. Each portal exists in an instance of PortalContainer. This scope contains services that are common for a set of portals, and services which should not be shared by all portals. </para> <para> <mediaobject> @@ -27,13 +27,13 @@ </mediaobject> </para> <para> - Whenever a specific service is looked up through PortalContainer, and the service is not available, the lookup is delegated further up to RootContainer. + Whenever a specific service is looked up through <literal>PortalContainer</literal>, and the service is not available, the lookup is delegated further up to <literal>RootContainer</literal>. </para> <para> - Therefore &PRODUCT; can have default instance of a certain component in RootContainer, and portal specific instances in some or all PortalContainers, that override the default instance. + &PRODUCT; can have default instance of a certain component in <literal>RootContainer</literal>, and portal specific instances in some or all <literal>PortalContainers</literal>, that override the default instance. </para> <para> - Whenever your portal application has to be integrated more closely with GateIn services, these services can be looked up through PortalContainer. + Whenever your portal application has to be integrated more closely with GateIn services, these services can be looked up through <literal>PortalContainer</literal>. </para> <important> <para> @@ -45,7 +45,7 @@ <section id="sect-Reference_Guide-Foundations-Configuring_services"> <title>Configuring services</title> <para> - GateIn 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 RootContainer scope, or into PortalContainer scope. + GateIn 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> All <filename>configuration.xml</filename> files located at <emphasis>conf/configuration.xml</emphasis> in the classpath (any directory, or any jar in the classpath) will have their services configured at RootContainer scope. All <filename>configuration.xml</filename> files located at <emphasis role="bold">conf/portal/configuration.xml</emphasis> in the classpath will have their services configured at PortalContainer scope. @@ -68,16 +68,16 @@ A service component is defined in <filename>configuration.xml</filename> by using <emphasis role="bold">&lt;component&gt;</emphasis> element. </para> <para> - Only one piece of information is required when defining a service; the service implementation class. This is specified using <emphasis role="bold">&lt;type&gt;</emphasis> + 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> - Every component has a <emphasis role="bold">&lt;key&gt;</emphasis> that identifies it. If not explicitly set, a key defaults to the value of &lt;type&gt;. If key can be loaded as a class, a Class object is used as a key, otherwise a String is used. + 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 key can be loaded as a class, a Class object is used as a key, otherwise a String is used. </para> <para> The usual approach is to specify an interface as a key. </para> -<!-- TODO XML highlight once issue https://bugzilla.redhat.com/show_bug.cgi?id=590933 resolved--> -<programlisting ><![CDATA[<?xml version="1.0" encoding="ISO-8859-1"?> + +<programlisting language="XML" role="XML"><![CDATA[<?xml version="1.0" encoding="ISO-8859-1"?> <configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.exoplaform.org/xml/ns/kernel_1_0.xsd @@ -97,7 +97,7 @@ <section id="sect-Reference_Guide-Configuration_syntax-External_Plugins"> <title>External Plugins</title> <para> - The GateIn Kernel supports non-component objects that can be configured, instantiated, and injected into registered components, using method calls. This 'plugins' method allows portal extensions to add additional configurations to core services. + The GateIn Kernel supports non-component objects that can be configured, instantiated, and injected into registered components, using method calls. This '<emphasis>plugins</emphasis>' 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-plugins&gt;</literal> wrapper element which contains one or more <literal>&lt;component-plugin&gt;</literal> definitions. @@ -114,8 +114,8 @@ <para> In the following example <literal>PortalContainerDefinitionPlugin</literal> implements <literal>ComponentPlugin</literal>: </para> -<!-- TODO XML highlight once issue https://bugzilla.redhat.com/show_bug.cgi?id=590933 resolved--> -<programlisting><![CDATA[<?xml version="1.0" encoding="UTF-8"?> + +<programlisting language="XML" role="XML"><![CDATA[<?xml version="1.0" encoding="UTF-8"?> <configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.exoplaform.org/xml/ns/kernel_1_0.xsd @@ -146,10 +146,10 @@ <section id="sect-Reference_Guide-Configuration_syntax-Includes_and_special_URLs"> <title>Includes, and special URLs</title> <para> - It is possible to the break <filename>configuration.xml</filename> file into many smaller files, that are then included into a 'master' configuration file. + It is possible to the break the <filename>configuration.xml</filename> file into many smaller files, which are then included into a 'master' configuration file. </para> <para> - The included files must be complete <filename>configuration.xml</filename> documents in themselves. That is, they can not be fragments of text. + The included files must be complete <filename>configuration.xml</filename> documents in their own right. That is, they can not be fragments of text. </para> <para> Below is an example <filename>configuration.xml</filename> that 'outsources' its content into several files: @@ -158,7 +158,7 @@ <areaspec> <area coords="6" id="area-Reference_Guide-Configuration_syntax-Includes_and_special_URLs-url_schema" /> </areaspec> -<!-- TODO XML highlight once issue https://bugzilla.redhat.com/show_bug.cgi?id=590933 resolved--> +<!-- TODO highlight once Publican 1.6.3 installed (XML)--> <programlisting><![CDATA[<configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.exoplaform.org/xml/ns/kernel_1_0.xsd http://www.exoplaform.org/xml/ns/kernel_1_0.xsd" @@ -172,73 +172,70 @@ <callout arearefs="area-Reference_Guide-Configuration_syntax-Includes_and_special_URLs-url_schema"> <para> - This line is being used to reference another configuration file. The <literal>war:</literal> URL schema indicates that the path that follows is to be resolved relative to the current PortalContainer's servlet context resource path, starting with <emphasis role="bold">WEB-INF</emphasis> as a root. + This line is being used to reference another configuration file. The <code>war:</code> URL schema indicates that the path that follows is to be resolved relative to the current PortalContainer's servlet context resource path, starting with <emphasis role="bold">WEB-INF</emphasis> as a root. </para> </callout> </calloutlist> </programlistingco> <note> <para> - Current PortalContainer is really a newly created PortalContainer, as war: URLs only make sense for PortalContainer scoped configuration. + 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> - Also, thanks to extension mechanism, the servlet context used for resource loading is a <emphasis role="bold">unified servlet context</emphasis> (as explaned in a later section). + Through the extension mechanism the servlet context used for resource loading is a <emphasis role="bold">unified servlet context</emphasis> (this is explaned in a later section). </para> <para> - To have include path resolved relative to current classpath (context classloader), use <emphasis role="bold">'jar:'</emphasis> URL schema. + To have an 'include' path resolved relative to current classpath (context classloader), use a <code>'jar:'</code> URL schema. </para> </section> <section id="sect-Reference_Guide-Configuration_syntax-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 (_). This facilitates reuse of configuration files in situations where portal specific unique names need to be assigned to some resources (i.e. JNDI names, Database / DataSource names, JCR repository names, etc ...). + 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> - This variable is only defined when there is a current PortalContainer available - only for PortalContainer scoped services. + 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> - A good example for this is <emphasis role="bold">HibernateService</emphasis>: + 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> - <example id="exam-Reference_Guide-Special_variables-HibernateService_using_variables"> - <title>HibernateService using variables</title> - -<programlisting role="XML"> -&lt;?xml version="1.0" encoding="ISO-8859-1"?&gt; -&lt;configuration + <para> + A good example of this is the <emphasis role="bold">HibernateService</emphasis>: + </para> +<programlisting language="XML" role="XML"><![CDATA[<?xml version="1.0" encoding="ISO-8859-1"?> +<configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.exoplaform.org/xml/ns/kernel_1_0.xsd http://www.exoplaform.org/xml/ns/kernel_1_0.xsd" - xmlns="http://www.exoplaform.org/xml/ns/kernel_1_0.xsd"&gt; + xmlns="http://www.exoplaform.org/xml/ns/kernel_1_0.xsd"> - &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; - &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${container.name.suffix}" /&gt; - &lt;property name="hibernate.connection.driver_class" value="org.hsqldb.jdbcDriver" /&gt; - &lt;property name="hibernate.connection.autocommit" value="true" /&gt; - &lt;property name="hibernate.connection.username" value="sa" /&gt; - &lt;property name="hibernate.connection.password" value="" /&gt; - &lt;property name="hibernate.dialect" value="org.hibernate.dialect.HSQLDialect" /&gt; - &lt;property name="hibernate.c3p0.min_size" value="5" /&gt; - &lt;property name="hibernate.c3p0.max_size" value="20" /&gt; - &lt;property name="hibernate.c3p0.timeout" value="1800" /&gt; - &lt;property name="hibernate.c3p0.max_statements" value="50" /&gt; - &lt;/properties-param&gt; - &lt;/init-params&gt; - &lt;/component&gt; -&lt;/configuration&gt; -</programlisting> - </example> + <component> + <key>org.exoplatform.services.database.HibernateService</key> + <jmx-name>database:type=HibernateService</jmx-name> + <type>org.exoplatform.services.database.impl.HibernateServiceImpl</type> + <init-params> + <properties-param> + <name>hibernate.properties</name> + <description>Default Hibernate Service</description> + <property name="hibernate.show_sql" value="false" /> + <property name="hibernate.cglib.use_reflection_optimizer" value="true" /> + <property name="hibernate.connection.url" + value="jdbc:hsqldb:file:../temp/data/exodb${container.name.suffix}" /> + <property name="hibernate.connection.driver_class" value="org.hsqldb.jdbcDriver" /> + <property name="hibernate.connection.autocommit" value="true" /> + <property name="hibernate.connection.username" value="sa" /> + <property name="hibernate.connection.password" value="" /> + <property name="hibernate.dialect" value="org.hibernate.dialect.HSQLDialect" /> + <property name="hibernate.c3p0.min_size" value="5" /> + <property name="hibernate.c3p0.max_size" value="20" /> + <property name="hibernate.c3p0.timeout" value="1800" /> + <property name="hibernate.c3p0.max_statements" value="50" /> + </properties-param> + </init-params> + </component> +</configuration>]]></programlisting> </section> </section> @@ -246,39 +243,78 @@ <section id="sect-Reference_Guide-Foundations-InitParams_configuration_object"> <title>InitParams configuration object</title> <para> - <literal>InitParams</literal> is a configuration object that is essentially a map of key-value pairs, where key is always a <literal>String</literal>, and value can be any type that can be described using kernel configuration xml. + <parameter>InitParams</parameter> is a configuration object 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> - Service components that form the &PRODUCT; insfrastructure use <literal>InitParams</literal> object to configure themselves. A component can have one instance of InitParams injected at most. If the service component's constructor takes InitParams as any of the parameters it will automatically be injected at component instantiation time. The xml configuration for a service component that expects InitParams object must include &lt;init-params&gt; element (even if an empty one). + Service components that form the &PRODUCT; insfrastructure use <parameter>InitParams</parameter> objects to configure themselves. A component can have one instance of <parameter>InitParams</parameter> injected at most. </para> <para> - Let's use an example to see how the kernel xml configuration syntax looks for creating <literal>InitParams</literal> instances. + 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> - <example id="exam-Reference_Guide-InitParams_configuration_object-InitParams_properties_param"> - <title>InitParams - properties-param</title> - -<programlisting role="XML"> -&lt;component&gt; - &lt;key&gt;org.exoplatform.services.naming.InitialContextInitializer&lt;/key&gt; - &lt;type&gt;org.exoplatform.services.naming.InitialContextInitializer&lt;/type&gt; - &lt;init-params&gt; - &lt;properties-param&gt; - &lt;name&gt;default-properties&lt;/name&gt; - &lt;description&gt;Default initial context properties&lt;/description&gt; - &lt;property name="java.naming.factory.initial" - value="org.exoplatform.services.naming.SimpleContextFactory" /&gt; - &lt;/properties-param&gt; - &lt;/init-params&gt; -&lt;/component&gt; -</programlisting> - </example> <para> - InitParams object description begins with &lt;init-params&gt; element. It can have zero or more children elements each of which is one of &lt;value-param&gt;, &lt;values-param&gt;, &lt;properties-param&gt;, or &lt;object-param&gt;. Each of these child elements takes a &lt;name&gt; that serves as a map entry key, and an optional &lt;description&gt;. It also takes a type-specific value specification. + The XML configuration for a service component that expects an <parameter>InitParams</parameter> object <emphasis role="bold">must</emphasis> include an <parameter>&lt;init-params&gt;</parameter> element, however this element may be empty. </para> <para> - For &lt;properties-param&gt; the value specification is in the form of one or more &lt;property&gt; elements, each of which specifies two strings - a property name, and a property value. Each &lt;properties-params&gt; defines one <literal>java.util.Properties</literal> instance. Also see <xref linkend="exam-Reference_Guide-Special_variables-HibernateService_using_variables" /> for an example. + Below is an example of how the kernel XML configuration syntax looks when creating <parameter>InitParams</parameter> instances: </para> - <example id="exam-Reference_Guide-InitParams_configuration_object-InitParams_value_param"> + +<programlisting language="XML" role="XML"><![CDATA[<component> + <key>org.exoplatform.services.naming.InitialContextInitializer</key> + <type>org.exoplatform.services.naming.InitialContextInitializer</type> + <init-params> + <properties-param> + <name>default-properties</name> + <description>Default initial context properties</description> + <property name="java.naming.factory.initial" + value="org.exoplatform.services.naming.SimpleContextFactory" /> + </properties-param> + </init-params> +</component> +]]></programlisting> + + <para> + An <parameter>InitParams</parameter> object description begins with <parameter>&lt;init-params&gt;</parameter> element. + </para> + <para> + It can have zero or more children elements, each of which is one of the following: + </para> + <itemizedlist> + <listitem> + <para> + <parameter>&lt;value-param&gt;</parameter> + </para> + </listitem> + <listitem> + <para> + <parameter>&lt;values-param&gt;</parameter> + </para> + </listitem> + <listitem> + <para> + <parameter>&lt;properties-param&gt;</parameter> + </para> + </listitem> + </itemizedlist> + <para> + or + </para> + <itemizedlist> + <listitem> + <para> + <parameter>&lt;object-param&gt;</parameter> + </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> + 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 examples above. + </para> + <para> + Each <parameter>&lt;properties-params&gt;</parameter> defines one <literal>java.util.Properties</literal> instance. + </para> +<!-- <example id="exam-Reference_Guide-InitParams_configuration_object-InitParams_value_param"> <title>InitParams - value-param</title> <programlisting role="XML"> @@ -293,310 +329,373 @@ &lt;/init-params&gt; &lt;/component&gt; </programlisting> - </example> + </example> --> <para> - For &lt;value-param&gt; the value specification is in the form of &lt;value&gt; element, which defines one <literal>String</literal> instance. + 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> - <example id="exam-Reference_Guide-InitParams_configuration_object-InitParams_values_param"> - <title>InitParams - values-param</title> - -<programlisting role="XML"> -&lt;component&gt; - &lt;key&gt;org.exoplatform.services.resources.ResourceBundleService&lt;/key&gt; - &lt;type&gt;org.exoplatform.services.resources.impl.SimpleResourceBundleService&lt;/type&gt; - &lt;init-params&gt; - &lt;values-param&gt; - &lt;name&gt;classpath.resources&lt;/name&gt; - &lt;description&gt;The resources that start with the following package name should be load from file system&lt;/description&gt; - &lt;value&gt;locale.portlet&lt;/value&gt; - &lt;/values-param&gt; - &lt;values-param&gt; - &lt;name&gt;init.resources&lt;/name&gt; - &lt;description&gt;Store the following resources into the db for the first launch &lt;/description&gt; - &lt;value&gt;locale.test.resources.test&lt;/value&gt; - &lt;/values-param&gt; +<programlisting language="XML" role="XML"><![CDATA[<component> + <key>org.exoplatform.services.resources.ResourceBundleService</key> + <type>org.exoplatform.services.resources.impl.SimpleResourceBundleService</type> + <init-params> + <values-param> + <name>classpath.resources</name> + <description>The resources that start with the following package name should be load from file system</description> + <value>locale.portlet</value> + </values-param> - &lt;values-param&gt; - &lt;name&gt;portal.resource.names&lt;/name&gt; - &lt;description&gt;The properties files of the portal , those file will be merged - into one ResourceBundle properties &lt;/description&gt; - &lt;value&gt;local.portal.portal&lt;/value&gt; - &lt;value&gt;local.portal.custom&lt;/value&gt; - &lt;/values-param&gt; - &lt;/init-params&gt; -&lt;/component&gt; -</programlisting> - </example> + <values-param> + <name>init.resources</name> + <description>Store the following resources into the db for the first launch </description> + <value>locale.test.resources.test</value> + </values-param> + + <values-param> + <name>portal.resource.names</name> + <description>The properties files of the portal , those file will be merged + into one ResourceBundle properties </description> + <value>local.portal.portal</value> + <value>local.portal.custom</value> + </values-param> + </init-params> +</component> +]]></programlisting> + <para> - For &lt;values-param&gt; the value specification is in the form of one or more &lt;value&gt; elements, each of which represents one <literal>String</literal> instance, where all the <literal>String</literal> values are then collected into a <literal>java.util.List</literal> instance. + 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> - <example id="exam-Reference_Guide-InitParams_configuration_object-InitParams_object_param"> - <title>InitParams - object-param</title> - -<programlisting role="XML"> -&lt;component&gt; - &lt;key&gt;org.exoplatform.services.cache.CacheService&lt;/key&gt; - &lt;jmx-name&gt;cache:type=CacheService&lt;/jmx-name&gt; - &lt;type&gt;org.exoplatform.services.cache.impl.CacheServiceImpl&lt;/type&gt; - &lt;init-params&gt; - &lt;object-param&gt; - &lt;name&gt;cache.config.default&lt;/name&gt; - &lt;description&gt;The default cache configuration&lt;/description&gt; - &lt;object type="org.exoplatform.services.cache.ExoCacheConfig"&gt; - &lt;field name="name"&gt; - &lt;string&gt;default&lt;/string&gt; - &lt;/field&gt; - &lt;field name="maxSize"&gt; - &lt;int&gt;300&lt;/int&gt; - &lt;/field&gt; - &lt;field name="liveTime"&gt; - &lt;long&gt;300&lt;/long&gt; - &lt;/field&gt; - &lt;field name="distributed"&gt; - &lt;boolean&gt;false&lt;/boolean&gt; - &lt;/field&gt; - &lt;field name="implementation"&gt; - &lt;string&gt;org.exoplatform.services.cache.concurrent.ConcurrentFIFOExoCache&lt;/string&gt; - &lt;/field&gt; - &lt;/object&gt; - &lt;/object-param&gt; - &lt;/init-params&gt; -&lt;/component&gt; -</programlisting> - </example> + +<programlisting language="XML" role="XML"><![CDATA[<component> + <key>org.exoplatform.services.cache.CacheService</key> + <jmx-name>cache:type=CacheService</jmx-name> + <type>org.exoplatform.services.cache.impl.CacheServiceImpl</type> + <init-params> + <object-param> + <name>cache.config.default</name> + <description>The default cache configuration</description> + <object type="org.exoplatform.services.cache.ExoCacheConfig"> + <field name="name"> + <string>default</string> + </field> + <field name="maxSize"> + <int>300</int> + </field> + <field name="liveTime"> + <long>300</long> + </field> + <field name="distributed"> + <boolean>false</boolean> + </field> + <field name="implementation"> + <string>org.exoplatform.services.cache.concurrent.ConcurrentFIFOExoCache</string> + </field> + </object> + </object-param> + </init-params> +</component> +]]></programlisting> + <para> - For &lt;object-param&gt; in our case, the value specification comes in a form of &lt;object&gt; element, which is used for POJO style object specification (you specify an implementation class - &lt;type&gt;, and property values - &lt;field&gt;). + For <parameter>&lt;object-param&gt;</parameter> entries, the value specification consists of a <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> - Also see <xref linkend="exam-Reference_Guide-Configuring_a_portal_container-Portal_container_declaration_example" /> for an example of specifying a field of <literal>Collection</literal> type. + The following section has an example of specifying a field of with a <literal>Collection</literal> type. </para> <para> - The <literal>InitParams</literal> structure - the names and types of entries is specific for each service, as it is the code inside service components's class that decides what entry names to look up and what types it expects to find. + 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's class that defines which entry names to look up and what types it expects to find. </para> </section> <section id="sect-Reference_Guide-Foundations-Configuring_a_portal_container"> <title>Configuring a portal container</title> <para> - A <emphasis role="bold">portal container</emphasis> is defined by several attributes. + A <literal>portal container</literal> is defined by several attributes: </para> - <para> - First, there is a <emphasis role="bold">portal container name</emphasis>, which is always equal to URL context to which the current portal is bound. - </para> - <para> - Second, there is a <emphasis role="bold">REST context name</emphasis>, which is used for REST access to portal application - every portal has exactly one (unique) REST context name. - </para> - <para> - Then, there is a <emphasis role="bold">realm name</emphasis> which is the name of security realm used for authentication when users log into the portal. - </para> - <para> - Finally, there is a list of <emphasis role="bold">Dependencies</emphasis> - other web applications, whose resources are visible to current portal (via extension mechanism described later), and are searched in the specified order. - </para> - <example id="exam-Reference_Guide-Configuring_a_portal_container-Portal_container_declaration_example"> - <title>Portal container declaration example</title> - -<programlisting role="XML"> -&lt;?xml version="1.0" encoding="UTF-8"?&gt; -&lt;configuration + <variablelist> + <varlistentry> + <term>Portal Container Name</term> + <listitem> + <para> + This attribute is always equal to the URL context to which the current portal is bound. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>REST Context Name</term> + <listitem> + <para> + This attribute is used for REST access to portal application; every portal has one unique REST context name. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Realm Name</term> + <listitem> + <para> + This is the name of the security realm used for authentication when users log into the portal. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Dependencies</term> + <listitem> + <para> + This is a list of other web applications whose resources are visible to the current portal (via the extension mechanism described later), and are searched for in the specified order. + </para> + </listitem> + </varlistentry> + </variablelist> + +<programlisting language="XML" role="XML"><![CDATA[<?xml version="1.0" encoding="UTF-8"?> +<configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.exoplaform.org/xml/ns/kernel_1_0.xsd http://www.exoplaform.org/xml/ns/kernel_1_0.xsd" - xmlns="http://www.exoplaform.org/xml/ns/kernel_1_0.xsd"&gt; + xmlns="http://www.exoplaform.org/xml/ns/kernel_1_0.xsd"> - &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; + <external-component-plugins> + <!-- The full qualified name of the PortalContainerConfig --> + <target-component>org.exoplatform.container.definition.PortalContainerConfig</target-component> - &lt;component-plugin&gt; - &lt;!-- The name of the plugin --&gt; - &lt;name&gt;Add PortalContainer Definitions&lt;/name&gt; + <component-plugin> + <!-- The name of the plugin --> + <name>Add PortalContainer Definitions</name> - &lt;!-- The name of the method to call on the PortalContainerConfig - in order to register the PortalContainerDefinitions --&gt; - &lt;set-method&gt;registerPlugin&lt;/set-method&gt; + <!-- The name of the method to call on the PortalContainerConfig + in order to register the PortalContainerDefinitions --> + <set-method>registerPlugin</set-method> - &lt;!-- The full qualified name of the PortalContainerDefinitionPlugin --&gt; - &lt;type&gt;org.exoplatform.container.definition.PortalContainerDefinitionPlugin&lt;/type&gt; + <!-- The full qualified name of the PortalContainerDefinitionPlugin --> + <type>org.exoplatform.container.definition.PortalContainerDefinitionPlugin</type> - &lt;init-params&gt; - &lt;object-param&gt; - &lt;name&gt;portal&lt;/name&gt; - &lt;object type="org.exoplatform.container.definition.PortalContainerDefinition"&gt; - &lt;!-- The name of the portal container --&gt; - &lt;field name="name"&gt;&lt;string&gt;portal&lt;/string&gt;&lt;/field&gt; + <init-params> + <object-param> + <name>portal</name> + <object type="org.exoplatform.container.definition.PortalContainerDefinition"> + <!-- The name of the portal container --> + <field name="name"><string>portal</string></field> - &lt;!-- The name of the context name of the rest web application --&gt; - &lt;field name="restContextName"&gt;&lt;string&gt;rest&lt;/string&gt;&lt;/field&gt; + <!-- The name of the context name of the rest web application --> + <field name="restContextName"><string>rest</string></field> - &lt;!-- The name of the realm --&gt; - &lt;field name="realmName"&gt;&lt;string&gt;exo-domain&lt;/string&gt;&lt;/field&gt; + <!-- The name of the realm --> + <field name="realmName"><string>exo-domain</string></field> - &lt;!-- All the dependencies of the portal container ordered by loading priority --&gt; - &lt;field name="dependencies"&gt; - &lt;collection type="java.util.ArrayList"&gt; - &lt;value&gt; - &lt;string&gt;eXoResources&lt;/string&gt; - &lt;/value&gt; - &lt;value&gt; - &lt;string&gt;portal&lt;/string&gt; - &lt;/value&gt; - &lt;value&gt; - &lt;string&gt;dashboard&lt;/string&gt; - &lt;/value&gt; - &lt;value&gt; - &lt;string&gt;exoadmin&lt;/string&gt; - &lt;/value&gt; - &lt;value&gt; - &lt;string&gt;eXoGadgets&lt;/string&gt; - &lt;/value&gt; - &lt;value&gt; - &lt;string&gt;eXoGadgetServer&lt;/string&gt; - &lt;/value&gt; - &lt;value&gt; - &lt;string&gt;rest&lt;/string&gt; - &lt;/value&gt; - &lt;value&gt; - &lt;string&gt;web&lt;/string&gt; - &lt;/value&gt; - &lt;value&gt; - &lt;string&gt;wsrp-producer&lt;/string&gt; - &lt;/value&gt; - &lt;!-- The sample-ext has been added at the end of the dependency list - in order to have the highest priority --&gt; - &lt;value&gt; - &lt;string&gt;sample-ext&lt;/string&gt; - &lt;/value&gt; - &lt;/collection&gt; - &lt;/field&gt; - &lt;/object&gt; - &lt;/object-param&gt; - &lt;/init-params&gt; - &lt;/component-plugin&gt; - &lt;/external-component-plugins&gt; -&lt;/configuration&gt; -</programlisting> - </example> - <note> - <para> - Dependencies are part of the extension mechanism. - </para> - </note> + <!-- All the dependencies of the portal container ordered by loading priority --> + <field name="dependencies"> + <collection type="java.util.ArrayList"> + <value> + <string>eXoResources</string> + </value> + <value> + <string>portal</string> + </value> + <value> + <string>dashboard</string> + </value> + <value> + <string>exoadmin</string> + </value> + <value> + <string>eXoGadgets</string> + </value> + <value> + <string>eXoGadgetServer</string> + </value> + <value> + <string>rest</string> + </value> + <value> + <string>web</string> + </value> + <value> + <string>wsrp-producer</string> + </value> + <!-- The sample-ext has been added at the end of the dependency list + in order to have the highest priority --> + <value> + <string>sample-ext</string> + </value> + </collection> + </field> + </object> + </object-param> + </init-params> + </component-plugin> + </external-component-plugins> +</configuration> +]]></programlisting> + <para> - Every <emphasis role="bold">portal container</emphasis> is represented by a <emphasis role="bold">PortalContainer instance</emphasis>, which contains: - <itemizedlist> - <listitem> - <para> - associated <emphasis role="bold">ExoContainerContext</emphasis>, which contains information about the portal - </para> - </listitem> - <listitem> - <para> - <emphasis role="bold">unified servlet context</emphasis>, for web-archive-relative resource loading - </para> - </listitem> - <listitem> - <para> - <emphasis role="bold">unified classloader</emphasis>, for classpath based resource loading - </para> - </listitem> - <listitem> - <para> - methods for retrieving services - </para> - </listitem> - </itemizedlist> + Dependencies are part of the <emphasis role="bold">extension mechanism</emphasis> which is discussed later in this document. </para> <para> - <emphasis role="bold">Unified servlet context</emphasis>, and <emphasis role="bold">unified classloader</emphasis> are part of the <emphasis role="bold">extension mechanism</emphasis> (explained in next section), and provide standard API (ServletContext, ClassLoader) with specific resource loading behavior - visibility into associated web application archives, configured with Dependencies property of PortalContainerDefinition. Resources from other web applications are queried in the order specified by Dependencies. The later entries in the list override the previous ones. + Every <literal>portal container</literal> is represented by a <literal>PortalContainer instance</literal>, which contains: </para> + <variablelist> + <varlistentry> + <term>ExoContainerContext</term> + <listitem> + <para> + This contains information about the portal. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Unified Servlet Context</term> + <listitem> + <para> + Which deals with web-archive-relative resource loading. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Unified Classloader</term> + <listitem> + <para> + For classpath based resource loading. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Various methods for retrieving services</term> + <listitem> + <para> + + </para> + </listitem> + </varlistentry> + </variablelist> + <para> + The <emphasis role="bold">Unified servlet context</emphasis>, and <emphasis role="bold">unified classloader</emphasis> are part of the <emphasis role="bold">extension mechanism</emphasis> (which is detailed in the next section). + </para> + <para> + They provide standard API (<literal>ServletContext</literal>, <literal>ClassLoader</literal>) with specific resource loading behavior, such as visibility into associated web application archives, configured with Dependencies property of <literal>PortalContainerDefinition</literal>. + </para> + <para> + Resources from other web applications are queried in the order specified by Dependencies. The later entries in the list override the previous ones. + </para> </section> <section id="sect-Reference_Guide-Foundations-GateIn_Extension_Mechanism_and_Portal_Extensions"> - <title>GateIn Extension Mechanism, and Portal Extensions</title> + <title>The Extension Mechanism and Portal Extensions</title> <para> - <emphasis role="bold">Extension mechanism</emphasis> is a functionality that makes it possible to override portal resources in an almost plug-and-play fashion - just drop in a .war archive with the resources, and configure its position on the portal's classpath. This way any customizations of the portal don't have to involve unpacking and repacking the original portal .war archives. Instead, you create your own .war archive with changed resources, that override the resources in the original archive. + The <emphasis role="bold">Extension mechanism</emphasis> makes it possible to override portal resources in a way similar to hardware plug-and-play functionalities. </para> <para> - A web archive packaged in a way to be used through extension mechanism is called <emphasis role="bold">portal extension</emphasis>. + Customizations can be implemented, without unpacking and repacking the original portal <code>.war</code> archives, by adding a <code>.war</code> archive to the resources and configuring its position in the portal's classpath. Custom <code>.war</code> archives can be created with new resources that override the resources in the original archive. </para> <para> - There are two steps necessary to create a portal extension. + These archives, packaged for use through the extension mechanism, are called <emphasis role="bold">portal extensions</emphasis>. </para> - <para> - First, declare <emphasis role="bold">PortalConfigOwner</emphasis> servlet context listener in web.xml of your web application. - </para> - <example id="exam-Reference_Guide-GateIn_Extension_Mechanism_and_Portal_Extensions-Example_of_a_portal_extension_called_sample_ext"> - <title>Example of a portal extension called sample-ext:</title> - -<programlisting 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; -&lt;web-app&gt; + <procedure> + <title>Creating a portal extension</title> + <step> + <para> + Declare the <emphasis role="bold">PortalConfigOwner</emphasis> servlet context listener in the <filename>web.xml</filename> of your web application. + </para> + <para> + This example shows a portal extension called <emphasis role="bold">sample-ext</emphasis>. + </para> +<programlisting language="XML" role="XML"><![CDATA[<?xml version="1.0" encoding="ISO-8859-1" ?> +<!DOCTYPE web-app PUBLIC -//Sun Microsystems, Inc.//DTD Web Application 2.3//EN + http://java.sun.com/dtd/web-app_2_3.dtd> +<web-app> - &lt;display-name&gt;sample-ext&lt;/display-name&gt; + <display-name>sample-ext</display-name> - &lt;listener&gt; - &lt;listener-class&gt;org.exoplatform.container.web.PortalContainerConfigOwner&lt;/listener-class&gt; - &lt;/listener&gt; + <listener> + <listener-class>org.exoplatform.container.web.PortalContainerConfigOwner</listener-class> + </listener> ... -&lt;/web-app&gt; -</programlisting> - </example> - <para> - Then, add the servlet context name of this web application in proper place in the list of Dependencies of the PortalContainerDefinition of all the portal containers that you want to have access to its resources. - </para> - <para> - After this step your web archive will be on portal's unified classpath, and unified servlet context resource path. The later in the Dependencies list your application is, the higher priority it has when resources are loaded by portal. - </para> +</web-app>]]></programlisting> + </step> + <step> + <para> + Add the application's servlet context name to the <literal>PortalContainerDefinition</literal>'s list of Dependencies. This must be done for each portal container that you want to have access to the new application. + </para> + <para> + The application's position in these lists will dictate its priority when the portal loads resources. The later your application appears in the list, the higher its resource priority will be. + </para> + </step> + <step> + <para> + At this point your new web archive will be on both the portal's unified classpath and unified servlet context resource path. + </para> + </step> + </procedure> + <note> + <title>Example</title> <para> - See 'Configuring a portal' section for example of PortalContainerDefinition, that has sample-ext at the end of its list of Dependencies. + Refer to the code extract in <xref linkend="sect-Reference_Guide-Foundations-Configuring_a_portal_container"/> for an example of a <literal>PortalContainerDefinition</literal> that has <emphasis role="bold">sample-ext</emphasis> in its list of Dependencies. </para> </note> </section> <section id="sect-Reference_Guide-Foundations-Running_Multiple_Portals"> <title>Running Multiple Portals</title> +<!-- DOC TODO: This section requires more work to structure the information effectively. Consider sub-sections --> <para> - It is possible to run several independent portal containers - each bound to a different URL context - within the same JVM instance. This kind of setup is very efficient from administration and resource consumption aspect. The most elegant way to <emphasis role="bold">reuse</emphasis> configuration for different coexisting portals is by way of extension mechanism - by <emphasis role="bold">inheriting</emphasis> resources and configuration from existing web archives, and just <emphasis role="bold">adding</emphasis> extra resources to it, and <emphasis role="bold">overriding</emphasis> those that need to be changed by including modified copies. + It is possible to run several independent portal containers, each bound to a different URL context, within the same JVM instance. </para> <para> - In order for a portal application to correctly function when deployed in multiple portals, the application may have to dynamically query the information about the current portal container. The application should not make any assumptions about the name, and other information of the current portal, as there are now multiple different portals in play. + This method of deployment allows for efficient administration and resource consumption by allowing coexisting portals to <emphasis>reuse</emphasis> configuration arrangements through the extension mechanism. </para> + <para> + Portals can <emphasis>inherit</emphasis> resources and configuration from existing web archives and add extra resources as needed, <emphasis>overriding</emphasis> those that need to be changed by including modified copies. + </para> <para> - At any point during request processing, or lifecycle event processing, your application can retrieve this information through <emphasis role="bold">org.exoplatform.container. ExoContainerContext</emphasis>. Sometimes your application needs to make sure that the proper <emphasis role="bold">PortalContainer</emphasis> - the source of <emphasis role="bold">ExoContainerContext</emphasis> - is associated with the current call. + In order for a portal application to function correctly when deployed within a multiple portal deployment, it may have to dynamically query the information about the current portal container. The application should not make any assumptions about the name, and other information of the current portal, as there are now multiple different portals in play. </para> <para> - If you ship servlets or servlet filters as part of your portal application, and if you need to access portal specific resources at any time during the processing of the servlet or filter request, then you need to make sure the servlet/filter is associated with the current container. + At any point during request processing, or life-cycle event processing, an application can retrieve this information through <literal>org.exoplatform.container. ExoContainerContext</literal>. </para> <para> - The proper way to do that is to make your servlet extend <emphasis role="bold">org.exoplatform.container.web. AbstractHttpServlet</emphasis> class. This will not only properly initialize current <emphasis role="bold">PortalContainer</emphasis> for you, but will also set the current thread's context classloader to one that looks for resources in associated web applications in the order specified by <emphasis role="bold">Dependencies</emphasis> configuration (as explained in Extension mechanism section). + Sometimes an application must ensure that the proper <literal>PortalContainer</literal> is associated with the current <literal>ExoContainerContext</literal> call. </para> <para> - Similarly for filters, make sure your filter class extends <emphasis role="bold">org.exoplatform.container.web. AbstractFilter</emphasis>. Both <emphasis role="bold">AbstractHttpServlet</emphasis>, and <emphasis role="bold">AbstractFilter</emphasis> have a method <emphasis role="bold">getContainer()</emphasis>, which returns the current <emphasis role="bold">PortalContainer</emphasis>. If your servlet handles the requests by implementing a <emphasis role="bold">service()</emphasis> method, you need to rename that method to match the following signature: + If the portal application contains servlets or servlet filters that need to access portal specific resources during their request processing, the servlet or filter must be associated with the current container. </para> + <para> + A servlet in this instance should extend the <literal>org.exoplatform.container.web. AbstractHttpServlet</literal> class so as to to properly initialize the current <literal>PortalContainer</literal>. + </para> + <para> + This will also set the current thread's context classloader to one that looks for resources in associated web applications in the order specified by <emphasis role="bold">Dependencies</emphasis> configuration (as seen in <xref linkend="sect-Reference_Guide-Foundations-GateIn_Extension_Mechanism_and_Portal_Extensions"/>). + </para> + <para> + Filter classes need to extend the <literal>org.exoplatform.container.web. AbstractFilter</literal>. + </para> + <para> + Both <literal>AbstractHttpServlet</literal>, and <literal>AbstractFilter</literal> have a <literal>getContainer()</literal> method, which returns the current <literal>PortalContainer</literal>. + </para> + <para> + If your servlet handles the requests by implementing a <literal>service()</literal> method, that method must be renamed to match the following signature: + </para> -<programlisting role="JAVA"> +<programlisting language="Java" role="JAVA"> /** * Use this method instead of Servlet.service() */ protected void onService(ExoContainer container, HttpServletRequest req, HttpServletResponse res) throws ServletException, IOException; </programlisting> + <note> <para> - The reason is that AbstractHttpServlet implements service() to perform its interception, and you don't want to overwrite (by overriding) this functionality. + This ensures that <literal>AbstractHttpServlet</literal>'s <literal>service()</literal> interception is not overwritten. </para> </note> <para> - You may also need to access portal information within your <emphasis role="bold">HttpSessionListener</emphasis>. Again, make sure to extend the provided abstract class - <emphasis role="bold">org.exoplatform.container.web. AbstractHttpSessionListener</emphasis>. Also, modify your method signatures as follows: + An application may also need to access portal information within the <emphasis role="bold">HttpSessionListener</emphasis>. Ensure the provided abstract class; <emphasis role="bold">org.exoplatform.container.web. AbstractHttpSessionListener</emphasis> is extended. </para> + <para> + In this instance, modify the method signatures as follows: + </para> -<programlisting role="JAVA"> +<programlisting language="Java" role="JAVA"> /** * Use this method instead of HttpSessionListener.sessionCreated() */ @@ -607,31 +706,55 @@ */ protected void onSessionDestroyed(ExoContainer container, HttpSessionEvent event); </programlisting> + <para> - There is another method you have to implement in this case: + Another method must also be implemented in this case: </para> -<programlisting role="JAVA"> +<programlisting language="Java" role="JAVA"> /** * Method should return true if unified servlet context, * and unified classloader should be made available */ protected boolean requirePortalEnvironment(); </programlisting> + <para> - If this method returns true, current thread's context classloader is set up according to <emphasis role="bold">Dependencies</emphasis> configuration, and availability of the associated web applications. If it returns false, the standard application separation rules are used for resource loading (effectively turning off the extension mechanism). This method exists on <emphasis role="bold">AbstractHttpServlet</emphasis> and <emphasis role="bold">AbstractFilter</emphasis> as well, where there is a default implementation that automatically returns true, when it detects there is a current PortalContainer present, otherwise it returns false. + If this method returns <emphasis>true</emphasis> the current thread's context classloader is set up according to the <emphasis role="bold">Dependencies</emphasis> configuration and availability of the associated web applications. </para> <para> - We still have to explain how to properly perform <emphasis role="bold">ServletContextListener</emphasis> based initialization, when you need access to current PortalContainer. + If it returns <emphasis>false</emphasis> the standard application separation rules are used for resource loading (effectively turning off the extension mechanism). </para> <para> - GateIn has no direct control over the deployment of application archives (.war, .ear files) - it is the application server that performs the deployment. For <emphasis role="bold">extension mechanism</emphasis> to work properly, the applications, associated with the portal via <emphasis role="bold">Dependencies</emphasis> configuration, have to be deployed before the portal, that depends on them, is initialized. On the other hand, these applications may require an already initialized PortalContainer to properly initialize themselves - we have a recursive dependency problem. To resolve this problem, a mechanism of <emphasis role="bold">initialization tasks</emphasis>, and <emphasis role="bold">task queues</emphasis>, was put in place. Web applications that depend on current PortalContainer for their initialization have to avoid performing their initialization directly in some ServletContextListener executed during their deployment (before any PortalContainer was initialize! d). Instead, a web application should package its initialization logic into an init task of appropriate type, and only use ServletContextListener to insert the init task instance into the proper init tasks queue. + This method exists on both <literal>AbstractHttpServlet</literal> and <literal>AbstractFilter</literal>. This is a default implementation that automatically returns <emphasis>true</emphasis> when it detects there is a current <literal>PortalContainer</literal> present and <emphasis>false</emphasis> otherwise. </para> + + <formalpara> + <title>ServletContextListener-based initialization needing to access PortalContainer</title> <para> - An example of this is Gadgets application which registers Google gadgets with the current PortalContainer: + &PRODUCT; has no direct control over the deployment of application archives (<code>.war</code> and <code>.ear</code> files); it is the application server that performs the deployment. </para> + </formalpara> + <para> + However, the applications in the <emphasis role="bold">Dependencies</emphasis> configuration must be deployed <emphasis>before</emphasis> the portal that depends on them is initialized in order for the <emphasis role="bold">extension mechanism</emphasis> to work properly. + </para> + <para> + Conversely, some applications may require an already initialized <literal>PortalContainer</literal> to properly initialize themselves. This gives rise to a recursive dependency problem. + </para> + <para> + A mechanism of <emphasis role="bold">initialization tasks</emphasis> and <emphasis role="bold">task queues</emphasis> has been implemented in &PRODUCT; to resolve this dependency issue. + </para> + <para> + Web applications that depend on a current <literal>PortalContainer</literal> to initialize must avoid performing their initialization directly on a <literal>ServletContextListener</literal> executed during their deployment (before any <literal>PortalContainer</literal> was initialized). + </para> + <para> + To ensure this, a web application should package its initialization logic into an <code>init</code> task of an appropriate type and only use <literal>ServletContextListener</literal> to insert the <code>init</code> task instance into the proper <code>init</code> tasks queue. + </para> + <para> + An example of this is the Gadgets application which registers Google gadgets with the current <literal>PortalContainer</literal>. This example uses <emphasis role="bold">PortalContainerPostInitTask</emphasis> which gets executed after the portal container has been initialized. + </para> -<programlisting role="JAVA"> +<programlisting language="Java" role="JAVA"> public class GadgetRegister implements ServletContextListener { public void contextInitialized(ServletContextEvent event) @@ -665,12 +788,25 @@ } } </programlisting> + <para> - The above example uses <emphasis role="bold">PortalContainerPostInitTask</emphasis>, which gets executed after the portal container has been initialized. In some situations you may want to execute initialization after portal container was instantiated, but before it was initialized - use <emphasis role="bold">PortalContainerPreInitTask</emphasis> in that case. Or, you may want to execute initialization after all the post-init tasks have been executed - use <emphasis role="bold">PortalContainerPostCreateTask</emphasis> in that case. + In some situations initialization may be required <emphasis>after</emphasis> the portal container is instantiated but <emphasis>before</emphasis> it has initialized. <literal>PortalContainerPreInitTask</literal> can be used in that case. </para> <para> - One more area that may need your attention are <emphasis role="bold">LoginModules</emphasis>. If you use custom LoginModules, that require current ExoContainer, make sure they extend <emphasis role="bold">org.exoplatform.services.security.jaas.AbstractLoginModule</emphasis> for proper initialization. AbstractLoginModule also takes care of the basic configuration - it recognizes two initialization options - <emphasis role="bold">portalContainerName</emphasis>, and <emphasis role="bold">realmName</emphasis> whose values you can access via protected fields of the same name. + Use <emphasis role="bold">PortalContainerPostCreateTask</emphasis> if initialization is required <emphasis>after</emphasis> all the <code>post-init</code> tasks have been executed. </para> + <formalpara> + <title>LoginModules</title> + <para> + If some custom <literal>LoginModules</literal> require the current <literal>ExoContainer</literal> for initialization ensure they extend <emphasis role="bold">org.exoplatform.services.security.jaas.AbstractLoginModule</emphasis>. + </para> + </formalpara> + <para> + <literal>AbstractLoginModule</literal> enforces some basic configuration. It recognizes two initialization options; <emphasis role="bold">portalContainerName</emphasis> and <emphasis role="bold">realmName</emphasis>. + </para> + <para> + The values for these options can be accessed via protected fields of the same name. + </para> </section> </chapter> Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/architecture.xml =================================================================== --- portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/architecture.xml 2010-05-13 06:32:28 UTC (rev 3072) +++ portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/architecture.xml 2010-05-13 07:06:06 UTC (rev 3073) @@ -13,7 +13,7 @@ </sectioninfo> <title>Basic concepts of eXoJCR</title> <para> - + DOC TODO: Needs text. </para> </section> Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/configuration.xml =================================================================== --- portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/configuration.xml 2010-05-13 06:32:28 UTC (rev 3072) +++ portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/configuration.xml 2010-05-13 07:06:06 UTC (rev 3073) @@ -5,26 +5,6 @@ ]> <section id="sect-Reference_Guide-eXo_JCR_configuration"> <title>eXo JCR configuration</title> - <section id="sect-Reference_Guide-eXo_JCR_configuration-Related_documents"> - <title>Related documents</title> - <itemizedlist> - <listitem> - <para> - <xref linkend="sect-Reference_Guide-Search_Configuration"/> - </para> - </listitem> - <listitem> - <para> - <xref linkend="sect-Reference_Guide-JDBC_Data_Container_Config"/> - </para> - </listitem> - <listitem> - <para> - <xref linkend="sect-Reference_Guide-External_Value_Storages"/> - </para> - </listitem> - </itemizedlist> - </section> <section id="sect-Reference_Guide-eXo_JCR_configuration-Portal_and_Standalone_configuration"> <title>Portal and Standalone configuration</title> @@ -32,11 +12,14 @@ Like other eXo services eXo JCR can be configured and used in portal or embedded mode (as a service embedded in eXo Portal) and in standalone mode. </para> <para> - In Embedded mode, JCR services are registered in the Portal container and the second option is to use a Standalone container. The main difference between these container types is that the first one is intended to be used in a Portal (Web) environment, while the second one can be used standalone <!--(TODO see the comprehensive page Service Configuration for Beginners for more details) -->. + In Embedded mode, JCR services are registered in the Portal container. In Standalone mode JCR uses a Standalone container. </para> <para> - The following setup procedure is used to obtain a Standalone configuration <!--(TODO find more in Container configuration)-->: + The main difference between these container types is that the first is intended to be used in a Portal (Web) environment while the second can be used standalone. <!--(DOC TODO see the comprehensive page Service Configuration for Beginners for more details) --> </para> + <para> + The following setup procedure is used to obtain a Standalone configuration: <!--(DOC TODO find more in Container configuration)--> + </para> <itemizedlist> <listitem> <para> @@ -631,8 +614,27 @@ &lt;!ELEMENT property EMPTY&gt; </programlisting> </section> - + <section id="sect-Reference_Guide-eXo_JCR_configuration-Related_documents"> + <title>Related documents</title> + <itemizedlist> + <listitem> + <para> + <xref linkend="sect-Reference_Guide-Search_Configuration"/> + </para> + </listitem> + <listitem> + <para> + <xref linkend="sect-Reference_Guide-JDBC_Data_Container_Config"/> + </para> + </listitem> + <listitem> + <para> + <xref linkend="sect-Reference_Guide-External_Value_Storages"/> + </para> + </listitem> + </itemizedlist> </section> + </section> </section> Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/intro.xml =================================================================== --- portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/intro.xml 2010-05-13 06:32:28 UTC (rev 3072) +++ portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/Advanced/JCR/intro.xml 2010-05-13 07:06:06 UTC (rev 3073) @@ -3,42 +3,45 @@ <!ENTITY % BOOK_ENTITIES SYSTEM "../../../Reference_Guide.ent"> %BOOK_ENTITIES; ]> -<section id="sect-Reference_Guide-Introduction_in_eXoJCR"> - <title>Introduction in eXoJCR</title> - <section id="sect-Reference_Guide-Introduction_in_eXoJCR-JCR_JSR_170_API_main_concepts"> - <title>JCR (JSR-170) API main concepts</title> +<section id="sect-Reference_Guide-Introduction"> + <title>Introduction</title> <para> - Java Content Repository API as well as other Java language related standards is created within the Java Community Process http://jcp.org/ as a result of collaboration of an expert group and the Java community and known as JSR-170 (Java Specification Request) http://www.jcp.org/en/jsr/detail?id=170. + The Java Content Repository(JCR) API was created within the Java Community Process <ulink type="http" url="http://jcp.org/">http://jcp.org/</ulink>) as a collaboration between an expert group and the Java community. </para> - <section id="sect-Reference_Guide-JCR_JSR_170_API_main_concepts-Data_model"> - <title>Data model</title> + <para> + Within the JCP, JCR is known as Java Specification Request-170 (JSR-170) <ulink type="http" url="http://www.jcp.org/en/jsr/detail?id=170">http://www.jcp...;. + </para> + + <section id="sect-Reference_Guide-JCR_JSR_170_API_main_concepts-The_Data_model"> + <title>The data model</title> <para> - As the main purpose of content repository is to maintain the data - the heart of CR is the data model: + The main purpose of a content repository (CR) is to maintain data. Therefore the core of any CR is the data model: </para> <para> - <itemizedlist> + Some points about the eXoJCR are: + </para> + <itemizedlist> <listitem> <para> - The main data storage abstraction of JCR's data model is a workspace + The main data storage abstraction of JCR's data model is a workspace. </para> </listitem> <listitem> <para> - Each repository should have one or more workspaces + Each repository should have one or more workspaces. </para> </listitem> <listitem> <para> - The content is stored in a workspace as a hierarchy of items + The content is stored in a workspace as a hierarchy of items. </para> </listitem> <listitem> <para> - Each workspace has its own hierarchy of items + Each workspace has its own hierarchy of items. </para> </listitem> </itemizedlist> - </para> <!-- <figure> <title>Item hierarchy</title> @@ -51,18 +54,26 @@ </figure> --> <para> - Node is intended to support the data hierarchy. They are typed using namespaced names which allows the content to be structured according to standardized constraints. A node may be versioned through an associated version graph (optional feature) + A <emphasis role="bold">node</emphasis> is intended to support the data hierarchy. They are typed using namespaced names which allows the content to be structured according to standardized constraints. </para> <para> - Property stored data are values of predefined types (String, Binary, Long, Boolean, Double, Date, Reference, Path). + A node may be versioned through an associated version graph, however this is an optional feature. </para> <para> - It is important to note that the data model for the interface (the repository model) is rarely the same as the data models used by the repository's underlying storage subsystems. The repository knows how to make the client's changes persistent because that is part of the repository configuration, rather than part of the application programming task. + <emphasis>Property stored data</emphasis> are values of predefined types such as; <emphasis role="bold">String</emphasis>, <emphasis role="bold">Binary</emphasis>, <emphasis role="bold">Long</emphasis>, <emphasis role="bold">Boolean</emphasis>, <emphasis role="bold">Double</emphasis>, <emphasis role="bold">Date</emphasis>, <emphasis role="bold">Reference</emphasis> and <emphasis role="bold">Path</emphasis>. </para> + <note> + <para> + The data model for the interface (the repository model) is rarely the same as the data models used by the repository's underlying storage subsystems. + </para> + <para> + The repository knows how to make the client's changes persistent because that is part of the repository configuration, rather than part of the application programming task. + </para> + </note> </section> - </section> + </section> Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/PortletDevelopment/Standard.xml =================================================================== --- portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/PortletDevelopment/Standard.xml 2010-05-13 06:32:28 UTC (rev 3072) +++ portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/PortletDevelopment/Standard.xml 2010-05-13 07:06:06 UTC (rev 3073) @@ -315,8 +315,8 @@ <area coords="12" id="area-Reference_Guide-Deploying_your_first_Portlet-Application_Descriptors.supports" /> <area coords="15" id="area-Reference_Guide-Deploying_your_first_Portlet-Application_Descriptors.portletinfo" /> </areaspec> -<!-- TODO XML highlight once issue https://bugzilla.redhat.com/show_bug.cgi?id=590933 resolved--> -<programlisting><![CDATA[<portlet-app xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd" + +<programlisting language="XML" role="XML"><![CDATA[<portlet-app xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_2... http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd" version="2.0"> @@ -484,7 +484,7 @@ <area coords="25" id="area-Reference_Guide-JavaServer_Pages_Portlet_Example-Portlet_Class.requestDispatcher" /> <area coords="26" id="area-Reference_Guide-JavaServer_Pages_Portlet_Example-Portlet_Class.include" /> </areaspec> -<!-- TODO JAVA highlight once issue https://bugzilla.redhat.com/show_bug.cgi?id=590933 resolved--> +<!-- TODO highlight once Publican 1.6.3 installed (JAVA)--> <programlisting><![CDATA[package org.gatein.portal.examples.portlets; import java.io.IOException; @@ -552,7 +552,7 @@ <para> The generic portlet that is inherited dispatches the different views to the methods: <literal>doView</literal> , <literal>doHelp</literal> and <literal>doEdit</literal>. </para> -<!-- TODO JAVA highlight once issue https://bugzilla.redhat.com/show_bug.cgi?id=590933 resolved--> +<!-- TODO highlight once Publican 1.6.3 installed (JAVA)--> <programlisting><![CDATA[... protected void doHelp(RenderRequest rRequest, RenderResponse rResponse) throws PortletException, IOException, UnavailableException @@ -585,7 +585,7 @@ <area coords="5" id="area-Reference_Guide-JavaServer_Pages_Portlet_Example-Portlet_Class.getActionParameter" /> <area coords="6" id="area-Reference_Guide-JavaServer_Pages_Portlet_Example-Portlet_Class.setRenderParameter" /> </areaspec> -<!-- TODO JAVA highlight once issue https://bugzilla.redhat.com/show_bug.cgi?id=590933 resolved--> +<!-- TODO highlight once Publican 1.6.3 installed (JAVA)--> <programlisting><![CDATA[... public void processAction(ActionRequest aRequest, ActionResponse aResponse) throws PortletException, IOException, UnavailableException @@ -757,8 +757,8 @@ <area coords="26" id="area-Reference_Guide-JavaServer_Pages_Portlet_Example-JSF_example_using_the_JBoss_Portlet_Bridge.edit" /> <area coords="31" id="area-Reference_Guide-JavaServer_Pages_Portlet_Example-JSF_example_using_the_JBoss_Portlet_Bridge.help" /> </areaspec> -<!-- TODO XML highlight once issue https://bugzilla.redhat.com/show_bug.cgi?id=590933 resolved--> -<programlisting><![CDATA[<?xml version="1.0" encoding="UTF-8"?> + +<programlisting language="XML" role="XML"><![CDATA[<?xml version="1.0" encoding="UTF-8"?> <portlet-app xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_2... http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd" Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/WSRP.xml =================================================================== --- portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/WSRP.xml 2010-05-13 06:32:28 UTC (rev 3072) +++ portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/WSRP.xml 2010-05-13 07:06:06 UTC (rev 3073) @@ -78,13 +78,12 @@ <note> <title>Assumptions</title> <para> - The following list asumes that <code>$GATEIN_HOME</code> is where &PRODUCT_NAME; has been installed, that <code>$WSRP_VERSION</code> is the version of the WSRP component (at the time of the writing, it was &WSRP_VERSION;) and that <code>$PORTAL_VERSION</code> is the current &PRODUCT_NAME; version (at the time of the writing, it was &PORTAL_VERSION;). + The following list asumes that &PRODUCT_NAME; has been installed into <code>$GATEIN_HOME</code>, that <code>$WSRP_VERSION</code> is the version of the WSRP component in use (at the time of the writing, it was &WSRP_VERSION;) and that <code>$PORTAL_VERSION</code> is the current &PRODUCT_NAME; version (at the time of the writing, it was &PORTAL_VERSION;). </para> </note> - <para> - WSRP support is provided by the following files: - </para> + <variablelist> + <title>WSRP support files</title> <varlistentry> <term>$GATEIN_HOME/wsrp-admin-gui.war</term> <listitem> @@ -156,16 +155,16 @@ <section id="sect-Reference_Guide-Deploying_PRODUCT_NAMEs_WSRP_services-Considerations_for_use_with_non-default_port_or_hostname"> <title>Considerations for use with non-default port or hostname</title> <para> - JBoss WS (the web service stack that &PRODUCT_NAME; uses) should take care of the details of updating the port and host name used in WSDL. See the <ulink url="http://community.jboss.org/wiki/JBossWS-UserGuide#Configuration... WS user guide on that subject </ulink> for more details. + JBoss WS (the web service stack that &PRODUCT_NAME; uses) should update the port and host name used in WSDL. See the JBoss WS <ulink url="http://community.jboss.org/wiki/JBossWS-UserGuide#Configuration... guide</ulink> for more information. </para> <para> - Of course, if you have modified you have modified the host name and port on which your server runs, you will need to update the configuration for the consumer used to consume &PRODUCT_NAME;'s 'self' producer. Please refer to the <xref linkend="sect-Reference_Guide-Web_Services_for_Remote_Portlets_WSRP-Consuming_remote_WSRP_portlets_in_PRODUCT_NAME" /> to learn how to do so. + If you have modified the host name and port on which your server runs, you will need to update the configuration for the consumer used to consume &PRODUCT_NAME;'s 'self' producer. Please refer to the <xref linkend="sect-Reference_Guide-Web_Services_for_Remote_Portlets_WSRP-Consuming_remote_WSRP_portlets_in_PRODUCT_NAME" /> to learn how to do so. </para> </section> <section id="sect-Reference_Guide-Deploying_PRODUCT_NAMEs_WSRP_services-Considerations_to_use_WSRP_with_SSL"><title>Considerations to use WSRP with SSL</title> <para> - It is possible to use WSRP over SSL for secure exchange of data. Please refer to the <ulink url="http://community.jboss.org/wiki/ConfiguringWSRPforuseoverSSL&qu... on how to do so from <ulink url="http://community.jboss.org/wiki/GateIn">GateIn's wiki</ulink>. + It is possible to use WSRP over SSL for secure exchange of data. Please refer to the <ulink url="http://community.jboss.org/wiki/ConfiguringWSRPforuseoverSSL&qu... on how to do so. </para> </section> @@ -174,70 +173,80 @@ <section id="sect-Reference_Guide-Web_Services_for_Remote_Portlets_WSRP-Making_a_portlet_remotable"> <title>Making a portlet remotable</title> <para> - &PRODUCT_NAME; does <emphasis role="bold">NOT</emphasis>, by default, expose local portlets for consumption by remote WSRP consumers. In order to make a portlet remotely available, it must be made "remotable" by marking it as such in the associated <filename>portlet.xml</filename>. This is accomplished by using a specific <code>org.gatein.pc.remotable container-runtime-option</code>. Setting its value to <code>true</code> makes the portlet available for remote consumption, while setting its value to <code>false</code> will not publish it remotely. As specifying the remotable status for a portlet is optional, you do not need to do anything if you don't need your portlet to be available remotely. + &PRODUCT_NAME; does <emphasis role="bold">NOT</emphasis>, by default, expose local portlets for consumption by remote WSRP consumers. </para> <para> + In order to make a portlet remotely available, it must be made "remotable" by marking it as such in the associated <filename>portlet.xml</filename>. + </para> + <para> + This is accomplished by using a specific <code>org.gatein.pc.remotable container-runtime-option</code>. Setting its value to <code>true</code> makes the portlet available for remote consumption, while setting its value to <code>false</code> will not publish it remotely. + </para> + <para> + As specifying the remotable status for a portlet is optional, you do not need to do anything if you do not need your portlet to be available remotely. + </para> + <para> In the following example, the "BasicPortlet" portlet is specified as being remotable. </para> - <example> - <title>BasicPortlet</title> -<programlisting> -&lt;?xml version="1.0" standalone="yes"?&gt; -&lt;portlet-app xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd" +<programlisting language="XML" role="XML"><![CDATA[<?xml version="1.0" standalone="yes"?> +<portlet-app xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_2... http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd" - version="2.0"&gt; -&lt;portlet-app&gt; - &lt;portlet&gt; - &lt;portlet-name&gt;BasicPortlet&lt;/portlet-name&gt; + version="2.0"> +<portlet-app> + <portlet> + <portlet-name>BasicPortlet</portlet-name> ... - &lt;container-runtime-option&gt; - &lt;name&gt;org.gatein.pc.remotable&lt;/name&gt; - &lt;value&gt;true&lt;/value&gt; - &lt;/container-runtime-option&gt; - &lt;/portlet&gt; -&lt;/portlet-app&gt; -</programlisting> - </example> + <container-runtime-option> + <name>org.gatein.pc.remotable</name> + <value>true</value> + </container-runtime-option> + </portlet> +</portlet-app>]]></programlisting> <para> - It is also possible to specify that all the portlets declared within a given portlet application to be remotable by default. This is done by specifying the <code> container-runtime-option </code> at the <code>portlet-app</code> element level. Individual portlets can override that value to not be remotely exposed. Let's look at an example: + It is also possible to specify that all the portlets declared within a given portlet application be remotable by default. </para> - <example> - <title>Remotable Override</title> -<programlisting> -&lt;?xml version="1.0" standalone="yes"?&gt; -&lt;portlet-app xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd" + <para> + This is done by specifying the <code>container-runtime-option</code> at the <code>portlet-app</code> element level. Individual portlets can override that value to not be remotely exposed. + </para> + <para> + For example: + </para> +<programlisting language="XML" role="XML"><![CDATA[<?xml version="1.0" standalone="yes"?> +<portlet-app xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_2... http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd" - version="2.0"&gt; -&lt;portlet-app&gt; + version="2.0"> +<portlet-app> - &lt;portlet&gt; - &lt;portlet-name&gt;RemotelyExposedPortlet&lt;/portlet-name&gt; + <portlet> + <portlet-name>RemotelyExposedPortlet</portlet-name> ... - &lt;/portlet&gt; - &lt;portlet&gt; - &lt;portlet-name&gt;NotRemotelyExposedPortlet&lt;/portlet-name&gt; + </portlet> + <portlet> + <portlet-name>NotRemotelyExposedPortlet</portlet-name> ... - &lt;container-runtime-option&gt; - &lt;name&gt;org.gatein.pc.remotable&lt;/name&gt; - &lt;value&gt;false&lt;/value&gt; - &lt;/container-runtime-option&gt; - &lt;/portlet&gt; + <container-runtime-option> + <name>org.gatein.pc.remotable</name> + <value>false</value> + </container-runtime-option> + </portlet> - &lt;container-runtime-option&gt; - &lt;name&gt;org.gatein.pc.remotable&lt;/name&gt; - &lt;value&gt;true&lt;/value&gt; - &lt;/container-runtime-option&gt; -&lt;/portlet-app&gt; -</programlisting> - </example> + <container-runtime-option> + <name>org.gatein.pc.remotable</name> + <value>true</value> + </container-runtime-option> +</portlet-app> +]]></programlisting> <para> - In the example above, we defined two portlets. The <code>org.gatein.pc.remotable container-runtime-option</code> being set to <code>true</code> at the <code>portlet-app</code> level, all portlets defined in this particular portlet application are exposed remotely by &PRODUCT_NAME;'s WSRP producer. Note, however, that it is possible to override the default behavior: specifying a value for the <code>org.gatein.pc.remotable container-runtime-option</code> at the <code>portlet</code> level will take precedence over the default. + This example defines two portlets. As the <code>org.gatein.pc.remotable container-runtime-option</code> is set to <code>true</code> at the <code>portlet-app</code> level, all portlets defined in this particular portlet application are exposed remotely by &PRODUCT_NAME;'s WSRP producer. </para> <para> + It is possible to override this default behavior. Specifying a value for the <code>org.gatein.pc.remotable container-runtime-option</code> at the <code>portlet</code> level will take precedence over the default. + </para> +<!-- Mark --> + <para> In the example above, the <varname>RemotelyExposedPortlet</varname> inherits the remotable status defined at the <code>portlet-app</code> level since it does not specify a value for the<code>org.gatein.pc.remotable container-runtime-option</code>. The<varname>NotRemotelyExposedPortlet</varname>, however, overrides the default behavior and is not remotely exposed. Note that in the absence of a top-level <code>org.gatein.pc.remotable container-runtime-option</code> value set to<code>true</code>, portlets are NOT remotely exposed. </para> </section>