Author: smumford Date: 2011-07-26 01:04:46 -0400 (Tue, 26 Jul 2011) New Revision: 6929 Added: epp/docs/branches/5.1/Reference_Guide/en-US/extras/Advanced_Development_JCR_as_managed_datasources/ epp/docs/branches/5.1/Reference_Guide/en-US/extras/Advanced_Development_JCR_as_managed_datasources/gatein-ds.xml epp/docs/branches/5.1/Reference_Guide/en-US/modules/Advanced/JCR/as_managed_datasources.xml Modified: epp/docs/branches/5.1/Reference_Guide/en-US/Book_Info.xml epp/docs/branches/5.1/Reference_Guide/en-US/Reference_Guide.ent epp/docs/branches/5.1/Reference_Guide/en-US/Revision_History.xml epp/docs/branches/5.1/Reference_Guide/en-US/modules/Advanced/JCR.xml epp/docs/branches/5.1/Reference_Guide/en-US/modules/AuthenticationAndIdentity.xml epp/docs/branches/5.1/Reference_Guide/en-US/modules/AuthenticationAndIdentity/LDAP.xml epp/docs/branches/5.1/Reference_Guide/en-US/modules/AuthenticationAndIdentity/SSO.xml epp/docs/branches/5.1/Reference_Guide/en-US/modules/Introduction.xml epp/docs/branches/5.1/Reference_Guide/en-US/modules/WSRP.xml Log: Updated for 5.1.1 Release. Modified: epp/docs/branches/5.1/Reference_Guide/en-US/Book_Info.xml =================================================================== --- epp/docs/branches/5.1/Reference_Guide/en-US/Book_Info.xml 2011-07-26 04:48:07 UTC (rev 6928) +++ epp/docs/branches/5.1/Reference_Guide/en-US/Book_Info.xml 2011-07-26 05:04:46 UTC (rev 6929) @@ -4,24 +4,24 @@ %BOOK_ENTITIES; ]> <bookinfo id="book-Reference_Guide"> - <title>Reference Guide</title> + <title>Reference Guide</title> <subtitle>An in-depth guide to Enterprise Portal Platform &VZ;</subtitle> - <productname>JBoss Enterprise Portal Platform</productname> - <productnumber>5.1</productnumber> - <edition>2</edition> - <pubsnumber>5.1.1</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> + <productname>JBoss Enterprise Portal Platform</productname> + <productnumber>5.1</productnumber> + <edition>2</edition> + <pubsnumber>5.1.2</pubsnumber> + <abstract> + <para> + This Reference Guide is a high-level usage document. It deals with more advanced topics than the Installation and User Guides, adding new content or taking concepts discussed in the earlier documents further. It aims to provide supporting documentation for advanced users of the JBoss Enterprise Portal Platform product. Its primary focus is on advanced use of the product and it assumes an intermediate or advanced knowledge of the technology and terms. + </para> + </abstract> <corpauthor> <inlinemediaobject> - <imageobject> - <imagedata fileref="Common_Content/images/title_logo.svg" format="SVG" /> - </imageobject> - </inlinemediaobject> - </corpauthor> + <imageobject> + <imagedata fileref="Common_Content/images/title_logo.svg" format="SVG" /> + </imageobject> + </inlinemediaobject> + </corpauthor> <!--FOR PUBLICAN --> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" @@ -33,5 +33,5 @@ </xi:fallback> </xi:include> - <xi:include href="Author_Group.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="Author_Group.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> </bookinfo> Modified: epp/docs/branches/5.1/Reference_Guide/en-US/Reference_Guide.ent =================================================================== --- epp/docs/branches/5.1/Reference_Guide/en-US/Reference_Guide.ent 2011-07-26 04:48:07 UTC (rev 6928) +++ epp/docs/branches/5.1/Reference_Guide/en-US/Reference_Guide.ent 2011-07-26 05:04:46 UTC (rev 6929) @@ -10,7 +10,7 @@ <!ENTITY BZURL "<ulink url='https://bugzilla.redhat.com/enter_bug.cgi?product=JBoss&perc... <!-- Corporate Specifics: --> -<!ENTITY YEAR "2010"> +<!ENTITY YEAR "2011"> <!ENTITY HOLDER "Red Hat, Inc"> <!-- Version Specifcs: --> Modified: epp/docs/branches/5.1/Reference_Guide/en-US/Revision_History.xml =================================================================== --- epp/docs/branches/5.1/Reference_Guide/en-US/Revision_History.xml 2011-07-26 04:48:07 UTC (rev 6928) +++ epp/docs/branches/5.1/Reference_Guide/en-US/Revision_History.xml 2011-07-26 05:04:46 UTC (rev 6929) @@ -4,38 +4,52 @@ %BOOK_ENTITIES; ]> <appendix id="appe-Reference_Guide-Revision_History"> - <title>Revision History</title> - <simpara> - <revhistory> - <revision> - <revnumber>2-5.1.1</revnumber> - <date>Monday June 27 2011</date> - <author> - <firstname>Scott</firstname> - <surname>Mumford</surname> - <email&gt;smumford(a)redhat.com&lt;/email&gt; - </author> - <revdescription> - <simplelist> - <member>Updated for 5.1.1 Release.</member> - </simplelist> - </revdescription> - </revision> - <revision> - <revnumber>1-5.8</revnumber> - <date>Wed June 22 2011</date> - <author> - <firstname>Scott</firstname> - <surname>Mumford</surname> - <email&gt;smumford(a)redhat.com&lt;/email&gt; - </author> - <revdescription> - <simplelist> - <member>Incorporated new Bugzilla feedback link.</member> - <member>Corrected minor typographical errors.</member> - </simplelist> - </revdescription> - </revision> + <title>Revision History</title> + <simpara> + <revhistory> + <revision> + <revnumber>2-5.1.2</revnumber> + <date>Fri Jul 15 2011</date> + <author> + <firstname>Scott</firstname> + <surname>Mumford</surname> + <email></email> + </author> + <revdescription> + <simplelist> + <member>Updated for 5.1.1 Release.</member> + </simplelist> + </revdescription> + </revision> + <!--<revision> + <revnumber>2-5.1.1</revnumber> + <date>Monday June 27 2011</date> + <author> + <firstname>Scott</firstname> + <surname>Mumford</surname> + <email&gt;smumford(a)redhat.com&lt;/email&gt; + </author> + <revdescription> + <simplelist> + <member>Updated for 5.1.1 Release.</member> + </simplelist> + </revdescription> + </revision>--> + <revision> + <revnumber>1-5.8</revnumber> + <date>Wed June 22 2011</date> + <author> + <firstname>Scott</firstname> + <surname>Mumford</surname> + <email&gt;smumford(a)redhat.com&lt;/email&gt; + </author> + <revdescription> + <simplelist> + <member>Incorporated new Bugzilla feedback link.</member> + <member>Corrected minor typographical errors.</member> + </simplelist> + </revdescription> + </revision> <revision> <revnumber>1-5.7</revnumber> <date>Mon May 30 2011</date> @@ -218,7 +232,7 @@ </simplelist> </revdescription> </revision> - <!-- <revision> + <!-- <revision> <revnumber>1-1.20</revnumber> <date>Mon Nov 29 2010</date> <author> @@ -261,7 +275,7 @@ </simplelist> </revdescription> </revision> - <revision> + <revision> <revnumber>1-1.15</revnumber> <date>Thu Nov 11 2010</date> <author> @@ -305,146 +319,146 @@ </simplelist> </revdescription> </revision> -<!-- <revision> - <revnumber>1-1.11</revnumber> - <date>Thu Sep 30 2010</date> - <author> - <firstname>Scott</firstname> - <surname>Mumford</surname> - <email&gt;smumford(a)redhat.com&lt;/email&gt; - </author> - <revdescription> - <simplelist> - <member>Edit Product version number for publishing restructure.</member> - </simplelist> - </revdescription> - </revision> +<!-- <revision> + <revnumber>1-1.11</revnumber> + <date>Thu Sep 30 2010</date> + <author> + <firstname>Scott</firstname> + <surname>Mumford</surname> + <email&gt;smumford(a)redhat.com&lt;/email&gt; + </author> + <revdescription> + <simplelist> + <member>Edit Product version number for publishing restructure.</member> + </simplelist> + </revdescription> + </revision> <revision> - <revnumber>1-1.10</revnumber> - <date>Thu Sep 23 2010</date> - <author> - <firstname>Scott</firstname> - <surname>Mumford</surname> - <email&gt;smumford(a)redhat.com&lt;/email&gt; - </author> - <revdescription> - <simplelist> - <member>Split <filename>repository-configuration.xml</filename> code sample into two smaller samples (workaround callout pointer bug). Removed further references to components in standalone mode.</member> - </simplelist> - </revdescription> - </revision> - <revision> - <revnumber>1-1.9</revnumber> - <date>Wed Sep 15 2010</date> - <author> - <firstname>Scott</firstname> - <surname>Mumford</surname> - <email&gt;smumford(a)redhat.com&lt;/email&gt; - </author> - <revdescription> - <simplelist> - <member>Started content for &#34;Debugging Resource Bundle Usage&#34; section. Started homoginizing filepath variables.</member> - </simplelist> - </revdescription> - </revision> --> - <revision> - <revnumber>1-1.8</revnumber> - <date>Fri Aug 27 2010</date> - <author> - <firstname>Scott</firstname> - <surname>Mumford</surname> - <email&gt;smumford(a)redhat.com&lt;/email&gt; - </author> - <revdescription> - <simplelist> - <member>Added new concept definitions to JCR chapter.</member> - </simplelist> - </revdescription> - </revision> -<!-- <revision> - <revnumber>1-1.7</revnumber> - <date>Mon Aug 9 2010</date> - <author> - <firstname>Scott</firstname> - <surname>Mumford</surname> - <email&gt;smumford(a)redhat.com&lt;/email&gt; - </author> - <revdescription> - <simplelist> - <member>Further clean-up of programlisting rendering.</member> - </simplelist> - </revdescription> - </revision> --> - <revision> - <revnumber>1-1.6</revnumber> - <date>Thu Aug 5 2010</date> - <author> - <firstname>Scott</firstname> - <surname>Mumford</surname> - <email&gt;smumford(a)redhat.com&lt;/email&gt; - </author> - <revdescription> - <simplelist> - <member>Extracted code snippets.</member> - </simplelist> - </revdescription> - </revision> -<!-- <revision> - <revnumber>1-1.5</revnumber> - <date>Thu Jul 29 2010</date> - <author> - <firstname>Scott</firstname> - <surname>Mumford</surname> - <email&gt;smumford(a)redhat.com&lt;/email&gt; - </author> - <revdescription> - <simplelist> - <member>Updated for 5.0.1 Release. Extracted programlistings/structure changes.</member> - </simplelist> - </revdescription> - </revision> - <revision> - <revnumber>1-1.1</revnumber> - <date>Sat Mar 20 2010</date> - <author> - <firstname>Scott</firstname> - <surname>Mumford</surname> - <email&gt;smumford(a)redhat.com&lt;/email&gt; - </author> - <revdescription> - <simplelist> - <member>Update for Staging</member> - </simplelist> - </revdescription> - </revision> - <revision> - <revnumber>1-1.1</revnumber> - <date>Mon Feb 15 2010</date> - <author> - <firstname>Scott</firstname> - <surname>Mumford</surname> - <email&gt;smumford(a)redhat.com&lt;/email&gt; - </author> - <revdescription> - <simplelist> - <member>First complete edit</member> - </simplelist> - </revdescription> - </revision> - <revision> - <revnumber>1-1.0</revnumber> - <date>Wed Nov 11 2009</date> - <author> - <firstname>Scott</firstname> - <surname>Mumford</surname> - <email&gt;smumford(a)redhat.com&lt;/email&gt; - </author> - <revdescription> - <simplelist> - <member>Initial creation of book by publican</member> - </simplelist> - </revdescription> - </revision> --> - </revhistory> - </simpara> + <revnumber>1-1.10</revnumber> + <date>Thu Sep 23 2010</date> + <author> + <firstname>Scott</firstname> + <surname>Mumford</surname> + <email&gt;smumford(a)redhat.com&lt;/email&gt; + </author> + <revdescription> + <simplelist> + <member>Split <filename>repository-configuration.xml</filename> code sample into two smaller samples (workaround callout pointer bug). Removed further references to components in standalone mode.</member> + </simplelist> + </revdescription> + </revision> + <revision> + <revnumber>1-1.9</revnumber> + <date>Wed Sep 15 2010</date> + <author> + <firstname>Scott</firstname> + <surname>Mumford</surname> + <email&gt;smumford(a)redhat.com&lt;/email&gt; + </author> + <revdescription> + <simplelist> + <member>Started content for &#34;Debugging Resource Bundle Usage&#34; section. Started homoginizing filepath variables.</member> + </simplelist> + </revdescription> + </revision> --> + <revision> + <revnumber>1-1.8</revnumber> + <date>Fri Aug 27 2010</date> + <author> + <firstname>Scott</firstname> + <surname>Mumford</surname> + <email&gt;smumford(a)redhat.com&lt;/email&gt; + </author> + <revdescription> + <simplelist> + <member>Added new concept definitions to JCR chapter.</member> + </simplelist> + </revdescription> + </revision> +<!-- <revision> + <revnumber>1-1.7</revnumber> + <date>Mon Aug 9 2010</date> + <author> + <firstname>Scott</firstname> + <surname>Mumford</surname> + <email&gt;smumford(a)redhat.com&lt;/email&gt; + </author> + <revdescription> + <simplelist> + <member>Further clean-up of programlisting rendering.</member> + </simplelist> + </revdescription> + </revision> --> + <revision> + <revnumber>1-1.6</revnumber> + <date>Thu Aug 5 2010</date> + <author> + <firstname>Scott</firstname> + <surname>Mumford</surname> + <email&gt;smumford(a)redhat.com&lt;/email&gt; + </author> + <revdescription> + <simplelist> + <member>Extracted code snippets.</member> + </simplelist> + </revdescription> + </revision> +<!-- <revision> + <revnumber>1-1.5</revnumber> + <date>Thu Jul 29 2010</date> + <author> + <firstname>Scott</firstname> + <surname>Mumford</surname> + <email&gt;smumford(a)redhat.com&lt;/email&gt; + </author> + <revdescription> + <simplelist> + <member>Updated for 5.0.1 Release. Extracted programlistings/structure changes.</member> + </simplelist> + </revdescription> + </revision> + <revision> + <revnumber>1-1.1</revnumber> + <date>Sat Mar 20 2010</date> + <author> + <firstname>Scott</firstname> + <surname>Mumford</surname> + <email&gt;smumford(a)redhat.com&lt;/email&gt; + </author> + <revdescription> + <simplelist> + <member>Update for Staging</member> + </simplelist> + </revdescription> + </revision> + <revision> + <revnumber>1-1.1</revnumber> + <date>Mon Feb 15 2010</date> + <author> + <firstname>Scott</firstname> + <surname>Mumford</surname> + <email&gt;smumford(a)redhat.com&lt;/email&gt; + </author> + <revdescription> + <simplelist> + <member>First complete edit</member> + </simplelist> + </revdescription> + </revision> + <revision> + <revnumber>1-1.0</revnumber> + <date>Wed Nov 11 2009</date> + <author> + <firstname>Scott</firstname> + <surname>Mumford</surname> + <email&gt;smumford(a)redhat.com&lt;/email&gt; + </author> + <revdescription> + <simplelist> + <member>Initial creation of book by publican</member> + </simplelist> + </revdescription> + </revision> --> + </revhistory> + </simpara> </appendix> Added: epp/docs/branches/5.1/Reference_Guide/en-US/extras/Advanced_Development_JCR_as_managed_datasources/gatein-ds.xml =================================================================== --- epp/docs/branches/5.1/Reference_Guide/en-US/extras/Advanced_Development_JCR_as_managed_datasources/gatein-ds.xml (rev 0) +++ epp/docs/branches/5.1/Reference_Guide/en-US/extras/Advanced_Development_JCR_as_managed_datasources/gatein-ds.xml 2011-07-26 05:04:46 UTC (rev 6929) @@ -0,0 +1,51 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!--~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ~ JBoss, a division of Red Hat ~ + ~ Copyright 2009, Red Hat Middleware, LLC, and individual ~ + ~ contributors as indicated by the @authors tag. See the ~ + ~ copyright.txt in the distribution for a full listing of ~ + ~ individual contributors. ~ + ~ ~ + ~ This is free software; you can redistribute it and/or modify it ~ + ~ under the terms of the GNU Lesser General Public License as ~ + ~ published by the Free Software Foundation; either version 2.1 of ~ + ~ the License, or (at your option) any later version. ~ + ~ ~ + ~ This software is distributed in the hope that it will be useful, ~ + ~ but WITHOUT ANY WARRANTY; without even the implied warranty of ~ + ~ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU ~ + ~ Lesser General Public License for more details. ~ + ~ ~ + ~ You should have received a copy of the GNU Lesser General Public ~ + ~ License along with this software; if not, write to the Free ~ + ~ Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA ~ + ~ 02110-1301 USA, or see the FSF site: http://www.fsf.org. ~ + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~--> + +<datasources> + <no-tx-datasource> + <jndi-name>gatein-idm</jndi-name> + <connection-url>jdbc:hsqldb:${jboss.server.data.dir}${/}gatein${/}hypersonic${/}gatein-idm-localDB</connection-url> + <driver-class>org.hsqldb.jdbcDriver</driver-class> + <user-name>sa</user-name> + <password></password> + + <min-pool-size>5</min-pool-size> + <max-pool-size>20</max-pool-size> + <idle-timeout-minutes>0</idle-timeout-minutes> + <prepared-statement-cache-size>32</prepared-statement-cache-size> + </no-tx-datasource> + + <no-tx-datasource> + <jndi-name>gatein-jcr</jndi-name> + <connection-url>jdbc:hsqldb:${jboss.server.data.dir}${/}gatein${/}hypersonic${/}gatein-jcr-localDB</connection-url> + <driver-class>org.hsqldb.jdbcDriver</driver-class> + <user-name>sa</user-name> + <password></password> + + <min-pool-size>5</min-pool-size> + <max-pool-size>20</max-pool-size> + <idle-timeout-minutes>0</idle-timeout-minutes> + <prepared-statement-cache-size>32</prepared-statement-cache-size> + </no-tx-datasource> +</datasources> Added: epp/docs/branches/5.1/Reference_Guide/en-US/modules/Advanced/JCR/as_managed_datasources.xml =================================================================== --- epp/docs/branches/5.1/Reference_Guide/en-US/modules/Advanced/JCR/as_managed_datasources.xml (rev 0) +++ epp/docs/branches/5.1/Reference_Guide/en-US/modules/Advanced/JCR/as_managed_datasources.xml 2011-07-26 05:04:46 UTC (rev 6929) @@ -0,0 +1,694 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../../../Reference_Guide.ent"> +%BOOK_ENTITIES; +]> +<!-- Resolves JBEPP-690--> +<!-- Source Metadata +This section is based on content synthesized from: + +The EAP Admin and Config Guide +URL: http://docs/docs/en-US/JBoss_Enterprise_Application_Platform/5/html-singl... +Author: ECS +License: CC-BY-SA + +The eXo Platoform Reference Guide +URL: http://docs.exoplatform.org/PLF30/refguide/html/ch-how-to-use-managed-dat... +Author: eXo +Licence: No licence provided in document + +The JBoss Application Server 4.2.2 Administration And Development Guide +URL: http://docs.jboss.org/jbossas/docs/Server_Configuration_Guide/4/html/Conn... +Authors: Alessio Soldano, Andreadis Dimitris, Bill Burke, Brian Stansberry, Carlo de Wolf, Galder Zamarreno, Heiko Braun, Michael Yuan, Roger Pearse, Shelly Mc Gowan, Thomas Diesler +Licence: No licence provided in document +--> + +<section> + <title><remark>Using AS Managed Datasources</remark></title> + <important> + <title>Supported Datasources</title> + <para> + It is important to note that JBoss Enterprise Portal Platform's JCR only supports <emphasis role="bold">no-tx-datasource</emphasis> datasources. + </para> + </important> + <para> + JBoss Enterprise Portal Platform uses JBoss's simplified datasource centric descriptor. This simplified configuration descriptor is deployed the same directory as other deployable components (e.g.; <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/</filename>). + </para> + <para> + In order for the AS to recognize the datasources, they must adhere to the <filename><replaceable>DBNAME</replaceable>-ds.xml</filename> naming convention. + </para> + <para> + Example datasources for all certified databases are located in the <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/docs/examples/jca/</filename> directory. Edit the datasource that corresponds to your database, then copy it to the <filename>deploy/ </filename> directory before restarting the application server. + </para> + <para> + The next section discusses the various parameters used to configure a datasource, however, at a minimum, you will need to set the <parameter>connection-url</parameter>, <parameter>user-name</parameter>, and <parameter>password</parameter> as required for your database. + </para> + <section> + <title>Datasource Configuration</title> + <warning> + <title>You must change your database</title> + <para> + The default persistence configuration works out of the box with + Hypersonic (HSQLDB) so that the JBoss Enterprise Platforms are able to + run &quot;out of the box&quot;. However, <emphasis>Hypersonic is not supported in production and should not be used in a production environment.</emphasis> + </para> + <para> + Known issues with the Hypersonic Database include: + </para> + <itemizedlist> + <listitem> + <para> + no transaction isolation + </para> + </listitem> + <listitem> + <para> + thread and socket leaks (<methodname>connection.close()</methodname> + does not tidy up resources) + </para> + </listitem> + <listitem> + <para> + persistence quality (logs commonly become corrupted after a failure, + preventing automatic recovery) + </para> + </listitem> + <listitem> + <para> + database corruption + </para> + </listitem> + <listitem> + <para> + stability under load (database processes cease when dealing with + too much data) + </para> + </listitem> + <listitem> + <para> + not viable in clustered environments + </para> + </listitem> + </itemizedlist> + </warning> + + <section> + <title>Declaring the datasource</title> + <para> + As mentioned above, datasource files are deployed alongside other deployable items in your <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/</filename> directory. + </para> + <para> + Although the examples in <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/docs/examples/jca/</filename> focus on individual datasources, your <filename><replaceable>DBNAME</replaceable>-ds.xml</filename> file can contain all the required datasources for your portal instance, as shown in the default JBoss Enterprise Portal Platform datasource file below: + </para> +<programlisting language="XML" role="XML"><xi:include href="../../../extras/Advanced_Development_JCR_as_managed_datasources/gatein-ds.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + </section> + + <section> + <title>Datasource Paramenters</title> + <para> + The following list contains parameters used in configuring a datasource: + </para> + <variablelist> + <title>Common Datasource Parameters</title> + <varlistentry> + <term>&lt;mbean&gt;</term> + <listitem> + <para> + A standard JBoss MBean deployment. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>&lt;depends&gt;</term> + <listitem> + <para> + The <literal>ObjectName</literal> of an MBean service this <classname>ConnectionFactory</classname> + or<classname>DataSource</classname> deployment depends upon. The connection manager service will not be started until the dependent services have been started. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>&lt;jndi-name&gt;</term> + <listitem> + <para> + The JNDI name under which the Datasource should be bound. Note that this name is relative to the <wordasword>java:/</wordasword> context, unless <parameter>use-java-context</parameter> is set to false. DataSource wrappers are not usable outside of the server VM, so they are normally bound under the <wordasword>java:/</wordasword>, which isn't shared outside the local VM. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>&lt;use-java-context&gt;</term> + <listitem> + <para> + Boolean value indicating whether the jndi-name should be prefixed with <wordasword>java:</wordasword>. This prefix causes the Datasource to only be accessible from within the JBoss virtual machine. Defaults to <literal>TRUE</literal>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>&lt;user-name&gt;</term> + <listitem> + <para> + The user name used to create the connection to the datasource. The actual username may be overridden by the application code getConnection parameters or the connection creation context JAAS Subject. + </para> + <note> + <title>Security</title> + <para>This is not used when security is configured.</para> + </note> + </listitem> + </varlistentry> + <varlistentry> + <term>&lt;password&gt;</term> + <listitem> + <para> + The password used to create the connection to the datasource. + </para> + <note> + <title>Security</title> + <para>This is not used when security is configured.</para> + </note> + </listitem> + </varlistentry> + <varlistentry> + <term>&lt;transaction-isolation&gt;</term> + <listitem> + <para> + The <literal>java.sql.Connection</literal> transaction isolation of the connection. If not specified, the database-provided default is used. + </para> + <itemizedlist> + <title>Possible values for &lt;transaction-isolation&gt;</title> + <listitem> + <para>TRANSACTION_READ_UNCOMMITTED</para> + </listitem> + <listitem> + <para>TRANSACTION_READ_COMMITTED</para> + </listitem> + <listitem> + <para>TRANSACTION_REPEATABLE_READ</para> + </listitem> + <listitem> + <para>TRANSACTION_SERIALIZABLE</para> + </listitem> + <listitem> + <para>TRANSACTION_NONE</para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>&lt;new-connection-sql&gt;</term> + <listitem> + <para> + An SQL statement that is executed against each new connection. This can be used to set up the connection schema, for instance. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>&lt;check-valid-connection-sql&gt;</term> + <listitem> + <para> + An SQL statement that is executed before the connection is checked out from the pool to make sure it is still valid. If the SQL statement fails, the connection is closed and a new one is created. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>&lt;valid-connection-checker-class-name&gt;</term> + <listitem> + <para> + A class that checks whether a connection is valid using a vendor-specific mechanism. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>&lt;exception-sorter-class-name&gt;</term> + <listitem> + <para> + A class that parses vendor-specific messages to determine whether SQL errors are fatal, and destroys the connection if so. If empty, no errors are treated as fatal. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>&lt;track-statements&gt;</term> + <listitem> + <para> + Whether to monitor for unclosed Statements and ResultSets and issue warnings when they haven&apos;t been closed. The default value is <literal>NOWARN</literal>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>&lt;prepared-statement-cache-size&gt;</term> + <listitem> + <para> + The number of prepared statements per connection to be kept open and reused in subsequent requests. They are stored in a <firstterm>Least Recently Used (LRU)</firstterm> cache. The default value is <literal>0</literal>, meaning that no cache is kept. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>&lt;share-prepared-statements&gt;</term> + <listitem> + <para> + When the &lt;prepared-statement-cache-size&gt; is non-zero, determines whether two requests in the same transaction should return the same statement. Defaults to <literal>FALSE</literal>. + </para> + <example> + <title>Using &lt;share-prepared-statements&gt;</title> + <para> + The goal is to work around questionable driver behavior, where the driver applies auto-commit semantics to local transactions. + </para> +<programlisting language="Java" role="JAVA"> +Connection c = dataSource.getConnection(); // auto-commit == false +PreparedStatement ps1 = c.prepareStatement(...); +ResultSet rs1 = ps1.executeQuery(); +PreparedStatement ps2 = c.prepareStatement(...); +ResultSet rs2 = ps2.executeQuery(); +</programlisting> + <para> + This assumes that the prepared statements are the same. For some drivers, <methodname>ps2.executeQuery()</methodname> automatically closes <varname>rs1</varname>, so you actually need two real prepared statements behind the scenes. This only applies to the auto-commit semantic, where re-running the query starts a new transaction automatically. For drivers that follow the specification, you can set it to <literal>TRUE</literal> to share the same real prepared statement. + </para> + </example> + </listitem> + </varlistentry> + <varlistentry> + <term>&lt;set-tx-query-timeout&gt;</term> + <listitem> + <para> + Whether to enable query timeout based on the length of time remaining until the transaction times out. Defaults to <literal>FALSE</literal>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>&lt;query-timeout&gt;</term> + <listitem> + <para> + The maximum time, in seconds, before a query times out. You can override this value by setting &lt;set-tx-query-timeout&gt; to <literal>TRUE</literal>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>&lt;metadata&gt;&gt;&lt;type-mapping&gt;</term> + <listitem> + <para> + A pointer to the type mapping in <filename>conf/standardjbosscmp.xml</filename>. A legacy from JBoss4. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>&lt;validate-on-match&gt;</term> + <listitem> + <para> + Whether to validate the connection when the JCA layer matches a managed connection, such as when the connection is checked out of the pool. With the addition of &lt;background-validation&gt; this is not required. It is usually not necessary to specify <literal>TRUE</literal> for &lt;validate-on-match&gt; in conjunction with specifying <literal>TRUE</literal> for &lt;background-validation&gt;. Defaults to <literal>TRUE</literal>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>&lt;prefill&gt;</term> + <listitem> + <para> + Whether to attempt to prefill the connection pool to the minimum number of connections. Only <firstterm>supporting pools</firstterm> (OnePool) support this feature. A warning is logged if the pool does not support prefilling. Defaults to <literal>TRUE</literal>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>&lt;background-validation&gt;</term> + <listitem> + <para> + Background connection validation reduces the overall load on the RDBMS system when validating a connection. When using this feature, EAP checks whether the current connection in the pool a separate thread (ConnectionValidator). &lt;background-validation-minutes&gt; depends on this value also being set to <literal>TRUE</literal>. Defaults to <literal>FALSE</literal>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>&lt;background-validation-millis&gt;</term> + <listitem> + <para> + Background connection validation reduces the overall load on the RDBMS system when validating a + connection. Setting this parameter means that JBoss will attempt to validate the current connections in + the pool as a separate thread (<classname>ConnectionValidator</classname>). This parameter&apos;s value + defines the interval, in milliseconds, for which the <classname>ConnectionValidator</classname> will + run. (This value should not be the same as your <literal><![CDATA[<idle-timeout-minutes]]></literal> + value.) + + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>&lt;idle-timeout-minutes&gt;</term> + <listitem> + <para> + The maximum time, in minutes, before an idle connection is closed. A value of <literal>0</literal> disables timeout. Defaults to <literal>15</literal> minutes. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>&lt;track-connection-by-tx&gt;</term> + <listitem> + <para> + Whether the connection should be locked to the transaction, instead of returning it to the pool at the end + of the transaction. In previous releases, this was <literal>true</literal> for local connection factories + and <literal>false</literal> for XA connection factories. The default is now <literal>true</literal> for + both local and XA connection factories, and the element has been deprecated. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>&lt;interleaving&gt;</term> + <listitem> + <para> + Enables interleaving for XA connection factories. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>&lt;background-validation-minutes&gt;</term> + <listitem> + <para> + How often, in minutes, the ConnectionValidator runs. Defaults to <literal>10</literal> minutes. + </para> + <note> + <para> + You should set this to a smallervalue than &lt;idle-timeout-minutes&gt;, unless you have specified &lt;min-pool-size&gt; a minimum pool size set. + </para> + </note> + </listitem> + </varlistentry> + <varlistentry> + <term>&lt;url-delimiter&gt;, &lt;url-property&gt;, &lt;url-selector-strategy-class-name&gt;</term> + <listitem> + <para> + Parameters dealing with database failover. As of JBoss Enterprise Application Platform 5.1, these are configured as part of the main datasource configuration. In previous versions, &lt;url-delimiter&gt; appeared as &lt;url-delimeter&gt;. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>&lt;stale-connection-checker-class-name&gt;</term> + <listitem> + <para> + An implementation of <classname>org.jboss.resource.adapter.jdbc.StateConnectionChecker</classname> that decides whether <systemitem>SQLException</systemitem>s that notify of bad connections throw the <systemitem>org.jboss.resource.adapter.jdbc.StateConnectionException</systemitem> exception. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>&lt;max-pool-size&gt;</term> + <listitem> + <para> + The maximum number of connections allowed in the pool. Defaults to <literal>20</literal>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>&lt;min-pool-size&gt;</term> + <listitem> + <para> + The minimum number of connections maintained in the pool. Unless &lt;prefill&gt; is <literal>TRUE</literal>, the pool remains empty until the first use, at which point the pool is filled to the &lt;min-pool-size&gt;. When the pool size drops below the &lt;min-pool-size&gt; due to idle timeouts, the pool is refilled to the &lt;min-pool-size&gt;. Defaults to <literal>0</literal>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>&lt;blocking-timeout-millis&gt;</term> + <listitem> + <para> + The length of time, in milliseconds, to wait for a connection to become available when all the connections are + checked out. Defaults to <literal>30000</literal>, which is 30 seconds. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>&lt;use-fast-fail&gt;</term> + <listitem> + <para> + Whether to continue trying to acquire a connection from the pool even if the previous attempt has failed, or begin + failover. This is to address performance issues where validation SQL takes significant time and resources to + execute. Defaults to <literal>FALSE</literal>. + </para> + </listitem> + </varlistentry> + </variablelist> + <variablelist> + <title>Parameters for <filename>javax.sql.XADataSource</filename> Usage</title> + <varlistentry> + <term>&lt;connection-url&gt;</term> + <listitem> + <para> + The JDBC driver connection URL string + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>&lt;driver-class&gt;</term> + <listitem> + <para> + The JDBC driver class implementing the <classname>java.sql.Driver</classname> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>&lt;connection-property&gt;</term> + <listitem> + <para> + Used to configure the connections retrieved from the <classname>java.sql.Driver</classname>. + </para> + <example> + <title>Example &lt;connection-property&gt;</title> +<programlisting language="XML" role="XML"> +&lt;connection-property name=&quot;char.encoding&quot;&gt;UTF-8&lt;/connection-property&gt; +</programlisting> + </example> + </listitem> + </varlistentry> + </variablelist> + <variablelist> + <title>Parameters for <filename>javax.sql.XADataSource</filename> Usage</title> + <varlistentry> + <term>&lt;xa-datasource-class&gt;</term> + <listitem> + <para> + The class implementing the <classname>XADataSource</classname> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>&lt;xa-datasource-property&gt;</term> + <listitem> + <para> + Properties used to configure the <classname>XADataSource</classname>. + </para> + <example> + <title>Example &lt;xa-datasource-property&gt; Declarations</title> +<programlisting language="XML" role="XML">&lt;xa-datasource-property name=&quot;IfxWAITTIME&quot;&gt;10&lt;/xa-datasource-property&gt; +&lt;xa-datasource-property name=&quot;IfxIFXHOST&quot;&gt;myhost.mydomain.com&lt;/xa-datasource-property&gt; +&lt;xa-datasource-property name=&quot;PortNumber&quot;&gt;1557&lt;/xa-datasource-property&gt; +&lt;xa-datasource-property name=&quot;DatabaseName&quot;&gt;mydb&lt;/xa-datasource-property&gt; +&lt;xa-datasource-property name=&quot;ServerName&quot;&gt;myserver&lt;/xa-datasource-property&gt; +</programlisting> + </example> + </listitem> + </varlistentry> + <varlistentry> + <term>&lt;xa-resource-timeout&gt;</term> + <listitem> + <para> + The number of seconds passed to <methodname>XAResource.setTransactionTimeout()</methodname> when not zero. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>&lt;isSameRM-override-value&gt;</term> + <listitem> + <para> + When set to <literal>FALSE</literal>, fixes some problems with Oracle databases. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>&lt;no-tx-separate-pools&gt;</term> + <listitem> + <para> + Pool transactional and non-transactional connections separately + </para> + <warning> + <para> + Using this option will cause your total pool size to be twice <varname>max-pool-size</varname>, because two + actual pools will be created. + </para> + </warning> + <para> + Used to fix problems with Oracle. + </para> + </listitem> + </varlistentry> + </variablelist> + + <variablelist> + <title>Security Parameters</title> + <varlistentry> + <term> + <literal><![CDATA[<application-managed-security>]]></literal> + </term> + <listitem> + <para> + Uses the username and password passed on the <methodname>getConnection</methodname> or + <methodname>createConnection</methodname> request by the application. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal><![CDATA[<security-domain>]]></literal> + </term> + <listitem> + <para> + Uses the identified login module configured in <filename>conf/login-module.xml</filename>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal><![CDATA[<security-domain-and-application>]]></literal> + </term> + <listitem> + <para> + Uses the identified login module configured in <filename>conf/login-module.xml</filename> and other + connection request information supplied by the application, for example JMS Queues and Topics. + </para> + </listitem> + </varlistentry> + </variablelist> + + <variablelist id="xa-recovery-parameters"> + <title>Parameters for XA Recovery in the JCA Layer</title> + <varlistentry> + <term>&lt;recover-user-name&gt;</term> + <listitem> + <para> + The user with credentials to perform a recovery operation. + </para> + </listitem> + + </varlistentry> + <varlistentry> + <term>&lt;recover-password&gt;</term> + <listitem> + <para> + Password of the user with credentials to perform a recovery operation. + </para> + </listitem> + + </varlistentry> + <varlistentry> + <term>&lt;recover-security-domain&gt;</term> + <listitem> + <para> + Security domain for recovery. + </para> + </listitem> + + </varlistentry> + <varlistentry> + <term>&lt;no-recover&gt;</term> + <listitem> + <para> + Excludes a datasource from recovery. + </para> + </listitem> + </varlistentry> + </variablelist> + <para> + The fields in <xref linkend="xa-recovery-parameters" /> should have a fall back value of their non-recover + counterparts: &lt;user-name&gt;,&lt; password&gt; and &lt;security-domain&gt;. + </para> + </section> + <section> + <title>Datasource Examples</title> + <section> + <title>Configuring a DataSource for Remote Usage</title> + <para> + JBoss EAP supports accessing a DataSource from a remote client. See <xref linkend="remote-usage-example"/> for the + change that gives the client the ability to look up the DataSource from JNDI, which is to specify + <varname>use-java-context</varname>=<literal>false</literal>. + </para> + <example id="remote-usage-example"> + <title>Configuring a Datasource for Remote Usage</title> +<programlisting language="XML" role="XML"> +&lt;datasources&gt; + &lt;local-tx-datasource&gt; + &lt;jndi-name&gt;GenericDS&lt;/jndi-name&gt; + &lt;use-java-context&gt;false&lt;/use-java-context&gt; + &lt;connection-url&gt;...&lt;/connection-url&gt; + ... +</programlisting> + </example> + <para> + This causes the DataSource to be bound under the JNDI name <literal>GenericDS</literal> instead of the default of + <literal>java:/GenericDS</literal>, which restricts the lookup to the same Virtual Machine as the EAP server. + </para> + <note> + <para> + Use of the &lt;use-java-context&gt; setting is not recommended in a production environment. It requires accessing a + connection pool remotely and this can cause unexpected problems, since connections are not serializable. Also, + transaction propagation is not supported, since it can lead to connection leaks if unreliability is present, such as + in a system crash or network failure. A remote session bean facade is the preferred way to access a datasource + remotely. + </para> + </note> + </section> + <section> + <title>Configuring a Datasource to Use Login Modules</title> + <procedure> + <title>Configuring a Datasource to Use Login Modules</title> + <step> + <title>Add the &lt;security-domain-parameter&gt; to the XML file for the datasource.</title> +<programlisting language="XML" role="XML"> + &lt;datasources&gt; + &lt;local-tx-datasource&gt; + ... + &lt;security-domain&gt;MyDomain&lt;/security-domain&gt; + ... + &lt;/local-tx-datasource&gt; + &lt;/datasources&gt; +</programlisting> + </step> + <step> + <title>Add an application policy to the <filename>login-config.xml</filename> file.</title> + <para> + The authentication section needs to include the configuration for your login-module. For example, to encrypt the + database password, use the <systemitem>SecureIdentityLoginModule</systemitem> login module. + </para> +<programlisting language="XML" role="XML"> +&lt;application-policy name=&quot;MyDomain&quot;&gt; + &lt;authentication&gt; + &lt;login-module code=&quot;org.jboss.resource.security.SecureIdentityLoginModule&quot; flag=&quot;required&quot;&gt; + &lt;module-option name=&quot;username&quot;&gt;scott&lt;/module-option&gt; + &lt;module-option name=&quot;password&quot;&gt;-170dd0fbd8c13748&lt;/module-option&gt; + &lt;module-option name=&quot;managedConnectionFactoryName&quot;&gt;jboss.jca:service=LocalTxCM,name=OracleDSJAAS&lt;/module-option&gt; + &lt;/login-module&gt; + &lt;/authentication&gt; +&lt;/application-policy&gt; +</programlisting> + </step> + <step> + <para> + If you plan to fetch the data source connection from a web application, authentication must be enabled for the web + application, so that the <systemitem>Subject</systemitem> is populated. + </para> + </step> + <step> + <para> + If users need the ability to connect anonymously, add an additional login module to the application-policy, to + populate the security credentials. + </para> + </step> + <step> + <para> + Add the <systemitem>UsersRolesLoginModule</systemitem> module to the beginning of the chain. The + <systemitem>usersProperties</systemitem> and <systemitem>rolesProperties</systemitem> parameters can be directed to + dummy files. + </para> +<programlisting language="XML" role="XML"> +&lt;login-module code=&quot;org.jboss.security.auth.spi.UsersRolesLoginModule&quot; flag=&quot;required&quot;&gt; + &lt;module-option name=&quot;unauthenticatedIdentity&quot;&gt;nobody&lt;/module-option&gt; + &lt;module-option name=&quot;usersProperties&quot;&gt;props/users.properties&lt;/module-option&gt; + &lt;module-option name=&quot;rolesProperties&quot;&gt;props/roles.properties&lt;/module-option&gt; +&lt;/login-module&gt; +</programlisting> + </step> + </procedure> + </section> + </section> + </section> +</section> \ No newline at end of file Modified: epp/docs/branches/5.1/Reference_Guide/en-US/modules/Advanced/JCR.xml =================================================================== --- epp/docs/branches/5.1/Reference_Guide/en-US/modules/Advanced/JCR.xml 2011-07-26 04:48:07 UTC (rev 6928) +++ epp/docs/branches/5.1/Reference_Guide/en-US/modules/Advanced/JCR.xml 2011-07-26 05:04:46 UTC (rev 6929) @@ -4,29 +4,30 @@ %BOOK_ENTITIES; ]> <chapter id="chap-Reference_Guide-eXo_JCR"> - <title>eXo JCR</title> - <xi:include href="JCR/intro.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <title>eXo JCR</title> + <xi:include href="JCR/intro.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="JCR/configuration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <!-- - <xi:include href="JCR/jdbc-data-container-config.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="JCR/jdbc-data-container-config.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> --> + <xi:include href="JCR/as_managed_datasources.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="JCR/external-value-storages.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="JCR/search-configuration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="JCR/multilanguage-support.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="JCR/search-configuration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="JCR/multilanguage-support.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <!-- <xi:include href="JCR/configuration-persister.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> --> <!-- <xi:include href="JCR/cluster-config.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> --> - <xi:include href="JCR/jbosscache-configuration-templates.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="JCR/lock-manager-config.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="JCR/query-handler-config.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="JCR/jbossts-transaction-service.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="JCR/jbosscache-configuration-templates.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="JCR/lock-manager-config.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="JCR/query-handler-config.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="JCR/jbossts-transaction-service.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <!-- - <xi:include href="JCR/transaction-manager-lookup.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="JCR/transaction-manager-lookup.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> --> <!-- - <xi:include href="JCR/statistics.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="JCR/statistics.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> --> </chapter> Modified: epp/docs/branches/5.1/Reference_Guide/en-US/modules/AuthenticationAndIdentity/LDAP.xml =================================================================== --- epp/docs/branches/5.1/Reference_Guide/en-US/modules/AuthenticationAndIdentity/LDAP.xml 2011-07-26 04:48:07 UTC (rev 6928) +++ epp/docs/branches/5.1/Reference_Guide/en-US/modules/AuthenticationAndIdentity/LDAP.xml 2011-07-26 05:04:46 UTC (rev 6929) @@ -5,12 +5,12 @@ ]> <section id="sect-Reference_Guide-LDAP_Integration"> - <title>LDAP Integration</title> + <title><remark>LDAP Integration</remark></title> <note> - <title>Notational Device</title> - <para> + <title>Notational Device</title> + <para> For ease of readability the following section uses the notational device <replaceable>ID_HOME</replaceable> to represent the file path <filename><replaceable>JBOSS_HOME</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/organization/</filename>, as this directory is the root of all JBoss Enterprise Portal Platform's identity-related configuration. - </para> + </para> </note> <para> <emphasis role="bold">LDAP</emphasis> (Lightweight Directory Access Protocol) is a set of open protocols used to access centrally stored information over a network. It is based on the X.500 standard for directory sharing, but is less complex and resource-intensive @@ -43,7 +43,7 @@ <emphasis>Version</emphasis> </entry> </row> - </thead> + </thead> <tbody> <row> <entry> Modified: epp/docs/branches/5.1/Reference_Guide/en-US/modules/AuthenticationAndIdentity/SSO.xml =================================================================== --- epp/docs/branches/5.1/Reference_Guide/en-US/modules/AuthenticationAndIdentity/SSO.xml 2011-07-26 04:48:07 UTC (rev 6928) +++ epp/docs/branches/5.1/Reference_Guide/en-US/modules/AuthenticationAndIdentity/SSO.xml 2011-07-26 05:04:46 UTC (rev 6929) @@ -4,853 +4,853 @@ %BOOK_ENTITIES; ]> <section id="sect-Reference_Guide-SSO_Single_Sign_On"> - <title>SSO - Single Sign On</title> - <section id="sect-Reference_Guide-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-SSO_Single_Sign_On-CAS_Central_Authentication_Service" /> - </para> - </listitem> - <listitem> - <para> - <xref linkend="sect-Reference_Guide-SSO_Single_Sign_On-JOSSO_Java_Open_Single_Sign_On_Project" /> - </para> - </listitem> - <listitem> - <para> - <xref linkend="sect-Reference_Guide-SSO_Single_Sign_On-OpenSSO_The_Open_Web_SSO_project" /> - </para> - </listitem> - <listitem> - <para> - <xref linkend="sect-Reference_Guide-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> - </warning> - </section> + <title>SSO - Single Sign On</title> + <section id="sect-Reference_Guide-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-SSO_Single_Sign_On-CAS_Central_Authentication_Service" /> + </para> + </listitem> + <listitem> + <para> + <xref linkend="sect-Reference_Guide-SSO_Single_Sign_On-JOSSO_Java_Open_Single_Sign_On_Project" /> + </para> + </listitem> + <listitem> + <para> + <xref linkend="sect-Reference_Guide-SSO_Single_Sign_On-OpenSSO_The_Open_Web_SSO_project" /> + </para> + </listitem> + <listitem> + <para> + <xref linkend="sect-Reference_Guide-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> + </warning> + </section> - - <section id="sect-Reference_Guide-SSO_Single_Sign_On-CAS_Central_Authentication_Service"> - <title>CAS - 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/products/cas/">here</ulink>;. - </para> - <procedure id="proc-Reference_Guide-CAS_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...;. - </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> - 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-CAS_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> - + + <section id="sect-Reference_Guide-SSO_Single_Sign_On-CAS_Central_Authentication_Service"> + <title>CAS - 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/products/cas/">here</ulink>;. + </para> + <procedure id="proc-Reference_Guide-CAS_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...;. + </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> + 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-CAS_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: - </para> - + <para> + ...with the following: + </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> - <para> - Make sure to set the <emphasis>host</emphasis>, <emphasis>port</emphasis> and <emphasis>context</emphasis> with the values corresponding to your portal (also available in <filename><replaceable>PORTAL_SSO</replaceable>/cas/plugin/WEB-INF/deployerConfigContext.xml</filename>). - </para> - </step> - <step> - <para> - Copy <filename><replaceable>PORTAL_SSO</replaceable>/cas/plugin/WEB-INF/lib/sso-cas-plugin-&#60;VERSION&#62;.jar</filename> and <filename><replaceable>PORTAL_SSO</replaceable>/cas/plugin/WEB-INF/lib/commons-httpclient-&#60;VERSION&#62;.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> - + <para> + Make sure to set the <emphasis>host</emphasis>, <emphasis>port</emphasis> and <emphasis>context</emphasis> with the values corresponding to your portal (also available in <filename><replaceable>PORTAL_SSO</replaceable>/cas/plugin/WEB-INF/deployerConfigContext.xml</filename>). + </para> + </step> + <step> + <para> + Copy <filename><replaceable>PORTAL_SSO</replaceable>/cas/plugin/WEB-INF/lib/sso-cas-plugin-&#60;VERSION&#62;.jar</filename> and <filename><replaceable>PORTAL_SSO</replaceable>/cas/plugin/WEB-INF/lib/commons-httpclient-&#60;VERSION&#62;.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> - - <procedure id="proc-Reference_Guide-CAS_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> - + </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> + + <procedure id="proc-Reference_Guide-CAS_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> - </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-CAS_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>gatein.ear/web.war/groovy/groovy/webui/component/UIBannerPortlet.gtml</filename> file as follows: - </para> - + <para> + There's a line comment already in this source file to assist you. + </para> + </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-CAS_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>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>gatein.ear/web.war/groovy/portal/webui/component/UILogoPortlet.gtmpl</filename> file as follows: - </para> - + </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/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> - + </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> - + </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> - <step> - <para> - Replace the <literal>InitiateLoginServlet</literal> declaration in <filename>gatein.ear/02portal.war/WEB-INF/web.xml</filename> with: - </para> - + </step> + <step> + <para> + Replace the <literal>InitiateLoginServlet</literal> declaration in <filename>gatein.ear/02portal.war/WEB-INF/web.xml</filename> with: + </para> + <programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default110.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> + </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-SSO_Single_Sign_On-JOSSO_Java_Open_Single_Sign_On_Project"> - <title>JOSSO - 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-JOSSO_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://so...;. - </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-JOSSO_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 should now 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-JOSSO_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> - </para> - </step> - <step> - <para> - Copy the <filename><replaceable>PORTAL_SSO</replaceable>/josso/gatein.ear/02portal.war/WEB-INF/classes/josso-agent-config.xml</filename> file into the <filename>gatein.ear/02portal.war/WEB-INF/classes</filename> directory. - </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> - + + <section id="sect-Reference_Guide-SSO_Single_Sign_On-JOSSO_Java_Open_Single_Sign_On_Project"> + <title>JOSSO - 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-JOSSO_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://so...;. + </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-JOSSO_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 should now 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-JOSSO_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> + </para> + </step> + <step> + <para> + Copy the <filename><replaceable>PORTAL_SSO</replaceable>/josso/gatein.ear/02portal.war/WEB-INF/classes/josso-agent-config.xml</filename> file into the <filename>gatein.ear/02portal.war/WEB-INF/classes</filename> directory. + </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> - The installation can be tested at this point. - </para> - <procedure> - <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> - </procedure> - </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-JOSSO_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>gatein.ear/web.war/groovy/groovy/webui/component/UIBannerPortlet.gtml</filename> file modify the 'Sign In' link as follows: - </para> - + </step> + <step> + <para> + The installation can be tested at this point. + </para> + <procedure> + <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> + </procedure> + </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-JOSSO_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>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> - + </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> - + </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> - + </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> - <step> - <para> - Replace the <literal>InitiateLoginServlet</literal> declaration in <filename>gatein.ear/02portal.war/WEB-INF/web.xml</filename> with: - </para> - + </step> + <step> + <para> + Replace the <literal>InitiateLoginServlet</literal> declaration in <filename>gatein.ear/02portal.war/WEB-INF/web.xml</filename> with: + </para> + <programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default116.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - </step> - <step> - <para> - Remove the <literal>PortalLoginController</literal> servlet declaration and mapping in <filename>gatein.ear/02portal.war/WEB-INF/web.xml</filename> - </para> - </step> - </procedure> - - <para> - From now on, all links redirecting to the user authentication pages will redirect to the JOSSO centralized authentication form. - </para> - </section> + </step> + <step> + <para> + Remove the <literal>PortalLoginController</literal> servlet declaration and mapping in <filename>gatein.ear/02portal.war/WEB-INF/web.xml</filename> + </para> + </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-SSO_Single_Sign_On-OpenSSO_The_Open_Web_SSO_project"> - <title>OpenSSO - The Open Web SSO project</title> - <para> - This Single Sign On plugin enables seamless integration between JBoss Enterprise Portal Platform and the Open Web SSO project (<emphasis role="bold">OpenSSO</emphasis>) Single Sign On Framework. Details about OpenSSO can be found <ulink url="https://opensso.dev.java.net/">here</ulink>;. - </para> - <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-OpenSSO_The_Open_Web_SSO_project-Obtaining_OpenSSO"> - <title>Obtaining OpenSSO</title> - <step> - <para> - Download OpenSSO from <ulink type="http" url="https://opensso.dev.java.net/public/use/index.html">htt...;. - </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> - - <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-OpenSSO_The_Open_Web_SSO_project-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> - + + <section id="sect-Reference_Guide-SSO_Single_Sign_On-OpenSSO_The_Open_Web_SSO_project"> + <title>OpenSSO - The Open Web SSO project</title> + <para> + This Single Sign On plugin enables seamless integration between JBoss Enterprise Portal Platform and the Open Web SSO project (<emphasis role="bold">OpenSSO</emphasis>) Single Sign On Framework. Details about OpenSSO can be found <ulink url="https://opensso.dev.java.net/">here</ulink>;. + </para> + <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-OpenSSO_The_Open_Web_SSO_project-Obtaining_OpenSSO"> + <title>Obtaining OpenSSO</title> + <step> + <para> + Download OpenSSO from <ulink type="http" url="https://opensso.dev.java.net/public/use/index.html">htt...;. + </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> + + <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-OpenSSO_The_Open_Web_SSO_project-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; - </para> - <itemizedlist> - <listitem> - <para> - <filename><replaceable>PORTAL_SSO</replaceable>/opensso/plugin/WEB-INF/lib/sso-opensso-plugin-&#60;VERSION&#62;.jar</filename> - </para> - </listitem> - <listitem> - <para> - <filename><replaceable>PORTAL_SSO</replaceable>/opensso/plugin/WEB-INF/lib/commons-httpclient-&#60;VERSION&#62;.jar</filename> - </para> - </listitem> - <listitem> - <para> - <filename><replaceable>PORTAL_SSO</replaceable>/opensso/plugin/WEB-INF/lib/commons-logging-&#60;VERSION&#62;.jar</filename> - </para> - </listitem> - </itemizedlist> - <para> - ...into the Tomcat directory at <filename>TOMCAT_HOME/webapps/opensso/WEB-INF/lib</filename>. - </para> - </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-OpenSSO_The_Open_Web_SSO_project-Configure_the_gatein_realm"> - <title>Configure the &#34;gatein&#34; 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>admin</literal>. - </para> - <important> - <para> - Go to the &#34;<emphasis role="bold">Configuration</emphasis>&#34; tab then to &#34;<emphasis role="bold">Authentication</emphasis>&#34;. - </para> - <para> - Follow the link to &#34;<emphasis role="bold">Core</emphasis>&#34; and add a new value with the class name &#34;<literal>org.gatein.sso.opensso.plugin.AuthenticationPlugin</literal>&#34;. - </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 &#34;<emphasis role="bold">Access control</emphasis>&#34; tab and create new realm called &#34;<literal>gatein</literal>&#34;. - </para> - </step> - <step> - <procedure> - <step> - <para> - Go to the new &#34;<literal>gatein</literal>&#34; realm and click on the &#34;<emphasis role="bold">Authentication</emphasis>&#34; tab. - </para> - </step> - <step> - <para> - Click on &#34;<emphasis role="bold">ldapService</emphasis>&#34; (at the bottom in the &#34;Authentication chaining&#34; section). - </para> - </step> - <step> - <para> - Change the selection from &#34;<literal>Datastore</literal>&#34;, which is the default module in the authentication chain, to &#34;<literal>AuthenticationPlugin</literal>&#34;. - </para> - </step> - </procedure> - - <para> - These changes enable authentication of the &#34;<literal>gatein</literal>&#34; realm using the <literal>GateIn REST</literal> service instead of the OpenSSO LDAP server. - </para> - </step> - <step> - <para> - Go to &#34;<emphasis role="bold">Advanced properties</emphasis>&#34; and change <literal>UserProfile</literal> from &#34;<parameter>Required</parameter>&#34; to &#34;<parameter>Dynamic</parameter>&#34; 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> - <procedure> - <step> - <para> - Go to &#34;<emphasis role="bold">Access control</emphasis>&#34;, then <emphasis role="bold">Top level realm</emphasis>, then click on the &#34;<emphasis role="bold">Privileges</emphasis>&#34; tab and go to &#34;<emphasis role="bold">All authenticated users</emphasis>&#34;. - </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> - </procedure> - </step> - <step> - <para> - Repeat step 7 for the '<literal>gatein</literal>' realm as well. - </para> - </step> - </procedure> - - <!-- <para> + </step> + <step> + <para> + Copy the following files; + </para> + <itemizedlist> + <listitem> + <para> + <filename><replaceable>PORTAL_SSO</replaceable>/opensso/plugin/WEB-INF/lib/sso-opensso-plugin-&#60;VERSION&#62;.jar</filename> + </para> + </listitem> + <listitem> + <para> + <filename><replaceable>PORTAL_SSO</replaceable>/opensso/plugin/WEB-INF/lib/commons-httpclient-&#60;VERSION&#62;.jar</filename> + </para> + </listitem> + <listitem> + <para> + <filename><replaceable>PORTAL_SSO</replaceable>/opensso/plugin/WEB-INF/lib/commons-logging-&#60;VERSION&#62;.jar</filename> + </para> + </listitem> + </itemizedlist> + <para> + ...into the Tomcat directory at <filename>TOMCAT_HOME/webapps/opensso/WEB-INF/lib</filename>. + </para> + </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-OpenSSO_The_Open_Web_SSO_project-Configure_the_gatein_realm"> + <title>Configure the &#34;gatein&#34; 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>admin</literal>. + </para> + <important> + <para> + Go to the &#34;<emphasis role="bold">Configuration</emphasis>&#34; tab then to &#34;<emphasis role="bold">Authentication</emphasis>&#34;. + </para> + <para> + Follow the link to &#34;<emphasis role="bold">Core</emphasis>&#34; and add a new value with the class name &#34;<literal>org.gatein.sso.opensso.plugin.AuthenticationPlugin</literal>&#34;. + </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 &#34;<emphasis role="bold">Access control</emphasis>&#34; tab and create new realm called &#34;<literal>gatein</literal>&#34;. + </para> + </step> + <step> + <procedure> + <step> + <para> + Go to the new &#34;<literal>gatein</literal>&#34; realm and click on the &#34;<emphasis role="bold">Authentication</emphasis>&#34; tab. + </para> + </step> + <step> + <para> + Click on &#34;<emphasis role="bold">ldapService</emphasis>&#34; (at the bottom in the &#34;Authentication chaining&#34; section). + </para> + </step> + <step> + <para> + Change the selection from &#34;<literal>Datastore</literal>&#34;, which is the default module in the authentication chain, to &#34;<literal>AuthenticationPlugin</literal>&#34;. + </para> + </step> + </procedure> + + <para> + These changes enable authentication of the &#34;<literal>gatein</literal>&#34; realm using the <literal>GateIn REST</literal> service instead of the OpenSSO LDAP server. + </para> + </step> + <step> + <para> + Go to &#34;<emphasis role="bold">Advanced properties</emphasis>&#34; and change <literal>UserProfile</literal> from &#34;<parameter>Required</parameter>&#34; to &#34;<parameter>Dynamic</parameter>&#34; 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> + <procedure> + <step> + <para> + Go to &#34;<emphasis role="bold">Access control</emphasis>&#34;, then <emphasis role="bold">Top level realm</emphasis>, then click on the &#34;<emphasis role="bold">Privileges</emphasis>&#34; tab and go to &#34;<emphasis role="bold">All authenticated users</emphasis>&#34;. + </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> + </procedure> + </step> + <step> + <para> + Repeat step 7 for the '<literal>gatein</literal>' realm as well. + </para> + </step> + </procedure> + + <!-- <para> TODO: The above OpenSSO manual configuration could be replaced by configuration files prepared in advance </para> --> - <procedure id="proc-Reference_Guide-OpenSSO_The_Open_Web_SSO_project-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>GATEIN_HOME/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> - + <procedure id="proc-Reference_Guide-OpenSSO_The_Open_Web_SSO_project-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>GATEIN_HOME/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/default118.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></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> - - <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-OpenSSO_The_Open_Web_SSO_project-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>gatein.ear/web.war/groovy/groovy/webui/component/UIBannerPortlet.gtml</filename> file as follows: - </para> - + </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> + + <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-OpenSSO_The_Open_Web_SSO_project-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>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> - + </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> - + </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> - + </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> - <step> - <para> - Replace the <literal>InitiateLoginServlet</literal> declaration in <filename>gatein.ear/02portal.war/WEB-INF/web.xml</filename> with: - </para> - + </step> + <step> + <para> + Replace the <literal>InitiateLoginServlet</literal> declaration in <filename>gatein.ear/02portal.war/WEB-INF/web.xml</filename> with: + </para> + <programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default123.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> + </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-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> + + <section id="sect-Reference_Guide-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 user. - </para> - </step> - <step> - <para> - The user experiences a seamless single sign on (SSO) into the web application. - </para> - </step> - </procedure> - - <para> - JBoss Enterprise Portal Platform uses JBoss Negotiation to enable SPNEGO-based desktop SSO. - </para> - <para> - The following procedure outlines how to integrate SPNEGO with the JBoss Enterprise Portal Platform. - </para> - <procedure id="proc-Reference_Guide-SPNEGO_Simple_and_Protected_GSSAPI_Negotiation_Mechanism-SPNEGO_Configuration"> - <title>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> - + </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 user. + </para> + </step> + <step> + <para> + The user experiences a seamless single sign on (SSO) into the web application. + </para> + </step> + </procedure> + + <para> + JBoss Enterprise Portal Platform uses JBoss Negotiation to enable SPNEGO-based desktop SSO. + </para> + <para> + The following procedure outlines how to integrate SPNEGO with the JBoss Enterprise Portal Platform. + </para> + <procedure id="proc-Reference_Guide-SPNEGO_Simple_and_Protected_GSSAPI_Negotiation_Mechanism-SPNEGO_Configuration"> + <title>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. See the <ulink type="http" url="http://community.jboss.org/wiki/SettingupyourKerberosDevelopmen... up your Kerberos Development Environment</ulink> guide 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> - + <para> + The '<literal>keyTab</literal>' value should point to the keytab file that was generated by the <literal>kadmin</literal> Kerberos tool. See the <ulink type="http" url="http://community.jboss.org/wiki/SettingupyourKerberosDevelopmen... up your Kerberos Development Environment</ulink> guide 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 adding <filename><replaceable>PORTAL_SSO</replaceable>/spnego/gatein.ear/lib/sso-agent.jar</filename> and <filename><replaceable>PORTAL_SSO</replaceable>/spnego/gatein.ear/lib/spnego-<replaceable>VERSION</replaceable>-epp-GA.jar</filename> to <filename>deploy/gatein.ear/lib</filename>. - </para> - </step> - <step> - <para> - Modifying <filename>deploy/gatein.ear/META-INF/gatein-jboss-beans.xml</filename> to match the following: - </para> - + </step> + <step> + <para> + Add the Gatein SSO module binaries by adding <filename><replaceable>PORTAL_SSO</replaceable>/spnego/gatein.ear/lib/sso-agent.jar</filename> and <filename><replaceable>PORTAL_SSO</replaceable>/spnego/gatein.ear/lib/spnego-<replaceable>VERSION</replaceable>-epp-GA.jar</filename> to <filename>deploy/gatein.ear/lib</filename>. + </para> + </step> + <step> + <para> + Modifying <filename>deploy/gatein.ear/META-INF/gatein-jboss-beans.xml</filename> 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 the SPNEGO <literal>LoginModule</literal> for use with JBoss Enterprise Portal Platform. - </para> - </step> - <step> - <para> - Modify <filename>gatein.ear/02portal.war/WEB-INF/web.xml</filename> to match: - </para> - + <para> + This activates the SPNEGO <literal>LoginModule</literal> for use with JBoss Enterprise Portal Platform. + </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> - This integrates SPNEGO support into the Portal web archive by switching authentication mechanism from the default &#34;<literal>FORM</literal>&#34;-based to &#34;<literal>SPNEGO</literal>&#34;-based authentication. - </para> - </step> - <step> - <para> - Add the following filters to the top of the Filter chain in the <filename>web.xml</filename> file: - </para> - + <para> + This integrates SPNEGO support into the Portal web archive by switching authentication mechanism from the default &#34;<literal>FORM</literal>&#34;-based to &#34;<literal>SPNEGO</literal>&#34;-based authentication. + </para> + </step> + <step> + <para> + Add the following filters to the top of the Filter chain in the <filename>web.xml</filename> file: + </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>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/web.war/groovy/groovy/webui/component/UIBannerPortlet.gtmpl</filename> to match the following: - </para> - + <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> - <para> - This modifies the Portal's '<emphasis role="bold">Sign In</emphasis>' link to perform SPNEGO authentication. - </para> - </step> - <step> - <para> - Start the JBoss Enterprise Portal Platform; - </para> + <para> + This modifies the Portal's '<emphasis role="bold">Sign In</emphasis>' link to perform SPNEGO authentication. + </para> + </step> + <step> + <para> + Start the JBoss Enterprise Portal Platform; + </para> <programlisting language="Java" role="Java"><xi:include parse="text" href="../../extras/Authentication_Identity_SSO/default130.java" 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> - + <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> - </section> + </step> + </procedure> + + <para> + Clicking the 'Sign In' link on the JBoss Enterprise Portal Platform should automatically sign the 'demo' user into the portal. + </para> + </section> </section> Modified: epp/docs/branches/5.1/Reference_Guide/en-US/modules/AuthenticationAndIdentity.xml =================================================================== --- epp/docs/branches/5.1/Reference_Guide/en-US/modules/AuthenticationAndIdentity.xml 2011-07-26 04:48:07 UTC (rev 6928) +++ epp/docs/branches/5.1/Reference_Guide/en-US/modules/AuthenticationAndIdentity.xml 2011-07-26 05:04:46 UTC (rev 6929) @@ -6,11 +6,11 @@ <chapter id="chap-Reference_Guide-Authentication_and_Identity"> <title>Authentication and Identity</title> <section id="sect-Reference_Guide-Authentication_and_Identity-Password_Encryption" > - <title>Password Encryption</title> + <title><remark>Password Encryption</remark></title> <!--The warning and first listitem below were relocated from sect-Reference_Guide-Authentication_Token_Configuration as security and plain-text password issues were being expanded on (from JBEPP-610)--> <warning> - <title>Username and passwords stored in clear text</title> - <para> + <title>Username and passwords stored in clear text</title> + <para> The <emphasis>Remember Me</emphasis> feature of JBoss Enterprise Portal Platform uses a token mechanism to be able to authenticate returning users without requiring an explicit login. However, to be able to authenticate these users, the token needs to store the username and password in clear text in the JCR. </para> </warning> @@ -64,11 +64,11 @@ </orderedlist> </section> - <xi:include href="AuthenticationAndIdentity/PredefinedUserConfiguration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="AuthenticationAndIdentity/AuthenticationTokenConfiguration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="AuthenticationAndIdentity/BackendConfiguration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="AuthenticationAndIdentity/OrganizationAPI.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="AuthenticationAndIdentity/AccessingUserProfile.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="AuthenticationAndIdentity/SSO.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="AuthenticationAndIdentity/PredefinedUserConfiguration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="AuthenticationAndIdentity/AuthenticationTokenConfiguration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="AuthenticationAndIdentity/BackendConfiguration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="AuthenticationAndIdentity/OrganizationAPI.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="AuthenticationAndIdentity/AccessingUserProfile.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="AuthenticationAndIdentity/SSO.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="AuthenticationAndIdentity/LDAP.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> </chapter> Modified: epp/docs/branches/5.1/Reference_Guide/en-US/modules/Introduction.xml =================================================================== --- epp/docs/branches/5.1/Reference_Guide/en-US/modules/Introduction.xml 2011-07-26 04:48:07 UTC (rev 6928) +++ epp/docs/branches/5.1/Reference_Guide/en-US/modules/Introduction.xml 2011-07-26 05:04:46 UTC (rev 6929) @@ -4,65 +4,99 @@ %BOOK_ENTITIES; ]> <chapter id="chap-Reference_Guide-Introduction"> - <title>Introduction</title> - <para> - JBoss Enterprise Portal Platform is based on the GateIn project which is the merge of two mature Java projects; JBoss Portal and eXo Portal. This new community project takes the best of both offerings and incorporates them into a single portal framework. The aim is to provide an intuitive user-friendly portal, and a framework to address the needs of today's Web 2.0 applications. - </para> - <mediaobject> - <imageobject role="html"> - <imagedata align="center" fileref="images/Common/Frontpage.png" format="PNG" scale="100" width="444" /> - </imageobject> - <imageobject role="fo"> - <imagedata align="center" contentwidth="150mm" fileref="images/Common/Frontpage.png" format="PNG" width="444" /> - </imageobject> - </mediaobject> - <para> - This book provides a deep-dive information about installation and configuration of the services provided by JBoss Enterprise Portal Platform. - </para> - <section id="sect-Reference_Guide-Introduction-Related_Links"> - <title>Related Links</title> - <variablelist> - <varlistentry> - <term>Technical documentation</term> - <listitem> - <para> - Other technical documentation, including an <emphasis role="bold">Installation Guide</emphasis>, and a <emphasis role="bold">User Guide</emphasis> can be found at <ulink type="http" url="http://www.redhat.com/docs/en-US/JBoss_Enterprise_Portal_Platfo... - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>Non-technical documentation</term> - <listitem> - <para> - Links to non-technical documents are included on the front page of the portal: - </para> - <mediaobject> - <imageobject role="html"> - <imagedata align="center" fileref="images/Common/Non-tech-docs.png" format="PNG" scale="90" width="444" /> - </imageobject> - <imageobject role="fo"> - <imagedata align="center" contentwidth="130mm" fileref="images/Common/Non-tech-docs.png" format="PNG" width="444" /> - </imageobject> - </mediaobject> - </listitem> - </varlistentry> - <varlistentry> - <term>Videos</term> - <listitem> - <para> - A link to <ulink type="http" url="http://vimeo.com/channels/gatein">videos</ulink> related to the JBoss Enterprise Portal Platform is also included on the front page: - </para> - <mediaobject> - <imageobject role="html"> - <imagedata align="center" fileref="images/Common/Videos.png" format="PNG" scale="90" width="444" /> - </imageobject> - <imageobject role="fo"> - <imagedata align="center" contentwidth="130mm" fileref="images/Common/Videos.png" format="PNG" width="444" /> - </imageobject> - </mediaobject> - </listitem> - </varlistentry> - </variablelist> - </section> + <title>Introduction</title> + <para> + JBoss Enterprise Portal Platform is based on the GateIn project which is the merge of two mature Java projects; JBoss Portal and eXo Portal. This new community project takes the best of both offerings and incorporates them into a single portal framework. The aim is to provide an intuitive user-friendly portal, and a framework to address the needs of today's Web 2.0 applications. + </para> + <mediaobject> + <imageobject role="html"> + <imagedata align="center" fileref="images/Common/Frontpage.png" format="PNG" scale="100" width="444" /> + </imageobject> + <imageobject role="fo"> + <imagedata align="center" contentwidth="150mm" fileref="images/Common/Frontpage.png" format="PNG" width="444" /> + </imageobject> + </mediaobject> + <para> + This book provides a deep-dive information about installation and configuration of the services provided by JBoss Enterprise Portal Platform. + </para> + <note> + <title>Notational Devices</title> + <para> + Along with the <emphasis>Document Conventions</emphasis> outlined in the <xref linkend="pref-Reference_Guide-Preface"/>, this document will also use the following notational devices: + <variablelist> + <title>Devices</title> + <varlistentry> + <term><replaceable>&lt;JBOSS_HOME&gt;</replaceable></term> + <listitem> + <para> + This device will refer to the <application>JBoss Application Server</application> (<filename>jboss-as</filename>) directory deployed in JBoss Enterprise Portal Platform by default. + </para> + <para> + Therefore, if your JBoss Enterprise Portal Platform instance is deployed into a directory called <filename>jboss-epp-&VZ;/</filename>, your <replaceable>&lt;JBOSS_HOME&gt;</replaceable> directory would be <filename>jboss-epp-&VZ;/jboss-as/</filename>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><replaceable>&lt;PROFILE&gt;</replaceable></term> + <listitem> + <para> + This device will usually follow an instance of <replaceable>&lt;JBOSS_HOME&gt;</replaceable> in a file path and refers to the directory that contains the server profile your JBoss Enterprise Portal Platform instance is configured to use. + </para> + <para> + JBoss Enterprise Portal Platform comes with six profiles by default; <emphasis role="bold">all</emphasis>, <emphasis role="bold">default</emphasis>, <emphasis role="bold">minimal</emphasis>, <emphasis role="bold">production</emphasis>, <emphasis role="bold">standard</emphasis> and <emphasis role="bold">web</emphasis>. These profiles are found in the <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/</filename> directory. + </para> + <para> + Therefore, if you are using the <emphasis>default</emphasis> profile, your <replaceable>&lt;PROFILE&gt;</replaceable> directory would be <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/default/</filename> + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </note> + <section id="sect-Reference_Guide-Introduction-Related_Links"> + <title>Related Links</title> + <variablelist> + <varlistentry> + <term>Technical documentation</term> + <listitem> + <para> + Other technical documentation, including an <emphasis role="bold">Installation Guide</emphasis>, and a <emphasis role="bold">User Guide</emphasis> can be found at <ulink type="http" url="http://www.redhat.com/docs/en-US/JBoss_Enterprise_Portal_Platfo... + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Non-technical documentation</term> + <listitem> + <para> + Links to non-technical documents are included on the front page of the portal: + </para> + <mediaobject> + <imageobject role="html"> + <imagedata align="center" fileref="images/Common/Non-tech-docs.png" format="PNG" scale="90" width="444" /> + </imageobject> + <imageobject role="fo"> + <imagedata align="center" contentwidth="130mm" fileref="images/Common/Non-tech-docs.png" format="PNG" width="444" /> + </imageobject> + </mediaobject> + </listitem> + </varlistentry> + <varlistentry> + <term>Videos</term> + <listitem> + <para> + A link to <ulink type="http" url="http://vimeo.com/channels/gatein">videos</ulink> related to the JBoss Enterprise Portal Platform is also included on the front page: + </para> + <mediaobject> + <imageobject role="html"> + <imagedata align="center" fileref="images/Common/Videos.png" format="PNG" scale="90" width="444" /> + </imageobject> + <imageobject role="fo"> + <imagedata align="center" contentwidth="130mm" fileref="images/Common/Videos.png" format="PNG" width="444" /> + </imageobject> + </mediaobject> + </listitem> + </varlistentry> + </variablelist> + </section> </chapter> Modified: epp/docs/branches/5.1/Reference_Guide/en-US/modules/WSRP.xml =================================================================== --- epp/docs/branches/5.1/Reference_Guide/en-US/modules/WSRP.xml 2011-07-26 04:48:07 UTC (rev 6928) +++ epp/docs/branches/5.1/Reference_Guide/en-US/modules/WSRP.xml 2011-07-26 05:04:46 UTC (rev 6929) @@ -4,70 +4,70 @@ %BOOK_ENTITIES; ]> <chapter id="chap-Reference_Guide-Web_Services_for_Remote_Portlets_WSRP"> - <title>Web Services for Remote Portlets (WSRP)</title> - <section id="sect-Reference_Guide-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> + <title>Web Services for Remote Portlets (WSRP)</title> + <section id="sect-Reference_Guide-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> + <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-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 5.1 includes implementations of WSRP 1.0 and 2.0. + + <section id="sect-Reference_Guide-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 5.1 includes implementations of WSRP 1.0 and 2.0. </para> <para> All optional features in WSRP 2 are implemented in JBoss Enterprise Portal Platform 5.1 except support for lifetimes and leasing support. </para> - </section> + </section> - - <section id="sect-Reference_Guide-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> + + <section id="sect-Reference_Guide-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> <title>Notations:</title> <varlistentry> @@ -106,50 +106,50 @@ </listitem> </varlistentry> </variablelist> - </note> + </note> - <variablelist id="vari-Reference_Guide-Deploying_WSRP-WSRP_support_files"> - <title>WSRP support files</title> - <varlistentry> + <variablelist id="vari-Reference_Guide-Deploying_WSRP-WSRP_support_files"> + <title>WSRP support files</title> + <varlistentry> <term><replaceable>WSRP_PATH</replaceable>/wsrp-admin-gui.war</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><replaceable>WSRP_PATH</replaceable>/wsrp-producer.war</term> - <listitem> - <para> - This file contains the WSRP producer web application. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><replaceable>WSRP_PATH</replaceable>/lib/wsrp-common-<replaceable>WSRP_VERSION</replaceable>.jar</term> - <listitem> - <para> - This file contains common classes needed by the different WSRP libraries. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><replaceable>WSRP_PATH</replaceable>/lib/wsrp-consumer-<replaceable>WSRP_VERSION</replaceable>.jar</term> - <listitem> - <para> - This file contains the WSRP consumer. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><replaceable>WSRP_PATH</replaceable>/lib/wsrp-integration-api-<replaceable>WSRP_VERSION</replaceable>.jar</term> - <listitem> - <para> - This file contains the API classes needed to integrate the WSRP component into portals. - </para> - </listitem> - </varlistentry> + <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><replaceable>WSRP_PATH</replaceable>/wsrp-producer.war</term> + <listitem> + <para> + This file contains the WSRP producer web application. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><replaceable>WSRP_PATH</replaceable>/lib/wsrp-common-<replaceable>WSRP_VERSION</replaceable>.jar</term> + <listitem> + <para> + This file contains common classes needed by the different WSRP libraries. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><replaceable>WSRP_PATH</replaceable>/lib/wsrp-consumer-<replaceable>WSRP_VERSION</replaceable>.jar</term> + <listitem> + <para> + This file contains the WSRP consumer. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><replaceable>WSRP_PATH</replaceable>/lib/wsrp-integration-api-<replaceable>WSRP_VERSION</replaceable>.jar</term> + <listitem> + <para> + This file contains the API classes needed to integrate the WSRP component into portals. + </para> + </listitem> + </varlistentry> <varlistentry> <term><replaceable>WSRP_PATH</replaceable>/lib/wsrp-producer-lib-$WSRP_VERSION.jar</term> <listitem> @@ -158,14 +158,14 @@ </para> </listitem> </varlistentry> - <varlistentry> - <term><replaceable>WSRP_PATH</replaceable>/lib/wsrp-wsrp1-ws-<replaceable>WSRP_VERSION</replaceable>.jar</term> - <listitem> - <para> - This file contains the generated JAX-WS classes for WSRP version 1. - </para> - </listitem> - </varlistentry> + <varlistentry> + <term><replaceable>WSRP_PATH</replaceable>/lib/wsrp-wsrp1-ws-<replaceable>WSRP_VERSION</replaceable>.jar</term> + <listitem> + <para> + This file contains the generated JAX-WS classes for WSRP version 1. + </para> + </listitem> + </varlistentry> <varlistentry> <term><replaceable>WSRP_PATH</replaceable>/lib/wsrp-wsrp2-ws-<replaceable>WSRP_VERSION</replaceable>.jar</term> <listitem> @@ -174,105 +174,105 @@ </para> </listitem> </varlistentry> - <varlistentry> - <term><replaceable>WSRP_PATH</replaceable>/lib/gatein.portal.component.wsrp-<replaceable>PORTAL_VERSION</replaceable>.jar</term> - <listitem> - <para> - This file contains the code to integrate the WSRP service into JBoss Enterprise Portal Platform. - </para> - </listitem> - </varlistentry> - </variablelist> + <varlistentry> + <term><replaceable>WSRP_PATH</replaceable>/lib/gatein.portal.component.wsrp-<replaceable>PORTAL_VERSION</replaceable>.jar</term> + <listitem> + <para> + This file contains the code to integrate the WSRP service into JBoss Enterprise Portal Platform. + </para> + </listitem> + </varlistentry> + </variablelist> - <section id="sect-Reference_Guide-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-Web_Services_for_Remote_Portlets_WSRP-Consuming_Remote_WSRP_Portlets" /> for directions on how to do this. - </para> - </section> + <section id="sect-Reference_Guide-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-Web_Services_for_Remote_Portlets_WSRP-Consuming_Remote_WSRP_Portlets" /> for directions on how to do this. + </para> + </section> - - <section id="sect-Reference_Guide-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-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-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> - + + <section id="sect-Reference_Guide-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> - + <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 <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>. - </para> - <para> - The <varname>NotRemotelyExposedPortlet</varname>, however, overrides the default behavior and is not remotely exposed. - </para> - <note> - <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> + <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 <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>. + </para> + <para> + The <varname>NotRemotelyExposedPortlet</varname>, however, overrides the default behavior and is not remotely exposed. + </para> + <note> + <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-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-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> + <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-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> + </para> <variablelist> <title>File paths:</title> <varlistentry> @@ -295,56 +295,56 @@ <para> The default hostname is <literal>localhost</literal> and the default port is <literal>8080</literal>. </para> - </section> + </section> - - <section id="sect-Reference_Guide-Web_Services_for_Remote_Portlets_WSRP-Consuming_Remote_WSRP_Portlets"> - <title>Consuming Remote WSRP Portlets</title> - <section id="sect-Reference_Guide-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 WSRP Producer descriptors. Alternatively, a portlet is provided to configure remote producers. - </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 id="sect-Reference_Guide-Web_Services_for_Remote_Portlets_WSRP-Consuming_Remote_WSRP_Portlets"> + <title>Consuming Remote WSRP Portlets</title> + <section id="sect-Reference_Guide-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 WSRP Producer descriptors. Alternatively, a portlet is provided to configure remote producers. + </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> + <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> - - <section id="sect-Reference_Guide-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">Oracle</emphasis>'s public WSRP producer. Firstly using the configuration portlet. 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> + + <section id="sect-Reference_Guide-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">Oracle</emphasis>'s public WSRP producer. Firstly using the configuration portlet. 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-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> + 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-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"></ulink>. @@ -495,133 +495,133 @@ </imageobject> </mediaobject> </section> - </section> + </section> - - <section id="sect-Reference_Guide-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 XML file located at <filename><replaceable>WSRP_PATH</replaceable>/lib/wsrp-consumer-<replaceable>WSRP_VERSION</replaceable>.jar/conf/wsrp-consumers-config.xml</filename>. - </para> - + + <section id="sect-Reference_Guide-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 XML file located at <filename><replaceable>WSRP_PATH</replaceable>/lib/wsrp-consumer-<replaceable>WSRP_VERSION</replaceable>.jar/conf/wsrp-consumers-config.xml</filename>. + </para> + <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> - <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> - </section> + <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> + <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> + </section> - <section id="sect-Reference_Guide-Configuring_a_Remote_Producer-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" /> - </imageobject> - <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/remote_portlets.png" format="PNG" /> - </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 id="sect-Reference_Guide-Configuring_a_Remote_Producer-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" /> + </imageobject> + <imageobject role="fo"> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/remote_portlets.png" format="PNG" /> + </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> - <section id="sect-Reference_Guide-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> - <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> - <note> - <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> - <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-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> - </note> - <section id="sect-Reference_Guide-Configuring_Access_to_Remote_Producers_via_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>&#60;wsrp-producer&#62;</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>&#60;endpoint-wsdl-url&#62;</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>&#60;endpoint-wsdl-url&#62;</literal> elements are required for a functional remote producer configuration. - </para> - </section> + <section id="sect-Reference_Guide-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> + <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> + <note> + <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> + <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-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> + </note> + <section id="sect-Reference_Guide-Configuring_Access_to_Remote_Producers_via_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>&#60;wsrp-producer&#62;</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>&#60;endpoint-wsdl-url&#62;</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>&#60;endpoint-wsdl-url&#62;</literal> elements are required for a functional remote producer configuration. + </para> + </section> - - <section id="sect-Reference_Guide-Configuring_Access_to_Remote_Producers_via_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-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>&#60;wsrp-producer&#62;</literal> element (in seconds). - </para> - <para> + + <section id="sect-Reference_Guide-Configuring_Access_to_Remote_Producers_via_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-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>&#60;wsrp-producer&#62;</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> + </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> @@ -633,247 +633,247 @@ </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>&#60;registration-data&#62;</literal> element. - </para> - <para> - If the remote producer does not require any registration properties, only an empty <literal>&#60;registration-data&#62;</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>&#60;property&#62;</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>&#60;consumer-name&#62;</literal> element. When providing a consumer name, please remember that it should uniquely identify your consumer. - </para> - </listitem> - </varlistentry> - </variablelist> - </section> + <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>&#60;registration-data&#62;</literal> element. + </para> + <para> + If the remote producer does not require any registration properties, only an empty <literal>&#60;registration-data&#62;</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>&#60;property&#62;</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>&#60;consumer-name&#62;</literal> element. When providing a consumer name, please remember that it should uniquely identify your consumer. + </para> + </listitem> + </varlistentry> + </variablelist> + </section> - </section> + </section> - - <section id="sect-Reference_Guide-Consuming_Remote_WSRP_Portlets-Examples"> - <title>Examples</title> - <para> + + <section id="sect-Reference_Guide-Consuming_Remote_WSRP_Portlets-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 five minutes and with a 30 second timeout for web service operations: - </para> - + </para> + <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> - + <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> + </section> - - <section id="sect-Reference_Guide-Web_Services_for_Remote_Portlets_WSRP-Consumers_Maintenance"> - <title>Consumers Maintenance</title> - <section id="sect-Reference_Guide-Consumers_Maintenance-Modifying_a_Currently_Held_Registration"> - <title>Modifying a Currently Held Registration</title> - <section id="sect-Reference_Guide-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-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" /> - </imageobject> - <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/modify_reg_start.png" format="PNG" /> - </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" /> - </imageobject> - <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/modify_reg_modify.png" format="PNG" /> - </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" /> - </imageobject> - <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/modify_reg_end.png" format="PNG" /> - </imageobject> - </mediaobject> - </step> - </procedure> - </section> + + <section id="sect-Reference_Guide-Web_Services_for_Remote_Portlets_WSRP-Consumers_Maintenance"> + <title>Consumers Maintenance</title> + <section id="sect-Reference_Guide-Consumers_Maintenance-Modifying_a_Currently_Held_Registration"> + <title>Modifying a Currently Held Registration</title> + <section id="sect-Reference_Guide-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-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" /> + </imageobject> + <imageobject role="fo"> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/modify_reg_start.png" format="PNG" /> + </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" /> + </imageobject> + <imageobject role="fo"> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/modify_reg_modify.png" format="PNG" /> + </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" /> + </imageobject> + <imageobject role="fo"> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/modify_reg_end.png" format="PNG" /> + </imageobject> + </mediaobject> + </step> + </procedure> + </section> - - <section id="sect-Reference_Guide-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" /> - </imageobject> - <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/config_self.png" format="PNG" /> - </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" /> - </imageobject> - <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/modify_reg_self.png" format="PNG" /> - </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" /> - </imageobject> - <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/modify_reg_self_end.png" format="PNG" /> - </imageobject> - </mediaobject> - <note> + + <section id="sect-Reference_Guide-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" /> + </imageobject> + <imageobject role="fo"> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/config_self.png" format="PNG" /> + </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" /> + </imageobject> + <imageobject role="fo"> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/modify_reg_self.png" format="PNG" /> + </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" /> + </imageobject> + <imageobject role="fo"> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/modify_reg_self_end.png" format="PNG" /> + </imageobject> + </mediaobject> + <note> <title><emphasis role="bold">JBoss Enterprise Portal Platform 5.1 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> + <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> - - <section id="sect-Reference_Guide-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" /> - </imageobject> - <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/consumer_operations.png" format="PNG" /> - </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> + + <section id="sect-Reference_Guide-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" /> + </imageobject> + <imageobject role="fo"> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/consumer_operations.png" format="PNG" /> + </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> <title><emphasis role="bold">Additional Functionalities in WSRP 2.0</emphasis></title> <para> @@ -1082,237 +1082,237 @@ </step> </procedure> </section> - </section> - - <section id="sect-Reference_Guide-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" /> - </imageobject> - <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/erase_registration.png" format="PNG" /> - </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" /> - </imageobject> - <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/erase_registration_warning.png" format="PNG" /> - </imageobject> - </mediaobject> - </warning> - </section> + </section> + + <section id="sect-Reference_Guide-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" /> + </imageobject> + <imageobject role="fo"> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/erase_registration.png" format="PNG" /> + </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" /> + </imageobject> + <imageobject role="fo"> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/erase_registration_warning.png" format="PNG" /> + </imageobject> + </mediaobject> + </warning> + </section> - </section> + </section> - - <section id="sect-Reference_Guide-Web_Services_for_Remote_Portlets_WSRP-Configuring_the_WSRP_Producer"> - <title>Configuring the WSRP Producer</title> - <section id="sect-Reference_Guide-Configuring_the_WSRP_Producer-Overview"> + + <section id="sect-Reference_Guide-Web_Services_for_Remote_Portlets_WSRP-Configuring_the_WSRP_Producer"> + <title>Configuring the WSRP Producer</title> + <section id="sect-Reference_Guide-Configuring_the_WSRP_Producer-Overview"> <title>Overview</title> - <para> + <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> + <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-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-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" /> - </imageobject> - <imageobject role="fo"> - <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/producer_default.png" format="PNG" /> - </imageobject> - </mediaobject> - <para> + </section> + + <section id="sect-Reference_Guide-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-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" /> + </imageobject> + <imageobject role="fo"> + <imagedata align="center" contentwidth="140mm" fileref="images/WSRP/producer_default.png" format="PNG" /> + </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> <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> - - <section id="sect-Reference_Guide-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" /> - </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" /> - </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-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" /> - </imageobject> - </mediaobject> - </step> - <step> - <para> - Press "Save" to record the modifications. - </para> - </step> - </procedure> - - <note> - <para> + + <section id="sect-Reference_Guide-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" /> + </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" /> + </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-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" /> + </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-Modifying_a_Currently_Held_Registration-Registration_Modification_on_Producer_Error" />. - </para> - </note> - <section id="sect-Reference_Guide-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> + </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-Modifying_a_Currently_Held_Registration-Registration_Modification_on_Producer_Error" />. + </para> + </note> + <section id="sect-Reference_Guide-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> + <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> + </para> + </note> + </section> - </section> + </section> - - <section id="sect-Reference_Guide-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. + + <section id="sect-Reference_Guide-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> + </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-Web_Services_for_Remote_Portlets_WSRP-Removing_WSRP"> - <title>Removing WSRP</title> - <para> + <title><remark>Removing WSRP</remark></title> + <para> If you are not going to use WSRP in your JBoss Enterprise Portal Platform instance, your installation will not be adversely affected should you leave the WSRP files in place. </para> <para> @@ -1322,7 +1322,7 @@ <title></title> <step> <para> - Navigate to the <filename><replaceable>JBOSS_HOME</replaceable>/jboss-as/server/<replaceable>&lt;PROFILE&gt;</replaceable>/conf/gatein/</filename> directory of your JBoss Enterprise Portal Platform instance. + 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>