March 2013 - gatein-commits - Jboss List Archives

gatein SVN: r9219 - in epp/docs/JPP/trunk/Development_Guide/en-US: code_samples and 1 other directory.

by do-not-reply＠jboss.org

Author: jaredmorgs Date: 2013-03-21 01:40:42 -0400 (Thu, 21 Mar 2013) New Revision: 9219 Added: epp/docs/JPP/trunk/Development_Guide/en-US/code_samples/ epp/docs/JPP/trunk/Development_Guide/en-US/code_samples/PortalACLPLugin_Directive.xml epp/docs/JPP/trunk/Development_Guide/en-US/code_samples/Portal_Navigation_Configuration_Navigators_Example.xml epp/docs/JPP/trunk/Development_Guide/en-US/code_samples/UserPortalConfigService_Directive.xml epp/docs/JPP/trunk/Development_Guide/en-US/code_samples/default172.java epp/docs/JPP/trunk/Development_Guide/en-US/code_samples/default173.java epp/docs/JPP/trunk/Development_Guide/en-US/code_samples/default174.java epp/docs/JPP/trunk/Development_Guide/en-US/code_samples/default175.java epp/docs/JPP/trunk/Development_Guide/en-US/code_samples/default176.java epp/docs/JPP/trunk/Development_Guide/en-US/code_samples/default177.java epp/docs/JPP/trunk/Development_Guide/en-US/code_samples/default178.java epp/docs/JPP/trunk/Development_Guide/en-US/code_samples/default179.java epp/docs/JPP/trunk/Development_Guide/en-US/code_samples/gadgets.xml epp/docs/JPP/trunk/Development_Guide/en-US/code_samples/navigation.xml epp/docs/JPP/trunk/Development_Guide/en-US/code_samples/pages.xml epp/docs/JPP/trunk/Development_Guide/en-US/code_samples/portal-configuration.xml.xml epp/docs/JPP/trunk/Development_Guide/en-US/code_samples/portal.xml epp/docs/JPP/trunk/Development_Guide/en-US/code_samples/subpage.xml Modified: epp/docs/JPP/trunk/Development_Guide/en-US/Book_Info.xml epp/docs/JPP/trunk/Development_Guide/en-US/Default_Portal_Configuration.xml epp/docs/JPP/trunk/Development_Guide/en-US/Developer_Guide.xml epp/docs/JPP/trunk/Development_Guide/en-US/Portal_Lifecycle.xml epp/docs/JPP/trunk/Development_Guide/en-US/Portal_Navigation_Configuration.xml epp/docs/JPP/trunk/Development_Guide/en-US/Portal_Permission_Configuration.xml epp/docs/JPP/trunk/Development_Guide/en-US/Skinning_The_Portal.xml epp/docs/JPP/trunk/Development_Guide/en-US/The_eXo_Kernel.xml epp/docs/JPP/trunk/Development_Guide/en-US/Visual_Identity.xml Log: Added code samples from Reference Guide to date, and renamed the extras directory to code_samples. Publican may not like this, but we will need to do a test publish on the content. Modified: epp/docs/JPP/trunk/Development_Guide/en-US/Book_Info.xml =================================================================== --- epp/docs/JPP/trunk/Development_Guide/en-US/Book_Info.xml 2013-03-21 02:26:49 UTC (rev 9218) +++ epp/docs/JPP/trunk/Development_Guide/en-US/Book_Info.xml 2013-03-21 05:40:42 UTC (rev 9219) @@ -10,7 +10,7 @@ <productnumber>6</productnumber> <edition>6.0.0</edition> <abstract> - <para>The JBoss Portal Platform Developer Guide is intended for those developing applications and gadgets for the JBoss Portal Platform product, and outlines options and strategies for successful deployment. + <para>The JBoss Portal Platform Developer Guide is intended for those developing portlet applications and gadgets for the JBoss Portal Platform product, and outlines options and strategies for successful deployment. </para> </abstract> Modified: epp/docs/JPP/trunk/Development_Guide/en-US/Default_Portal_Configuration.xml =================================================================== (Binary files differ) Modified: epp/docs/JPP/trunk/Development_Guide/en-US/Developer_Guide.xml =================================================================== --- epp/docs/JPP/trunk/Development_Guide/en-US/Developer_Guide.xml 2013-03-21 02:26:49 UTC (rev 9218) +++ epp/docs/JPP/trunk/Development_Guide/en-US/Developer_Guide.xml 2013-03-21 05:40:42 UTC (rev 9219) @@ -33,6 +33,7 @@ <part> <title>Application Development</title> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Gadget_Development.xml" encoding="UTF-8"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../Portlet_Development_Resources.xml" encoding="UTF-8"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Portlet_Development.xml" encoding="UTF-8"/> </part> <part> Modified: epp/docs/JPP/trunk/Development_Guide/en-US/Portal_Lifecycle.xml =================================================================== (Binary files differ) Modified: epp/docs/JPP/trunk/Development_Guide/en-US/Portal_Navigation_Configuration.xml =================================================================== (Binary files differ) Modified: epp/docs/JPP/trunk/Development_Guide/en-US/Portal_Permission_Configuration.xml =================================================================== (Binary files differ) Modified: epp/docs/JPP/trunk/Development_Guide/en-US/Skinning_The_Portal.xml =================================================================== (Binary files differ) Modified: epp/docs/JPP/trunk/Development_Guide/en-US/The_eXo_Kernel.xml =================================================================== (Binary files differ) Modified: epp/docs/JPP/trunk/Development_Guide/en-US/Visual_Identity.xml =================================================================== (Binary files differ) Added: epp/docs/JPP/trunk/Development_Guide/en-US/code_samples/PortalACLPLugin_Directive.xml =================================================================== --- epp/docs/JPP/trunk/Development_Guide/en-US/code_samples/PortalACLPLugin_Directive.xml (rev 0) +++ epp/docs/JPP/trunk/Development_Guide/en-US/code_samples/PortalACLPLugin_Directive.xml 2013-03-21 05:40:42 UTC (rev 9219) @@ -0,0 +1,20 @@ +<external-component-plugins> + <target-component>org.exoplatform.portal.config.UserACL</target-component> + <component-plugin> + <name>addPortalACLPlugin</name> + <set-method>addPortalACLPlugin</set-method> + <type>org.exoplatform.portal.config.PortalACLPlugin</type> + <description>setting some permission for portal</description> + <init-params> + <values-param> + <name>super.user</name> + <value>root</value> + </values-param> + <values-param> + <name>portal.creation.roles</name> + <value>*:/platform/administrators</value> + <value>*:/organization/management/executive-board</value> + </values-param> + </init-params> + </component-plugin> +</external-component-plugins> \ No newline at end of file Added: epp/docs/JPP/trunk/Development_Guide/en-US/code_samples/Portal_Navigation_Configuration_Navigators_Example.xml =================================================================== --- epp/docs/JPP/trunk/Development_Guide/en-US/code_samples/Portal_Navigation_Configuration_Navigators_Example.xml (rev 0) +++ epp/docs/JPP/trunk/Development_Guide/en-US/code_samples/Portal_Navigation_Configuration_Navigators_Example.xml 2013-03-21 05:40:42 UTC (rev 9219) @@ -0,0 +1,100 @@ +<component> + <key>org.exoplatform.portal.config.UserPortalConfigService</key> + <type>org.exoplatform.portal.config.UserPortalConfigService</type> + <component-plugins> + <component-plugin> + <name>new.portal.config.user.listener</name> + <set-method>initListener</set-method> + <type>org.exoplatform.portal.config.NewPortalConfigListener</type> + <description>this listener init the portal configuration</description> + <init-params> + <value-param> + <name>default.portal</name> + <description>The default portal for checking db is empty or not</description> + <value>classic</value> + </value-param> + <value-param> + <name>page.templates.location</name> + <description>the path to the location that contains Page templates</description> + <value>war:/conf/portal/template/pages</value> + </value-param> + <object-param> + <name>site.templates.location</name> + <description>description</description> + <object type="org.exoplatform.portal.config.SiteConfigTemplate"> + <field name="location"> + <string>war:/conf/portal</string> + </field> + <field name="portalTemplates"> + <collection type="java.util.HashSet"> + <value> + <string>classic</string> + </value> + </collection> + </field> + <field name="groupTemplates"> + <collection type="java.util.HashSet"> + <value> + <string>group</string> + </value> + </collection> + </field> + <field name="userTemplates"> + <collection type="java.util.HashSet"> + <value> + <string>user</string> + </value> + </collection> + </field> + </object> + </object-param> + <object-param> + <name>portal.configuration</name> + <description>description</description> + <object type="org.exoplatform.portal.config.NewPortalConfig"> + <field name="predefinedOwner"> + <collection type="java.util.HashSet"> + <value><string>classic</string></value> + </collection> + </field> + <field name="ownerType"><string>portal</string></field> + <field name="templateLocation"><string>war:/conf/portal/</string></field> + </object> + </object-param> + <object-param> + <name>group.configuration</name> + <description>description</description> + <object type="org.exoplatform.portal.config.NewPortalConfig"> + <field name="predefinedOwner"> + <collection type="java.util.HashSet"> + <value><string>/platform/administrators</string></value> + <value><string>/platform/users</string></value> + <value><string>/platform/guests</string></value> + <value><string>/organization/management/executive-board</string></value> + </collection> + </field> + <field name="ownerType"><string>group</string></field> + <field name="templateLocation"><string>war:/conf/portal</string></field> + </object> + </object-param> + <object-param> + <name>user.configuration</name> + <description>description</description> + <object type="org.exoplatform.portal.config.NewPortalConfig"> + <field name="predefinedOwner"> + <collection type="java.util.HashSet"> + <value><string>root</string></value> + <value><string>john</string></value> + <value><string>mary</string></value> + <value><string>demo</string></value> + <value><string>user</string></value> + </collection> + </field> + <field name="ownerType"><string>user</string></field> + <field name="templateLocation"><string>war:/conf/portal</string></field> + </object> + </object-param> + </init-params> + </component-plugin> + </component-plugins> +</component> Added: epp/docs/JPP/trunk/Development_Guide/en-US/code_samples/UserPortalConfigService_Directive.xml =================================================================== --- epp/docs/JPP/trunk/Development_Guide/en-US/code_samples/UserPortalConfigService_Directive.xml (rev 0) +++ epp/docs/JPP/trunk/Development_Guide/en-US/code_samples/UserPortalConfigService_Directive.xml 2013-03-21 05:40:42 UTC (rev 9219) @@ -0,0 +1,20 @@ +<component> + <key>org.exoplatform.portal.config.UserPortalConfigService</key> + <type>org.exoplatform.portal.config.UserPortalConfigService</type> + <component-plugins> + <component-plugin> + <name>new.portal.config.user.listener</name> + <set-method>initListener</set-method> + <type>org.exoplatform.portal.config.NewPortalConfigListener</type> + <description>this listener init the portal configuration</description> + <init-params> + <value-param> + <name>default.portal</name> + <description>The default portal for checking db is empty or not</description> + <value>classic</value> + </value-param> + ... + </init-params> + </component-plugin> + </component-plugins> + </component> Added: epp/docs/JPP/trunk/Development_Guide/en-US/code_samples/default172.java =================================================================== --- epp/docs/JPP/trunk/Development_Guide/en-US/code_samples/default172.java (rev 0) +++ epp/docs/JPP/trunk/Development_Guide/en-US/code_samples/default172.java 2013-03-21 05:40:42 UTC (rev 9219) @@ -0,0 +1,8 @@ + LT, // Western Europe + RT, // Middle East (Arabic, Hebrew) + TL, // Japanese, Chinese, Korean + TR; // Mongolian + public boolean isLT() { ... } + public boolean isRT() { ... } + public boolean isTL() { ... } + public boolean isTR() { ... } Added: epp/docs/JPP/trunk/Development_Guide/en-US/code_samples/default173.java =================================================================== --- epp/docs/JPP/trunk/Development_Guide/en-US/code_samples/default173.java (rev 0) +++ epp/docs/JPP/trunk/Development_Guide/en-US/code_samples/default173.java 2013-03-21 05:40:42 UTC (rev 9219) @@ -0,0 +1,5 @@ +float: left; /* orientation=lt */ +float: right; /* orientation=rt */ +font-weight: bold; +text-align: center; +white-space: nowrap; Added: epp/docs/JPP/trunk/Development_Guide/en-US/code_samples/default174.java =================================================================== --- epp/docs/JPP/trunk/Development_Guide/en-US/code_samples/default174.java (rev 0) +++ epp/docs/JPP/trunk/Development_Guide/en-US/code_samples/default174.java 2013-03-21 05:40:42 UTC (rev 9219) @@ -0,0 +1,4 @@ +float: left; /* orientation=lt */ +font-weight: bold; +text-align: center; +white-space: nowrap; Added: epp/docs/JPP/trunk/Development_Guide/en-US/code_samples/default175.java =================================================================== --- epp/docs/JPP/trunk/Development_Guide/en-US/code_samples/default175.java (rev 0) +++ epp/docs/JPP/trunk/Development_Guide/en-US/code_samples/default175.java 2013-03-21 05:40:42 UTC (rev 9219) @@ -0,0 +1,5 @@ + +float: right; /* orientation=rt */ +font-weight: bold; +text-align: center; +white-space: nowrap; Added: epp/docs/JPP/trunk/Development_Guide/en-US/code_samples/default176.java =================================================================== --- epp/docs/JPP/trunk/Development_Guide/en-US/code_samples/default176.java (rev 0) +++ epp/docs/JPP/trunk/Development_Guide/en-US/code_samples/default176.java 2013-03-21 05:40:42 UTC (rev 9219) @@ -0,0 +1,4 @@ +color: white; +line-height: 24px; +padding: 0px 5px 0px 0px; /* orientation=lt */ +padding: 0px 0px 0px 5px; /* orientation=rt */ Added: epp/docs/JPP/trunk/Development_Guide/en-US/code_samples/default177.java =================================================================== --- epp/docs/JPP/trunk/Development_Guide/en-US/code_samples/default177.java (rev 0) +++ epp/docs/JPP/trunk/Development_Guide/en-US/code_samples/default177.java 2013-03-21 05:40:42 UTC (rev 9219) @@ -0,0 +1,4 @@ + +color: white; +line-height: 24px; +padding: 0px 5px 0px 0px; /* orientation=lt */ Added: epp/docs/JPP/trunk/Development_Guide/en-US/code_samples/default178.java =================================================================== --- epp/docs/JPP/trunk/Development_Guide/en-US/code_samples/default178.java (rev 0) +++ epp/docs/JPP/trunk/Development_Guide/en-US/code_samples/default178.java 2013-03-21 05:40:42 UTC (rev 9219) @@ -0,0 +1,4 @@ + +color: white; +line-height: 24px; +padding: 0px 0px 0px 5px; /* orientation=rt */ Added: epp/docs/JPP/trunk/Development_Guide/en-US/code_samples/default179.java =================================================================== --- epp/docs/JPP/trunk/Development_Guide/en-US/code_samples/default179.java (rev 0) +++ epp/docs/JPP/trunk/Development_Guide/en-US/code_samples/default179.java 2013-03-21 05:40:42 UTC (rev 9219) @@ -0,0 +1,5 @@ +line-height: 24px; +background: url('background/NavigationTab.gif') no-repeat right top; /* orientation=lt */ +background: url('background/NavigationTab-rt.gif') no-repeat left top; /* orientation=rt */ +padding-right: 2px; /* orientation=lt */ +padding-left: 2px; /* orientation=rt */ Added: epp/docs/JPP/trunk/Development_Guide/en-US/code_samples/gadgets.xml =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Development_Guide/en-US/code_samples/gadgets.xml ___________________________________________________________________ Added: svn:mime-type + application/xml Added: epp/docs/JPP/trunk/Development_Guide/en-US/code_samples/navigation.xml =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Development_Guide/en-US/code_samples/navigation.xml ___________________________________________________________________ Added: svn:mime-type + application/xml Added: epp/docs/JPP/trunk/Development_Guide/en-US/code_samples/pages.xml =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Development_Guide/en-US/code_samples/pages.xml ___________________________________________________________________ Added: svn:mime-type + application/xml Added: epp/docs/JPP/trunk/Development_Guide/en-US/code_samples/portal-configuration.xml.xml =================================================================== --- epp/docs/JPP/trunk/Development_Guide/en-US/code_samples/portal-configuration.xml.xml (rev 0) +++ epp/docs/JPP/trunk/Development_Guide/en-US/code_samples/portal-configuration.xml.xml 2013-03-21 05:40:42 UTC (rev 9219) @@ -0,0 +1,40 @@ +<component> + <key>org.exoplatform.portal.config.UserACL</key> + <type>org.exoplatform.portal.config.UserACL</type> + <init-params> + <value-param> + <name>super.user</name> + <description>administrator</description> + <value>root</value> + </value-param> + + <value-param> + <name>portal.creator.groups</name> + <description>groups with membership type have permission to manage portal</description> + <value>*:/platform/administrators,*:/organization/management/executive-board</value> + </value-param> + + <value-param> + <name>navigation.creator.membership.type</name> + <description>specific membership type have full permission with group navigation</description> + <value>manager</value> + </value-param> + <value-param> + <name>guests.group</name> + <description>guests group</description> + <value>/platform/guests</value> + </value-param> + <values-param> + <name>mandatory.groups</name> + <description>Groups that can not be deleted.</description> + <value>/platform/administrators</value> + <value>/platform/users</value> + <value>/platform/guests</value> + </values-param> + <values-param> + <name>mandatory.mstypes</name> + <description>Membership type that can not be deleted.</description> + <value>member</value> + </values-param> + </init-params> +</component> \ No newline at end of file Added: epp/docs/JPP/trunk/Development_Guide/en-US/code_samples/portal.xml =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Development_Guide/en-US/code_samples/portal.xml ___________________________________________________________________ Added: svn:mime-type + application/xml Added: epp/docs/JPP/trunk/Development_Guide/en-US/code_samples/subpage.xml =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Development_Guide/en-US/code_samples/subpage.xml ___________________________________________________________________ Added: svn:mime-type + application/xml

11 years, 9 months

1
0
0 / 0

gatein SVN: r9218 - in epp/docs/JPP/trunk/Reference_Guide/en-US/modules: Advanced and 2 other directories.

by do-not-reply＠jboss.org

