[gatein-commits] gatein SVN: r8141 - in epp/docs/branches/5.2: Reference_Guide/en-US and 4 other directories.

Author: smumford Date: 2011-11-24 19:48:53 -0500 (Thu, 24 Nov 2011) New Revision: 8141 Added: epp/docs/branches/5.2/Reference_Guide/ epp/docs/branches/5.2/Reference_Guide/en-US/Author_Group.xml epp/docs/branches/5.2/Reference_Guide/en-US/Book_Info.xml epp/docs/branches/5.2/Reference_Guide/en-US/Revision_History.xml epp/docs/branches/5.2/Reference_Guide/en-US/images/WSRP/config_self.png epp/docs/branches/5.2/Reference_Guide/en-US/images/WSRP/modify_reg_end.png epp/docs/branches/5.2/Reference_Guide/en-US/images/WSRP/modify_reg_self_end.png epp/docs/branches/5.2/Reference_Guide/en-US/modules/Advanced/Foundations/Configuring_Services.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/SSO.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/RH-WSRP.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/WSRP.xml Removed: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/ epp/docs/branches/5.2/Reference_Guide/en-US/Author_Group.xml epp/docs/branches/5.2/Reference_Guide/en-US/Book_Info.xml epp/docs/branches/5.2/Reference_Guide/en-US/Revision_History.xml epp/docs/branches/5.2/Reference_Guide/en-US/images/WSRP/config_self.png epp/docs/branches/5.2/Reference_Guide/en-US/images/WSRP/modify_reg_end.png epp/docs/branches/5.2/Reference_Guide/en-US/images/WSRP/modify_reg_self_end.png epp/docs/branches/5.2/Reference_Guide/en-US/modules/Advanced/Foundations/Configuring_Services.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/SSO.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/WSRP.xml Log: Moving Ref_Guide_eXo to Ref_Guide Deleted: epp/docs/branches/5.2/Reference_Guide/en-US/Author_Group.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/Author_Group.xml 2011-11-24 17:26:22 UTC (rev 8138) +++ epp/docs/branches/5.2/Reference_Guide/en-US/Author_Group.xml 2011-11-25 00:48:53 UTC (rev 8141) @@ -1,57 +0,0 @@ -<?xml version='1.0' encoding='utf-8' ?> -<!DOCTYPE authorgroup PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -<!ENTITY % BOOK_ENTITIES SYSTEM "Reference_Guide_eXo_JCR_1.14.ent"> -%BOOK_ENTITIES; -]> -<authorgroup> - <editor> - <firstname>Luc</firstname> - <surname>Texier</surname> - <affiliation> - <shortaffil>Red Hat</shortaffil> - <orgdiv>JBoss Engineering</orgdiv> - - </affiliation> - - </editor> - <editor> - <firstname>Thomas</firstname> - <surname>Heute</surname> - <affiliation> - <shortaffil>Red Hat</shortaffil> - <orgdiv>JBoss Engineering</orgdiv> - - </affiliation> - - </editor> - <editor> - <firstname>Wesley</firstname> - <surname>Hales</surname> - <affiliation> - <shortaffil>Red Hat</shortaffil> - <orgdiv>JBoss Engineering</orgdiv> - - </affiliation> - - </editor> - <editor> - <firstname>Scott</firstname> - <surname>Mumford</surname> - <affiliation> - <shortaffil>Red Hat</shortaffil> - <orgdiv>Engineering Content Services</orgdiv> - - </affiliation> - - </editor> - <othercredit> - <affiliation> - <orgname><emphasis role="bold"><ulink type="http" url="http://www.jboss.org/gatein/">GateIn</ulink></... and <emphasis role="bold"><ulink type="http" url="http://www.exoplatform.com">eXo Platform</ulink></emphasis></orgname> - <orgdiv>Documentation Teams</orgdiv> - - </affiliation> - <contrib>Based on original product documentation by:</contrib> - - </othercredit> -</authorgroup> - Copied: epp/docs/branches/5.2/Reference_Guide/en-US/Author_Group.xml (from rev 8139, epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/Author_Group.xml) =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/Author_Group.xml (rev 0) +++ epp/docs/branches/5.2/Reference_Guide/en-US/Author_Group.xml 2011-11-25 00:48:53 UTC (rev 8141) @@ -0,0 +1,67 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE authorgroup PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "Reference_Guide_eXo_JCR_1.14.ent"> +%BOOK_ENTITIES; +]> +<authorgroup> + <editor> + <firstname>Luc</firstname> + <surname>Texier</surname> + <affiliation> + <shortaffil>Red Hat</shortaffil> + <orgdiv>JBoss Engineering</orgdiv> + + </affiliation> + + </editor> + <editor> + <firstname>Thomas</firstname> + <surname>Heute</surname> + <affiliation> + <shortaffil>Red Hat</shortaffil> + <orgdiv>JBoss Engineering</orgdiv> + + </affiliation> + + </editor> + <editor> + <firstname>Wesley</firstname> + <surname>Hales</surname> + <affiliation> + <shortaffil>Red Hat</shortaffil> + <orgdiv>JBoss Engineering</orgdiv> + + </affiliation> + + </editor> + <editor> + <firstname>Chris</firstname> + <surname>Laprun</surname> + <affiliation> + <shortaffil>Red Hat</shortaffil> + <orgdiv>JBoss Engineering</orgdiv> + + </affiliation> + + </editor> + <editor> + <firstname>Scott</firstname> + <surname>Mumford</surname> + <affiliation> + <shortaffil>Red Hat</shortaffil> + <orgdiv>Engineering Content Services</orgdiv> + + </affiliation> + + </editor> + <othercredit> + <affiliation> + <orgname><emphasis role="bold"><ulink type="http" url="http://www.jboss.org/gatein/">GateIn</ulink></... and <emphasis role="bold"><ulink type="http" url="http://www.exoplatform.com">eXo Platform</ulink></emphasis></orgname> + <orgdiv>Documentation Teams</orgdiv> + + </affiliation> + <contrib>Based on original product documentation by:</contrib> + + </othercredit> +</authorgroup> + Deleted: epp/docs/branches/5.2/Reference_Guide/en-US/Book_Info.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/Book_Info.xml 2011-11-24 17:26:22 UTC (rev 8138) +++ epp/docs/branches/5.2/Reference_Guide/en-US/Book_Info.xml 2011-11-25 00:48:53 UTC (rev 8141) @@ -1,33 +0,0 @@ -<?xml version='1.0' encoding='utf-8' ?> -<!DOCTYPE bookinfo 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_eXo_JCR_1.14.ent"> -%BOOK_ENTITIES; -]> -<bookinfo id="book-Reference_Guide_eXo_JCR_1.14-Reference_Guide_eXo_JCR_1.14"> - <title>Reference Guide eXo JCR 1.14</title> - <subtitle>An in-depth guide to Enterprise Portal Platform &VZ;</subtitle> - <productname>JBoss Enterprise Portal Platform</productname> - <productnumber>5.2</productnumber> - <edition>5.2.0</edition> - <pubsnumber>7</pubsnumber> - <abstract> - <para> - This Reference Guide is a high-level usage document. It deals with more advanced topics than the Installation and User Guides, adding new content or taking concepts discussed in the earlier documents further. It aims to provide supporting documentation for advanced users of the JBoss Enterprise Portal Platform product. Its primary focus is on advanced use of the product and it assumes an intermediate or advanced knowledge of the technology and terms. - </para> - - </abstract> - <corpauthor> - <inlinemediaobject> - <imageobject> - <imagedata fileref="Common_Content/images/title_logo.svg" format="SVG" /> - </imageobject> - - </inlinemediaobject> - - </corpauthor> - <!-- FOR PUBLICAN --> <xi:include href="Common_Content/Legal_Notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude"> <!-- FOR JDOCBOOK: --> <xi:fallback xmlns:xi="http://www.w3.org/2001/XInclude"> <xi:include href="fallback_content/Legal_Notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - </xi:fallback> - </xi:include> - <xi:include href="Author_Group.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> -</bookinfo> - Copied: epp/docs/branches/5.2/Reference_Guide/en-US/Book_Info.xml (from rev 8139, epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/Book_Info.xml) =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/Book_Info.xml (rev 0) +++ epp/docs/branches/5.2/Reference_Guide/en-US/Book_Info.xml 2011-11-25 00:48:53 UTC (rev 8141) @@ -0,0 +1,33 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE bookinfo 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_eXo_JCR_1.14.ent"> +%BOOK_ENTITIES; +]> +<bookinfo id="book-Reference_Guide_eXo_JCR_1.14-Reference_Guide_eXo_JCR_1.14"> + <title>Reference Guide eXo JCR 1.14</title> + <subtitle>An in-depth guide to Enterprise Portal Platform &VZ;</subtitle> + <productname>JBoss Enterprise Portal Platform</productname> + <productnumber>5.2</productnumber> + <edition>5.2.0</edition> + <pubsnumber>9</pubsnumber> + <abstract> + <para> + This Reference Guide is a high-level usage document. It deals with more advanced topics than the Installation and User Guides, adding new content or taking concepts discussed in the earlier documents further. It aims to provide supporting documentation for advanced users of the JBoss Enterprise Portal Platform product. Its primary focus is on advanced use of the product and it assumes an intermediate or advanced knowledge of the technology and terms. + </para> + + </abstract> + <corpauthor> + <inlinemediaobject> + <imageobject> + <imagedata fileref="Common_Content/images/title_logo.svg" format="SVG" /> + </imageobject> + + </inlinemediaobject> + + </corpauthor> + <!-- FOR PUBLICAN --> <xi:include href="Common_Content/Legal_Notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude"> <!-- FOR JDOCBOOK: --> <xi:fallback xmlns:xi="http://www.w3.org/2001/XInclude"> <xi:include href="fallback_content/Legal_Notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + </xi:fallback> + </xi:include> + <xi:include href="Author_Group.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> +</bookinfo> + Deleted: epp/docs/branches/5.2/Reference_Guide/en-US/Revision_History.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/Revision_History.xml 2011-11-24 17:26:22 UTC (rev 8138) +++ epp/docs/branches/5.2/Reference_Guide/en-US/Revision_History.xml 2011-11-25 00:48:53 UTC (rev 8141) @@ -1,141 +0,0 @@ -<?xml version='1.0' encoding='utf-8' ?> -<!DOCTYPE appendix 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_eXo_JCR_1.14.ent"> -%BOOK_ENTITIES; -]> -<appendix id="appe-Reference_Guide_eXo_JCR_1.14-Revision_History"> - <title>Revision History</title> - <simpara> - <revhistory> - <revision> - <revnumber>5.2.0-6</revnumber> - <date>Thu Nov 17 2011</date> - <author> - <firstname>Scott</firstname> - <surname>Mumford</surname> - <email></email> - - </author> - <revdescription> - <simplelist> - <member>Incorporated GateIn SSO updates.</member> - - </simplelist> - - </revdescription> - - </revision> - <revision> - <revnumber>5.2.0-5</revnumber> - <date>Tue Nov 15 2011</date> - <author> - <firstname>Scott</firstname> - <surname>Mumford</surname> - <email></email> - - </author> - <revdescription> - <simplelist> - <member>Staging for beta release.</member> - - </simplelist> - - </revdescription> - - </revision> - <revision> - <revnumber>5.2.0-4</revnumber> - <date>Wed Nov 9 2011</date> - <author> - <firstname>Scott</firstname> - <surname>Mumford</surname> - <email></email> - - </author> - <revdescription> - <simplelist> - <member>Republished for review/feedback.</member> - - </simplelist> - - </revdescription> - - </revision> - <revision> - <revnumber>5.2.0-3</revnumber> - <date>Wed Nov 2 2011</date> - <author> - <firstname>Scott</firstname> - <surname>Mumford</surname> - <email></email> - - </author> - <revdescription> - <simplelist> - <member>Staged for review of updated Foundations and eXo JCR content.</member> - - </simplelist> - - </revdescription> - - </revision> - <revision> - <revnumber>5.2.0-2</revnumber> - <date>Tue Sep 27 2011</date> - <author> - <firstname>Scott</firstname> - <surname>Mumford</surname> - <email></email> - - </author> - <revdescription> - <simplelist> - <member>Incorporated eXo JCR 1.14 documentation.</member> - - </simplelist> - - </revdescription> - - </revision> - <revision> - <revnumber>5.2.0-5</revnumber> - <date>Wed Sep 14 2011</date> - <author> - <firstname>Scott</firstname> - <surname>Mumford</surname> - <email></email> - - </author> - <revdescription> - <simplelist> - <member>Added Global Portlet Data section.</member> - - </simplelist> - - </revdescription> - - </revision> - <revision> - <revnumber>5.2.0-1</revnumber> - <date>Mon Aug 29 2011</date> - <author> - <firstname>Scott</firstname> - <surname>Mumford</surname> - <email></email> - - </author> - <revdescription> - <simplelist> - <member>Updating version and resetting pubs/ed numbers.</member> - - </simplelist> - - </revdescription> - - </revision> - - </revhistory> - - </simpara> -</appendix> - Copied: epp/docs/branches/5.2/Reference_Guide/en-US/Revision_History.xml (from rev 8139, epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/Revision_History.xml) =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/Revision_History.xml (rev 0) +++ epp/docs/branches/5.2/Reference_Guide/en-US/Revision_History.xml 2011-11-25 00:48:53 UTC (rev 8141) @@ -0,0 +1,171 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE appendix 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_eXo_JCR_1.14.ent"> +%BOOK_ENTITIES; +]> +<appendix id="appe-Reference_Guide_eXo_JCR_1.14-Revision_History"> + <title>Revision History</title> + <simpara> + <revhistory> + <revision> + <revnumber>5.2.0-9</revnumber> + <date>Fri Nov 25 2011</date> + <author> + <firstname>Scott</firstname> + <surname>Mumford</surname> + <email></email> + </author> + <revdescription> + <simplelist> + <member>Ported latest community WSRP content.</member> + </simplelist> + </revdescription> + </revision> + <revision> + <revnumber>5.2.0-8</revnumber> + <date>Thu Nov 24 2011</date> + <author> + <firstname>Scott</firstname> + <surname>Mumford</surname> + <email></email> + </author> + <revdescription> + <simplelist> + <member>Finalized first edit pass of eXoJCR content.</member> + <member>Moved eXoJCR section to Part IV.</member> + <member>Clean element ids and fix broken linkends.</member> + </simplelist> + </revdescription> + </revision> + <revision> + <revnumber>5.2.0-6</revnumber> + <date>Thu Nov 17 2011</date> + <author> + <firstname>Scott</firstname> + <surname>Mumford</surname> + <email></email> + + </author> + <revdescription> + <simplelist> + <member>Incorporated GateIn SSO updates.</member> + + </simplelist> + + </revdescription> + + </revision> + <revision> + <revnumber>5.2.0-5</revnumber> + <date>Tue Nov 15 2011</date> + <author> + <firstname>Scott</firstname> + <surname>Mumford</surname> + <email></email> + + </author> + <revdescription> + <simplelist> + <member>Staging for beta release.</member> + + </simplelist> + + </revdescription> + + </revision> + <revision> + <revnumber>5.2.0-4</revnumber> + <date>Wed Nov 9 2011</date> + <author> + <firstname>Scott</firstname> + <surname>Mumford</surname> + <email></email> + + </author> + <revdescription> + <simplelist> + <member>Republished for review/feedback.</member> + + </simplelist> + + </revdescription> + + </revision> + <revision> + <revnumber>5.2.0-3</revnumber> + <date>Wed Nov 2 2011</date> + <author> + <firstname>Scott</firstname> + <surname>Mumford</surname> + <email></email> + + </author> + <revdescription> + <simplelist> + <member>Staged for review of updated Foundations and eXo JCR content.</member> + + </simplelist> + + </revdescription> + + </revision> + <revision> + <revnumber>5.2.0-2</revnumber> + <date>Tue Sep 27 2011</date> + <author> + <firstname>Scott</firstname> + <surname>Mumford</surname> + <email></email> + + </author> + <revdescription> + <simplelist> + <member>Incorporated eXo JCR 1.14 documentation.</member> + + </simplelist> + + </revdescription> + + </revision> + <revision> + <revnumber>5.2.0-5</revnumber> + <date>Wed Sep 14 2011</date> + <author> + <firstname>Scott</firstname> + <surname>Mumford</surname> + <email></email> + + </author> + <revdescription> + <simplelist> + <member>Added Global Portlet Data section.</member> + + </simplelist> + + </revdescription> + + </revision> + <revision> + <revnumber>5.2.0-1</revnumber> + <date>Mon Aug 29 2011</date> + <author> + <firstname>Scott</firstname> + <surname>Mumford</surname> + <email></email> + + </author> + <revdescription> + <simplelist> + <member>Updating version and resetting pubs/ed numbers.</member> + + </simplelist> + + </revdescription> + + </revision> + + </revhistory> + + </simpara> +</appendix> + Deleted: epp/docs/branches/5.2/Reference_Guide/en-US/images/WSRP/config_self.png =================================================================== (Binary files differ) Copied: epp/docs/branches/5.2/Reference_Guide/en-US/images/WSRP/config_self.png (from rev 8139, epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/images/WSRP/config_self.png) =================================================================== (Binary files differ) Deleted: epp/docs/branches/5.2/Reference_Guide/en-US/images/WSRP/modify_reg_end.png =================================================================== (Binary files differ) Copied: epp/docs/branches/5.2/Reference_Guide/en-US/images/WSRP/modify_reg_end.png (from rev 8139, epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/images/WSRP/modify_reg_end.png) =================================================================== (Binary files differ) Deleted: epp/docs/branches/5.2/Reference_Guide/en-US/images/WSRP/modify_reg_self_end.png =================================================================== (Binary files differ) Copied: epp/docs/branches/5.2/Reference_Guide/en-US/images/WSRP/modify_reg_self_end.png (from rev 8139, epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/images/WSRP/modify_reg_self_end.png) =================================================================== (Binary files differ) Deleted: epp/docs/branches/5.2/Reference_Guide/en-US/modules/Advanced/Foundations/Configuring_Services.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/Foundations/Configuring_Services.xml 2011-11-24 17:26:22 UTC (rev 8138) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/Advanced/Foundations/Configuring_Services.xml 2011-11-25 00:48:53 UTC (rev 8141) @@ -1,913 +0,0 @@ -<?xml version='1.0' encoding='utf-8' ?> -<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -<!ENTITY % BOOK_ENTITIES SYSTEM "Reference_Guide_eXo_JCR_1.14.ent"> -%BOOK_ENTITIES; -]> -<section id="sect-Reference_Guide_eXo_JCR_1.14-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>, therefore you create a first simple configuration file. Copy the following code to a file called "configuration.xml" and place this file in a /conf subdirectory of your service base folder. As you already know the container looks for a "/conf/configuration.xml" file in each jar-file. - </para> - <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. 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 contain configuration in <filename><replaceable>JBOSS_HOME</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/configuration.xml</filename>, and will also have their services configured in the <literal>PortalContainer</literal> scope. - </para> - <para> - 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_eXo_JCR_1.14-Configuring_Services-Configuration_syntax"> - <title>Configuration syntax</title> - <section id="sect-Reference_Guide_eXo_JCR_1.14-Configuration_syntax-Components"> - <title>Components</title> - <para> - A service component is defined in <filename>configuration.xml</filename> by using a <emphasis role="bold">&lt;component&gt;</emphasis> element. - </para> - <para> - Only one piece of information is required when defining a service; the service implementation class. This is specified using <literal>&lt;type&gt;</literal> - </para> - <para> - Every component has a <literal>&lt;key&gt;</literal> that identifies it. If not explicitly set, a key defaults to the value of <literal>&lt;type&gt;</literal>. If a key can be loaded as a class, a class object is used as a key, otherwise a string is used. - </para> - <para> - The usual approach is to specify an interface as a key. - </para> - -<programlisting language="XML" role="XML"><xi:include href="../../../extras/Advanced_Development_Foundations/default.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <para> - The configuration you find inside the jar file is considered as the default configuration. If you want to override this default configuration you can do it in different places outside the jar. When the container finds several configurations for the same service, the configuration which is found later replaces completely the one found previously. Let's call this the <emphasis>configuration override mechanism</emphasis>. - </para> - <para> - After deploying you find the configuration.xml file in webapps/portal/WEB-INF/conf Use component registration tags. Let's look at the key tag that defines the interface and the type tag that defines the implementation. Note that the key tag is not mandatory, but it improves performance. - </para> - -<programlisting language="XML" role="XML">&lt;!-- Portlet container hooks --&gt; - &lt;component&gt; - &lt;key&gt;org.exoplatform.services.portletcontainer.persistence.PortletPreferencesPersister&lt;/key&gt; - &lt;type&gt;org.exoplatform.services.portal.impl.PortletPreferencesPersisterImpl&lt;/type&gt; - &lt;/component&gt;</programlisting> - <para> - Register plugins that can act as listeners or external plugin to bundle some plugin classes in other jar modules. The usual example is the hibernate service to which we can add hbm mapping files even if those are deployed in an other maven artifact. - </para> - -<programlisting language="XML" role="XML">&lt;external-component-plugins&gt; - &lt;target-component&gt;org.exoplatform.services.database.HibernateService&lt;/target-component&gt; - &lt;component-plugin&gt; - &lt;name&gt;add.hibernate.mapping&lt;/name&gt; - &lt;set-method&gt;addPlugin&lt;/set-method&gt; - &lt;type&gt;org.exoplatform.services.database.impl.AddHibernateMappingPlugin&lt;/type&gt; - &lt;init-params&gt; - &lt;values-param&gt; - &lt;name&gt;hibernate.mapping&lt;/name&gt; - &lt;value&gt;org/exoplatform/services/portal/impl/PortalConfigData.hbm.xml&lt;/value&gt; - &lt;value&gt;org/exoplatform/services/portal/impl/PageData.hbm.xml&lt;/value&gt; - &lt;value&gt;org/exoplatform/services/portal/impl/NodeNavigationData.hbm.xml&lt;/value&gt; - &lt;/values-param&gt; - &lt;/init-params&gt; - &lt;/component-plugin&gt; -&lt;/external-component-plugins&gt;</programlisting> - <para> - In that sample we target the HibernateService and we will call its addPlugin() method with an argument of the type AddHibernateMappingPlugin. That object will first have been filled with the init parameters. - </para> - <para> - Therefore, it is possible to define services that will be able to receive plugins without implementing any framework interface. - </para> - <para> - Another example of use is the case of listeners as in the following code where a listener is added to the OrganisationService and will be called each time a new user is created: - </para> - -<programlisting language="XML" role="XML">&lt;external-component-plugins&gt; - &lt;target-component&gt;org.exoplatform.services.organization.OrganizationService&lt;/target-component&gt; - &lt;component-plugin&gt; - &lt;name&gt;portal.new.user.event.listener&lt;/name&gt; - &lt;set-method&gt;addListenerPlugin&lt;/set-method&gt; - &lt;type&gt;org.exoplatform.services.portal.impl.PortalUserEventListenerImpl&lt;/type&gt; - &lt;description&gt;this listener create the portal configuration for the new user&lt;/description&gt; - &lt;init-params&gt; - &lt;object-param&gt; - &lt;name&gt;configuration&lt;/name&gt; - &lt;description&gt;description&lt;/description&gt; - &lt;object type="org.exoplatform.services.portal.impl.NewPortalConfig"&gt; - &lt;field name="predefinedUser"&gt; - &lt;collection type="java.util.HashSet"&gt; - &lt;value&gt;&lt;string&gt;admin&lt;/string&gt;&lt;/value&gt; - &lt;value&gt;&lt;string&gt;exo&lt;/string&gt;&lt;/value&gt; - &lt;value&gt;&lt;string&gt;company&lt;/string&gt;&lt;/value&gt; - &lt;value&gt;&lt;string&gt;community&lt;/string&gt;&lt;/value&gt; - &lt;value&gt;&lt;string&gt;portal&lt;/string&gt;&lt;/value&gt; - &lt;value&gt;&lt;string&gt;exotest&lt;/string&gt;&lt;/value&gt; - &lt;/collection&gt; - &lt;/field&gt; - &lt;field name="templateUser"&gt;&lt;string&gt;template&lt;/string&gt;&lt;/field&gt; - &lt;field name="templateLocation"&gt;&lt;string&gt;war:/conf/users&lt;/string&gt;&lt;/field&gt; - &lt;/object&gt; - &lt;/object-param&gt; - &lt;/init-params&gt; - &lt;/component-plugin&gt; -...</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_eXo_JCR_1.14-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> - <emphasis role="bold">HashTable</emphasis> The <classname>RootContainer</classname> creates a java <classname>HashTable</classname> which contains key-value pairs for the services. The qualified interface name of each service is used as key for the hashtable. Hopefully you still remember that the <parameter>&lt;key&gt;</parameter> tag of the configuration file contains the interface name? The value of each hashtable pair is an object that contains the service configuration (yes, this means the whole structure between the <parameter>&lt;component&gt;</parameter> tags of your <filename>configuration.xml</filename> file). - </para> - <para> - The <classname>RootContainer</classname> runs over all jar files you find in <emphasis>exo-tomcat/lib</emphasis> and looks if there is a configuration file at <emphasis>/conf/configuration.xml</emphasis>, the services configured in this file are added to the hashtable. That way - at the end of this process - the default configurations for all services are stored in the hashtable. - </para> - <note> - <para> - What happens if the same service - recognized by the same qualified interface name - is configured in different jars? As the service only can exist one time the configuration of the jar found later overrides the previous configuration. You know that the loading <emphasis role="bold">order of the jars is unpredictable</emphasis> you <emphasis role="bold">must not depend on this</emphasis>. - </para> - - </note> - <para> - If you wish to provide your own configurations for one or several services, you can do it in a general configuration file that has to be placed at <emphasis>exo-tomcat/exo-conf/configuration.xml</emphasis>. Do not search for such a file on your computer - you won't find one, because this option is not used in the default installation. Here again the same rule applies: <emphasis>The posterior configuration replaces the previous one</emphasis>. - </para> - <para> - The further configuration retrieval depends on the container type. - </para> - - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-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> weppapp (folder <emphasis>/WEB-INF/conf/configuration.xml</emphasis>) - </para> - - </listitem> - <listitem> - <para> - External configuration for services of a named portal, it will be found at <emphasis>exo-tomcat/exo-conf/portal/$portal_name/configuration.xml</emphasis> (as of Portal 2.5) - </para> - - </listitem> - - </orderedlist> - <para> - You see, here the <emphasis>/conf/portal/configuration.xml</emphasis> file of each jar enters the game, they are searched at first. Next, there is nearly always a configuration.xml in the portal.war file (or in the portal webapp folder), you find this file at <emphasis>/WEB-INF/conf/configuration.xml</emphasis>. If you open it, you will find a lot of import statements that point to other configuration files in the same portal.war (or portal webapp). - </para> - <para> - <emphasis role="bold">Multiple Portals</emphasis> Be aware that you might set up several different portals ("admin", "mexico", etc.), and each of these portals will use a different PortalContainer. And each of these PortalContainers can be configured separately. As of eXo Portal 2.5 you also will be able to provide configurations from outside the jars and wars or webapps. Put a configuration file in <emphasis>exo-tomcat/exo-conf/portal/$portal_name/configuration.xml</emphasis> where <parameter>$portal_name</parameter> is the name of the portal you want to configure for . But normally you only have one portal which is called "portal" so you use <emphasis>exo-tomcat/exo-conf/portal/portal/configuration.xml</emphasis>. - </para> - <note> - <para> - As of eXo Portal 2.5 you can override the external configuration location with the system property <emphasis>exo.conf.dir</emphasis>. If the property exists its value will be used as path to the eXo configuration directory, that means this is an alternative to <emphasis>exo-tomcat/exo-conf</emphasis>. Just put this property in the command line: <emphasis>java -Dexo.conf.dir=/path/to/exo/conf</emphasis> or use eXo.bat or eXo.sh. In this particular use case, you have no need to use any prefixes in your configuration file to import other files. For example, if your configuration file is <emphasis>exo-tomcat/exo-conf/portal/PORTAL_NAME/configuration.xml</emphasis> and you want to import the configuration file <emphasis>exo-tomcat/exo-conf/portal/PORTAL_NAME/mySubConfDir/myConfig.xml</emphasis>, you can do it by adding <emphasis>&lt;import&gt;mySubConfDir/myConfig.xml&lt;/import&gt;</emphasis> to your configuration file. - </para> - - </note> - <note> - <para> - Under <emphasis role="bold">JBoss</emphasis> application server <emphasis>exo-conf</emphasis> will be looked up in directory described by JBoss System property <emphasis>jboss.server.config.url</emphasis>. If the property is not found or empty <emphasis>exo-jboss/exo-conf</emphasis> will be asked (since kernel 2.0.4). - </para> - - </note> - - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-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 plugin is defined by using the <literal>&lt;external-component-plugin&gt;</literal> wrapper element which contains one or more <literal>&lt;component-plugin&gt;</literal> definitions. - </para> - <para> - The <literal>&lt;external-component-plugin&gt;</literal> element uses <literal>&lt;target-component&gt;</literal> to specify a target service component that will receive injected objects. - </para> - <para> - Every <literal>&lt;component-plugin&gt;</literal> defines an implementation type, and a method on the target component to use for injection (<literal>&lt;set-method&gt;</literal>). - </para> - <para> - A plugin implementation class has to implement the <emphasis role="bold">org.exoplatform.container.component. ComponentPlugin</emphasis> interface. - </para> - <para> - In the following example the <literal>PortalContainerDefinitionPlugin</literal> implements the <literal>ComponentPlugin</literal>: - </para> - -<programlisting language="XML" role="XML"><xi:include href="../../../extras/Advanced_Development_Foundations/default1.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <para> - The <emphasis role="bold">&lt;target-component&gt;</emphasis> defines the service for which the plugin is defined. The configuration is injected by the container using a method that is defined in <emphasis role="bold">&lt;set-method&gt;</emphasis>. The method has exactly one argument of the type org.exoplatform.services.cms.categories.impl.TaxonomyPlugin: - </para> - <itemizedlist> - <listitem> - <para> - addTaxonomyPlugin(org.exoplatform.services.cms.categories.impl.TaxonomyPlugin plugin) - </para> - - </listitem> - - </itemizedlist> - <para> - The content of <emphasis role="bold">&lt;init-params&gt;</emphasis> corresponds to the structure of the TaxonomyPlugin object. - </para> - <note> - <para> - 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_eXo_JCR_1.14-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.com... - </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_eXo_JCR_1.14-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_eXo_JCR_1.14-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> - <programlistingco> - <areaspec> - <area coords="6" id="area-Reference_Guide_eXo_JCR_1.14-Components-Includes_and_special_URLs-url_schema" /> - - </areaspec> - -<programlisting language="XML" role="XML"><xi:include href="../../../extras/Advanced_Development_Foundations/default2.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <calloutlist> - <callout arearefs="area-Reference_Guide_eXo_JCR_1.14-Components-Includes_and_special_URLs-url_schema"> - <para> - This line is being used to reference another configuration file. The <code>war:</code> URL schema indicates that the following path is to be resolved relative to the current <literal>PortalContainer</literal>'s servlet context resource path, starting with <emphasis role="bold">WEB-INF</emphasis> as a root. - </para> - - </callout> - - </calloutlist> - - </programlistingco> - - <note> - <para> - The current <literal>PortalContainer</literal> is really a newly created <literal>PortalContainer</literal>, as <code>war:</code> URLs only make sense for <literal>PortalContainer</literal> scoped configuration. - </para> - - </note> - <para> - 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_eXo_JCR_1.14-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 href="../../../extras/Advanced_Development_Foundations/default3.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - - </section> - - - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Configuration_syntax-InitParams_configuration_element"> - <title>InitParams configuration element</title> - <para> - <parameter>InitParams</parameter> is a configuration element that is essentially a map of key-value pairs, where <emphasis role="bold">key</emphasis> is always a <literal>String</literal>, and <emphasis role="bold">value</emphasis> can be any type that can be described using the kernel XML configuration. - </para> - <para> - Service components that form the JBoss Enterprise Portal Platform infrastructure use <parameter>InitParams</parameter> elements to configure themselves. A component can have one instance of <parameter>InitParams</parameter> injected at most. - </para> - <para> - If the service component's constructor takes <parameter>InitParams</parameter> as any of the parameters it will automatically be injected at component instantiation time. - </para> - <para> - The XML configuration for a service component that expects an <parameter>InitParams</parameter> element must have an <parameter>&lt;init-params&gt;</parameter> element present, however this element can be left empty. - </para> - <para> - Below is an example of how the kernel XML configuration syntax looks when creating <parameter>InitParams</parameter> instances: - </para> - -<programlisting language="XML" role="XML"><xi:include href="../../../extras/Advanced_Development_Foundations/default4.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <para> - An <parameter>InitParams</parameter> element description begins with an <parameter>&lt;init-params&gt;</parameter> element. - </para> - <para> - It can have zero or more children elements, each of which is one of the following: - </para> - <itemizedlist> - <listitem> - <para> - <parameter>&lt;value-param&gt;</parameter> - </para> - - </listitem> - <listitem> - <para> - <parameter>&lt;values-param&gt;</parameter> - </para> - - </listitem> - <listitem> - <para> - <parameter>&lt;properties-param&gt;</parameter> - </para> - - </listitem> - - </itemizedlist> - <para> - or - </para> - <itemizedlist> - <listitem> - <para> - <parameter>&lt;object-param&gt;</parameter> - </para> - - </listitem> - - </itemizedlist> - <para> - Each of these child elements takes a <parameter>&lt;name&gt;</parameter> that serves as a map entry key, and an optional <parameter>&lt;description&gt;</parameter>. It also takes a type-specific <emphasis role="bold">value</emphasis> specification. - </para> - <para> - The value specification for the <parameter>&lt;properties-param&gt;</parameter> defines one or more <parameter>&lt;property&gt;</parameter> elements, each of which specifies two strings; a property name and a property value. This is evident in the two previous examples. - </para> - <para> - Each <parameter>&lt;properties-params&gt;</parameter> defines one <literal>java.util.Properties</literal> instance. - </para> - <para> - The value specification for <parameter>&lt;value-param&gt;</parameter> elements is a <parameter>&lt;value&gt;</parameter> element which defines a <literal>String</literal> instance. - </para> - -<programlisting language="XML" role="XML"><xi:include href="../../../extras/Advanced_Development_Foundations/default5.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <para> - The value specification for <parameter>&lt;values-param&gt;</parameter> requires one or more <parameter>&lt;value&gt;</parameter> elements. Each <parameter>&lt;value&gt;</parameter> represents one <literal>String</literal> instance. All <literal>String</literal> values are then collected into a <literal>java.util.List</literal> instance. - </para> - -<programlisting language="XML" role="XML"><xi:include href="../../../extras/Advanced_Development_Foundations/default6.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <para> - For <parameter>&lt;object-param&gt;</parameter> entries, the value specification consists of an <parameter>&lt;object&gt;</parameter> element which is used for plain Java style object specification (specifying an implementation <emphasis>class - <parameter>&lt;type&gt;</parameter></emphasis>, and <emphasis>property values - <parameter>&lt;field&gt;</parameter></emphasis>). - </para> - <para> - The following section has an example of specifying a field of with a <literal>Collection</literal> type. - </para> - <para> - The <parameter>InitParams</parameter> structure (the names and types of entries) is specific for each service, as it is the code inside a service components' class that defines which entry names to look up and what types it expects to find. - </para> - <section id="sect-Reference_Guide_eXo_JCR_1.14-InitParams_configuration_element-Value_Param"> - <title>Value-Param</title> - <para> - There is an value-param example: - </para> - -<programlisting language="XML" role="XML"> &lt;component&gt; - &lt;key&gt;org.exoplatform.portal.config.UserACL&lt;/key&gt; - &lt;type&gt;org.exoplatform.portal.config.UserACL&lt;/type&gt; - &lt;init-params&gt; -... - &lt;value-param&gt; - &lt;name&gt;access.control.workspace&lt;/name&gt; - &lt;description&gt;groups with memberships that have the right to access the User Control Workspace&lt;/description&gt; - &lt;value&gt;*:/platform/administrators,*:/organization/management/executive-board&lt;/value&gt; - &lt;/value-param&gt; -... - &lt;/component&gt;</programlisting> - <para> - The UserACL class accesses to the <emphasis role="bold">value-param</emphasis> in its constructor. - </para> - -<programlisting language="Java" role="Java">package org.exoplatform.portal.config; -public class UserACL { - - public UserACL(InitParams params) { - UserACLMetaData md = new UserACLMetaData(); - ValueParam accessControlWorkspaceParam = params.getValueParam("access.control.workspace"); - if(accessControlWorkspaceParam != null) md.setAccessControlWorkspace(accessControlWorkspaceParam.getValue()); -...</programlisting> - - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-InitParams_configuration_element-Properties_Param"> - <title>Properties-Param</title> - <para> - Properties are name-value pairs. Both the name and the value are Java Strings. - </para> - <para> - Here you see the hibernate configuration example: - </para> - -<programlisting language="XML" role="XML"> &lt;component&gt; - &lt;key&gt;org.exoplatform.services.database.HibernateService&lt;/key&gt; - &lt;type&gt;org.exoplatform.services.database.impl.HibernateServiceImpl&lt;/type&gt; - &lt;init-params&gt; - &lt;properties-param&gt; - &lt;name&gt;hibernate.properties&lt;/name&gt; - &lt;description&gt;Default Hibernate Service&lt;/description&gt; - &lt;property name="hibernate.show_sql" value="false"/&gt; - &lt;property name="hibernate.cglib.use_reflection_optimizer" value="true"/&gt; - &lt;property name="hibernate.connection.url" value="jdbc:hsqldb:file:../temp/data/exodb"/&gt; - &lt;property name="hibernate.connection.driver_class" value="org.hsqldb.jdbcDriver"/&gt; -... - &lt;/properties-param&gt; - &lt;/init-params&gt; - &lt;/component&gt;</programlisting> - <para> - In the org.exoplatform.services.database.impl.HibernateServiceImpl you will find that the name "hibernate.properties" of the properties-param is used to access the properties. - </para> - -<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> - - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-InitParams_configuration_element-Object_Param"> - <title>Object-Param</title> - <para> - Let's have a look at the configuration of the LDAPService. It's not important to know LDAP, we only discuss the parameters. - </para> - -<programlisting language="XML" role="XML">&lt;component&gt; - &lt;key&gt;org.exoplatform.services.ldap.LDAPService&lt;/key&gt; - &lt;type&gt;org.exoplatform.services.ldap.impl.LDAPServiceImpl&lt;/type&gt; - &lt;init-params&gt; - &lt;object-param&gt; - &lt;name&gt;ldap.config&lt;/name&gt; - &lt;description&gt;Default ldap config&lt;/description&gt; - &lt;object type="org.exoplatform.services.ldap.impl.LDAPConnectionConfig"&gt; - &lt;field name="providerURL"&gt;&lt;string&gt;ldaps://10.0.0.3:636&lt;/string&gt;&lt;/field&gt; - &lt;field name="rootdn"&gt;&lt;string&gt;CN=Administrator,CN=Users,DC=exoplatform,DC=org&lt;/string&gt;&lt;/field&gt; - &lt;field name="password"&gt;&lt;string&gt;exo&lt;/string&gt;&lt;/field&gt; - &lt;field name="version"&gt;&lt;string&gt;3&lt;/string&gt;&lt;/field&gt; - &lt;field name="minConnection"&gt;&lt;int&gt;5&lt;/int&gt;&lt;/field&gt; - &lt;field name="maxConnection"&gt;&lt;int&gt;10&lt;/int&gt;&lt;/field&gt; - &lt;field name="referralMode"&gt;&lt;string&gt;ignore&lt;/string&gt;&lt;/field&gt; - &lt;field name="serverName"&gt;&lt;string&gt;active.directory&lt;/string&gt;&lt;/field&gt; - &lt;/object&gt; - &lt;/object-param&gt; - &lt;/init-params&gt; -&lt;/component&gt;</programlisting> - <para> - You see here an <emphasis role="bold">object-param</emphasis> is being used to pass the parameters inside an object (actually a java bean). It consists of a <emphasis role="bold">name</emphasis>, a <emphasis role="bold">description</emphasis> and exactly one <emphasis role="bold">object</emphasis>. The object defines the <emphasis role="bold">type</emphasis> and a number of <emphasis role="bold">fields</emphasis>. - </para> - <para> - Here you see how the service accesses the object: - </para> - -<programlisting 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...;. - </para> - - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-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"> &lt;component-plugin&gt; - &lt;name&gt;new.user.event.listener&lt;/name&gt; - &lt;set-method&gt;addListenerPlugin&lt;/set-method&gt; - &lt;type&gt;org.exoplatform.services.organization.impl.NewUserEventListener&lt;/type&gt; - &lt;description&gt;this listener assign group and membership to a new created user&lt;/description&gt; - &lt;init-params&gt; - &lt;object-param&gt; - &lt;name&gt;configuration&lt;/name&gt; - &lt;description&gt;description&lt;/description&gt; - &lt;object type="org.exoplatform.services.organization.impl.NewUserConfig"&gt; - &lt;field name="group"&gt; - &lt;collection type="java.util.ArrayList"&gt; - &lt;value&gt; - &lt;object type="org.exoplatform.services.organization.impl.NewUserConfig$JoinGroup"&gt; - &lt;field name="groupId"&gt;&lt;string&gt;/platform/users&lt;/string&gt;&lt;/field&gt; - &lt;field name="membership"&gt;&lt;string&gt;member&lt;/string&gt;&lt;/field&gt; - &lt;/object&gt; - &lt;/value&gt; - &lt;/collection&gt; - &lt;/field&gt; - &lt;field name="ignoredUser"&gt; - &lt;collection type="java.util.HashSet"&gt; - &lt;value&gt;&lt;string&gt;root&lt;/string&gt;&lt;/value&gt; - &lt;value&gt;&lt;string&gt;john&lt;/string&gt;&lt;/value&gt; - &lt;value&gt;&lt;string&gt;marry&lt;/string&gt;&lt;/value&gt; - &lt;value&gt;&lt;string&gt;demo&lt;/string&gt;&lt;/value&gt; - &lt;value&gt;&lt;string&gt;james&lt;/string&gt;&lt;/value&gt; - &lt;/collection&gt; - &lt;/field&gt; - &lt;/object&gt; - &lt;/object-param&gt; - &lt;/init-params&gt; - &lt;/component-plugin&gt;</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_eXo_JCR_1.14-Configuration_syntax-Component_Plugin_Priority"> - <title>Component Plugin Priority</title> - <para> - Since kernel version 2.0.6 it is possible to setup order of loading for ComponentPlugin. Use the ' <emphasis role="bold">priority</emphasis>' tag to define plugin's load priority. By <emphasis role="bold">default</emphasis> all plugins get <emphasis role="bold">priority '0'</emphasis>; they will be loaded in the container's natural way. If you want one plugin to be loaded later than the others then just set priority for it <emphasis role="bold">higher than zero</emphasis>. - </para> - <para> - Simple example of fragment of a <emphasis role="bold">configuration.xml</emphasis>. - </para> - -<programlisting language="XML" role="XML">... -&lt;component&gt; - &lt;type&gt;org.exoplatform.services.Component1&lt;/type&gt; -&lt;/component&gt; - -&lt;external-component-plugins&gt; - &lt;target-component&gt;org.exoplatform.services.Component1&lt;/target-component&gt; - - &lt;component-plugin&gt; - &lt;name&gt;Plugin1&lt;/name&gt; - &lt;set-method&gt;addPlugin&lt;/set-method&gt; - &lt;type&gt;org.exoplatform.services.plugins.Plugin1&lt;/type&gt; - &lt;description&gt;description&lt;/description&gt; - &lt;priority&gt;1&lt;/priority&gt; - &lt;/component-plugin&gt; - - &lt;component-plugin&gt; - &lt;name&gt;Plugin2&lt;/name&gt; - &lt;set-method&gt;addPlugin&lt;/set-method&gt; - &lt;type&gt;org.exoplatform.services.plugins.Plugin2&lt;/type&gt; - &lt;description&gt;description&lt;/description&gt; - &lt;priority&gt;2&lt;/priority&gt; - &lt;/component-plugin&gt; - -&lt;/external-component-plugins&gt; - -&lt;external-component-plugins&gt; - &lt;target-component&gt;org.exoplatform.services.Component1&lt;/target-component&gt; - &lt;component-plugin&gt; - &lt;name&gt;Plugin3&lt;/name&gt; - &lt;set-method&gt;addPlugin&lt;/set-method&gt; - &lt;type&gt;org.exoplatform.services.plugins.Plugin3&lt;/type&gt; - &lt;description&gt;description&lt;/description&gt; - &lt;/component-plugin&gt; -&lt;/external-component-plugins&gt; -...</programlisting> - <para> - In the above example plugin 'Plugin3' will be loaded first because it has the default priority '0'. Then, plugin 'Plugin1' will be loaded and last one is plugin 'Plugin2'. - </para> - - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-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_eXo_JCR_1.14-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 "portal/trunk/web/portal/src/main/webapp/WEB-INF/conf.configuration.xml" you will see that it consists only of imports: - </para> - -<programlisting language="XML" role="XML">&lt;import&gt;war:/conf/common/common-configuration.xml&lt;/import&gt; -&lt;import&gt;war:/conf/common/logs-configuration.xml&lt;/import&gt; -&lt;import&gt;war:/conf/database/database-configuration.xml&lt;/import&gt; -&lt;import&gt;war:/conf/jcr/jcr-configuration.xml&lt;/import&gt; -&lt;import&gt;war:/conf/common/portlet-container-configuration.xml&lt;/import&gt; -...</programlisting> - - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-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"> &lt;component&gt; - &lt;key&gt;org.exoplatform.services.database.HibernateService&lt;/key&gt; - &lt;jmx-name&gt;database:type=HibernateService&lt;/jmx-name&gt; - &lt;type&gt;org.exoplatform.services.database.impl.HibernateServiceImpl&lt;/type&gt; - &lt;init-params&gt; - &lt;properties-param&gt; - &lt;name&gt;hibernate.properties&lt;/name&gt; - &lt;description&gt;Default Hibernate Service&lt;/description&gt; -... - &lt;property name="hibernate.connection.url" value="${connectionUrl}"/&gt; - &lt;property name="hibernate.connection.driver_class" value="${driverClass}"/&gt; - &lt;property name="hibernate.connection.username" value="${username}"/&gt; - &lt;property name="hibernate.connection.password" value="${password}"/&gt; - &lt;property name="hibernate.dialect" value="${dialect}"/&gt; -... - &lt;/properties-param&gt; - &lt;/init-params&gt; - &lt;/component&gt;</programlisting> - <para> - As these are system properties you use the -D command: <emphasis role="bold">java -DconnectionUrl=jdbc:hsqldb:file:../temp/data/exodb -DdriverClass=org.hsqldb.jdbcDriver</emphasis> Or better use the parameters of eXo.bat / eXo.sh when you start eXo Portal: <emphasis role="bold">set EXO_OPTS="-DconnectionUrl=jdbc:hsqldb:file:../temp/data/exodb -DdriverClass=org.hsqldb.jdbcDriver"</emphasis> - </para> - - </section> - - - </section> - - -</section> - - Copied: epp/docs/branches/5.2/Reference_Guide/en-US/modules/Advanced/Foundations/Configuring_Services.xml (from rev 8139, epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/Foundations/Configuring_Services.xml) =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/Advanced/Foundations/Configuring_Services.xml (rev 0) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/Advanced/Foundations/Configuring_Services.xml 2011-11-25 00:48:53 UTC (rev 8141) @@ -0,0 +1,919 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "Reference_Guide_eXo_JCR_1.14.ent"> +%BOOK_ENTITIES; +]> +<section id="sect-Reference_Guide_eXo_JCR_1.14-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 fan 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>JBOSS_HOME</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/configuration.xml</filename>, and will also have their services configured in the <literal>PortalContainer</literal> scope. + </para> + <para> + 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_eXo_JCR_1.14-Configuring_Services-Configuration_syntax"> + <title>Configuration syntax</title> + <section id="sect-Reference_Guide_eXo_JCR_1.14-Configuration_syntax-Components"> + <title>Components</title> + <para> + A service component is defined in <filename>configuration.xml</filename> by using a <emphasis role="bold">&lt;component&gt;</emphasis> element. + </para> + <para> + Only one piece of information is required when defining a service; the service implementation class. This is specified using <literal>&lt;type&gt;</literal> + </para> + <para> + Every component has a <literal>&lt;key&gt;</literal> that identifies it. If not explicitly set, a key defaults to the value of <literal>&lt;type&gt;</literal>. If a key can be loaded as a class, a class object is used as a key, otherwise a string is used. + </para> + <para> + The usual approach is to specify an interface as a key. + </para> + +<programlisting language="XML" role="XML"><xi:include href="../../../extras/Advanced_Development_Foundations/default.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + <para> + The configuration found inside the jar file is considered as the default configuration. If you want to override this default configuration you can do it in different places outside the jar. When the container finds several configurations for the same service, the configuration which is found later replaces completely the one found previously. Let's call this the <emphasis>configuration override mechanism</emphasis>. + </para> + <para> + After deploying you find the configuration.xml file in webapps/portal/WEB-INF/conf Use component registration tags. Let's look at the key tag that defines the interface and the type tag that defines the implementation. Note that the key tag is not mandatory, but it improves performance. + </para> + +<programlisting language="XML" role="XML">&lt;!-- Portlet container hooks --&gt; + &lt;component&gt; + &lt;key&gt;org.exoplatform.services.portletcontainer.persistence.PortletPreferencesPersister&lt;/key&gt; + &lt;type&gt;org.exoplatform.services.portal.impl.PortletPreferencesPersisterImpl&lt;/type&gt; + &lt;/component&gt;</programlisting> + <para> + Register plugins that can act as listeners or external plugin to bundle some plugin classes in other jar modules. The usual example is the hibernate service to which we can add hbm mapping files even if those are deployed in an other maven artifact. + </para> + +<programlisting language="XML" role="XML">&lt;external-component-plugins&gt; + &lt;target-component&gt;org.exoplatform.services.database.HibernateService&lt;/target-component&gt; + &lt;component-plugin&gt; + &lt;name&gt;add.hibernate.mapping&lt;/name&gt; + &lt;set-method&gt;addPlugin&lt;/set-method&gt; + &lt;type&gt;org.exoplatform.services.database.impl.AddHibernateMappingPlugin&lt;/type&gt; + &lt;init-params&gt; + &lt;values-param&gt; + &lt;name&gt;hibernate.mapping&lt;/name&gt; + &lt;value&gt;org/exoplatform/services/portal/impl/PortalConfigData.hbm.xml&lt;/value&gt; + &lt;value&gt;org/exoplatform/services/portal/impl/PageData.hbm.xml&lt;/value&gt; + &lt;value&gt;org/exoplatform/services/portal/impl/NodeNavigationData.hbm.xml&lt;/value&gt; + &lt;/values-param&gt; + &lt;/init-params&gt; + &lt;/component-plugin&gt; +&lt;/external-component-plugins&gt;</programlisting> + <para> + In that sample we target the HibernateService and we will call its addPlugin() method with an argument of the type AddHibernateMappingPlugin. That object will first have been filled with the init parameters. + </para> + <para> + Therefore, it is possible to define services that will be able to receive plugins without implementing any framework interface. + </para> + <para> + Another example of use is the case of listeners as in the following code where a listener is added to the OrganisationService and will be called each time a new user is created: + </para> + +<programlisting language="XML" role="XML">&lt;external-component-plugins&gt; + &lt;target-component&gt;org.exoplatform.services.organization.OrganizationService&lt;/target-component&gt; + &lt;component-plugin&gt; + &lt;name&gt;portal.new.user.event.listener&lt;/name&gt; + &lt;set-method&gt;addListenerPlugin&lt;/set-method&gt; + &lt;type&gt;org.exoplatform.services.portal.impl.PortalUserEventListenerImpl&lt;/type&gt; + &lt;description&gt;this listener create the portal configuration for the new user&lt;/description&gt; + &lt;init-params&gt; + &lt;object-param&gt; + &lt;name&gt;configuration&lt;/name&gt; + &lt;description&gt;description&lt;/description&gt; + &lt;object type="org.exoplatform.services.portal.impl.NewPortalConfig"&gt; + &lt;field name="predefinedUser"&gt; + &lt;collection type="java.util.HashSet"&gt; + &lt;value&gt;&lt;string&gt;admin&lt;/string&gt;&lt;/value&gt; + &lt;value&gt;&lt;string&gt;exo&lt;/string&gt;&lt;/value&gt; + &lt;value&gt;&lt;string&gt;company&lt;/string&gt;&lt;/value&gt; + &lt;value&gt;&lt;string&gt;community&lt;/string&gt;&lt;/value&gt; + &lt;value&gt;&lt;string&gt;portal&lt;/string&gt;&lt;/value&gt; + &lt;value&gt;&lt;string&gt;exotest&lt;/string&gt;&lt;/value&gt; + &lt;/collection&gt; + &lt;/field&gt; + &lt;field name="templateUser"&gt;&lt;string&gt;template&lt;/string&gt;&lt;/field&gt; + &lt;field name="templateLocation"&gt;&lt;string&gt;war:/conf/users&lt;/string&gt;&lt;/field&gt; + &lt;/object&gt; + &lt;/object-param&gt; + &lt;/init-params&gt; + &lt;/component-plugin&gt; +...</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_eXo_JCR_1.14-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> + <emphasis role="bold">HashTable</emphasis> The <classname>RootContainer</classname> creates a java <classname>HashTable</classname> which contains key-value pairs for the services. The qualified interface name of each service is used as key for the hashtable. Hopefully you still remember that the <parameter>&lt;key&gt;</parameter> tag of the configuration file contains the interface name? The value of each hashtable pair is an object that contains the service configuration (yes, this means the whole structure between the <parameter>&lt;component&gt;</parameter> tags of your <filename>configuration.xml</filename> file). + </para> + <para> + The <classname>RootContainer</classname> runs over all jar files you find in <emphasis>exo-tomcat/lib</emphasis> and looks if there is a configuration file at <emphasis>/conf/configuration.xml</emphasis>, the services configured in this file are added to the hashtable. That way - at the end of this process - the default configurations for all services are stored in the hashtable. + </para> + <note> + <para> + What happens if the same service - recognized by the same qualified interface name - is configured in different jars? As the service only can exist one time the configuration of the jar found later overrides the previous configuration. You know that the loading <emphasis role="bold">order of the jars is unpredictable</emphasis> you <emphasis role="bold">must not depend on this</emphasis>. + </para> + + </note> + <para> + If you wish to provide your own configurations for one or several services, you can do it in a general configuration file that has to be placed at <emphasis>exo-tomcat/exo-conf/configuration.xml</emphasis>. Do not search for such a file on your computer - you won't find one, because this option is not used in the default installation. Here again the same rule applies: <emphasis>The posterior configuration replaces the previous one</emphasis>. + </para> + <para> + The further configuration retrieval depends on the container type. + </para> + + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-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> weppapp (folder <emphasis>/WEB-INF/conf/configuration.xml</emphasis>) + </para> + + </listitem> + <listitem> + <para> + External configuration for services of a named portal, it will be found at <emphasis>exo-tomcat/exo-conf/portal/$portal_name/configuration.xml</emphasis> (as of Portal 2.5) + </para> + + </listitem> + + </orderedlist> + <para> + You see, here the <emphasis>/conf/portal/configuration.xml</emphasis> file of each jar enters the game, they are searched at first. Next, there is nearly always a configuration.xml in the portal.war file (or in the portal webapp folder), you find this file at <emphasis>/WEB-INF/conf/configuration.xml</emphasis>. If you open it, you will find a lot of import statements that point to other configuration files in the same portal.war (or portal webapp). + </para> + <para> + <emphasis role="bold">Multiple Portals</emphasis> Be aware that you might set up several different portals ("admin", "mexico", etc.), and each of these portals will use a different PortalContainer. And each of these PortalContainers can be configured separately. As of eXo Portal 2.5 you also will be able to provide configurations from outside the jars and wars or webapps. Put a configuration file in <emphasis>exo-tomcat/exo-conf/portal/$portal_name/configuration.xml</emphasis> where <parameter>$portal_name</parameter> is the name of the portal you want to configure for . But normally you only have one portal which is called "portal" so you use <emphasis>exo-tomcat/exo-conf/portal/portal/configuration.xml</emphasis>. + </para> + <note> + <para> + As of eXo Portal 2.5 you can override the external configuration location with the system property <emphasis>exo.conf.dir</emphasis>. If the property exists its value will be used as path to the eXo configuration directory, that means this is an alternative to <emphasis>exo-tomcat/exo-conf</emphasis>. Just put this property in the command line: <emphasis>java -Dexo.conf.dir=/path/to/exo/conf</emphasis> or use eXo.bat or eXo.sh. In this particular use case, you have no need to use any prefixes in your configuration file to import other files. For example, if your configuration file is <emphasis>exo-tomcat/exo-conf/portal/PORTAL_NAME/configuration.xml</emphasis> and you want to import the configuration file <emphasis>exo-tomcat/exo-conf/portal/PORTAL_NAME/mySubConfDir/myConfig.xml</emphasis>, you can do it by adding <emphasis>&lt;import&gt;mySubConfDir/myConfig.xml&lt;/import&gt;</emphasis> to your configuration file. + </para> + + </note> + <note> + <para> + Under <emphasis role="bold">JBoss</emphasis> application server <emphasis>exo-conf</emphasis> will be looked up in directory described by JBoss System property <emphasis>jboss.server.config.url</emphasis>. If the property is not found or empty <emphasis>exo-jboss/exo-conf</emphasis> will be asked (since kernel 2.0.4). + </para> + + </note> + + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-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 plugin is defined by using the <literal>&lt;external-component-plugin&gt;</literal> wrapper element which contains one or more <literal>&lt;component-plugin&gt;</literal> definitions. + </para> + <para> + The <literal>&lt;external-component-plugin&gt;</literal> element uses <literal>&lt;target-component&gt;</literal> to specify a target service component that will receive injected objects. + </para> + <para> + Every <literal>&lt;component-plugin&gt;</literal> defines an implementation type, and a method on the target component to use for injection (<literal>&lt;set-method&gt;</literal>). + </para> + <para> + A plugin implementation class has to implement the <emphasis role="bold">org.exoplatform.container.component. ComponentPlugin</emphasis> interface. + </para> + <para> + In the following example the <literal>PortalContainerDefinitionPlugin</literal> implements the <literal>ComponentPlugin</literal>: + </para> + +<programlisting language="XML" role="XML"><xi:include href="../../../extras/Advanced_Development_Foundations/default1.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + <para> + The <emphasis role="bold">&lt;target-component&gt;</emphasis> defines the service for which the plugin is defined. The configuration is injected by the container using a method that is defined in <emphasis role="bold">&lt;set-method&gt;</emphasis>. The method has exactly one argument of the type org.exoplatform.services.cms.categories.impl.TaxonomyPlugin: + </para> + <itemizedlist> + <listitem> + <para> + addTaxonomyPlugin(org.exoplatform.services.cms.categories.impl.TaxonomyPlugin plugin) + </para> + + </listitem> + + </itemizedlist> + <para> + The content of <emphasis role="bold">&lt;init-params&gt;</emphasis> corresponds to the structure of the TaxonomyPlugin object. + </para> + <note> + <para> + 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_eXo_JCR_1.14-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.com... + </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_eXo_JCR_1.14-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_eXo_JCR_1.14-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> + <programlistingco> + <areaspec> + <area coords="6" id="area-Reference_Guide_eXo_JCR_1.14-Components-Includes_and_special_URLs-url_schema" /> + + </areaspec> + +<programlisting language="XML" role="XML"><xi:include href="../../../extras/Advanced_Development_Foundations/default2.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + <calloutlist> + <callout arearefs="area-Reference_Guide_eXo_JCR_1.14-Components-Includes_and_special_URLs-url_schema"> + <para> + This line is being used to reference another configuration file. The <code>war:</code> URL schema indicates that the following path is to be resolved relative to the current <literal>PortalContainer</literal>'s servlet context resource path, starting with <emphasis role="bold">WEB-INF</emphasis> as a root. + </para> + + </callout> + + </calloutlist> + + </programlistingco> + + <note> + <para> + The current <literal>PortalContainer</literal> is really a newly created <literal>PortalContainer</literal>, as <code>war:</code> URLs only make sense for <literal>PortalContainer</literal> scoped configuration. + </para> + + </note> + <para> + 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_eXo_JCR_1.14-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 href="../../../extras/Advanced_Development_Foundations/default3.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + + </section> + + + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Configuration_syntax-InitParams_configuration_element"> + <title>InitParams configuration element</title> + <para> + <parameter>InitParams</parameter> is a configuration element that is essentially a map of key-value pairs, where <emphasis role="bold">key</emphasis> is always a <literal>String</literal>, and <emphasis role="bold">value</emphasis> can be any type that can be described using the kernel XML configuration. + </para> + <para> + Service components that form the JBoss Enterprise Portal Platform infrastructure use <parameter>InitParams</parameter> elements to configure themselves. A component can have one instance of <parameter>InitParams</parameter> injected at most. + </para> + <para> + If the service component's constructor takes <parameter>InitParams</parameter> as any of the parameters it will automatically be injected at component instantiation time. + </para> + <para> + The XML configuration for a service component that expects an <parameter>InitParams</parameter> element must have an <parameter>&lt;init-params&gt;</parameter> element present, however this element can be left empty. + </para> + <para> + Below is an example of how the kernel XML configuration syntax looks when creating <parameter>InitParams</parameter> instances: + </para> + +<programlisting language="XML" role="XML"><xi:include href="../../../extras/Advanced_Development_Foundations/default4.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + <para> + An <parameter>InitParams</parameter> element description begins with an <parameter>&lt;init-params&gt;</parameter> element. + </para> + <para> + It can have zero or more children elements, each of which is one of the following: + </para> + <itemizedlist> + <listitem> + <para> + <parameter>&lt;value-param&gt;</parameter> + </para> + + </listitem> + <listitem> + <para> + <parameter>&lt;values-param&gt;</parameter> + </para> + + </listitem> + <listitem> + <para> + <parameter>&lt;properties-param&gt;</parameter> + </para> + + </listitem> + + </itemizedlist> + <para> + or + </para> + <itemizedlist> + <listitem> + <para> + <parameter>&lt;object-param&gt;</parameter> + </para> + + </listitem> + + </itemizedlist> + <para> + Each of these child elements takes a <parameter>&lt;name&gt;</parameter> that serves as a map entry key, and an optional <parameter>&lt;description&gt;</parameter>. It also takes a type-specific <emphasis role="bold">value</emphasis> specification. + </para> + <para> + The value specification for the <parameter>&lt;properties-param&gt;</parameter> defines one or more <parameter>&lt;property&gt;</parameter> elements, each of which specifies two strings; a property name and a property value. This is evident in the two previous examples. + </para> + <para> + Each <parameter>&lt;properties-params&gt;</parameter> defines one <literal>java.util.Properties</literal> instance. + </para> + <para> + The value specification for <parameter>&lt;value-param&gt;</parameter> elements is a <parameter>&lt;value&gt;</parameter> element which defines a <literal>String</literal> instance. + </para> + +<programlisting language="XML" role="XML"><xi:include href="../../../extras/Advanced_Development_Foundations/default5.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + <para> + The value specification for <parameter>&lt;values-param&gt;</parameter> requires one or more <parameter>&lt;value&gt;</parameter> elements. Each <parameter>&lt;value&gt;</parameter> represents one <literal>String</literal> instance. All <literal>String</literal> values are then collected into a <literal>java.util.List</literal> instance. + </para> + +<programlisting language="XML" role="XML"><xi:include href="../../../extras/Advanced_Development_Foundations/default6.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + <para> + For <parameter>&lt;object-param&gt;</parameter> entries, the value specification consists of an <parameter>&lt;object&gt;</parameter> element which is used for plain Java style object specification (specifying an implementation <emphasis>class - <parameter>&lt;type&gt;</parameter></emphasis>, and <emphasis>property values - <parameter>&lt;field&gt;</parameter></emphasis>). + </para> + <para> + The following section has an example of specifying a field of with a <literal>Collection</literal> type. + </para> + <para> + The <parameter>InitParams</parameter> structure (the names and types of entries) is specific for each service, as it is the code inside a service components' class that defines which entry names to look up and what types it expects to find. + </para> + <section id="sect-Reference_Guide_eXo_JCR_1.14-InitParams_configuration_element-Value_Param"> + <title>Value-Param</title> + <para> + There is an value-param example: + </para> + +<programlisting language="XML" role="XML"> &lt;component&gt; + &lt;key&gt;org.exoplatform.portal.config.UserACL&lt;/key&gt; + &lt;type&gt;org.exoplatform.portal.config.UserACL&lt;/type&gt; + &lt;init-params&gt; +... + &lt;value-param&gt; + &lt;name&gt;access.control.workspace&lt;/name&gt; + &lt;description&gt;groups with memberships that have the right to access the User Control Workspace&lt;/description&gt; + &lt;value&gt;*:/platform/administrators,*:/organization/management/executive-board&lt;/value&gt; + &lt;/value-param&gt; +... + &lt;/component&gt;</programlisting> + <para> + The UserACL class accesses to the <emphasis role="bold">value-param</emphasis> in its constructor. + </para> + +<programlisting language="Java" role="Java">package org.exoplatform.portal.config; +public class UserACL { + + public UserACL(InitParams params) { + UserACLMetaData md = new UserACLMetaData(); + ValueParam accessControlWorkspaceParam = params.getValueParam("access.control.workspace"); + if(accessControlWorkspaceParam != null) md.setAccessControlWorkspace(accessControlWorkspaceParam.getValue()); +...</programlisting> + + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-InitParams_configuration_element-Properties_Param"> + <title>Properties-Param</title> + <para> + Properties are name-value pairs. Both the name and the value are Java Strings. + </para> + <para> + Here you see the hibernate configuration example: + </para> + +<programlisting language="XML" role="XML"> &lt;component&gt; + &lt;key&gt;org.exoplatform.services.database.HibernateService&lt;/key&gt; + &lt;type&gt;org.exoplatform.services.database.impl.HibernateServiceImpl&lt;/type&gt; + &lt;init-params&gt; + &lt;properties-param&gt; + &lt;name&gt;hibernate.properties&lt;/name&gt; + &lt;description&gt;Default Hibernate Service&lt;/description&gt; + &lt;property name="hibernate.show_sql" value="false"/&gt; + &lt;property name="hibernate.cglib.use_reflection_optimizer" value="true"/&gt; + &lt;property name="hibernate.connection.url" value="jdbc:hsqldb:file:../temp/data/exodb"/&gt; + &lt;property name="hibernate.connection.driver_class" value="org.hsqldb.jdbcDriver"/&gt; +... + &lt;/properties-param&gt; + &lt;/init-params&gt; + &lt;/component&gt;</programlisting> + <para> + In the org.exoplatform.services.database.impl.HibernateServiceImpl you will find that the name "hibernate.properties" of the properties-param is used to access the properties. + </para> + +<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> + + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-InitParams_configuration_element-Object_Param"> + <title>Object-Param</title> + <para> + Let's have a look at the configuration of the LDAPService. It's not important to know LDAP, we only discuss the parameters. + </para> + +<programlisting language="XML" role="XML">&lt;component&gt; + &lt;key&gt;org.exoplatform.services.ldap.LDAPService&lt;/key&gt; + &lt;type&gt;org.exoplatform.services.ldap.impl.LDAPServiceImpl&lt;/type&gt; + &lt;init-params&gt; + &lt;object-param&gt; + &lt;name&gt;ldap.config&lt;/name&gt; + &lt;description&gt;Default ldap config&lt;/description&gt; + &lt;object type="org.exoplatform.services.ldap.impl.LDAPConnectionConfig"&gt; + &lt;field name="providerURL"&gt;&lt;string&gt;ldaps://10.0.0.3:636&lt;/string&gt;&lt;/field&gt; + &lt;field name="rootdn"&gt;&lt;string&gt;CN=Administrator,CN=Users,DC=exoplatform,DC=org&lt;/string&gt;&lt;/field&gt; + &lt;field name="password"&gt;&lt;string&gt;exo&lt;/string&gt;&lt;/field&gt; + &lt;field name="version"&gt;&lt;string&gt;3&lt;/string&gt;&lt;/field&gt; + &lt;field name="minConnection"&gt;&lt;int&gt;5&lt;/int&gt;&lt;/field&gt; + &lt;field name="maxConnection"&gt;&lt;int&gt;10&lt;/int&gt;&lt;/field&gt; + &lt;field name="referralMode"&gt;&lt;string&gt;ignore&lt;/string&gt;&lt;/field&gt; + &lt;field name="serverName"&gt;&lt;string&gt;active.directory&lt;/string&gt;&lt;/field&gt; + &lt;/object&gt; + &lt;/object-param&gt; + &lt;/init-params&gt; +&lt;/component&gt;</programlisting> + <para> + You see here an <emphasis role="bold">object-param</emphasis> is being used to pass the parameters inside an object (actually a java bean). It consists of a <emphasis role="bold">name</emphasis>, a <emphasis role="bold">description</emphasis> and exactly one <emphasis role="bold">object</emphasis>. The object defines the <emphasis role="bold">type</emphasis> and a number of <emphasis role="bold">fields</emphasis>. + </para> + <para> + Here you see how the service accesses the object: + </para> + +<programlisting 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...;. + </para> + + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-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"> &lt;component-plugin&gt; + &lt;name&gt;new.user.event.listener&lt;/name&gt; + &lt;set-method&gt;addListenerPlugin&lt;/set-method&gt; + &lt;type&gt;org.exoplatform.services.organization.impl.NewUserEventListener&lt;/type&gt; + &lt;description&gt;this listener assign group and membership to a new created user&lt;/description&gt; + &lt;init-params&gt; + &lt;object-param&gt; + &lt;name&gt;configuration&lt;/name&gt; + &lt;description&gt;description&lt;/description&gt; + &lt;object type="org.exoplatform.services.organization.impl.NewUserConfig"&gt; + &lt;field name="group"&gt; + &lt;collection type="java.util.ArrayList"&gt; + &lt;value&gt; + &lt;object type="org.exoplatform.services.organization.impl.NewUserConfig$JoinGroup"&gt; + &lt;field name="groupId"&gt;&lt;string&gt;/platform/users&lt;/string&gt;&lt;/field&gt; + &lt;field name="membership"&gt;&lt;string&gt;member&lt;/string&gt;&lt;/field&gt; + &lt;/object&gt; + &lt;/value&gt; + &lt;/collection&gt; + &lt;/field&gt; + &lt;field name="ignoredUser"&gt; + &lt;collection type="java.util.HashSet"&gt; + &lt;value&gt;&lt;string&gt;root&lt;/string&gt;&lt;/value&gt; + &lt;value&gt;&lt;string&gt;john&lt;/string&gt;&lt;/value&gt; + &lt;value&gt;&lt;string&gt;marry&lt;/string&gt;&lt;/value&gt; + &lt;value&gt;&lt;string&gt;demo&lt;/string&gt;&lt;/value&gt; + &lt;value&gt;&lt;string&gt;james&lt;/string&gt;&lt;/value&gt; + &lt;/collection&gt; + &lt;/field&gt; + &lt;/object&gt; + &lt;/object-param&gt; + &lt;/init-params&gt; + &lt;/component-plugin&gt;</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_eXo_JCR_1.14-Configuration_syntax-Component_Plugin_Priority"> + <title>Component Plugin Priority</title> + <para> + Since kernel version 2.0.6 it is possible to setup order of loading for ComponentPlugin. Use the ' <emphasis role="bold">priority</emphasis>' tag to define plugin's load priority. By <emphasis role="bold">default</emphasis> all plugins get <emphasis role="bold">priority '0'</emphasis>; they will be loaded in the container's natural way. If you want one plugin to be loaded later than the others then just set priority for it <emphasis role="bold">higher than zero</emphasis>. + </para> + <para> + Simple example of fragment of a <emphasis role="bold">configuration.xml</emphasis>. + </para> + +<programlisting language="XML" role="XML">... +&lt;component&gt; + &lt;type&gt;org.exoplatform.services.Component1&lt;/type&gt; +&lt;/component&gt; + +&lt;external-component-plugins&gt; + &lt;target-component&gt;org.exoplatform.services.Component1&lt;/target-component&gt; + + &lt;component-plugin&gt; + &lt;name&gt;Plugin1&lt;/name&gt; + &lt;set-method&gt;addPlugin&lt;/set-method&gt; + &lt;type&gt;org.exoplatform.services.plugins.Plugin1&lt;/type&gt; + &lt;description&gt;description&lt;/description&gt; + &lt;priority&gt;1&lt;/priority&gt; + &lt;/component-plugin&gt; + + &lt;component-plugin&gt; + &lt;name&gt;Plugin2&lt;/name&gt; + &lt;set-method&gt;addPlugin&lt;/set-method&gt; + &lt;type&gt;org.exoplatform.services.plugins.Plugin2&lt;/type&gt; + &lt;description&gt;description&lt;/description&gt; + &lt;priority&gt;2&lt;/priority&gt; + &lt;/component-plugin&gt; + +&lt;/external-component-plugins&gt; + +&lt;external-component-plugins&gt; + &lt;target-component&gt;org.exoplatform.services.Component1&lt;/target-component&gt; + &lt;component-plugin&gt; + &lt;name&gt;Plugin3&lt;/name&gt; + &lt;set-method&gt;addPlugin&lt;/set-method&gt; + &lt;type&gt;org.exoplatform.services.plugins.Plugin3&lt;/type&gt; + &lt;description&gt;description&lt;/description&gt; + &lt;/component-plugin&gt; +&lt;/external-component-plugins&gt; +...</programlisting> + <para> + In the above example plugin 'Plugin3' will be loaded first because it has the default priority '0'. Then, plugin 'Plugin1' will be loaded and last one is plugin 'Plugin2'. + </para> + + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-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_eXo_JCR_1.14-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 "portal/trunk/web/portal/src/main/webapp/WEB-INF/conf.configuration.xml" you will see that it consists only of imports: + </para> + +<programlisting language="XML" role="XML">&lt;import&gt;war:/conf/common/common-configuration.xml&lt;/import&gt; +&lt;import&gt;war:/conf/common/logs-configuration.xml&lt;/import&gt; +&lt;import&gt;war:/conf/database/database-configuration.xml&lt;/import&gt; +&lt;import&gt;war:/conf/jcr/jcr-configuration.xml&lt;/import&gt; +&lt;import&gt;war:/conf/common/portlet-container-configuration.xml&lt;/import&gt; +...</programlisting> + + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-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"> &lt;component&gt; + &lt;key&gt;org.exoplatform.services.database.HibernateService&lt;/key&gt; + &lt;jmx-name&gt;database:type=HibernateService&lt;/jmx-name&gt; + &lt;type&gt;org.exoplatform.services.database.impl.HibernateServiceImpl&lt;/type&gt; + &lt;init-params&gt; + &lt;properties-param&gt; + &lt;name&gt;hibernate.properties&lt;/name&gt; + &lt;description&gt;Default Hibernate Service&lt;/description&gt; +... + &lt;property name="hibernate.connection.url" value="${connectionUrl}"/&gt; + &lt;property name="hibernate.connection.driver_class" value="${driverClass}"/&gt; + &lt;property name="hibernate.connection.username" value="${username}"/&gt; + &lt;property name="hibernate.connection.password" value="${password}"/&gt; + &lt;property name="hibernate.dialect" value="${dialect}"/&gt; +... + &lt;/properties-param&gt; + &lt;/init-params&gt; + &lt;/component&gt;</programlisting> + <para> + As these are system properties you use the -D command: <emphasis role="bold">java -DconnectionUrl=jdbc:hsqldb:file:../temp/data/exodb -DdriverClass=org.hsqldb.jdbcDriver</emphasis> Or better use the parameters of eXo.bat / eXo.sh when you start eXo Portal: <emphasis role="bold">set EXO_OPTS="-DconnectionUrl=jdbc:hsqldb:file:../temp/data/exodb -DdriverClass=org.hsqldb.jdbcDriver"</emphasis> + </para> + + </section> + + + </section> + + +</section> + + Deleted: epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/SSO.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/AuthenticationAndIdentity/SSO.xml 2011-11-24 17:26:22 UTC (rev 8138) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/SSO.xml 2011-11-25 00:48:53 UTC (rev 8141) @@ -1,1695 +0,0 @@ -<?xml version='1.0' encoding='utf-8' ?> -<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -<!ENTITY % BOOK_ENTITIES SYSTEM "Reference_Guide_eXo_JCR_1.14.ent"> -%BOOK_ENTITIES; -]> -<section id="sect-Reference_Guide_eXo_JCR_1.14-SSO_Single_Sign_On_"> - <title><remark>SSO - Single Sign On</remark> - </title> - <section id="sect-Reference_Guide_eXo_JCR_1.14-SSO_Single_Sign_On_-Overview"> - <title>Overview</title> - <para> - JBoss Enterprise Portal Platform provides an implementation of Single Sign On (<literal>SSO</literal>) as an integration and aggregation platform. - </para> - <para> - When logging into the portal users can access many systems through portlets using a single identity. In many cases, however, the portal infrastructure must be integrated with other SSO enabled systems. - </para> - <para> - There are many different Identity Management solutions available. In most cases each SSO framework provides a unique way to plug into a Java EE application. - </para> - <para> - This section will cover the implementation of four different SSO plug-ins with JBoss Enterprise Portal Platform: - </para> - <itemizedlist> - <listitem> - <para> - <xref linkend="sect-Reference_Guide_eXo_JCR_1.14-SSO_Single_Sign_On_-Central_Authentication_Service" /> - </para> - - </listitem> - <listitem> - <para> - <xref linkend="sect-Reference_Guide_eXo_JCR_1.14-SSO_Single_Sign_On_-Java_Open_Single_Sign_On_Project" /> - </para> - - </listitem> - <listitem> - <para> - <xref linkend="sect-Reference_Guide_eXo_JCR_1.14-SSO_Single_Sign_On_-OpenSSO" /> - </para> - - </listitem> - <listitem> - <para> - <xref linkend="sect-Reference_Guide_eXo_JCR_1.14-SSO_Single_Sign_On_-SPNEGO_Simple_and_Protected_GSSAPI_Negotiation_Mechanism" /> - </para> - - </listitem> - - </itemizedlist> - <note> - <title>Prerequisites</title> - <para> - In this tutorial, the SSO server is being installed in a Tomcat environment. Tomcat can be obtained from <ulink type="http" url="http://tomcat.apache.org"> http://tomcat.apache.org </ulink> . - </para> - - </note> - <para> - All the packages required for SSO setup can be found in a zip file located in the <filename>jboss-epp-<replaceable>VERSION</replaceable>/gatein-sso</filename> directory of the JBoss Enterprise Portal Platform binary package. - </para> - <para> - In the following scenarios this directory will be referred to as <replaceable>PORTAL_SSO</replaceable>. - </para> - <warning> - <para> - Users are advised to not run any portal extensions that could override the data when manipulating the <filename>gatein.ear</filename> file directly. - </para> - <!-- Removed in GateIn reference-guide - <para> - Remove <filename>JBOSS_HOME/server/PROFILE/deploy/gatein-sample-extension.ear</filename> and <filename>JBOSS_HOME/server/PROFILE/deploy/gatein-sample-portal.ear</filename> which are packaged by default with JBoss Enterprise Portal Platform. - </para> --> - </warning> - - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-SSO_Single_Sign_On_-Enabling_SSO_using_JBoss_SSO_Valve"> - <title>Enabling SSO using JBoss SSO Valve</title> - <!-- Source Metadata -URL: https://issues.jboss.org/browse/JBQA-4530 -Author [w/email]: Marek Posolda (mposolda(a)redhat.com) - -URL: http://community.jboss.org/wiki/JBossWebSingleSignOn -Author [w/email]: Brian Stansberry (bstansberry(a)jboss.com) - -URL: https://issues.jboss.org/browse/JBEPP-615 -Author [w/email]: Marek Posolda (mposolda(a)redhat.com) - --> <para> - The JBoss SSO valve is useful to authenticate a user on one JBoss Enterprise Portal Platform node in a cluster and have that authentication automatically carry across to other nodes in the cluster. - </para> - <para> - This authentication can also be used in any other web applications which may require authentication, <emphasis role="bold">provided that these applications use same roles as the main portal instance</emphasis>. Attempting to use an SSO authentication in an application that uses different roles may create authorization errors (<emphasis role="bold">403</emphasis> errors, for example). - </para> - <note> - <title>Reauthentication</title> - <para> - This behavior is coming from the fact that same JAAS principal is added by SSO valve to all HTTP requests, even to other web applications. - </para> - <para> - So the same roles are required because of it. There is an alternative that allows you to configure the SSO valve with the <parameter>requireReauthentication=true</parameter> parameter, which will force the SSO valve to perform reauthentication with saved credentials in each HTTP request against security domain of particular web application where the request is coming. - </para> - <para> - This will ensure that a new principal for that web application will be created with updated roles for that web application. - </para> - <para> - In other words; when <parameter>requireReauthentication</parameter> is <emphasis role="bold">false</emphasis> (the default state), you need to have the same roles among web applications. When <parameter>requireReauthentication</parameter> is <emphasis role="bold">true</emphasis> you need to have same username and passwords. - </para> - - </note> - <para> - More info about the JBoss SSO valve can be found at <ulink type="http" url="http://docs.redhat.com/docs/en-US/JBoss_Enterprise_Web_Platform... />. - </para> - <para> - To successfully implement SSO integration, do the following: - </para> - <procedure id="proc-Reference_Guide_eXo_JCR_1.14-Enabling_SSO_using_JBoss_SSO_Valve-SSO_Integration"> - <title>SSO Integration</title> - <step> - <para> - Open the <filename>/<replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/jbossweb.sar/server.xml</filename> file and uncomment one of the two <parameter>Valve</parameter> entries: - </para> - <itemizedlist> - <listitem> - <para> - For a <emphasis>non-clustered</emphasis> implementation, uncomment: - </para> - -<programlisting language="XML" role="XML">&lt;Valve className="org.apache.catalina.authenticator.SingleSignOn" /&gt; -</programlisting> - - </listitem> - <listitem> - <para> - For a <emphasis>clustered</emphasis> implementation, uncomment: - </para> - -<programlisting language="XML" role="XML">&lt;Valve className="org.jboss.web.tomcat.service.sso.ClusteredSingleSignOn" /&gt;</programlisting> - - </listitem> - - </itemizedlist> - - </step> - <step> - <para> - For implementation of the SSO valve among the different nodes of cluster, all the nodes must share the same domain (<emphasis>node1.yourdomain.com</emphasis> and <emphasis>node2.yourdomain.com</emphasis>, for example). - </para> - <para> - This domain needs to be configured in the SSO valve parameter <parameter>cookieDomain</parameter>. This is required because the SSO valve adds the cookie <emphasis role="bold">JSESSIONIDSSO</emphasis>, which is, by default bound only to the host where the request is originating. - </para> - <para> - When the <parameter>cookieDomain</parameter> parameter is used, the cookie is bound to the domain (like <emphasis>yourdomain.com</emphasis>), which will ensure that it is shared among both hosts <emphasis>node1.yourdomain.com</emphasis> and <emphasis>node2.yourdomain.com</emphasis>. - </para> - <para> - So in this case, the valve configuration would be: - </para> - -<programlisting language="XML" role="XML">&lt;Valve className="org.jboss.web.tomcat.service.sso.ClusteredSingleSignOn" -cookieDomain="yourdomain.com" /&gt; -</programlisting> - - </step> - <step> - <para> - Another important thing is that both cluster nodes needs to be on same cluster (using same parameter <emphasis role="bold">-g</emphasis> and same parameter <emphasis role="bold">-u</emphasis> and also using parameter <emphasis role="bold">-Dexo.profiles=cluster</emphasis>). - </para> - <para> - They must also share the same NFS directory and the same database and apply all the configuration needed for JBoss Enterprise Portal Platform cluster. - </para> - - </step> - - </procedure> - - <formalpara id="form-Reference_Guide_eXo_JCR_1.14-Enabling_SSO_using_JBoss_SSO_Valve-Testing_SSO_in_a_physical_cluster"> - <title>Testing SSO in a physical cluster</title> - <para> - In this example, we will try to simulate testing on more physical machines by simply using virtual hosts on single machine. - </para> - - </formalpara> - <procedure id="proc-Reference_Guide_eXo_JCR_1.14-Enabling_SSO_using_JBoss_SSO_Valve-Testing_the_SSO_Valve"> - <title>Testing the SSO Valve</title> - <step> - <para> - If you are using a Linux system, you can configure file <emphasis role="bold">/etc/hosts</emphasis> to contain these lines: - </para> - -<programlisting> -127.0.1.1 machine1.yourdomain.com -127.0.1.2 machine2.yourdomain.com -</programlisting> - - </step> - <step> - <para> - Open the <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/all/deploy/jbossweb.sar/server.xml</filename> file. - </para> - - </step> - <step> - <para> - Uncomment the line: - </para> - -<programlisting language="XML" role="XML">&lt;!-- -&lt;Valve className="org.jboss.web.tomcat.service.sso.ClusteredSingleSignOn" /&gt; ---&gt; -</programlisting> - - </step> - <step> - <para> - And edit it to match the following: - </para> - -<programlisting language="XML" role="XML">&lt;Valve className="org.jboss.web.tomcat.service.sso.ClusteredSingleSignOn" -cookieDomain="yourdomain.com" /&gt; -</programlisting> - <para> - This will ensure the <literal>JSESSIONIDSSO</literal> cookie is used in the correct domain, allowing the SSO authentication to occur. - </para> - - </step> - <step> - <para> - Copy server configuration <emphasis role="bold">all</emphasis> and create another two configurations <emphasis role="bold">node1</emphasis> and <emphasis role="bold">node2</emphasis> from it. - </para> - - </step> - <step> - <para> - Start both cluster nodes with commands: - </para> - -<programlisting> -./run.sh -c node1 -b machine1.yourdomain.com -Dexo.profiles=cluster -Djboss.messaging.ServerPeerID=0 &amp; -./run.sh -c node2 -b machine2.yourdomain.com -Dexo.profiles=cluster -Djboss.messaging.ServerPeerID=1 &amp; -</programlisting> - - </step> - <step> - <para> - Go to <ulink type="http" url="http://machine1.yourdomain.com:8080/portal">http://machine1.yourdomain.com:8080/portal</ulink> and login as a user. - </para> - - </step> - <step> - <para> - Access a private URL on the second host, such as <ulink type="http" url="http://machine2.yourdomain.com:8080/portal/dologin">http://machine2.yourdomain.com:8080/portal/dologin</ulink>, for example. - </para> - <para> - Now you should be logged directly into <literal>machine2</literal> thanks to SSO valve. - </para> - - </step> - <step> - <para> - Logout from SSO initiating machine1.yourdomain.com should also logged you out from other cluster nodes. So you should be logout directly from machine2 as well. - </para> - - </step> - - </procedure> - - <formalpara id="form-Reference_Guide_eXo_JCR_1.14-Enabling_SSO_using_JBoss_SSO_Valve-Enabling_SSO_with_Other_Web_Applications"> - <title>Enabling SSO with Other Web Applications</title> - <para> - As mentioned earlier, in order to use SSO authentication between JBoss Enterprise Portal Platform instances and other web applications, the roles defined in the web application must match those used in the portal instance (unless you have the <parameter>requireReauthentication</parameter> parameter set to <literal>true</literal>). - </para> - - </formalpara> - <para> - As an example, to use the SSO Valve to authenticate a user in both a portal instance and the JMX Console, the following actions would be required: - </para> - <procedure> - <title></title> - <step> - <para> - Open the <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/node1/deploy/jmx-console.war/WEB-INF/web.xml</filename> file and edit it as follows: - </para> - <substeps> - <step> - <para> - Change the <parameter>&lt;role-name&gt;</parameter> entry in the <parameter>&lt;auth-constraint&gt;</parameter> element (line <literal>110</literal>) from <literal>JBossAdmin</literal> to <literal>users</literal>: - </para> - -<programlisting language="XML" role="XML">&lt;auth-constraint&gt; - &lt;!--&lt;role-name&gt;JBossAdmin&lt;/role-name&gt;--&gt; - &lt;role-name&gt;users&lt;/role-name&gt; -&lt;/auth-constraint&gt;</programlisting> - - </step> - <step> - <para> - Change the <parameter>&lt;role-name&gt;</parameter> entry in the <parameter>&lt;security-role&gt;</parameter> element (line <literal>120</literal>) from <literal>JBossAdmin</literal> to <literal>users</literal> - </para> - -<programlisting language="XML" role="XML">&lt;security-role&gt; - &lt;!--&lt;role-name&gt;JBossAdmin&lt;/role-name&gt;--&gt; - &lt;role-name&gt;users&lt;/role-name&gt; -&lt;/security-role&gt;</programlisting> - - </step> - - </substeps> - - </step> - - </procedure> - - <formalpara id="form-Reference_Guide_eXo_JCR_1.14-Enabling_SSO_using_JBoss_SSO_Valve-Testing_SSO_With_Other_Web_Applications"> - <title>Testing SSO With Other Web Applications</title> - <para> - To test that SSO authentication is enabled from portal instances to other web applications (in this case, the JMX Console), do the following: - </para> - - </formalpara> - <procedure id="proc-Reference_Guide_eXo_JCR_1.14-Enabling_SSO_using_JBoss_SSO_Valve-Test_SSO_Between_Portal_and_JMX_Console"> - <title>Test SSO Between Portal and JMX Console</title> - <step> - <para> - Start a portal instance on one node: - </para> - -<programlisting>./run.sh -c node1 -b machine1.yourdomain.com -Dexo.profiles=cluster -Djboss.messaging.ServerPeerID=0 &amp; -</programlisting> - - </step> - <step> - <para> - Navigate to <ulink type="http" url="http://machine1.yourdomain.com:8080/portal/private/classic" /> and authenticate with the pre-configured user account "<systemitem>root</systemitem>" (password "<systemitem>gtn </systemitem>"). - </para> - - </step> - <step> - <para> - Navigate to <ulink type="http" url="http://machine1.yourdomain.com:8080/jmx-console" />. You should be automatically authenticated into the JMX Console. - </para> - - </step> - - </procedure> - - <formalpara id="form-Reference_Guide_eXo_JCR_1.14-Enabling_SSO_using_JBoss_SSO_Valve-Using_SSO_to_Authenticate_From_the_Public_Page"> - <title>Using SSO to Authenticate From the Public Page</title> - <para> - The previous configuration changes in this section are useful if a user is using a secured URL (<ulink type="http" url="http://localhost:8080/portal/private/classic" />, for example) to log in to the portal instance. - </para> - - </formalpara> - <para> - Further changes are needed however, if SSO authentication is required to work with the <guilabel>Sign In</guilabel> button on the front page of the portal (<ulink type="http" url="http://localhost:8080/portal/classic" />). - </para> - <para> - To enable this functionality, the <guilabel>Sign In</guilabel> link must redirect to some secured URL, which will ensure that JAAS authentication will be enforced directly without showing login dialog. - </para> - <procedure id="proc-Reference_Guide_eXo_JCR_1.14-Enabling_SSO_using_JBoss_SSO_Valve-Redirect_to_Use_SSO_Valve_Authentication"> - <title>Redirect to Use SSO Valve Authentication</title> - <step> - <para> - Open the <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/web.war/groovy/groovy/webui/component/UIBannerPortlet.gtml</filename> file and edit the line: - </para> - -<programlisting language="Java" role="java">&lt;a class="Login" onclick="$signInAction"&gt;&lt;%=_ctx.appRes("UILoginForm.label.Signin")%&gt;&lt;/a&gt; -</programlisting> - <para> - To read: - </para> - -<programlisting language="Java" role="java">&lt;a class="Login" href="/portal/private/classic"&gt;&lt;%=_ctx.appRes("UILoginForm.label.Signin")%&gt;&lt;/a&gt; -</programlisting> - - </step> - <step> - <para> - Open the <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/web.war/groovy/portal/webui/component/UILogoPortlet.gtmpl</filename> file and change the line: - </para> - -<programlisting language="Java" role="java">&lt;a onclick="$signInAction"&gt;&lt;%=_ctx.appRes("UILogoPortlet.action.signin")%&gt;&lt;/a&gt; -</programlisting> - <para> - To read: - </para> - -<programlisting language="Java" role="java">&lt;a href="/portal/private/classic"&gt;&lt;%=_ctx.appRes("UILogoPortlet.action.signin")%&gt;&lt;/a&gt; -</programlisting> - - </step> - - </procedure> - - - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-SSO_Single_Sign_On_-Central_Authentication_Service"> - <title>Central Authentication Service</title> - <para> - This Single Sign On plugin enables seamless integration between JBoss Enterprise Portal Platform and the Central Authentication Service (<emphasis role="bold">CAS</emphasis>) Single Sign On Framework. Details about CAS can be found <ulink url="http://www.ja-sig.org/cas/"> here </ulink> . - </para> - <para> - The integration consists of two parts; the first part consists of installing or configuring a CAS server, the second part consists of setting up the portal to use the CAS server. - </para> - <procedure id="proc-Reference_Guide_eXo_JCR_1.14-Central_Authentication_Service-CAS_server"> - <title>CAS server</title> - <step> - <para> - Set up the server to authenticate against the portal login module. - </para> - - </step> - <step> - <para> - Downloaded CAS from <ulink type="http" url="http://www.jasig.org/cas/download"> http://www.jasig.org/cas/download </ulink> . - </para> - <para> - The version, tested with these instructions is <emphasis role="bold">CAS 3.3.5</emphasis>. Other versions may work. - </para> - - </step> - <step> - <para> - Extract the downloaded file into a suitable location. This location will be referred to as <replaceable>CAS_DIR</replaceable> in the following example. - </para> - - </step> - - </procedure> - - <para> - The simplest way to configure the web archive is to make the necessary changes directly into the CAS codebase. - </para> - <note> - <para> - To perform the final build step and complete these instructions you will need the Apache Maven 2. Download it from <ulink type="http" url="http://maven.apache.org/download.html"> here </ulink> . - </para> - - </note> - <para> - Change the default authentication handler with the one provided by JBoss Enterprise Portal Platform. - </para> - <para> - The CAS Server Plugin makes secure callbacks to a RESTful service installed on the remote JBoss Enterprise Portal Platform server to authenticate a user. - </para> - <para> - In order for the plugin to function correctly, it needs to be properly configured to connect to this service. This configuration is controlled by the <filename>cas.war/WEB-INF/deployerConfigContext.xml </filename> file. - </para> - <procedure id="proc-Reference_Guide_eXo_JCR_1.14-Central_Authentication_Service-Modifying_CAS_server"> - <title>Modifying CAS server</title> - <step> - <para> - Open <filename><replaceable>CAS_DIR</replaceable>/cas-server-webapp/src/main/webapp/WEB-INF/deployerConfigContext.xml</filename> - </para> - - </step> - <step> - <para> - Replace this code: - </para> - -<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default102.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <para> - with the following (ensure you set the host, port and context with the values corresponding to your portal). Also available in <filename>GATEIN_SSO_HOME/cas/plugin/WEB-INF/deployerConfigContext.xml</filename>.): - </para> - -<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default103.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - - </step> - <step> - <para> - Copy <filename><replaceable>PORTAL_SSO</replaceable>/cas/plugin/WEB-INF/lib/sso-cas-plugin-&lt;VERSION&gt;.jar</filename> and <filename><replaceable>PORTAL_SSO</replaceable>/cas/plugin/WEB-INF/lib/commons-httpclient-&lt;VERSION&gt;.jar</filename> into the <filename><replaceable>CAS_DIR</replaceable>/cas-server-webapp/src/main/webapp/WEB-INF/lib</filename> created directory. - </para> - - </step> - <step> - <para> - If you have not already done so, download an instance of Tomcat and extract it into a suitable location (which will be called <filename>TOMCAT_HOME</filename> for these instructions). - </para> - - </step> - <step> - <para> - Edit <filename>TOMCAT_HOME/conf/server.xml</filename> and change the 8080 port to 8888 to avoid a conflict with the default JBoss Enterprise Portal Platform. - </para> - <note> - <para> - If JBoss Enterprise Portal Platform is running on the same machine as Tomcat other ports will need to be changed in addition to 8080 in order to avoid conflicts. They can be changed to any free port. For example; you can change the admin port from 8005 to 8805 and the AJP port from 8009 to 8809. - </para> - - </note> - - </step> - <step> - <para> - Navigate locally to the <filename><replaceable>CAS_DIR</replaceable>/cas-server-webapp</filename> directory and execute the following command: - </para> - -<programlisting>mvn install -</programlisting> - - </step> - <step> - <para> - Copy the <filename><replaceable>CAS_DIR</replaceable>/cas-server-webapp/target/cas.war</filename> file into the <filename>TOMCAT_HOME/webapps</filename> directory. - </para> - <para> - Tomcat should start without issue and should be accessible at <ulink type="http" url="http://localhost:8888/cas"> http://localhost:8888/cas </ulink> . - </para> - <note> - <para> - At this stage the login functionality will not be available. - </para> - - </note> - <mediaobject> - <imageobject> - <imagedata fileref="images/AuthenticationAndIdentity/SSO/cas.png" format="PNG" scale="100" width="444" /> - </imageobject> - - </mediaobject> - - </step> - - </procedure> - - <note> - <para> - On logout, the CAS server will display the CAS logout page with a link to return to the portal. To make the CAS server redirect to the portal page after a logout, modify the <filename>cas.war/WEB-INF/cas-servlet.xml</filename> to include the follow line : - </para> - -<programlisting> -&lt;bean id="logoutController" class="org.jasig.cas.web.LogoutController" - p:centralAuthenticationService-ref="centralAuthenticationService" - p:logoutView="casLogoutView" - p:warnCookieGenerator-ref="warnCookieGenerator" - p:ticketGrantingTicketCookieGenerator-ref="ticketGrantingTicketCookieGenerator" - p:followServiceRedirects="true"/&gt; -</programlisting> - - </note> - <procedure id="proc-Reference_Guide_eXo_JCR_1.14-Central_Authentication_Service-Setup_the_CAS_client"> - <title>Setup the CAS client</title> - <step> - <para> - Copy all the libraries from the <filename><replaceable>PORTAL_SSO</replaceable>/cas/gatein.ear/lib</filename> directory into the <filename>JBOSS_HOME/server/default/deploy/gatein.ear/lib</filename>) directory. - </para> - - </step> - <step> - <para> - Edit the <filename>jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/META-INF/gatein-jboss-beans.xml</filename> and uncomment this section: - </para> - -<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default105.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <para> - There's a line comment already in this source file to assist you. - </para> - <!-- Removing as per https://issues.jboss.org/browse/JBEPP-1350 - <para> - In Tomcat, edit <filename>GATEIN_HOME/conf/jaas.conf</filename>, uncomment on this section and comment other parts: - </para> -<programlisting>org.gatein.sso.agent.login.SSOLoginModule required; -org.exoplatform.services.security.j2ee.TomcatLoginModule required -portalContainerName=portal -realmName=gatein-domain; -</programlisting> - --> - </step> - <step> - <para> - The installation can be tested at this point (assuming the CAS server on Tomcat is running): - </para> - <procedure> - <step> - <para> - Start (or restart) JBoss Enterprise Portal Platform and direct your web browser to <ulink type="http" url="http://localhost:8888/cas"> http://localhost:8888/cas </ulink> . - </para> - - </step> - <step> - <para> - Login with the username <literal>root</literal> and the password <literal>gtn</literal> (or any other account created through the portal). - </para> - - </step> - - </procedure> - - - </step> - - </procedure> - - <para> - To utilize the Central Authentication Service, JBoss Enterprise Portal Platform needs to redirect all user authentication to the CAS server. - </para> - <para> - Information about where the CAS is hosted must be properly configured within the JBoss Enterprise Portal Platform instance. The required configuration is done by modifying three files. - </para> - <procedure id="proc-Reference_Guide_eXo_JCR_1.14-Central_Authentication_Service-Redirect_to_CAS"> - <title>Redirect to CAS</title> - <step> - <para> - Modify the '<emphasis role="bold">Sign In</emphasis>' link in the <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/web.war/groovy/groovy/webui/component/UIBannerPortlet.gtml</filename> file as follows: - </para> - -<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default106.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - - </step> - <step> - <para> - Modify the '<emphasis role="bold">Sign In</emphasis>' link in the <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/web.war/groovy/portal/webui/component/UILogoPortlet.gtmpl</filename> file as follows: - </para> - -<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default107.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - - </step> - <step> - <para> - Replace the entire contents of <filename>gatein.ear/02portal.war/login/jsp/login.jsp</filename> with: - </para> - -<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default108.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - - </step> - <step> - <para> - Add the following Filters at the top of the filter chain in <filename>gatein.ear/02portal.war/WEB-INF/web.xml</filename>: - </para> - -<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default109.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - - </step> - - </procedure> - - <para> - Once these changes have been made, all links to the user authentication pages will redirect to the CAS centralized authentication form and CAS can be used as an SSO implementation in your portal. - </para> - - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-SSO_Single_Sign_On_-Java_Open_Single_Sign_On_Project"> - <title>Java Open Single Sign-On Project</title> - <para> - This Single Sign On plugin enables seamless integration between JBoss Enterprise Portal Platform and the Java Open Single Sign-On Project (<emphasis role="bold">JOSSO</emphasis>) Single Sign On Framework. Details about JOSSO can be found at <ulink url="http://www.josso.org"> www.josso.org </ulink> . - </para> - <para> - This section details setting up the JOSSO server to authenticate against the JBoss Enterprise Portal Platform login module. - </para> - <procedure id="proc-Reference_Guide_eXo_JCR_1.14-Java_Open_Single_Sign_On_Project-JOSSO_server"> - <title>JOSSO server</title> - <step> - <para> - Download JOSSO from <ulink type="http" url="http://sourceforge.net/projects/josso/files/"> http://sourceforge.net/projects/josso/files/ </ulink> . - </para> - <note> - <para> - Use the package that embeds Apache Tomcat. The integration was tested with JOSSO-1.8.1. - </para> - - </note> - - </step> - <step> - <para> - Extract the package into what will be called <filename>JOSSO_HOME</filename> in this example. - </para> - - </step> - - </procedure> - - <procedure id="proc-Reference_Guide_eXo_JCR_1.14-Java_Open_Single_Sign_On_Project-Modifying_JOSSO_server"> - <title>Modifying JOSSO server</title> - <step> - <para> - Copy the files from <filename><replaceable>PORTAL_SSO</replaceable>/josso/plugin</filename> into the <filename>JOSSO_HOME</filename> directory created in the last step. - </para> - <para> - This action should replace or add the following files to the <filename>JOSSO_HOME/webapps/josso/WEB-INF/lib</filename> directory: - </para> - <itemizedlist> - <listitem> - <para> - <filename>JOSSO_HOME/lib/josso-gateway-config.xml</filename> - </para> - - </listitem> - <listitem> - <para> - <filename>JOSSO_HOME/lib/josso-gateway-gatein-stores.xml</filename> - </para> - - </listitem> - <listitem> - <para> - <filename>JOSSO_HOME/webapps/josso/WEB-INF/classes/gatein.properties</filename> - </para> - - </listitem> - - </itemizedlist> - - </step> - <step> - <para> - Edit <filename>TOMCAT_HOME/conf/server.xml</filename> file and change the 8080 port to 8888 to avoid a conflict with the default JBoss Enterprise Portal Platform port. - <note> - <title>Port Conflicts</title> - <para> - If JBoss Enterprise Portal Platform is running on the same machine as Tomcat, other ports need to be changed in addition to 8080 in order to avoid port conflicts. They can be changed to any free port. For example, you can change admin port from 8005 to 8805, and AJP port from 8009 to 8809. - </para> - - </note> - - </para> - - </step> - <step> - <para> - Tomcat will start and allow access to <ulink type="http" url="http://localhost:8888/josso/signon/login.do"> http://localhost:8888/josso/signon/login.do </ulink> but at this stage login will not be available. - </para> - <mediaobject> - <imageobject> - <imagedata fileref="images/AuthenticationAndIdentity/SSO/opensso.png" format="PNG" width="444" /> - </imageobject> - - </mediaobject> - - </step> - - </procedure> - - <procedure id="proc-Reference_Guide_eXo_JCR_1.14-Java_Open_Single_Sign_On_Project-Setup_the_JOSSO_client"> - <title>Setup the JOSSO client</title> - <step> - <para> - Copy the library files from <filename><replaceable>PORTAL_SSO</replaceable>/josso/gatein.ear/lib</filename> into <filename>gatein.ear/lib</filename> (or into <filename>GATEIN_HOME/lib</filename> if the product is running in Tomcat). - </para> - - </step> - <step> - <para> - Copy the <filename><replaceable>PORTAL_SSO</replaceable>/josso/gatein.ear/portal.war/WEB-INF/classes/josso-agent-config.xml</filename> file into the <filename>gatein.ear/02portal.war/WEB-INF/classes</filename> directory (or into <filename>JBOSS_HOME/webapps/portal.war/WEB-INF/classes</filename>, or <filename>GATEIN_HOME/conf</filename> if the product is running in Tomcat). - </para> - - </step> - <step> - <para> - Edit <filename>jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/META-INF/gatein-jboss-beans.xml</filename> and uncomment this section: - </para> - -<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default111.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - - </step> - <step> - <para> - In Tomcat, edit <filename>JBOSS_HOME/conf/jaas.conf</filename> and uncomment this section: - </para> - -<programlisting>org.gatein.sso.agent.login.SSOLoginModule required; -org.exoplatform.services.security.j2ee.TomcatLoginModule requiredtm -portalContainerName=portal -realmName=gatein-domain; -</programlisting> - - </step> - <step> - <para> - The installation can be tested at this point. - </para> - <substeps> - <step> - <para> - Start (or restart) JBoss Enterprise Portal Platform, and (assuming the JOSSO server on Tomcat is running) direct your browser to <ulink type="http" url="http://localhost:8888/josso/signon/login.do"> http://localhost:8888/josso/signon/login.do </ulink> . - </para> - - </step> - <step> - <para> - Login with the username <literal>root</literal> and the password <literal>gtn</literal> or any account created through the portal. - </para> - - </step> - - </substeps> - - </step> - - </procedure> - - <para> - The next part of the process is to redirect all user authentication to the JOSSO server. - </para> - <para> - Information about where the JOSSO server is hosted must be properly configured within the JBoss Enterprise Portal Platform instance. The required configuration is done by modifying four files: - </para> - <procedure id="proc-Reference_Guide_eXo_JCR_1.14-Java_Open_Single_Sign_On_Project-Setup_the_portal_to_redirect_to_JOSSO"> - <title>Setup the portal to redirect to JOSSO</title> - <step> - <para> - In the <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/web.war/groovy/groovy/webui/component/UIBannerPortlet.gtml</filename> file modify the 'Sign In' link as follows: - </para> - -<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default112.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - - </step> - <step> - <para> - Modify the '<emphasis role="bold">Sign In</emphasis>' link in the <filename>gatein.ear/web.war/groovy/portal/webui/component/UILogoPortlet.gtmpl</filename> file as follows: - </para> - -<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default113.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - - </step> - <step> - <para> - Replace the entire contents of <filename>gatein.ear/02portal.war/login/jsp/login.jsp</filename> with: - </para> - -<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default114.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - - </step> - <step> - <para> - Add the following Filters to the top of the filter chain in <filename>gatein.ear/02portal.war/WEB-INF/web.xml</filename>: - </para> - -<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default115.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - - </step> - - </procedure> - - <para> - From now on, all links redirecting to the user authentication pages will redirect to the JOSSO centralized authentication form. - </para> - - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-SSO_Single_Sign_On_-OpenSSO"> - <title>OpenSSO</title> - <para> - This section details the setting up of OpenSSO server to authenticate against the JBoss Enterprise Portal Platform login module. - </para> - <procedure id="proc-Reference_Guide_eXo_JCR_1.14-OpenSSO-Obtaining_OpenSSO"> - <title>Obtaining OpenSSO</title> - <step> - <para> - OpenSSO must be purchased from <ulink type="http" url="http://www.oracle.com/technetwork/middleware/id-mgmt/overview/i... Oracle </ulink> . - </para> - <para> - For testing purpose, use OpenSSO_80U2, which can be downloaded from <ulink type="http" url="http://download.oracle.com/otn/nt/middleware/11g/oracle_opensso... Oracle </ulink> . - </para> - - </step> - <step> - <para> - Extract the package into a suitable location. This location will be referred to as <filename>OPENSSO_HOME</filename> in this example. - </para> - - </step> - - </procedure> - - <note> - <para> - It is also possible to use OpenAM instead of OpenSSO server. OpenAM is free and the integration steps between Enterprise Portal Platform and OpenAM are very similar as with OpenSSO. More info is available <ulink type="http" url="http://community.jboss.org/wiki/GateInAndOpenAMIntegration"... here </ulink> . - </para> - - </note> - - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-SSO_Single_Sign_On_-Modifying_the_OpenSSO_server"> - <title>Modifying the OpenSSO server</title> - <para> - To configure the web server as required, it is simpler to directly modify the source files. - </para> - <para> - The first step is to add the JBoss Enterprise Portal Platform Authentication Plugin. - </para> - <para> - The plugin makes secure callbacks to a RESTful service installed on the remote JBoss Enterprise Portal Platform server to authenticate a user. - </para> - <para> - In order for the plugin to function correctly, it needs to be properly configured to connect to this service. This configuration is done via the <filename>opensso.war/config/auth/default/AuthenticationPlugin.xml</filename> file. - </para> - <procedure id="proc-Reference_Guide_eXo_JCR_1.14-Modifying_the_OpenSSO_server-Modifying_OpenSSO_server"> - <title>Modifying OpenSSO server</title> - <step> - <para> - Obtain a copy of Tomcat and extract it into a suitable location. This location will be referred to as <filename>TOMCAT_HOME</filename> in this example. - </para> - - </step> - <step> - <para> - Edit <filename>TOMCAT_HOME/conf/server.xml</filename> and change the 8080 port to 8888 to avoid a conflict with the default JBoss Enterprise Portal Platform port. - <note> - <para> - If JBoss Enterprise Portal Platform is running on the same machine as Tomcat, other ports need to be changed in addition to 8080 in order to avoid port conflicts. They can be changed to any free port. For example, you can change the admin port from 8005 to 8805 and the AJP port from 8009 to 8809. - </para> - - </note> - - </para> - - </step> - <step> - <para> - Ensure the <filename>TOMCAT_HOME/webapps/opensso/config/auth/default/AuthenticationPlugin.xml</filename> file matches the following: - </para> - -<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default117.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - - </step> - <step> - <para> - Copy the following files into the Tomcat directory at <filename>TOMCAT_HOME/webapps/opensso/WEB-INF/lib</filename>: - </para> - <itemizedlist> - <listitem> - <para> - <filename><replaceable>PORTAL_SSO</replaceable>/opensso/plugin/WEB-INF/lib/sso-opensso-plugin-&lt;VERSION&gt;.jar</filename> - </para> - - </listitem> - <listitem> - <para> - <filename><replaceable>PORTAL_SSO</replaceable>/opensso/plugin/WEB-INF/lib/commons-httpclient-&lt;VERSION&gt;.jar</filename> - </para> - - </listitem> - <listitem> - <para> - <filename><replaceable>PORTAL_SSO</replaceable>/opensso/plugin/WEB-INF/lib/commons-logging-&lt;VERSION&gt;.jar</filename> - </para> - - </listitem> - - </itemizedlist> - - </step> - <step> - <para> - Copy the <filename><replaceable>PORTAL_SSO</replaceable>/opensso/plugin/WEB-INF/classes/gatein.properties</filename> file into the <filename>TOMCAT_HOME/webapps/opensso/WEB-INF/classes</filename> directory. - </para> - - </step> - <step> - <para> - Tomcat should start and be able to access <ulink type="http" url="http://localhost:8888/opensso/UI/Login?realm=gatein"> http://localhost:8888/opensso/UI/Login?realm=gatein </ulink> . - </para> - <mediaobject> - <imageobject role="html"> - <imagedata align="center" fileref="images/AuthenticationAndIdentity/SSO/opensso-shot.png" format="PNG" scale="110" width="444" /> - </imageobject> - <imageobject role="fo"> - <imagedata align="center" contentwidth="150mm" fileref="images/AuthenticationAndIdentity/SSO/opensso-shot.png" format="PNG" width="444" /> - </imageobject> - - </mediaobject> - <note> - <para> - Login will not be available at this point. - </para> - - </note> - - </step> - - </procedure> - - <procedure id="proc-Reference_Guide_eXo_JCR_1.14-Modifying_the_OpenSSO_server-Configure_the_gatein_realm"> - <title>Configure the "gatein" realm</title> - <step> - <para> - Direct your browser to <ulink type="http" url="http://localhost:8888/opensso"> http://localhost:8888/opensso </ulink> - </para> - - </step> - <step> - <para> - Create a default configuration. - </para> - - </step> - <step> - <para> - Login as <literal>amadmin</literal>. - </para> - <important> - <para> - Go to <menuchoice><guimenu>Configuration</guimenu> <guimenuitem> Authentication </guimenuitem> </menuchoice> and follow the link to <guilabel>Core</guilabel> - </para> - <para> - Add a new value with the class name <literal>org.gatein.sso.opensso.plugin.AuthenticationPlugin</literal>. - </para> - <para> - If this is not done <literal>AuthenticationPlugin</literal> is not available among other OpenSSO authentication modules. - </para> - - </important> - - </step> - <step> - <para> - Go to the <guilabel>Access control</guilabel> tab and create new realm called <literal>gatein</literal>. - </para> - - </step> - <step> - <substeps> - <step> - <para> - Go to the new <literal>gatein</literal> realm and click on the <guilabel>Authentication</guilabel> tab. - </para> - - </step> - <step> - <para> - Click on <guilabel>ldapService</guilabel> (at the bottom in the <guilabel>Authentication chaining</guilabel> section). - </para> - - </step> - <step> - <para> - Change the selection from <literal>Datastore</literal>, which is the default module in the authentication chain, to <literal>AuthenticationPlugin</literal>. - </para> - - </step> - - </substeps> - <para> - These changes enable authentication of the <literal>gatein</literal> realm using the <literal>GateIn REST</literal> service instead of the OpenSSO LDAP server. - </para> - - </step> - <step> - <para> - Go to <guilabel>Advanced properties</guilabel> and change <literal>UserProfile</literal> from <parameter>Required</parameter> to <parameter>Dynamic</parameter> to ensure all new users are automatically created in the OpenSSO datastore after successful authentication. - </para> - - </step> - <step> - <para> - Increase the user privileges to allow REST access with the following procedure: - </para> - <substeps> - <step> - <para> - Go to <menuchoice><guimenu>Access control</guimenu> <guimenuitem> Top level realm </guimenuitem> <guimenuitem> Privileges </guimenuitem> <guimenuitem> All authenticated users </guimenuitem> </menuchoice>. - </para> - - </step> - <step> - <para> - Check the last two checkboxes: - </para> - <itemizedlist> - <listitem> - <para> - Read and write access only for policy properties - </para> - - </listitem> - <listitem> - <para> - Read and write access to all realm and policy properties - </para> - - </listitem> - - </itemizedlist> - - </step> - - </substeps> - - </step> - <step> - <para> - Repeat step 7 for the '<literal>gatein</literal>' realm as well. - </para> - - </step> - - </procedure> - - - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-SSO_Single_Sign_On_-Setup_the_OpenSSO_Client"> - <title>Setup the OpenSSO Client</title> - <procedure id="proc-Reference_Guide_eXo_JCR_1.14-Setup_the_OpenSSO_Client-Setup_the_OpenSSO_client"> - <title>Setup the OpenSSO client</title> - <step> - <para> - Copy all libraries from the <filename><replaceable>PORTAL_SSO</replaceable>/opensso/gatein.ear/lib</filename> directory into the <filename>JBOSS_HOME/server/default/deploy/gatein.ear/lib</filename> directory. - </para> - <para> - Alternatively, in a Tomcat environment, copy the libraries into the <filename>JBOSS_HOME/lib</filename> directory. - </para> - - </step> - <step> - <para> - Edit the <filename>jboss-as/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/META-INF/gatein-jboss-beans.xml</filename> and uncomment this section: - </para> - -<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default118.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - - </step> - <!-- Removed as per https://issues.jboss.org/browse/JBEPP-1350 - <step> - <para> - If you are running the product in Tomcat, edit <replaceable>&lt;JBOSS_HOME&gt;</replaceable>/conf/jaas.conf, uncomment the following section and comment all other sections: - </para> -<programlisting>org.gatein.sso.agent.login.SSOLoginModule required; -org.exoplatform.services.security.j2ee.TomcatLoginModule required -portalContainerName=portal -realmName=gatein-domain; -</programlisting> - </step> - --> <step> - <para> - Test the installation: - </para> - <procedure> - <step> - <para> - Access JBoss Enterprise Portal Platform by going to <ulink type="http" url="http://localhost:8888/opensso/UI/Login?realm=gatein"> http://localhost:8888/opensso/UI/Login?realm=gatein </ulink> (assuming that the OpenSSO server using Tomcat is still running). - </para> - - </step> - <step> - <para> - Login with the username <literal>root</literal> and the password <literal>gtn</literal> or any account created through the portal. - </para> - - </step> - - </procedure> - - - </step> - - </procedure> - - - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-SSO_Single_Sign_On_-Setup_the_portal_to_redirect_to_OpenSSO"> - <title>Setup the portal to redirect to OpenSSO</title> - <para> - The next part of the process is to redirect all user authentication to the OpenSSO server. - </para> - <para> - Information about where the OpenSSO server is hosted must be properly configured within the Enterprise Portal Platform instance. The required configuration is done by modifying three files: - </para> - <procedure id="proc-Reference_Guide_eXo_JCR_1.14-Setup_the_portal_to_redirect_to_OpenSSO-Setup_the_portal_to_redirect_to_OpenSSO"> - <title>Setup the portal to redirect to OpenSSO</title> - <step> - <para> - Modify the '<emphasis role="bold">Sign In</emphasis>' link in the <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/web.war/groovy/groovy/webui/component/UIBannerPortlet.gtml</filename> file as follows: - </para> - -<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default119.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - - </step> - <step> - <para> - Modify the '<emphasis role="bold">Sign In</emphasis>' link in the <filename>gatein.ear/web.war/groovy/portal/webui/component/UILogoPortlet.gtmpl</filename> file as follows: - </para> - -<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default120.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - - </step> - <step> - <para> - Replace the entire contents of <filename>gatein.ear/02portal.war/login/jsp/login.jsp</filename> with: - </para> - -<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default121.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - - </step> - <step> - <para> - Add the following Filters to the top of the filter chain in <filename>gatein.ear/02portal.war/WEB-INF/web.xml</filename>: - </para> - -<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default122.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - - </step> - - </procedure> - - <para> - From now on, all links redirecting to the user authentication pages will redirect to the OpenSSO centralized authentication form. - </para> - - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-SSO_Single_Sign_On_-SPNEGO_Simple_and_Protected_GSSAPI_Negotiation_Mechanism"> - <title>SPNEGO - Simple and Protected GSSAPI Negotiation Mechanism</title> - <para> - The Simple and Protected GSSAPI Negotiation Mechanism (<emphasis role="bold">SPNEGO</emphasis>) uses desktop credentials provided during a desktop login to transparently authenticate a portal user through a web browser. - </para> - <para> - For illustrative purposes; a typical use case would be: - </para> - <procedure> - <step> - <para> - A user logs into their desktop computer with a login that is governed by an Active Directory domain. - </para> - - </step> - <step> - <para> - The user then launches a web browser to access a web application (that uses JBoss Negotiation) hosted on JBoss Enterprise Portal Platform. - </para> - - </step> - <step> - <para> - The browser transfers the desktop credentials to the web application. - </para> - - </step> - <step> - <para> - JBoss EAP/AS uses background GSS messages with the Active Directory (or any Kerberos Server) to validate the Kerberos ticket from user. - </para> - - </step> - <step> - <para> - The user experiences a seamless single sign on (SSO) into the web application. - </para> - - </step> - - </procedure> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-SPNEGO_Simple_and_Protected_GSSAPI_Negotiation_Mechanism-SPNEGO_Server_Configuration"> - <title>SPNEGO Server Configuration</title> - <para> - In this section, we will describe some necessary steps for setup Kerberos server on Linux. This server will then be used for SPNEGO authentication against JBoss Enterprise Portal Platform. - </para> - <note> - <title>SPNEGO Basics</title> - <para> - The procedure below only describes the basic steps to configure the SPNEGO server in a Linux environment. If you are already familiar with SPNEGO, or if you are using Windows and Active Directory domain, you can jump to the <xref linkend="proc-Reference_Guide_eXo_JCR_1.14-JBoss_Enterprise_Portal_Platform_Configuration-Advanced_SPNEGO_Configuration" /> to see how to integrate SPNEGO with JBoss Enterprise Portal Platform. - </para> - <para> - Please note that Kerberos setup is also dependent on your Linux distribution and so steps can be slightly different in your environment. - </para> - - </note> - <procedure id="proc-Reference_Guide_eXo_JCR_1.14-SPNEGO_Server_Configuration-SPNEGO_Basics"> - <title>SPNEGO Basics</title> - <step> - <para> - Correct the setup of network on the machine. For example, if you are using the "server.local.network" domain as your machine where Kerberos and JBoss Enterprise Portal Platform are localed, add the line containing the machine's IP address to the <emphasis role="bold">/etc/host </emphasis> file. - </para> - -<programlisting> -192.168.1.88 server.local.network -</programlisting> - <note> - <para> - It is not recommended you use loopback addresses. - </para> - - </note> - - </step> - <step> - <para> - Install Kerberos with these packages: krb5-admin-server, krb5-kdc, krb5-config, krb5-user, krb5-clients, and krb5-rsh-server. - </para> - - </step> - <step> - <para> - Edit the Kerberos configuration file at <emphasis role="bold">/etc/krb5.config</emphasis>, including: - </para> - <itemizedlist> - <listitem> - <para> - Uncomment on these lines: - </para> - -<programlisting> -default_tgs_enctypes = des3-hmac-sha1 -default_tkt_enctypes = des3-hmac-sha1 -permitted_enctypes = des3-hmac-sha1 -</programlisting> - - </listitem> - <listitem> - <para> - Add <emphasis role="bold">local.network</emphasis> as a default realm and it is also added to the list of realms and remove the remains of realms. The content looks like: - </para> - -<programlisting> -[libdefaults] - default_realm = LOCAL.NETWORK - -# The following krb5.conf variables are only for MIT Kerberos. - krb4_config = /etc/krb.conf - krb4_realms = /etc/krb.realms - kdc_timesync = 1 - ccache_type = 4 - forwardable = true - proxiable = true - -# The following encryption type specification will be used by MIT Kerberos -# if uncommented. In general, the defaults in the MIT Kerberos code are -# correct and overriding these specifications only serves to disable new -# encryption types as they are added, creating interoperability problems. -# -# Thie only time when you might need to uncomment these lines and change -# the enctypes is if you have local software that will break on ticket -# caches containing ticket encryption types it doesn't know about (such as -# old versions of Sun Java). - - default_tgs_enctypes = des3-hmac-sha1 - default_tkt_enctypes = des3-hmac-sha1 - permitted_enctypes = des3-hmac-sha1 - -# The following libdefaults parameters are only for Heimdal Kerberos. - v4_instance_resolve = false - v4_name_convert = { - host = { - rcmd = host - ftp = ftp - } - plain = { - something = something-else - } - } - fcc-mit-ticketflags = true - -[realms] - LOCAL.NETWORK = { - kdc = server.local.network - admin_server = server.local.network - } - -[domain_realm] - .local.network = LOCAL.NETWORK - local.network = LOCAL.NETWORK - -[login] - krb4_convert = true - krb4_get_tickets = false -</programlisting> - - </listitem> - - </itemizedlist> - - </step> - <step> - <para> - Edit the KDC configuraton file at <emphasis role="bold">/etc/krb5kdc/kdc.conf</emphasis> that looks like. - </para> - -<programlisting> -[kdcdefaults] - kdc_ports = 750,88 - -[realms] - LOCAL.NETWORK = { - database_name = /home/gatein/krb5kdc/principal - admin_keytab = FILE:/home/gatein/krb5kdc/kadm5.keytab - acl_file = /home/gatein/krb5kdc/kadm5.acl - key_stash_file = /home/gatein/krb5kdc/stash - kdc_ports = 750,88 - max_life = 10h 0m 0s - max_renewable_life = 7d 0h 0m 0s - master_key_type = des3-hmac-sha1 - supported_enctypes = aes256-cts:normal arcfour-hmac:normal des3-hmac-sha1:normal des-cbc-crc:normal des:normal des:v4 des:norealm des:onlyrealm des:afs3 - default_principal_flags = +preauth - } - -[logging] - kdc = FILE:/home/gatein/krb5logs/kdc.log - admin_server = FILE:/home/gatein/krb5logs/kadmin.log -</programlisting> - <itemizedlist> - <listitem> - <para> - Create krb5kdc and krb5logs directory for Kerberos database as shown in the configuration file above. - </para> - - </listitem> - <listitem> - <para> - Next, create a KDC database using the following command. - </para> - -<programlisting> -sudo krb5_newrealm -</programlisting> - - </listitem> - <listitem> - <para> - Start the KDC and Kerberos admin servers using these commands: - </para> - -<programlisting> -sudo /etc/init.d/krb5-kdc restart -sudo /etc/init.d/krb-admin-server restart -</programlisting> - - </listitem> - - </itemizedlist> - - </step> - <step> - <para> - Add Principals and create Keys. - </para> - <itemizedlist> - <listitem> - <para> - Start an interactive 'kadmin' session and create the necessary Principals. - </para> - -<programlisting> -sudo kadmin.local -</programlisting> - - </listitem> - <listitem> - <para> - Add the JBoss Enterprise Portal Platform machine and keytab file that need to be authenticated. - </para> - -<programlisting> -addprinc -randkey HTTP/server.local.network(a)LOCAL.NETWORK -ktadd HTTP/server.local.network(a)LOCAL.NETWORK -</programlisting> - - </listitem> - <listitem> - <para> - Add the default JBoss Enterprise Portal Platform user accounts and enter the password for each created user that will be authenticated. - </para> - -<programlisting> -addprinc john -addprinc demo -addprinc root -</programlisting> - - </listitem> - - </itemizedlist> - - </step> - <step> - <para> - Test your changed setup by using the command. - </para> - -<programlisting> -kinit -A demo -</programlisting> - <itemizedlist> - <listitem> - <para> - If the setup works well, you are required to enter the password created for this user in Step 5. Without the -A, the kerberos ticket validation involved reverse DNS lookups, which can get very cumbersome to debug if your network's DNS setup is not great. This is a production level security feature, which is not necessary in this development setup. In production environment, it will be better to avoid -A option. - </para> - - </listitem> - <listitem> - <para> - After successful login to Kerberos, you can see your Kerberos ticket when using this command. - </para> - -<programlisting> -klist -</programlisting> - - </listitem> - <listitem> - <para> - If you want to logout and destroy your ticket, use this command. - </para> - -<programlisting> -kdestroy -</programlisting> - - </listitem> - - </itemizedlist> - - </step> - - </procedure> - - - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-SPNEGO_Simple_and_Protected_GSSAPI_Negotiation_Mechanism-SPNEGO_Server_Configuration-Clients"> - <title>Clients</title> - <para> - After performing all configurations above, you need to enable the <emphasis role="bold">Negotiate authentication </emphasis> of Firefox in client machines so that clients could be authenticated by JBoss Enterprise Portal Platform as follows: - </para> - <procedure> - <step> - <para> - Start Firefox, then enter the command: <emphasis role="bold">about:config </emphasis> into the address field. - </para> - - </step> - <step> - <para> - Enter <emphasis role="bold">network.negotiate-auth</emphasis> and set the value as below: - </para> - -<programlisting> -network.negotiate-auth.allow-proxies = true -network.negotiate-auth.delegation-uris = .local.network -network.negotiate-auth.gsslib (no-value) -network.negotiate-auth.trusted-uris = .local.network -network.negotiate-auth.using-native-gsslib = true -</programlisting> - - </step> - - </procedure> - - <note> - <para> - Consult documentation of your OS or web browser if using different browser than Firefox. - </para> - - </note> - - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-SPNEGO_Simple_and_Protected_GSSAPI_Negotiation_Mechanism-JBoss_Enterprise_Portal_Platform_Configuration"> - <title>JBoss Enterprise Portal Platform Configuration</title> - <para> - JBoss Enterprise Portal Platform uses JBoss Negotiation to enable SPNEGO-based desktop SSO for the portal. Here are the steps to integrate SPNEGO with JBoss Enterprise Portal Platform. - </para> - <procedure id="proc-Reference_Guide_eXo_JCR_1.14-JBoss_Enterprise_Portal_Platform_Configuration-Advanced_SPNEGO_Configuration"> - <title>Advanced SPNEGO Configuration</title> - <step> - <para> - Activate the Host authentication. Add the following host login module to the <filename>jboss-as/server/<replaceable>PROFILE</replaceable>/conf/login-config.xml</filename>: - </para> - -<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default124.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <para> - The '<literal>keyTab</literal>' value should point to the keytab file that was generated by the <literal>kadmin</literal> Kerberos tool. When using Kerberos on Linux, it should be value of parameter <emphasis role="bold">admin_keytab</emphasis> from kdc.conf file. See the <xref linkend="proc-Reference_Guide_eXo_JCR_1.14-SPNEGO_Server_Configuration-SPNEGO_Basics" /> for more details. - </para> - - </step> - <step> - <para> - Extend the core authentication mechanisms to support SPNEGO. Under <filename>deployers/jbossweb.deployer/META-INF/war-deployers-jboss-beans.xml</filename>, add a '<literal>SPNEGO</literal>' authenticators property - </para> - -<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default125.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - - </step> - <step> - <para> - Add the GateIn SSO module binaries by copying <emphasis role="bold">GATEIN_SSO_HOME/spnego/gatein.ear/lib/sso-agent-VERSION.jar</emphasis> to the <emphasis role="bold">JBOSS_HOME/server/default/deploy/gatein.ear/lib</emphasis> directory. File <emphasis role="bold">GATEIN_SSO_HOME/spnego/gatein.ear/lib/spnego-VERSION.jar</emphasis> needs to be copied to the <emphasis role="bold">JBOSS_HOME/server/default/lib</emphasis> directory. - </para> - - </step> - <!-- This step not required as EPP already has the correct version of Negotiation 2.0.4.GA - <step> - <para> - Download library <filename>jboss-negotiation-2.0.4.GA</filename> from location - <ulink type="html" url="https://repository.jboss.org/nexus/content/groups/public/org/jb... - and copy this file to <filename>JBOSS_HOME/server/default/lib</filename> directory as well. - </para> - </step> - --> <step> - <para> - Modify the <filename>deploy/gatein.ear/META-INF/gatein-jboss-beans.xml</filename> file to match the following: - </para> - -<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default126.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <para> - This activates SPNEGO LoginModules with fallback to FORM authentication. When SPNEGO is not available and it needs to fallback to FORM, it will use <emphasis role="bold">gatein-form-auth-domain</emphasis> security domain. - </para> - - </step> - <step> - <para> - Modify <filename>gatein.ear/02portal.war/WEB-INF/web.xml</filename> to match: - </para> - -<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default127.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <para> - Integrate the request pre-processing needed for SPNEGO via filters by adding the following filters to the <emphasis role="bold">JBOSS_HOME/server/default/deploy/gatein.ear/02portal.war/WEB-INF/web.xml</emphasis> at the top of the Filter chain. - </para> - -<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default128.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <para> - This integrates request pre-processing needed for SPNEGO. - </para> - - </step> - <step> - <para> - Edit the '<emphasis role="bold">Sign In</emphasis>' link in <filename><replaceable>JBOSS_HOME</replaceable>/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/web.war/groovy/groovy/webui/component/UIBannerPortlet.gtmpl</filename> to match the following: - </para> - -<programlisting language="Java" role="Java"><xi:include href="../../extras/Authentication_Identity_SSO/default129.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - - </step> - <step> - <para> - Start the JBoss Enterprise Portal Platform; - </para> - -<programlisting language="Java" role="Java"><xi:include href="../../extras/Authentication_Identity_SSO/default130.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <para> - The <replaceable>PROFILE</replaceable> parameter in the above command should be replaced with the server profile modified with the above configuration. - </para> - - </step> - <step> - <para> - Login to Kerberos: - </para> - -<programlisting>kinit -A demo -</programlisting> - - </step> - - </procedure> - - <para> - Clicking the 'Sign In' link on the JBoss Enterprise Portal Platform should automatically sign the 'demo' user into the portal. - </para> - <para> - If you destroy your kerberos ticket with command <command>kdestroy</command>, then try to login again, you will directed to the login screen of JBoss Enterprise Portal Product because you don't have active Kerberos ticket. You can login with predefined account and password "demo"/"gtn" . - </para> - - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-SPNEGO_Simple_and_Protected_GSSAPI_Negotiation_Mechanism-JBoss_Enterprise_Portal_Platform_Configuration-Clients"> - <title>Clients</title> - <para> - After performing all configurations above, you need to enable the <emphasis role="bold">Negotiate authentication </emphasis> of Firefox in clients so that clients can be authenticated by JBoss Enterprise Portal Platform as follows: - </para> - <procedure> - <step> - <para> - Start Firefox, then enter the command: <emphasis role="bold">about:config </emphasis> into the address field. - </para> - - </step> - <step> - <para> - Enter <emphasis role="bold">network.negotiate-auth</emphasis> and set the value as below: - </para> - -<programlisting> -network.negotiate-auth.allow-proxies = true -network.negotiate-auth.delegation-uris = .local.network -network.negotiate-auth.gsslib (no-value) -network.negotiate-auth.trusted-uris = .local.network -network.negotiate-auth.using-native-gsslib = true -</programlisting> - - </step> - - </procedure> - - - </section> - - - </section> - - -</section> - - Copied: epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/SSO.xml (from rev 8139, epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/AuthenticationAndIdentity/SSO.xml) =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/SSO.xml (rev 0) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/SSO.xml 2011-11-25 00:48:53 UTC (rev 8141) @@ -0,0 +1,1695 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "Reference_Guide_eXo_JCR_1.14.ent"> +%BOOK_ENTITIES; +]> +<section id="sect-Reference_Guide_eXo_JCR_1.14-SSO_Single_Sign_On_"> + <title><remark>SSO - Single Sign On</remark> + </title> + <section id="sect-Reference_Guide_eXo_JCR_1.14-SSO_Single_Sign_On_-Overview"> + <title>Overview</title> + <para> + JBoss Enterprise Portal Platform provides an implementation of Single Sign On (<literal>SSO</literal>) as an integration and aggregation platform. + </para> + <para> + When logging into the portal users can access many systems through portlets using a single identity. In many cases, however, the portal infrastructure must be integrated with other SSO enabled systems. + </para> + <para> + There are many different Identity Management solutions available. In most cases each SSO framework provides a unique way to plug into a Java EE application. + </para> + <para> + This section will cover the implementation of four different SSO plug-ins with JBoss Enterprise Portal Platform: + </para> + <itemizedlist> + <listitem> + <para> + <xref linkend="sect-Reference_Guide_eXo_JCR_1.14-SSO_Single_Sign_On_-Central_Authentication_Service" /> + </para> + + </listitem> + <listitem> + <para> + <xref linkend="sect-Reference_Guide_eXo_JCR_1.14-SSO_Single_Sign_On_-Java_Open_Single_Sign_On_Project" /> + </para> + + </listitem> + <listitem> + <para> + <xref linkend="sect-Reference_Guide_eXo_JCR_1.14-SSO_Single_Sign_On_-OpenSSO" /> + </para> + + </listitem> + <listitem> + <para> + <xref linkend="sect-Reference_Guide_eXo_JCR_1.14-SSO_Single_Sign_On_-SPNEGO_Simple_and_Protected_GSSAPI_Negotiation_Mechanism" /> + </para> + + </listitem> + + </itemizedlist> + <note> + <title>Prerequisites</title> + <para> + In this tutorial, the SSO server is being installed in a Tomcat environment. Tomcat can be obtained from <ulink type="http" url="http://tomcat.apache.org"> http://tomcat.apache.org </ulink> . + </para> + + </note> + <para> + All the packages required for SSO setup can be found in a zip file located in the <filename>jboss-epp-<replaceable>VERSION</replaceable>/gatein-sso</filename> directory of the JBoss Enterprise Portal Platform binary package. + </para> + <para> + In the following scenarios this directory will be referred to as <replaceable>PORTAL_SSO</replaceable>. + </para> + <warning> + <para> + Users are advised to not run any portal extensions that could override the data when manipulating the <filename>gatein.ear</filename> file directly. + </para> + <!-- Removed in GateIn reference-guide + <para> + Remove <filename>JBOSS_HOME/server/PROFILE/deploy/gatein-sample-extension.ear</filename> and <filename>JBOSS_HOME/server/PROFILE/deploy/gatein-sample-portal.ear</filename> which are packaged by default with JBoss Enterprise Portal Platform. + </para> --> + </warning> + + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-SSO_Single_Sign_On_-Enabling_SSO_using_JBoss_SSO_Valve"> + <title>Enabling SSO using JBoss SSO Valve</title> + <!-- Source Metadata +URL: https://issues.jboss.org/browse/JBQA-4530 +Author [w/email]: Marek Posolda (mposolda(a)redhat.com) + +URL: http://community.jboss.org/wiki/JBossWebSingleSignOn +Author [w/email]: Brian Stansberry (bstansberry(a)jboss.com) + +URL: https://issues.jboss.org/browse/JBEPP-615 +Author [w/email]: Marek Posolda (mposolda(a)redhat.com) + --> <para> + The JBoss SSO valve is useful to authenticate a user on one JBoss Enterprise Portal Platform node in a cluster and have that authentication automatically carry across to other nodes in the cluster. + </para> + <para> + This authentication can also be used in any other web applications which may require authentication, <emphasis role="bold">provided that these applications use same roles as the main portal instance</emphasis>. Attempting to use an SSO authentication in an application that uses different roles may create authorization errors (<emphasis role="bold">403</emphasis> errors, for example). + </para> + <note> + <title>Reauthentication</title> + <para> + This behavior is coming from the fact that same JAAS principal is added by SSO valve to all HTTP requests, even to other web applications. + </para> + <para> + So the same roles are required because of it. There is an alternative that allows you to configure the SSO valve with the <parameter>requireReauthentication=true</parameter> parameter, which will force the SSO valve to perform reauthentication with saved credentials in each HTTP request against security domain of particular web application where the request is coming. + </para> + <para> + This will ensure that a new principal for that web application will be created with updated roles for that web application. + </para> + <para> + In other words; when <parameter>requireReauthentication</parameter> is <emphasis role="bold">false</emphasis> (the default state), you need to have the same roles among web applications. When <parameter>requireReauthentication</parameter> is <emphasis role="bold">true</emphasis> you need to have same username and passwords. + </para> + + </note> + <para> + More info about the JBoss SSO valve can be found at <ulink type="http" url="http://docs.redhat.com/docs/en-US/JBoss_Enterprise_Web_Platform... />. + </para> + <para> + To successfully implement SSO integration, do the following: + </para> + <procedure id="proc-Reference_Guide_eXo_JCR_1.14-Enabling_SSO_using_JBoss_SSO_Valve-SSO_Integration"> + <title>SSO Integration</title> + <step> + <para> + Open the <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/jbossweb.sar/server.xml</filename> file and uncomment one of the two <parameter>Valve</parameter> entries: + </para> + <itemizedlist> + <listitem> + <para> + For a <emphasis>non-clustered</emphasis> implementation, uncomment: + </para> + +<programlisting language="XML" role="XML">&lt;Valve className="org.apache.catalina.authenticator.SingleSignOn" /&gt; +</programlisting> + + </listitem> + <listitem> + <para> + For a <emphasis>clustered</emphasis> implementation, uncomment: + </para> + +<programlisting language="XML" role="XML">&lt;Valve className="org.jboss.web.tomcat.service.sso.ClusteredSingleSignOn" /&gt;</programlisting> + + </listitem> + + </itemizedlist> + + </step> + <step> + <para> + For implementation of the SSO valve among the different nodes of cluster, all the nodes must share the same domain (<emphasis>node1.yourdomain.com</emphasis> and <emphasis>node2.yourdomain.com</emphasis>, for example). + </para> + <para> + This domain needs to be configured in the SSO valve parameter <parameter>cookieDomain</parameter>. This is required because the SSO valve adds the cookie <emphasis role="bold">JSESSIONIDSSO</emphasis>, which is, by default bound only to the host where the request is originating. + </para> + <para> + When the <parameter>cookieDomain</parameter> parameter is used, the cookie is bound to the domain (like <emphasis>yourdomain.com</emphasis>), which will ensure that it is shared among both hosts <emphasis>node1.yourdomain.com</emphasis> and <emphasis>node2.yourdomain.com</emphasis>. + </para> + <para> + So in this case, the valve configuration would be: + </para> + +<programlisting language="XML" role="XML">&lt;Valve className="org.jboss.web.tomcat.service.sso.ClusteredSingleSignOn" +cookieDomain="yourdomain.com" /&gt; +</programlisting> + + </step> + <step> + <para> + Another important thing is that both cluster nodes needs to be on same cluster (using same parameter <emphasis role="bold">-g</emphasis> and same parameter <emphasis role="bold">-u</emphasis> and also using parameter <emphasis role="bold">-Dexo.profiles=cluster</emphasis>). + </para> + <para> + They must also share the same NFS directory and the same database and apply all the configuration needed for JBoss Enterprise Portal Platform cluster. + </para> + + </step> + + </procedure> + + <formalpara id="form-Reference_Guide_eXo_JCR_1.14-Enabling_SSO_using_JBoss_SSO_Valve-Testing_SSO_in_a_physical_cluster"> + <title>Testing SSO in a physical cluster</title> + <para> + In this example, we will try to simulate testing on more physical machines by simply using virtual hosts on single machine. + </para> + + </formalpara> + <procedure id="proc-Reference_Guide_eXo_JCR_1.14-Enabling_SSO_using_JBoss_SSO_Valve-Testing_the_SSO_Valve"> + <title>Testing the SSO Valve</title> + <step> + <para> + If you are using a Linux system, you can configure file <emphasis role="bold">/etc/hosts</emphasis> to contain these lines: + </para> + +<programlisting> +127.0.1.1 machine1.yourdomain.com +127.0.1.2 machine2.yourdomain.com +</programlisting> + + </step> + <step> + <para> + Open the <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/all/<replaceable>&lt;PROFILE&gt;</replaceable>/jbossweb.sar/server.xml</filename> file. + </para> + + </step> + <step> + <para> + Uncomment the line: + </para> + +<programlisting language="XML" role="XML">&lt;!-- +&lt;Valve className="org.jboss.web.tomcat.service.sso.ClusteredSingleSignOn" /&gt; +--&gt; +</programlisting> + + </step> + <step> + <para> + And edit it to match the following: + </para> + +<programlisting language="XML" role="XML">&lt;Valve className="org.jboss.web.tomcat.service.sso.ClusteredSingleSignOn" +cookieDomain="yourdomain.com" /&gt; +</programlisting> + <para> + This will ensure the <literal>JSESSIONIDSSO</literal> cookie is used in the correct domain, allowing the SSO authentication to occur. + </para> + + </step> + <step> + <para> + Copy server configuration <emphasis role="bold">all</emphasis> and create another two configurations <emphasis role="bold">node1</emphasis> and <emphasis role="bold">node2</emphasis> from it. + </para> + + </step> + <step> + <para> + Start both cluster nodes with commands: + </para> + +<programlisting> +./run.sh -c node1 -b machine1.yourdomain.com -Dexo.profiles=cluster -Djboss.messaging.ServerPeerID=0 &amp; +./run.sh -c node2 -b machine2.yourdomain.com -Dexo.profiles=cluster -Djboss.messaging.ServerPeerID=1 &amp; +</programlisting> + + </step> + <step> + <para> + Go to <uri>http://machine1.yourdomain.com:8080/portal</uri> and login as a user. + </para> + + </step> + <step> + <para> + Access a private URL on the second host, such as <uri>http://machine2.yourdomain.com:8080/portal/dologin</uri>, for example. + </para> + <para> + Now you should be logged directly into <literal>machine2</literal> thanks to SSO valve. + </para> + + </step> + <step> + <para> + Logout from SSO initiating machine1.yourdomain.com should also logged you out from other cluster nodes. So you should be logout directly from machine2 as well. + </para> + + </step> + + </procedure> + + <formalpara id="form-Reference_Guide_eXo_JCR_1.14-Enabling_SSO_using_JBoss_SSO_Valve-Enabling_SSO_with_Other_Web_Applications"> + <title>Enabling SSO with Other Web Applications</title> + <para> + As mentioned earlier, in order to use SSO authentication between JBoss Enterprise Portal Platform instances and other web applications, the roles defined in the web application must match those used in the portal instance (unless you have the <parameter>requireReauthentication</parameter> parameter set to <literal>true</literal>). + </para> + + </formalpara> + <para> + As an example, to use the SSO Valve to authenticate a user in both a portal instance and the JMX Console, the following actions would be required: + </para> + <procedure> + <title></title> + <step> + <para> + Open the <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/node1/deploy/jmx-console.war/WEB-INF/web.xml</filename> file and edit it as follows: + </para> + <substeps> + <step> + <para> + Change the <parameter>&lt;role-name&gt;</parameter> entry in the <parameter>&lt;auth-constraint&gt;</parameter> element (line <literal>110</literal>) from <literal>JBossAdmin</literal> to <literal>users</literal>: + </para> + +<programlisting language="XML" role="XML">&lt;auth-constraint&gt; + &lt;!--&lt;role-name&gt;JBossAdmin&lt;/role-name&gt;--&gt; + &lt;role-name&gt;users&lt;/role-name&gt; +&lt;/auth-constraint&gt;</programlisting> + + </step> + <step> + <para> + Change the <parameter>&lt;role-name&gt;</parameter> entry in the <parameter>&lt;security-role&gt;</parameter> element (line <literal>120</literal>) from <literal>JBossAdmin</literal> to <literal>users</literal> + </para> + +<programlisting language="XML" role="XML">&lt;security-role&gt; + &lt;!--&lt;role-name&gt;JBossAdmin&lt;/role-name&gt;--&gt; + &lt;role-name&gt;users&lt;/role-name&gt; +&lt;/security-role&gt;</programlisting> + + </step> + + </substeps> + + </step> + + </procedure> + + <formalpara id="form-Reference_Guide_eXo_JCR_1.14-Enabling_SSO_using_JBoss_SSO_Valve-Testing_SSO_With_Other_Web_Applications"> + <title>Testing SSO With Other Web Applications</title> + <para> + To test that SSO authentication is enabled from portal instances to other web applications (in this case, the JMX Console), do the following: + </para> + + </formalpara> + <procedure id="proc-Reference_Guide_eXo_JCR_1.14-Enabling_SSO_using_JBoss_SSO_Valve-Test_SSO_Between_Portal_and_JMX_Console"> + <title>Test SSO Between Portal and JMX Console</title> + <step> + <para> + Start a portal instance on one node: + </para> + +<programlisting>./run.sh -c node1 -b machine1.yourdomain.com -Dexo.profiles=cluster -Djboss.messaging.ServerPeerID=0 &amp; +</programlisting> + + </step> + <step> + <para> + Navigate to <uri>http://machine1.yourdomain.com:8080/portal/private/classic</uri> and authenticate with the pre-configured user account "<systemitem>root</systemitem>" (password "<systemitem>gtn </systemitem>"). + </para> + + </step> + <step> + <para> + Navigate to <uri>http://machine1.yourdomain.com:8080/jmx-console</uri>. You should be automatically authenticated into the JMX Console. + </para> + + </step> + + </procedure> + + <formalpara id="form-Reference_Guide_eXo_JCR_1.14-Enabling_SSO_using_JBoss_SSO_Valve-Using_SSO_to_Authenticate_From_the_Public_Page"> + <title>Using SSO to Authenticate From the Public Page</title> + <para> + The previous configuration changes in this section are useful if a user is using a secured URL (<ulink type="http" url="http://localhost:8080/portal/private/classic" />, for example) to log in to the portal instance. + </para> + + </formalpara> + <para> + Further changes are needed however, if SSO authentication is required to work with the <guilabel>Sign In</guilabel> button on the front page of the portal (<ulink type="http" url="http://localhost:8080/portal/classic" />). + </para> + <para> + To enable this functionality, the <guilabel>Sign In</guilabel> link must redirect to some secured URL, which will ensure that JAAS authentication will be enforced directly without showing login dialog. + </para> + <procedure id="proc-Reference_Guide_eXo_JCR_1.14-Enabling_SSO_using_JBoss_SSO_Valve-Redirect_to_Use_SSO_Valve_Authentication"> + <title>Redirect to Use SSO Valve Authentication</title> + <step> + <para> + Open the <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/web.war/groovy/groovy/webui/component/UIBannerPortlet.gtml</filename> file and edit the line: + </para> + +<programlisting language="Java" role="java">&lt;a class="Login" onclick="$signInAction"&gt;&lt;%=_ctx.appRes("UILoginForm.label.Signin")%&gt;&lt;/a&gt; +</programlisting> + <para> + To read: + </para> + +<programlisting language="Java" role="java">&lt;a class="Login" href="/portal/private/classic"&gt;&lt;%=_ctx.appRes("UILoginForm.label.Signin")%&gt;&lt;/a&gt; +</programlisting> + + </step> + <step> + <para> + Open the <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/web.war/groovy/portal/webui/component/UILogoPortlet.gtmpl</filename> file and change the line: + </para> + +<programlisting language="Java" role="java">&lt;a onclick="$signInAction"&gt;&lt;%=_ctx.appRes("UILogoPortlet.action.signin")%&gt;&lt;/a&gt; +</programlisting> + <para> + To read: + </para> + +<programlisting language="Java" role="java">&lt;a href="/portal/private/classic"&gt;&lt;%=_ctx.appRes("UILogoPortlet.action.signin")%&gt;&lt;/a&gt; +</programlisting> + + </step> + + </procedure> + + + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-SSO_Single_Sign_On_-Central_Authentication_Service"> + <title>Central Authentication Service</title> + <para> + This Single Sign On plugin enables seamless integration between JBoss Enterprise Portal Platform and the Central Authentication Service (<emphasis role="bold">CAS</emphasis>) Single Sign On Framework. Details about CAS can be found <ulink url="http://www.ja-sig.org/cas/"> here </ulink> . + </para> + <para> + The integration consists of two parts; the first part consists of installing or configuring a CAS server, the second part consists of setting up the portal to use the CAS server. + </para> + <procedure id="proc-Reference_Guide_eXo_JCR_1.14-Central_Authentication_Service-CAS_server"> + <title>CAS server</title> + <step> + <para> + Set up the server to authenticate against the portal login module. + </para> + + </step> + <step> + <para> + Downloaded CAS from <ulink type="http" url="http://www.jasig.org/cas/download"> http://www.jasig.org/cas/download </ulink> . + </para> + <para> + The version, tested with these instructions is <emphasis role="bold">CAS 3.3.5</emphasis>. Other versions may work. + </para> + + </step> + <step> + <para> + Extract the downloaded file into a suitable location. This location will be referred to as <replaceable>CAS_DIR</replaceable> in the following example. + </para> + + </step> + + </procedure> + + <para> + The simplest way to configure the web archive is to make the necessary changes directly into the CAS codebase. + </para> + <note> + <para> + To perform the final build step and complete these instructions you will need the Apache Maven 2. Download it from <ulink type="http" url="http://maven.apache.org/download.html"> here </ulink> . + </para> + + </note> + <para> + Change the default authentication handler with the one provided by JBoss Enterprise Portal Platform. + </para> + <para> + The CAS Server Plugin makes secure callbacks to a RESTful service installed on the remote JBoss Enterprise Portal Platform server to authenticate a user. + </para> + <para> + In order for the plugin to function correctly, it needs to be properly configured to connect to this service. This configuration is controlled by the <filename>cas.war/WEB-INF/deployerConfigContext.xml </filename> file. + </para> + <procedure id="proc-Reference_Guide_eXo_JCR_1.14-Central_Authentication_Service-Modifying_CAS_server"> + <title>Modifying CAS server</title> + <step> + <para> + Open <filename><replaceable>CAS_DIR</replaceable>/cas-server-webapp/src/main/webapp/WEB-INF/deployerConfigContext.xml</filename> + </para> + + </step> + <step> + <para> + Replace this code: + </para> + +<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default102.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + <para> + with the following (ensure you set the host, port and context with the values corresponding to your portal). Also available in <filename>GATEIN_SSO_HOME/cas/plugin/WEB-INF/deployerConfigContext.xml</filename>.): + </para> + +<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default103.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + + </step> + <step> + <para> + Copy <filename><replaceable>PORTAL_SSO</replaceable>/cas/plugin/WEB-INF/lib/sso-cas-plugin-&lt;VERSION&gt;.jar</filename> and <filename><replaceable>PORTAL_SSO</replaceable>/cas/plugin/WEB-INF/lib/commons-httpclient-&lt;VERSION&gt;.jar</filename> into the <filename><replaceable>CAS_DIR</replaceable>/cas-server-webapp/src/main/webapp/WEB-INF/lib</filename> created directory. + </para> + + </step> + <step> + <para> + If you have not already done so, download an instance of Tomcat and extract it into a suitable location (which will be called <filename>TOMCAT_HOME</filename> for these instructions). + </para> + + </step> + <step> + <para> + Edit <filename>TOMCAT_HOME/conf/server.xml</filename> and change the 8080 port to 8888 to avoid a conflict with the default JBoss Enterprise Portal Platform. + </para> + <note> + <para> + If JBoss Enterprise Portal Platform is running on the same machine as Tomcat other ports will need to be changed in addition to 8080 in order to avoid conflicts. They can be changed to any free port. For example; you can change the admin port from 8005 to 8805 and the AJP port from 8009 to 8809. + </para> + + </note> + + </step> + <step> + <para> + Navigate locally to the <filename><replaceable>CAS_DIR</replaceable>/cas-server-webapp</filename> directory and execute the following command: + </para> + +<programlisting>mvn install +</programlisting> + + </step> + <step> + <para> + Copy the <filename><replaceable>CAS_DIR</replaceable>/cas-server-webapp/target/cas.war</filename> file into the <filename>TOMCAT_HOME/webapps</filename> directory. + </para> + <para> + Tomcat should start without issue and should be accessible at <ulink type="http" url="http://localhost:8888/cas"> http://localhost:8888/cas </ulink> . + </para> + <note> + <para> + At this stage the login functionality will not be available. + </para> + + </note> + <mediaobject> + <imageobject> + <imagedata fileref="images/AuthenticationAndIdentity/SSO/cas.png" format="PNG" scale="100" width="444" /> + </imageobject> + + </mediaobject> + + </step> + + </procedure> + + <note> + <para> + On logout, the CAS server will display the CAS logout page with a link to return to the portal. To make the CAS server redirect to the portal page after a logout, modify the <filename>cas.war/WEB-INF/cas-servlet.xml</filename> to include the follow line : + </para> + +<programlisting> +&lt;bean id="logoutController" class="org.jasig.cas.web.LogoutController" + p:centralAuthenticationService-ref="centralAuthenticationService" + p:logoutView="casLogoutView" + p:warnCookieGenerator-ref="warnCookieGenerator" + p:ticketGrantingTicketCookieGenerator-ref="ticketGrantingTicketCookieGenerator" + p:followServiceRedirects="true"/&gt; +</programlisting> + + </note> + <procedure id="proc-Reference_Guide_eXo_JCR_1.14-Central_Authentication_Service-Setup_the_CAS_client"> + <title>Setup the CAS client</title> + <step> + <para> + Copy all the libraries from the <filename><replaceable>PORTAL_SSO</replaceable>/cas/gatein.ear/lib</filename> directory into the <filename>JBOSS_HOME/server/default/deploy/gatein.ear/lib</filename>) directory. + </para> + + </step> + <step> + <para> + Edit the <filename>jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/META-INF/gatein-jboss-beans.xml</filename> and uncomment this section: + </para> + +<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default105.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + <para> + There's a line comment already in this source file to assist you. + </para> + <!-- Removing as per https://issues.jboss.org/browse/JBEPP-1350 + <para> + In Tomcat, edit <filename>GATEIN_HOME/conf/jaas.conf</filename>, uncomment on this section and comment other parts: + </para> +<programlisting>org.gatein.sso.agent.login.SSOLoginModule required; +org.exoplatform.services.security.j2ee.TomcatLoginModule required +portalContainerName=portal +realmName=gatein-domain; +</programlisting> + --> + </step> + <step> + <para> + The installation can be tested at this point (assuming the CAS server on Tomcat is running): + </para> + <procedure> + <step> + <para> + Start (or restart) JBoss Enterprise Portal Platform and direct your web browser to <ulink type="http" url="http://localhost:8888/cas"> http://localhost:8888/cas </ulink> . + </para> + + </step> + <step> + <para> + Login with the username <literal>root</literal> and the password <literal>gtn</literal> (or any other account created through the portal). + </para> + + </step> + + </procedure> + + + </step> + + </procedure> + + <para> + To utilize the Central Authentication Service, JBoss Enterprise Portal Platform needs to redirect all user authentication to the CAS server. + </para> + <para> + Information about where the CAS is hosted must be properly configured within the JBoss Enterprise Portal Platform instance. The required configuration is done by modifying three files. + </para> + <procedure id="proc-Reference_Guide_eXo_JCR_1.14-Central_Authentication_Service-Redirect_to_CAS"> + <title>Redirect to CAS</title> + <step> + <para> + Modify the '<emphasis role="bold">Sign In</emphasis>' link in the <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/web.war/groovy/groovy/webui/component/UIBannerPortlet.gtml</filename> file as follows: + </para> + +<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default106.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + + </step> + <step> + <para> + Modify the '<emphasis role="bold">Sign In</emphasis>' link in the <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/web.war/groovy/portal/webui/component/UILogoPortlet.gtmpl</filename> file as follows: + </para> + +<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default107.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + + </step> + <step> + <para> + Replace the entire contents of <filename>gatein.ear/02portal.war/login/jsp/login.jsp</filename> with: + </para> + +<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default108.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + + </step> + <step> + <para> + Add the following Filters at the top of the filter chain in <filename>gatein.ear/02portal.war/WEB-INF/web.xml</filename>: + </para> + +<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default109.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + + </step> + + </procedure> + + <para> + Once these changes have been made, all links to the user authentication pages will redirect to the CAS centralized authentication form and CAS can be used as an SSO implementation in your portal. + </para> + + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-SSO_Single_Sign_On_-Java_Open_Single_Sign_On_Project"> + <title>Java Open Single Sign-On Project</title> + <para> + This Single Sign On plugin enables seamless integration between JBoss Enterprise Portal Platform and the Java Open Single Sign-On Project (<emphasis role="bold">JOSSO</emphasis>) Single Sign On Framework. Details about JOSSO can be found at <ulink url="http://www.josso.org"> www.josso.org </ulink> . + </para> + <para> + This section details setting up the JOSSO server to authenticate against the JBoss Enterprise Portal Platform login module. + </para> + <procedure id="proc-Reference_Guide_eXo_JCR_1.14-Java_Open_Single_Sign_On_Project-JOSSO_server"> + <title>JOSSO server</title> + <step> + <para> + Download JOSSO from <ulink type="http" url="http://sourceforge.net/projects/josso/files/"> http://sourceforge.net/projects/josso/files/ </ulink> . + </para> + <note> + <para> + Use the package that embeds Apache Tomcat. The integration was tested with JOSSO-1.8.1. + </para> + + </note> + + </step> + <step> + <para> + Extract the package into what will be called <filename>JOSSO_HOME</filename> in this example. + </para> + + </step> + + </procedure> + + <procedure id="proc-Reference_Guide_eXo_JCR_1.14-Java_Open_Single_Sign_On_Project-Modifying_JOSSO_server"> + <title>Modifying JOSSO server</title> + <step> + <para> + Copy the files from <filename><replaceable>PORTAL_SSO</replaceable>/josso/plugin</filename> into the <filename>JOSSO_HOME</filename> directory created in the last step. + </para> + <para> + This action should replace or add the following files to the <filename>JOSSO_HOME/webapps/josso/WEB-INF/lib</filename> directory: + </para> + <itemizedlist> + <listitem> + <para> + <filename>JOSSO_HOME/lib/josso-gateway-config.xml</filename> + </para> + + </listitem> + <listitem> + <para> + <filename>JOSSO_HOME/lib/josso-gateway-gatein-stores.xml</filename> + </para> + + </listitem> + <listitem> + <para> + <filename>JOSSO_HOME/webapps/josso/WEB-INF/classes/gatein.properties</filename> + </para> + + </listitem> + + </itemizedlist> + + </step> + <step> + <para> + Edit <filename>TOMCAT_HOME/conf/server.xml</filename> file and change the 8080 port to 8888 to avoid a conflict with the default JBoss Enterprise Portal Platform port. + <note> + <title>Port Conflicts</title> + <para> + If JBoss Enterprise Portal Platform is running on the same machine as Tomcat, other ports need to be changed in addition to 8080 in order to avoid port conflicts. They can be changed to any free port. For example, you can change admin port from 8005 to 8805, and AJP port from 8009 to 8809. + </para> + + </note> + + </para> + + </step> + <step> + <para> + Tomcat will start and allow access to <ulink type="http" url="http://localhost:8888/josso/signon/login.do"> http://localhost:8888/josso/signon/login.do </ulink> but at this stage login will not be available. + </para> + <mediaobject> + <imageobject> + <imagedata fileref="images/AuthenticationAndIdentity/SSO/opensso.png" format="PNG" width="444" /> + </imageobject> + + </mediaobject> + + </step> + + </procedure> + + <procedure id="proc-Reference_Guide_eXo_JCR_1.14-Java_Open_Single_Sign_On_Project-Setup_the_JOSSO_client"> + <title>Setup the JOSSO client</title> + <step> + <para> + Copy the library files from <filename><replaceable>PORTAL_SSO</replaceable>/josso/gatein.ear/lib</filename> into <filename>gatein.ear/lib</filename> (or into <filename>GATEIN_HOME/lib</filename> if the product is running in Tomcat). + </para> + + </step> + <step> + <para> + Copy the <filename><replaceable>PORTAL_SSO</replaceable>/josso/gatein.ear/portal.war/WEB-INF/classes/josso-agent-config.xml</filename> file into the <filename>gatein.ear/02portal.war/WEB-INF/classes</filename> directory (or into <filename>JBOSS_HOME/webapps/portal.war/WEB-INF/classes</filename>, or <filename>GATEIN_HOME/conf</filename> if the product is running in Tomcat). + </para> + + </step> + <step> + <para> + Edit <filename>jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/META-INF/gatein-jboss-beans.xml</filename> and uncomment this section: + </para> + +<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default111.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + + </step> + <step> + <para> + In Tomcat, edit <filename>JBOSS_HOME/conf/jaas.conf</filename> and uncomment this section: + </para> + +<programlisting>org.gatein.sso.agent.login.SSOLoginModule required; +org.exoplatform.services.security.j2ee.TomcatLoginModule requiredtm +portalContainerName=portal +realmName=gatein-domain; +</programlisting> + + </step> + <step> + <para> + The installation can be tested at this point. + </para> + <substeps> + <step> + <para> + Start (or restart) JBoss Enterprise Portal Platform, and (assuming the JOSSO server on Tomcat is running) direct your browser to <ulink type="http" url="http://localhost:8888/josso/signon/login.do"> http://localhost:8888/josso/signon/login.do </ulink> . + </para> + + </step> + <step> + <para> + Login with the username <literal>root</literal> and the password <literal>gtn</literal> or any account created through the portal. + </para> + + </step> + + </substeps> + + </step> + + </procedure> + + <para> + The next part of the process is to redirect all user authentication to the JOSSO server. + </para> + <para> + Information about where the JOSSO server is hosted must be properly configured within the JBoss Enterprise Portal Platform instance. The required configuration is done by modifying four files: + </para> + <procedure id="proc-Reference_Guide_eXo_JCR_1.14-Java_Open_Single_Sign_On_Project-Setup_the_portal_to_redirect_to_JOSSO"> + <title>Setup the portal to redirect to JOSSO</title> + <step> + <para> + In the <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/web.war/groovy/groovy/webui/component/UIBannerPortlet.gtml</filename> file modify the 'Sign In' link as follows: + </para> + +<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default112.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + + </step> + <step> + <para> + Modify the '<emphasis role="bold">Sign In</emphasis>' link in the <filename>gatein.ear/web.war/groovy/portal/webui/component/UILogoPortlet.gtmpl</filename> file as follows: + </para> + +<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default113.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + + </step> + <step> + <para> + Replace the entire contents of <filename>gatein.ear/02portal.war/login/jsp/login.jsp</filename> with: + </para> + +<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default114.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + + </step> + <step> + <para> + Add the following Filters to the top of the filter chain in <filename>gatein.ear/02portal.war/WEB-INF/web.xml</filename>: + </para> + +<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default115.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + + </step> + + </procedure> + + <para> + From now on, all links redirecting to the user authentication pages will redirect to the JOSSO centralized authentication form. + </para> + + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-SSO_Single_Sign_On_-OpenSSO"> + <title>OpenSSO</title> + <para> + This section details the setting up of OpenSSO server to authenticate against the JBoss Enterprise Portal Platform login module. + </para> + <procedure id="proc-Reference_Guide_eXo_JCR_1.14-OpenSSO-Obtaining_OpenSSO"> + <title>Obtaining OpenSSO</title> + <step> + <para> + OpenSSO must be purchased from <ulink type="http" url="http://www.oracle.com/technetwork/middleware/id-mgmt/overview/i... Oracle </ulink> . + </para> + <para> + For testing purposes, use OpenSSO_80U2, which can be downloaded from <ulink type="http" url="http://download.oracle.com/otn/nt/middleware/11g/oracle_opensso... </ulink> . + </para> + + </step> + <step> + <para> + Extract the package into a suitable location. This location will be referred to as <filename>OPENSSO_HOME</filename> in this example. + </para> + + </step> + + </procedure> + + <note> + <para> + It is also possible to use OpenAM instead of OpenSSO server. OpenAM is free and the integration steps between Enterprise Portal Platform and OpenAM are very similar as with OpenSSO. More info is available <ulink type="http" url="http://community.jboss.org/wiki/GateInAndOpenAMIntegration"... here </ulink> . + </para> + + </note> + + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-SSO_Single_Sign_On_-Modifying_the_OpenSSO_server"> + <title>Modifying the OpenSSO server</title> + <para> + To configure the web server as required, it is simpler to directly modify the source files. + </para> + <para> + The first step is to add the JBoss Enterprise Portal Platform Authentication Plugin. + </para> + <para> + The plugin makes secure callbacks to a RESTful service installed on the remote JBoss Enterprise Portal Platform server to authenticate a user. + </para> + <para> + In order for the plugin to function correctly, it needs to be properly configured to connect to this service. This configuration is done via the <filename>opensso.war/config/auth/default/AuthenticationPlugin.xml</filename> file. + </para> + <procedure id="proc-Reference_Guide_eXo_JCR_1.14-Modifying_the_OpenSSO_server-Modifying_OpenSSO_server"> + <title>Modifying OpenSSO server</title> + <step> + <para> + Obtain a copy of Tomcat and extract it into a suitable location. This location will be referred to as <filename>TOMCAT_HOME</filename> in this example. + </para> + + </step> + <step> + <para> + Edit <filename>TOMCAT_HOME/conf/server.xml</filename> and change the 8080 port to 8888 to avoid a conflict with the default JBoss Enterprise Portal Platform port. + <note> + <para> + If JBoss Enterprise Portal Platform is running on the same machine as Tomcat, other ports need to be changed in addition to 8080 in order to avoid port conflicts. They can be changed to any free port. For example, you can change the admin port from 8005 to 8805 and the AJP port from 8009 to 8809. + </para> + + </note> + + </para> + + </step> + <step> + <para> + Ensure the <filename>TOMCAT_HOME/webapps/opensso/config/auth/default/AuthenticationPlugin.xml</filename> file matches the following: + </para> + +<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default117.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + + </step> + <step> + <para> + Copy the following files into the Tomcat directory at <filename>TOMCAT_HOME/webapps/opensso/WEB-INF/lib</filename>: + </para> + <itemizedlist> + <listitem> + <para> + <filename><replaceable>PORTAL_SSO</replaceable>/opensso/plugin/WEB-INF/lib/sso-opensso-plugin-&lt;VERSION&gt;.jar</filename> + </para> + + </listitem> + <listitem> + <para> + <filename><replaceable>PORTAL_SSO</replaceable>/opensso/plugin/WEB-INF/lib/commons-httpclient-&lt;VERSION&gt;.jar</filename> + </para> + + </listitem> + <listitem> + <para> + <filename><replaceable>PORTAL_SSO</replaceable>/opensso/plugin/WEB-INF/lib/commons-logging-&lt;VERSION&gt;.jar</filename> + </para> + + </listitem> + + </itemizedlist> + + </step> + <step> + <para> + Copy the <filename><replaceable>PORTAL_SSO</replaceable>/opensso/plugin/WEB-INF/classes/gatein.properties</filename> file into the <filename>TOMCAT_HOME/webapps/opensso/WEB-INF/classes</filename> directory. + </para> + + </step> + <step> + <para> + Tomcat should start and be able to access <ulink type="http" url="http://localhost:8888/opensso/UI/Login?realm=gatein"> http://localhost:8888/opensso/UI/Login?realm=gatein </ulink> . + </para> + <mediaobject> + <imageobject role="html"> + <imagedata align="center" fileref="images/AuthenticationAndIdentity/SSO/opensso-shot.png" format="PNG" scale="110" width="444" /> + </imageobject> + <imageobject role="fo"> + <imagedata align="center" contentwidth="150mm" fileref="images/AuthenticationAndIdentity/SSO/opensso-shot.png" format="PNG" width="444" /> + </imageobject> + + </mediaobject> + <note> + <para> + Login will not be available at this point. + </para> + + </note> + + </step> + + </procedure> + + <procedure id="proc-Reference_Guide_eXo_JCR_1.14-Modifying_the_OpenSSO_server-Configure_the_gatein_realm"> + <title>Configure the "gatein" realm</title> + <step> + <para> + Direct your browser to <ulink type="http" url="http://localhost:8888/opensso"> http://localhost:8888/opensso </ulink> + </para> + + </step> + <step> + <para> + Create a default configuration. + </para> + + </step> + <step> + <para> + Login as <literal>amadmin</literal>. + </para> + <important> + <para> + Go to <menuchoice><guimenu>Configuration</guimenu> <guimenuitem> Authentication </guimenuitem> </menuchoice> and follow the link to <guilabel>Core</guilabel> + </para> + <para> + Add a new value with the class name <literal>org.gatein.sso.opensso.plugin.AuthenticationPlugin</literal>. + </para> + <para> + If this is not done <literal>AuthenticationPlugin</literal> is not available among other OpenSSO authentication modules. + </para> + + </important> + + </step> + <step> + <para> + Go to the <guilabel>Access control</guilabel> tab and create new realm called <literal>gatein</literal>. + </para> + + </step> + <step> + <substeps> + <step> + <para> + Go to the new <literal>gatein</literal> realm and click on the <guilabel>Authentication</guilabel> tab. + </para> + + </step> + <step> + <para> + Click on <guilabel>ldapService</guilabel> (at the bottom in the <guilabel>Authentication chaining</guilabel> section). + </para> + + </step> + <step> + <para> + Change the selection from <literal>Datastore</literal>, which is the default module in the authentication chain, to <literal>AuthenticationPlugin</literal>. + </para> + + </step> + + </substeps> + <para> + These changes enable authentication of the <literal>gatein</literal> realm using the <literal>GateIn REST</literal> service instead of the OpenSSO LDAP server. + </para> + + </step> + <step> + <para> + Go to <guilabel>Advanced properties</guilabel> and change <literal>UserProfile</literal> from <parameter>Required</parameter> to <parameter>Dynamic</parameter> to ensure all new users are automatically created in the OpenSSO datastore after successful authentication. + </para> + + </step> + <step> + <para> + Increase the user privileges to allow REST access with the following procedure: + </para> + <substeps> + <step> + <para> + Go to <menuchoice><guimenu>Access control</guimenu> <guimenuitem> Top level realm </guimenuitem> <guimenuitem> Privileges </guimenuitem> <guimenuitem> All authenticated users </guimenuitem> </menuchoice>. + </para> + + </step> + <step> + <para> + Check the last two checkboxes: + </para> + <itemizedlist> + <listitem> + <para> + Read and write access only for policy properties + </para> + + </listitem> + <listitem> + <para> + Read and write access to all realm and policy properties + </para> + + </listitem> + + </itemizedlist> + + </step> + + </substeps> + + </step> + <step> + <para> + Repeat step 7 for the '<literal>gatein</literal>' realm as well. + </para> + + </step> + + </procedure> + + + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-SSO_Single_Sign_On_-Setup_the_OpenSSO_Client"> + <title>Setup the OpenSSO Client</title> + <procedure id="proc-Reference_Guide_eXo_JCR_1.14-Setup_the_OpenSSO_Client-Setup_the_OpenSSO_client"> + <title>Setup the OpenSSO client</title> + <step> + <para> + Copy all libraries from the <filename><replaceable>PORTAL_SSO</replaceable>/opensso/gatein.ear/lib</filename> directory into the <filename>JBOSS_HOME/server/default/deploy/gatein.ear/lib</filename> directory. + </para> + <para> + Alternatively, in a Tomcat environment, copy the libraries into the <filename>JBOSS_HOME/lib</filename> directory. + </para> + + </step> + <step> + <para> + Edit the <filename>jboss-as/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/META-INF/gatein-jboss-beans.xml</filename> and uncomment this section: + </para> + +<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default118.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + + </step> + <!-- Removed as per https://issues.jboss.org/browse/JBEPP-1350 + <step> + <para> + If you are running the product in Tomcat, edit <replaceable>&lt;JBOSS_HOME&gt;</replaceable>/conf/jaas.conf, uncomment the following section and comment all other sections: + </para> +<programlisting>org.gatein.sso.agent.login.SSOLoginModule required; +org.exoplatform.services.security.j2ee.TomcatLoginModule required +portalContainerName=portal +realmName=gatein-domain; +</programlisting> + </step> + --> <step> + <para> + Test the installation: + </para> + <procedure> + <step> + <para> + Access JBoss Enterprise Portal Platform by going to <ulink type="http" url="http://localhost:8888/opensso/UI/Login?realm=gatein"> http://localhost:8888/opensso/UI/Login?realm=gatein </ulink> (assuming that the OpenSSO server using Tomcat is still running). + </para> + + </step> + <step> + <para> + Login with the username <literal>root</literal> and the password <literal>gtn</literal> or any account created through the portal. + </para> + + </step> + + </procedure> + + + </step> + + </procedure> + + + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-SSO_Single_Sign_On_-Setup_the_portal_to_redirect_to_OpenSSO"> + <title>Setup the portal to redirect to OpenSSO</title> + <para> + The next part of the process is to redirect all user authentication to the OpenSSO server. + </para> + <para> + Information about where the OpenSSO server is hosted must be properly configured within the Enterprise Portal Platform instance. The required configuration is done by modifying three files: + </para> + <procedure id="proc-Reference_Guide_eXo_JCR_1.14-Setup_the_portal_to_redirect_to_OpenSSO-Setup_the_portal_to_redirect_to_OpenSSO"> + <title>Setup the portal to redirect to OpenSSO</title> + <step> + <para> + Modify the '<emphasis role="bold">Sign In</emphasis>' link in the <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/web.war/groovy/groovy/webui/component/UIBannerPortlet.gtml</filename> file as follows: + </para> + +<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default119.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + + </step> + <step> + <para> + Modify the '<emphasis role="bold">Sign In</emphasis>' link in the <filename>gatein.ear/web.war/groovy/portal/webui/component/UILogoPortlet.gtmpl</filename> file as follows: + </para> + +<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default120.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + + </step> + <step> + <para> + Replace the entire contents of <filename>gatein.ear/02portal.war/login/jsp/login.jsp</filename> with: + </para> + +<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default121.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + + </step> + <step> + <para> + Add the following Filters to the top of the filter chain in <filename>gatein.ear/02portal.war/WEB-INF/web.xml</filename>: + </para> + +<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default122.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + + </step> + + </procedure> + + <para> + From now on, all links redirecting to the user authentication pages will redirect to the OpenSSO centralized authentication form. + </para> + + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-SSO_Single_Sign_On_-SPNEGO_Simple_and_Protected_GSSAPI_Negotiation_Mechanism"> + <title>SPNEGO - Simple and Protected GSSAPI Negotiation Mechanism</title> + <para> + The Simple and Protected GSSAPI Negotiation Mechanism (<emphasis role="bold">SPNEGO</emphasis>) uses desktop credentials provided during a desktop login to transparently authenticate a portal user through a web browser. + </para> + <para> + For illustrative purposes; a typical use case would be: + </para> + <procedure> + <step> + <para> + A user logs into their desktop computer with a login that is governed by an Active Directory domain. + </para> + + </step> + <step> + <para> + The user then launches a web browser to access a web application (that uses JBoss Negotiation) hosted on JBoss Enterprise Portal Platform. + </para> + + </step> + <step> + <para> + The browser transfers the desktop credentials to the web application. + </para> + + </step> + <step> + <para> + JBoss EAP/AS uses background GSS messages with the Active Directory (or any Kerberos Server) to validate the Kerberos ticket from user. + </para> + + </step> + <step> + <para> + The user experiences a seamless single sign on (SSO) into the web application. + </para> + + </step> + + </procedure> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-SPNEGO_Simple_and_Protected_GSSAPI_Negotiation_Mechanism-SPNEGO_Server_Configuration"> + <title>SPNEGO Server Configuration</title> + <para> + In this section, we will describe some necessary steps for setup Kerberos server on Linux. This server will then be used for SPNEGO authentication against JBoss Enterprise Portal Platform. + </para> + <note> + <title>SPNEGO Basics</title> + <para> + The procedure below only describes the basic steps to configure the SPNEGO server in a Linux environment. If you are already familiar with SPNEGO, or if you are using Windows and Active Directory domain, you can jump to the <xref linkend="proc-Reference_Guide_eXo_JCR_1.14-JBoss_Enterprise_Portal_Platform_Configuration-Advanced_SPNEGO_Configuration" /> to see how to integrate SPNEGO with JBoss Enterprise Portal Platform. + </para> + <para> + Please note that Kerberos setup is also dependent on your Linux distribution and so steps can be slightly different in your environment. + </para> + + </note> + <procedure id="proc-Reference_Guide_eXo_JCR_1.14-SPNEGO_Server_Configuration-SPNEGO_Basics"> + <title>SPNEGO Basics</title> + <step> + <para> + Correct the setup of network on the machine. For example, if you are using the "server.local.network" domain as your machine where Kerberos and JBoss Enterprise Portal Platform are localed, add the line containing the machine's IP address to the <emphasis role="bold">/etc/host </emphasis> file. + </para> + +<programlisting> +192.168.1.88 server.local.network +</programlisting> + <note> + <para> + It is not recommended you use loopback addresses. + </para> + + </note> + + </step> + <step> + <para> + Install Kerberos with these packages: krb5-admin-server, krb5-kdc, krb5-config, krb5-user, krb5-clients, and krb5-rsh-server. + </para> + + </step> + <step> + <para> + Edit the Kerberos configuration file at <emphasis role="bold">/etc/krb5.config</emphasis>, including: + </para> + <itemizedlist> + <listitem> + <para> + Uncomment on these lines: + </para> + +<programlisting> +default_tgs_enctypes = des3-hmac-sha1 +default_tkt_enctypes = des3-hmac-sha1 +permitted_enctypes = des3-hmac-sha1 +</programlisting> + + </listitem> + <listitem> + <para> + Add <emphasis role="bold">local.network</emphasis> as a default realm and it is also added to the list of realms and remove the remains of realms. The content looks like: + </para> + +<programlisting> +[libdefaults] + default_realm = LOCAL.NETWORK + +# The following krb5.conf variables are only for MIT Kerberos. + krb4_config = /etc/krb.conf + krb4_realms = /etc/krb.realms + kdc_timesync = 1 + ccache_type = 4 + forwardable = true + proxiable = true + +# The following encryption type specification will be used by MIT Kerberos +# if uncommented. In general, the defaults in the MIT Kerberos code are +# correct and overriding these specifications only serves to disable new +# encryption types as they are added, creating interoperability problems. +# +# Thie only time when you might need to uncomment these lines and change +# the enctypes is if you have local software that will break on ticket +# caches containing ticket encryption types it doesn't know about (such as +# old versions of Sun Java). + + default_tgs_enctypes = des3-hmac-sha1 + default_tkt_enctypes = des3-hmac-sha1 + permitted_enctypes = des3-hmac-sha1 + +# The following libdefaults parameters are only for Heimdal Kerberos. + v4_instance_resolve = false + v4_name_convert = { + host = { + rcmd = host + ftp = ftp + } + plain = { + something = something-else + } + } + fcc-mit-ticketflags = true + +[realms] + LOCAL.NETWORK = { + kdc = server.local.network + admin_server = server.local.network + } + +[domain_realm] + .local.network = LOCAL.NETWORK + local.network = LOCAL.NETWORK + +[login] + krb4_convert = true + krb4_get_tickets = false +</programlisting> + + </listitem> + + </itemizedlist> + + </step> + <step> + <para> + Edit the KDC configuraton file at <emphasis role="bold">/etc/krb5kdc/kdc.conf</emphasis> that looks like. + </para> + +<programlisting> +[kdcdefaults] + kdc_ports = 750,88 + +[realms] + LOCAL.NETWORK = { + database_name = /home/gatein/krb5kdc/principal + admin_keytab = FILE:/home/gatein/krb5kdc/kadm5.keytab + acl_file = /home/gatein/krb5kdc/kadm5.acl + key_stash_file = /home/gatein/krb5kdc/stash + kdc_ports = 750,88 + max_life = 10h 0m 0s + max_renewable_life = 7d 0h 0m 0s + master_key_type = des3-hmac-sha1 + supported_enctypes = aes256-cts:normal arcfour-hmac:normal des3-hmac-sha1:normal des-cbc-crc:normal des:normal des:v4 des:norealm des:onlyrealm des:afs3 + default_principal_flags = +preauth + } + +[logging] + kdc = FILE:/home/gatein/krb5logs/kdc.log + admin_server = FILE:/home/gatein/krb5logs/kadmin.log +</programlisting> + <itemizedlist> + <listitem> + <para> + Create krb5kdc and krb5logs directory for Kerberos database as shown in the configuration file above. + </para> + + </listitem> + <listitem> + <para> + Next, create a KDC database using the following command. + </para> + +<programlisting> +sudo krb5_newrealm +</programlisting> + + </listitem> + <listitem> + <para> + Start the KDC and Kerberos admin servers using these commands: + </para> + +<programlisting> +sudo /etc/init.d/krb5-kdc restart +sudo /etc/init.d/krb-admin-server restart +</programlisting> + + </listitem> + + </itemizedlist> + + </step> + <step> + <para> + Add Principals and create Keys. + </para> + <itemizedlist> + <listitem> + <para> + Start an interactive 'kadmin' session and create the necessary Principals. + </para> + +<programlisting> +sudo kadmin.local +</programlisting> + + </listitem> + <listitem> + <para> + Add the JBoss Enterprise Portal Platform machine and keytab file that need to be authenticated. + </para> + +<programlisting> +addprinc -randkey HTTP/server.local.network(a)LOCAL.NETWORK +ktadd HTTP/server.local.network(a)LOCAL.NETWORK +</programlisting> + + </listitem> + <listitem> + <para> + Add the default JBoss Enterprise Portal Platform user accounts and enter the password for each created user that will be authenticated. + </para> + +<programlisting> +addprinc john +addprinc demo +addprinc root +</programlisting> + + </listitem> + + </itemizedlist> + + </step> + <step> + <para> + Test your changed setup by using the command. + </para> + +<programlisting> +kinit -A demo +</programlisting> + <itemizedlist> + <listitem> + <para> + If the setup works well, you are required to enter the password created for this user in Step 5. Without the -A, the kerberos ticket validation involved reverse DNS lookups, which can get very cumbersome to debug if your network's DNS setup is not great. This is a production level security feature, which is not necessary in this development setup. In production environment, it will be better to avoid -A option. + </para> + + </listitem> + <listitem> + <para> + After successful login to Kerberos, you can see your Kerberos ticket when using this command. + </para> + +<programlisting> +klist +</programlisting> + + </listitem> + <listitem> + <para> + If you want to logout and destroy your ticket, use this command. + </para> + +<programlisting> +kdestroy +</programlisting> + + </listitem> + + </itemizedlist> + + </step> + + </procedure> + + + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-SPNEGO_Simple_and_Protected_GSSAPI_Negotiation_Mechanism-SPNEGO_Server_Configuration-Clients"> + <title>Clients</title> + <para> + After performing all configurations above, you need to enable the <emphasis role="bold">Negotiate authentication </emphasis> of Firefox in client machines so that clients could be authenticated by JBoss Enterprise Portal Platform as follows: + </para> + <procedure> + <step> + <para> + Start Firefox, then enter the command: <emphasis role="bold">about:config </emphasis> into the address field. + </para> + + </step> + <step> + <para> + Enter <emphasis role="bold">network.negotiate-auth</emphasis> and set the value as below: + </para> + +<programlisting> +network.negotiate-auth.allow-proxies = true +network.negotiate-auth.delegation-uris = .local.network +network.negotiate-auth.gsslib (no-value) +network.negotiate-auth.trusted-uris = .local.network +network.negotiate-auth.using-native-gsslib = true +</programlisting> + + </step> + + </procedure> + + <note> + <para> + Consult documentation of your OS or web browser if using different browser than Firefox. + </para> + + </note> + + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-SPNEGO_Simple_and_Protected_GSSAPI_Negotiation_Mechanism-JBoss_Enterprise_Portal_Platform_Configuration"> + <title>JBoss Enterprise Portal Platform Configuration</title> + <para> + JBoss Enterprise Portal Platform uses JBoss Negotiation to enable SPNEGO-based desktop SSO for the portal. Here are the steps to integrate SPNEGO with JBoss Enterprise Portal Platform. + </para> + <procedure id="proc-Reference_Guide_eXo_JCR_1.14-JBoss_Enterprise_Portal_Platform_Configuration-Advanced_SPNEGO_Configuration"> + <title>Advanced SPNEGO Configuration</title> + <step> + <para> + Activate the Host authentication. Add the following host login module to the <filename>jboss-as/server/<replaceable>PROFILE</replaceable>/conf/login-config.xml</filename>: + </para> + +<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default124.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + <para> + The '<literal>keyTab</literal>' value should point to the keytab file that was generated by the <literal>kadmin</literal> Kerberos tool. When using Kerberos on Linux, it should be value of parameter <emphasis role="bold">admin_keytab</emphasis> from kdc.conf file. See the <xref linkend="proc-Reference_Guide_eXo_JCR_1.14-SPNEGO_Server_Configuration-SPNEGO_Basics" /> for more details. + </para> + + </step> + <step> + <para> + Extend the core authentication mechanisms to support SPNEGO. Under <filename>deployers/jbossweb.deployer/META-INF/war-deployers-jboss-beans.xml</filename>, add a '<literal>SPNEGO</literal>' authenticators property + </para> + +<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default125.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + + </step> + <step> + <para> + Add the GateIn SSO module binaries by copying <emphasis role="bold">GATEIN_SSO_HOME/spnego/gatein.ear/lib/sso-agent-VERSION.jar</emphasis> to the <emphasis role="bold">JBOSS_HOME/server/default/deploy/gatein.ear/lib</emphasis> directory. File <emphasis role="bold">GATEIN_SSO_HOME/spnego/gatein.ear/lib/spnego-VERSION.jar</emphasis> needs to be copied to the <emphasis role="bold">JBOSS_HOME/server/default/lib</emphasis> directory. + </para> + + </step> + <!-- This step not required as EPP already has the correct version of Negotiation 2.0.4.GA + <step> + <para> + Download library <filename>jboss-negotiation-2.0.4.GA</filename> from location + <ulink type="html" url="https://repository.jboss.org/nexus/content/groups/public/org/jb... + and copy this file to <filename>JBOSS_HOME/server/default/lib</filename> directory as well. + </para> + </step> + --> <step> + <para> + Modify the <filename>deploy/gatein.ear/META-INF/gatein-jboss-beans.xml</filename> file to match the following: + </para> + +<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default126.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + <para> + This activates SPNEGO LoginModules with fallback to FORM authentication. When SPNEGO is not available and it needs to fallback to FORM, it will use <emphasis role="bold">gatein-form-auth-domain</emphasis> security domain. + </para> + + </step> + <step> + <para> + Modify <filename>gatein.ear/02portal.war/WEB-INF/web.xml</filename> to match: + </para> + +<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default127.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + <para> + Integrate the request pre-processing needed for SPNEGO via filters by adding the following filters to the <emphasis role="bold">JBOSS_HOME/server/default/deploy/gatein.ear/02portal.war/WEB-INF/web.xml</emphasis> at the top of the Filter chain. + </para> + +<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default128.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + <para> + This integrates request pre-processing needed for SPNEGO. + </para> + + </step> + <step> + <para> + Edit the '<emphasis role="bold">Sign In</emphasis>' link in <filename><replaceable>JBOSS_HOME</replaceable>/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/web.war/groovy/groovy/webui/component/UIBannerPortlet.gtmpl</filename> to match the following: + </para> + +<programlisting language="Java" role="Java"><xi:include href="../../extras/Authentication_Identity_SSO/default129.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + + </step> + <step> + <para> + Start the JBoss Enterprise Portal Platform; + </para> + +<programlisting language="Java" role="Java"><xi:include href="../../extras/Authentication_Identity_SSO/default130.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + <para> + The <replaceable>PROFILE</replaceable> parameter in the above command should be replaced with the server profile modified with the above configuration. + </para> + + </step> + <step> + <para> + Login to Kerberos: + </para> + +<programlisting>kinit -A demo +</programlisting> + + </step> + + </procedure> + + <para> + Clicking the 'Sign In' link on the JBoss Enterprise Portal Platform should automatically sign the 'demo' user into the portal. + </para> + <para> + If you destroy your kerberos ticket with command <command>kdestroy</command>, then try to login again, you will directed to the login screen of JBoss Enterprise Portal Product because you don't have active Kerberos ticket. You can login with predefined account and password "demo"/"gtn" . + </para> + + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-SPNEGO_Simple_and_Protected_GSSAPI_Negotiation_Mechanism-JBoss_Enterprise_Portal_Platform_Configuration-Clients"> + <title>Clients</title> + <para> + After performing all configurations above, you need to enable the <emphasis role="bold">Negotiate authentication </emphasis> of Firefox in clients so that clients can be authenticated by JBoss Enterprise Portal Platform as follows: + </para> + <procedure> + <step> + <para> + Start Firefox, then enter the command: <emphasis role="bold">about:config </emphasis> into the address field. + </para> + + </step> + <step> + <para> + Enter <emphasis role="bold">network.negotiate-auth</emphasis> and set the value as below: + </para> + +<programlisting> +network.negotiate-auth.allow-proxies = true +network.negotiate-auth.delegation-uris = .local.network +network.negotiate-auth.gsslib (no-value) +network.negotiate-auth.trusted-uris = .local.network +network.negotiate-auth.using-native-gsslib = true +</programlisting> + + </step> + + </procedure> + + + </section> + + + </section> + + +</section> + + Copied: epp/docs/branches/5.2/Reference_Guide/en-US/modules/RH-WSRP.xml (from rev 8139, epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/RH-WSRP.xml) =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/RH-WSRP.xml (rev 0) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/RH-WSRP.xml 2011-11-25 00:48:53 UTC (rev 8141) @@ -0,0 +1,2003 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "Reference_Guide_eXo_JCR_1.14.ent"> +%BOOK_ENTITIES; +]> +<chapter id="chap-Reference_Guide_eXo_JCR_1.14-Web_Services_for_Remote_Portlets_WSRP"> + <title><remark>Web Services for Remote Portlets (WSRP)</remark></title> + <section id="sect-Reference_Guide_eXo_JCR_1.14-Web_Services_for_Remote_Portlets_WSRP-Introduction"> + <title>Introduction</title> + <para> + The Web Services for Remote Portlets (WSRP) specification defines a web service interface for accessing and interacting with interactive presentation-oriented web services. + </para> + <para> + It has been produced through the efforts of the Web Services for Remote Portlets (WSRP) OASIS Technical Committee. It is based on the requirements gathered and the proposals made to the committee. + </para> + <para> + Scenarios that motivate WSRP functionality include: + </para> + <itemizedlist> + <listitem> + <para> + Content hosts, such as portal servers, providing Portlets as presentation-oriented web services that can be used by aggregation engines. + </para> + + </listitem> + <listitem> + <para> + Aggregating frameworks, including portal servers, consuming presentation-oriented web services offered by content providers and integrating them into the framework. + </para> + + </listitem> + + </itemizedlist> + <para> + More information on WSRP can be found on the official <ulink url="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wsrp...;. We suggest reading the <ulink url="http://www.oasis-open.org/committees/download.php/10539/wsrp-pr... for a good, albeit technical, overview of WSRP. + </para> + + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Web_Services_for_Remote_Portlets_WSRP-Level_of_Support"> + <title>Level of Support</title> + <para> + The WSRP Technical Committee defined <ulink url="http://www.oasis-open.org/committees/download.php/3073">... Use Profiles</ulink> to help with WSRP interoperability. Terms defined in that document will be used in this section. + </para> + <para> + JBoss Enterprise Portal Platform provides a <emphasis>Simple</emphasis> level of support for the WSRP Producer, with the exception of out-of-band registration. In-band registration and persistent local state (which are defined at the <emphasis>Complex</emphasis> level) are supported. + </para> + <para> + JBoss Enterprise Portal Platform provides a <emphasis>Medium</emphasis> level of support for the Consumer, excepting HTML markup (as JBoss Enterprise Portal Platform itself does not handle other markup types). Explicit portlet cloning and the <literal>PortletManagement</literal> interface are supported. + </para> + <para> + The WSRP component has Level 1 Producer and Consumer caching. Cookie handling is supported properly on the Consumer. The Producer requires cookie initialization (as this improves interoperability with some consumers). + </para> + <para> + JBoss Enterprise Portal Platform does not support custom window states or modes, therefore neither does the WSRP component. It does, however, support CSS on both the Producer (although this is more a function of the portlets than an inherent Producer capability) and Consumer. + </para> + <para> + JBoss Enterprise Portal Platform &VY; includes implementations of WSRP 1.0 and 2.0. + </para> + <para> + All optional features in WSRP 2 are implemented in JBoss Enterprise Portal Platform &VY; except support for lifetimes and leasing support. + </para> + <note> + <para> + As of version &VZ; of Enterprise Portal Platform, WSRP is only activated and supported when deployed on JBoss Enterprise Application Server. + </para> + + </note> + + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Web_Services_for_Remote_Portlets_WSRP-Deploying_WSRP"> + <title>Deploying WSRP</title> + <note> + <title>Notational Devices</title> + <para> + The following list of support files uses the following notational devices: + </para> + <variablelist id="vari-Reference_Guide_eXo_JCR_1.14-Deploying_WSRP-Notations"> + <title>Notations:</title> + <varlistentry> + <term><replaceable>JBOSS_HOME</replaceable></term> + <listitem> + <para> + <replaceable>JBOSS_HOME</replaceable> refers to the directory that your instance of JBoss Enterprise Portal Platform has been extracted/installed to. For example: <filename>/home/<replaceable>USERNAME</replaceable>/jboss-epp-<replaceable>&lt;VERSION&gt;</replaceable>/</filename> + </para> + + </listitem> + + </varlistentry> + <varlistentry> + <term><replaceable>WSRP_PATH</replaceable></term> + <listitem> + <para> + The WSRP files referred to in this section are found in the <filename><replaceable>JBOSS_HOME</replaceable>/jboss-as/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear</filename> directory. + </para> + <para> + For ease of reference this path will be represented by: <replaceable>WSRP_PATH</replaceable>. + </para> + + </listitem> + + </varlistentry> + <varlistentry> + <term><replaceable>WSRP_VERSION</replaceable></term> + <listitem> + <para> + <replaceable>WSRP_VERSION</replaceable> represents the version of the WSRP component in use. + </para> + + </listitem> + + </varlistentry> + <varlistentry> + <term><replaceable>PORTAL_VERSION</replaceable></term> + <listitem> + <para> + <replaceable>PORTAL_VERSION</replaceable> represents the version of JBoss Enterprise Portal Platform in use. + </para> + + </listitem> + + </varlistentry> + + </variablelist> + + </note> + <para> + Starting with version 2.1.0-GA of the component, WSRP is packaged as a JBoss Enterprise Portal Platform extension and is now self-contained in an easy to install package named <filename>gatein-wsrp-integration.ear</filename>, deployed directly in the <filename>deploy</filename> directory of your JBoss Application Server configuration directory. + </para> + <para> + The extension itself is composed of the following components: + </para> + <variablelist id="vari-Reference_Guide_eXo_JCR_1.14-Deploying_WSRP-WSRP_support_files"> + <title>WSRP support files</title> + <varlistentry> + <term><filename>META-INF/</filename></term> + <listitem> + <para> + This directory contains files necessary for EAR packaging. The only file that is of interest from a user perspective is <filename>gatein-wsse-consumer.xml</filename> which allows you to configure WS-Security support for the consumer. + </para> + <para> + Refer to <xref linkend="sect-Reference_Guide_eXo_JCR_1.14-WSRP_and_WS_Security-WS_Security_Configuration" /> section for more details. + </para> + + </listitem> + + </varlistentry> + <varlistentry> + <term><filename>extension-component-$PORTAL_VERSION.jar</filename></term> + <listitem> + <para> + This archive which contains the components needed to integrate the WSRP component into JBoss Enterprise Portal Platform. It also includes the default configuration files for the WSRP producer and the default WSRP consumers. + </para> + + </listitem> + + </varlistentry> + <varlistentry> + <term><filename>extension-config-$PORTAL_VERSION.jar</filename></term> + <listitem> + <para> + This file contains the configuration file needed by the GateIn extension mechanism to properly register this EAR as an extension. + </para> + + </listitem> + + </varlistentry> + <varlistentry> + <term><filename>extension-war-$PORTAL_VERSION.war</filename></term> + <listitem> + <para> + This file contains the configuration files needed by the GateIn extension mechanism to properly setup the WSRP service. It includes <filename>wsrp-configuration.xml</filename> which, in particular, configures several options for the <code> WSRPServiceIntegration </code> component at the heart of the WSRP integration in JBoss Enterprise Portal Platform. + </para> + + </listitem> + + </varlistentry> + <varlistentry> + <term><filename>lib/</filename></term> + <listitem> + <para> + This directory contains the different libraries needed by the WSRP service. + </para> + + </listitem> + + </varlistentry> + <varlistentry> + <term><filename>wsrp-admin-gui-$WSRP_VERSION.war</filename></term> + <listitem> + <para> + This file contains the WSRP Configuration portlet with which you can configure consumers to access remote servers and how the WSRP producer is configured. + </para> + + </listitem> + + </varlistentry> + <varlistentry> + <term><filename>wsrp-producer-jb5wsss-$WSRP_VERSION.war</filename></term> + <listitem> + <para> + This file contains the producer-side support for WS-Security. The only file of interest from a user perspective is <filename>gatein-wsse-producer.xml</filename> which allows you to configure WS-Security support for the producer. + </para> + <para> + Refer to <xref linkend="sect-Reference_Guide_eXo_JCR_1.14-WSRP_and_WS_Security-WS_Security_Configuration" /> for more details. + </para> + + </listitem> + + </varlistentry> + + </variablelist> + <section id="sect-Reference_Guide_eXo_JCR_1.14-Deploying_WSRP-Non_default_Ports_or_Hostnames"> + <title>Non-default Ports or Hostnames</title> + <para> + JBoss WS (the web service stack that JBoss Enterprise Portal Platform uses) should update the port and host name used in WSDL. Refer to the JBoss WS <ulink url="http://community.jboss.org/wiki/JBossWS-UserGuide#Configuration... guide</ulink> for more information. + </para> + <para> + If the host name and port on which the server runs have been modified, the configuration for the Consumer used to consume JBoss Enterprise Portal Platform's "self" Producer will need to be updated. Refer to <xref linkend="sect-Reference_Guide_eXo_JCR_1.14-Web_Services_for_Remote_Portlets_WSRP-Consuming_Remote_WSRP_Portlets" /> for directions on how to do this. + </para> + + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Deploying_WSRP-Using_WSRP_with_SSL"> + <title>Using WSRP with SSL</title> + <para> + It is possible to use WSRP over SSL for secure exchange of data. Refer to these <ulink url="http://community.jboss.org/wiki/ConfiguringWSRPforuseoverSSL&qu... for how to do this. + </para> + + </section> + + + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Web_Services_for_Remote_Portlets_WSRP-WSRP_and_WS_Security"> + <title>WSRP and WS-Security</title> + <para> + Portlets may present different data or options depending on the currently authenticated user. For remote portlets, this means having to propagate the user credentials from the consumer back to the producer in a safe and secure manner. + </para> + <para> + The WSRP specification does not directly specify how this should be accomplished, but delegates this work to the existing WS-Security standards. + </para> + <note> + <title>Web Container Compatibility</title> + <para> + WSRP and WS-Security is currently only supported on JBoss Enterprise Portal Platform when running on top of JBoss AS 5. + </para> + + </note> + <warning> + <title>Encryption</title> + <para> + <emphasis role="bold">The use of encryption is strongly recommended.</emphasis> + </para> + <para> + Credentials being sent between the consumer and producer should be encrypted or they will be sent in plain text and could be easily intercepted. + </para> + <para> + You can either configure WS-Security to encrypt and sign the SOAP messages being sent, or secure the transport layer by using an <literal>https</literal> endpoint. + </para> + <para> + Failure to encrypt the SOAP message or transport layer will result in the username and password being sent in plain text. + </para> + + </warning> + <important> + <title>Credentials</title> + <para> + When the consumer sends the user credentials to the producer, it is sending the credentials for the currently authenticated user in the consumer. This makes signing in to remote portlets transparent to end users, but also requires that the producer and consumer use the same credentials. + </para> + <para> + The username and password must be the same and valid on both servers. + </para> + <para> + The recommended approach for this situation would be to use a common LDAP configuration. Please see the User Guide at <ulink type="http" url="docs.redhat.com" /> for information on how to configure LDAP for use with JBoss Enterprise Portal Platform + </para> + + </important> + <para> + This community Wiki <ulink url="http://community.jboss.org/wiki/GateInWSRPAndWebServiceSecurity...;, also provides a step-by-step example on how to configure WSRP with WS-Security. + </para> + <section id="sect-Reference_Guide_eXo_JCR_1.14-WSRP_and_WS_Security-WS_Security_Configuration"> + <title>WS-Security Configuration</title> + <para> + JBoss Enterprise Portal Platform uses <application>JBossWS Native</application> to handle ws-security. + </para> + <para> + Refer to the WS-Security section of the <ulink url="http://www.jboss.org/jbossas/docs/5-x">JBoss AS 5 Administration and Configuration Guide </ulink> for in-depth configuration options. + </para> + <para> + Please note that since the consumer passes its credentials to the producer, the consumer will act at the wss client and the producer will act as the wss server. + </para> + <para> + The following are the JBossWS Native configuration files which need to be configure for WSRP: + </para> + <variablelist> + <title></title> + <varlistentry> + <term>gatein-wsrp-integration.ear/META-INF/gatein-wsse-consumer.xml</term> + <listitem> + <para> + BossWS configuration file for the consumer. + </para> + + </listitem> + + </varlistentry> + <varlistentry> + <term>gatein-wsrp-integration.ear/wsrp-producer-jb5wss.war/WEB-INF/conf/gatein-wsse-producer.xml</term> + <listitem> + <para> + JBossWS configuration file for the producer. + </para> + + </listitem> + + </varlistentry> + + </variablelist> + + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-WSRP_and_WS_Security-WS_Security_Producer_Configuration"> + <title>WS-Security Producer Configuration</title> + <para> + Other than the JBossWS configuration file mention above, no other configuration changes should be necessary for the producer. + </para> + + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-WSRP_and_WS_Security-WS_Security_Consumer_Configuration"> + <title>WS-Security Consumer Configuration</title> + <para> + The consumer requires some changes before it will function properly with WS-Security. + </para> + <para> + The consumer needs access to the current servlet request since this is used to retrieve the currently authenticated user. In order to access this information, the consumer needs a special servlet-filter added to the portal. + </para> + <procedure id="proc-Reference_Guide_eXo_JCR_1.14-WS_Security_Consumer_Configuration-Add_the_servlet_filter"> + <title>Add the servlet-filter</title> + <step> + <para> + Open <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/web.xml</filename> and add the following: + </para> + +<programlisting role="XML">&lt;!-- Filter to put request and response in ServletAccess --&gt; + &lt;filter&gt; + &lt;filter-name&gt;ServletAccessFilter&lt;/filter-name&gt; + &lt;filter-class&gt;org.gatein.wsrp.servlet.ServletAccessFilter&lt;/filter-class&gt; + &lt;/filter&gt; + &lt;filter-mapping&gt; + &lt;filter-name&gt;ServletAccessFilter&lt;/filter-name&gt; + &lt;url-pattern&gt;/*&lt;/url-pattern&gt; + &lt;/filter-mapping&gt; +</programlisting> + + </step> + <step> + <para> + Check the <guilabel>Enable WS Security</guilabel> checkbox in the consumer configuration options of the WSRP Configuration portlet + </para> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/WSRP/config_wss_selected.png" format="PNG" scalefit="1" valign="middle" width="444" /> + </imageobject> + + </mediaobject> + </step> + </procedure> + + + </section> + + <section> + <title>WS-Security Consumer Checklist</title> + <para> + In order for the consumer to handle ws-security, the following items must be implemented: + </para> + <orderedlist> + <listitem> + <para> + The JBossWS configuration files must be configured + </para> + + </listitem> + <listitem> + <para> + The filter must be added to the portal's web.xml + </para> + + </listitem> + <listitem> + <para> + the enable wss feature must be check in the wsrp admin + </para> + + </listitem> + + </orderedlist> + <para> + The consumer will not properly handle ws-security unless all three items are correctly configured. + </para> + + </section> + + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Web_Services_for_Remote_Portlets_WSRP-Making_a_Portlet_Remotable"> + <title>Making a Portlet Remotable</title> + <note> + <para> + Only JSR-286 (Portlet 2.0) portlets can be made remotable as the mechanism to expose a portlet to WSRP relies on a JSR-286-only functionality. + </para> + + </note> + <para> + JBoss Enterprise Portal Platform does <emphasis role="bold">not</emphasis>, by default, expose local portlets for consumption by remote WSRP consumers. + </para> + <para> + In order to make a portlet remotely available, it must be made "remotable" by marking it as such in the associated <filename>portlet.xml</filename>. + </para> + <para> + A specific <code>org.gatein.pc.remotable container-runtime-option</code> is used to accomplish this. Setting its value to <code>true</code> makes the portlet available for remote consumption, while setting its value to <code>false</code> will not publish it remotely. + </para> + <para> + As specifying the remotable status for a portlet is optional, nothing need be done if portlets do not need to be remotely available. + </para> + <para> + In the following example, the "BasicPortlet" portlet is specified as being remotable. + </para> + +<programlisting language="XML" role="XML"><xi:include href="../extras/WSRP/default255.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + <para> + It is also possible to specify that all the portlets declared within a given portlet application be remotable by default. + </para> + <para> + This is done by specifying the <code>container-runtime-option</code> at the <code>portlet-app</code> element level. Individual portlets can override that value to not be remotely exposed. + </para> + <para> + For example: + </para> + +<programlisting language="XML" role="XML"><xi:include href="../extras/WSRP/default256.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + <para> + This example defines two portlets. As the <code>org.gatein.pc.remotable container-runtime-option</code> is set to <code>true</code> at the <code>portlet-app</code> level, all portlets defined in this particular portlet application are exposed remotely by JBoss Enterprise Portal Platform's WSRP Producer. + </para> + <para> + It is possible to override this default behavior. Specifying a value for the <code>org.gatein.pc.remotable container-runtime-option</code> at the <code>portlet</code> level will take precedence over the default. + </para> + <para> + In the example above, the <literal>RemotelyExposedPortlet</literal> inherits the remotable status defined at the <code>portlet-app</code> level since it does not specify a value for the <code>org.gatein.pc.remotable container-runtime-option</code>. + </para> + <para> + The <literal>NotRemotelyExposedPortlet</literal>, however, overrides the default behavior and is not remotely exposed. + </para> + <note> + <title>Note</title> + <para> + Portlets are not remotely exposed if no top-level <code>org.gatein.pc.remotable container-runtime-option</code> value is set to <code>true</code>. + </para> + + </note> + + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Web_Services_for_Remote_Portlets_WSRP-Consuming_WSRP_portlets_from_a_remote_Consumer"> + <title>Consuming WSRP portlets from a remote Consumer</title> + <para> + Configuration is extremely variable between different WSRP Consumers. Most, however, require a specification of the URL for the Producer's WSDL definition. If the JBoss Enterprise Portal Platform Consumer is not being used, refer to the documentation for the Consumer that is in use for specific instructions. + </para> + <para> + For instructions on how to specify this URL in JBoss Enterprise Portal Platform, refer to <xref linkend="sect-Reference_Guide_eXo_JCR_1.14-Web_Services_for_Remote_Portlets_WSRP-Consuming_Remote_WSRP_Portlets" />. + </para> + <para> + JBoss Enterprise Portal Platform's Producer is automatically set up when a portal instance is deployed with the WSRP service. + </para> + <para> + The WSDL file can be accessed at: + </para> + <variablelist id="vari-Reference_Guide_eXo_JCR_1.14-Consuming_WSRP_portlets_from_a_remote_Consumer-File_paths"> + <title>File paths:</title> + <varlistentry> + <term>WSRP 1.0:</term> + <listitem> + <para> + <filename>http://<replaceable>{hostname}</replaceable>:<replaceable>{port}</replaceable>/wsrp-producer/v1/MarkupService?wsdl</filename>. + </para> + + </listitem> + + </varlistentry> + <varlistentry> + <term>WSRP 2.0:</term> + <listitem> + <para> + <filename>http://<replaceable>{hostname}</replaceable>:<replaceable>{port}</replaceable>/wsrp-producer/v2/MarkupService?wsdl</filename>. + </para> + + </listitem> + + </varlistentry> + + </variablelist> + <para> + The default hostname is <literal>localhost</literal> and the default port is <literal>8080</literal>. + </para> + + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Web_Services_for_Remote_Portlets_WSRP-Consuming_Remote_WSRP_Portlets"> + <title>Consuming Remote WSRP Portlets</title> + <section id="sect-Reference_Guide_eXo_JCR_1.14-Consuming_Remote_WSRP_Portlets-Overview"> + <title>Overview</title> + <para> + To be able to consume WSRP portlets exposed by a remote producer, JBoss Enterprise Portal Platform's WSRP consumer must be configured to access that remote producer. + </para> + <para> + Access to a remote producer can be configured using the provided configuration portlet. Alternatively, it is also possible to configure access to remote producers using an XML descriptor. The configuration portlet is the recommended method. + </para> + <para> + Once a remote producer has been configured, the portlets that it exposes are then available in the Application Registry to be added to categories and then to pages. + </para> + <!-- Removed as out of date and not in Community version of doc. + <para> + A default consumer named <literal>self</literal>, that consumes the portlets exposed by JBoss Enterprise Portal Platform's producer, has been configured as a way to test the WSRP producer service and to check that portlets are correctly published via WSRP. + </para> + --> + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Consuming_Remote_WSRP_Portlets-Configuring_a_Remote_Producer"> + <title>Configuring a Remote Producer</title> + <para> + Access to a remote producer needs to be defined so that portlets can be consumed within JBoss Enterprise Portal Platform. This section will show how to configure access to <emphasis role="bold">NetUnity</emphasis>'s public WSRP producer. + </para> + <para> + Firstly using the configuration portlet and then how the same result can be accomplished with a producer descriptor, though it is far easier to do so via the configuration portlet. + </para> + <important> + <title>Chunked Encoding</title> + <para> + Some WSRP producers, such as Oracle, do not support chunked encoding. If your producer does not support chunked encoding, it will not be able to properly connect to the producer. + </para> + <para> + This will manifest itself with the following error: + </para> + +<screen>Caused by: org.jboss.ws.WSException: Invalid HTTP server response [503] - Service Unavailable. +</screen> + <para> + A workaround for this issue involves editing the <parameter>chunksize</parameter> setting in the <filename>standard-jaxws-client-config.xml</filename> file. + </para> + <para> + Refer to <ulink type="http" url="http://community.jboss.org/wiki/Workaroundwhenchunkedencodingis... for more information. + </para> + + </important> + <section id="sect-Reference_Guide_eXo_JCR_1.14-Configuring_a_Remote_Producer-The_Configuration_Portlet"> + <title>The Configuration Portlet</title> + <para> + JBoss Enterprise Portal Platform provides a graphical portlet to assist with configuring access to, and other facets of, remote WSRP Producers. + </para> + <para> + It is available at: <ulink type="http" url="http://localhost:8080/portal/login?initialURI=%2Fportal%2Fprivate%2Fclassic%2FwsrpConfiguration&amp;username=root&amp;password=gtn" />. + </para> + <para> + The portlet also is a group page for /platform/administrators + </para> + <para> + Although the Configuration Portlet is installed by default in JBoss Enterprise Portal Platform &VY;., installation instructions are included below should the portlet ever need to be re-installed: + </para> + <procedure id="proc-Reference_Guide_eXo_JCR_1.14-The_Configuration_Portlet-Installing_the_configuration_portlet"> + <title><emphasis role="bold">Installing the configuration portlet:</emphasis></title> + <step> + <para> + Log into the portal as an administrator and go to the Application Registry (Click <ulink url="http://localhost:8080/portal/private/classic/administration/registry">http://localhost:8080/portal/private/classic/administration/registry</ulink> if using the default installation). + </para> + + </step> + <step> + <para> + Add the WSRP Configuration portlet to the Administration category. If the Import Applications functionality is used, the WSRP Configuration portlet will be automatically added to the Administration category. + </para> + + </step> + <step> + <para> + Once the portlet is added to a category, it can be added to a page and used. It is recommended that it be added to the same page as the Application Registry (as other operations relating to WSRP and adding portlets to categories are somewhat related). Add the WSRP Configuration portlet to the page using the standard procedure. + </para> + + </step> + + </procedure> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-The_Configuration_Portlet-Using_the_Configuration_portlet"> + <title><emphasis role="bold">Using the Configuration portlet</emphasis></title> + <mediaobject> + <imageobject role="html"> + <imagedata align="center" fileref="images/WSRP/config_init.png" format="PNG" scale="120" width="444" /> + </imageobject> + <imageobject role="fo"> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/config_init.png" format="PNG" width="444" /> + </imageobject> + + </mediaobject> + <para> + This screen presents all the configured consumers associated with their status and possible actions on them. + </para> + <para> + A Consumer can be active or inactive. Activating a Consumer means that it is ready to act as a portlet provider. + </para> + <para> + Note also that a Consumer can be marked as requiring <emphasis>refresh</emphasis>, which means that the information held about it might not be up to date. Refreshing it from the remote Producer will update this information. + </para> + <para> + This can happen for several reasons: the service description for that remote Producer has not been fetched yet, the cached version has expired or modifications have been made to the configuration that could potentially invalidate it, thus requiring re-validation of the information. + </para> + <para> + To create a new Consumer: + </para> + <procedure id="proc-Reference_Guide_eXo_JCR_1.14-Using_the_Configuration_portlet-Creating_a_Consumer"> + <title><emphasis role="bold">Creating a Consumer</emphasis></title> + <step> + <para> + Type "<literal>netunity</literal>" into the "<emphasis role="bold">Create a consumer named:</emphasis>" field. + </para> + + </step> + <step> + <para> + Click on "<emphasis role="bold">Create consumer</emphasis>" to create a new Consumer called <literal>netunity</literal>. + </para> + <mediaobject> + <imageobject role="html"> + <imagedata align="center" fileref="images/WSRP/config_create.png" format="PNG" scale="100" /> + </imageobject> + <imageobject role="fo"> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/config_create.png" format="PNG" /> + </imageobject> + + </mediaobject> + + </step> + <step> + <para> + In the next form, set the cache expiration value to <parameter>300</parameter> seconds. + </para> + + </step> + <step> + <para> + Leave the default timeout value for web services (WS) operations. + </para> + + </step> + <step> + <para> + Enter the WSDL URL for the producer in the text field. + </para> + + </step> + <step> + <para> + Press the "Refresh &amp; Save" button: + </para> + <mediaobject> + <imageobject role="html"> + <imagedata align="center" fileref="images/WSRP/config_wsdl.png" format="PNG" scale="120" width="444" /> + </imageobject> + <imageobject role="fo"> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/config_wsdl.png" format="PNG" width="444" /> + </imageobject> + + </mediaobject> + + </step> + + </procedure> + + <para> + This will retrieve the service description associated with the Producer which WSRP interface is described by the WSDL file found at the URL entered. + </para> + <para> + In this case, querying the service description will show that the Producer requires registration, that it requested three registration properties and that the current configuration is missing values for these properties: + </para> + <mediaobject> + <imageobject role="html"> + <imagedata align="center" fileref="images/WSRP/config_missing.png" format="PNG" scale="120" width="444" /> + </imageobject> + <imageobject role="fo"> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/config_missing.png" format="PNG" width="444" /> + </imageobject> + + </mediaobject> + <para> + This particular producer requests simple <literal>Yes</literal> or <literal>No</literal> values for the three registration properties. + </para> + <para> + Enter <literal>No</literal>, <literal>Yes</literal> and <literal>No</literal> (in that order) for the values and then pressing the "Refresh &amp; Save" button should result in: + </para> + <mediaobject> + <imageobject role="html"> + <imagedata align="center" fileref="images/WSRP/config_end.png" format="PNG" scale="120" width="444" /> + </imageobject> + <imageobject role="fo"> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/config_end.png" format="PNG" width="444" /> + </imageobject> + + </mediaobject> + <note> + <title>Values</title> + <para> + Unfortunately there is no automated way to learn about which possible values (if any) are expected by the remote Producer. Possible values may be indicated in the registration property description but this is not always the case. Refer to the specific Producer's documentation. + </para> + + </note> + <para> + The Consumer for the <literal>netunity</literal> Producer should now be available as a portlet provider and be ready to be used. + </para> + <para> + If the producer had required registration but did not require any registration properties, as is the case for the <literal>selfv2</literal> consumer (the consumer that accesses the portlets made remotely available by JBoss Enterprise Portal Platform's producer via WSRP 2), the following screen would have appeared after pressing the "Refresh &amp; Save" button: + </para> + <mediaobject> + <imageobject role="html"> + <imagedata align="center" fileref="images/WSRP/config_refresh.png" format="PNG" scale="120" width="444" /> + </imageobject> + <imageobject role="fo"> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/config_refresh.png" format="PNG" width="444" /> + </imageobject> + + </mediaobject> + + </section> + + + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Configuring_a_Remote_Producer-Using_XML"> + <title>Using XML</title> + <para> + Although using the WSRP Configuration portlet to configure Consumers is recommended, the WSRP component provides an alternative way to configure consumers. + </para> + <para> + This is done by editing the <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/conf/gatein/wsrp-consumers-config.xml</filename> XML file. + </para> + <!-- Removed in GateIn revision 8119 +<programlisting language="XML" role="XML"><xi:include href="../extras/WSRP/default257.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + <para> + The file as shown above specifies access to two producers: <literal>self</literal>, which consumes JBoss Enterprise Portal Platform's own WSRP producer (albeit in a version that assumes that the producer requires a value for an <literal>email</literal> registration property), and <literal>oracle</literal>, which consumes Oracle's public producer, both in configurations as shown in the procedure above. + </para> --> <note> + <title>XML Elements</title> + <para> + An XML Schema defining which elements are available to configure Consumers via XML can be found in <filename><replaceable>WSRP_PATH</replaceable>/lib/wsrp-integration-api-<replaceable>WSRP_VERSION</replaceable>.jar/xsd/gatein_wsrp_consumer_1_0.xsd </filename> + </para> + + </note> + <!-- Removed in GateIn revision 8119 + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Consuming_Remote_WSRP_Portlets-Configuring_Access_to_Remote_Producers_via_XML"> + <title>Configuring Access to Remote Producers via XML</title> + + <para> + Again, configuring consumers via XML is done by editing <filename><replaceable>WSRP_PATH</replaceable>/lib/wsrp-consumer-<replaceable>WSRP_VERSION</replaceable>.jar/conf/wsrp-consumers-config.xml</filename>. + </para> --> <formalpara id="form-Reference_Guide_eXo_JCR_1.14-Using_XML-The_Consumer_Configuration_file"> + <title>The Consumer Configuration file</title> + <para> + It is important to understand how the XML Consumers configuration file is processed. It is read the first time the WSRP service starts and the associated information is then put under control of the JCR (Java Content Repository). + </para> + + </formalpara> + <para> + Subsequent launches of the WSRP service will use the JCR-stored information for all producers that are already known to JBoss Enterprise Portal Platform. More specifically, the <filename>wsrp-consumers-config.xml</filename> file is scanned for producer identifiers. Any identifier that is already known will be bypassed and the JCR information associated with this remote producer will be used. + </para> + <para> + The information defined at the XML level is only processed for producer definition for which no information is already present in the JCR. + </para> + <para> + Therefore, to delete a Producer configuration, the associated information in the database must be deleted (this can be accomplished using the configuration portlet as shown in <xref linkend="sect-Reference_Guide_eXo_JCR_1.14-Configuring_a_Remote_Producer-The_Configuration_Portlet" /> ). + </para> + <para> + The associated information in <filename>wsrp-consumers-config.xml</filename> (if such information exists) must also be removed, otherwise the producer will be re-created the next time the WSRP is launched. + </para> + <section id="sect-Reference_Guide_eXo_JCR_1.14-Using_XML-Required_Configuration_Information"> + <title>Required Configuration Information</title> + <para> + The following information needs to be provided to configure access to a remote Producer: + </para> + <orderedlist> + <listitem> + <para> + An identifier must be provided for the producer being configured so that it can be referred to later. This is done in the mandatory <literal>id</literal> attribute of the <literal>&lt;wsrp-producer&gt;</literal> element. + </para> + + </listitem> + <listitem> + <para> + JBoss Enterprise Portal Platform also needs to know about the remote Producer's endpoints to be able to connect to the remote web services and perform WSRP invocations. Use the <literal>&lt;endpoint-wsdl-url&gt;</literal> element to specify the URL for the WSDL description of the remote WSRP service. + </para> + + </listitem> + + </orderedlist> + <para> + Both the <literal>id</literal> attribute and <literal>&lt;endpoint-wsdl-url&gt;</literal> elements are required for a functional remote producer configuration. + </para> + + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Using_XML-Optional_Configuration"> + <title>Optional Configuration</title> + <para> + It is also possible to provide additional configuration, which, in some cases, might be important to establish a proper connection to the remote producer. + </para> + <variablelist id="vari-Reference_Guide_eXo_JCR_1.14-Optional_Configuration-Optional_Configurations"> + <title>Optional Configurations</title> + <varlistentry> + <term>Caching</term> + <listitem> + <para> + To prevent unnecessary traffic between the local consumer and the remote producer, it is possible to cache some of the information sent by the producer (such as the list of offered portlets) for a given duration. + </para> + <para> + The rate at which the information is refreshed is defined by the <literal>expiration-cache</literal> attribute of the <literal>&lt;wsrp-producer&gt;</literal> element (in seconds). + </para> + <para> + For example; providing a value of <literal>120</literal> for expiration-cache means that the producer information will not be refreshed for 2 minutes after it has been accessed. If no value is provided, JBoss Enterprise Portal Platform will always access the remote producer regardless of whether the remote information has changed or not. + </para> + <para> + Since, in most instances, the information provided by the producer does not change often, use of this caching facility to minimize bandwidth usage is recommended. + </para> + + </listitem> + + </varlistentry> + <varlistentry> + <term>WS Timeout</term> + <listitem> + <para> + It is also possible to define a timeout after which WS operations are considered as failed. This is helpful to avoid blocking the WSRP service, as it waits on a service that does not answer. + </para> + <para> + Use the <literal>ws-timeout</literal> attribute of the <literal>&lt;wsrp-producer&gt;</literal> element to specify how many milliseconds the WSRP service will wait for a response from the remote producer before timing out. + </para> + + </listitem> + + </varlistentry> + <varlistentry> + <term>Pre-registration information</term> + <listitem> + <para> + Some producers require consumers to register with them before authorizing them to access their offered portlets. If known, some registration information can be provided in the producer configuration beforehand, so that the consumer can register with the remote producer when required. + </para> + <note> + <para> + Only simple String properties are supported. It is not possible to configure complex registration data. However, this should be sufficient for most cases. + </para> + + </note> + <para> + This pre-registration configuration is done via the <literal>&lt;registration-data&gt;</literal> element. + </para> + <para> + If the remote producer does not require any registration properties, only an empty <literal>&lt;registration-data&gt;</literal> element need be provided, as JBoss Enterprise Portal Platform can generate the mandatory information. + </para> + <para> + Values for the registration properties required by the remote producer can be provided via <literal>&lt;property&gt;</literal> elements. Refer to the example below for more details. + </para> + <para> + Additionally, the default consumer name automatically provided by JBoss Enterprise Portal Platform can be overridden via the <literal>&lt;consumer-name&gt;</literal> element. When providing a consumer name, please remember that it should uniquely identify your consumer. + </para> + + </listitem> + + </varlistentry> + + </variablelist> + + </section> + + + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Configuring_a_Remote_Producer-Examples"> + <title>Examples</title> + <para> + This is the configuration of the <literal>selfv1</literal> and <literal>selfv2</literal> consumers as found in <filename>default-wsrp.xml</filename> with a cache expiring every 500 seconds and with a 50 second timeout for web service operations: + </para> + <note> + <para> + This file contains the default configuration and should not need to be edited. If modifications are required, the recommended practice is to follow the procedure detailed in <xref linkend="sect-Reference_Guide_eXo_JCR_1.14-The_Configuration_Portlet-Using_the_Configuration_portlet" />. + </para> + + </note> + +<programlisting language="XML" role="XML"><xi:include href="../extras/WSRP/default258.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + <para> + This is an example of a WSRP descriptor with registration data and cache expiring every minute: + </para> + +<programlisting language="XML" role="XML"><xi:include href="../extras/WSRP/default259.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + + </section> + + + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Consuming_Remote_WSRP_Portlets-Adding_remote_portlets_to_categories"> + <title>Adding remote portlets to categories</title> + <para> + Clicking on the Portlet link in the Application Registry will now show the remote portlets in the <emphasis role="bold">REMOTE</emphasis> tab in the left column: + </para> + <mediaobject> + <imageobject role="html"> + <imagedata align="center" fileref="images/WSRP/remote_portlets.png" format="PNG" scale="120" width="444" /> + </imageobject> + <imageobject role="fo"> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/remote_portlets.png" format="PNG" width="444" /> + </imageobject> + + </mediaobject> + <para> + These portlets are available to be used as regular portlets: they can be used in categories and added to pages. Using the Import Applications functionality will also automatically import them into categories based on the keywords they define. + </para> + <para> + More specifically, to add a <emphasis>WSRP</emphasis> portlet to a category, select <literal>wsrp</literal> in the Application Type drop-down menu: + </para> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/WSRP/remote_portlets_category.png" format="PNG" scalefit="1" valign="middle" /> + </imageobject> + + </mediaobject> + + </section> + + + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Web_Services_for_Remote_Portlets_WSRP-Consumers_Maintenance"> + <title>Consumers Maintenance</title> + <section id="sect-Reference_Guide_eXo_JCR_1.14-Consumers_Maintenance-Modifying_a_Currently_Held_Registration"> + <title>Modifying a Currently Held Registration</title> + <section id="sect-Reference_Guide_eXo_JCR_1.14-Modifying_a_Currently_Held_Registration-Registration_Modification_for_Service_Upgrade"> + <title>Registration Modification for Service Upgrade</title> + <para> + Producers often offer several levels of service depending on consumers' subscription levels (for example). This is implemented at the WSRP level with the registration concept: producers can assert which level of service to provide to consumers based on the values of given registration properties. + </para> + <para> + There may also be cases where the registration information has changed and must be updated. For example, the producer required you to provide a valid email and the previous email address is not valid anymore and needs to be updated. + </para> + <para> + Therefore at times it may be necessary to modify the registration that sets the service agreement between a consumer and a producer. + </para> + <para> + For example; the producer requiring an email that was configured in <xref linkend="sect-Reference_Guide_eXo_JCR_1.14-Configuring_a_Remote_Producer-The_Configuration_Portlet" /> . In that case the producer was requiring registration and required a value to be provided for the <literal>email</literal> property. + </para> + <para> + To update the email address that was provided, the remote producer must be informed that some registration data has been modified. + </para> + <para> + The following procedure assumes access to the producer has been configured as previously described. + </para> + <procedure> + <step> + <para> + Go to the configuration screen for the <literal>self</literal> producer and change the value of <literal>email</literal> to <literal&gt;foo(a)example.com&lt;/literal&gt; instead of <literal&gt;example(a)example.com&lt;/literal&gt;: + </para> + <mediaobject> + <imageobject role="html"> + <imagedata align="center" fileref="images/WSRP/modify_reg_start.png" format="PNG" scale="100" width="444" /> + </imageobject> + <imageobject role="fo"> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/modify_reg_start.png" format="PNG" width="444" /> + </imageobject> + + </mediaobject> + + </step> + <step> + <para> + Click on "<emphasis role="bold">Update properties</emphasis>" to save the change. A "<emphasis role="bold">Modify registration</emphasis>" button should now appear to let you send this new data to the remote producer: + </para> + <mediaobject> + <imageobject role="html"> + <imagedata align="center" fileref="images/WSRP/modify_reg_modify.png" format="PNG" scale="100" width="444" /> + </imageobject> + <imageobject role="fo"> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/modify_reg_modify.png" format="PNG" width="444" /> + </imageobject> + + </mediaobject> + + </step> + <step> + <para> + Click on <emphasis role="bold">Modify registration</emphasis> and, if the updated registration details have been accepted by the remote producer the following should appear: + </para> + <mediaobject> + <imageobject role="html"> + <imagedata align="center" fileref="images/WSRP/modify_reg_end.png" format="PNG" scale="120" width="444" /> + </imageobject> + <imageobject role="fo"> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/modify_reg_end.png" format="PNG" width="444" /> + </imageobject> + + </mediaobject> + + </step> + + </procedure> + + + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Modifying_a_Currently_Held_Registration-Registration_Modification_on_Producer_Error"> + <title>Registration Modification on Producer Error</title> + <para> + If a Producer administrator changes the requirements for registered consumers, invoking operations on the producer may fail with an <exceptionname>OperationFailedFault</exceptionname>. JBoss Enterprise Portal Platform will attempt to assist in these cases. + </para> + <para> + This section will discuss an example using the <literal>self</literal> producer. + </para> + <para> + Assuming that the registration requires a valid value for an <literal>email</literal> registration property (as has been shown) the configuration screen for this producer should show: + </para> + <mediaobject> + <imageobject role="html"> + <imagedata align="center" fileref="images/WSRP/config_self.png" format="PNG" scale="120" width="444" /> + </imageobject> + <imageobject role="fo"> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/config_self.png" format="PNG" width="444" /> + </imageobject> + + </mediaobject> + <para> + If the administrator of the producer now requires an additional value to be provided for a <literal>name</literal> registration property operations with this producer will fail. + </para> + <para> + If a registration modification is required, go to the configuration screen for this remote producer and refresh the information held by the consumer by pressing "<emphasis role="bold">Refresh &amp; Save</emphasis>": + </para> + <mediaobject> + <imageobject role="html"> + <imagedata align="center" fileref="images/WSRP/modify_reg_self.png" format="PNG" scale="120" width="444" /> + </imageobject> + <imageobject role="fo"> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/modify_reg_self.png" format="PNG" width="444" /> + </imageobject> + + </mediaobject> + <para> + The configuration screen now shows the currently held registration information and the expected information from the producer. + </para> + <para> + Enter a value for the <literal>name</literal> property and then click on "<emphasis role="bold">Modify registration</emphasis>". If the producer accepts the new registration data, the following screen will appear: + </para> + <mediaobject> + <imageobject role="html"> + <imagedata align="center" fileref="images/WSRP/modify_reg_self_end.png" format="PNG" scale="120" width="444" /> + </imageobject> + <imageobject role="fo"> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/modify_reg_self_end.png" format="PNG" width="444" /> + </imageobject> + + </mediaobject> + <note> + <title><emphasis role="bold">JBoss Enterprise Portal Platform &VY; and WSRP 1 Exceptions</emphasis></title> + <para> + In WSRP 1, it can be difficult to ascertain what caused an <exceptionname> OperationFailedFault </exceptionname> as it is a generic exception returned by producers during a failed method invocation. + </para> + <para> + An <exceptionname>OperationFailedFault</exceptionname> failure can be caused by several different reasons, one of them being a request to modify the registration data. + </para> + <para> + In these instances examining the log files may assist in gathering more information about the problem. + </para> + <para> + WSRP 2 introduces an exception that is specific to a request to modify registrations which reduces the ambiguity that currently exists. + </para> + + </note> + + </section> + + + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Consumers_Maintenance-Consumer_Operations"> + <title>Consumer Operations</title> + <para> + Several operations are available from the consumer list view of the WSRP configuration portlet: + </para> + <mediaobject> + <imageobject role="html"> + <imagedata align="center" fileref="images/WSRP/consumer_operations.png" format="PNG" scale="120" width="444" /> + </imageobject> + <imageobject role="fo"> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/consumer_operations.png" format="PNG" width="444" /> + </imageobject> + + </mediaobject> + <para> + The available operations are: + </para> + <variablelist> + <varlistentry> + <term>Configure</term> + <listitem> + <para> + Displays the consumer details and allows user to edit them. + </para> + + </listitem> + + </varlistentry> + <varlistentry> + <term>Refresh</term> + <listitem> + <para> + Forces the consumer to retrieve the service description from the remote producer to refresh the local information (such as offered portlets, registration information). + </para> + + </listitem> + + </varlistentry> + <varlistentry> + <term>Activate/Deactivate</term> + <listitem> + <para> + Activates or deactivates a consumer, governing whether it will be available to provide portlets and receive portlet invocations. + </para> + + </listitem> + + </varlistentry> + <varlistentry> + <term>Register/De-register</term> + <listitem> + <para> + Registers or de-registers a consumer based on whether registration is required and/or acquired. + </para> + + </listitem> + + </varlistentry> + <varlistentry> + <term>Delete</term> + <listitem> + <para> + Destroys the consumer, after de-registering it if it was registered. + </para> + + </listitem> + + </varlistentry> + + </variablelist> + <formalpara id="form-Reference_Guide_eXo_JCR_1.14-Consumer_Operations-Additional_Functionalities_in_WSRP_2.0"> + <title><emphasis role="bold">Additional Functionalities in WSRP 2.0</emphasis></title> + <para> + In addition to those listed above, the WSRP 2.0 implementation in JBoss Enterprise Portal Platform &VY; also includes the following functions: + </para> + + </formalpara> + <variablelist id="vari-Reference_Guide_eXo_JCR_1.14-Consumer_Operations-Additional_Functions"> + <title>Additional Functions:</title> + <varlistentry> + <term>Export</term> + <listitem> + <para> + Exports some or all of the consumer's portlets to be able to later import them in a different context + </para> + + </listitem> + + </varlistentry> + <varlistentry> + <term>Import</term> + <listitem> + <para> + Imports some or all of previously exported portlets. + </para> + + </listitem> + + </varlistentry> + + </variablelist> + <section id="sect-Reference_Guide_eXo_JCR_1.14-Consumer_Operations-Importing_and_Exporting_Portlets"> + <title><emphasis role="bold">Importing and Exporting Portlets</emphasis></title> + <para> + Import and export are new functionalities added in WSRP 2. + </para> + <para> + Exporting a portlet allows a consumer to get an opaque representation of the portlet which can then be use by the corresponding import operation to reconstitute it. + </para> + <para> + This is mostly used in migration scenarios during batch operations. Since JBoss Enterprise Portal Platform does not currently support automated migration of portal data, the functionality provided as part of WSRP 2 is necessarily less complete than it could be with full portal support. + </para> + <para> + The import/export implementation in JBoss Enterprise Portal Platform allows users to export portlets from a given consumer and then import them back to replace existing portlets assigned to windows on pages by the previously exported portlets. + </para> + <procedure> + <title></title> + <step> + <para> + Click on the "<guilabel>Export</guilabel>" action for a given consumer to display the list of portlets currently made available by this specific consumer. An example list is shown below: + </para> + <mediaobject> + <imageobject role="html"> + <imagedata align="center" fileref="images/WSRP/export_portlet_list.png" format="PNG" scale="120" width="444" /> + </imageobject> + <imageobject role="fo"> + <imagedata align="center" contentwidth="150mm" fileref="images/WSRP/export_portlet_list.png" format="PNG" width="444" /> + </imageobject> + + </mediaobject> + + </step> + <step> + <para> + Once portlets have been selected, they can be exported by clicking on the "<guilabel>Export</guilabel>" button. This makes them available for later import: + </para> + <mediaobject> + <imageobject role="html"> + <imagedata align="center" fileref="images/WSRP/export_done.png" format="PNG" scale="120" width="444" /> + </imageobject> + <imageobject role="fo"> + <imagedata align="center" contentwidth="150mm" fileref="images/WSRP/export_done.png" format="PNG" width="444" /> + </imageobject> + + </mediaobject> + + </step> + <step> + <para> + The portlets can be re-imported directly by pressing the "<guilabel>Use for import</guilabel>" button or, on the Consumers list page, using the "<guilabel>Import</guilabel>" action for a given consumer. + </para> + <para> + The example below assumes that the second option has been used and that several sets of previously exported portlets are available to import from. After clicking the action link, a screen similar to the one below should appear: + </para> + <mediaobject> + <imageobject role="html"> + <imagedata align="center" fileref="images/WSRP/export_list.png" format="PNG" scale="120" width="444" /> + </imageobject> + <imageobject role="fo"> + <imagedata align="center" contentwidth="150mm" fileref="images/WSRP/export_list.png" format="PNG" width="444" /> + </imageobject> + + </mediaobject> + <para> + This screen presents the list of available exports with available operations for each. + </para> + <variablelist id="vari-Reference_Guide_eXo_JCR_1.14-Importing_and_Exporting_Portlets-Operations"> + <title>Operations:</title> + <varlistentry> + <term>View</term> + <listitem> + <para> + Displays the export details as previously seen when the export was first performed. + </para> + + </listitem> + + </varlistentry> + <varlistentry> + <term>Delete</term> + <listitem> + <para> + Deletes the selected export, asking you for confirmation first. + </para> + + </listitem> + + </varlistentry> + <varlistentry> + <term>Use for import</term> + <listitem> + <para> + Selects the export to import portlets from. + </para> + + </listitem> + + </varlistentry> + + </variablelist> + + </step> + <step> + <para> + Once you have selected an export to import from, you will see a screen similar to the one below: + </para> + <mediaobject> + <imageobject role="html"> + <imagedata align="center" fileref="images/WSRP/import_start.png" format="PNG" scale="120" width="444" /> + </imageobject> + <imageobject role="fo"> + <imagedata align="center" contentwidth="150mm" fileref="images/WSRP/import_start.png" format="PNG" width="444" /> + </imageobject> + + </mediaobject> + <para> + The screen displays the list of available exported portlets for the previously selected export. You can select which portlet you want to import by checking the checkbox next to its name. + </para> + + </step> + <step> + <para> + Select the content of which window the imported portlet will replace. This process is done in three steps: + </para> + <para> + This example assumes that you have the following page called <literal>page1</literal> which contains two windows called <literal>NetUnity WSRP 2 Interop - Cache Markup (remote)</literal> and <literal>/samples-remotecontroller-portlet.RemoteControl (remote)</literal>, as shown below: + </para> + <mediaobject> + <imageobject role="html"> + <imagedata align="center" fileref="images/WSRP/import_original_page.png" format="PNG" scale="120" width="444" /> + </imageobject> + <imageobject role="fo"> + <imagedata align="center" contentwidth="150mm" fileref="images/WSRP/import_original_page.png" format="PNG" width="444" /> + </imageobject> + + </mediaobject> + <para> + In this example, we want to replace the content of the <literal>/samples-remotecontroller-portlet.RemoteControl (remote)</literal> with the content of the <literal>/ajaxPortlet.JSFAJAXPortlet</literal> portlet that was previously exported. + </para> + <procedure> + <title></title> + <step> + <para> + Check the box next to the <literal>/ajaxPortlet.JSFAJAXPortlet</literal> portlet name to indicate that you want to import its data. + </para> + + </step> + <step> + <para> + Select <literal>page1</literal> in the list of available pages. The screen will then refresh to display the list of available windows on that page, similar to the image below: + </para> + <mediaobject> + <imageobject role="html"> + <imagedata align="center" fileref="images/WSRP/import_selected_page.png" format="PNG" scale="120" width="444" /> + </imageobject> + <imageobject role="fo"> + <imagedata align="center" contentwidth="150mm" fileref="images/WSRP/import_selected_page.png" format="PNG" width="444" /> + </imageobject> + + </mediaobject> + <note> + <title>Note</title> + <para> + At this point, you still need to select which window content you want to replace before being able to complete the import operation + </para> + + </note> + + </step> + <step> + <para> + Select the <literal>/samples-remotecontroller-portlet.RemoteControl (remote)</literal> window, which enables the "<guilabel>Import</guilabel>" button. This indicates that all the necessary data to perform the import is available. + </para> + + </step> + <step> + <para> + Click the "<guilabel>Import</guilabel>" button. A screen similar to the one below will appear: + </para> + <mediaobject> + <imageobject role="html"> + <imagedata align="center" fileref="images/WSRP/import_success.png" format="PNG" scale="120" width="444" /> + </imageobject> + <imageobject role="fo"> + <imagedata align="center" contentwidth="150mm" fileref="images/WSRP/import_success.png" format="PNG" width="444" /> + </imageobject> + + </mediaobject> + + </step> + + </procedure> + + + </step> + <step> + <para> + The <literal>page1</literal> page should now show that the content of <literal>/samples-remotecontroller-portlet.RemoteControl (remote)</literal> window has been replaced by the content of the <literal>/ajaxPortlet.JSFAJAXPortlet</literal> imported portlet and that the window has been renamed appropriately. + </para> + <mediaobject> + <imageobject role="html"> + <imagedata align="center" fileref="images/WSRP/import_modified_page.png" format="PNG" scale="120" width="444" /> + </imageobject> + <imageobject role="fo"> + <imagedata align="center" contentwidth="150mm" fileref="images/WSRP/import_modified_page.png" format="PNG" width="444" /> + </imageobject> + + </mediaobject> + + </step> + + </procedure> + + + </section> + + + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Consumers_Maintenance-Erasing_Local_Registration_Data"> + <title>Erasing Local Registration Data</title> + <para> + In rare cases, it may be necessary to erase the local data without being able to de-register first. + </para> + <para> + This can occur when a consumer is registered with a producer that has been modified by its administrator to not require registration any longer. + </para> + <para> + In this scenario, local registration information can be erased from the consumer to allow it to resume interacting with the remote producer. + </para> + <para> + To do this click on the "<emphasis role="bold">Erase local registration</emphasis>" button next to the registration context information on the consumer configuration screen: + </para> + <mediaobject> + <imageobject role="html"> + <imagedata align="center" fileref="images/WSRP/erase_registration.png" format="PNG" scale="80" width="444" /> + </imageobject> + <imageobject role="fo"> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/erase_registration.png" format="PNG" width="444" /> + </imageobject> + + </mediaobject> + <warning> + <para> + This operation is dangerous as it can result in inability to interact with the remote producer if invoked when not required. The warning message below will be displayed before any data is erased. + </para> + <mediaobject> + <imageobject role="html"> + <imagedata align="center" fileref="images/WSRP/erase_registration_warning.png" format="PNG" scale="100" width="444" /> + </imageobject> + <imageobject role="fo"> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/erase_registration_warning.png" format="PNG" width="444" /> + </imageobject> + + </mediaobject> + + </warning> + + </section> + + + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Web_Services_for_Remote_Portlets_WSRP-Configuring_the_WSRP_Producer"> + <title>Configuring the WSRP Producer</title> + <section id="sect-Reference_Guide_eXo_JCR_1.14-Configuring_the_WSRP_Producer-Overview"> + <title>Overview</title> + <para> + The behavior of the Portal's WSRP Producer can be configured using the WSRP administration interface, (this is the recommended method), or by editing the <filename><replaceable>WSRP_PATH</replaceable>/lib/gatein.portal.component.wsrp-<replaceable>&lt;VERSION&gt;</replaceable>-epp-GA.jar/conf/wsrp-producer-config.xml</filename> file. + </para> + <para> + Several aspects can be modified with respect to whether registration is required for consumers to access the Producer's services. An XML Schema for the configuration format is available at <filename><replaceable>WSRP_PATH</replaceable>/lib/wsrp-integration-api-<replaceable>WSRP_VERSION</replaceable>.jar/xsd/gatein_wsrp_producer_1_0.xsd </filename>. + </para> + <para> + An alternative to editing the default <filename>wsrp-producer-config.xml</filename> file is to make a custom copy containing the required configuration options. + </para> + <para> + If a copy is used in place of the original, however, the <filename><replaceable>WSRP_PATH</replaceable>/02portal.war/WEB-INF/conf/wsrp/wsrp-configuration.xml</filename> <emphasis role="bold">must</emphasis> be updated to reference the custom file (this file defines the component <literal>WSRPServiceIntegration</literal> and contains a producer and consumer configuration location). + </para> + + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Configuring_the_WSRP_Producer-Default_Configuration"> + <title>Default Configuration</title> + <para> + The default producer configuration requires that consumers register with it before providing access to its services. However it does not require any specific registration properties (excepting those mandated by the WSRP standard). + </para> + <para> + It does, however, require consumers to be registered before sending them a full service description. This means that the WSRP producer will not provide the list of offered portlets and other capabilities to unregistered consumers. + </para> + <para> + The producer also uses the default <classname>RegistrationPolicy</classname> paired with the default <classname>RegistrationPropertyValidator</classname>. + </para> + <para> + This allows users to customize how Portal's WSRP Producer decides whether a given registration property is valid or not (however property validators are discussed in greater detail in <xref linkend="sect-Reference_Guide_eXo_JCR_1.14-Configuring_the_WSRP_Producer-Registration_Configuration" /> ). + </para> + <para> + JBoss Enterprise Portal Platform provides a web interface to configure the producer's behavior. It can be accessed by clicking on the "<emphasis role="bold">Producer Configuration</emphasis>" tab of the "<emphasis role="bold">WSRP</emphasis>" page of the "<emphasis role="bold">admin</emphasis>" portal. + </para> + <para> + The default configuration should show: + </para> + <mediaobject> + <imageobject role="html"> + <imagedata align="center" fileref="images/WSRP/producer_default.png" format="PNG" scale="110" width="444" /> + </imageobject> + <imageobject role="fo"> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/producer_default.png" format="PNG" width="444" /> + </imageobject> + + </mediaobject> + <para> + You can specify whether or not the producer will send the full service description to unregistered consumers, and, if it requires registration, which <literal>RegistrationPolicy</literal> to use (and, if needed, which <literal>RegistrationPropertyValidator</literal>), along with required registration property description for which consumers must provide acceptable values to successfully register. + </para> + <para> + WSDL URLs to access JBoss Enterprise Portal Platform's WSRP producer are now displayed in either in WSRP 1 or WSRP 2 mode. + </para> + + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Configuring_the_WSRP_Producer-Registration_Configuration"> + <title>Registration Configuration</title> + <para> + In order to have consumers register with Portal's producer the Portal's behavior with respect to registration must be configured. + </para> + <para> + Registration is optional, as are registration properties. The producer can require registration without requiring consumers to pass any registration properties as is the case in the default configuration. + </para> + <para> + The following section discusses configuring a producer's registration behavior from a blank state: + </para> + <mediaobject> + <imageobject role="html"> + <imagedata align="center" fileref="images/WSRP/producer_blank.png" format="PNG" width="700" /> + </imageobject> + <imageobject role="fo"> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/producer_blank.png" format="PNG" width="444" /> + </imageobject> + + </mediaobject> + <procedure> + <step> + <para> + To allow unregistered consumers to see the list of offered portlets, leave the first checkbox ("<emphasis role="bold">Access to full service description requires consumers to be registered.</emphasis>") unchecked. + </para> + + </step> + <step> + <para> + To specify, however, that consumers will need to be registered to be able to interact with the producer, check the second box ("<emphasis role="bold">Requires registration. Modifying this information will trigger invalidation of consumer registrations."</emphasis>). + </para> + <para> + The screen will refresh and display: + </para> + <mediaobject> + <imageobject role="html"> + <imagedata align="center" fileref="images/WSRP/producer_registration.png" format="PNG" width="700" /> + </imageobject> + <imageobject role="fo"> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/producer_registration.png" format="PNG" width="444" /> + </imageobject> + + </mediaobject> + + </step> + <step> + <para> + The fully-qualified name for the <classname>RegistrationPolicy</classname> and <classname>RegistrationPropertyValidator</classname> can be specified here. The default values are acceptable. Refer to <xref linkend="sect-Reference_Guide_eXo_JCR_1.14-Registration_Configuration-Customization_of_Registration_Handling_Behavior" /> for more information. + </para> + + </step> + <step> + <para> + To add a registration property called <literal>email</literal> click "<emphasis role="bold">Add property</emphasis>" and enter the appropriate information in the fields, providing a description for the registration property that can be used by consumers to determine its purpose: + </para> + <mediaobject> + <imageobject role="html"> + <imagedata align="center" fileref="images/WSRP/producer_email.png" format="PNG" width="700" /> + </imageobject> + <imageobject role="fo"> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/producer_email.png" format="PNG" width="444" /> + </imageobject> + + </mediaobject> + + </step> + <step> + <para> + Press "Save" to record the modifications. + </para> + + </step> + + </procedure> + + <note> + <para> + At this time, only String (<literal>xsd:string</literal>) properties are supported. + </para> + + </note> + <note> + <para> + If consumers are already registered with the producer, modifying the configuration of required registration information will trigger the invalidation of held registrations, requiring consumers to modify their registration before being able to access the producer again. The consumer side of that process is documented in <xref linkend="sect-Reference_Guide_eXo_JCR_1.14-Modifying_a_Currently_Held_Registration-Registration_Modification_on_Producer_Error" />. + </para> + + </note> + <section id="sect-Reference_Guide_eXo_JCR_1.14-Registration_Configuration-Customization_of_Registration_Handling_Behavior"> + <title>Customization of Registration Handling Behavior</title> + <para> + Registration handling behavior can be customized by users to suit their Producer needs. This is done with an implementation of the <classname>RegistrationPolicy</classname> interface. + </para> + <para> + This interface defines methods that are called by Portal's Registration service so that decisions can be made appropriately. A default registration policy that provides basic behavior is provided and should be enough for most user needs. + </para> + <para> + While the default registration policy provides default behavior for most registration-related aspects, one aspect requires specific configuration: whether a given value for a registration property is acceptable by the WSRP Producer. + </para> + <para> + This is done by plugging a <classname>RegistrationPropertyValidator</classname> into the default registration policy. This allows users to define their own validation mechanism. + </para> + <para> + Refer to the <trademark class="trade">Javadoc</trademark> for <classname>org.gatein.registration.RegistrationPolicy</classname> and <classname>org.gatein.registration.policies.RegistrationPropertyValidator</classname> for more details on what is expected of each method. + </para> + <para> + A defined registration policy is required for the producer to be correctly configured. Do this by specifying the qualified class name of the registration policy. + </para> + <para> + As it is anticipated that most users will use the default registration policy, it is possible to provide the class name of a custom property validator instead to customize the default registration policy behavior. Note that property validators are only used by the default policy. + </para> + <note> + <para> + Since the policy or the validator are defined via their class name and dynamically loaded, it is important to ensure that the identified class is available to the application server. + </para> + <para> + One way to accomplish that is to deploy the policy implementation as a JAR file in the AS instance deploy directory. + </para> + <para> + Note also that, since both policies and validators are dynamically instantiated, they must provide a default, no-argument constructor. + </para> + + </note> + + </section> + + + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Configuring_the_WSRP_Producer-WSRP_Validation_Mode"> + <title>WSRP Validation Mode</title> + <para> + The lack of conformance kit and the wording of the WSRP specification leaves room for differing interpretations, resulting in interoperability issues. It is therefore possible to encounter issues when using consumers from different vendors. + </para> + <para> + Experience of these issues has produced a way to relax the validation that the WSRP producer performs on the data provided by consumers to help with interoperability by accepting data that would normally be invalid. + </para> + <para> + Note that the our validation algorithm is only relaxed on aspects of the specification that are deemed harmless such as invalid language codes. + </para> + <para> + By default, the WSRP producer is configured in strict mode. If you experience issues with a given consumer, you may attempt to relax the validation mode. Un-checking the "Use strict WSRP compliance" checkbox on the Producer configuration screen to do this. + </para> + + </section> + + + </section> + + <section id="sect-Reference_Guide_eXo_JCR_1.14-Web_Services_for_Remote_Portlets_WSRP-Removing_WSRP"> + <title>Removing WSRP</title> + <para> + If you are not going to use WSRP in your JBoss Enterprise Portal Platform instance, the WSRP configuration files may be left in place. They will not adversely affect your installation. + </para> + <para> + However, if you wish to completely remove WSRP from your portal installation, remove the <filename>gatein-wsrp-integration.ear</filename> file from your application server deploy directory. + </para> + <!-- <para> + However, if you wish to completely remove WSRP from your portal installation, follow this procedure: + </para> + <procedure> + <title></title> + <step> + <para> + Navigate to the <filename><replaceable>JBOSS_HOME</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/conf/gatein/</filename> directory of your JBoss Enterprise Portal Platform instance. + </para> + <substeps> + <step> + <para> + Open the <filename>configuration.xml</filename> file and remove the following lines: + </para> + +<programlisting language="XML" role="XML">&lt;value&gt; + &lt;string&gt;wsrp-producer&lt;/string&gt; +&lt;/value&gt; +</programlisting> + + </step> + + </substeps> + + </step> + <step> + <para> + Navigate up two directory levels and into the <filename>deploy/gatein.ear/</filename> directory (For example: <command>cd ../../deploy/gatein.ear/</command>). + </para> + + </step> + <step> + <para> + Remove the following files: + </para> + <itemizedlist> + <listitem> + <para> + <filename>wsrp-admin-gui.war</filename> + </para> + + </listitem> + <listitem> + <para> + <filename>wsrp-producer.war</filename> + </para> + + </listitem> + + </itemizedlist> + + </step> + <step> + <para> + Navigate into the <filename>lib/</filename> subdirectory and remove the following files: + </para> + <itemizedlist> + <listitem> + <para> + <filename>gatein.portal.component.wsrp-PORTAL_VERSION.jar</filename> + </para> + + </listitem> + <listitem> + <para> + <filename>wsrp-common-WSRP_VERSION.jar</filename> + </para> + + </listitem> + <listitem> + <para> + <filename>wsrp-consumer-WSRP_VERSION.jar</filename> + </para> + + </listitem> + <listitem> + <para> + <filename>wsrp-integration-api-WSRP_VERSION.jar</filename> + </para> + + </listitem> + <listitem> + <para> + <filename>wsrp-producer-lib-WSRP_VERSION.jar</filename> + </para> + + </listitem> + <listitem> + <para> + <filename>wsrp-wsrp1-ws-WSRP_VERSION.jar</filename> + </para> + + </listitem> + <listitem> + <para> + <filename>wsrp-wsrp2-ws-WSRP_VERSION.jar</filename> + </para> + + </listitem> + + </itemizedlist> + + </step> + <step> + <para> + Return to the <filename>gatein.ear/</filename> directory and move into the <filename>META-INF/</filename> subdirectory. + </para> + <substeps> + <step> + <para> + Open the <filename>application.xml</filename> file and remove the following modules: + </para> + +<programlisting language="XML" role="XML">&lt;module&gt; + &lt;web&gt; + &lt;web-uri&gt;wsrp-admin-gui.war&lt;/web-uri&gt; + &lt;context-root&gt;wsrp-admin-gui&lt;/context-root&gt; + &lt;/web&gt; +&lt;/module&gt; +</programlisting> + +<programlisting language="XML" role="XML">&lt;module&gt; + &lt;web&gt; + &lt;web-uri&gt;wsrp-producer.war&lt;/web-uri&gt; + &lt;context-root&gt;wsrp-producer&lt;/context-root&gt; + &lt;/web&gt; +&lt;/module&gt; +</programlisting> + + </step> + <step> + <para> + Save and exit the file. + </para> + + </step> + + </substeps> + + </step> + <step> + <para> + Return to the <filename>gatein.ear/</filename> directory and navigate into the <filename>02portal.war/WEB-INF/conf/</filename> subdirectory. + </para> + <substeps> + <step> + <para> + Remove the <filename>wsrp/</filename> directory. + </para> + + </step> + <step> + <para> + Open the <filename>configuration.xml</filename> file and remove the following line: + </para> + +<programlisting language="XML" role="XML">&lt;import profiles="jboss"&gt;war:/conf/wsrp/wsrp-configuration.xml&lt;/import&gt; +</programlisting> + + </step> + <step> + <para> + Save and exit the file. + </para> + + </step> + + </substeps> + + </step> + <step> + <para> + From your current location, navigate into the <filename>portal/</filename> subdirectory. + </para> + <substeps> + <step> + <para> + Open the <filename>portal-configuration.xml</filename> file and remove the line: + </para> + +<programlisting language="XML" role="XML">&lt;value&gt;org.exoplatform.portal.pom.spi.wsrp.WSRPState&lt;/value&gt; +</programlisting> + + </step> + <step> + <para> + Save and exit the file. + </para> + + </step> + + </substeps> + + </step> + <step> + <para> + Return to the <filename>conf/</filename> directory and move into the <filename>jcr/</filename> subdirectory. + </para> + <substeps> + <step> + <para> + Open the <filename>jcr-configuration.xml</filename> file and remove the line: + </para> + +<programlisting language="XML" role="XML">&lt;property name="wsrp" value="http://www.gatein.org/jcr/wsrp/1.0/"/&gt; +</programlisting> + + </step> + <step> + <para> + Remove the following configuration file references: + </para> + +<programlisting language="XML" role="XML">&lt;value&gt;war:/conf/wsrp/consumers-configuration-nodetypes.xml&lt;/value&gt; +&lt;value&gt;war:/conf/wsrp/producer-configuration-nodetypes.xml&lt;/value&gt; +&lt;value&gt;war:/conf/wsrp/producer-registrations-nodetypes.xml&lt;/value&gt; +&lt;value&gt;war:/conf/wsrp/producer-pc-nodetypes.xml&lt;/value&gt; +&lt;value&gt;war:/conf/wsrp/migration-nodetypes.xml&lt;/value&gt; +</programlisting> + + </step> + <step> + <para> + Save and exit the file. + </para> + + </step> + <step> + <para> + Open the <filename>repository-configuration.xml</filename> and remove the <emphasis role="bold">WSRP</emphasis> workspace: + </para> + +<programlisting language="XML" role="XML"> + &lt;workspace name="wsrp-system"&gt; + &lt;container&gt; + &lt;properties&gt; + &lt;property name="source-name" value="${gatein.jcr.datasource.name}${container.name.suffix}"/&gt; + &lt;property name="dialect" value="${gatein.jcr.datasource.dialect}"/&gt; + &lt;property name="multi-db" value="false"/&gt; + &lt;property name="update-storage" value="true"/&gt; + &lt;property name="max-buffer-size" value="204800"/&gt; + &lt;property name="swap-directory" value="${gatein.jcr.data.dir}/swap/wsrp${container.name.suffix}"/&gt; + &lt;/properties&gt; + &lt;value-storages&gt; + &lt;value-storage id="gadgets" + &gt; + &lt;properties&gt; + &lt;property name="path" value="${gatein.jcr.storage.data.dir}/wsrp${container.name.suffix}"/&gt; + &lt;/properties&gt; + &lt;filters&gt; + &lt;filter property-type="Binary"/&gt; + &lt;/filters&gt; + &lt;/value-storage&gt; + &lt;/value-storages&gt; + &lt;/container&gt; + &lt;initializer&gt; + &lt;properties&gt; + &lt;property name="root-nodetype" value="nt:unstructured"/&gt; + &lt;property name="root-permissions" value="*:/platform/administrators read;*:/platform/administrators add_node;*:/platform/administrators set_property;*:/platform/administrators remove"/&gt; + &lt;/properties&gt; + &lt;/initializer&gt; + &lt;cache enabled="true"&gt; + &lt;properties&gt; + &lt;property name="jbosscache-configuration" value="${gatein.jcr.cache.config}" /&gt; + &lt;property name="jgroups-configuration" value="${gatein.jcr.jgroups.config}" /&gt; + &lt;property name="jgroups-multiplexer-stack" value="true" /&gt; + &lt;property name="jbosscache-cluster-name" value="jcr-${container.name.suffix}-wsrp-system" /&gt; + &lt;/properties&gt; + &lt;/cache&gt; + &lt;query-handler&gt; + &lt;properties&gt; + &lt;property name="index-dir" value="${gatein.jcr.index.data.dir}/wsrp-system${container.name.suffix}"/&gt; + &lt;property name="changesfilter-class" value="${gatein.jcr.index.changefilterclass}" /&gt; + &lt;property name="jbosscache-configuration" value="${gatein.jcr.index.cache.config}" /&gt; + &lt;property name="jgroups-configuration" value="${gatein.jcr.jgroups.config}" /&gt; + &lt;property name="jgroups-multiplexer-stack" value="true" /&gt; + &lt;property name="jbosscache-cluster-name" value="jcrindexer-${container.name.suffix}-wsrp-system" /&gt; + &lt;property name="max-volatile-time" value="60" /&gt; + &lt;/properties&gt; + &lt;/query-handler&gt; + &lt;lock-manager&gt; + &lt;properties&gt; + &lt;property name="time-out" value="15m" /&gt; + &lt;property name="jbosscache-configuration" value="${gatein.jcr.lock.cache.config}" /&gt; + &lt;property name="jgroups-configuration" value="${gatein.jcr.jgroups.config}" /&gt; + &lt;property name="jgroups-multiplexer-stack" value="true" /&gt; + &lt;property name="jbosscache-cluster-name" value="jcrlock-${container.name.suffix}-wsrp-system" /&gt; + &lt;property name="jbosscache-cl-cache.jdbc.table.name" value="jcrlock_wsrp_system" /&gt; + &lt;property name="jbosscache-cl-cache.jdbc.table.create" value="true" /&gt; + &lt;property name="jbosscache-cl-cache.jdbc.table.drop" value="false" /&gt; + &lt;property name="jbosscache-cl-cache.jdbc.table.primarykey" value="pk" /&gt; + &lt;property name="jbosscache-cl-cache.jdbc.fqn.column" value="fqn" /&gt; + &lt;property name="jbosscache-cl-cache.jdbc.node.column" value="node" /&gt; + &lt;property name="jbosscache-cl-cache.jdbc.parent.column" value="parent" /&gt; + &lt;property name="jbosscache-cl-cache.jdbc.datasource" value="${gatein.jcr.datasource.name}${container.name.suffix}" /&gt; + &lt;/properties&gt; + &lt;/lock-manager&gt; + &lt;/workspace&gt; +</programlisting> + + </step> + + </substeps> + + </step> + <step> + <title>Optional:</title> + <para> + Remove any references to <emphasis>WSRP</emphasis> from the following files: + </para> + <itemizedlist> + <listitem> + <para> + <filename>gatein.ear/01eXoResources.war/META-INF/MANIFEST.MF</filename> + </para> + + </listitem> + <listitem> + <para> + <filename>gatein.ear/META-INF/MANIFEST.MF</filename> + </para> + + </listitem> + <listitem> + <para> + <filename>gatein.ear/02portal.war/META-INF/MANIFEST.MF</filename> + </para> + + </listitem> + + </itemizedlist> + + </step> + + </procedure> --> + </section> + + +</chapter> + Deleted: epp/docs/branches/5.2/Reference_Guide/en-US/modules/WSRP.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/WSRP.xml 2011-11-24 17:26:22 UTC (rev 8138) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/WSRP.xml 2011-11-25 00:48:53 UTC (rev 8141) @@ -1,2003 +0,0 @@ -<?xml version='1.0' encoding='utf-8' ?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -<!ENTITY % BOOK_ENTITIES SYSTEM "Reference_Guide_eXo_JCR_1.14.ent"> -%BOOK_ENTITIES; -]> -<chapter id="chap-Reference_Guide_eXo_JCR_1.14-Web_Services_for_Remote_Portlets_WSRP"> - <title>Web Services for Remote Portlets (WSRP)</title> - <section id="sect-Reference_Guide_eXo_JCR_1.14-Web_Services_for_Remote_Portlets_WSRP-Introduction"> - <title>Introduction</title> - <para> - The Web Services for Remote Portlets (WSRP) specification defines a web service interface for accessing and interacting with interactive presentation-oriented web services. - </para> - <para> - It has been produced through the efforts of the Web Services for Remote Portlets (WSRP) OASIS Technical Committee. It is based on the requirements gathered and the proposals made to the committee. - </para> - <para> - Scenarios that motivate WSRP functionality include: - </para> - <itemizedlist> - <listitem> - <para> - Content hosts, such as portal servers, providing Portlets as presentation-oriented web services that can be used by aggregation engines. - </para> - - </listitem> - <listitem> - <para> - Aggregating frameworks, including portal servers, consuming presentation-oriented web services offered by content providers and integrating them into the framework. - </para> - - </listitem> - - </itemizedlist> - <para> - More information on WSRP can be found on the official <ulink url="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wsrp...;. We suggest reading the <ulink url="http://www.oasis-open.org/committees/download.php/10539/wsrp-pr... for a good, albeit technical, overview of WSRP. - </para> - - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Web_Services_for_Remote_Portlets_WSRP-Level_of_Support"> - <title>Level of Support</title> - <para> - The WSRP Technical Committee defined <ulink url="http://www.oasis-open.org/committees/download.php/3073">... Use Profiles</ulink> to help with WSRP interoperability. Terms defined in that document will be used in this section. - </para> - <para> - JBoss Enterprise Portal Platform provides a <emphasis>Simple</emphasis> level of support for the WSRP Producer, with the exception of out-of-band registration. In-band registration and persistent local state (which are defined at the <emphasis>Complex</emphasis> level) are supported. - </para> - <para> - JBoss Enterprise Portal Platform provides a <emphasis>Medium</emphasis> level of support for the Consumer, excepting HTML markup (as JBoss Enterprise Portal Platform itself does not handle other markup types). Explicit portlet cloning and the <literal>PortletManagement</literal> interface are supported. - </para> - <para> - The WSRP component has Level 1 Producer and Consumer caching. Cookie handling is supported properly on the Consumer. The Producer requires cookie initialization (as this improves interoperability with some consumers). - </para> - <para> - JBoss Enterprise Portal Platform does not support custom window states or modes, therefore neither does the WSRP component. It does, however, support CSS on both the Producer (although this is more a function of the portlets than an inherent Producer capability) and Consumer. - </para> - <para> - JBoss Enterprise Portal Platform &VY; includes implementations of WSRP 1.0 and 2.0. - </para> - <para> - All optional features in WSRP 2 are implemented in JBoss Enterprise Portal Platform &VY; except support for lifetimes and leasing support. - </para> - <note> - <para> - As of version &VZ; of Enterprise Portal Platform, WSRP is only activated and supported when deployed on JBoss Enterprise Application Server. - </para> - - </note> - - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Web_Services_for_Remote_Portlets_WSRP-Deploying_WSRP"> - <title>Deploying WSRP</title> - <note> - <title>Notational Devices</title> - <para> - The following list of support files uses the following notational devices: - </para> - <variablelist id="vari-Reference_Guide_eXo_JCR_1.14-Deploying_WSRP-Notations"> - <title>Notations:</title> - <varlistentry> - <term><replaceable>JBOSS_HOME</replaceable></term> - <listitem> - <para> - <replaceable>JBOSS_HOME</replaceable> refers to the directory that your instance of JBoss Enterprise Portal Platform has been extracted/installed to. For example: <filename>/home/<replaceable>USERNAME</replaceable>/jboss-epp-<replaceable>&lt;VERSION&gt;</replaceable>/</filename> - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term><replaceable>WSRP_PATH</replaceable></term> - <listitem> - <para> - The WSRP files referred to in this section are found in the <filename><replaceable>JBOSS_HOME</replaceable>/jboss-as/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear</filename> directory. - </para> - <para> - For ease of reference this path will be represented by: <replaceable>WSRP_PATH</replaceable>. - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term><replaceable>WSRP_VERSION</replaceable></term> - <listitem> - <para> - <replaceable>WSRP_VERSION</replaceable> represents the version of the WSRP component in use. - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term><replaceable>PORTAL_VERSION</replaceable></term> - <listitem> - <para> - <replaceable>PORTAL_VERSION</replaceable> represents the version of JBoss Enterprise Portal Platform in use. - </para> - - </listitem> - - </varlistentry> - - </variablelist> - - </note> - <para> - Starting with version 2.1.0-GA of the component, WSRP is packaged as a JBoss Enterprise Portal Platform extension and is now self-contained in an easy to install package named <filename>gatein-wsrp-integration.ear</filename>, deployed directly in the <filename>deploy</filename> directory of your JBoss Application Server configuration directory. - </para> - <para> - The extension itself is composed of the following components: - </para> - <variablelist id="vari-Reference_Guide_eXo_JCR_1.14-Deploying_WSRP-WSRP_support_files"> - <title>WSRP support files</title> - <varlistentry> - <term><filename>META-INF/</filename></term> - <listitem> - <para> - This directory contains files necessary for EAR packaging. The only file that is of interest from a user perspective is <filename>gatein-wsse-consumer.xml</filename> which allows you to configure WS-Security support for the consumer. - </para> - <para> - Refer to <xref linkend="sect-Reference_Guide_eXo_JCR_1.14-WSRP_and_WS_Security-WS_Security_Configuration" /> section for more details. - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term><filename>extension-component-$PORTAL_VERSION.jar</filename></term> - <listitem> - <para> - This archive which contains the components needed to integrate the WSRP component into JBoss Enterprise Portal Platform. It also includes the default configuration files for the WSRP producer and the default WSRP consumers. - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term><filename>extension-config-$PORTAL_VERSION.jar</filename></term> - <listitem> - <para> - This file contains the configuration file needed by the GateIn extension mechanism to properly register this EAR as an extension. - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term><filename>extension-war-$PORTAL_VERSION.war</filename></term> - <listitem> - <para> - This file contains the configuration files needed by the GateIn extension mechanism to properly setup the WSRP service. It includes <filename>wsrp-configuration.xml</filename> which, in particular, configures several options for the <code> WSRPServiceIntegration </code> component at the heart of the WSRP integration in JBoss Enterprise Portal Platform. - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term><filename>lib/</filename></term> - <listitem> - <para> - This directory contains the different libraries needed by the WSRP service. - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term><filename>wsrp-admin-gui-$WSRP_VERSION.war</filename></term> - <listitem> - <para> - This file contains the WSRP Configuration portlet with which you can configure consumers to access remote servers and how the WSRP producer is configured. - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term><filename>wsrp-producer-jb5wsss-$WSRP_VERSION.war</filename></term> - <listitem> - <para> - This file contains the producer-side support for WS-Security. The only file of interest from a user perspective is <filename>gatein-wsse-producer.xml</filename> which allows you to configure WS-Security support for the producer. - </para> - <para> - Refer to <xref linkend="sect-Reference_Guide_eXo_JCR_1.14-WSRP_and_WS_Security-WS_Security_Configuration" /> for more details. - </para> - - </listitem> - - </varlistentry> - - </variablelist> - <section id="sect-Reference_Guide_eXo_JCR_1.14-Deploying_WSRP-Non_default_Ports_or_Hostnames"> - <title>Non-default Ports or Hostnames</title> - <para> - JBoss WS (the web service stack that JBoss Enterprise Portal Platform uses) should update the port and host name used in WSDL. Refer to the JBoss WS <ulink url="http://community.jboss.org/wiki/JBossWS-UserGuide#Configuration... guide</ulink> for more information. - </para> - <para> - If the host name and port on which the server runs have been modified, the configuration for the Consumer used to consume JBoss Enterprise Portal Platform's "self" Producer will need to be updated. Refer to <xref linkend="sect-Reference_Guide_eXo_JCR_1.14-Web_Services_for_Remote_Portlets_WSRP-Consuming_Remote_WSRP_Portlets" /> for directions on how to do this. - </para> - - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Deploying_WSRP-Using_WSRP_with_SSL"> - <title>Using WSRP with SSL</title> - <para> - It is possible to use WSRP over SSL for secure exchange of data. Refer to these <ulink url="http://community.jboss.org/wiki/ConfiguringWSRPforuseoverSSL&qu... for how to do this. - </para> - - </section> - - - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Web_Services_for_Remote_Portlets_WSRP-WSRP_and_WS_Security"> - <title>WSRP and WS-Security</title> - <para> - Portlets may present different data or options depending on the currently authenticated user. For remote portlets, this means having to propagate the user credentials from the consumer back to the producer in a safe and secure manner. - </para> - <para> - The WSRP specification does not directly specify how this should be accomplished, but delegates this work to the existing WS-Security standards. - </para> - <note> - <title>Web Container Compatibility</title> - <para> - WSRP and WS-Security is currently only supported on JBoss Enterprise Portal Platform when running on top of JBoss AS 5. - </para> - - </note> - <warning> - <title>Encryption</title> - <para> - <emphasis role="bold">The use of encryption is strongly recommended.</emphasis> - </para> - <para> - Credentials being sent between the consumer and producer should be encrypted or they will be sent in plain text and could be easily intercepted. - </para> - <para> - You can either configure WS-Security to encrypt and sign the SOAP messages being sent, or secure the transport layer by using an <literal>https</literal> endpoint. - </para> - <para> - Failure to encrypt the SOAP message or transport layer will result in the username and password being sent in plain text. - </para> - - </warning> - <important> - <title>Credentials</title> - <para> - When the consumer sends the user credentials to the producer, it is sending the credentials for the currently authenticated user in the consumer. This makes signing in to remote portlets transparent to end users, but also requires that the producer and consumer use the same credentials. - </para> - <para> - The username and password must be the same and valid on both servers. - </para> - <para> - The recommended approach for this situation would be to use a common LDAP configuration. Please see the User Guide at <ulink type="http" url="docs.redhat.com" /> for information on how to configure LDAP for use with JBoss Enterprise Portal Platform - </para> - - </important> - <para> - This community Wiki <ulink url="http://community.jboss.org/wiki/GateInWSRPAndWebServiceSecurity...;, also provides a step-by-step example on how to configure WSRP with WS-Security. - </para> - <section id="sect-Reference_Guide_eXo_JCR_1.14-WSRP_and_WS_Security-WS_Security_Configuration"> - <title>WS-Security Configuration</title> - <para> - JBoss Enterprise Portal Platform uses <application>JBossWS Native</application> to handle ws-security. - </para> - <para> - Refer to the WS-Security section of the <ulink url="http://www.jboss.org/jbossas/docs/5-x">JBoss AS 5 Administration and Configuration Guide </ulink> for in-depth configuration options. - </para> - <para> - Please note that since the consumer passes its credentials to the producer, the consumer will act at the wss client and the producer will act as the wss server. - </para> - <para> - The following are the JBossWS Native configuration files which need to be configure for WSRP: - </para> - <variablelist> - <title></title> - <varlistentry> - <term>gatein-wsrp-integration.ear/META-INF/gatein-wsse-consumer.xml</term> - <listitem> - <para> - BossWS configuration file for the consumer. - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>gatein-wsrp-integration.ear/wsrp-producer-jb5wss.war/WEB-INF/conf/gatein-wsse-producer.xml</term> - <listitem> - <para> - JBossWS configuration file for the producer. - </para> - - </listitem> - - </varlistentry> - - </variablelist> - - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-WSRP_and_WS_Security-WS_Security_Producer_Configuration"> - <title>WS-Security Producer Configuration</title> - <para> - Other than the JBossWS configuration file mention above, no other configuration changes should be necessary for the producer. - </para> - - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-WSRP_and_WS_Security-WS_Security_Consumer_Configuration"> - <title>WS-Security Consumer Configuration</title> - <para> - The consumer requires some changes before it will function properly with WS-Security. - </para> - <para> - The consumer needs access to the current servlet request since this is used to retrieve the currently authenticated user. In order to access this information, the consumer needs a special servlet-filter added to the portal. - </para> - <procedure id="proc-Reference_Guide_eXo_JCR_1.14-WS_Security_Consumer_Configuration-Add_the_servlet_filter"> - <title>Add the servlet-filter</title> - <step> - <para> - Open <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/web.xml</filename> and add the following: - </para> - -<programlisting role="XML">&lt;!-- Filter to put request and response in ServletAccess --&gt; - &lt;filter&gt; - &lt;filter-name&gt;ServletAccessFilter&lt;/filter-name&gt; - &lt;filter-class&gt;org.gatein.wsrp.servlet.ServletAccessFilter&lt;/filter-class&gt; - &lt;/filter&gt; - &lt;filter-mapping&gt; - &lt;filter-name&gt;ServletAccessFilter&lt;/filter-name&gt; - &lt;url-pattern&gt;/*&lt;/url-pattern&gt; - &lt;/filter-mapping&gt; -</programlisting> - - </step> - <step> - <para> - Check the <guilabel>Enable WS Security</guilabel> checkbox in the consumer configuration options of the WSRP Configuration portlet - </para> - <mediaobject> - <imageobject> - <imagedata align="center" fileref="images/WSRP/config_wss_selected.png" format="PNG" scalefit="1" valign="middle" width="444" /> - </imageobject> - - </mediaobject> - </step> - </procedure> - - - </section> - - <section> - <title>WS-Security Consumer Checklist</title> - <para> - In order for the consumer to handle ws-security, the following items must be implemented: - </para> - <orderedlist> - <listitem> - <para> - The JBossWS configuration files must be configured - </para> - - </listitem> - <listitem> - <para> - The filter must be added to the portal's web.xml - </para> - - </listitem> - <listitem> - <para> - the enable wss feature must be check in the wsrp admin - </para> - - </listitem> - - </orderedlist> - <para> - The consumer will not properly handle ws-security unless all three items are correctly configured. - </para> - - </section> - - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Web_Services_for_Remote_Portlets_WSRP-Making_a_Portlet_Remotable"> - <title>Making a Portlet Remotable</title> - <note> - <para> - Only JSR-286 (Portlet 2.0) portlets can be made remotable as the mechanism to expose a portlet to WSRP relies on a JSR-286-only functionality. - </para> - - </note> - <para> - JBoss Enterprise Portal Platform does <emphasis role="bold">not</emphasis>, by default, expose local portlets for consumption by remote WSRP consumers. - </para> - <para> - In order to make a portlet remotely available, it must be made "remotable" by marking it as such in the associated <filename>portlet.xml</filename>. - </para> - <para> - A specific <code>org.gatein.pc.remotable container-runtime-option</code> is used to accomplish this. Setting its value to <code>true</code> makes the portlet available for remote consumption, while setting its value to <code>false</code> will not publish it remotely. - </para> - <para> - As specifying the remotable status for a portlet is optional, nothing need be done if portlets do not need to be remotely available. - </para> - <para> - In the following example, the "BasicPortlet" portlet is specified as being remotable. - </para> - -<programlisting language="XML" role="XML"><xi:include href="../extras/WSRP/default255.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <para> - It is also possible to specify that all the portlets declared within a given portlet application be remotable by default. - </para> - <para> - This is done by specifying the <code>container-runtime-option</code> at the <code>portlet-app</code> element level. Individual portlets can override that value to not be remotely exposed. - </para> - <para> - For example: - </para> - -<programlisting language="XML" role="XML"><xi:include href="../extras/WSRP/default256.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <para> - This example defines two portlets. As the <code>org.gatein.pc.remotable container-runtime-option</code> is set to <code>true</code> at the <code>portlet-app</code> level, all portlets defined in this particular portlet application are exposed remotely by JBoss Enterprise Portal Platform's WSRP Producer. - </para> - <para> - It is possible to override this default behavior. Specifying a value for the <code>org.gatein.pc.remotable container-runtime-option</code> at the <code>portlet</code> level will take precedence over the default. - </para> - <para> - In the example above, the <literal>RemotelyExposedPortlet</literal> inherits the remotable status defined at the <code>portlet-app</code> level since it does not specify a value for the <code>org.gatein.pc.remotable container-runtime-option</code>. - </para> - <para> - The <literal>NotRemotelyExposedPortlet</literal>, however, overrides the default behavior and is not remotely exposed. - </para> - <note> - <title>Note</title> - <para> - Portlets are not remotely exposed if no top-level <code>org.gatein.pc.remotable container-runtime-option</code> value is set to <code>true</code>. - </para> - - </note> - - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Web_Services_for_Remote_Portlets_WSRP-Consuming_WSRP_portlets_from_a_remote_Consumer"> - <title>Consuming WSRP portlets from a remote Consumer</title> - <para> - Configuration is extremely variable between different WSRP Consumers. Most, however, require a specification of the URL for the Producer's WSDL definition. If the JBoss Enterprise Portal Platform Consumer is not being used, refer to the documentation for the Consumer that is in use for specific instructions. - </para> - <para> - For instructions on how to specify this URL in JBoss Enterprise Portal Platform, refer to <xref linkend="sect-Reference_Guide_eXo_JCR_1.14-Web_Services_for_Remote_Portlets_WSRP-Consuming_Remote_WSRP_Portlets" />. - </para> - <para> - JBoss Enterprise Portal Platform's Producer is automatically set up when a portal instance is deployed with the WSRP service. - </para> - <para> - The WSDL file can be accessed at: - </para> - <variablelist id="vari-Reference_Guide_eXo_JCR_1.14-Consuming_WSRP_portlets_from_a_remote_Consumer-File_paths"> - <title>File paths:</title> - <varlistentry> - <term>WSRP 1.0:</term> - <listitem> - <para> - <filename>http://<replaceable>{hostname}</replaceable>:<replaceable>{port}</replaceable>/wsrp-producer/v1/MarkupService?wsdl</filename>. - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>WSRP 2.0:</term> - <listitem> - <para> - <filename>http://<replaceable>{hostname}</replaceable>:<replaceable>{port}</replaceable>/wsrp-producer/v2/MarkupService?wsdl</filename>. - </para> - - </listitem> - - </varlistentry> - - </variablelist> - <para> - The default hostname is <literal>localhost</literal> and the default port is <literal>8080</literal>. - </para> - - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Web_Services_for_Remote_Portlets_WSRP-Consuming_Remote_WSRP_Portlets"> - <title>Consuming Remote WSRP Portlets</title> - <section id="sect-Reference_Guide_eXo_JCR_1.14-Consuming_Remote_WSRP_Portlets-Overview"> - <title>Overview</title> - <para> - To be able to consume WSRP portlets exposed by a remote producer, JBoss Enterprise Portal Platform's WSRP consumer must be configured to access that remote producer. - </para> - <para> - Access to a remote producer can be configured using the provided configuration portlet. Alternatively, it is also possible to configure access to remote producers using an XML descriptor. The configuration portlet is the recommended method. - </para> - <para> - Once a remote producer has been configured, the portlets that it exposes are then available in the Application Registry to be added to categories and then to pages. - </para> - <!-- Removed as out of date and not in Community version of doc. - <para> - A default consumer named <literal>self</literal>, that consumes the portlets exposed by JBoss Enterprise Portal Platform's producer, has been configured as a way to test the WSRP producer service and to check that portlets are correctly published via WSRP. - </para> - --> - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Consuming_Remote_WSRP_Portlets-Configuring_a_Remote_Producer"> - <title>Configuring a Remote Producer</title> - <para> - Access to a remote producer needs to be defined so that portlets can be consumed within JBoss Enterprise Portal Platform. This section will show how to configure access to <emphasis role="bold">NetUnity</emphasis>'s public WSRP producer. - </para> - <para> - Firstly using the configuration portlet and then how the same result can be accomplished with a producer descriptor, though it is far easier to do so via the configuration portlet. - </para> - <important> - <title>Chunked Encoding</title> - <para> - Some WSRP producers, such as Oracle, do not support chunked encoding. If your producer does not support chunked encoding, it will not be able to properly connect to the producer. - </para> - <para> - This will manifest itself with the following error: - </para> - -<screen>Caused by: org.jboss.ws.WSException: Invalid HTTP server response [503] - Service Unavailable. -</screen> - <para> - A workaround for this issue involves editing the <parameter>chunksize</parameter> setting in the <filename>standard-jaxws-client-config.xml</filename> file. - </para> - <para> - Refer to <ulink type="http" url="http://community.jboss.org/wiki/Workaroundwhenchunkedencodingis... for more information. - </para> - - </important> - <section id="sect-Reference_Guide_eXo_JCR_1.14-Configuring_a_Remote_Producer-The_Configuration_Portlet"> - <title>The Configuration Portlet</title> - <para> - JBoss Enterprise Portal Platform provides a graphical portlet to assist with configuring access to, and other facets of, remote WSRP Producers. - </para> - <para> - It is available at: <ulink type="http" url="http://localhost:8080/portal/login?initialURI=%2Fportal%2Fprivate%2Fclassic%2FwsrpConfiguration&amp;username=root&amp;password=gtn" />. - </para> - <para> - The portlet also is a group page for /platform/administrators - </para> - <para> - Although the Configuration Portlet is installed by default in JBoss Enterprise Portal Platform &VY;., installation instructions are included below should the portlet ever need to be re-installed: - </para> - <procedure id="proc-Reference_Guide_eXo_JCR_1.14-The_Configuration_Portlet-Installing_the_configuration_portlet"> - <title><emphasis role="bold">Installing the configuration portlet:</emphasis></title> - <step> - <para> - Log into the portal as an administrator and go to the Application Registry (Click <ulink url="http://localhost:8080/portal/private/classic/administration/registry">http://localhost:8080/portal/private/classic/administration/registry</ulink> if using the default installation). - </para> - - </step> - <step> - <para> - Add the WSRP Configuration portlet to the Administration category. If the Import Applications functionality is used, the WSRP Configuration portlet will be automatically added to the Administration category. - </para> - - </step> - <step> - <para> - Once the portlet is added to a category, it can be added to a page and used. It is recommended that it be added to the same page as the Application Registry (as other operations relating to WSRP and adding portlets to categories are somewhat related). Add the WSRP Configuration portlet to the page using the standard procedure. - </para> - - </step> - - </procedure> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-The_Configuration_Portlet-Using_the_Configuration_portlet"> - <title><emphasis role="bold">Using the Configuration portlet</emphasis></title> - <mediaobject> - <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/config_init.png" format="PNG" scale="120" width="444" /> - </imageobject> - <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/config_init.png" format="PNG" width="444" /> - </imageobject> - - </mediaobject> - <para> - This screen presents all the configured consumers associated with their status and possible actions on them. - </para> - <para> - A Consumer can be active or inactive. Activating a Consumer means that it is ready to act as a portlet provider. - </para> - <para> - Note also that a Consumer can be marked as requiring <emphasis>refresh</emphasis>, which means that the information held about it might not be up to date. Refreshing it from the remote Producer will update this information. - </para> - <para> - This can happen for several reasons: the service description for that remote Producer has not been fetched yet, the cached version has expired or modifications have been made to the configuration that could potentially invalidate it, thus requiring re-validation of the information. - </para> - <para> - To create a new Consumer: - </para> - <procedure id="proc-Reference_Guide_eXo_JCR_1.14-Using_the_Configuration_portlet-Creating_a_Consumer"> - <title><emphasis role="bold">Creating a Consumer</emphasis></title> - <step> - <para> - Type "<literal>netunity</literal>" into the "<emphasis role="bold">Create a consumer named:</emphasis>" field. - </para> - - </step> - <step> - <para> - Click on "<emphasis role="bold">Create consumer</emphasis>" to create a new Consumer called <literal>netunity</literal>. - </para> - <mediaobject> - <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/config_create.png" format="PNG" scale="100" /> - </imageobject> - <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/config_create.png" format="PNG" /> - </imageobject> - - </mediaobject> - - </step> - <step> - <para> - In the next form, set the cache expiration value to <parameter>300</parameter> seconds. - </para> - - </step> - <step> - <para> - Leave the default timeout value for web services (WS) operations. - </para> - - </step> - <step> - <para> - Enter the WSDL URL for the producer in the text field. - </para> - - </step> - <step> - <para> - Press the "Refresh &amp; Save" button: - </para> - <mediaobject> - <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/config_wsdl.png" format="PNG" scale="120" width="444" /> - </imageobject> - <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/config_wsdl.png" format="PNG" width="444" /> - </imageobject> - - </mediaobject> - - </step> - - </procedure> - - <para> - This will retrieve the service description associated with the Producer which WSRP interface is described by the WSDL file found at the URL entered. - </para> - <para> - In this case, querying the service description will show that the Producer requires registration, that it requested three registration properties and that the current configuration is missing values for these properties: - </para> - <mediaobject> - <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/config_missing.png" format="PNG" scale="120" width="444" /> - </imageobject> - <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/config_missing.png" format="PNG" width="444" /> - </imageobject> - - </mediaobject> - <para> - This particular producer requests simple <literal>Yes</literal> or <literal>No</literal> values for the three registration properties. - </para> - <para> - Enter <literal>No</literal>, <literal>Yes</literal> and <literal>No</literal> (in that order) for the values and then pressing the "Refresh &amp; Save" button should result in: - </para> - <mediaobject> - <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/config_end.png" format="PNG" scale="120" width="444" /> - </imageobject> - <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/config_end.png" format="PNG" width="444" /> - </imageobject> - - </mediaobject> - <note> - <title>Values</title> - <para> - Unfortunately there is no automated way to learn about which possible values (if any) are expected by the remote Producer. Possible values may be indicated in the registration property description but this is not always the case. Refer to the specific Producer's documentation. - </para> - - </note> - <para> - The Consumer for the <literal>netunity</literal> Producer should now be available as a portlet provider and be ready to be used. - </para> - <para> - If the producer had required registration but did not require any registration properties, as is the case for the <literal>selfv2</literal> consumer (the consumer that accesses the portlets made remotely available by JBoss Enterprise Portal Platform's producer via WSRP 2), the following screen would have appeared after pressing the "Refresh &amp; Save" button: - </para> - <mediaobject> - <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/config_refresh.png" format="PNG" scale="120" width="444" /> - </imageobject> - <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/config_refresh.png" format="PNG" width="444" /> - </imageobject> - - </mediaobject> - - </section> - - - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Configuring_a_Remote_Producer-Using_XML"> - <title>Using XML</title> - <para> - Although using the WSRP Configuration portlet to configure Consumers is recommended, the WSRP component provides an alternative way to configure consumers. - </para> - <para> - This is done by editing the <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/conf/gatein/wsrp-consumers-config.xml</filename> XML file. - </para> - <!-- Removed in GateIn revision 8119 -<programlisting language="XML" role="XML"><xi:include href="../extras/WSRP/default257.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <para> - The file as shown above specifies access to two producers: <literal>self</literal>, which consumes JBoss Enterprise Portal Platform's own WSRP producer (albeit in a version that assumes that the producer requires a value for an <literal>email</literal> registration property), and <literal>oracle</literal>, which consumes Oracle's public producer, both in configurations as shown in the procedure above. - </para> --> <note> - <title>XML Elements</title> - <para> - An XML Schema defining which elements are available to configure Consumers via XML can be found in <filename><replaceable>WSRP_PATH</replaceable>/lib/wsrp-integration-api-<replaceable>WSRP_VERSION</replaceable>.jar/xsd/gatein_wsrp_consumer_1_0.xsd </filename> - </para> - - </note> - <!-- Removed in GateIn revision 8119 - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Consuming_Remote_WSRP_Portlets-Configuring_Access_to_Remote_Producers_via_XML"> - <title>Configuring Access to Remote Producers via XML</title> - - <para> - Again, configuring consumers via XML is done by editing <filename><replaceable>WSRP_PATH</replaceable>/lib/wsrp-consumer-<replaceable>WSRP_VERSION</replaceable>.jar/conf/wsrp-consumers-config.xml</filename>. - </para> --> <formalpara id="form-Reference_Guide_eXo_JCR_1.14-Using_XML-The_Consumer_Configuration_file"> - <title>The Consumer Configuration file</title> - <para> - It is important to understand how the XML Consumers configuration file is processed. It is read the first time the WSRP service starts and the associated information is then put under control of the JCR (Java Content Repository). - </para> - - </formalpara> - <para> - Subsequent launches of the WSRP service will use the JCR-stored information for all producers that are already known to JBoss Enterprise Portal Platform. More specifically, the <filename>wsrp-consumers-config.xml</filename> file is scanned for producer identifiers. Any identifier that is already known will be bypassed and the JCR information associated with this remote producer will be used. - </para> - <para> - The information defined at the XML level is only processed for producer definition for which no information is already present in the JCR. - </para> - <para> - Therefore, to delete a Producer configuration, the associated information in the database must be deleted (this can be accomplished using the configuration portlet as shown in <xref linkend="sect-Reference_Guide_eXo_JCR_1.14-Configuring_a_Remote_Producer-The_Configuration_Portlet" /> ). - </para> - <para> - The associated information in <filename>wsrp-consumers-config.xml</filename> (if such information exists) must also be removed, otherwise the producer will be re-created the next time the WSRP is launched. - </para> - <section id="sect-Reference_Guide_eXo_JCR_1.14-Using_XML-Required_Configuration_Information"> - <title>Required Configuration Information</title> - <para> - The following information needs to be provided to configure access to a remote Producer: - </para> - <orderedlist> - <listitem> - <para> - An identifier must be provided for the producer being configured so that it can be referred to later. This is done in the mandatory <literal>id</literal> attribute of the <literal>&lt;wsrp-producer&gt;</literal> element. - </para> - - </listitem> - <listitem> - <para> - JBoss Enterprise Portal Platform also needs to know about the remote Producer's endpoints to be able to connect to the remote web services and perform WSRP invocations. Use the <literal>&lt;endpoint-wsdl-url&gt;</literal> element to specify the URL for the WSDL description of the remote WSRP service. - </para> - - </listitem> - - </orderedlist> - <para> - Both the <literal>id</literal> attribute and <literal>&lt;endpoint-wsdl-url&gt;</literal> elements are required for a functional remote producer configuration. - </para> - - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Using_XML-Optional_Configuration"> - <title>Optional Configuration</title> - <para> - It is also possible to provide additional configuration, which, in some cases, might be important to establish a proper connection to the remote producer. - </para> - <variablelist id="vari-Reference_Guide_eXo_JCR_1.14-Optional_Configuration-Optional_Configurations"> - <title>Optional Configurations</title> - <varlistentry> - <term>Caching</term> - <listitem> - <para> - To prevent unnecessary traffic between the local consumer and the remote producer, it is possible to cache some of the information sent by the producer (such as the list of offered portlets) for a given duration. - </para> - <para> - The rate at which the information is refreshed is defined by the <literal>expiration-cache</literal> attribute of the <literal>&lt;wsrp-producer&gt;</literal> element (in seconds). - </para> - <para> - For example; providing a value of <literal>120</literal> for expiration-cache means that the producer information will not be refreshed for 2 minutes after it has been accessed. If no value is provided, JBoss Enterprise Portal Platform will always access the remote producer regardless of whether the remote information has changed or not. - </para> - <para> - Since, in most instances, the information provided by the producer does not change often, use of this caching facility to minimize bandwidth usage is recommended. - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>WS Timeout</term> - <listitem> - <para> - It is also possible to define a timeout after which WS operations are considered as failed. This is helpful to avoid blocking the WSRP service, as it waits on a service that does not answer. - </para> - <para> - Use the <literal>ws-timeout</literal> attribute of the <literal>&lt;wsrp-producer&gt;</literal> element to specify how many milliseconds the WSRP service will wait for a response from the remote producer before timing out. - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Pre-registration information</term> - <listitem> - <para> - Some producers require consumers to register with them before authorizing them to access their offered portlets. If known, some registration information can be provided in the producer configuration beforehand, so that the consumer can register with the remote producer when required. - </para> - <note> - <para> - Only simple String properties are supported. It is not possible to configure complex registration data. However, this should be sufficient for most cases. - </para> - - </note> - <para> - This pre-registration configuration is done via the <literal>&lt;registration-data&gt;</literal> element. - </para> - <para> - If the remote producer does not require any registration properties, only an empty <literal>&lt;registration-data&gt;</literal> element need be provided, as JBoss Enterprise Portal Platform can generate the mandatory information. - </para> - <para> - Values for the registration properties required by the remote producer can be provided via <literal>&lt;property&gt;</literal> elements. Refer to the example below for more details. - </para> - <para> - Additionally, the default consumer name automatically provided by JBoss Enterprise Portal Platform can be overridden via the <literal>&lt;consumer-name&gt;</literal> element. When providing a consumer name, please remember that it should uniquely identify your consumer. - </para> - - </listitem> - - </varlistentry> - - </variablelist> - - </section> - - - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Configuring_a_Remote_Producer-Examples"> - <title>Examples</title> - <para> - This is the configuration of the <literal>selfv1</literal> and <literal>selfv2</literal> consumers as found in <filename>default-wsrp.xml</filename> with a cache expiring every 500 seconds and with a 50 second timeout for web service operations: - </para> - <note> - <para> - This file contains the default configuration and should not need to be edited. If modifications are required, the recommended practice is to follow the procedure detailed in <xref linkend="sect-Reference_Guide_eXo_JCR_1.14-The_Configuration_Portlet-Using_the_Configuration_portlet" />. - </para> - - </note> - -<programlisting language="XML" role="XML"><xi:include href="../extras/WSRP/default258.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <para> - This is an example of a WSRP descriptor with registration data and cache expiring every minute: - </para> - -<programlisting language="XML" role="XML"><xi:include href="../extras/WSRP/default259.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - - </section> - - - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Consuming_Remote_WSRP_Portlets-Adding_remote_portlets_to_categories"> - <title>Adding remote portlets to categories</title> - <para> - Clicking on the Portlet link in the Application Registry will now show the remote portlets in the <emphasis role="bold">REMOTE</emphasis> tab in the left column: - </para> - <mediaobject> - <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/remote_portlets.png" format="PNG" scale="120" width="444" /> - </imageobject> - <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/remote_portlets.png" format="PNG" width="444" /> - </imageobject> - - </mediaobject> - <para> - These portlets are available to be used as regular portlets: they can be used in categories and added to pages. Using the Import Applications functionality will also automatically import them into categories based on the keywords they define. - </para> - <para> - More specifically, to add a <emphasis>WSRP</emphasis> portlet to a category, select <literal>wsrp</literal> in the Application Type drop-down menu: - </para> - <mediaobject> - <imageobject> - <imagedata align="center" fileref="images/WSRP/remote_portlets_category.png" format="PNG" scalefit="1" valign="middle" /> - </imageobject> - - </mediaobject> - - </section> - - - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Web_Services_for_Remote_Portlets_WSRP-Consumers_Maintenance"> - <title>Consumers Maintenance</title> - <section id="sect-Reference_Guide_eXo_JCR_1.14-Consumers_Maintenance-Modifying_a_Currently_Held_Registration"> - <title>Modifying a Currently Held Registration</title> - <section id="sect-Reference_Guide_eXo_JCR_1.14-Modifying_a_Currently_Held_Registration-Registration_Modification_for_Service_Upgrade"> - <title>Registration Modification for Service Upgrade</title> - <para> - Producers often offer several levels of service depending on consumers' subscription levels (for example). This is implemented at the WSRP level with the registration concept: producers can assert which level of service to provide to consumers based on the values of given registration properties. - </para> - <para> - There may also be cases where the registration information has changed and must be updated. For example, the producer required you to provide a valid email and the previous email address is not valid anymore and needs to be updated. - </para> - <para> - Therefore at times it may be necessary to modify the registration that sets the service agreement between a consumer and a producer. - </para> - <para> - For example; the producer requiring an email that was configured in <xref linkend="sect-Reference_Guide_eXo_JCR_1.14-Configuring_a_Remote_Producer-The_Configuration_Portlet" /> . In that case the producer was requiring registration and required a value to be provided for the <literal>email</literal> property. - </para> - <para> - To update the email address that was provided, the remote producer must be informed that some registration data has been modified. - </para> - <para> - The following procedure assumes access to the producer has been configured as previously described. - </para> - <procedure> - <step> - <para> - Go to the configuration screen for the <literal>self</literal> producer and change the value of <literal>email</literal> to <literal&gt;foo(a)example.com&lt;/literal&gt; instead of <literal&gt;example(a)example.com&lt;/literal&gt;: - </para> - <mediaobject> - <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/modify_reg_start.png" format="PNG" scale="100" width="444" /> - </imageobject> - <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/modify_reg_start.png" format="PNG" width="444" /> - </imageobject> - - </mediaobject> - - </step> - <step> - <para> - Click on "<emphasis role="bold">Update properties</emphasis>" to save the change. A "<emphasis role="bold">Modify registration</emphasis>" button should now appear to let you send this new data to the remote producer: - </para> - <mediaobject> - <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/modify_reg_modify.png" format="PNG" scale="100" width="444" /> - </imageobject> - <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/modify_reg_modify.png" format="PNG" width="444" /> - </imageobject> - - </mediaobject> - - </step> - <step> - <para> - Click on <emphasis role="bold">Modify registration</emphasis> and, if the updated registration details have been accepted by the remote producer the following should appear: - </para> - <mediaobject> - <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/modify_reg_end.png" format="PNG" scale="120" width="444" /> - </imageobject> - <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/modify_reg_end.png" format="PNG" width="444" /> - </imageobject> - - </mediaobject> - - </step> - - </procedure> - - - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Modifying_a_Currently_Held_Registration-Registration_Modification_on_Producer_Error"> - <title>Registration Modification on Producer Error</title> - <para> - If a Producer administrator changes the requirements for registered consumers, invoking operations on the producer may fail with an <exceptionname>OperationFailedFault</exceptionname>. JBoss Enterprise Portal Platform will attempt to assist in these cases. - </para> - <para> - This section will discuss an example using the <literal>self</literal> producer. - </para> - <para> - Assuming that the registration requires a valid value for an <literal>email</literal> registration property (as has been shown) the configuration screen for this producer should show: - </para> - <mediaobject> - <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/config_self.png" format="PNG" scale="120" width="444" /> - </imageobject> - <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/config_self.png" format="PNG" width="444" /> - </imageobject> - - </mediaobject> - <para> - If the administrator of the producer now requires an additional value to be provided for a <literal>name</literal> registration property operations with this producer will fail. - </para> - <para> - If a registration modification is required, go to the configuration screen for this remote producer and refresh the information held by the consumer by pressing "<emphasis role="bold">Refresh &amp; Save</emphasis>": - </para> - <mediaobject> - <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/modify_reg_self.png" format="PNG" scale="120" width="444" /> - </imageobject> - <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/modify_reg_self.png" format="PNG" width="444" /> - </imageobject> - - </mediaobject> - <para> - The configuration screen now shows the currently held registration information and the expected information from the producer. - </para> - <para> - Enter a value for the <literal>name</literal> property and then click on "<emphasis role="bold">Modify registration</emphasis>". If the producer accepts the new registration data, the following screen will appear: - </para> - <mediaobject> - <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/modify_reg_self_end.png" format="PNG" scale="120" width="444" /> - </imageobject> - <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/modify_reg_self_end.png" format="PNG" width="444" /> - </imageobject> - - </mediaobject> - <note> - <title><emphasis role="bold">JBoss Enterprise Portal Platform &VY; and WSRP 1 Exceptions</emphasis></title> - <para> - In WSRP 1, it can be difficult to ascertain what caused an <exceptionname> OperationFailedFault </exceptionname> as it is a generic exception returned by producers during a failed method invocation. - </para> - <para> - An <exceptionname>OperationFailedFault</exceptionname> failure can be caused by several different reasons, one of them being a request to modify the registration data. - </para> - <para> - In these instances examining the log files may assist in gathering more information about the problem. - </para> - <para> - WSRP 2 introduces an exception that is specific to a request to modify registrations which reduces the ambiguity that currently exists. - </para> - - </note> - - </section> - - - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Consumers_Maintenance-Consumer_Operations"> - <title>Consumer Operations</title> - <para> - Several operations are available from the consumer list view of the WSRP configuration portlet: - </para> - <mediaobject> - <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/consumer_operations.png" format="PNG" scale="120" width="444" /> - </imageobject> - <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/consumer_operations.png" format="PNG" width="444" /> - </imageobject> - - </mediaobject> - <para> - The available operations are: - </para> - <variablelist> - <varlistentry> - <term>Configure</term> - <listitem> - <para> - Displays the consumer details and allows user to edit them. - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Refresh</term> - <listitem> - <para> - Forces the consumer to retrieve the service description from the remote producer to refresh the local information (such as offered portlets, registration information). - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Activate/Deactivate</term> - <listitem> - <para> - Activates or deactivates a consumer, governing whether it will be available to provide portlets and receive portlet invocations. - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Register/De-register</term> - <listitem> - <para> - Registers or de-registers a consumer based on whether registration is required and/or acquired. - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Delete</term> - <listitem> - <para> - Destroys the consumer, after de-registering it if it was registered. - </para> - - </listitem> - - </varlistentry> - - </variablelist> - <formalpara id="form-Reference_Guide_eXo_JCR_1.14-Consumer_Operations-Additional_Functionalities_in_WSRP_2.0"> - <title><emphasis role="bold">Additional Functionalities in WSRP 2.0</emphasis></title> - <para> - In addition to those listed above, the WSRP 2.0 implementation in JBoss Enterprise Portal Platform &VY; also includes the following functions: - </para> - - </formalpara> - <variablelist id="vari-Reference_Guide_eXo_JCR_1.14-Consumer_Operations-Additional_Functions"> - <title>Additional Functions:</title> - <varlistentry> - <term>Export</term> - <listitem> - <para> - Exports some or all of the consumer's portlets to be able to later import them in a different context - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Import</term> - <listitem> - <para> - Imports some or all of previously exported portlets. - </para> - - </listitem> - - </varlistentry> - - </variablelist> - <section id="sect-Reference_Guide_eXo_JCR_1.14-Consumer_Operations-Importing_and_Exporting_Portlets"> - <title><emphasis role="bold">Importing and Exporting Portlets</emphasis></title> - <para> - Import and export are new functionalities added in WSRP 2. - </para> - <para> - Exporting a portlet allows a consumer to get an opaque representation of the portlet which can then be use by the corresponding import operation to reconstitute it. - </para> - <para> - This is mostly used in migration scenarios during batch operations. Since JBoss Enterprise Portal Platform does not currently support automated migration of portal data, the functionality provided as part of WSRP 2 is necessarily less complete than it could be with full portal support. - </para> - <para> - The import/export implementation in JBoss Enterprise Portal Platform allows users to export portlets from a given consumer and then import them back to replace existing portlets assigned to windows on pages by the previously exported portlets. - </para> - <procedure> - <title></title> - <step> - <para> - Click on the "<guilabel>Export</guilabel>" action for a given consumer to display the list of portlets currently made available by this specific consumer. An example list is shown below: - </para> - <mediaobject> - <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/export_portlet_list.png" format="PNG" scale="120" width="444" /> - </imageobject> - <imageobject role="fo"> - <imagedata align="center" contentwidth="150mm" fileref="images/WSRP/export_portlet_list.png" format="PNG" width="444" /> - </imageobject> - - </mediaobject> - - </step> - <step> - <para> - Once portlets have been selected, they can be exported by clicking on the "<guilabel>Export</guilabel>" button. This makes them available for later import: - </para> - <mediaobject> - <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/export_done.png" format="PNG" scale="120" width="444" /> - </imageobject> - <imageobject role="fo"> - <imagedata align="center" contentwidth="150mm" fileref="images/WSRP/export_done.png" format="PNG" width="444" /> - </imageobject> - - </mediaobject> - - </step> - <step> - <para> - The portlets can be re-imported directly by pressing the "<guilabel>Use for import</guilabel>" button or, on the Consumers list page, using the "<guilabel>Import</guilabel>" action for a given consumer. - </para> - <para> - The example below assumes that the second option has been used and that several sets of previously exported portlets are available to import from. After clicking the action link, a screen similar to the one below should appear: - </para> - <mediaobject> - <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/export_list.png" format="PNG" scale="120" width="444" /> - </imageobject> - <imageobject role="fo"> - <imagedata align="center" contentwidth="150mm" fileref="images/WSRP/export_list.png" format="PNG" width="444" /> - </imageobject> - - </mediaobject> - <para> - This screen presents the list of available exports with available operations for each. - </para> - <variablelist id="vari-Reference_Guide_eXo_JCR_1.14-Importing_and_Exporting_Portlets-Operations"> - <title>Operations:</title> - <varlistentry> - <term>View</term> - <listitem> - <para> - Displays the export details as previously seen when the export was first performed. - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Delete</term> - <listitem> - <para> - Deletes the selected export, asking you for confirmation first. - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>Use for import</term> - <listitem> - <para> - Selects the export to import portlets from. - </para> - - </listitem> - - </varlistentry> - - </variablelist> - - </step> - <step> - <para> - Once you have selected an export to import from, you will see a screen similar to the one below: - </para> - <mediaobject> - <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/import_start.png" format="PNG" scale="120" width="444" /> - </imageobject> - <imageobject role="fo"> - <imagedata align="center" contentwidth="150mm" fileref="images/WSRP/import_start.png" format="PNG" width="444" /> - </imageobject> - - </mediaobject> - <para> - The screen displays the list of available exported portlets for the previously selected export. You can select which portlet you want to import by checking the checkbox next to its name. - </para> - - </step> - <step> - <para> - Select the content of which window the imported portlet will replace. This process is done in three steps: - </para> - <para> - This example assumes that you have the following page called <literal>page1</literal> which contains two windows called <literal>NetUnity WSRP 2 Interop - Cache Markup (remote)</literal> and <literal>/samples-remotecontroller-portlet.RemoteControl (remote)</literal>, as shown below: - </para> - <mediaobject> - <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/import_original_page.png" format="PNG" scale="120" width="444" /> - </imageobject> - <imageobject role="fo"> - <imagedata align="center" contentwidth="150mm" fileref="images/WSRP/import_original_page.png" format="PNG" width="444" /> - </imageobject> - - </mediaobject> - <para> - In this example, we want to replace the content of the <literal>/samples-remotecontroller-portlet.RemoteControl (remote)</literal> with the content of the <literal>/ajaxPortlet.JSFAJAXPortlet</literal> portlet that was previously exported. - </para> - <procedure> - <title></title> - <step> - <para> - Check the box next to the <literal>/ajaxPortlet.JSFAJAXPortlet</literal> portlet name to indicate that you want to import its data. - </para> - - </step> - <step> - <para> - Select <literal>page1</literal> in the list of available pages. The screen will then refresh to display the list of available windows on that page, similar to the image below: - </para> - <mediaobject> - <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/import_selected_page.png" format="PNG" scale="120" width="444" /> - </imageobject> - <imageobject role="fo"> - <imagedata align="center" contentwidth="150mm" fileref="images/WSRP/import_selected_page.png" format="PNG" width="444" /> - </imageobject> - - </mediaobject> - <note> - <title>Note</title> - <para> - At this point, you still need to select which window content you want to replace before being able to complete the import operation - </para> - - </note> - - </step> - <step> - <para> - Select the <literal>/samples-remotecontroller-portlet.RemoteControl (remote)</literal> window, which enables the "<guilabel>Import</guilabel>" button. This indicates that all the necessary data to perform the import is available. - </para> - - </step> - <step> - <para> - Click the "<guilabel>Import</guilabel>" button. A screen similar to the one below will appear: - </para> - <mediaobject> - <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/import_success.png" format="PNG" scale="120" width="444" /> - </imageobject> - <imageobject role="fo"> - <imagedata align="center" contentwidth="150mm" fileref="images/WSRP/import_success.png" format="PNG" width="444" /> - </imageobject> - - </mediaobject> - - </step> - - </procedure> - - - </step> - <step> - <para> - The <literal>page1</literal> page should now show that the content of <literal>/samples-remotecontroller-portlet.RemoteControl (remote)</literal> window has been replaced by the content of the <literal>/ajaxPortlet.JSFAJAXPortlet</literal> imported portlet and that the window has been renamed appropriately. - </para> - <mediaobject> - <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/import_modified_page.png" format="PNG" scale="120" width="444" /> - </imageobject> - <imageobject role="fo"> - <imagedata align="center" contentwidth="150mm" fileref="images/WSRP/import_modified_page.png" format="PNG" width="444" /> - </imageobject> - - </mediaobject> - - </step> - - </procedure> - - - </section> - - - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Consumers_Maintenance-Erasing_Local_Registration_Data"> - <title>Erasing Local Registration Data</title> - <para> - In rare cases, it may be necessary to erase the local data without being able to de-register first. - </para> - <para> - This can occur when a consumer is registered with a producer that has been modified by its administrator to not require registration any longer. - </para> - <para> - In this scenario, local registration information can be erased from the consumer to allow it to resume interacting with the remote producer. - </para> - <para> - To do this click on the "<emphasis role="bold">Erase local registration</emphasis>" button next to the registration context information on the consumer configuration screen: - </para> - <mediaobject> - <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/erase_registration.png" format="PNG" scale="80" width="444" /> - </imageobject> - <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/erase_registration.png" format="PNG" width="444" /> - </imageobject> - - </mediaobject> - <warning> - <para> - This operation is dangerous as it can result in inability to interact with the remote producer if invoked when not required. The warning message below will be displayed before any data is erased. - </para> - <mediaobject> - <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/erase_registration_warning.png" format="PNG" scale="100" width="444" /> - </imageobject> - <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/erase_registration_warning.png" format="PNG" width="444" /> - </imageobject> - - </mediaobject> - - </warning> - - </section> - - - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Web_Services_for_Remote_Portlets_WSRP-Configuring_the_WSRP_Producer"> - <title>Configuring the WSRP Producer</title> - <section id="sect-Reference_Guide_eXo_JCR_1.14-Configuring_the_WSRP_Producer-Overview"> - <title>Overview</title> - <para> - The behavior of the Portal's WSRP Producer can be configured using the WSRP administration interface, (this is the recommended method), or by editing the <filename><replaceable>WSRP_PATH</replaceable>/lib/gatein.portal.component.wsrp-<replaceable>&lt;VERSION&gt;</replaceable>-epp-GA.jar/conf/wsrp-producer-config.xml</filename> file. - </para> - <para> - Several aspects can be modified with respect to whether registration is required for consumers to access the Producer's services. An XML Schema for the configuration format is available at <filename><replaceable>WSRP_PATH</replaceable>/lib/wsrp-integration-api-<replaceable>WSRP_VERSION</replaceable>.jar/xsd/gatein_wsrp_producer_1_0.xsd </filename>. - </para> - <para> - An alternative to editing the default <filename>wsrp-producer-config.xml</filename> file is to make a custom copy containing the required configuration options. - </para> - <para> - If a copy is used in place of the original, however, the <filename><replaceable>WSRP_PATH</replaceable>/02portal.war/WEB-INF/conf/wsrp/wsrp-configuration.xml</filename> <emphasis role="bold">must</emphasis> be updated to reference the custom file (this file defines the component <literal>WSRPServiceIntegration</literal> and contains a producer and consumer configuration location). - </para> - - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Configuring_the_WSRP_Producer-Default_Configuration"> - <title>Default Configuration</title> - <para> - The default producer configuration requires that consumers register with it before providing access to its services. However it does not require any specific registration properties (excepting those mandated by the WSRP standard). - </para> - <para> - It does, however, require consumers to be registered before sending them a full service description. This means that the WSRP producer will not provide the list of offered portlets and other capabilities to unregistered consumers. - </para> - <para> - The producer also uses the default <classname>RegistrationPolicy</classname> paired with the default <classname>RegistrationPropertyValidator</classname>. - </para> - <para> - This allows users to customize how Portal's WSRP Producer decides whether a given registration property is valid or not (however property validators are discussed in greater detail in <xref linkend="sect-Reference_Guide_eXo_JCR_1.14-Configuring_the_WSRP_Producer-Registration_Configuration" /> ). - </para> - <para> - JBoss Enterprise Portal Platform provides a web interface to configure the producer's behavior. It can be accessed by clicking on the "<emphasis role="bold">Producer Configuration</emphasis>" tab of the "<emphasis role="bold">WSRP</emphasis>" page of the "<emphasis role="bold">admin</emphasis>" portal. - </para> - <para> - The default configuration should show: - </para> - <mediaobject> - <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/producer_default.png" format="PNG" scale="110" width="444" /> - </imageobject> - <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/producer_default.png" format="PNG" width="444" /> - </imageobject> - - </mediaobject> - <para> - You can specify whether or not the producer will send the full service description to unregistered consumers, and, if it requires registration, which <literal>RegistrationPolicy</literal> to use (and, if needed, which <literal>RegistrationPropertyValidator</literal>), along with required registration property description for which consumers must provide acceptable values to successfully register. - </para> - <para> - WSDL URLs to access JBoss Enterprise Portal Platform's WSRP producer are now displayed in either in WSRP 1 or WSRP 2 mode. - </para> - - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Configuring_the_WSRP_Producer-Registration_Configuration"> - <title>Registration Configuration</title> - <para> - In order to have consumers register with Portal's producer the Portal's behavior with respect to registration must be configured. - </para> - <para> - Registration is optional, as are registration properties. The producer can require registration without requiring consumers to pass any registration properties as is the case in the default configuration. - </para> - <para> - The following section discusses configuring a producer's registration behavior from a blank state: - </para> - <mediaobject> - <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/producer_blank.png" format="PNG" width="700" /> - </imageobject> - <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/producer_blank.png" format="PNG" width="444" /> - </imageobject> - - </mediaobject> - <procedure> - <step> - <para> - To allow unregistered consumers to see the list of offered portlets, leave the first checkbox ("<emphasis role="bold">Access to full service description requires consumers to be registered.</emphasis>") unchecked. - </para> - - </step> - <step> - <para> - To specify, however, that consumers will need to be registered to be able to interact with the producer, check the second box ("<emphasis role="bold">Requires registration. Modifying this information will trigger invalidation of consumer registrations."</emphasis>). - </para> - <para> - The screen will refresh and display: - </para> - <mediaobject> - <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/producer_registration.png" format="PNG" width="700" /> - </imageobject> - <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/producer_registration.png" format="PNG" width="444" /> - </imageobject> - - </mediaobject> - - </step> - <step> - <para> - The fully-qualified name for the <classname>RegistrationPolicy</classname> and <classname>RegistrationPropertyValidator</classname> can be specified here. The default values are acceptable. Refer to <xref linkend="sect-Reference_Guide_eXo_JCR_1.14-Registration_Configuration-Customization_of_Registration_Handling_Behavior" /> for more information. - </para> - - </step> - <step> - <para> - To add a registration property called <literal>email</literal> click "<emphasis role="bold">Add property</emphasis>" and enter the appropriate information in the fields, providing a description for the registration property that can be used by consumers to determine its purpose: - </para> - <mediaobject> - <imageobject role="html"> - <imagedata align="center" fileref="images/WSRP/producer_email.png" format="PNG" width="700" /> - </imageobject> - <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/producer_email.png" format="PNG" width="444" /> - </imageobject> - - </mediaobject> - - </step> - <step> - <para> - Press "Save" to record the modifications. - </para> - - </step> - - </procedure> - - <note> - <para> - At this time, only String (<literal>xsd:string</literal>) properties are supported. - </para> - - </note> - <note> - <para> - If consumers are already registered with the producer, modifying the configuration of required registration information will trigger the invalidation of held registrations, requiring consumers to modify their registration before being able to access the producer again. The consumer side of that process is documented in <xref linkend="sect-Reference_Guide_eXo_JCR_1.14-Modifying_a_Currently_Held_Registration-Registration_Modification_on_Producer_Error" />. - </para> - - </note> - <section id="sect-Reference_Guide_eXo_JCR_1.14-Registration_Configuration-Customization_of_Registration_Handling_Behavior"> - <title>Customization of Registration Handling Behavior</title> - <para> - Registration handling behavior can be customized by users to suit their Producer needs. This is done with an implementation of the <classname>RegistrationPolicy</classname> interface. - </para> - <para> - This interface defines methods that are called by Portal's Registration service so that decisions can be made appropriately. A default registration policy that provides basic behavior is provided and should be enough for most user needs. - </para> - <para> - While the default registration policy provides default behavior for most registration-related aspects, one aspect requires specific configuration: whether a given value for a registration property is acceptable by the WSRP Producer. - </para> - <para> - This is done by plugging a <classname>RegistrationPropertyValidator</classname> into the default registration policy. This allows users to define their own validation mechanism. - </para> - <para> - Refer to the <trademark class="trade">Javadoc</trademark> for <classname>org.gatein.registration.RegistrationPolicy</classname> and <classname>org.gatein.registration.policies.RegistrationPropertyValidator</classname> for more details on what is expected of each method. - </para> - <para> - A defined registration policy is required for the producer to be correctly configured. Do this by specifying the qualified class name of the registration policy. - </para> - <para> - As it is anticipated that most users will use the default registration policy, it is possible to provide the class name of a custom property validator instead to customize the default registration policy behavior. Note that property validators are only used by the default policy. - </para> - <note> - <para> - Since the policy or the validator are defined via their class name and dynamically loaded, it is important to ensure that the identified class is available to the application server. - </para> - <para> - One way to accomplish that is to deploy the policy implementation as a JAR file in the AS instance deploy directory. - </para> - <para> - Note also that, since both policies and validators are dynamically instantiated, they must provide a default, no-argument constructor. - </para> - - </note> - - </section> - - - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Configuring_the_WSRP_Producer-WSRP_Validation_Mode"> - <title>WSRP Validation Mode</title> - <para> - The lack of conformance kit and the wording of the WSRP specification leaves room for differing interpretations, resulting in interoperability issues. It is therefore possible to encounter issues when using consumers from different vendors. - </para> - <para> - Experience of these issues has produced a way to relax the validation that the WSRP producer performs on the data provided by consumers to help with interoperability by accepting data that would normally be invalid. - </para> - <para> - Note that the our validation algorithm is only relaxed on aspects of the specification that are deemed harmless such as invalid language codes. - </para> - <para> - By default, the WSRP producer is configured in strict mode. If you experience issues with a given consumer, you may attempt to relax the validation mode. Un-checking the "Use strict WSRP compliance" checkbox on the Producer configuration screen to do this. - </para> - - </section> - - - </section> - - <section id="sect-Reference_Guide_eXo_JCR_1.14-Web_Services_for_Remote_Portlets_WSRP-Removing_WSRP"> - <title>Removing WSRP</title> - <para> - If you are not going to use WSRP in your JBoss Enterprise Portal Platform instance, the WSRP configuration files may be left in place. They will not adversely affect your installation. - </para> - <para> - However, if you wish to completely remove WSRP from your portal installation, remove the <filename>gatein-wsrp-integration.ear</filename> file from your application server deploy directory. - </para> - <!-- <para> - However, if you wish to completely remove WSRP from your portal installation, follow this procedure: - </para> - <procedure> - <title></title> - <step> - <para> - Navigate to the <filename><replaceable>JBOSS_HOME</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/conf/gatein/</filename> directory of your JBoss Enterprise Portal Platform instance. - </para> - <substeps> - <step> - <para> - Open the <filename>configuration.xml</filename> file and remove the following lines: - </para> - -<programlisting language="XML" role="XML">&lt;value&gt; - &lt;string&gt;wsrp-producer&lt;/string&gt; -&lt;/value&gt; -</programlisting> - - </step> - - </substeps> - - </step> - <step> - <para> - Navigate up two directory levels and into the <filename>deploy/gatein.ear/</filename> directory (For example: <command>cd ../../deploy/gatein.ear/</command>). - </para> - - </step> - <step> - <para> - Remove the following files: - </para> - <itemizedlist> - <listitem> - <para> - <filename>wsrp-admin-gui.war</filename> - </para> - - </listitem> - <listitem> - <para> - <filename>wsrp-producer.war</filename> - </para> - - </listitem> - - </itemizedlist> - - </step> - <step> - <para> - Navigate into the <filename>lib/</filename> subdirectory and remove the following files: - </para> - <itemizedlist> - <listitem> - <para> - <filename>gatein.portal.component.wsrp-PORTAL_VERSION.jar</filename> - </para> - - </listitem> - <listitem> - <para> - <filename>wsrp-common-WSRP_VERSION.jar</filename> - </para> - - </listitem> - <listitem> - <para> - <filename>wsrp-consumer-WSRP_VERSION.jar</filename> - </para> - - </listitem> - <listitem> - <para> - <filename>wsrp-integration-api-WSRP_VERSION.jar</filename> - </para> - - </listitem> - <listitem> - <para> - <filename>wsrp-producer-lib-WSRP_VERSION.jar</filename> - </para> - - </listitem> - <listitem> - <para> - <filename>wsrp-wsrp1-ws-WSRP_VERSION.jar</filename> - </para> - - </listitem> - <listitem> - <para> - <filename>wsrp-wsrp2-ws-WSRP_VERSION.jar</filename> - </para> - - </listitem> - - </itemizedlist> - - </step> - <step> - <para> - Return to the <filename>gatein.ear/</filename> directory and move into the <filename>META-INF/</filename> subdirectory. - </para> - <substeps> - <step> - <para> - Open the <filename>application.xml</filename> file and remove the following modules: - </para> - -<programlisting language="XML" role="XML">&lt;module&gt; - &lt;web&gt; - &lt;web-uri&gt;wsrp-admin-gui.war&lt;/web-uri&gt; - &lt;context-root&gt;wsrp-admin-gui&lt;/context-root&gt; - &lt;/web&gt; -&lt;/module&gt; -</programlisting> - -<programlisting language="XML" role="XML">&lt;module&gt; - &lt;web&gt; - &lt;web-uri&gt;wsrp-producer.war&lt;/web-uri&gt; - &lt;context-root&gt;wsrp-producer&lt;/context-root&gt; - &lt;/web&gt; -&lt;/module&gt; -</programlisting> - - </step> - <step> - <para> - Save and exit the file. - </para> - - </step> - - </substeps> - - </step> - <step> - <para> - Return to the <filename>gatein.ear/</filename> directory and navigate into the <filename>02portal.war/WEB-INF/conf/</filename> subdirectory. - </para> - <substeps> - <step> - <para> - Remove the <filename>wsrp/</filename> directory. - </para> - - </step> - <step> - <para> - Open the <filename>configuration.xml</filename> file and remove the following line: - </para> - -<programlisting language="XML" role="XML">&lt;import profiles="jboss"&gt;war:/conf/wsrp/wsrp-configuration.xml&lt;/import&gt; -</programlisting> - - </step> - <step> - <para> - Save and exit the file. - </para> - - </step> - - </substeps> - - </step> - <step> - <para> - From your current location, navigate into the <filename>portal/</filename> subdirectory. - </para> - <substeps> - <step> - <para> - Open the <filename>portal-configuration.xml</filename> file and remove the line: - </para> - -<programlisting language="XML" role="XML">&lt;value&gt;org.exoplatform.portal.pom.spi.wsrp.WSRPState&lt;/value&gt; -</programlisting> - - </step> - <step> - <para> - Save and exit the file. - </para> - - </step> - - </substeps> - - </step> - <step> - <para> - Return to the <filename>conf/</filename> directory and move into the <filename>jcr/</filename> subdirectory. - </para> - <substeps> - <step> - <para> - Open the <filename>jcr-configuration.xml</filename> file and remove the line: - </para> - -<programlisting language="XML" role="XML">&lt;property name="wsrp" value="http://www.gatein.org/jcr/wsrp/1.0/"/&gt; -</programlisting> - - </step> - <step> - <para> - Remove the following configuration file references: - </para> - -<programlisting language="XML" role="XML">&lt;value&gt;war:/conf/wsrp/consumers-configuration-nodetypes.xml&lt;/value&gt; -&lt;value&gt;war:/conf/wsrp/producer-configuration-nodetypes.xml&lt;/value&gt; -&lt;value&gt;war:/conf/wsrp/producer-registrations-nodetypes.xml&lt;/value&gt; -&lt;value&gt;war:/conf/wsrp/producer-pc-nodetypes.xml&lt;/value&gt; -&lt;value&gt;war:/conf/wsrp/migration-nodetypes.xml&lt;/value&gt; -</programlisting> - - </step> - <step> - <para> - Save and exit the file. - </para> - - </step> - <step> - <para> - Open the <filename>repository-configuration.xml</filename> and remove the <emphasis role="bold">WSRP</emphasis> workspace: - </para> - -<programlisting language="XML" role="XML"> - &lt;workspace name="wsrp-system"&gt; - &lt;container&gt; - &lt;properties&gt; - &lt;property name="source-name" value="${gatein.jcr.datasource.name}${container.name.suffix}"/&gt; - &lt;property name="dialect" value="${gatein.jcr.datasource.dialect}"/&gt; - &lt;property name="multi-db" value="false"/&gt; - &lt;property name="update-storage" value="true"/&gt; - &lt;property name="max-buffer-size" value="204800"/&gt; - &lt;property name="swap-directory" value="${gatein.jcr.data.dir}/swap/wsrp${container.name.suffix}"/&gt; - &lt;/properties&gt; - &lt;value-storages&gt; - &lt;value-storage id="gadgets" - &gt; - &lt;properties&gt; - &lt;property name="path" value="${gatein.jcr.storage.data.dir}/wsrp${container.name.suffix}"/&gt; - &lt;/properties&gt; - &lt;filters&gt; - &lt;filter property-type="Binary"/&gt; - &lt;/filters&gt; - &lt;/value-storage&gt; - &lt;/value-storages&gt; - &lt;/container&gt; - &lt;initializer&gt; - &lt;properties&gt; - &lt;property name="root-nodetype" value="nt:unstructured"/&gt; - &lt;property name="root-permissions" value="*:/platform/administrators read;*:/platform/administrators add_node;*:/platform/administrators set_property;*:/platform/administrators remove"/&gt; - &lt;/properties&gt; - &lt;/initializer&gt; - &lt;cache enabled="true"&gt; - &lt;properties&gt; - &lt;property name="jbosscache-configuration" value="${gatein.jcr.cache.config}" /&gt; - &lt;property name="jgroups-configuration" value="${gatein.jcr.jgroups.config}" /&gt; - &lt;property name="jgroups-multiplexer-stack" value="true" /&gt; - &lt;property name="jbosscache-cluster-name" value="jcr-${container.name.suffix}-wsrp-system" /&gt; - &lt;/properties&gt; - &lt;/cache&gt; - &lt;query-handler&gt; - &lt;properties&gt; - &lt;property name="index-dir" value="${gatein.jcr.index.data.dir}/wsrp-system${container.name.suffix}"/&gt; - &lt;property name="changesfilter-class" value="${gatein.jcr.index.changefilterclass}" /&gt; - &lt;property name="jbosscache-configuration" value="${gatein.jcr.index.cache.config}" /&gt; - &lt;property name="jgroups-configuration" value="${gatein.jcr.jgroups.config}" /&gt; - &lt;property name="jgroups-multiplexer-stack" value="true" /&gt; - &lt;property name="jbosscache-cluster-name" value="jcrindexer-${container.name.suffix}-wsrp-system" /&gt; - &lt;property name="max-volatile-time" value="60" /&gt; - &lt;/properties&gt; - &lt;/query-handler&gt; - &lt;lock-manager&gt; - &lt;properties&gt; - &lt;property name="time-out" value="15m" /&gt; - &lt;property name="jbosscache-configuration" value="${gatein.jcr.lock.cache.config}" /&gt; - &lt;property name="jgroups-configuration" value="${gatein.jcr.jgroups.config}" /&gt; - &lt;property name="jgroups-multiplexer-stack" value="true" /&gt; - &lt;property name="jbosscache-cluster-name" value="jcrlock-${container.name.suffix}-wsrp-system" /&gt; - &lt;property name="jbosscache-cl-cache.jdbc.table.name" value="jcrlock_wsrp_system" /&gt; - &lt;property name="jbosscache-cl-cache.jdbc.table.create" value="true" /&gt; - &lt;property name="jbosscache-cl-cache.jdbc.table.drop" value="false" /&gt; - &lt;property name="jbosscache-cl-cache.jdbc.table.primarykey" value="pk" /&gt; - &lt;property name="jbosscache-cl-cache.jdbc.fqn.column" value="fqn" /&gt; - &lt;property name="jbosscache-cl-cache.jdbc.node.column" value="node" /&gt; - &lt;property name="jbosscache-cl-cache.jdbc.parent.column" value="parent" /&gt; - &lt;property name="jbosscache-cl-cache.jdbc.datasource" value="${gatein.jcr.datasource.name}${container.name.suffix}" /&gt; - &lt;/properties&gt; - &lt;/lock-manager&gt; - &lt;/workspace&gt; -</programlisting> - - </step> - - </substeps> - - </step> - <step> - <title>Optional:</title> - <para> - Remove any references to <emphasis>WSRP</emphasis> from the following files: - </para> - <itemizedlist> - <listitem> - <para> - <filename>gatein.ear/01eXoResources.war/META-INF/MANIFEST.MF</filename> - </para> - - </listitem> - <listitem> - <para> - <filename>gatein.ear/META-INF/MANIFEST.MF</filename> - </para> - - </listitem> - <listitem> - <para> - <filename>gatein.ear/02portal.war/META-INF/MANIFEST.MF</filename> - </para> - - </listitem> - - </itemizedlist> - - </step> - - </procedure> --> - </section> - - -</chapter> - Copied: epp/docs/branches/5.2/Reference_Guide/en-US/modules/WSRP.xml (from rev 8139, epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/WSRP.xml) =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/WSRP.xml (rev 0) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/WSRP.xml 2011-11-25 00:48:53 UTC (rev 8141) @@ -0,0 +1,1370 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ + <!ENTITY % BOOK_ENTITIES SYSTEM "../Reference_Guide.ent"> + %BOOK_ENTITIES; + ]> +<chapter id="wsrp"> + <title>Web Services for Remote Portlets (WSRP)</title> + + <section> + <title>Introduction</title> + <para>The Web Services for Remote Portlets specification defines a web service interface for accessing and + interacting with interactive presentation-oriented web services. It has been produced through the efforts of + the Web Services for Remote Portlets (WSRP) OASIS Technical Committee. It is based on the requirements + gathered and on the concrete proposals made to the committee. + </para> + + <para>Scenarios that motivate WSRP functionality include: + <itemizedlist> + <listitem> + <para>Content hosts, such as portal servers, providing Portlets as presentation-oriented web services + that can be used by aggregation engines. + </para> + </listitem> + <listitem> + <para>Aggregating frameworks, including portal servers, consuming presentation-oriented web services + offered by content providers and integrating them into the framework. + </para> + </listitem> + </itemizedlist> + </para> + + <para>More information on WSRP can be found on the + <ulink url="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wsrp... website for WSRP</ulink>. + We suggest reading the + <ulink url="http://www.oasis-open.org/committees/download.php/10539/wsrp-pr... + for a good, albeit technical, overview of WSRP. + </para> + </section> + + <section id="wsrp_support"> + <title>Level of support in JBoss Enterprise Portal Platform</title> + <para>The WSRP Technical Committee defined + <ulink url="http://www.oasis-open.org/committees/download.php/3073">... Use Profiles</ulink> + to help with WSRP interoperability. We will refer to terms defined in that document in + this section. + </para> + + <para>JBoss Enterprise Portal Platform provides a Simple level of support for our WSRP Producer except that out-of-band registration + is not currently handled. We support in-band registration and persistent local state (which are + defined at the Complex level). + </para> + + <para>On the Consumer side, JBoss Enterprise Portal Platform provides a Medium level of support for WSRP, except that we only handle + HTML markup (as JBoss Enterprise Portal Platform itself doesn't handle other markup types). We do support explicit portlet + cloning and we fully support the PortletManagement interface. + </para> + + <para>As far as caching goes, we have Level 1 Producer and Consumer. We support Cookie handling properly on the + Consumer and our Producer requires initialization of cookies (as we have found that it improved interoperabilty + with some consumers). We don't support custom window states or modes, as JBoss Enterprise Portal Platform doesn't either. We do, + however, support CSS on both the Producer (though it's more a function of the portlets than inherent Producer + capability) and Consumer. + </para> + + <para>While we provide a complete implementation of WSRP 1.0, we do need to go through the + <ulink url="http://www.oasis-open.org/committees/download.php/6018">... statements</ulink> + and perform more interoperability testing (an area that needs to be better supported by the WSRP Technical + Committee and Community at large). + </para> + + <para>JBoss Enterprise Portal Platform supports WSRP 2.0 with a complete implementation of the non-optional features. The only + features that we have not implemented is support for lifetimes and leasing + support. + </para> + + <note> + <para>As of version &VY; of JBoss Enterprise Portal Platform, WSRP is only activated and supported + when JBoss Enterprise Portal Platform is deployed on JBoss Application Server. + </para> + </note> + </section> + + <section> + <title>Deploying JBoss Enterprise Portal Platform's WSRP services</title> + <para> + JBoss Enterprise Portal Platform provides a complete support of WSRP 1.0 and 2.0 standard interfaces and offers both consumer and + producer services. Starting with version 2.1.0-GA of the component, WSRP is packaged as a JBoss Enterprise Portal Platform + extension and is now self-contained in an easy to install package named + <filename>$JBOSS_PROFILE_HOME/deploy/gatein-wsrp-integration.ear</filename> + where + <filename>$JBOSS_PROFILE_HOME</filename> + refers to your JBoss AS profile directory (<filename>default</filename>, for instance). + </para> + <para> + The extension itself is composed of the following components, assuming + <code>$WSRP_VERSION</code> + (at the time of the writing, it was 2.1.0-GA) is the version of the WSRP component and + <code>$PORTAL_VERSION</code> + (at the time of the writing, it was &VY;) is the current JBoss Enterprise Portal Platform version: + <itemizedlist> + <listitem> + <para> + <filename>META-INF</filename> + contains files necessary for EAR packaging. The only file that is of interest from a user perspective + is + <filename>gatein-wsse-consumer.xml</filename> + which allows you to configure WS-Security support for the consumer. Please see the + <link linkend="wss_configuration">WSRP and WS-Security</link> section for more details. + </para> + </listitem> + <listitem> + <para> + <filename>extension-component-$PORTAL_VERSION.jar</filename>, which contains the components needed to + integrate the WSRP component into JBoss Enterprise Portal Platform. It also includes the default configuration files for + the WSRP producer and the default WSRP consumers. + </para> + </listitem> + <listitem> + <para> + <filename>extension-config-$PORTAL_VERSION.jar</filename>, which contains the configuration file + needed by the GateIn extension mechanism to properly register this EAR as an extension. + </para> + </listitem> + <listitem> + <para> + <filename>extension-war-$PORTAL_VERSION.war</filename>, which contains the configuration files + needed by the GateIn extension mechanism to properly setup the WSRP service. It includes + <filename>wsrp-configuration.xml</filename> + which, in particular, configures several options for the + <code>WSRPServiceIntegration</code> + component at the heart of the WSRP integration in JBoss Enterprise Portal Platform. + </para> + </listitem> + <listitem> + <para> + <filename>lib</filename>, which contains the different libraries needed by the WSRP service. + </para> + </listitem> + <listitem> + <para> + <filename>wsrp-admin-gui-$WSRP_VERSION.war</filename>, which contains the WSRP Configuration portlet + with which you can configure consumers to access remote servers and how the WSRP producer is + configured. + </para> + </listitem> + <listitem> + <para><filename>wsrp-producer-jb5wsss-$WSRP_VERSION.war</filename>, which contains the producer-side + support for WS-Security. The only file of interest from a user perspective is + <filename>gatein-wsse-producer.xml</filename> which allows you to configure WS-Security support for + the producer. Please see the <link linkend="wss_configuration">WSRP and WS-Security</link> section + for more details. + </para> + </listitem> + </itemizedlist> + </para> + <para> + If you're not going to use WSRP in JBoss Enterprise Portal Platform, it won't adversely affect your installation to leave it + as-is. Otherwise, you can just remove the + <filename>gatein-wsrp-integration.ear</filename> + file from your AS deploy directory. + </para> + + <section id="wsrp-ports"> + <title>Considerations to use WSRP when running JBoss Enterprise Portal Platform on a non-default port or hostname</title> + <para> + JBoss WS (the web service stack that JBoss Enterprise Portal Platform uses) should take care of the details of updating the + port and host name used in WSDL. See the + <ulink url="http://community.jboss.org/wiki/JBossWS-UserGuide#Configuration... WS user guide on that + subject + </ulink> + for more details. + </para> + <para> + Of course, if you have modified you have modified the host name and port on which your server runs, you will + need to + update the configuration for the consumer used to consume JBoss Enterprise Portal Platform's 'self' producer. Please refer to + the + <xref linkend="consumer_configuration"/> + to learn how to do so. + </para> + </section> + </section> + + <section> + <title>Securing WSRP</title> + <section> + <title>Considerations to use WSRP with SSL</title> + <para>It is possible to use WSRP over SSL for secure exchange of data. Please refer to the + <ulink url="http://community.jboss.org/wiki/ConfiguringWSRPforuseoverSSL&qu... + on how to do so from + <ulink url="http://community.jboss.org/wiki/GateIn">GateIn's wiki</ulink>. + </para> + </section> + <section> + <title>WSRP and WS-Security</title> + <para>Portlets may present different data or options depending on the currently authenticated user. For remote + portlets, this means having to propagate the user credentials from the consumer back to the producer in + a safe and secure manner. The WSRP specification does not directly specify how this should be + accomplished, but delegates this work to the existing WS-Security standards. + </para> + <note> + <title>Web Container Compatibility</title> + <para>WSRP and WS-Security is currently only supported on JBoss Enterprise Portal Platform when running on top of JBoss + AS 5. + </para> + </note> + <warning> + <title>Encryption</title> + <para>You will want to encrypt the credentials being sent between the consumer and producer, otherwise they + will be sent in plain text and could be easily intercepted. You can either configure WS-Security to + encrypt and sign the SOAP messages being sent, or secure the transport layer by using an https endpoint. + Failure to encrypt the soap message or transport layer will result in the username and password being + sent in plain text. <emphasis role="bold">Use of encryption is strongly recommended.</emphasis> + </para> + </warning> + <important> + <title>Credentials</title> + <para>When the consumer sends the user credentials to the producer, it is sending the credentials for the + currently authenticated user in the consumer. This makes signing in to remote portlets transparent + to end users, but also requires that the producer and consumer use the same credentials. This means + that the username and password must be the same and valid on both servers. + </para> + <para>The recommended approach for this situation would be to use a common ldap configuration. Please + see the user guide on how to configure ldap for use with JBoss Enterprise Portal Platform + </para> + </important> + <para>The GateIn Wiki article, <ulink url="http://community.jboss.org/wiki/GateInWSRPAndWebServiceSecurity... + GateIn WSRP and Web Service Security</ulink>, also provides a step-by-step example on how to configure + WSRP with WS-Security. + </para> + <section id="wss_configuration"> + <title>WS-Security Configuration</title> + <para>JBoss Enterprise Portal Platform uses JBossWS Native to handle ws-security. Please see the WS-Security section of the + <ulink url="http://www.jboss.org/jbossas/docs/5-x">JBoss AS 5 Administration and Configuration Guide + </ulink> for indepth configuration options. Please note that since the consumer passes its credentials + to the producer, the consumer will act at the wss client and the producer will act as the wss server. + </para> + <para> The following are the JBossWS Native configuration files which need to be configure for WSRP: + </para> + <itemizedlist> + <listitem> + <para> + <filename>gatein-wsrp-integration.ear/META-INF/gatein-wsse-consumer.xml</filename>: JBossWS + configuration file for the consumer. + </para> + </listitem> + <listitem> + <para> + <filename>gatein-wsrp-integration.ear/wsrp-producer-jb5wss.war/WEB-INF/conf/gatein-wsse-producer.xml + </filename>: JBossWS configuration file for the producer. + </para> + </listitem> + </itemizedlist> + </section> + <section> + <title>WS-Security Producer Configuration</title> + <para> + Other than the JBossWS configuration file mention above, no other configuration changes should be necessary + for the producer. + </para> + </section> + <section> + <title>WS-Security Consumer Configuration</title> + <para>The consumer requires a few changes before it will function properly with WS-Security. The consumer + needs access to the current servlet request since this is used to retrieve the currently authenticated + user. In order for the consumer to access this information, it needs a special servlet-filter added to + the portal. + </para> + <para>In <filename>gatein.ear/02portal.war/WEB-INF/web.xml</filename> add the following information: + </para> +<programlisting role="XML"><![CDATA[<!-- Filter to put request and response in ServletAccess --> + <filter> + <filter-name>ServletAccessFilter</filter-name> + <filter-class>org.gatein.wsrp.servlet.ServletAccessFilter</filter-class> + </filter> + <filter-mapping> + <filter-name>ServletAccessFilter</filter-name> + <url-pattern>/*</url-pattern> + </filter-mapping>]]> +</programlisting> + <para> + Finally, in the WSRP Configuration portlet, in the consumer configuration options, you will need to check the 'Enable WS Security' checkbox: + </para> + <mediaobject> + <imageobject> + <imagedata fileref="images/WSRP/config_wss_selected.png" format="PNG" align="center" valign="middle" scalefit="1"/> + </imageobject> + </mediaobject> + </section> + <section> + <title>WS-Security Consumer Checklist</title> + <para> + In order for the consumer to handle ws-security, the following steps must be completed properly + </para> + <itemizedlist> + <listitem> + <para>The JBossWS configuration files must be configured</para> + </listitem> + <listitem> + <para>The filter must be added to the portal's web.xml</para> + </listitem> + <listitem> + <para>the enable wss feature must be check in the wsrp admin</para> + </listitem> + </itemizedlist> + <para>The consumer will not properly handle ws-security unless all 3 are properly configured</para> + </section> + </section> + </section> + + <section> + <title>Making a portlet remotable</title> + <important> + <para> + Only JSR-286 (Portlet 2.0) portlets can be made remotable as the mechanism to expose a portlet to WSRP + relies on a JSR-286-only functionality. + </para> + </important> + <para>JBoss Enterprise Portal Platform does + <emphasis role="bold">NOT</emphasis>, by default, expose local portlets for consumption + by remote WSRP consumers. In order to make a portlet remotely available, it must be made "remotable" by marking + it as such in the associated + <filename>portlet.xml</filename>. This is accomplished by using a specific + <code>org.gatein.pc.remotable container-runtime-option</code>. Setting its value to + <code>true</code> + makes the portlet available for remote consumption, while setting its value to + <code>false</code> + will not publish it remotely. As specifying the remotable status for a portlet is optional, you do not need to + do anything if you don't need your portlet to be available remotely. + </para> + <para>In the following example, the "BasicPortlet" portlet is specified as being remotable. + </para> + <example> + <title>Example</title> + <para> + <programlisting><![CDATA[ +<?xml version="1.0" standalone="yes"?> +<portlet-app xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_2... http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd" + version="2.0"> +<portlet-app> + <portlet> + <portlet-name>BasicPortlet</portlet-name> + + ... + + <container-runtime-option> + <name>org.gatein.pc.remotable</name> + <value>true</value> + </container-runtime-option> + </portlet> +</portlet-app>]]></programlisting> + </para> + + </example> + <para> + It is also possible to specify that all the portlets declared within a given portlet application to be + remotable by default. This is done by specifying the + <code> + container-runtime-option + </code> + at the + <code>portlet-app</code> + element level. Individual portlets can override that value to not be remotely exposed. Let's look at an + example: + </para> + <example> + <title>Example</title> + <para> + <programlisting><![CDATA[ +<?xml version="1.0" standalone="yes"?> +<portlet-app xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_2... http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd" + version="2.0"> +<portlet-app> + + <portlet> + <portlet-name>RemotelyExposedPortlet</portlet-name> + ... + </portlet> + <portlet> + <portlet-name>NotRemotelyExposedPortlet</portlet-name> + ... + <container-runtime-option> + <name>org.gatein.pc.remotable</name> + <value>false</value> + </container-runtime-option> + </portlet> + + <container-runtime-option> + <name>org.gatein.pc.remotable</name> + <value>true</value> + </container-runtime-option> +</portlet-app>]]> + </programlisting> + </para> + + </example> + + <para> + In the example above, we defined two portlets. The + <code>org.gatein.pc.remotable container-runtime-option</code> + being set to + <code>true</code> + at the + <code>portlet-app</code> + level, all portlets defined in this particular portlet application are exposed remotely by JBoss Enterprise Portal Platform's + WSRP + producer. + Note, however, that it is possible to override the default behavior: specifying a value for the + <code>org.gatein.pc.remotable container-runtime-option</code> + at the + <code>portlet</code> + level will take precedence over the default. In the example above, the + <varname>RemotelyExposedPortlet</varname> + inherits the remotable status defined at the + <code>portlet-app</code> + level since it does not specify a value for the<code>org.gatein.pc.remotable container-runtime-option</code>. + The<varname>NotRemotelyExposedPortlet</varname>, however, overrides the default behavior and is not remotely + exposed. Note that in the absence of a top-level + <code>org.gatein.pc.remotable container-runtime-option</code> + value set to<code>true</code>, portlets are NOT remotely exposed. + </para> + </section> + + <section> + <title>Consuming JBoss Enterprise Portal Platform's WSRP portlets from a remote Consumer</title> + <para>WSRP Producers vary a lot as far as how they are configured. Most of them require that you specify + the URL for the Producer's WSDL definition. Please refer to the remote producer's documentation for specific + instructions. For instructions on how to do so in JBoss Enterprise Portal Platform, please refer to + <xref linkend="consumer_configuration"/>. + </para> + <para> + JBoss Enterprise Portal Platform's Producer is automatically set up when you deploy a portal instance with the WSRP service. + You can access the WSDL file at + <filename>http://{hostname}:{port}/wsrp-producer/v2/MarkupService?wsdl</filename>. If you wish to use only the + WSRP 1 compliant version of the producer, please use the WSDL file found at + <filename>http://{hostname}:{port}/wsrp-producer/v1/MarkupService?wsdl</filename>. + The default hostname is + <literal>localhost</literal> + and the default port is 8080. + </para> + </section> + + <section id="consumer_configuration"> + <title>Consuming remote WSRP portlets in JBoss Enterprise Portal Platform</title> + <section> + <title>Overview</title> + <para> + To be able to consume WSRP portlets exposed by a remote producer, JBoss Enterprise Portal Platform's WSRP consumer needs to + know how to access that remote producer. One can configure access to a remote producer using the provided + configuration portlet. Alternatively, it is also possible to configure access to remote producers using an + XML descriptor, though it is recommended (and easier) to do so via the configuration portlet. + </para> + <para> + Once a remote producer has been configured, the portlets that it exposes are then available in the + Application Registry to be added to categories and then to pages. + </para> + </section> + + <section id="consumer_gui"> + <title>Configuring a remote producer using the configuration portlet</title> + <para> + Let's work through the steps of defining access to a remote producer using the configuration portlet so that its portlets can be + consumed within JBoss Enterprise Portal Platform. We will configure access to NetUnity's public WSRP producer. + </para> + + <note> + <para> + Some WSRP producers do not support chunked encoding that is activated by default by JBoss WS. If your + producer does not support chunked encoding, your consumer will not be able to properly connect to the + producer. This will manifest itself with the following error: + <code>Caused by: org.jboss.ws.WSException: Invalid HTTP server response [503] - Service + Unavailable</code>. + Please see this GateIn's + <ulink url="http://community.jboss.org/wiki/Workaroundwhenchunkedencodingis... page + </ulink> + for more details. + </para> + </note> + + <para> + JBoss Enterprise Portal Platform provides a portlet to configure access (among other functions) to remote WSRP Producers + grahically. Starting with &VY;, the WSRP configuration portlet is installed by default. You + can find it at + <ulink + url="http://localhost:8080/portal/login?initialURI=%2Fportal%2Fprivate%2Fclassic%2FwsrpConfiguration&amp;username=root&amp;password=gtn"> + http://localhost:8080/portal/login?initialURI=%2Fportal%2Fprivate%2Fclass... + </ulink> + </para> + + <para> + You should see a screen similar to: + <mediaobject> + <imageobject> + <imagedata fileref="images/WSRP/config_init.png" format="PNG" align="center" valign="middle" + scalefit="1"/> + </imageobject> + </mediaobject> + This screen presents all the configured Consumers associated with their status and possible actions on + them. A Consumer can be active or inactive. Activating a Consumer means that it is ready to act as a + portlet provider. Note also that a Consumer can be marked as requiring refresh meaning that the + information held about it might not be up to date and refreshing it from the remote Producer might be a + good idea. This can happen for several reasons: the service description for that remote Producer has not + been fetched yet, the cached version has expired or modifications have been made to the configuration + that could potentially invalidate it, thus requiring re-validation of the information. + </para> + + <note> + <para> + The WSRP configuration didn't use to be installed by default in previous versions of JBoss Enterprise Portal Platform. + We include here the legacy instructions on how to install this portlet in case you ever need to + re-install it. + </para> + <para> + Use the usual procedure to log in as a Portal administrator and go to the Application + Registry. With the default install, you can just go to + <ulink + url="http://localhost:8080/portal/login?initialURI=%2Fportal%2Fprivate%2Fclassic%2Fadministration%2Fregistry&amp;username=root&amp;password=gtn"> + http://localhost:8080/portal/login?initialURI=%2Fportal%2Fprivate%2Fclass... + </ulink> + Add the WSRP Configuration portlet to the Administration category. If you use the Import Applications + functionality, the WSRP Configuration portlet will be automatically added to the Administration + category. + </para> + <para> + Now that the portlet is added to a category, it can be added to a page and used. We recommend adding + it to the same page as the Application Registry as operations relating to WSRP and adding portlets to + categories are somewhat related as we will see. Go ahead and add the WSRP Configuration portlet to the + page using the standard procedure. + </para> + </note> + + <para> + Next, we create a new Consumer which we will call <literal>netunity</literal>. Type + "<literal>netunity</literal>" in + the "Create a consumer named:" field then click on "Create consumer": + <mediaobject> + <imageobject> + <imagedata fileref="images/WSRP/config_create.png" format="PNG" align="center" valign="middle" + scalefit="1"/> + </imageobject> + </mediaobject> + You should now see a form allowing you to enter/modify the information about the Consumer. + Set the cache expiration value to 300 seconds, leave the default timeout value for web services (WS) + operations and enter the WSDL URL for the producer in the text field + and press the "Refresh &amp; Save" button: + <mediaobject> + <imageobject> + <imagedata fileref="images/WSRP/config_wsdl.png" format="PNG" align="center" valign="middle" + scalefit="1"/> + </imageobject> + </mediaobject> + This will retrieve the service description associated with the Producer which WSRP interface is described + by the WSDL file found at the URL you just entered. In our case, querying the service description will + allow us to learn that the Producer requires registration, requested three registration properties and that + we are missing values for these properties: + <mediaobject> + <imageobject> + <imagedata fileref="images/WSRP/config_missing.png" format="PNG" align="center" valign="middle" + scalefit="1"/> + </imageobject> + </mediaobject> + This particular producer requests simple + <literal>Yes</literal> + or + <literal>No</literal> + values for the three registration properties. Entering <literal>No</literal>, + <literal>Yes</literal> + and + <literal>No</literal> + (in that order) for the values and then pressing the "Refresh &amp; Save" button should result in: + <mediaobject> + <imageobject> + <imagedata fileref="images/WSRP/config_end.png" format="PNG" align="center" valign="middle" + scalefit="1"/> + </imageobject> + </mediaobject> + + <note> + <para>At this point, there is no automated way to learn about which possible values (if any) are + expected by the remote Producer. Sometimes, the possible values will be indicated in the + registration + property description but this is not always the case... Please refer to the specific Producer's + documentation. + </para> + </note> + </para> + + <para> + If we had been dealing with a producer which required registration but didn't require any registration + properties, as is the case for the + <literal>selfv2</literal> + consumer (the consumer that accesses the portlets made remotely available by JBoss Enterprise Portal Platform's producer via + WSRP 2), we'd have seen something similar to, after pressing the "Refresh &amp; Save" button: + <mediaobject> + <imageobject> + <imagedata fileref="images/WSRP/config_refresh.png" format="PNG" align="center" valign="middle" + scalefit="1"/> + </imageobject> + </mediaobject> + </para> + </section> + + <section id="consumer_xml"> + <title>Configuring access to remote producers via XML</title> + + <para>While we recommend you use the WSRP Configuration portlet to configure Consumers, we provide an + alternative way to configure consumers by adding an XML file called + <filename>wsrp-consumers-config.xml</filename> in the + <filename>$JBOSS_PROFILE_HOME/conf/gatein/</filename> directory. + <note> + <para>An XML Schema defining which elements are available to configure Consumers via XML can be found + in + <filename> + $JBOSS_PROFILE_HOME/deploy/gatein-wsrp-integration.ear/lib/wsrp-integration-api-$WSRP_VERSION.jar/xsd/gatein_wsrp_consumer_1_0.xsd + </filename> + </para> + </note> + <important> + <para> + It is important to note that once the XML configuration file for consumers has been read upon + the WSRP service first start, the associated information is put under control of JCR (Java Content + Repository). Subsequent launches of the WSRP service will use the JCR-stored information and ignore + the content of the XML configuration file. + </para> + + <!--<para>It is important to note how the XML consumers configuration file is processed. It is read the first + time the WSRP service starts and the associated information is then put under control of JCR (Java + Content Repository). Subsequent launches of the WSRP service will use the JCR-stored information for + all producers already known to JBoss Enterprise Portal Platform. More specifically, the + <filename>wsrp-consumers-config.xml</filename> + file is scanned for producer identifiers. + Any identifier that is already known will be bypassed and the JCR information associated with this + remote producer will be used. The information defined at the XML level is only processed for producer + definition for which no information is already present in JCR. Therefore, if you wish to delete a + producer configuration, you need to delete the associated information in the database (this can be + accomplished using the configuration portlet as we saw in + <xref linkend="consumer_gui"/>) + <emphasis>AND</emphasis> + remove the associated information in + <filename>wsrp-consumers-config.xml</filename> + (if such information exists) as the producer will be re-created the next time the WSRP is launched if + that information is not removed. + </para>--> + </important> + </para> + + <section> + <title>Required configuration information</title> + + <para>Let's now look at which information needs to be provided to configure access to a remote producer. + </para> + + <para>First, we need to provide an identifier for the producer we are configuring so that we can refer to it + afterwards. This is accomplished via the mandatory + <literal>id</literal> + attribute of the + <literal>&lt;wsrp-producer&gt;</literal> + element. + </para> + + <para>JBoss Enterprise Portal Platform also needs to learn about the remote producer's endpoints to be able to connect to the + remote web services and perform WSRP invocations. This is accomplished by specifying the URL for the + WSDL description for the remote WSRP service, using the + <literal>&lt;endpoint-wsdl-url&gt;</literal> + element. + </para> + + <para>Both the + <literal>id</literal> + attribute and + <literal>&lt;endpoint-wsdl-url&gt;</literal> + elements are required for a functional remote producer configuration. + </para> + </section> + + <section> + <title>Optional configuration</title> + <para>It is also possible to provide addtional configuration, which, in some cases, might be important to + establish a proper connection to the remote producer. + </para> + + <para>One such optional configuration concerns caching. To prevent useless roundtrips between the local + consumer and the remote producer, it is possible to cache some of the information sent by the producer + (such as the list of offered portlets) for a given duration. The rate at which the information is + refreshed is + defined by the + <literal>expiration-cache</literal> + attribute of the + <literal>&lt;wsrp-producer&gt;</literal> + element which specifies the refreshing period in seconds. For example, providing a value of 120 for + expiration-cache means that the producer information will not be refreshed for 2 minutes after it has + been somehow accessed. If no value is provided, JBoss Enterprise Portal Platform will always access the remote producer + regardless of whether the remote information has changed or not. Since, in most instances, the + information provided by the producer does not change often, we recommend that you use this caching + facility to minimize bandwidth usage. + </para> + + <para>It is also possible to define a timeout after which WS operations are considered as failed. This is + helpful to avoid blocking the WSRP service, waiting forever on the service that doesn't answer. Use the + <literal>ws-timeout</literal> + attribute of the + <literal>&lt;wsrp-producer&gt;</literal> + element to specify how many milliseconds the WSRP service will wait for a response from the remote + producer before timing out and giving up. + </para> + + <para>Additionally, some producers require consumers to register with them before authorizing them to access + their offered portlets. If you know that information beforehand, you can provide the required + registration information in the producer configuration so that the consumer can register with the remote + producer when required. + <note> + <para>At this time, though, only simple String properties are supported and it is not possible to + configure complex registration data. This should, however, be sufficient for most cases. + </para> + </note> + </para> + + <para>Registration configuration is done via the + <literal>&lt;registration-data&gt;</literal> + element. Since JBoss Enterprise Portal Platform can generate the mandatory information for you, if the remote producer does + not require any registration properties, you only need to provide an empty + <literal>&lt;registration-data&gt;</literal> + element. Values for the registration properties + required by the remote producer can be provided via + <literal>&lt;property&gt;</literal> + elements. See the example below for more details. Additionally, you can override the default consumer + name automatically provided by JBoss Enterprise Portal Platform via the + <literal>&lt;consumer-name&gt;</literal> + element. If you choose to provide a consumer name, please remember that this should uniquely identify + your consumer. + </para> + </section> + + <section> + <title>Examples</title> + + <para> + Here is the configuration of the + <literal>selfv1</literal> + and + <literal>selfv2</literal> + consumers as found in + <filename>$JBOSS_PROFILE_HOME/deploy/gatein-wsrp-integration.ear/lib/extension-component-$WSRP_VERSION.jar/conf/wsrp-consumers-config.xml</filename> + with a cache expiring every 500 seconds and with a 50 second timeout for web service operations. + <note> + <para> + This file contains the default configuration and you shouldn't need to edit it. If you want to make + modifications to it, we recommend that you follow the procedure detailed in + <xref linkend="consumer_gui"/>. + </para> + </note> + </para> + + <example> + <title>Example</title> + <para> + <programlisting><![CDATA[ +<?xml version='1.0' encoding='UTF-8' ?> +<deployments xmlns="http://www.gatein.org/xml/ns/gatein_wsrp_consumer_1_0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.gatein.org/xml/ns/gatein_wsrp_consume... http://www.jboss.org/portal/xsd/gatein_wsrp_consumer_1_0.xsd"> + <deployment> + <wsrp-producer id="selfv1" expiration-cache="500" ws-timeout="50000"> + <endpoint-wsdl-url>http://localhost:8080/wsrp-producer/v1/MarkupService?wsdl</endpoint-wsdl-url> + <registration-data/> + </wsrp-producer> + </deployment> + <deployment> + <wsrp-producer id="selfv2" expiration-cache="500" ws-timeout="50000"> + <endpoint-wsdl-url>http://localhost:8080/wsrp-producer/v2/MarkupService?wsdl</endpoint-wsdl-url> + <registration-data/> + </wsrp-producer> + </deployment> +</deployments>]]> + </programlisting> + </para> + + </example> + + <para>Here is an example of a WSRP descriptor with registration data and cache expiring every minute: + </para> + + <example> + <title>Example</title> + <para> + <programlisting><![CDATA[ +<?xml version='1.0' encoding='UTF-8' ?> +<deployments xmlns="http://www.gatein.org/xml/ns/gatein_wsrp_consumer_1_0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.gatein.org/xml/ns/gatein_wsrp_consume... http://www.jboss.org/portal/xsd/gatein_wsrp_consumer_1_0.xsd"> +<deployments> + <deployment> + <wsrp-producer id="AnotherProducer" expiration-cache="60"> + <endpoint-wsdl-url>http://example.com/producer/producer?WSDL</endpoi... + <registration-data> + <property> + <name>property name</name> + <lang>en</lang> + <value>property value</value> + </property> + </registration-data> + </wsrp-producer> + </deployment> +</deployments>]]></programlisting> + </para> + </example> + </section> + </section> + + <section> + <title>Adding remote portlets to categories</title> + <para> + If we go to the Application Registry and examine the available portlets by clicking on the + Portlet link, you will now be able to see remote portlets if you click on the REMOTE tab in the left + column: + <mediaobject> + <imageobject> + <imagedata fileref="images/WSRP/remote_portlets.png" format="PNG" align="center" valign="middle" + scalefit="1"/> + </imageobject> + </mediaobject> + </para> + + <para> + These portlets are, of course, available to be used such as regular portlets: they can be used in + categories and added to pages. If you use the Import Applications functionality, they will also be + automatically imported in categories based on the keywords they define. + </para> + + <para> + More specifically, if you want to add a WSRP portlet to a category, you can access these portlets by + selecting + <literal>wsrp</literal> + in the Application Type drop-down menu: + <mediaobject> + <imageobject> + <imagedata fileref="images/WSRP/remote_portlets_category.png" format="PNG" align="center" + valign="middle" + scalefit="1"/> + </imageobject> + </mediaobject> + </para> + </section> + </section> + + <section> + <title>Consumers maintenance</title> + + <section> + <title>Modifying a currently held registration</title> + + <section> + <title>Registration modification for service upgrade</title> + <para> + Producers often offer several levels of service depending on consumers' subscription levels (for + example). This is implemented at the WSRP level with the registration concept: producers can assert which + level of service to provide to consumers based on the values of given registration properties. + </para> + <para> + There might also be cases where you just want to update the registration information because it has + changed. For example, the producer required you to provide a valid email and the previously email + address is not valid anymore and needs to be updated. + </para> + <para> + It is therefore sometimes necessary to modify the registration that concretizes the service agreement + between a consumer and a producer. Let's take the example of a producer requiring a valid email (via an + <literal>email</literal> + registration property) as part of its required information that consumers need to provide to be properly + registered. + </para> + <para> + Suppose now that we would like to update the email address that we provided to the remote producer when + we first registered. We will need to tell the producer that our registration data has been modified. + Let's see how to do this. Select the consumer for the remote producer in the available consumers list to + display its configuration. Assuming you want to change the email you registered with to + <literal&gt;foo(a)example.com&lt;/literal&gt;, change its value in the field for the + <literal>email</literal> + registration property: + <mediaobject> + <imageobject> + <imagedata fileref="images/WSRP/modify_reg_start.png" format="PNG" align="center" valign="middle" + scalefit="1"/> + </imageobject> + </mediaobject> + Now click on "Update properties" to save the change. A "Modify registration" button should now appear to + let you send this new data to the remote producer: + <mediaobject> + <imageobject> + <imagedata fileref="images/WSRP/modify_reg_modify.png" format="PNG" align="center" + valign="middle" scalefit="1"/> + </imageobject> + </mediaobject> + Click on this new button and, if everything went well and your updated registration has been accepted by + the remote producer, you should see something similar to: + <mediaobject> + <imageobject> + <imagedata fileref="images/WSRP/modify_reg_end.png" format="PNG" align="center" valign="middle" + scalefit="1"/> + </imageobject> + </mediaobject> + </para> + + </section> + + <section id="reg_mod_error"> + <title>Registration modification on producer error</title> + + <para> + It can also happen that a producer administrator decided to change its requirement for registered + consumers. JBoss Enterprise Portal Platform will attempt to help you in this situation. Let's walk through an example using + the <literal>selfv2</literal> consumer. Let's assume that registration is requiring a valid value for an + <literal>email</literal> + registration property. If you go to the configuration screen for this consumer, you should see: + <mediaobject> + <imageobject> + <imagedata fileref="images/WSRP/config_self.png" format="PNG" align="center" valign="middle" + scalefit="1"/> + </imageobject> + </mediaobject> + + Now suppose that the administrator of the producer now additionaly requires a value to be provided for a + <literal>name</literal> + registration property. We will actually see how to do perform this operation + in JBoss Enterprise Portal Platform when we examine how to configure JBoss Enterprise Portal Platform's producer in + <xref linkend="producer_config"/>. + Operations with this producer will now fail. If you suspect that a registration modification is required, + you should go to the configuration screen for this remote producer and refresh the information held by + the consumer by pressing "Refresh &amp; Save": + <mediaobject> + <imageobject> + <imagedata fileref="images/WSRP/modify_reg_self.png" format="PNG" align="center" valign="middle" + scalefit="1"/> + </imageobject> + </mediaobject> + + As you can see, the configuration screen now shows the currently held registration information and + the expected information from the producer. Enter a value for the + <literal>name</literal> + property + and then click on "Modify registration". If all went well and the producer accepted your new registration + data, you should see something similar to: + <mediaobject> + <imageobject> + <imagedata fileref="images/WSRP/modify_reg_self_end.png" format="PNG" align="center" + valign="middle" scalefit="1"/> + </imageobject> + </mediaobject> + + <note> + <para>WSRP 1 makes it rather difficult to ascertain for sure what caused an + <exceptionname>OperationFailedFault</exceptionname> + as it is the generic exception returned by + producers if something didn't quite happen as expected during a method invocation. This means that + <exceptionname>OperationFailedFault</exceptionname> + can be caused by several different reasons, one + of them being a request to modify the registration data. Please take a look at the log files to see + if you can gather more information as to what happened. WSRP 2 introduces an exception that is + specific to a request to modify registrations thus reducing the ambiguity that exists when using WSRP 1. + </para> + + </note> + </para> + </section> + </section> + + <section> + <title>Consumer operations</title> + <para> + Several operations are available from the consumer list view of the WSRP configuration portlet: + <mediaobject> + <imageobject> + <imagedata fileref="images/WSRP/consumer_operations.png" format="PNG" align="center" valign="middle" + scalefit="1"/> + </imageobject> + </mediaobject> + </para> + <para> + The available operations are: + <itemizedlist> + <listitem> + <para>Configure: displays the consumer details and allows user to edit them</para> + </listitem> + <listitem> + <para>Refresh: forces the consumer to retrieve the service description from the remote producer to + refresh + the local information (offered portlets, registration information, etc.) + </para> + </listitem> + <listitem> + <para>Activate/Deactivate: activates/deactivates a consumer, governing whether it will be available to + provide portlets and receive portlet invocations + </para> + </listitem> + <listitem> + <para>Register/Deregister: registers/deregisters a consumer based on whether registration is required + and/or acquired + </para> + </listitem> + <listitem> + <para>Delete: destroys the consumer, after deregistering it if it was registered</para> + </listitem> + <listitem> + <para>Export: exports some or all of the consumer's portlets to be able to later import them in a + different context + </para> + </listitem> + <listitem> + <para>Import: imports some or all of previously exported portlets</para> + </listitem> + </itemizedlist> + </para> + <note> + <para> + Import/Export functionality is only available to WSRP 2 consumers of producers that support this optional + functionality. Import functionality is only available if portlets had previously been exported. + </para> + </note> + </section> + + <section> + <title>Importing and exporting portlets</title> + <para>Import and export are new functionalities added in WSRP 2. Exporting a portlet allows a consumer to get + an opaque representation of the portlet which can then be use by the corresponding import operation to + reconstitute it. It is mostly used in migration scenarios during batch operations. Since JBoss Enterprise Portal Platform + does not currently support automated migration of portal data, the functionality that we provide as part of + WSRP 2 is necessarily less complete than it could be with full portal support. + </para> + <para>The import/export implementation in JBoss Enterprise Portal Platform (available since 3.1) allows users to export portlets + from a given consumer. + These portlets can then be used to replace existing content on pages. This is accomplished by assigning + previously exported portlets to replace the content displayed by windows on the portal's pages. Let us walk + through an example to make things clearer. + </para> + <para>Clicking on the "Export" action for a given consumer will display the list of portlets currently made + available by this specific consumer. An example of such a list is shown below: + </para> + <mediaobject> + <imageobject> + <imagedata fileref="images/WSRP/export_portlet_list.png" format="PNG" align="center" valign="middle"/> + </imageobject> + </mediaobject> + <para>Once portlets have been selected, they can be exported by clicking on the "Export" button thus making + them available for later import: + </para> + <mediaobject> + <imageobject> + <imagedata fileref="images/WSRP/export_done.png" format="PNG" align="center" valign="middle"/> + </imageobject> + </mediaobject> + <para>You can re-import the portlets directly by pressing the "Use for import" button or, on the Consumers list + page, using the "Import" action for a given consumer. Let's assume that you used that second option and that + you currently have several available sets of previously exported portlets to import from. After clicking the + action link, you should see a screen similar to the one below: + </para> + <mediaobject> + <imageobject> + <imagedata fileref="images/WSRP/export_list.png" format="PNG" align="center" valign="middle"/> + </imageobject> + </mediaobject> + <para>As you can see this screen presents the list of available exports with available operations for each. + <itemizedlist> + <listitem> + <para>View: displays the export details as previously seen when the export was first performed</para> + </listitem> + <listitem> + <para>Delete: deletes the selected export, asking you for confirmation first</para> + </listitem> + <listitem> + <para>Use for import: selects the export to import portlets from</para> + </listitem> + </itemizedlist> + </para> + <para>Once you've selected an export to import from, you will see a screen similar to the one below:</para> + <mediaobject> + <imageobject> + <imagedata fileref="images/WSRP/import_start.png" format="PNG" align="center" valign="middle"/> + </imageobject> + </mediaobject> + <para>The screen displays the list of available exported portlets for the previously selected export. You can + select which portlet you want to import by checking the checkbox next to its name. Next, you need to select + the content of which window the imported portlet will replace. This process is done in three steps. Let's + assume in this example that you have the following page called + <literal>page1</literal> + and containing two windows called + <literal>NetUnity WSRP 2 Interop - Cache Markup (remote)</literal> + and + <literal>/samples-remotecontroller-portlet.RemoteControl (remote)</literal> + as shown below: + </para> + <mediaobject> + <imageobject> + <imagedata fileref="images/WSRP/import_original_page.png" format="PNG" align="center" valign="middle"/> + </imageobject> + </mediaobject> + <para>In this example, we want to replace the content of the + <literal>/samples-remotecontroller-portlet.RemoteControl (remote)</literal> + by the content of the + <literal>/ajaxPortlet.JSFAJAXPortlet</literal> + portlet that we previously exported. To do so, we will check the checkbox next to the + <literal>/ajaxPortlet.JSFAJAXPortlet</literal> + portlet name to indicate that we want to import its data and then select the + <literal>page1</literal> + in the list of available pages. The screen will then refresh to display the list of available windows on + that page, similar to the one seen below: + </para> + <mediaobject> + <imageobject> + <imagedata fileref="images/WSRP/import_selected_page.png" format="PNG" align="center" valign="middle"/> + </imageobject> + </mediaobject> + <para>Note that, at this point, we still need to select the window which content we want to replace before + being able to complete the import operation. Let's select the + <literal>/samples-remotecontroller-portlet.RemoteControl (remote)</literal> + window, at which point the "Import" button will become enabled, indicating that we now have all the + necessary data to perform the import. If all goes well, pressing that button should result in a screen + similar to the one below: + </para> + <mediaobject> + <imageobject> + <imagedata fileref="images/WSRP/import_success.png" format="PNG" align="center" valign="middle"/> + </imageobject> + </mediaobject> + <para>If you now take a look at the + <literal>page1</literal> + page, you should now see that the content + <literal>/samples-remotecontroller-portlet.RemoteControl (remote)</literal> + window has been replaced by the content of the + <literal>/ajaxPortlet.JSFAJAXPortlet</literal> + imported portlet and the window renamed appropriately: + </para> + <mediaobject> + <imageobject> + <imagedata fileref="images/WSRP/import_modified_page.png" format="PNG" align="center" valign="middle"/> + </imageobject> + </mediaobject> + </section> + + <section> + <title>Erasing local registration data</title> + <para> + There are rare cases where it might be required to erase the local information without being able to + deregister first. This is the case when a consumer is registered with a producer that has been modified by + its administrator to not require registration anymore. If that ever was to happen (most likely, it won't), + you can erase the local registration information from the consumer so that it can resume interacting with + the remote producer. To do so, click on "Erase local registration" button next to the registration context + information on the consumer configuration screen: + </para> + <mediaobject> + <imageobject> + <imagedata fileref="images/WSRP/erase_registration.png" format="PNG" align="center" valign="middle"/> + </imageobject> + </mediaobject> + <para> + <emphasis>Warning:</emphasis> + This operation is dangerous as it can result in inability to interact with the remote producer if invoked + when not required. A warning screen will be displayed to give you a chance to change your mind: + </para> + <mediaobject> + <imageobject> + <imagedata fileref="images/WSRP/erase_registration_warning.png" format="PNG" align="center" + valign="middle"/> + </imageobject> + </mediaobject> + </section> + </section> + + <section id="producer_config"> + <title>Configuring JBoss Enterprise Portal Platform's WSRP Producer</title> + <section> + <title>Overview</title> + <para> + The preferred way to configure the behavior of Portal's WSRP Producer is via the WSRP configuration portlet. + Alternatively, it is possible to add an XML file called + <filename>wsrp-producer-config.xml</filename> + in the + <filename>$JBOSS_PROFILE_HOME/conf/gatein/</filename> + directory. + Several aspects can be modified with respects to whether registration is required for consumers to access + the Producer's services. + <note> + <para>An XML Schema defining which elements are available to configure Consumers via XML can be found + in + <filename> + $JBOSS_PROFILE_HOME/deploy/gatein-wsrp-integration.ear/lib/wsrp-integration-api-$WSRP_VERSION.jar/xsd/gatein_wsrp_producer_1_0.xsd + </filename> + </para> + </note> + <important> + <para> + It is important to note that once the XML configuration file for the producer has been read upon + the WSRP service first start, the associated information is put under control of JCR (Java Content + Repository). Subsequent launches of the WSRP service will use the JCR-stored information and ignore + the content of the XML configuration file. + </para> + </important> + <note> + <para> + The default configuration file for the producer can be found at + <filename>$JBOSS_PROFILE_HOME/deploy/gatein-wsrp-integration.ear/lib/extension-component-$WSRP_VERSION.jar/conf/wsrp-producer-config.xml</filename> + </para> + </note> + </para> + </section> + <section> + <title>Default configuration</title> + <para> + The default producer configuration is to require that consumers register with it before providing access its + services but does not require any specific registration properties (apart from what is mandated by the + WSRP standard). It does, however, require consumers to be registered before sending them a full service + description. This means that our WSRP producer will not provide the list of offered portlets and other + capabilities to unregistered consumers. The producer also uses the default + <classname>RegistrationPolicy</classname> + paired with the default + <classname>RegistrationPropertyValidator</classname>. We will look into property + validators in greater detail later in<xref linkend="registration-configuration"/>. Suffice to say for now + that this allows users to customize how Portal's WSRP Producer decides whether a given registration property + is valid or not. + </para> + <para> + JBoss Enterprise Portal Platform provides a web interface to configure the producer's behavior. You can access it + by clicking on the "Producer Configuration" tab of the "WSRP" page of the "admin" portal. Here's what you + should see with the default configuration: + <mediaobject> + <imageobject> + <imagedata fileref="images/WSRP/producer_default.png" format="PNG" align="center" valign="middle" + scalefit="1"/> + </imageobject> + </mediaobject> + As would be expected, you can specify whether or not the producer will send the full service description to + unregistered consumers, and, if it requires registration, which + <classname>RegistrationPolicy</classname> + to use (and, if needed, which + <classname>RegistrationPropertyValidator</classname>), along with required + registration property description for which consumers must provide acceptable values to successfully + register. + </para> + <para>New in JBoss Enterprise Portal Platform, we now display the WSDL URLs to access JBoss Enterprise Portal Platform's WSRP producer either in WSRP 1 + or WSRP 2 mode. + </para> + </section> + + <section id="registration-configuration"> + <title>Registration configuration</title> + <para> + In order to require consumers to register with Portal's producer before interacting with it, you need to + configure Portal's behavior with respect to registration. Registration is optional, as are registration + properties. The producer can require registration without requiring consumers to pass any registration + properties as is the case in the default configuration. Let's configure our producer starting with a blank + state: + <mediaobject> + <imageobject> + <imagedata fileref="images/WSRP/producer_blank.png" format="PNG" align="center" valign="middle" + scalefit="1"/> + </imageobject> + </mediaobject> + We will allow unregistered consumers to see the list of offered portlets so we leave the first checkbox + ("Access to full service description requires consumers to be registered.") unchecked. We will, however, + specify that consumers will need to be registered to be able to interact with our producer. Check the second + checkbox ("Requires registration. Modifying this information will trigger invalidation of consumer + registrations."). The screen should now refresh and display: + <mediaobject> + <imageobject> + <imagedata fileref="images/WSRP/producer_registration.png" format="PNG" align="center" + valign="middle" scalefit="1"/> + </imageobject> + </mediaobject> + You can specify the fully-qualified name for your + <classname>RegistrationPolicy</classname> + and + <classname>RegistrationPropertyValidator</classname> + there. We will keep the default value. See + <xref linkend="custom_registration"/> + for more details. Let's add, however, a registration property called + <literal>email</literal>. Click "Add property" and enter the appropriate information in the fields, + providing a description for the registration property that can be used by consumers to figure out its + purpose: + <mediaobject> + <imageobject> + <imagedata fileref="images/WSRP/producer_email.png" format="PNG" align="center" valign="middle" + scalefit="1"/> + </imageobject> + </mediaobject> + Press "Save" to record your modifications. + + <note> + <para>At this time, only String (xsd:string) properties are supported. If your application requires more + complex properties, please let us know. + </para> + </note> + + <note> + <para>If consumers are already registered with the producer, modifying the configuration of required + registration + information will trigger the invalidation of held registrations, requiring consumers to modify their + registration before being able to access the producer again. We saw the consumer side of that process + in + <xref linkend="reg_mod_error"/>. + </para> + + </note> + </para> + + <section id="custom_registration"> + <title>Customization of Registration handling behavior</title> + <para> + Registration handling behavior can be customized by users to suit their Producer needs. This is + accomplished by providing an implementation of the + <classname>RegistrationPolicy</classname> + interface. This interface defines methods that are called by Portal's Registration service so that + decisions can be made appropriately. A default registration policy that provides basic + behavior is provided and should be enough for most user needs. + </para> + <para> + While the default registration policy provides default behavior for most registration-related aspects, + there is still one aspect that requires configuration: whether a given value for a registration property + is acceptable by the WSRP Producer. This is accomplished by plugging a + <classname>RegistrationPropertyValidator</classname> + in the default registration policy. This allows users to define their own validation mechanism. + </para> + <para> + Please refer to the + <trademark class="trade">Javadoc</trademark> + for + <classname>org.gatein.registration.RegistrationPolicy</classname> + and + <classname>org.gatein.registration.policies.RegistrationPropertyValidator</classname> + for more + details on what is expected of each method. + </para> + <para>Defining a registration policy is required for the producer to be correctly configured. This is + accomplished by specifying the qualified class name of the registration policy. Since we anticipate that + most users will use the default registration policy, it is possible to provide the class + name of your custom property validator instead to customize the default registration policy behavior. + Note that property validators are only used by the default policy. + + <note> + <para>Since the policy or the validator are defined via their class name and dynamically loaded, it is + important that you make sure that the identified class is available to the application server. One + way + to accomplish that is to deploy your policy implementation as JAR file in your AS instance deploy + directory. Note also that, since both policies and validators are dynamically instantiated, they + must + provide a default, no-argument constructor. + </para> + </note> + </para> + </section> + </section> + <section id="strict-mode"> + <title>WSRP validation mode</title> + <para>The lack of conformance kit and the wording of the WSRP specification leaves room for differing + interpretations, resulting in interoperability issues. It is therefore possible to encounter issues when + using consumers from different vendors. We have experienced such issues and have introduced a way to relax + the validation that our WSRP producer performs on the data provided by consumers to help with + interoperability by accepting data that would normally be invalid. Note that we only relax our validation + algorithm on aspects of the specification that are deemed harmless such as invalid language codes. + </para> + <para> + By default, the WSRP producer is configured in strict mode. If you experience issues with a given consumer, + you might want to try to relax the validation mode. This is accomplished by unchecking the "Use strict WSRP + compliance." checkbox on the Producer configuration screen. + </para> + </section> + + </section> +</chapter>