Author: jaredmorgs Date: 2013-03-20 22:26:49 -0400 (Wed, 20 Mar 2013) New Revision: 9218 Modified: epp/docs/JPP/trunk/Reference_Guide/en-US/modules/Advanced/Foundations.xml epp/docs/JPP/trunk/Reference_Guide/en-US/modules/PortalDevelopment.xml epp/docs/JPP/trunk/Reference_Guide/en-US/modules/PortalDevelopment/DataImportStrategy.xml epp/docs/JPP/trunk/Reference_Guide/en-US/modules/PortalDevelopment/DefaultPortalConfiguration.xml epp/docs/JPP/trunk/Reference_Guide/en-US/modules/PortalDevelopment/DefaultPortalNavigationConfiguration.xml epp/docs/JPP/trunk/Reference_Guide/en-US/modules/PortalDevelopment/DefaultPortalPermissionConfiguration.xml epp/docs/JPP/trunk/Reference_Guide/en-US/modules/PortalDevelopment/InternationalizationConfiguration.xml epp/docs/JPP/trunk/Reference_Guide/en-US/modules/PortalDevelopment/JavascriptInterApplicationCommunication.xml epp/docs/JPP/trunk/Reference_Guide/en-US/modules/PortalDevelopment/LocalizationConfiguration.xml epp/docs/JPP/trunk/Reference_Guide/en-US/modules/PortalDevelopment/NavigationController.xml epp/docs/JPP/trunk/Reference_Guide/en-US/modules/PortalDevelopment/PortalLifecycle.xml epp/docs/JPP/trunk/Reference_Guide/en-US/modules/PortalDevelopment/RTLFramework.xml epp/docs/JPP/trunk/Reference_Guide/en-US/modules/PortalDevelopment/Skinning.xml epp/docs/JPP/trunk/Reference_Guide/en-US/modules/PortalDevelopment/XMLResourceBundles.xml epp/docs/JPP/trunk/Reference_Guide/en-US/modules/PortletDevelopment/Global_Portlet.xml epp/docs/JPP/trunk/Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge.xml epp/docs/JPP/trunk/Reference_Guide/en-US/modules/PortletDevelopment/Standard.xml epp/docs/JPP/trunk/Reference_Guide/en-US/modules/ServerIntegration.xml Log: Made <remark> statements in all migrated sections for tracking purposes. All Portal and Portlet Development topics are migrated over to the Developers Guide. Modified: epp/docs/JPP/trunk/Reference_Guide/en-US/modules/Advanced/Foundations.xml =================================================================== --- epp/docs/JPP/trunk/Reference_Guide/en-US/modules/Advanced/Foundations.xml 2013-03-21 02:18:56 UTC (rev 9217) +++ epp/docs/JPP/trunk/Reference_Guide/en-US/modules/Advanced/Foundations.xml 2013-03-21 02:26:49 UTC (rev 9218) @@ -5,15 +5,3359 @@ ]> <chapter id="chap-Reference_Guide-Foundations"> <title>The eXo Kernel</title> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Foundations/Kernel.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Foundations/Config_Retrieval.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Foundations/Advanced_Concepts.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Foundations/Profiles.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Foundations/Requests.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Foundations/Configuring_Services.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Foundations/Specific_Services.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Foundations/Configuring_Containers.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Foundations/System_Properties.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Foundations/Extensions_And_Multiple_Portals.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Foundations/Management.xml"/> + <remark>MOVED to Development Guide - The_eXo_Kernel.xml</remark> + <section xmlns="" id="sect-Reference_Guide-The_eXo_Kernel"> + <title>eXo Kernel</title> + <para> +JBoss Portal Platform is built as a set of services on top of a dependency injection kernel. The kernel provides configuration, life-cycle handling, component scopes and some core services. + </para> + <para> + The portal kernel and the JCR used in JBoss Portal Platform use the <emphasis>Inversion of Control</emphasis> (<emphasis role="bold">IoC</emphasis>) system to control service instantiation. This method is also known as 'dependency injection'. + </para> + <para> + In this system, services are not responsible for the instantiation of the components on which they depend. It prevents objects creating the instances of any objects referenced. This task is delegated to the container. The below image illustrates this: + </para> + <figure> + <title id="IOC.">Inversion of Control</title> + <mediaobject> + <imageobject role="html"> + <imagedata width="444" align="center" fileref="images/Advanced/Foundations/ioc.png" format="PNG"/> + </imageobject> + <imageobject role="fo"> + <imagedata width="444" align="center" fileref="images/Advanced/Foundations/ioc.png" format="PNG"/> + </imageobject> + </mediaobject> + </figure> + <para> + There are two ways to inject a dependency : + </para> + <para> + Using a constructor: + </para> + <programlisting language="Java" role="Java">public ServiceA(ServiceB serviceB)</programlisting> + <para> + Using setter methods: + </para> + <programlisting language="Java" role="Java">public void setServiceB(ServiceB serviceB)</programlisting> + <para> + When a client service can not be stored in the container then the service locator pattern is used: + </para> + <programlisting language="Java" role="Java">public ServiceA(){ +this.serviceB =Container.getSInstance().getService(ServiceB.class); +}</programlisting> + <para> + The container package is responsible of building a hierarchy of containers. Each service will then be registered in one container or the other according to the XML configuration file it is defined in. It is important to understand that there can be several PortalContainer instances that all are children of the RootContainer. + </para> + <para> + The behavior of the hierarchy is similar to a class loader one, hence when you will lookup a service that depends on another one, the container will look for it in the current container and if it cannot be found, then it will look in the parent container. That way you can load all the reusable business logic components in the same container (here the RootContainer) and differentiate the service implementation from one portal instance to the other by just loading different service implementations in two sibling PortalContainers. + </para> + <para> + Therefore, if you look at the Portal Container as a service repository for all the business logic in a portal instance, then you understand why several PortalContainers allows you to manage several portals (each one deployed as a single war) in the same server by just changing XML configuration files. + </para> + <para> + The default configuration XML files are packaged in the service jar. There are three configuration.xml files, one for each container type. In that XML file, we define the list of services and their init parameters that will be loaded in the corresponding container. + </para> + <para> + 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 <literal>PortalContainer</literal>, is portal-specific. Each portal exists in an instance of the <literal>PortalContainer</literal>. This scope contains services that are common for a set of portals, and services which should not be shared by all portals. + </para> + <itemizedlist> + <listitem> + <para> + RootContainer: This is a base container. This container plays an important role during startup, but you should not use it directly. + </para> + </listitem> + <listitem> + <para> + PortalContainer: Created at the startup of the portal web application (in the init() method of the PortalController servlet) + </para> + </listitem> + </itemizedlist> + <para> +<figure> + <title id="Portalcontainers">Portal Containers</title> + <mediaobject> + <imageobject role="html"> + <imagedata width="444" align="center" scale="100" fileref="images/Advanced/Foundations/PortalContainers.png" format="PNG"/> + </imageobject> + <imageobject role="fo"> + <imagedata width="444" contentwidth="150mm" align="center" fileref="images/Advanced/Foundations/PortalContainers.png" format="PNG"/> + </imageobject> + </mediaobject> + </figure> + + </para> + <para> + As there can be several portal container instances per JVM. it is important to be able to configure the loaded services per instance. Therefore all the default configuration files located in the service impl jar can be overridden from the portal war. + </para> + <para> + Whenever a specific service is looked up through the <literal>PortalContainer</literal>, and the service is not available, the lookup is delegated further up to the <literal>RootContainer</literal>. + </para> + <para> +JBoss Portal Platform can have default instances of a certain component in the <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 eXo services, these services can be looked up through the <literal>PortalContainer</literal>. + </para> + <important> + <para> + Only officially documented services should be accessed this way, and used according to documentation, as most of the services are an implementation detail of eXo, and subject to change without notice. + </para> + </important> + <section id="sect-Reference_Guide-The_eXo_Kernel-Kernel_configuration_namespace"> + <title>Kernel configuration namespace</title> + <para> + To be effective, the namespace URI <uri>http://www.exoplaform.org/xml/ns/kernel_1_2.xsd</uri> must be target namespace of the XML configuration file. + </para> + <programlisting language="XML" role="XML"><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"> + + +... +</configuration></programlisting> + <note> + <para> + Any values in the configuration files can be created thanks to variables since the eXo kernel resolves them, for example the following configuration will be well interpreted: + </para> + <programlisting language="XML" role="XML"><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"> + +<import>${db.configuration.path}/db.xml</import> +<import>${java.io.tmpdir}/bindfile.xml</import> +<import>simple.xml</import> + +</configuration></programlisting> + <para> + The variables that are supported, are System properties and variables that are specific to your portal container, see next sections for more details. + </para> + </note> + </section> + </section> + <section xmlns="" 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>/conf/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> + </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> + <remark>NEEDINFO - FILE PATHS - the file before was configuration.xml, but I'm pretty sure all this is defined in standalone.xml now, correct?</remark> + <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>...... + Add configuration jar:file:/D:/Projects/eXo/dev/exo-working/exo-tomcat/lib/exo.kernel.container-trunk.jar!/conf/portal/configuration.xml + Add configuration jar:file:/D:/Projects/eXo/dev/exo-working/exo-tomcat/lib/exo.kernel.component.cache-trunk.jar!/conf/portal/configuration.xml + Add configuration jndi:/localhost/portal/WEB-INF/conf/configuration.xml + import jndi:/localhost/portal/WEB-INF/conf/common/common-configuration.xml + import jndi:/localhost/portal/WEB-INF/conf/database/database-configuration.xml + import jndi:/localhost/portal/WEB-INF/conf/ecm/jcr-component-plugins-configuration.xml + import jndi:/localhost/portal/WEB-INF/conf/jcr/jcr-configuration.xml + ......</programlisting> + <para> + 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 plug-in has been initialized. + </para> + </section> + <section xmlns="" 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 JBoss Portal Platform. + </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"><?xml version="1.0" encoding="ISO-8859-1" ?> +<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN" + "http://java.sun.com/dtd/web-app_2_3.dtd"> +<web-app> +... +  +  +  + <listener> + <listener-class>org.exoplatform.container.web.PortalContainerConfigOwner</listener-class> + </listener> +... +</web-app></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 JBoss Portal Platform, 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"> <component> +  + <type>org.exoplatform.container.definition.PortalContainerConfig</type> + <init-params> +  + <value-param> + <name>default.portal.container</name> + <value>myPortal</value> + </value-param> +  + <value-param> + <name>default.rest.context</name> + <value>myRest</value> + </value-param> +  + <value-param> + <name>default.realm.name</name> + <value>my-exo-domain</value> + </value-param> +  + <value-param> + <name>ignore.unregistered.webapp</name> + <value>true</value> + </value-param> +  +  + <object-param> + <name>default.portal.definition</name> + <object type="org.exoplatform.container.definition.PortalContainerDefinition"> +  + <field name="dependencies"> + <collection type="java.util.ArrayList"> + <value> + <string>foo</string> + </value> + <value> + <string>foo2</string> + </value> + <value> + <string>foo3</string> + </value> + </collection> + </field> +  + <field name="settings"> + <map type="java.util.HashMap"> + <entry> + <key> + <string>foo5</string> + </key> + <value> + <string>value</string> + </value> + </entry> + <entry> + <key> + <string>string</string> + </key> + <value> + <string>value0</string> + </value> + </entry> + <entry> + <key> + <string>int</string> + </key> + <value> + <int>100</int> + </value> + </entry> + </map> + </field> +  + <field name="externalSettingsPath"> + <string>classpath:/org/exoplatform/container/definition/default-settings.properties</string> + </field> + </object> + </object-param> + </init-params> + </component></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 JBoss Portal Platform 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"> <external-component-plugins> +  + <target-component>org.exoplatform.container.definition.PortalContainerConfig</target-component> + <component-plugin> +  + <name>Add PortalContainer Definitions</name> +  + <set-method>registerPlugin</set-method> +  + <type>org.exoplatform.container.definition.PortalContainerDefinitionPlugin</type> + <init-params> + <object-param> + <name>portal</name> + <object type="org.exoplatform.container.definition.PortalContainerDefinition"> +  + <field name="name"> + <string>myPortal</string> + </field> +  + <field name="restContextName"> + <string>myRest</string> + </field> +  + <field name="realmName"> + <string>my-domain</string> + </field> +  + <field name="dependencies"> + <collection type="java.util.ArrayList"> + <value> + <string>foo</string> + </value> + <value> + <string>foo2</string> + </value> + <value> + <string>foo3</string> + </value> + </collection> + </field> +  + <field name="settings"> + <map type="java.util.HashMap"> + <entry> + <key> + <string>foo</string> + </key> + <value> + <string>value</string> + </value> + </entry> + <entry> + <key> + <string>int</string> + </key> + <value> + <int>10</int> + </value> + </entry> + <entry> + <key> + <string>long</string> + </key> + <value> + <long>10</long> + </value> + </entry> + <entry> + <key> + <string>double</string> + </key> + <value> + <double>10</double> + </value> + </entry> + <entry> + <key> + <string>boolean</string> + </key> + <value> + <boolean>true</boolean> + </value> + </entry> + </map> + </field> +  + <field name="externalSettingsPath"> + <string>classpath:/org/exoplatform/container/definition/settings.properties</string> + </field> + </object> + </object-param> + </init-params> + </component-plugin> + </external-component-plugins></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 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> + + </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 can 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 can 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 can 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 can 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 JBoss Portal Platform 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"><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"> + <component> + <type>org.exoplatform.container.TestPortalContainer$MyComponent</type> + <init-params> +  + <value-param> + <name>portal</name> + <value>${portal.container.name}</value> + </value-param> +  + <value-param> + <name>rest</name> + <value>${portal.container.rest}</value> + </value-param> +  + <value-param> + <name>realm</name> + <value>${portal.container.realm}</value> + </value-param> + <value-param> + <name>foo</name> + <value>${portal.container.foo}</value> + </value-param> + <value-param> + <name>before foo after</name> + <value>before ${portal.container.foo} after</value> + </value-param> + </init-params> + </component> +</configuration></programlisting> + <para> + In the properties file corresponding to the external settings, you can reuse variables previously defined (in the external settings or in the internal settings) to create a new variable. In this case, the prefix "<emphasis>portal.container.</emphasis>" is not needed, see an example below: +<programlisting>my-var1=value 1 +my-var2=value 2 +complex-value=${my-var1}-${my-var2}</programlisting> + + </para> + <para> + In the external and internal settings, you can also use create variables based on value of System 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> + 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"><external-component-plugins> +  + <target-component>org.exoplatform.container.definition.PortalContainerConfig</target-component> + <component-plugin> +  + <name>Change PortalContainer Definitions</name> +  + <set-method>registerChangePlugin</set-method> +  + <type>org.exoplatform.container.definition.PortalContainerDefinitionChangePlugin</type> + <init-params> + <value-param> + <name>apply.default</name> + <value>true</value> + </value-param> + <values-param> + <name>apply.specific</name> + <value>foo1</value> + <value>foo2</value> + </values-param> + <object-param> + <name>change</name> + <object type="org.exoplatform.container.definition.PortalContainerDefinitionChange$AddDependencies"> +  + <field name="dependencies"> + <collection type="java.util.ArrayList"> + <value> + <string>foo</string> + </value> + </collection> + </field> + </object> + </object-param> + </init-params> + </component-plugin> +</external-component-plugins></programlisting> + <table 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 JBoss Portal Platform 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"><external-component-plugins> +  + <target-component>org.exoplatform.container.definition.PortalContainerConfig</target-component> + <component-plugin> +  + <name>Change PortalContainer Definitions</name> +  + <set-method>registerChangePlugin</set-method> +  + <type>org.exoplatform.container.definition.PortalContainerDefinitionChangePlugin</type> + <init-params> + <value-param> + <name>apply.default</name> + <value>true</value> + </value-param> + <object-param> + <name>change</name> + <object type="org.exoplatform.container.definition.PortalContainerDefinitionChange$AddDependencies"> +  + <field name="dependencies"> + <collection type="java.util.ArrayList"> + <value> + <string>foo</string> + </value> + </collection> + </field> + </object> + </object-param> + </init-params> + </component-plugin> +</external-component-plugins></programlisting> + </section> + <section 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"><external-component-plugins> +  + <target-component>org.exoplatform.container.definition.PortalContainerConfig</target-component> + <component-plugin> +  + <name>Change PortalContainer Definitions</name> +  + <set-method>registerChangePlugin</set-method> +  + <type>org.exoplatform.container.definition.PortalContainerDefinitionChangePlugin</type> + <init-params> + <value-param> + <name>apply.default</name> + <value>true</value> + </value-param> + <object-param> + <name>change</name> + <object type="org.exoplatform.container.definition.PortalContainerDefinitionChange$AddDependenciesBefore"> +  + <field name="dependencies"> + <collection type="java.util.ArrayList"> + <value> + <string>foo</string> + </value> + </collection> + </field> +  + <field name="target"> + <string>foo2</string> + </field> + </object> + </object-param> + </init-params> + </component-plugin> +</external-component-plugins></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"><external-component-plugins> +  + <target-component>org.exoplatform.container.definition.PortalContainerConfig</target-component> + <component-plugin> +  + <name>Change PortalContainer Definitions</name> +  + <set-method>registerChangePlugin</set-method> +  + <type>org.exoplatform.container.definition.PortalContainerDefinitionChangePlugin</type> + <init-params> + <value-param> + <name>apply.default</name> + <value>true</value> + </value-param> + <object-param> + <name>change</name> + <object type="org.exoplatform.container.definition.PortalContainerDefinitionChange$AddDependenciesAfter"> +  + <field name="dependencies"> + <collection type="java.util.ArrayList"> + <value> + <string>foo</string> + </value> + </collection> + </field> +  + <field name="target"> + <string>foo2</string> + </field> + </object> + </object-param> + </init-params> + </component-plugin> +</external-component-plugins></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><String, Object></emphasis> corresponding to the settings to add. If the value of this field is empty, the change will be ignored. </entry> + </row> + </tbody> + </tgroup> + </table> + <para> + See an example below, that will add the settings <envar>string</envar> and <envar>stringX</envar> to the settings of the default portal container: + </para> + <programlisting language="XML" role="XML"><external-component-plugins> +  + <target-component>org.exoplatform.container.definition.PortalContainerConfig</target-component> + <component-plugin> +  + <name>Change PortalContainer Definitions</name> +  + <set-method>registerChangePlugin</set-method> +  + <type>org.exoplatform.container.definition.PortalContainerDefinitionChangePlugin</type> + <init-params> + <value-param> + <name>apply.default</name> + <value>true</value> + </value-param> + <object-param> + <name>change</name> + <object type="org.exoplatform.container.definition.PortalContainerDefinitionChange$AddSettings"> +  + <field name="settings"> + <map type="java.util.HashMap"> + <entry> + <key> + <string>string</string> + </key> + <value> + <string>value1</string> + </value> + </entry> + <entry> + <key> + <string>stringX</string> + </key> + <value> + <string>value1</string> + </value> + </entry> + </map> + </field> + </object> + </object-param> + </init-params> + </component-plugin> +</external-component-plugins></programlisting> + </section> + </section> + </section> + <section 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"><external-component-plugins> +  + <target-component>org.exoplatform.container.definition.PortalContainerConfig</target-component> + <component-plugin> +  + <name>Disable a PortalContainer</name> +  + <set-method>registerDisablePlugin</set-method> +  + <type>org.exoplatform.container.definition.PortalContainerDefinitionDisablePlugin</type> + <init-params> +  + <values-param> + <name>names</name> + <value>foo</value> + </values-param> + </init-params> + </component-plugin> +</external-component-plugins></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 JBoss Portal Platform 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"><filter> + <filter-name>PortalContainerFilter</filter-name> + <filter-class>org.exoplatform.container.web.PortalContainerFilter</filter-class> +</filter> + +<filter-mapping> + <filter-name>PortalContainerFilter</filter-name> + <url-pattern>/*</url-pattern> +</filter-mapping></programlisting> + <note> + <para> + It is only possible to disable a portal container when at least one PortalContainerDefinition has been registered. + </para> + </note> + </section> + </section> + <section xmlns="" 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 JBoss Portal Platform on Tomcat with the profiles tomcat and foo +sh JBoss Portal Platform.sh -Dexo.profiles=foo + +# runs JBoss Portal Platform 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"><component> + <key>Component</key> + <type>Component</type> +</component> + +<component profiles="foo"> + <key>Component</key> + <type>FooComponent</type> +</component></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-plugin> elements can be enabled or disabled: + </para> + <programlisting language="XML" role="XML"><external-component-plugins> + <target-component>Component</target-component> + <component-plugin profiles="foo"> + <name>foo</name> + <set-method>addPlugin</set-method> + <type>type</type> + <init-params> + <value-param> + <name>param</name> + <value>empty</value> + </value-param> + </init-params> + </component-plugin> +</external-component-plugins></programlisting> + </section> + <section 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"><import>empty</import> +<import profiles="foo">foo</import> +<import profiles="bar">bar</import></programlisting> + </section> + <section id="sect-Reference_Guide-Profiles_capable_configuration_elements-Init_param_element"> + <title><init-params> element</title> + <para> + The <init-params> element configures the parameter argument of the construction of a component service: + </para> + <programlisting language="XML" role="XML"><component> + <key>Component</key> + <type>ComponentImpl</type> + <init-params> + <value-param> + <name>param</name> + <value>empty</value> + </value-param> + <value-param profiles="foo"> + <name>param</name> + <value>foo</value> + </value-param> + <value-param profiles="bar"> + <name>param</name> + <value>bar</value> + </value-param> + </init-params> +</component></programlisting> + </section> + <section 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"><object type="org.exoplatform.container.configuration.ConfigParam"> + <field name="role"> + <collection type="java.util.ArrayList"> + <value><string>manager</string></value> + <value profiles="foo"><string>foo_manager</string></value> + <value profiles="foo,bar"><string>foo_bar_manager</string></value> + </collection> + </field> +</object></programlisting> + </section> + <section 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"><object-param> + <name>test.configuration</name> + <object type="org.exoplatform.container.configuration.ConfigParam"> + <field name="role"> + <collection type="java.util.ArrayList"> + <value><string>manager</string></value> + </collection> + </field> + <field name="role" profiles="foo,bar"> + <collection type="java.util.ArrayList"> + <value><string>foo_bar_manager</string></value> + </collection> + </field> + <field name="role" profiles="foo"> + <collection type="java.util.ArrayList"> + <value><string>foo_manager</string></value> + </collection> + </field> + </object> +</object-param></programlisting> + </section> + </section> + </section> + </section> + <section xmlns="" id="sect-Reference_Guide-Component_request_life_cycle"> + <title>Component request life cycle</title> + <section id="sect-Reference_Guide-Component_request_life_cycle-Component_request_life_cycle_contract"> + <title>Component request life cycle contract</title> + <para> + The component request life cycle is an interface that defines a contract for a component for being involved into a request: + </para> + <programlisting language="Java" role="Java">public interface ComponentRequestLifecycle +{ + /** + * Start a request. + * @param container the related container + */ + void startRequest(ExoContainer container); + + /** + * Ends a request. + * @param container the related container + */ + void endRequest(ExoContainer container); +}</programlisting> + <para> + The container passed is the container to which the component is related. This contract is often used to setup a thread local based context that will be demarcated by a request. + </para> + <para> + For instance in the portal context, a component request life cycle is triggered for user requests. Another example is the initial data import in GateIn that demarcates using callbacks made to that interface. + </para> + </section> + <section id="sect-Reference_Guide-Component_request_life_cycle-Request_life_cycle"> + <title>Request life cycle</title> + <para> + The <envar>RequestLifeCycle</envar> class has several statics methods that are used to schedule the component request life cycle of components. Its main responsibility is to perform scheduling while respecting the constraint to execute the request life cycle of a component only once even if it can be scheduled several times. + </para> + <section id="sect-Reference_Guide-Request_life_cycle-Scheduling_a_component_request_life_cycle"> + <title>Scheduling a component request life cycle</title> + <programlisting language="Java" role="Java">RequestLifeCycle.begin(component); +try +{ + // Do something +} +finally +{ + RequestLifeCycle.end(); +}</programlisting> + </section> + <section id="sect-Reference_Guide-Request_life_cycle-Scheduling_a_container_request_life_cycle"> + <title>Scheduling a container request life cycle</title> + <para> + Scheduling a container triggers the component request life cycle of all the components that implement the interface <envar>ComponentRequestLifeCycle</envar>. If one of the component has already been scheduled before and then that component will not be scheduled again. When the local value is true, then the looked components will be those of the container, when it is false then the scheduler will also look at the components in the ancestor containers. + </para> + <programlisting language="Java" role="Java">RequestLifeCycle.begin(container, local); +try +{ + // Do something +} +finally +{ + RequestLifeCycle.end(); +}</programlisting> + </section> + <section id="sect-Reference_Guide-Request_life_cycle-When_request_life_cycle_is_triggered"> + <title>When request life cycle is triggered</title> + <section id="sect-Reference_Guide-When_request_life_cycle_is_triggered-Portal_request_life_cycle"> + <title>Portal request life cycle</title> + <para> + Each portal request triggers the life cycle of the associated portal container. + </para> + </section> + <section id="sect-Reference_Guide-When_request_life_cycle_is_triggered-JMX_request_Life_Cycle"> + <title>JMX request Life Cycle</title> + <para> + When a JMX bean is invoked, the request life cycle of the container to which it belongs it scheduled. Indeed JMX is an entry point of the system that may need component to have a request life cycle triggered. + </para> + </section> + </section> + </section> + </section> + <section xmlns="" id="sect-Reference_Guide-Configuring_Services"> + <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> + When creating a service, you also should declare its existence to the <emphasis role="bold">Container</emphasis>. This can be done by creating a simple configuration file. + </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> + 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> + 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> + Additionally, <emphasis role="bold">portal extensions</emphasis> can use configuration information stored in <filename><replaceable>JPP_DIST</replaceable>/gatein/gatein.ear/portal.war/WEB-INF/conf/configuration.xml</filename>, and will also have their services configured in the <literal>PortalContainer</literal> scope. + </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> + <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> + A service component is defined in <filename>configuration.xml</filename> by using a <component> element. + </para> + <para> + Only one piece of information is required when defining a service; the service implementation class. This is specified using <type> + </para> + <para> + Every component has a <key> that identifies it. If not explicitly set, a key defaults to the value of <type>. If a 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> + <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's call this the <emphasis>configuration override mechanism</emphasis>. + </para> + <para>All custom configuration is made in the <filename>webapps/portal/WEB-INF/conf/configuration.xml</filename> file. Use <component> elements to contain the configuration information. The <key> element defines the interface, and the <type> tag defines the implementation. While the <key> tag is not mandatory, it can lead to a small performance improvement. + </para> + <programlisting language="XML" role="XML"> + <component> + <key>org.exoplatform.services.portletcontainer.persistence.PortletPreferencesPersister</key> + <type>org.exoplatform.services.portal.impl.PortletPreferencesPersisterImpl</type> + </component></programlisting> + <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"><external-component-plugins> + <target-component>org.exoplatform.services.database.HibernateService</target-component> + <component-plugin> + <name>add.hibernate.mapping</name> + <set-method>addPlugin</set-method> + <type>org.exoplatform.services.database.impl.AddHibernateMappingPlugin</type> + <init-params> + <values-param> + <name>hibernate.mapping</name> + <value>org/exoplatform/services/portal/impl/PortalConfigData.hbm.xml</value> + <value>org/exoplatform/services/portal/impl/PageData.hbm.xml</value> + <value>org/exoplatform/services/portal/impl/NodeNavigationData.hbm.xml</value> + </values-param> + </init-params> + </component-plugin> +</external-component-plugins></programlisting> + <para> + In that sample we target the HibernateService and we will call its addPlugin() method with an argument of the type AddHibernateMappingPlugin. That object will first have been filled with the init parameters. + </para> + <para> + Therefore, it is possible to define services that will be able to receive plug-ins without implementing any framework interface. + </para> + <para> + Another example of use is the case of listeners as in the following code where a listener is added to the OrganisationService and will be called each time a new user is created: + </para> + <programlisting language="XML" role="XML"><external-component-plugins> + <target-component>org.exoplatform.services.organization.OrganizationService</target-component> + <component-plugin> + <name>portal.new.user.event.listener</name> + <set-method>addListenerPlugin</set-method> + <type>org.exoplatform.services.portal.impl.PortalUserEventListenerImpl</type> + <description>this listener create the portal configuration for the new user</description> + <init-params> + <object-param> + <name>configuration</name> + <description>description</description> + <object type="org.exoplatform.services.portal.impl.NewPortalConfig"> + <field name="predefinedUser"> + <collection type="java.util.HashSet"> + <value><string>admin</string></value> + <value><string>exo</string></value> + <value><string>company</string></value> + <value><string>community</string></value> + <value><string>portal</string></value> + <value><string>exotest</string></value> + </collection> + </field> + <field name="templateUser"><string>template</string></field> + <field name="templateLocation"><string>war:/conf/users</string></field> + </object> + </object-param> + </init-params> + </component-plugin> +...</programlisting> + <para> + In the previous XML configuration, we 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> + As you can see, there are several types of init parameters, from a simple value param which binds a key with a value to a more complex object mapping that fills a JavaBean with the info defined in the XML. + </para> + <para> + Many other examples exist such as for the Scheduler Service where you can add a job with a simple XML configuration or the JCR Service where you can add a NodeType from your own configuration.xml file. + </para> + <section 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> + The retrieval sequence in short: + </para> + <orderedlist> + <listitem> + <para> + Services default <classname>RootContainer</classname> configurations from JAR files <emphasis>/conf/configuration.xml</emphasis> + </para> + </listitem> + <listitem> + <para> + External <classname>RootContainer</classname> configuration, to be found at <emphasis>exo-tomcat/exo-conf/configuration.xml</emphasis> + </para> + </listitem> + </orderedlist> + <note> + <para> + Naturally you always have to replace <parameter>exo-tomcat</parameter> by your own folder name. + </para> + </note> + <para> + The <classname>RootContainer</classname> creates a java <classname>HashTable</classname> which contains key-value pairs for the services. The qualified interface name of each service is used as key for the hashtable. Hopefully you still remember that the <parameter><key></parameter> tag of the configuration file contains the interface name? The value of each hashtable pair is an object that contains the service configuration (yes, this means the whole structure between the <parameter><component></parameter> tags of your <filename>configuration.xml</filename> file). + </para> + <para> + The <classname>RootContainer</classname> runs over all jar files you find in <emphasis>exo-tomcat/lib</emphasis> and looks if there is a configuration file at <emphasis>/conf/configuration.xml</emphasis>, the services configured in this file are added to the hashtable. That way - at the end of this process - the default configurations for all services are stored in the hashtable. + </para> + <note> + <para> + What happens if the same service - recognized by the same qualified interface name - is configured in different jars? As the service only can exist one time the configuration of the jar found later overrides the previous configuration. You know that the loading <emphasis role="bold">order of the jars is unpredictable</emphasis> you <emphasis role="bold">must not depend on this</emphasis>. + </para> + </note> + <para> + If you wish to provide your own configurations for one or several services, you can do it in a general configuration file that has to be placed at <emphasis>exo-tomcat/exo-conf/configuration.xml</emphasis>. Do not search for such a file on your computer - you won't find one, because this option is not used in the default installation. Here again the same rule applies: <emphasis>The posterior configuration replaces the previous one</emphasis>. + </para> + <para> + The further configuration retrieval depends on the container type. + </para> + </section> + <section 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> + In short PortalContainer configurations are retrieved in the following lookup sequence : + </para> + <orderedlist> + <listitem> + <para> + Take over the configurations of the RootContainer + </para> + </listitem> + <listitem> + <para> + Default PortalContainer configurations from all JAR files (folder <emphasis>/conf/portal/configuration.xml</emphasis>) + </para> + </listitem> + <listitem> + <para> + Web application configurations from the portal.war file - or the <emphasis>portal</emphasis> web app (folder <emphasis>/WEB-INF/conf/configuration.xml</emphasis>) + </para> + </listitem> + <listitem> + <para> + External configuration for services of a named portal, it will be found at <emphasis>exo-tomcat/exo-conf/portal/$portal_name/configuration.xml</emphasis> (as of Portal 2.5) + </para> + </listitem> + </orderedlist> + <para> + You see, here the <emphasis>/conf/portal/configuration.xml</emphasis> file of each jar enters the game, they are searched at first. Next, there is nearly always a configuration.xml in the portal.war file (or in the portal webapp folder), you find this file at <emphasis>/WEB-INF/conf/configuration.xml</emphasis>. If you open it, you will find a lot of import statements that point to other configuration files in the same portal.war (or portal webapp). + </para> + <para> + <emphasis role="bold">Multiple Portals</emphasis> Be aware that you might set up several different portals ("admin", "mexico", etc.), and each of these portals will use a different PortalContainer. And each of these PortalContainers can be configured separately. As of JBoss 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> + <note> + <para> + As of JBoss 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><import>mySubConfDir/myConfig.xml</import></emphasis> to your configuration file. + </para> + </note> + <note> + <para> + Under <emphasis role="bold">JBoss</emphasis> application server <emphasis>exo-conf</emphasis> will be looked up in directory described by JBoss System property <emphasis>jboss.server.config.url</emphasis>. If the property is not found or empty <emphasis>exo-jboss/exo-conf</emphasis> will be asked (since kernel 2.0.4). + </para> + </note> + </section> + <section 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. + </para> + <para> + An external plug-in is defined by using the <literal><external-component-plugin></literal> wrapper element which contains one or more <literal><component-plugin></literal> definitions. + </para> + <para> + The <literal><external-component-plugin></literal> element uses <literal><target-component></literal> to specify a target service component that will receive injected objects. + </para> + <para> + Every <literal><component-plugin></literal> defines an implementation type, and a method on the target component to use for injection (<literal><set-method></literal>). + </para> + <para> + A plug-in implementation class has to implement the <emphasis role="bold">org.exoplatform.container.component. ComponentPlugin</emphasis> interface. + </para> + <para> + In the following example the <literal>PortalContainerDefinitionPlugin</literal> implements the <literal>ComponentPlugin</literal>: + </para> + <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"><target-component></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"><set-method></emphasis>. The method has exactly one argument of the type org.exoplatform.services.cms.categories.impl.TaxonomyPlugin: + </para> + <itemizedlist> + <listitem> + <para> + addTaxonomyPlugin(org.exoplatform.services.cms.categories.impl.TaxonomyPlugin plugin) + </para> + </listitem> + </itemizedlist> + <para> + The content of <emphasis role="bold"><init-params></emphasis> corresponds to the structure of the TaxonomyPlugin object. + </para> + <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. + </para> + <para> + But now look at <ulink url="https://anonsvn.jboss.org/repos/exo-jcr/core/trunk/exo.core.component.org...">OrganizationServiceImpl.java</ulink> + </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> + You see this service depends on two other services. In order to be able to call this constructor the container first needs a <classname>ListenerService</classname> and a <classname>DatabaseService</classname>. Therefore these services must be instantiated before <classname>BaseOrganizationService</classname>, because <classname>BaseOrganizationService</classname> depends on them. + </para> + <para> + For this purpose the container first looks at the constructors of all services and creates a matrix of service dependencies in order to call the services in a proper order. If for any reason there are interdependencies or circular dependencies you will get a java <classname>Exception</classname>. <emphasis>In this way the dependencies are injected by the container</emphasis>. + </para> + <note> + <para> + What happens if one service has more than one constructor? The container always tries first to use the constructor with a maximum of arguments, if this is not possible the container continues step by step with constructors that have less arguments until arriving at the zero-argument constructor (if there is one). + </para> + </note> + </section> + <section 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> + With this command you get your current container: + </para> + <itemizedlist> + <listitem> + <para> + <emphasis role="bold">ExoContainer myContainer = ExoContainerContext.getCurrentContainer();</emphasis> + </para> + </listitem> + </itemizedlist> + <para> + Whenever you need one of the services that you have configured use the method: + </para> + <itemizedlist> + <listitem> + <para> + <emphasis role="bold">myContainer.getComponentInstance(class)</emphasis> + </para> + </listitem> + </itemizedlist> + <para> + In our case: + </para> + <itemizedlist> + <listitem> + <para> + <emphasis role="bold">ArticleStatsService statsService = (ArticleStatsService) myContainer.getComponentInstance(ArticleStatsService.class);</emphasis> + </para> + </listitem> + </itemizedlist> + <para> + Recapitulation: + </para> + <programlisting language="Java" role="Java">package com.laverdad.common; + +import org.exoplatform.container.ExoContainer; +import org.exoplatform.container.ExoContainerContext; +import com.laverdad.services.*; + +public class Statistics { + + public int makeStatistics(String articleText) { + ExoContainer myContainer = ExoContainerContext.getCurrentContainer(); + ArticleStatsService statsService = (ArticleStatsService) + myContainer.getComponentInstance(ArticleStatsService.class); + int numberOfSentences = statsService.calcSentences(articleText); + return numberOfSentences; + } + + public static void main( String args[]) { + Statistics stats = new Statistics(); + String newText = "This is a normal text. The method only counts the number of periods. " + + "You can implement your own implementation with a more exact counting. " + + "Let`s make a last sentence."; + System.out.println("Number of sentences: " + stats.makeStatistics(newText)); + } +}</programlisting> + </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> + 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> + <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> + <para> + Comment #1: 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. + </para> + <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> + 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> + </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> + 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> + 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> + A good example of this is the <emphasis role="bold">HibernateService</emphasis>: + </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><init-params> configuration element</title> + <para><init-params> 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> + Service components that form the JBoss Portal Platform infrastructure use <init-params> elements to configure themselves. A component can have one instance of <init-params> injected at most. + </para> + <para> + If the service component's constructor takes <init-params> as any of the parameters it will automatically be injected at component instantiation time. + </para> + <para> + The XML configuration for a service component that expects an <init-params> element must have an <init-params> element present, however this element can be left empty. + </para> + <para> + Below is an example of how the kernel XML configuration syntax looks when creating <init-params> instances: + </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 <init-params> element description begins with an <init-params> element. + </para> + <para> + It can have zero or more children elements, each of which is one of the following: + </para> + <itemizedlist> + <listitem> + <para> + <value-param> + </para> + </listitem> + <listitem> + <para> + <values-param> + </para> + </listitem> + <listitem> + <para> + <properties-param> + </para> + </listitem> + <listitem> + <para> + <object-param> + </para> + </listitem> + </itemizedlist> + <para> + Each of these child elements takes a <name> that serves as a map entry key, and an optional <description>. It also takes a type-specific <emphasis role="bold">value</emphasis> specification. + </para> + <para> + The value specification for the <properties-param> defines one or more <property> elements, each of which specifies two strings; a property name and a property value. This is evident in the two previous examples. + </para> + <para> + Each <properties-params> defines one <literal>java.util.Properties</literal> instance. + </para> + <example> + <title><properties-param> Hibernate Example</title> + <programlisting language="XML" role="XML"> <component> + <key>org.exoplatform.services.database.HibernateService</key> + <type>org.exoplatform.services.database.impl.HibernateServiceImpl</type> + <init-params> + <properties-param> + <name>hibernate.properties</name> + <description>Default Hibernate Service</description> + <property name="hibernate.show_sql" value="false"/> + <property name="hibernate.cglib.use_reflection_optimizer" value="true"/> + <property name="hibernate.connection.url" value="jdbc:hsqldb:file:../temp/data/exodb"/> + <property name="hibernate.connection.driver_class" value="org.hsqldb.jdbcDriver"/> +... + </properties-param> + </init-params> + </component></programlisting> + <para> + In the org.exoplatform.services.database.impl.HibernateServiceImpl you will find that the name "hibernate.properties" of the properties-param is used to access the properties. + </para> + <programlisting 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"); +... +}</programlisting> + </example> + <para> + The value specification for <value-param> elements is a <value> element which defines a <literal>String</literal> instance. + </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 <values-param> requires one or more <value> elements. Each <value> 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 xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/Advanced_Development_Foundations/default6.xml" parse="text"/></programlisting> + <example> + <title><value-param> Example</title> + <programlisting language="XML" role="XML"> <component> + <key>org.exoplatform.portal.config.UserACL</key> + <type>org.exoplatform.portal.config.UserACL</type> + <init-params> +... + <value-param> + <name>access.control.workspace</name> + <description>groups with memberships that have the right to access the User Control Workspace</description> + <value>*:/platform/administrators,*:/organization/management/executive-board</value> + </value-param> +... + </component></programlisting> + <para> + The UserACL class accesses to the <value-param> in its constructor. + </para> + <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"); + if(accessControlWorkspaceParam != null) md.setAccessControlWorkspace(accessControlWorkspaceParam.getValue()); +...</programlisting> + </example> + <para> + For <object-param> entries, the value specification consists of an <object> element which is used for plain Java style object specification (specifying an implementation <emphasis>class - <type></emphasis>, and <emphasis>property values - <field></emphasis>). +</para> + <example> + <title><object-param> and LDAP Example</title> + <para> + Let's have a look at the configuration of the LDAPService. It is not important to understand LDAP, we only discuss the parameters as they relate to <object-param>. + </para> + <programlisting language="XML" role="XML"><component> + <key>org.exoplatform.services.LDAP.LDAPService</key> + <type>org.exoplatform.services.LDAP.impl.LDAPServiceImpl</type> + <init-params> + <object-param> + <name>LDAP.config</name> + <description>Default LDAP config</description> + <object type="org.exoplatform.services.LDAP.impl.LDAPConnectionConfig"> + <field name="providerURL"><string>LDAPs://10.0.0.3:636</string></field> + <field name="rootdn"><string>CN=Administrator,CN=Users,DC=exoplatform,DC=org</string></field> + <field name="password"><string>exo</string></field> + <field name="version"><string>3</string></field> + <field name="minConnection"><int>5</int></field> + <field name="maxConnection"><int>10</int></field> + <field name="referralMode"><string>ignore</string></field> + <field name="serverName"><string>active.directory</string></field> + </object> + </object-param> + </init-params> +</component></programlisting> + <para> + You see here an <object-param> element is being used to pass the parameters inside an object (actually a java bean). It consists of a <emphasis role="bold">name</emphasis>, a <emphasis role="bold">description</emphasis> and exactly one <emphasis role="bold">object</emphasis>. The object defines the <emphasis role="bold">type</emphasis> and a number of <emphasis role="bold">fields</emphasis>. + </para> + <para> + Here you see how the service accesses the object: + </para> + <programlisting 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") + .getObject(); +...</programlisting> + <para> + The passed object is LDAPConnectionConfig which is a classic <emphasis role="bold">java bean</emphasis>. It contains all fields and also the appropriate getters and setters (not listed here). You also can provide default values. The container creates a new instance of your bean and calls all setters whose values are configured in the configuration file. + </para> + <programlisting language="Java" role="Java">package org.exoplatform.services.LDAP.impl; + +public class LDAPConnectionConfig { + private String providerURL = "LDAP://127.0.0.1:389"; + private String rootdn; + private String password; + private String version; + private String authenticationType = "simple"; + private String serverName = "default"; + private int minConnection; + private int maxConnection; + private String referralMode = "follow"; +...</programlisting> + <para> + You see that the types (String, int) of the fields in the configuration correspond with the bean. A short glance in the kernel_1_2.xsd file let us discover more simple types: + </para> + <itemizedlist> + <listitem> + <para> + <emphasis role="bold">string, int, long, boolean, date, double</emphasis> + </para> + </listitem> + </itemizedlist> + <para> + Have a look on this type test xml file: <ulink url="https://anonsvn.jboss.org/repos/exo-jcr/kernel/trunk/exo.kernel.container...">https://anonsvn.jboss.org/repos/exo-jcr/kernel/trunk/exo.kernel.container...</ulink>. + </para> + </example> + <para> + The following section has an example of specifying a field of with a <literal>Collection</literal> type. + </para> + <para> + The <init-params> 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> + <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. + </para> + <para> + There are two collections: The first collection is an <emphasis role="bold">ArrayList</emphasis>. This ArrayList contains only one value, but there could be more. The only value is an object which defines the field of the NewUserConfig$JoinGroup bean. + </para> + <para> + The second collection is a <emphasis role="bold">HashSet</emphasis> that is a set of strings. + </para> + <programlisting language="XML" role="XML"> <component-plugin> + <name>new.user.event.listener</name> + <set-method>addListenerPlugin</set-method> + <type>org.exoplatform.services.organization.impl.NewUserEventListener</type> + <description>this listener assign group and membership to a new created user</description> + <init-params> + <object-param> + <name>configuration</name> + <description>description</description> + <object type="org.exoplatform.services.organization.impl.NewUserConfig"> + <field name="group"> + <collection type="java.util.ArrayList"> + <value> + <object type="org.exoplatform.services.organization.impl.NewUserConfig$JoinGroup"> + <field name="groupId"><string>/platform/users</string></field> + <field name="membership"><string>member</string></field> + </object> + </value> + </collection> + </field> + <field name="ignoredUser"> + <collection type="java.util.HashSet"> + <value><string>root</string></value> + <value><string>john</string></value> + <value><string>marry</string></value> + <value><string>demo</string></value> + <value><string>james</string></value> + </collection> + </field> + </object> + </object-param> + </init-params> + </component-plugin></programlisting> + <para> + Let's look at the org.exoplatform.services.organization.impl.NewUserConfig bean: + </para> + <programlisting language="Java" role="Java">public class NewUserConfig { + private List role; + private List group; + private HashSet ignoredUser; + + ... + + public void setIgnoredUser(String user) { + ignoredUser.add(user); + + ... + + static public class JoinGroup { + public String groupId; + public String membership; + ... +}</programlisting> + <para> + You see the values of the HashSet are set one by one by the container, and it's the responsibility of the bean to add these values to its HashSet. + </para> + <para> + The JoinGroup object is just an inner class and implements a bean of its own. It can be accessed like any other inner class using NewUserConfig.JoinGroup. + </para> + </section> + </section> + <section id="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 ' <emphasis role="bold">priority</emphasis>' tag to define plug-in's load priority. By <emphasis role="bold">default</emphasis> all plug-ins get <emphasis role="bold">priority '0'</emphasis>; they will be loaded in the container'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> + Simple example of fragment of a <emphasis role="bold">configuration.xml</emphasis>. + </para> + <programlisting language="XML" role="XML">... +<component> + <type>org.exoplatform.services.Component1</type> +</component> + +<external-component-plugins> + <target-component>org.exoplatform.services.Component1</target-component> + + <component-plugin> + <name>Plugin1</name> + <set-method>addPlugin</set-method> + <type>org.exoplatform.services.plugins.Plugin1</type> + <description>description</description> + <priority>1</priority> + </component-plugin> + + <component-plugin> + <name>Plugin2</name> + <set-method>addPlugin</set-method> + <type>org.exoplatform.services.plugins.Plugin2</type> + <description>description</description> + <priority>2</priority> + </component-plugin> + +</external-component-plugins> + +<external-component-plugins> + <target-component>org.exoplatform.services.Component1</target-component> + <component-plugin> + <name>Plugin3</name> + <set-method>addPlugin</set-method> + <type>org.exoplatform.services.plugins.Plugin3</type> + <description>description</description> + </component-plugin> +</external-component-plugins> +...</programlisting> + <para> + In the above example plug-in 'Plugin3' will be loaded first because it has the default priority '0'. Then, plug-in 'Plugin1' will be loaded and last one is plug-in 'Plugin2'. + </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> + If this property is set the container configuration manager reports during startup the configuration retrieval process to the standard output (System.out). + </para> + <programlisting>...... +Add configuration jar:file:/D:/Projects/eXo/dev/exo-working/exo-tomcat/lib/exo.kernel.container-trunk.jar!/conf/portal/configuration.xml +Add configuration jar:file:/D:/Projects/eXo/dev/exo-working/exo-tomcat/lib/exo.kernel.component.cache-trunk.jar!/conf/portal/configuration.xml +Add configuration jndi:/localhost/portal/WEB-INF/conf/configuration.xml import jndi:/localhost/portal/WEB-INF/conf/common/common-configuration.xml +import jndi:/localhost/portal/WEB-INF/conf/database/database-configuration.xml import jndi:/localhost/portal/WEB-INF/conf/ecm/jcr-component-plugins-configuration.xml +import jndi:/localhost/portal/WEB-INF/conf/jcr/jcr-configuration.xml +......</programlisting> + </section> + <section 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> + <emphasis role="bold">war</emphasis>: Imports from <emphasis role="bold">portal.war/WEB-INF</emphasis> + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold">jar</emphasis> or <emphasis role="bold">classpath</emphasis>: Uses the <emphasis role="bold">classloader</emphasis>, you can use this prefix in the default configuration for importing an other configuration file which is accessible by the classloader. + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold">file</emphasis>: Uses an <emphasis role="bold">absolute path</emphasis>, you also can put a <emphasis role="bold">URL</emphasis>. + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold">without any prefix</emphasis>: + </para> + </listitem> + </itemizedlist> + <para> + If you open the <filename>portal/trunk/web/portal/src/main/webapp/WEB-INF/conf/configuration.xml</filename> you will see that it consists only of imports: + </para> + <programlisting language="XML" role="XML"><import>war:/conf/common/common-configuration.xml</import> +<import>war:/conf/common/logs-configuration.xml</import> +<import>war:/conf/database/database-configuration.xml</import> +<import>war:/conf/jcr/jcr-configuration.xml</import> +<import>war:/conf/common/portlet-container-configuration.xml</import> +...</programlisting> + </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> + 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"> <component> + <key>org.exoplatform.services.database.HibernateService</key> + <jmx-name>database:type=HibernateService</jmx-name> + <type>org.exoplatform.services.database.impl.HibernateServiceImpl</type> + <init-params> + <properties-param> + <name>hibernate.properties</name> + <description>Default Hibernate Service</description> +... + <property name="hibernate.connection.url" value="${connectionUrl}"/> + <property name="hibernate.connection.driver_class" value="${driverClass}"/> + <property name="hibernate.connection.username" value="${username}"/> + <property name="hibernate.connection.password" value="${password}"/> + <property name="hibernate.dialect" value="${dialect}"/> +... + </properties-param> + </init-params> + </component></programlisting> + <para> + As these are system properties you use the -D command: <emphasis role="bold">java -DconnectionUrl=jdbc:hsqldb:file:../temp/data/exodb -DdriverClass=org.hsqldb.jdbcDriver</emphasis> Or better use the parameters of eXo.bat / eXo.sh when you start JBoss Portal Platform: <emphasis role="bold">set EXO_OPTS="-DconnectionUrl=jdbc:hsqldb:file:../temp/data/exodb -DdriverClass=org.hsqldb.jdbcDriver"</emphasis> + </para> + </section> + </section> + </section> + <section xmlns="" 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 +class AsynchListenerWithException<S,D> extends Listener<S,D> +{ + @Override + public void onEvent(Event<S,D> event) throws Exception + { + // 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"> <component> + <key>org.exoplatform.services.listener.ListenerService</key> + <type>org.exoplatform.services.listener.ListenerService</type> + + <init-params> + <value-param> + <name>asynchPoolSize</name> + <value>5</value> + </value-param> + </init-params> + + </component></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">/** + * This method is used to register a listener with the service. The method + * should: 1. Check to see if there is a list of listener with the listener + * name, create one if the listener list doesn't exit 2. Add the new listener + * to the listener list + * + * @param listener +*/ +public void addListener(Listener listener) { + ... +}</programlisting> + <para> + By convention, we use the listener name as the name of the event to listen to. + </para> + </section> + <section 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 + * data 3. For each listener in the listener list, invoke the method + * onEvent(Event) + * + * @param <S> The type of the source that broadcast the event + * @param <D> The type of the data that the source object is working on + * @param name The name of the event + * @param source The source object instance + * @param data The data object instance + * @throws Exception + */ +public <S, D> void broadcast(String name, S source, D data) throws Exception { + ... +} + +/** + * This method is used when a developer want to implement his own event object + * and broadcast the event. The method should: 1. Check if there is a list of + * listener that listen to the event name. 2. If there is a list of the + * listener, For each listener in the listener list, invoke the method + * onEvent(Event) + * + * @param <T> The type of the event object, the type of the event object has + * to be extended from the Event type + * @param event The event instance + * @throws Exception + */ +public <T extends Event> void broadcast(T event) throws Exception { + ... +}</programlisting> + <para> + The 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<S, D> extends BaseComponentPlugin { + + /** + * This method should be invoked when an event with the same name is + * broadcasted + */ + public abstract void onEvent(Event<S, D> event) throws Exception; +}</programlisting> + <warning> + <para> + As you can see we use generics to limit the source of the event to the type 'S' and the data of the event to the type 'D', so we expect that listeners implement the method onEvent() with the corresponding types + </para> + </warning> + <para> + Each listener is also a ComponentPlugin with a name and a description, in other words, the name of the listener will be the name given in the configuration file, for more details see the next section. + </para> + <programlisting language="Java" role="Java">public interface ComponentPlugin { + public String getName(); + + public void setName(String name); + + public String getDescription(); + + 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"><?xml version="1.0" encoding="ISO-8859-1"?> +<configuration> +... + <external-component-plugins> +  + <target-component>org.exoplatform.services.listener.ListenerService</target-component> + + <component-plugin> +  + <name>${name-of-the-target-event}</name> +  + <set-method>addListener</set-method> +  + <type>${the-FQN-of-the-listener}</type> + </component-plugin> + + </external-component-plugins> +</configuration></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<ConversationRegistry, ConversationState> event) on all the listeners which name is "exo.core.security.ConversationRegistry.register". + </para> + <para> + In the example below, we define a Listener that will listen the event "exo.core.security.ConversationRegistry.register". + </para> + <programlisting language="XML" role="XML"><?xml version="1.0" encoding="ISO-8859-1"?> +<configuration> +... + <external-component-plugins> +  + <target-component>org.exoplatform.services.listener.ListenerService</target-component> + + <component-plugin> +  + <name>exo.core.security.ConversationRegistry.register</name> +  + <set-method>addListener</set-method> +  + <type>org.exoplatform.forum.service.AuthenticationLoginListener</type> + </component-plugin> + + </external-component-plugins> +</configuration> +...</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"><?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_2.xsd http://www.exoplaform.org/xml/ns/kernel_1_2.xsd" + xmlns="http://www.exoplaform.org/xml/ns/kernel_1_2.xsd"> + + <component> + <type>org.exoplatform.services.scheduler.impl.QuartzSheduler</type> + </component> + + <component> + <type>org.exoplatform.services.scheduler.QueueTasks</type> + </component> + + <component> + <key>org.exoplatform.services.scheduler.JobSchedulerService</key> + <type>org.exoplatform.services.scheduler.impl.JobSchedulerServiceImpl</type> + </component> + +</configuration></programlisting> + </section> + <section 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">here</ulink> + </para> + </note> + <para> + Work with <classname>JobSchedulerService</classname> by creating a sample project and use JBoss Portal Platform 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> + </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"><project + xmlns="http://maven.apache.org/POM/4.0.0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd"> + + <modelVersion>4.0.0</modelVersion> + + <parent> + <artifactId>exo.portal.parent</artifactId> + <groupId>org.exoplatform.portal</groupId> + <version>3.1.0-GA</version> + </parent> + + <groupId>org.exoplatform.samples</groupId> + <artifactId>exo.samples.scheduler</artifactId> + <version>1.0.0-SNAPSHOT</version> + <name>eXo Samples For Scheduler</name> + <description>eXo Samples Code For Scheduler</description> +</project></programlisting> + <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 "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; + +import org.exoplatform.services.log.ExoLogger; +import org.exoplatform.services.log.Log; +import org.quartz.Job; +import org.quartz.JobExecutionContext; +import org.quartz.JobExecutionException; + +/** + * DumbJob for executing a defined dumb job. + */ +public class DumbJob implements Job { + + /** + * The logger + */ + private static final Log LOG = ExoLogger.getLogger(DumbJob.class); + + /** + * The job of the DumbJob will be done by executing this method. + * + * @param context + * @throws JobExecutionException + */ + public void execute(JobExecutionContext context) throws JobExecutionException { + LOG.info("DumbJob is executing..."); + } +}</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 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"><external-component-plugins> + <target-component>org.exoplatform.services.scheduler.JobSchedulerService</target-component> + <component-plugin> + <name>PeriodJob Plugin</name> + <set-method>addPeriodJob</set-method> + <type>org.exoplatform.services.scheduler.PeriodJob</type> + <description>period job configuration</description> + <init-params> + <properties-param> + <name>job.info</name> + <description>dumb job executed periodically</description> + <property name="jobName" value="DumbJob"/> + <property name="groupName" value="DumbJobGroup"/> + <property name="job" value="org.exoplatform.samples.scheduler.jobs.DumbJob"/> + <property name="repeatCount" value="0"/> + <property name="period" value="60000"/> + <property name="startTime" value="+45"/> + <property name="endTime" value=""/> + </properties-param> + </init-params> + </component-plugin> + </external-component-plugins></programlisting> + <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 'cron-like' definitions. The plug-in 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 => "0 0 12 * * ?"; or at 10:15am every Monday, Tuesday, Wednesday, Thursday and Friday => "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"><external-component-plugins> + <target-component>org.exoplatform.services.scheduler.JobSchedulerService</target-component> + <component-plugin> + <name>CronJob Plugin</name> + <set-method>addCronJob</set-method> + <type>org.exoplatform.services.scheduler.CronJob</type> + <description>cron job configuration</description> + <init-params> + <properties-param> + <name>job.info</name> + <description>dumb job executed by cron expression</description> + <property name="jobName" value="DumbJob"/> + <property name="groupName" value="DumbJobGroup"/> + <property name="job" value="org.exoplatform.samples.scheduler.jobs.DumbJob"/> +  + <property name="expression" value="0 15 10 * * ?"/> + </properties-param> + </init-params> + </component-plugin> + </external-component-plugins></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 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"><?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_2.xsd http://www.exoplaform.org/xml/ns/kernel_1_2.xsd" + xmlns="http://www.exoplaform.org/xml/ns/kernel_1_2.xsd"> + + <component> + <type>org.exoplatform.services.scheduler.impl.QuartzSheduler</type> + </component> + <component> + <type>org.exoplatform.services.scheduler.QueueTasks</type> + </component> + <component> + <key>org.exoplatform.services.scheduler.JobSchedulerService</key> + <type>org.exoplatform.services.scheduler.impl.JobSchedulerServiceImpl</type> + </component> + + <external-component-plugins> + <target-component>org.exoplatform.services.scheduler.JobSchedulerService</target-component> + <component-plugin> + <name>PeriodJob Plugin</name> + <set-method>addPeriodJob</set-method> + <type>org.exoplatform.services.scheduler.PeriodJob</type> + <description>period job configuration</description> + <init-params> + <properties-param> + <name>job.info</name> + <description>dumb job executed periodically</description> + <property name="jobName" value="DumbJob"/> + <property name="groupName" value="DumbJobGroup"/> + <property name="job" value="org.exoplatform.samples.scheduler.jobs.DumbJob"/> + <property name="repeatCount" value="0"/> + <property name="period" value="60000"/> + <property name="startTime" value="+45"/> + <property name="endTime" value=""/> + </properties-param> + </init-params> + </component-plugin> + </external-component-plugins> +</configuration></programlisting> + <para> + <emphasis role="italic">mvn clean install </emphasis>the project. Copy .jar file to<emphasis role="italic"> lib</emphasis> in tomcat bundled with JBoss Portal Platform 6. 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 JBoss Portal Platform'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-scheduler.org/</ulink> + </para> + </listitem> + <listitem> + <para> + <ulink url="http://en.wikipedia.org/wiki/Job_scheduler">http://en.wikipedia.org/wiki/Job_scheduler</ulink> + </para> + </listitem> + <listitem> + <para> + <ulink url="http://www.theserverside.com/news/1364726/Job-Scheduling-in-J2EE-Applicat...">http://www.theserverside.com/news/1364726/Job-Scheduling-in-J2EE-Applicat...</ulink> + </para> + </listitem> + <listitem> + <para> + <ulink url="http://technet.microsoft.com/en-us/library/cc720070%28WS.10%29.aspx">http://technet.microsoft.com/en-us/library/cc720070%28WS.10%29.aspx</ulink> + </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><configuration> +.... + <component> + <key>org.exoplatform.services.jdbc.DataSourceProvider</key> + <type>org.exoplatform.services.jdbc.impl.DataSourceProviderImpl</type> + <init-params> +  +  +  +  +  +  + </init-params> + </component> +... +</configuration></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> + </section> + <section xmlns="" id="sect-Reference_Guide-Configuring_a_portal_container"> + <title>Configuring a portal container</title> + <para> + A <literal>portal container</literal> is defined by several attributes: + </para> + <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"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/Advanced_Development_Foundations/default7.xml" parse="text"/></programlisting> + <para> + Dependencies are part of the <emphasis role="bold">extension mechanism</emphasis> which is discussed later in this document. + </para> + <para> + Every <literal>PortalContainer</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> + This 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 the standard API (<literal>ServletContext</literal>, <literal>ClassLoader</literal>) with specific resource loading behavior, such as visibility into associated web application archives, configured with the dependencies property of <literal>PortalContainerDefinition</literal>. + </para> + <para> + Resources from other web applications are queried in the order specified by the dependencies. The later entries in the list override the previous ones. + </para> + </section> + <section xmlns="" id="sect-Reference_Guide-System_property_configuration"> + <title>System property configuration</title> + <para> + A new property configuration service has been developed for taking care of configuring system properties from the inline kernel configuration or from specified property files. + </para> + <para> + The service is scoped at the root container level because it is used by all the services in the different portal containers in the application runtime. + </para> + <section id="sect-Reference_Guide-System_property_configuration-Properties_init_param"> + <title>Properties <init-param></title> + <para> + The properties init param takes a property declared to configure various properties. + </para> + <programlisting language="XML" role="XML"><component> + <key>PropertyManagerConfigurator</key> + <type>org.exoplatform.container.PropertyConfigurator</type> + <init-params> + <properties-param> + <name>properties</name> + <property name="foo" value="bar"/> + </properties-param> + </init-params> +</component></programlisting> + </section> + <section id="sect-Reference_Guide-System_property_configuration-Properties_URL_init_param"> + <title>Properties URL <init-param></title> + <para> + The properties URL init param allow to load an external file by specifying its URL. Both property and XML format are supported, see the javadoc of the <emphasis> + <envar>java.util.Properties</envar> + </emphasis> class for more information. When a property file is loaded the various property declarations are loaded in the order in which the properties are declared sequentially in the file. + </para> + <programlisting language="XML" role="XML"><component> + <key>PropertyManagerConfigurator</key> + <type>org.exoplatform.container.PropertyConfigurator</type> + <init-params> + <value-param> + <name>properties.url</name> + <value>classpath:configuration.properties</value> + </value-param> + </init-params> +</component></programlisting> + <para> + In the properties file corresponding to the external properties, you can reuse variables before defining to create a new variable. In this case, the prefix "<emphasis>portal.container.</emphasis>" is not needed, see an example below: +<programlisting>my-var1=value 1 +my-var2=value 2 +complex-value=${my-var1}-${my-var2}</programlisting> + + </para> + </section> + <section id="sect-Reference_Guide-System_property_configuration-System_Property_configuration_of_the_properties_URL"> + <title>System Property configuration of the properties URL</title> + <para> + It is possible to replace the properties URL init param by a system property that overwrites it. The name of that property is <emphasis>exo.properties.url</emphasis>. + </para> + </section> + <section id="sect-Reference_Guide-System_property_configuration-Variable_Syntaxes"> + <title>Variable Syntaxes</title> + <para> + All the variables that we described in the previous sections can be defined thanks to 2 possible syntaxes which are <emphasis>${variable-name}</emphasis> or <emphasis>${variable-name:default-value}</emphasis>. The first syntax doesn't define any default value so if the variable has not be set the value will be <emphasis>${variable-name}</emphasis> to indicate that it could not be resolved. The second syntax allows you to define the default value after the semi colon so if the variable has not be set the value will be the given default value. + </para> + </section> + </section> + <section xmlns="" id="sect-Reference_Guide-The_Extension_Mechanism_and_Portal_Extensions"> + <title>The Extension Mechanism and Portal Extensions</title> + <para> + 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> + 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> + These archives, packaged for use through the extension mechanism, are called <emphasis role="bold">portal extensions</emphasis>. + </para> + <procedure id="proc-Reference_Guide-The_Extension_Mechanism_and_Portal_Extensions-Creating_a_portal_extension"> + <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"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/Advanced_Development_Foundations/default8.xml" parse="text"/></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> + Refer to the code extract in <xref linkend="sect-Reference_Guide-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 id="sect-Reference_Guide-The_Extension_Mechanism_and_Portal_Extensions-Running_Multiple_Portals"> + <title>Running Multiple Portals</title> + <para> + It is possible to run several independent portal containers, each bound to a different URL context, within the same JVM instance. + </para> + <para> + 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> + 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> + 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> + Sometimes an application must ensure that the proper <literal>PortalContainer</literal> is associated with the current <literal>eXoContainerContext</literal> call. + </para> + <para> + 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 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 the <emphasis role="bold">dependencies</emphasis> configuration (as seen in <xref linkend="sect-Reference_Guide-The_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 language="Java" role="Java"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/Advanced_Development_Foundations/default9.java" parse="text"/></programlisting> + <note> + <para> + This ensures that <literal>AbstractHttpServlet</literal>'s <literal>service()</literal> interception is not overwritten. + </para> + </note> + <para> + An application may also need access to portal information within the <emphasis role="bold">HttpSessionListener</emphasis>. Ensure the 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 language="Java" role="Java"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/Advanced_Development_Foundations/default10.java" parse="text"/></programlisting> + <para> + Another method must also be implemented in this case: + </para> + <programlisting language="Java" role="Java"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/Advanced_Development_Foundations/default11.java" parse="text"/></programlisting> + <para> + 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> + If it returns <emphasis>false</emphasis> the standard application separation rules are used for resource loading (effectively turning off the extension mechanism). + </para> + <para> + 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 id="form-Reference_Guide-Running_Multiple_Portals-ServletContextListener_based_initialization_access_to_PortalContainer"> + <title>ServletContextListener-based initialization access to PortalContainer</title> + <para> +JBoss Portal Platform 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, 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 JBoss Portal Platform 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 is executed after the portal container has been initialized. + </para> + <programlisting language="Java" role="Java"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/Advanced_Development_Foundations/GadgetRegister.java" parse="text"/></programlisting> + <para> + 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> + 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 id="form-Reference_Guide-Running_Multiple_Portals-LoginModules"> + <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> + </section> + <section xmlns="" id="sect-Reference_Guide-Manageability"> + <title>Manageability</title> + <section id="sect-Reference_Guide-Manageability-Introduction"> + <title>Introduction</title> + <para> + The kernel has a framework for exposing a management view of the various sub systems of the platform. The management view is a lose term for defining how we can access relevant information about the system and how we can apply management operations. JMX is the de facto standard for exposing a management view in the Java Platform but we take in consideration other kind of views such as REST web services. Therefore, the framework is not tied to JMX, yet it provides a JMX part to define more precisely details related to the JMX management view. The legacy framework is still in use but is deprecated in favor of the new framework as it is less tested and less efficient. It will be removed by sanitization in the future. + </para> + </section> + <section id="sect-Reference_Guide-Manageability-Managed_framework_API"> + <title>Managed framework API</title> + <para> + The managed frameworks define an API for exposing a management view of objects. The API is targeted for internal use and is not a public API. The framework leverages Java 5 annotations to describe the management view from an object. + </para> + <section id="sect-Reference_Guide-Managed_framework_API-Annotations"> + <title>Annotations</title> + <section id="sect-Reference_Guide-Annotations-org.exoplatform.management.annotations.Managed_annotation"> + <title>@org.exoplatform.management.annotations.Managed annotation</title> + <para> + The @Managed annotates elements that wants to expose a management view to a management layer. + </para> + <para> + <emphasis role="bold">@Managed for objects</emphasis> + </para> + <para> + The framework will export a management view for the objects annotated. + </para> + <para> + <emphasis role="bold">@Managed for getter/setter</emphasis> + </para> + <para> + Defines a managed property. An annotated getter defines a read property, an annotated setter defines a write property and if matching getter/setter are annotated it defines a read/write property. + </para> + <para> + <emphasis role="bold">@Managed on method</emphasis> + </para> + <para> + Defines a managed operation. + </para> + </section> + <section id="sect-Reference_Guide-Annotations-org.exoplatform.management.annotations.ManagedDescription"> + <title>@org.exoplatform.management.annotations.ManagedDescription</title> + <para> + The @ManagedDescription annotation provides a description of a managed element. It is valid to annotated object or methods. It takes as sole argument a string that is the description value. + </para> + </section> + <section id="sect-Reference_Guide-Annotations-org.exoplatform.management.annotations.ManagedName"> + <title>@org.exoplatform.management.annotations.ManagedName</title> + <para> + The @ManagedName annotation provides an alternative name for managed properties. It is used to accomodate legacy methods of an object that can be renamed for compatibility reasons. It takes as sole argument a string that is the name value. + </para> + </section> + <section id="sect-Reference_Guide-Annotations-org.exoplatform.management.annotations.ManagedBy"> + <title>@org.exoplatform.management.annotations.ManagedBy</title> + <para> + The @ManagedBy annotation defines a delegate class for exposing a management view. The sole argument of the annotation are class literals. The delegate class must provide a constructor with the managed object as argument. + </para> + </section> + </section> + </section> + <section id="sect-Reference_Guide-Manageability-JMX_Management_View"> + <title>JMX Management View</title> + <section id="sect-Reference_Guide-JMX_Management_View-JMX_Annotations"> + <title>JMX Annotations</title> + <section id="sect-Reference_Guide-JMX_Annotations-org.exoplatform.management.jmx.annotations.Property_annotation"> + <title>@org.exoplatform.management.jmx.annotations.Property annotation</title> + <para> + The @Property annotation is used to within other annotations such as @NameTemplate or @NamingContext. It should be seen as a structural way for a list of properties. A property is made of a key and a value. The value can either be a string literal or it can be surrounded by curly brace to be a dynamic property. A dynamic property is resolved against the instance of the object at runtime. + </para> + </section> + <section id="sect-Reference_Guide-JMX_Annotations-org.exoplatform.management.jmx.annotations.NameTemplate_annotation"> + <title>@org.exoplatform.management.jmx.annotations.NameTemplate annotation</title> + <para> + The @NameTemplate defines a template that is used at registration time of a managed object to create the JMX object name. The template is formed of properties. + </para> + <programlisting language="Java" role="Java">@NameTemplate({ + @Property(key="container", value="workspace"), + @Property(key="name", value="{Name}")})</programlisting> + </section> + <section id="sect-Reference_Guide-JMX_Annotations-org.exoplatform.management.jmx.annotations.NamingContext_annotation"> + <title>@org.exoplatform.management.jmx.annotations.NamingContext annotation</title> + <para> + The @NamingContext annotation defines a set of properties which are used within a management context. It allows to propagate properties down to managed objects which are defined by an object implementing the ManagementAware interface. The goal is to scope different instances of the same class that would have the same object name otherwise. + </para> + <programlisting language="Java" role="Java">@NamingContext(@Property(key="workspace", value="{Name}"))</programlisting> + </section> + </section> + </section> + <section id="sect-Reference_Guide-Manageability-Example"> + <title>Example</title> + <section id="sect-Reference_Guide-Example-CacheService_example"> + <title>CacheService example</title> + <para> + The cache service delegates most of the work to the CacheServiceManaged class by using the @ManagedBy annotation. At runtime when a new cache is created, it calls the CacheServiceManaged class in order to let the CacheServiceManaged object register the cache. + </para> + <programlisting language="Java" role="Java">@ManagedBy(CacheServiceManaged.class) +public class CacheServiceImpl implements CacheService { + + CacheServiceManaged managed; + ... + synchronized private ExoCache createCacheInstance(String region) throws Exception { + ... + if (managed != null) { + managed.registerCache(simple); + } + ... + } +}</programlisting> + <para> + The ExoCache interface is annotated to define its management view. The @NameTemplate is used to produce object name values when ExoCache instance are registered. + </para> + <programlisting language="Java" role="Java">@Managed +@NameTemplate({@Property(key="service", value="cache"), @Property(key="name", value="{Name}")}) +@ManagedDescription("Exo Cache") +public interface ExoCache { + + @Managed + @ManagedName("Name") + @ManagedDescription("The cache name") + public String getName(); + + @Managed + @ManagedName("Capacity") + @ManagedDescription("The maximum capacity") + public int getMaxSize(); + + @Managed + @ManagedDescription("Evict all entries of the cache") + public void clearCache() throws Exception; + + ... +}</programlisting> + <para> + The CacheServiceManaged is the glue code between the CacheService and the management view. The main reason is that only exo services are registered automatically against the management view. Any other managed bean must be registered manually for now. Therefore, it needs to know about the management layer via the management context. The management context allows an object implementing the ManagementAware interface to receive a context to perform further registration of managed objects. + </para> + <programlisting language="Java" role="Java">@Managed +public class CacheServiceManaged implements ManagementAware { + + /** . */ + private ManagementContext context; + + /** . */ + private CacheServiceImpl cacheService; + + public CacheServiceManaged(CacheServiceImpl cacheService) { + this.cacheService = cacheService; + + // + cacheService.managed = this; + } + + public void setContext(ManagementContext context) { + this.context = context; + } + + void registerCache(ExoCache cache) { + if (context != null) { + context.register(cache); + } + } +}</programlisting> + </section> + </section> + </section> </chapter> Modified: epp/docs/JPP/trunk/Reference_Guide/en-US/modules/PortalDevelopment/DataImportStrategy.xml =================================================================== --- epp/docs/JPP/trunk/Reference_Guide/en-US/modules/PortalDevelopment/DataImportStrategy.xml 2013-03-21 02:18:56 UTC (rev 9217) +++ epp/docs/JPP/trunk/Reference_Guide/en-US/modules/PortalDevelopment/DataImportStrategy.xml 2013-03-21 02:26:49 UTC (rev 9218) @@ -5,6 +5,7 @@ ]> <chapter id="chap-Reference_Guide-Data_Import_Strategy"> <title>Data Import Strategy</title> + <remark>MOVED to Development Guide - Data_Import_Strategy.xml</remark> <section id="sect-Reference_Guide-Data_Import_Strategy-Introduction"> <title>Introduction</title> <para> Modified: epp/docs/JPP/trunk/Reference_Guide/en-US/modules/PortalDevelopment/DefaultPortalConfiguration.xml =================================================================== --- epp/docs/JPP/trunk/Reference_Guide/en-US/modules/PortalDevelopment/DefaultPortalConfiguration.xml 2013-03-21 02:18:56 UTC (rev 9217) +++ epp/docs/JPP/trunk/Reference_Guide/en-US/modules/PortalDevelopment/DefaultPortalConfiguration.xml 2013-03-21 02:26:49 UTC (rev 9218) @@ -6,6 +6,7 @@ <chapter id="chap-Reference_Guide-Default_Portal_Configuration"> <title>Default Portal Configuration</title> <remark>Source content: https://docs.jboss.org/author/display/GTNPORTAL35/Default+Portal+Configur...</remark> + <remark>MOVED: Development Guide - Default_Portal_Configuration.xml</remark> <section id="sect-Reference_Guide-Default_Portal_Configuration-Overview"> <title>Overview</title> <para> Modified: epp/docs/JPP/trunk/Reference_Guide/en-US/modules/PortalDevelopment/DefaultPortalNavigationConfiguration.xml =================================================================== --- epp/docs/JPP/trunk/Reference_Guide/en-US/modules/PortalDevelopment/DefaultPortalNavigationConfiguration.xml 2013-03-21 02:18:56 UTC (rev 9217) +++ epp/docs/JPP/trunk/Reference_Guide/en-US/modules/PortalDevelopment/DefaultPortalNavigationConfiguration.xml 2013-03-21 02:26:49 UTC (rev 9218) @@ -6,6 +6,7 @@ <chapter id="chap-Reference_Guide-Portal_Navigation_Configuration"> <title>Portal Navigation Configuration</title> <remark>Source: https://docs.jboss.org/author/display/GTNPORTAL35/Portal+Navigation+Confi...</remark> + <remark>MOVED to Development Guide - Portal_Navigation_Configuration.xml</remark> <section id="sect-Reference_Guide-Portal_Navigation_Configuration-Overview"> <title>Overview</title> <para> Modified: epp/docs/JPP/trunk/Reference_Guide/en-US/modules/PortalDevelopment/DefaultPortalPermissionConfiguration.xml =================================================================== --- epp/docs/JPP/trunk/Reference_Guide/en-US/modules/PortalDevelopment/DefaultPortalPermissionConfiguration.xml 2013-03-21 02:18:56 UTC (rev 9217) +++ epp/docs/JPP/trunk/Reference_Guide/en-US/modules/PortalDevelopment/DefaultPortalPermissionConfiguration.xml 2013-03-21 02:26:49 UTC (rev 9218) @@ -5,6 +5,7 @@ ]> <chapter id="chap-Reference_Guide-Portal_Default_Permission_Configuration"> <title>Portal Default Permission Configuration</title> + <remark>MOVED: Development Guide - Portal_Permission_Configuration.xml</remark> <section id="sect-Reference_Guide-Portal_Default_Permission_Configuration-Overview"> <title>Overview</title> <para> Modified: epp/docs/JPP/trunk/Reference_Guide/en-US/modules/PortalDevelopment/InternationalizationConfiguration.xml =================================================================== --- epp/docs/JPP/trunk/Reference_Guide/en-US/modules/PortalDevelopment/InternationalizationConfiguration.xml 2013-03-21 02:18:56 UTC (rev 9217) +++ epp/docs/JPP/trunk/Reference_Guide/en-US/modules/PortalDevelopment/InternationalizationConfiguration.xml 2013-03-21 02:26:49 UTC (rev 9218) @@ -6,6 +6,7 @@ <chapter id="chap-Reference_Guide-Internationalization_Configuration"> <title><remark>BZ#896760 </remark>Internationalization Configuration</title> <remark>Source: https://docs.jboss.org/author/display/GTNPORTAL35/Internationalization+Co...</remark> + <remark>MOVED to Development Guide - Internationalization_Configuration.xml</remark> <section id="sect-Reference_Guide-Internationalization_Configuration-Overview"> <title>Overview</title> <note> Modified: epp/docs/JPP/trunk/Reference_Guide/en-US/modules/PortalDevelopment/JavascriptInterApplicationCommunication.xml =================================================================== --- epp/docs/JPP/trunk/Reference_Guide/en-US/modules/PortalDevelopment/JavascriptInterApplicationCommunication.xml 2013-03-21 02:18:56 UTC (rev 9217) +++ epp/docs/JPP/trunk/Reference_Guide/en-US/modules/PortalDevelopment/JavascriptInterApplicationCommunication.xml 2013-03-21 02:26:49 UTC (rev 9218) @@ -4,7 +4,8 @@ %BOOK_ENTITIES; ]> <chapter id="chap-Reference_Guide-JavaScript_Inter_Application_Communication"> - <title>JavaScript Inter Application Communication</title> + <title>JavaScript Inter-application Communication</title> + <remark>MOVED to Development Guide - Javascript_Inter-application_Communication.xml</remark> <section id="sect-Reference_Guide-JavaScript_Inter_Application_Communication-Overview"> <title>Overview</title> <para> Modified: epp/docs/JPP/trunk/Reference_Guide/en-US/modules/PortalDevelopment/LocalizationConfiguration.xml =================================================================== --- epp/docs/JPP/trunk/Reference_Guide/en-US/modules/PortalDevelopment/LocalizationConfiguration.xml 2013-03-21 02:18:56 UTC (rev 9217) +++ epp/docs/JPP/trunk/Reference_Guide/en-US/modules/PortalDevelopment/LocalizationConfiguration.xml 2013-03-21 02:26:49 UTC (rev 9218) @@ -5,6 +5,7 @@ ]> <chapter id="chap-Reference_Guide-Localization_Configuration"> <title>Localization Configuration</title> + <remark>MOVED to Development Guide - Localization_Configuration.xml</remark> <section id="sect-Reference_Guide-Localization_Configuration-Pluggable_Locale_Policy"> <title>Pluggable Locale Policy</title> <remark>Source: https://docs.jboss.org/author/display/GTNPORTAL35/Pluggable+Locale+Policy</remark> Modified: epp/docs/JPP/trunk/Reference_Guide/en-US/modules/PortalDevelopment/NavigationController.xml =================================================================== --- epp/docs/JPP/trunk/Reference_Guide/en-US/modules/PortalDevelopment/NavigationController.xml 2013-03-21 02:18:56 UTC (rev 9217) +++ epp/docs/JPP/trunk/Reference_Guide/en-US/modules/PortalDevelopment/NavigationController.xml 2013-03-21 02:26:49 UTC (rev 9218) @@ -5,6 +5,7 @@ ]> <chapter id="chap-Reference_Guide-Navigation_Controller_"> <title>Navigation Controller </title> + <remark>MOVED to Development Guide - Navigation_Controller.xml</remark> <section id="sect-Reference_Guide-Navigation_Controller_-Description"> <title>Description</title> <para> Modified: epp/docs/JPP/trunk/Reference_Guide/en-US/modules/PortalDevelopment/PortalLifecycle.xml =================================================================== --- epp/docs/JPP/trunk/Reference_Guide/en-US/modules/PortalDevelopment/PortalLifecycle.xml 2013-03-21 02:18:56 UTC (rev 9217) +++ epp/docs/JPP/trunk/Reference_Guide/en-US/modules/PortalDevelopment/PortalLifecycle.xml 2013-03-21 02:26:49 UTC (rev 9218) @@ -5,6 +5,7 @@ ]> <chapter id="chap-Reference_Guide-Portal_Life_cycle"> <title>Portal Life-cycle</title> + <remark>MOVED: Chapter moved to Development Guide: Portal_Lifecycle.xml</remark> <section id="sect-Reference_Guide-Portal_Life_cycle-Overview"> <title>Overview</title> <para> @@ -87,10 +88,10 @@ <url-pattern>/gateinservlet</url-pattern> </servlet-mapping> ]]></programlisting> - </listitem> - </varlistentry> - </variablelist> - </section> + </listitem> + </varlistentry> + </variablelist> + </section> </section> <section id="sect-Reference_Guide-Portal_Life_cycle-The_Command_Servlet"> <title>The Command Servlet</title> Modified: epp/docs/JPP/trunk/Reference_Guide/en-US/modules/PortalDevelopment/RTLFramework.xml =================================================================== --- epp/docs/JPP/trunk/Reference_Guide/en-US/modules/PortalDevelopment/RTLFramework.xml 2013-03-21 02:18:56 UTC (rev 9217) +++ epp/docs/JPP/trunk/Reference_Guide/en-US/modules/PortalDevelopment/RTLFramework.xml 2013-03-21 02:26:49 UTC (rev 9218) @@ -5,6 +5,7 @@ ]> <chapter id="chap-Reference_Guide-Right_To_Left_RTL_Framework"> <title>Right To Left (RTL) Framework</title> + <remark>MOVED to Development Guide - RTL_Framework.xml</remark> <para> The text orientation depends on the current locale setting. The orientation is a Java 5 enum that provides a set of functionalities: </para> Modified: epp/docs/JPP/trunk/Reference_Guide/en-US/modules/PortalDevelopment/Skinning.xml =================================================================== --- epp/docs/JPP/trunk/Reference_Guide/en-US/modules/PortalDevelopment/Skinning.xml 2013-03-21 02:18:56 UTC (rev 9217) +++ epp/docs/JPP/trunk/Reference_Guide/en-US/modules/PortalDevelopment/Skinning.xml 2013-03-21 02:26:49 UTC (rev 9218) @@ -5,6 +5,7 @@ ]> <chapter id="chap-Reference_Guide-Skinning_the_Portal"> <title>Skinning the Portal</title> + <remark>MOVED: Chapter moved to Development Guide: Skinning_The_Portal.xml</remark> <section id="sect-Reference_Guide-Skinning_the_Portal-Overview"> <title>Overview</title> <para> Modified: epp/docs/JPP/trunk/Reference_Guide/en-US/modules/PortalDevelopment/XMLResourceBundles.xml =================================================================== --- epp/docs/JPP/trunk/Reference_Guide/en-US/modules/PortalDevelopment/XMLResourceBundles.xml 2013-03-21 02:18:56 UTC (rev 9217) +++ epp/docs/JPP/trunk/Reference_Guide/en-US/modules/PortalDevelopment/XMLResourceBundles.xml 2013-03-21 02:26:49 UTC (rev 9218) @@ -5,6 +5,7 @@ ]> <chapter id="chap-Reference_Guide-XML_Resources_Bundles"> <title>XML Resources Bundles</title> + <remark>MOVED to Development Guide - XML_Resource_Bundles.xml</remark> <section id="sect-Reference_Guide-XML_Resources_Bundles-Overview"> <title>Overview</title> <para> Modified: epp/docs/JPP/trunk/Reference_Guide/en-US/modules/PortalDevelopment.xml =================================================================== --- epp/docs/JPP/trunk/Reference_Guide/en-US/modules/PortalDevelopment.xml 2013-03-21 02:18:56 UTC (rev 9217) +++ epp/docs/JPP/trunk/Reference_Guide/en-US/modules/PortalDevelopment.xml 2013-03-21 02:26:49 UTC (rev 9218) @@ -1,25 +1,20 @@ -<?xml version='1.0' encoding='utf-8' ?> +<?xml version='1.0' encoding='UTF-8'?> <!DOCTYPE part 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; ]> <part id="part-Reference_Guide-Portal_Development"> - <title>Portal Development</title> - <xi:include href="PortalDevelopment/Skinning.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="PortalDevelopment/PortalLifecycle.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="PortalDevelopment/DefaultPortalConfiguration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="PortalDevelopment/DefaultPortalPermissionConfiguration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="PortalDevelopment/DefaultPortalNavigationConfiguration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="PortalDevelopment/DataImportStrategy.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="PortalDevelopment/InternationalizationConfiguration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="PortalDevelopment/LocalizationConfiguration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="PortalDevelopment/XMLResourceBundles.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> -  -  - <xi:include href="PortalDevelopment/RTLFramework.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="PortalDevelopment/JavascriptInterApplicationCommunication.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> -  -  - <xi:include href="PortalDevelopment/NavigationController.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <title>Portal Development</title> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="PortalDevelopment/Skinning.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="PortalDevelopment/PortalLifecycle.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="PortalDevelopment/DefaultPortalConfiguration.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="PortalDevelopment/DefaultPortalPermissionConfiguration.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="PortalDevelopment/DefaultPortalNavigationConfiguration.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="PortalDevelopment/DataImportStrategy.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="PortalDevelopment/InternationalizationConfiguration.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="PortalDevelopment/LocalizationConfiguration.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="PortalDevelopment/XMLResourceBundles.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="PortalDevelopment/RTLFramework.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="PortalDevelopment/JavascriptInterApplicationCommunication.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="PortalDevelopment/NavigationController.xml"/> </part> - Modified: epp/docs/JPP/trunk/Reference_Guide/en-US/modules/PortletDevelopment/Global_Portlet.xml =================================================================== --- epp/docs/JPP/trunk/Reference_Guide/en-US/modules/PortletDevelopment/Global_Portlet.xml 2013-03-21 02:18:56 UTC (rev 9217) +++ epp/docs/JPP/trunk/Reference_Guide/en-US/modules/PortletDevelopment/Global_Portlet.xml 2013-03-21 02:26:49 UTC (rev 9218) @@ -5,6 +5,7 @@ ]> <chapter id="chap-Reference_Guide-Shared_portlet.xml"> <title>Shared portlet.xml</title> + <remark>MOVED to Development Guide - Global_Portlet.xml</remark> <para> The Java Portlet Specification introduces <literal>PortletFilter</literal> as a standard approach to extend the behaviors of portlet objects. For example, a filter can transform the content of portlet requests and portlet responses. </para> Modified: epp/docs/JPP/trunk/Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge.xml =================================================================== --- epp/docs/JPP/trunk/Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge.xml 2013-03-21 02:18:56 UTC (rev 9217) +++ epp/docs/JPP/trunk/Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge.xml 2013-03-21 02:26:49 UTC (rev 9218) @@ -5,6 +5,7 @@ ]> <chapter id="chap-Reference_Guide-Building_JSF_Portlets"> <title>JBoss Portlet Bridge</title> + <remark>MOVED to Developers Guide - Portlet_Bridge.xml</remark> <section id="Portlet_Bridge_Definition"> <title>Portlet Bridge</title> <para>A portlet bridge is a mediator that allows non-native application frameworks to run in a portal environment, independent to the underlying portlet API, or portlet concept. This functionality provides a developer flexibility to continue writing applications in a preferred language, and allows a controlled transition to new technologies. </para> Modified: epp/docs/JPP/trunk/Reference_Guide/en-US/modules/PortletDevelopment/Standard.xml =================================================================== --- epp/docs/JPP/trunk/Reference_Guide/en-US/modules/PortletDevelopment/Standard.xml 2013-03-21 02:18:56 UTC (rev 9217) +++ epp/docs/JPP/trunk/Reference_Guide/en-US/modules/PortletDevelopment/Standard.xml 2013-03-21 02:26:49 UTC (rev 9218) @@ -5,6 +5,7 @@ ]> <chapter id="chap-Reference_Guide-Portlet_Primer"> <title>Portlet Primer</title> + <remark>MOVED to Development Guide - Portlet_Development_Resources.xml</remark> <section id="sect-Reference_Guide-Portlet_Primer-JSR_168_and_JSR_286_overview"> <title>JSR-168 and JSR-286 overview</title> <para> Modified: epp/docs/JPP/trunk/Reference_Guide/en-US/modules/ServerIntegration.xml =================================================================== (Binary files differ)

11 years, 9 months

1
0
0 / 0

gatein SVN: r9217 - epp/docs/JPP/trunk/Development_Guide/en-US.

by do-not-reply＠jboss.org

Author: jaredmorgs Date: 2013-03-20 22:18:56 -0400 (Wed, 20 Mar 2013) New Revision: 9217 Added: epp/docs/JPP/trunk/Development_Guide/en-US/Data_Import_Strategy.xml epp/docs/JPP/trunk/Development_Guide/en-US/Default_Portal_Configuration.xml epp/docs/JPP/trunk/Development_Guide/en-US/Global_Portlet.xml epp/docs/JPP/trunk/Development_Guide/en-US/Internationalization_Configuration.xml epp/docs/JPP/trunk/Development_Guide/en-US/Javascript_Inter-application_Communication.xml epp/docs/JPP/trunk/Development_Guide/en-US/Localization_Configuration.xml epp/docs/JPP/trunk/Development_Guide/en-US/Navigation_Controller.xml epp/docs/JPP/trunk/Development_Guide/en-US/Portal_Lifecycle.xml epp/docs/JPP/trunk/Development_Guide/en-US/Portal_Navigation_Configuration.xml epp/docs/JPP/trunk/Development_Guide/en-US/Portal_Permission_Configuration.xml epp/docs/JPP/trunk/Development_Guide/en-US/Portlet_Bridge.xml epp/docs/JPP/trunk/Development_Guide/en-US/Portlet_Development_Resources.xml epp/docs/JPP/trunk/Development_Guide/en-US/RTL_Framework.xml epp/docs/JPP/trunk/Development_Guide/en-US/Skinning_The_Portal.xml epp/docs/JPP/trunk/Development_Guide/en-US/The_eXo_Kernel.xml epp/docs/JPP/trunk/Development_Guide/en-US/XML_Resource_Bundles.xml Log: Added all files for Portal Development and Portlet Development Added: epp/docs/JPP/trunk/Development_Guide/en-US/Data_Import_Strategy.xml =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Development_Guide/en-US/Data_Import_Strategy.xml ___________________________________________________________________ Added: svn:mime-type + application/xml Added: epp/docs/JPP/trunk/Development_Guide/en-US/Default_Portal_Configuration.xml =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Development_Guide/en-US/Default_Portal_Configuration.xml ___________________________________________________________________ Added: svn:mime-type + application/xml Added: epp/docs/JPP/trunk/Development_Guide/en-US/Global_Portlet.xml =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Development_Guide/en-US/Global_Portlet.xml ___________________________________________________________________ Added: svn:mime-type + application/xml Added: epp/docs/JPP/trunk/Development_Guide/en-US/Internationalization_Configuration.xml =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Development_Guide/en-US/Internationalization_Configuration.xml ___________________________________________________________________ Added: svn:mime-type + application/xml Added: epp/docs/JPP/trunk/Development_Guide/en-US/Javascript_Inter-application_Communication.xml =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Development_Guide/en-US/Javascript_Inter-application_Communication.xml ___________________________________________________________________ Added: svn:mime-type + application/xml Added: epp/docs/JPP/trunk/Development_Guide/en-US/Localization_Configuration.xml =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Development_Guide/en-US/Localization_Configuration.xml ___________________________________________________________________ Added: svn:mime-type + application/xml Added: epp/docs/JPP/trunk/Development_Guide/en-US/Navigation_Controller.xml =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Development_Guide/en-US/Navigation_Controller.xml ___________________________________________________________________ Added: svn:mime-type + application/xml Added: epp/docs/JPP/trunk/Development_Guide/en-US/Portal_Lifecycle.xml =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Development_Guide/en-US/Portal_Lifecycle.xml ___________________________________________________________________ Added: svn:mime-type + application/xml Added: epp/docs/JPP/trunk/Development_Guide/en-US/Portal_Navigation_Configuration.xml =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Development_Guide/en-US/Portal_Navigation_Configuration.xml ___________________________________________________________________ Added: svn:mime-type + application/xml Added: epp/docs/JPP/trunk/Development_Guide/en-US/Portal_Permission_Configuration.xml =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Development_Guide/en-US/Portal_Permission_Configuration.xml ___________________________________________________________________ Added: svn:mime-type + application/xml Added: epp/docs/JPP/trunk/Development_Guide/en-US/Portlet_Bridge.xml =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Development_Guide/en-US/Portlet_Bridge.xml ___________________________________________________________________ Added: svn:mime-type + application/xml Added: epp/docs/JPP/trunk/Development_Guide/en-US/Portlet_Development_Resources.xml =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Development_Guide/en-US/Portlet_Development_Resources.xml ___________________________________________________________________ Added: svn:mime-type + application/xml Added: epp/docs/JPP/trunk/Development_Guide/en-US/RTL_Framework.xml =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Development_Guide/en-US/RTL_Framework.xml ___________________________________________________________________ Added: svn:mime-type + application/xml Added: epp/docs/JPP/trunk/Development_Guide/en-US/Skinning_The_Portal.xml =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Development_Guide/en-US/Skinning_The_Portal.xml ___________________________________________________________________ Added: svn:mime-type + application/xml Added: epp/docs/JPP/trunk/Development_Guide/en-US/The_eXo_Kernel.xml =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Development_Guide/en-US/The_eXo_Kernel.xml ___________________________________________________________________ Added: svn:mime-type + application/xml Added: epp/docs/JPP/trunk/Development_Guide/en-US/XML_Resource_Bundles.xml =================================================================== (Binary files differ) Property changes on: epp/docs/JPP/trunk/Development_Guide/en-US/XML_Resource_Bundles.xml ___________________________________________________________________ Added: svn:mime-type + application/xml

11 years, 9 months

1
0
0 / 0

gatein SVN: r9216 - in epp/docs/JPP/trunk/Development_Guide/en-US: Application_Development and 2 other directories.

by do-not-reply＠jboss.org

Author: jaredmorgs Date: 2013-03-20 22:16:45 -0400 (Wed, 20 Mar 2013) New Revision: 9216 Added: epp/docs/JPP/trunk/Development_Guide/en-US/Gadget_Development.xml epp/docs/JPP/trunk/Development_Guide/en-US/Introduction.xml epp/docs/JPP/trunk/Development_Guide/en-US/Portal_Containers.xml epp/docs/JPP/trunk/Development_Guide/en-US/Portal_Extension.xml epp/docs/JPP/trunk/Development_Guide/en-US/Portlet_Development.xml epp/docs/JPP/trunk/Development_Guide/en-US/Visual_Identity.xml Removed: epp/docs/JPP/trunk/Development_Guide/en-US/Application_Development/Gadget_Development.xml epp/docs/JPP/trunk/Development_Guide/en-US/Application_Development/Portlet_Development.xml epp/docs/JPP/trunk/Development_Guide/en-US/Introduction/Introduction.xml epp/docs/JPP/trunk/Development_Guide/en-US/Portal_Development/Portal_Containers.xml epp/docs/JPP/trunk/Development_Guide/en-US/Portal_Development/Portal_Extension.xml epp/docs/JPP/trunk/Development_Guide/en-US/Portal_Development/Visual_Identity.xml Modified: epp/docs/JPP/trunk/Development_Guide/en-US/Developer_Guide.xml Log: Syncing changes to the Dev Guide files to date to avoid commit conflicts Deleted: epp/docs/JPP/trunk/Development_Guide/en-US/Application_Development/Gadget_Development.xml =================================================================== (Binary files differ) Deleted: epp/docs/JPP/trunk/Development_Guide/en-US/Application_Development/Portlet_Development.xml =================================================================== (Binary files differ) Modified: epp/docs/JPP/trunk/Development_Guide/en-US/Developer_Guide.xml =================================================================== --- epp/docs/JPP/trunk/Development_Guide/en-US/Developer_Guide.xml 2013-03-20 15:17:30 UTC (rev 9215) +++ epp/docs/JPP/trunk/Development_Guide/en-US/Developer_Guide.xml 2013-03-21 02:16:45 UTC (rev 9216) @@ -6,7 +6,7 @@ <book> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Book_Info.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Preface.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Introduction/Introduction.xml" encoding="UTF-8"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Introduction.xml" encoding="UTF-8"/> <part> <title>Architectural and Design Choices</title> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Architectural_Design_Choices/Architectural_Choices.xml" encoding="UTF-8"/> @@ -14,14 +14,26 @@ </part> <part> <title>Portal Development</title> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Portal_Development/Portal_Containers.xml" encoding="UTF-8"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Portal_Development/Visual_Identity.xml" encoding="UTF-8"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Portal_Development/Portal_Extension.xml" encoding="UTF-8"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Portal_Lifecycle.xml" encoding="UTF-8"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Portal_Containers.xml" encoding="UTF-8"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Portal_Permission_Configuration.xml" encoding="UTF-8"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Portal_Navigation_Configuration.xml" encoding="UTF-8"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Default_Portal_Configuration.xml" encoding="UTF-8"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Visual_Identity.xml" encoding="UTF-8"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Skinning_The_Portal.xml" encoding="UTF-8"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Portal_Extension.xml" encoding="UTF-8"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Data_Import_Strategy.xml" encoding="UTF-8"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Internationalization_Configuration.xml" encoding="UTF-8"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Localization_Configuration.xml" encoding="UTF-8"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="RTL_Framework.xml" encoding="UTF-8"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="XML_Resource_Bundles.xml" encoding="UTF-8"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Javascript_Inter-application_Communication.xml" encoding="UTF-8"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Navigation_Controller.xml" encoding="UTF-8"/> </part> <part> <title>Application Development</title> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Application_Development/Gadget_Development.xml" encoding="UTF-8"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Application_Development/Portlet_Development.xml" encoding="UTF-8"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Gadget_Development.xml" encoding="UTF-8"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Portlet_Development.xml" encoding="UTF-8"/> </part> <part> <title>JavaScript Development</title> @@ -41,6 +53,10 @@ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="JavaScript_Development/Module_Cookbook.xml" encoding="UTF-8"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="JavaScript_Development/Script_Cookbook.xml" encoding="UTF-8"/> </part> + <part> + <title>Advanced Development Concepts</title> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="The_eXo_Kernel.xml" encoding="UTF-8"/> + </part> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="appendix-Quickstarts.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Revision_History.xml"/> </book> Copied: epp/docs/JPP/trunk/Development_Guide/en-US/Gadget_Development.xml (from rev 9215, epp/docs/JPP/trunk/Development_Guide/en-US/Application_Development/Gadget_Development.xml) =================================================================== (Binary files differ) Deleted: epp/docs/JPP/trunk/Development_Guide/en-US/Introduction/Introduction.xml =================================================================== (Binary files differ) Copied: epp/docs/JPP/trunk/Development_Guide/en-US/Introduction.xml (from rev 9215, epp/docs/JPP/trunk/Development_Guide/en-US/Introduction/Introduction.xml) =================================================================== (Binary files differ) Copied: epp/docs/JPP/trunk/Development_Guide/en-US/Portal_Containers.xml (from rev 9215, epp/docs/JPP/trunk/Development_Guide/en-US/Portal_Development/Portal_Containers.xml) =================================================================== (Binary files differ) Deleted: epp/docs/JPP/trunk/Development_Guide/en-US/Portal_Development/Portal_Containers.xml =================================================================== (Binary files differ) Deleted: epp/docs/JPP/trunk/Development_Guide/en-US/Portal_Development/Portal_Extension.xml =================================================================== (Binary files differ) Deleted: epp/docs/JPP/trunk/Development_Guide/en-US/Portal_Development/Visual_Identity.xml =================================================================== (Binary files differ) Copied: epp/docs/JPP/trunk/Development_Guide/en-US/Portal_Extension.xml (from rev 9215, epp/docs/JPP/trunk/Development_Guide/en-US/Portal_Development/Portal_Extension.xml) =================================================================== (Binary files differ) Copied: epp/docs/JPP/trunk/Development_Guide/en-US/Portlet_Development.xml (from rev 9215, epp/docs/JPP/trunk/Development_Guide/en-US/Application_Development/Portlet_Development.xml) =================================================================== (Binary files differ) Copied: epp/docs/JPP/trunk/Development_Guide/en-US/Visual_Identity.xml (from rev 9215, epp/docs/JPP/trunk/Development_Guide/en-US/Portal_Development/Visual_Identity.xml) =================================================================== (Binary files differ)

11 years, 9 months

1
0
0 / 0

gatein SVN: r9215 - in epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181: component/identity/src/main/java/org/exoplatform/services/organization/idm and 19 other directories.

by do-not-reply＠jboss.org

Author: mputz Date: 2013-03-20 11:17:30 -0400 (Wed, 20 Mar 2013) New Revision: 9215 Added: epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/webui/framework/src/main/java/org/exoplatform/webui/CSRFTokenUtil.java Modified: epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/component/identity/src/main/java/org/exoplatform/services/organization/idm/IDMMembershipListAccess.java epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/component/web/controller/src/main/java/org/exoplatform/web/application/ApplicationMessage.java epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/component/web/controller/src/main/java/org/exoplatform/web/application/URLBuilder.java epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/component/web/controller/src/main/java/org/exoplatform/web/url/PortalURL.java epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/pom.xml epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/portlet/exoadmin/src/main/java/org/exoplatform/account/webui/component/UIRegisterForm.java epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/portlet/exoadmin/src/main/java/org/exoplatform/navigation/webui/component/UIPageNodeForm.java epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/portlet/exoadmin/src/main/java/org/exoplatform/organization/webui/component/UIGroupMembershipForm.java epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/portlet/exoadmin/src/main/java/org/exoplatform/organization/webui/component/UIUserInGroup.java epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/portlet/exoadmin/src/main/java/org/exoplatform/organization/webui/component/UIUserInfo.java epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/webui/core/src/main/java/org/exoplatform/webui/core/lifecycle/UIFormLifecycle.java epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/webui/core/src/main/java/org/exoplatform/webui/form/UIForm.java epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/webui/framework/src/main/java/org/exoplatform/webui/application/ConfigurationManager.java epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/webui/framework/src/main/java/org/exoplatform/webui/config/Event.java epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/webui/framework/src/main/java/org/exoplatform/webui/config/annotation/EventConfig.java epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/webui/framework/src/main/java/org/exoplatform/webui/core/UIApplication.java epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/webui/framework/src/main/java/org/exoplatform/webui/core/UIComponent.java epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/webui/framework/src/main/java/org/exoplatform/webui/event/Event.java epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/webui/framework/src/main/java/org/exoplatform/webui/exception/MessageException.java epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/webui/portal/src/main/java/org/exoplatform/portal/account/UIAccountProfiles.java epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/webui/portal/src/main/java/org/exoplatform/portal/application/PortalURLBuilder.java epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/webui/portal/src/main/java/org/exoplatform/portal/url/PortalURLContext.java epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/webui/portal/src/main/java/org/exoplatform/portal/webui/application/ExoPortletInvocationContext.java epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/webui/portlet/src/main/java/org/exoplatform/webui/application/portlet/PortletURLBuilder.java Log: Bug 851392 - Fix for CVE-2012-3532: Gatein CSRF issue + previous patches Modified: epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/component/identity/src/main/java/org/exoplatform/services/organization/idm/IDMMembershipListAccess.java =================================================================== --- epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/component/identity/src/main/java/org/exoplatform/services/organization/idm/IDMMembershipListAccess.java 2013-03-20 04:10:52 UTC (rev 9214) +++ epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/component/identity/src/main/java/org/exoplatform/services/organization/idm/IDMMembershipListAccess.java 2013-03-20 15:17:30 UTC (rev 9215) @@ -103,7 +103,7 @@ // int i = 0; - for (; i < roles.size(); i++) + for (; i < length; i++) { Role role = roles.get(i); Modified: epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/component/web/controller/src/main/java/org/exoplatform/web/application/ApplicationMessage.java =================================================================== --- epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/component/web/controller/src/main/java/org/exoplatform/web/application/ApplicationMessage.java 2013-03-20 04:10:52 UTC (rev 9214) +++ epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/component/web/controller/src/main/java/org/exoplatform/web/application/ApplicationMessage.java 2013-03-20 15:17:30 UTC (rev 9215) @@ -30,13 +30,22 @@ { private final String messageKey_; private final Object[] messageArgs_; + private String message; public ApplicationMessage(String key, Object[] args) { this.messageKey_ = key; this.messageArgs_ = args; + message = null; } + public ApplicationMessage(String message) + { + messageKey_ = null; + messageArgs_ = null; + this.message = message; + } + @Override public boolean equals(Object o) { @@ -85,24 +94,32 @@ public String getMessage() { - String msg = resolveMessage(messageKey_); - if (msg != null && messageArgs_ != null) + if (message == null) { - for (int i = 0; i < messageArgs_.length; i++) + String msg = resolveMessage(messageKey_); + if (msg != null && messageArgs_ != null) { - final Object messageArg = messageArgs_[i]; - if (messageArg != null) + for (int i = 0; i < messageArgs_.length; i++) { - String arg = messageArg.toString(); - if (isArgsLocalized()) + final Object messageArg = messageArgs_[i]; + if (messageArg != null) { - arg = resolveMessage(arg); + String arg = messageArg.toString(); + if (isArgsLocalized()) + { + arg = resolveMessage(arg); + } + msg = msg.replace("{" + i + "}", arg); } - msg = msg.replace("{" + i + "}", arg); } } + + message = msg; + return msg; } - - return msg; + else + { + return message; + } } } Modified: epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/component/web/controller/src/main/java/org/exoplatform/web/application/URLBuilder.java =================================================================== --- epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/component/web/controller/src/main/java/org/exoplatform/web/application/URLBuilder.java 2013-03-20 04:10:52 UTC (rev 9214) +++ epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/component/web/controller/src/main/java/org/exoplatform/web/application/URLBuilder.java 2013-03-20 15:17:30 UTC (rev 9215) @@ -78,20 +78,20 @@ public final String createURL(T targetComponent, String action, String targetBeanId) { - return createURL(targetComponent, action, null, targetBeanId, (Parameter[])null); + return createURL(targetComponent, action, null, targetBeanId, (Parameter[])null, false); } public final String createAjaxURL(T targetComponent, String action, String targetBeanId) { - return createAjaxURL(targetComponent, action, null, targetBeanId, (Parameter[])null); + return createAjaxURL(targetComponent, action, null, targetBeanId, (Parameter[])null, false); } public final String createAjaxURL(T targetComponent, String action, String confirm, String targetBeanId) { - return createAjaxURL(targetComponent, action, confirm, targetBeanId, (Parameter[])null); + return createAjaxURL(targetComponent, action, confirm, targetBeanId, (Parameter[])null, false); } - public abstract String createAjaxURL(T targetComponent, String action, String confirm, String targetBeanId, Parameter[] params); + public abstract String createAjaxURL(T targetComponent, String action, String confirm, String targetBeanId, Parameter[] params, boolean csrfCheck); - public abstract String createURL(T targetComponent, String action, String confirm, String targetBeanId, Parameter[] params); + public abstract String createURL(T targetComponent, String action, String confirm, String targetBeanId, Parameter[] params, boolean csrfCheck); } Modified: epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/component/web/controller/src/main/java/org/exoplatform/web/url/PortalURL.java =================================================================== --- epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/component/web/controller/src/main/java/org/exoplatform/web/url/PortalURL.java 2013-03-20 04:10:52 UTC (rev 9214) +++ epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/component/web/controller/src/main/java/org/exoplatform/web/url/PortalURL.java 2013-03-20 15:17:30 UTC (rev 9215) @@ -43,6 +43,9 @@ /** . */ private boolean authorityUse; + + /** . */ + private boolean csrfCheck; /** . */ protected Boolean ajax; @@ -241,7 +244,17 @@ { this.locale = locale; } + + public boolean isCSRFCheck() + { + return csrfCheck; + } + public void setCSRFCheck(boolean csrfCheck) + { + this.csrfCheck = csrfCheck; + } + /** * Reset the Portal URL state */ Modified: epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/pom.xml =================================================================== --- epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/pom.xml 2013-03-20 04:10:52 UTC (rev 9214) +++ epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/pom.xml 2013-03-20 15:17:30 UTC (rev 9215) @@ -52,7 +52,7 @@ <org.gatein.dep.version>1.1.0-GA</org.gatein.dep.version> <org.gatein.wci.version>2.1.1-GA</org.gatein.wci.version> <org.gatein.pc.version>2.3.1-GA</org.gatein.pc.version> - <org.picketlink.idm>1.3.2.CR01</org.picketlink.idm> + <org.picketlink.idm>1.3.3.Final</org.picketlink.idm> <org.gatein.wsrp.version>2.1.7-EPP522-GA</org.gatein.wsrp.version> <org.gatein.mop.version>1.1.2-GA</org.gatein.mop.version> <org.gatein.mgmt.version>1.0.1-GA</org.gatein.mgmt.version> Modified: epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/portlet/exoadmin/src/main/java/org/exoplatform/account/webui/component/UIRegisterForm.java =================================================================== --- epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/portlet/exoadmin/src/main/java/org/exoplatform/account/webui/component/UIRegisterForm.java 2013-03-20 04:10:52 UTC (rev 9214) +++ epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/portlet/exoadmin/src/main/java/org/exoplatform/account/webui/component/UIRegisterForm.java 2013-03-20 15:17:30 UTC (rev 9215) @@ -18,7 +18,7 @@ */ package org.exoplatform.account.webui.component; - + import java.util.ArrayList; import java.util.List; @@ -154,7 +154,7 @@ } catch (MessageException e) { - event.getRequestContext().getUIApplication().addMessage(e.getDetailMessage()); + event.getRequestContext().getUIApplication().addMessage(e.getDetailedMessage()); return; } Modified: epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/portlet/exoadmin/src/main/java/org/exoplatform/navigation/webui/component/UIPageNodeForm.java =================================================================== --- epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/portlet/exoadmin/src/main/java/org/exoplatform/navigation/webui/component/UIPageNodeForm.java 2013-03-20 04:10:52 UTC (rev 9214) +++ epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/portlet/exoadmin/src/main/java/org/exoplatform/navigation/webui/component/UIPageNodeForm.java 2013-03-20 15:17:30 UTC (rev 9215) @@ -677,7 +677,7 @@ } catch (MessageException ex) { - uiPortalApp.addMessage(ex.getDetailMessage()); + uiPortalApp.addMessage(ex.getDetailedMessage()); return; } catch (Exception ex) Modified: epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/portlet/exoadmin/src/main/java/org/exoplatform/organization/webui/component/UIGroupMembershipForm.java =================================================================== --- epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/portlet/exoadmin/src/main/java/org/exoplatform/organization/webui/component/UIGroupMembershipForm.java 2013-03-20 04:10:52 UTC (rev 9214) +++ epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/portlet/exoadmin/src/main/java/org/exoplatform/organization/webui/component/UIGroupMembershipForm.java 2013-03-20 15:17:30 UTC (rev 9215) @@ -41,7 +41,7 @@ import org.exoplatform.webui.form.UIForm; import org.exoplatform.webui.form.UIFormSelectBox; import org.exoplatform.webui.form.UIFormStringInput; -import org.exoplatform.webui.form.validator.UserConfigurableValidator; +import org.exoplatform.webui.form.validator.MandatoryValidator; import org.exoplatform.webui.organization.account.UIUserSelector; import java.util.ArrayList; @@ -75,7 +75,7 @@ public UIGroupMembershipForm() throws Exception { - addUIFormInput(new UIFormStringInput(USER_NAME, USER_NAME, null).addValidator(UserConfigurableValidator.class, UserConfigurableValidator.GROUPMEMBERSHIP, UserConfigurableValidator.GROUP_MEMBERSHIP_LOCALIZATION_KEY)); + addUIFormInput(new UIFormStringInput(USER_NAME, USER_NAME, null).addValidator(MandatoryValidator.class)); addUIFormInput(new UIFormSelectBox("membership", "membership", listOption).setSize(1)); UIPopupWindow searchUserPopup = addChild(UIPopupWindow.class, "SearchUser", "SearchUser"); searchUserPopup.setWindowSize(640, 0); Modified: epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/portlet/exoadmin/src/main/java/org/exoplatform/organization/webui/component/UIUserInGroup.java =================================================================== --- epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/portlet/exoadmin/src/main/java/org/exoplatform/organization/webui/component/UIUserInGroup.java 2013-03-20 04:10:52 UTC (rev 9214) +++ epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/portlet/exoadmin/src/main/java/org/exoplatform/organization/webui/component/UIUserInGroup.java 2013-03-20 15:17:30 UTC (rev 9215) @@ -132,14 +132,9 @@ } else { - OrganizationService service = getApplicationComponent(OrganizationService.class); - MembershipHandler handler = service.getMembershipHandler(); - ListAccess<?> list = handler.findAllMembershipsByGroup(group); - pageList = new FindMembershipByGroupPageList(group.getId(), - list.getSize() > 10 ? list.getSize() : 10); + pageList = new FindMembershipByGroupPageList(group.getId(), 5); } UIGridUser uiGrid = getChild(UIGridUser.class); - pageList.setPageSize(5); UIPageIterator pageIterator = uiGrid.getUIPageIterator(); /** We keep the currently selected page index **/ Modified: epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/portlet/exoadmin/src/main/java/org/exoplatform/organization/webui/component/UIUserInfo.java =================================================================== --- epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/portlet/exoadmin/src/main/java/org/exoplatform/organization/webui/component/UIUserInfo.java 2013-03-20 04:10:52 UTC (rev 9214) +++ epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/portlet/exoadmin/src/main/java/org/exoplatform/organization/webui/component/UIUserInfo.java 2013-03-20 15:17:30 UTC (rev 9215) @@ -48,7 +48,7 @@ /** Created by The eXo Platform SARL Author : chungnv nguyenchung136(a)yahoo.com Jun 23, 2006 10:07:15 AM */ @ComponentConfig(lifecycle = UIFormLifecycle.class, template = "system:/groovy/webui/form/UIFormTabPane.gtmpl", events = { - @EventConfig(listeners = UIUserInfo.SaveActionListener.class), + @EventConfig(listeners = UIUserInfo.SaveActionListener.class, csrfCheck = true), @EventConfig(listeners = UIUserInfo.BackActionListener.class, phase = Phase.DECODE), @EventConfig(listeners = UIUserInfo.ToggleChangePasswordActionListener.class, phase = Phase.DECODE)}) @Serialized Modified: epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/webui/core/src/main/java/org/exoplatform/webui/core/lifecycle/UIFormLifecycle.java =================================================================== --- epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/webui/core/src/main/java/org/exoplatform/webui/core/lifecycle/UIFormLifecycle.java 2013-03-20 04:10:52 UTC (rev 9214) +++ epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/webui/core/src/main/java/org/exoplatform/webui/core/lifecycle/UIFormLifecycle.java 2013-03-20 15:17:30 UTC (rev 9215) @@ -195,7 +195,7 @@ } catch (MessageException ex) { - uiApp.addMessage(ex.getDetailMessage()); + uiApp.addMessage(ex.getDetailedMessage()); context.setProcessRender(true); } catch (Exception ex) @@ -231,7 +231,7 @@ } catch (MessageException ex) { - uiApp.addMessage(ex.getDetailMessage()); + uiApp.addMessage(ex.getDetailedMessage()); context.setProcessRender(true); } } @@ -261,7 +261,7 @@ } catch (MessageException ex) { - uiApp.addMessage(ex.getDetailMessage()); + uiApp.addMessage(ex.getDetailedMessage()); context.setProcessRender(true); } catch (Exception ex) Modified: epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/webui/core/src/main/java/org/exoplatform/webui/form/UIForm.java =================================================================== --- epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/webui/core/src/main/java/org/exoplatform/webui/form/UIForm.java 2013-03-20 04:10:52 UTC (rev 9214) +++ epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/webui/core/src/main/java/org/exoplatform/webui/form/UIForm.java 2013-03-20 15:17:30 UTC (rev 9215) @@ -19,6 +19,7 @@ package org.exoplatform.webui.form; +import org.exoplatform.webui.CSRFTokenUtil; import org.exoplatform.webui.application.WebuiRequestContext; import org.exoplatform.webui.application.portlet.PortletRequestContext; import org.exoplatform.commons.serialization.api.annotations.Serialized; @@ -186,7 +187,10 @@ writer.append(" enctype=\"multipart/form-data\""); } writer.append(" method=\"post\">"); - writer.append("<div><input type=\"hidden\" name=\"").append(ACTION).append("\" value=\"\"/></div>"); + writer.append("<div><input type=\"hidden\" name=\"").append(ACTION).append("\" value=\"\"/>"); + writer.append("<input type=\"hidden\" name=\"").append(CSRFTokenUtil.CSRF_TOKEN).append("\" value=\""); + writer.append(CSRFTokenUtil.getToken()); + writer.append("\"/></div>"); } @Override @@ -336,4 +340,4 @@ { return "uiform"; } -} \ No newline at end of file +} Added: epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/webui/framework/src/main/java/org/exoplatform/webui/CSRFTokenUtil.java =================================================================== --- epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/webui/framework/src/main/java/org/exoplatform/webui/CSRFTokenUtil.java (rev 0) +++ epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/webui/framework/src/main/java/org/exoplatform/webui/CSRFTokenUtil.java 2013-03-20 15:17:30 UTC (rev 9215) @@ -0,0 +1,99 @@ +/* + * Copyright (C) 2012 eXo Platform SAS. + * + * This is free software; you can redistribute it and/or modify it + * under the terms of the GNU Lesser General Public License as + * published by the Free Software Foundation; either version 2.1 of + * the License, or (at your option) any later version. + * + * This software is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * Lesser General Public License for more details. + * + * You should have received a copy of the GNU Lesser General Public + * License along with this software; if not, write to the Free + * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA + * 02110-1301 USA, or see the FSF site: http://www.fsf.org. + */ +package org.exoplatform.webui; + +import javax.portlet.PortletRequest; +import javax.servlet.http.HttpServletRequest; +import javax.servlet.http.HttpSession; + +import org.exoplatform.services.log.ExoLogger; +import org.exoplatform.services.log.Log; +import org.exoplatform.webui.application.WebuiRequestContext; +import org.gatein.common.util.UUIDGenerator; + +/** + * @author <a href="mailto:phuong.vu@exoplatform.com">Vu Viet Phuong</a> + * @version $Id$ + * + */ +public class CSRFTokenUtil +{ + public static final String CSRF_TOKEN = "gtn:csrf"; + + private static Log log = ExoLogger.getExoLogger(CSRFTokenUtil.class); + + private static final UUIDGenerator generator = new UUIDGenerator(); + + public static boolean check() throws Exception + { + HttpServletRequest request = getRequest(); + if (request != null) + { + String sessionToken = getToken(); + String reqToken = request.getParameter(CSRF_TOKEN); + + return reqToken != null && reqToken.equals(sessionToken); + } + else + { + log.warn("No HttpServletRequest found, can't check CSRF"); + return false; + } + } + + public static String getToken() throws Exception + { + HttpServletRequest request = getRequest(); + if (request != null) + { + HttpSession session = request.getSession(); + String token = (String)session.getAttribute(CSRF_TOKEN); + if (token == null) + { + token = generator.generateKey(); + session.setAttribute(CSRF_TOKEN, token); + } + return token; + } + else + { + log.warn("No HttpServletRequest found, can't generate CSRF token"); + return null; + } + } + + private static HttpServletRequest getRequest() throws Exception + { + WebuiRequestContext context = WebuiRequestContext.getCurrentInstance(); + if (context != null && context.getRequest() instanceof PortletRequest) + { + context = (WebuiRequestContext)context.getParentAppRequestContext(); + } + + if (context != null) + { + return context.getRequest(); + } + else + { + log.warn("Can't find portal context"); + return null; + } + } +} Modified: epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/webui/framework/src/main/java/org/exoplatform/webui/application/ConfigurationManager.java =================================================================== --- epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/webui/framework/src/main/java/org/exoplatform/webui/application/ConfigurationManager.java 2013-03-20 04:10:52 UTC (rev 9214) +++ epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/webui/framework/src/main/java/org/exoplatform/webui/application/ConfigurationManager.java 2013-03-20 15:17:30 UTC (rev 9215) @@ -373,6 +373,7 @@ event.setName(name); } event.setListeners(listeners); + event.setCsrfCheck(annotation.csrfCheck()); return event; } Modified: epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/webui/framework/src/main/java/org/exoplatform/webui/config/Event.java =================================================================== --- epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/webui/framework/src/main/java/org/exoplatform/webui/config/Event.java 2013-03-20 04:10:52 UTC (rev 9214) +++ epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/webui/framework/src/main/java/org/exoplatform/webui/config/Event.java 2013-03-20 15:17:30 UTC (rev 9215) @@ -39,6 +39,8 @@ private InitParams initParams; private ArrayList<String> listeners; + + private boolean csrfCheck; transient private List<EventListener> eventListeners_; @@ -125,5 +127,15 @@ { eventListeners_ = list; } + + public boolean isCsrfCheck() + { + return csrfCheck; + } + public void setCsrfCheck(boolean csrfCheck) + { + this.csrfCheck = csrfCheck; + } + } Modified: epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/webui/framework/src/main/java/org/exoplatform/webui/config/annotation/EventConfig.java =================================================================== --- epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/webui/framework/src/main/java/org/exoplatform/webui/config/annotation/EventConfig.java 2013-03-20 04:10:52 UTC (rev 9214) +++ epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/webui/framework/src/main/java/org/exoplatform/webui/config/annotation/EventConfig.java 2013-03-20 15:17:30 UTC (rev 9215) @@ -40,6 +40,8 @@ Class[] listeners(); Phase phase() default Phase.PROCESS; + + boolean csrfCheck() default false; ParamConfig[] initParams() default {}; } Modified: epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/webui/framework/src/main/java/org/exoplatform/webui/core/UIApplication.java =================================================================== --- epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/webui/framework/src/main/java/org/exoplatform/webui/core/UIApplication.java 2013-03-20 04:10:52 UTC (rev 9214) +++ epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/webui/framework/src/main/java/org/exoplatform/webui/core/UIApplication.java 2013-03-20 15:17:30 UTC (rev 9215) @@ -138,7 +138,7 @@ } catch (MessageException ex) { - addMessage(ex.getDetailMessage()); + addMessage(ex.getDetailedMessage()); } catch (Throwable t) { Modified: epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/webui/framework/src/main/java/org/exoplatform/webui/core/UIComponent.java =================================================================== --- epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/webui/framework/src/main/java/org/exoplatform/webui/core/UIComponent.java 2013-03-20 04:10:52 UTC (rev 9214) +++ epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/webui/framework/src/main/java/org/exoplatform/webui/core/UIComponent.java 2013-03-20 15:17:30 UTC (rev 9215) @@ -319,13 +319,13 @@ // if (ajax) { - return urlBuilder.createAjaxURL(this, event.getName(), confirm, beanId, params); + return urlBuilder.createAjaxURL(this, event.getName(), confirm, beanId, params, event.isCsrfCheck()); } else { try { - return urlBuilder.createURL(this, event.getName(), confirm, beanId, params); + return urlBuilder.createURL(this, event.getName(), confirm, beanId, params, event.isCsrfCheck()); } catch (Exception e) { @@ -352,6 +352,8 @@ { return; } + event.setCsrfCheck(econfig.isCsrfCheck()); + Phase executionPhase = econfig.getExecutionPhase(); if (executionPhase == phase || executionPhase == Event.Phase.ANY) { @@ -461,6 +463,7 @@ Event<UIComponent> event = new Event<UIComponent>(this, name, context); event.setExecutionPhase(phase); event.setEventListeners(econfig.getCachedEventListeners()); + event.setCsrfCheck(econfig.isCsrfCheck()); return event; } return null; @@ -490,4 +493,4 @@ } return null; } -} \ No newline at end of file +} Modified: epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/webui/framework/src/main/java/org/exoplatform/webui/event/Event.java =================================================================== --- epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/webui/framework/src/main/java/org/exoplatform/webui/event/Event.java 2013-03-20 04:10:52 UTC (rev 9214) +++ epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/webui/framework/src/main/java/org/exoplatform/webui/event/Event.java 2013-03-20 15:17:30 UTC (rev 9215) @@ -19,9 +19,13 @@ package org.exoplatform.webui.event; +import java.util.List; + +import org.exoplatform.services.log.ExoLogger; +import org.exoplatform.services.log.Log; +import org.exoplatform.webui.CSRFTokenUtil; import org.exoplatform.webui.application.WebuiRequestContext; -import java.util.List; public class Event<T> { @@ -35,6 +39,10 @@ private WebuiRequestContext context_; private List<EventListener> listeners_; + + private boolean csrfCheck; + + private static final Log log = ExoLogger.getLogger(Event.class.getName()); public Event(T source, String name, WebuiRequestContext context) { @@ -83,14 +91,32 @@ listeners_ = listeners; } - final public void broadcast() throws Exception + public boolean isCsrfCheck() { - for (EventListener<T> listener : listeners_) - listener.execute(this); + return csrfCheck; } + public void setCsrfCheck(boolean csrfCheck) + { + this.csrfCheck = csrfCheck; + } + + final public void broadcast() throws Exception + { + if (isCsrfCheck() && !CSRFTokenUtil.check()) + { + getRequestContext().setResponseComplete(true); + log.error("csrfToken is lost or this is an csrf attack"); + } + else + { + for (EventListener<T> listener : listeners_) + listener.execute(this); + } + } + static public enum Phase { ANY, DECODE, PROCESS, RENDER } -} \ No newline at end of file +} Modified: epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/webui/framework/src/main/java/org/exoplatform/webui/exception/MessageException.java =================================================================== --- epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/webui/framework/src/main/java/org/exoplatform/webui/exception/MessageException.java 2013-03-20 04:10:52 UTC (rev 9214) +++ epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/webui/framework/src/main/java/org/exoplatform/webui/exception/MessageException.java 2013-03-20 15:17:30 UTC (rev 9215) @@ -45,9 +45,13 @@ this((AbstractApplicationMessage)message); } - public AbstractApplicationMessage getDetailMessage() + public AbstractApplicationMessage getDetailedMessage() { return message; } + public ApplicationMessage getDetailMessage() + { + return new ApplicationMessage(message.getMessage()); + } } Modified: epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/webui/portal/src/main/java/org/exoplatform/portal/account/UIAccountProfiles.java =================================================================== --- epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/webui/portal/src/main/java/org/exoplatform/portal/account/UIAccountProfiles.java 2013-03-20 04:10:52 UTC (rev 9214) +++ epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/webui/portal/src/main/java/org/exoplatform/portal/account/UIAccountProfiles.java 2013-03-20 15:17:30 UTC (rev 9215) @@ -52,7 +52,7 @@ @ComponentConfig(lifecycle = UIFormLifecycle.class, template = "system:/groovy/webui/form/UIForm.gtmpl", -events = {@EventConfig(listeners = UIAccountProfiles.SaveActionListener.class), +events = {@EventConfig(listeners = UIAccountProfiles.SaveActionListener.class, csrfCheck = true), @EventConfig(listeners = UIAccountProfiles.ResetActionListener.class, phase = Phase.DECODE)}) public class UIAccountProfiles extends UIForm { Modified: epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/webui/portal/src/main/java/org/exoplatform/portal/application/PortalURLBuilder.java =================================================================== --- epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/webui/portal/src/main/java/org/exoplatform/portal/application/PortalURLBuilder.java 2013-03-20 04:10:52 UTC (rev 9214) +++ epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/webui/portal/src/main/java/org/exoplatform/portal/application/PortalURLBuilder.java 2013-03-20 15:17:30 UTC (rev 9215) @@ -46,18 +46,18 @@ } @Override - public String createAjaxURL(UIComponent targetComponent, String action, String confirm, String targetBeanId, Parameter[] params) + public String createAjaxURL(UIComponent targetComponent, String action, String confirm, String targetBeanId, Parameter[] params, boolean csrfCheck) { - return createURL(true, targetComponent, action, confirm, targetBeanId, params); + return createURL(true, targetComponent, action, confirm, targetBeanId, params, csrfCheck); } @Override - public String createURL(UIComponent targetComponent, String action, String confirm, String targetBeanId, Parameter[] params) + public String createURL(UIComponent targetComponent, String action, String confirm, String targetBeanId, Parameter[] params, boolean csrfCheck) { - return createURL(false, targetComponent, action, confirm, targetBeanId, params); + return createURL(false, targetComponent, action, confirm, targetBeanId, params, csrfCheck); } - private String createURL(boolean ajax, UIComponent targetComponent, String action, String confirm, String targetBeanId, Parameter[] params) + private String createURL(boolean ajax, UIComponent targetComponent, String action, String confirm, String targetBeanId, Parameter[] params, boolean csrfCheck) { url.reset(); @@ -88,7 +88,9 @@ { url.setLocale(locale); } - + + url.setCSRFCheck(csrfCheck); + // return url.toString(); } Modified: epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/webui/portal/src/main/java/org/exoplatform/portal/url/PortalURLContext.java =================================================================== --- epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/webui/portal/src/main/java/org/exoplatform/portal/url/PortalURLContext.java 2013-03-20 04:10:52 UTC (rev 9214) +++ epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/webui/portal/src/main/java/org/exoplatform/portal/url/PortalURLContext.java 2013-03-20 15:17:30 UTC (rev 9215) @@ -19,6 +19,13 @@ package org.exoplatform.portal.url; +import javax.servlet.http.HttpServletRequest; + +import java.io.IOException; +import java.util.HashMap; +import java.util.Locale; +import java.util.Map; + import org.exoplatform.commons.utils.I18N; import org.exoplatform.portal.application.PortalRequestHandler; import org.exoplatform.portal.mop.SiteKey; @@ -28,14 +35,9 @@ import org.exoplatform.web.controller.router.URIWriter; import org.exoplatform.web.url.PortalURL; import org.exoplatform.web.url.URLContext; +import org.exoplatform.webui.CSRFTokenUtil; import org.gatein.common.io.UndeclaredIOException; -import javax.servlet.http.HttpServletRequest; -import java.io.IOException; -import java.util.HashMap; -import java.util.Locale; -import java.util.Map; - /** * @author <a href="mailto:julien.viet@exoplatform.com">Julien Viet</a> */ @@ -189,7 +191,22 @@ } } } - + + //CSRF token + if (url.isCSRFCheck()) + { + String token; + try + { + token = CSRFTokenUtil.getToken(); + writer.appendQueryParameter(CSRFTokenUtil.CSRF_TOKEN, token); + } + catch (Exception e) + { + throw new IllegalStateException("Can't add csrf token to url", e); + } + } + // if (ajax) { Modified: epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/webui/portal/src/main/java/org/exoplatform/portal/webui/application/ExoPortletInvocationContext.java =================================================================== --- epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/webui/portal/src/main/java/org/exoplatform/portal/webui/application/ExoPortletInvocationContext.java 2013-03-20 04:10:52 UTC (rev 9214) +++ epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/webui/portal/src/main/java/org/exoplatform/portal/webui/application/ExoPortletInvocationContext.java 2013-03-20 15:17:30 UTC (rev 9215) @@ -24,6 +24,7 @@ import org.exoplatform.portal.application.PortalRequestContext; import org.exoplatform.web.url.MimeType; import org.exoplatform.web.url.PortalURL; +import org.exoplatform.webui.application.portlet.PortletURLBuilder; import org.exoplatform.webui.core.UIComponent; import org.exoplatform.webui.url.ComponentURL; import org.gatein.common.logging.Logger; @@ -282,6 +283,10 @@ // Confirm messsage url.setConfirm(props.get("gtn:confirm")); + + // + String csrfCheck = props.get(PortletURLBuilder.CSRF_PROP); + url.setCSRFCheck(Boolean.parseBoolean(csrfCheck)); // MimeType mimeType = Boolean.TRUE.equals(format.getWantEscapeXML()) ? MimeType.XHTML : MimeType.PLAIN; Modified: epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/webui/portlet/src/main/java/org/exoplatform/webui/application/portlet/PortletURLBuilder.java =================================================================== --- epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/webui/portlet/src/main/java/org/exoplatform/webui/application/portlet/PortletURLBuilder.java 2013-03-20 04:10:52 UTC (rev 9214) +++ epp/portal/branches/EPP_5_2_2_GA_BZ851392_BZ874821_BZ895343_BZ921181/webui/portlet/src/main/java/org/exoplatform/webui/application/portlet/PortletURLBuilder.java 2013-03-20 15:17:30 UTC (rev 9215) @@ -35,27 +35,29 @@ /** . */ private final PortletURL url; + + public static final String CSRF_PROP = "gtn:csrfCheck"; public PortletURLBuilder(PortletURL url) { this.url = url; } - public String createAjaxURL(UIComponent targetComponent, String action, String confirm, String targetBeanId, Parameter[] params) + public String createAjaxURL(UIComponent targetComponent, String action, String confirm, String targetBeanId, Parameter[] params, boolean csrfCheck) { - return createURL(true, confirm, targetComponent, action, targetBeanId, params); + return createURL(true, confirm, targetComponent, action, targetBeanId, params, csrfCheck); } - public String createURL(UIComponent targetComponent, String action, String confirm, String targetBeanId, Parameter[] params) + public String createURL(UIComponent targetComponent, String action, String confirm, String targetBeanId, Parameter[] params, boolean csrfCheck) { - return createURL(false, confirm, targetComponent, action, targetBeanId, params); + return createURL(false, confirm, targetComponent, action, targetBeanId, params, csrfCheck); } private String createURL( boolean ajax, String confirm, UIComponent targetComponent, String action, String targetBeanId, - Parameter[] params) + Parameter[] params, boolean csrfCheck) { // Clear URL url.getParameterMap().clear(); @@ -99,6 +101,12 @@ } // + if (csrfCheck) + { + url.setProperty(CSRF_PROP, Boolean.TRUE.toString()); + } + return url.toString(); + } }

11 years, 9 months

1
0
0 / 0

gatein SVN: r9214 - epp/docs/JPP/tags/6.0.

by do-not-reply＠jboss.org

Author: jaredmorgs Date: 2013-03-20 00:10:52 -0400 (Wed, 20 Mar 2013) New Revision: 9214 Removed: epp/docs/JPP/tags/6.0/Draft_CSP_Maps/ Log: This folder is not required in the tagged directory. Cleaning up

11 years, 9 months

1
0
0 / 0

gatein SVN: r9213 - epp/docs/JPP.

by do-not-reply＠jboss.org

Author: jaredmorgs Date: 2013-03-20 00:09:15 -0400 (Wed, 20 Mar 2013) New Revision: 9213 Added: epp/docs/JPP/trunk/ Removed: epp/docs/JPP/6.0/ Log: And finally renaming the folder to trunk

11 years, 9 months

1
0
0 / 0

gatein SVN: r9212 - epp/docs/JPP/tags.

by do-not-reply＠jboss.org

Author: jaredmorgs Date: 2013-03-20 00:07:51 -0400 (Wed, 20 Mar 2013) New Revision: 9212 Added: epp/docs/JPP/tags/6.0/ Log: Moving the current docs trunk to a tag for safe keeping

11 years, 9 months

1
0
0 / 0

gatein SVN: r9211 - epp/docs/JPP.

by do-not-reply＠jboss.org

Author: jaredmorgs Date: 2013-03-20 00:04:50 -0400 (Wed, 20 Mar 2013) New Revision: 9211 Removed: epp/docs/JPP/trunk/ Log: Deleting the old trunk

11 years, 9 months

1
0
0 / 0

gatein SVN: r9210 - in epp/docs/JPP: trunk and 1 other directory.

by do-not-reply＠jboss.org

Author: jaredmorgs Date: 2013-03-20 00:03:41 -0400 (Wed, 20 Mar 2013) New Revision: 9210 Added: epp/docs/JPP/6.0/ Removed: epp/docs/JPP/trunk/6.0/ Log: Moving things some more

11 years, 9 months

1
0
0 / 0

2024

2023

2022

2021

2020

2019

2018

2017

2016

2015

2014

2013

2012

2011

2010

2009

gatein-commits March 2013