Author: smumford
Date: 2011-11-24 19:43:12 -0500 (Thu, 24 Nov 2011)
New Revision: 8139
Added:
epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/RH-WSRP.xml
Modified:
epp/docs/branches/5.2/Admin_Guide/en-US/Admin_Guide.ent
epp/docs/branches/5.2/Admin_Guide/en-US/Book_Info.xml
epp/docs/branches/5.2/Admin_Guide/en-US/chapter-1-Introduction.xml
epp/docs/branches/5.2/Admin_Guide/en-US/chapter-2-REST.xml
epp/docs/branches/5.2/Admin_Guide/en-US/chapter-4-Management_Extensions.xml
epp/docs/branches/5.2/Developer_Guide/en-US/Book_Info.xml
epp/docs/branches/5.2/Developer_Guide/en-US/Preface.xml
epp/docs/branches/5.2/Developer_Guide/en-US/Revision_History.xml
epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/Author_Group.xml
epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/Book_Info.xml
epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/Revision_History.xml
epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/images/WSRP/config_self.png
epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/images/WSRP/modify_reg_end.png
epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/images/WSRP/modify_reg_self_end.png
epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/Foundations/Configuring_Services.xml
epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/AuthenticationAndIdentity/SSO.xml
epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/WSRP.xml
Log:
WSRP ports. Admin/Dev Guide updates
Modified: epp/docs/branches/5.2/Admin_Guide/en-US/Admin_Guide.ent
===================================================================
--- epp/docs/branches/5.2/Admin_Guide/en-US/Admin_Guide.ent 2011-11-24 17:26:22 UTC (rev
8138)
+++ epp/docs/branches/5.2/Admin_Guide/en-US/Admin_Guide.ent 2011-11-25 00:43:12 UTC (rev
8139)
@@ -7,7 +7,7 @@
<!-- Bugzilla Specifics -->
<!ENTITY BZPRODUCT "JBoss Enterprise Portal Platform 5">
<!ENTITY BZCOMPONENT "docs-Admin_Guide">
-<!ENTITY BZURL "<ulink
url='https://bugzilla.redhat.com/enter_bug.cgi?product=JBoss&perc...
+<!ENTITY BZURL "<ulink
url='https://bugzilla.redhat.com/enter_bug.cgi?product=JBoss&perc...
<!-- Corporate Specifics: -->
<!ENTITY YEAR "2011">
Modified: epp/docs/branches/5.2/Admin_Guide/en-US/Book_Info.xml
===================================================================
--- epp/docs/branches/5.2/Admin_Guide/en-US/Book_Info.xml 2011-11-24 17:26:22 UTC (rev
8138)
+++ epp/docs/branches/5.2/Admin_Guide/en-US/Book_Info.xml 2011-11-25 00:43:12 UTC (rev
8139)
@@ -4,7 +4,7 @@
%BOOK_ENTITIES;
]>
<bookinfo id="book-Admin_Guide-Admin_Guide">
- <title>Admin Guide</title>
+ <title>Administration Guide</title>
<subtitle>For use with JBoss Enterprise Portal Platform 5</subtitle>
<productname>JBoss Enterprise Portal Platform</productname>
<productnumber>5.2</productnumber>
Modified: epp/docs/branches/5.2/Admin_Guide/en-US/chapter-1-Introduction.xml
===================================================================
--- epp/docs/branches/5.2/Admin_Guide/en-US/chapter-1-Introduction.xml 2011-11-24 17:26:22
UTC (rev 8138)
+++ epp/docs/branches/5.2/Admin_Guide/en-US/chapter-1-Introduction.xml 2011-11-25 00:43:12
UTC (rev 8139)
@@ -154,7 +154,7 @@
</entry>
<entry>
<para>
- The read-resource operation is responsible for reading the managed
resource; describing itself and listing any operations and/or sub-resources it may
contain.
+ The read-resource operation is responsible for reading the managed
resource; describing itself and listing any operations and/or sub-resources it may
contain.
This is the primary operation to obtain information about a managed
component and it's managed resources.
</para>
Modified: epp/docs/branches/5.2/Admin_Guide/en-US/chapter-2-REST.xml
===================================================================
--- epp/docs/branches/5.2/Admin_Guide/en-US/chapter-2-REST.xml 2011-11-24 17:26:22 UTC
(rev 8138)
+++ epp/docs/branches/5.2/Admin_Guide/en-US/chapter-2-REST.xml 2011-11-25 00:43:12 UTC
(rev 8139)
@@ -260,7 +260,7 @@
<para>Management attributes (which are part of a management request) are
mapped by including all request parameters of the HTTP request as attributes. So if an
operation supports certain attributes, query parameters can be added to the request URL to
be used as attributes of the management request.</para>
<example>
<title>Attributes first-name and last-name as request
parameters</title>
-
<programlisting><![CDATA[http://localhost:8080/rest/private/managed-components/foo/bar?first-name=john&last-name=doe]]></programlisting>
+
<programlisting>http://localhost:8080/rest/private/managed-components/foo/bar?first-name=john&last-name=doe</programlisting>
</example>
<section id="sid-8094332_GateInManagement-MultivalueAttributes">
@@ -268,7 +268,7 @@
<para>Management attributes can be multi-valued (meaning more then one
value associated with an attribute). This is easy as HTTP query parameters can be
multi-valued as well.</para>
<example>
<title>Multi-valued attribute colors as request parameters</title>
-
<programlisting><![CDATA[http://localhost:8080/rest/private/managed-components/foo/bar?colors=red&colors=green&colors=blue]]></programlisting>
+
<programlisting>http://localhost:8080/rest/private/managed-components/foo/bar?colors=red&colors=green&colors=blue</programlisting>
</example>
</section>
</section>
@@ -428,7 +428,7 @@
</section>
<section id="sid-8094332_GateInManagement-readresource">
- <title>read-resource</title>
+ <title>resource</title>
<para>
Since the
<code>read-resource</code>
Modified: epp/docs/branches/5.2/Admin_Guide/en-US/chapter-4-Management_Extensions.xml
===================================================================
--- epp/docs/branches/5.2/Admin_Guide/en-US/chapter-4-Management_Extensions.xml 2011-11-24
17:26:22 UTC (rev 8138)
+++ epp/docs/branches/5.2/Admin_Guide/en-US/chapter-4-Management_Extensions.xml 2011-11-25
00:43:12 UTC (rev 8139)
@@ -13,257 +13,261 @@
<title>MOP Management Extension</title>
<para>The MOP management extension registers the 'mop' managed
component which is responsible for managing pages, navigation, and site layout. It
primarily supports exporting and importing this data through the export-resource and
import-resource operations. It also supports the read-config-as-xml operation to expose
the portal meta data as xml.</para>
- </section>
- <section id="sid-8094332_GateInManagement-Operationsxx">
-
- <title>Operations</title>
- <section id="sid-8094332_GateInManagement-readconfigasxml">
+ <section id="sid-8094332_GateInManagement-Operationsxx">
- <title>read-config-as-xml</title>
+ <title>Operations</title>
<para>
- The
- <code>read-config-as-xml</code>
- operation can only be executed on the site layout, pages, and navigation
managed resources. The xml format returned is that of which is defined in by the
- <ulink
url="http://www.gatein.org/xml/ns/">gatein-objects</ulink...
- xsd. This means that these resources are exposed in the same format as what a
portal extension would accept for importing data into the portal.
+
</para>
+ <section id="sid-8094332_GateInManagement-readconfigasxml">
+
+ <title>config-as-xml</title>
+ <para>
+ The
+ <code>read-config-as-xml</code>
+ operation can only be executed on the site layout, pages, and navigation
managed resources. The xml format returned is that of which is defined in by the
+ <ulink
url="http://www.gatein.org/xml/ns/">gatein-objects</ulink...
+ xsd. This means that these resources are exposed in the same format as that
which a portal extension would accept for importing data into the portal.
+ </para>
+ </section>
+ <section id="sid-8094332_GateInManagement-exportresource">
+
+ <title>export-resource</title>
+ <para>
+ The
+ <code>export-resource</code>
+ operation can be executed on any resource of the MOP extension (including the
mop component itself). Since the management system recursively searches for all
sub-resources that have export-resource defined (which they are defined at the site
layout, page, and navigation level), exports can be very granular.
+ </para>
+ </section>
+ <section id="sid-8094332_GateInManagement-importresource">
+
+ <title>import-resource</title>
+ <para>
+ The
+ <code>import-resource</code>
+ operation can only be executed at the mop component (root managed resource of
the mop extension). This is because the exported zip file contains the path information
(like site type and site name). So executing an
+ <code>import-resource</code>
+ operation on a group site, when the zip contains data from a portal site,
doesn't make sense.
+ </para>
+ <para>
+ The MOP
+ <code>import-resource</code>
+ operation defines the
+ <code>importMode</code>
+ attribute as follows during import.
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>
+ <para>
+ Mode
+
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Description
+
+ </para>
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <para>
+ conserve
+
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Import data only if no artifacts exist for that site. For example
if one page exists for site 'classic', nothing will be imported.
+
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ insert
+
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Import data when data does not exist, otherwise do nothing.
+
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ merge
+
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Import when data does not exist, update data when it does exist.
+
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ overwrite
+
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Delete all data for that artifact of the site, import new data. For
example if the zip file only contains pages for site classic, then
+
+ all pages for that site are deleted and imported.
+
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ <note>
+ <title>Note</title>
+ <para>'merge' is the default importMode.</para>
+ </note>
+ </section>
</section>
- <section id="sid-8094332_GateInManagement-exportresource">
+ <section id="sid-8094332_GateInManagement-PathTemplatesx">
- <title>export-resource</title>
- <para>
- The
- <code>export-resource</code>
- operation can be executed on any resource of the MOP extension (including the
mop component itself). Since the management system recursively searches for all
sub-resources that have export-resource defined (which they are defined at the site
layout, page, and navigation level), exports can be very granular.
- </para>
+ <title>Path Templates</title>
+ <para>Below are the list of path template variables defined in the MOP
management extension. These path template variables are used for filtering during
export.</para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <code>site-type</code>
+
+ These are the site types of the portal to include or exclude. Available
values are:
+ <code>portal</code>
+ ,
+ <code>group</code>
+ , and
+ <code>user</code>
+ .
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <code>site-name</code>
+
+ The sites to include or exclude. Examples could be
+ <code>classic</code>
+ and
+ <code>/platform/administrators</code>
+ .
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <code>site-layout</code>
+
+ The name of the site layout depending on the site type. Available values
are:
+ <code>portal</code>
+ ,
+ <code>group</code>
+ ,
+ <code>user</code>
+ .
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <code>page-name</code>
+
+ The name of the page(s) to include or exclude.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <code>nav-uri</code>
+
+ The URI of the navigation node to include or exclude.
+ </para>
+ </listitem>
+ </itemizedlist>
</section>
- <section id="sid-8094332_GateInManagement-importresource">
+ <section id="sid-8094332_GateInManagement-RESTAPI">
- <title>import-resource</title>
- <para>
- The
- <code>import-resource</code>
- operation can only be executed at the mop component (root managed resource of
the mop extension). This is because the exported zip file contains the path information
(like site type and site name). So executing an
- <code>import-resource</code>
- operation on a group site, when the zip contains data from a portal site,
doesn't make sense.
- </para>
- <para>
- The MOP
- <code>import-resource</code>
- operation defines the
- <code>importMode</code>
- attribute as follows during import.
- </para>
- <informaltable>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>
- <para>
- Mode
-
- </para>
- </entry>
- <entry>
- <para>
- Description
-
- </para>
- </entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <para>
- conserve
-
- </para>
- </entry>
- <entry>
- <para>
- Import data only if no artifacts exist for that site. For example if
one page exists for site 'classic', nothing will be imported.
-
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- insert
-
- </para>
- </entry>
- <entry>
- <para>
- Import data when data does not exist, otherwise do nothing.
-
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- merge
-
- </para>
- </entry>
- <entry>
- <para>
- Import when data does not exist, update data when it does exist.
-
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- overwrite
-
- </para>
- </entry>
- <entry>
- <para>
- Delete all data for that artifact of the site, import new data. For
example if the zip file only contains pages for site classic, then
-
- all pages for that site are deleted and imported.
-
- </para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
+ <title>REST API</title>
<note>
<title>Note</title>
- <para>'merge' is the default importMode.</para>
+ <para>All URL's below are relative to the REST management entry point
of the portal container.</para>
</note>
- </section>
- </section>
- <section id="sid-8094332_GateInManagement-PathTemplatesx">
-
- <title>Path Templates</title>
- <para>Below are the list of path template variables defined in the MOP
management extension. These path template variables are used for filtering during
export.</para>
- <itemizedlist>
- <listitem>
+ <note>
+ <title>Note</title>
<para>
- <code>site-type</code>
-
- These are the site types of the portal to include or exclude. Available
values are:
- <code>portal</code>
- ,
- <code>group</code>
- , and
- <code>user</code>
- .
+ For all read-config-as-xml refer
+ <ulink
url="http://www.gatein.org/xml/ns/gatein_objects_1_2"/>
+ for the format of the XML.
</para>
- </listitem>
- <listitem>
+ </note>
+ <section id="sid-8094332_GateInManagement-MOPComponentResource">
+
+ <title>MOP Component Resource</title>
<para>
- <code>site-name</code>
-
- The sites to include or exclude. Examples could be
- <code>classic</code>
- and
- <code>/platform/administrators</code>
- .
+ The mop managed component resource (root managed resource) is the only
resource that accepts the
+ <code>import-resource</code>
+ operation.
</para>
- </listitem>
- <listitem>
- <para>
- <code>site-layout</code>
-
- The name of the site layout depending on the site type. Available values
are:
- <code>portal</code>
- ,
- <code>group</code>
- ,
- <code>user</code>
- .
- </para>
- </listitem>
- <listitem>
- <para>
- <code>page-name</code>
-
- The name of the page(s) to include or exclude.
- </para>
- </listitem>
- <listitem>
- <para>
- <code>nav-uri</code>
-
- The URI of the navigation node to include or exclude.
- </para>
- </listitem>
- </itemizedlist>
- </section>
- <section id="sid-8094332_GateInManagement-RESTAPI">
-
- <title>REST API</title>
- <note>
- <title>Note</title>
- <para>All URL's below are relative to the REST management entry point
of the portal container.</para>
- </note>
- <note>
- <title>Note</title>
- <para>
- For all read-config-as-xml refer
- <ulink
url="http://www.gatein.org/xml/ns/gatein_objects_1_2"/>
- for the format of the XML.
- </para>
- </note>
- <section id="sid-8094332_GateInManagement-MOPComponentResource">
-
- <title>MOP Component Resource</title>
- <para>
- The mop managed component resource (root managed resource) is the only resource
that accepts the
- <code>import-resource</code>
- operation.
- </para>
- <example>
- <title>HTTP Request</title>
- <programlisting>PUT /mop
+ <example>
+ <title>HTTP Request</title>
+ <programlisting>PUT /mop
Headers:
Content-Type: application/zip</programlisting>
- </example>
- <example>
- <title>HTTP Response</title>
- <programlisting>HTTP/1.1 200 OK</programlisting>
- </example>
- </section>
- <section id="sid-8094332_GateInManagement-SiteLayoutResource">
-
- <title>Site Layout Resource</title>
- <para>
- The site layout resource represents the site layout of the portal. It's the
data defined in the
- <emphasis role="strong">portal.xml</emphasis>
- ,
- <emphasis role="strong">group.xml</emphasis>
- , and
- <emphasis role="strong">user.xml</emphasis>
- files (depending on site type) used in portal extensions to configure data.
- </para>
- <example>
- <title>URL</title>
- <programlisting>URL:
/mop/{site-type}sites/{site-name}/{site-layout}</programlisting>
- </example>
- <section id="sid-8094332_GateInManagement-readconfigasxmlx">
+ </example>
+ <example>
+ <title>HTTP Response</title>
+ <programlisting>HTTP/1.1 200 OK</programlisting>
+ </example>
+ </section>
+
+ </section>
+ <section id="sid-8094332_GateInManagement-SiteLayoutResource">
- <title>read-config-as-xml</title>
- <para>Example of reading the site layout as xml for site
classic.</para>
+ <title>Site Layout Resource</title>
+ <para>
+ The site layout resource represents the site layout of the portal. It's
the data defined in the
+ <emphasis role="strong">portal.xml</emphasis>
+ ,
+ <emphasis role="strong">group.xml</emphasis>
+ , and
+ <emphasis role="strong">user.xml</emphasis>
+ files (depending on site type) used in portal extensions to configure data.
+ </para>
<example>
- <title>HTTP Request</title>
- <programlisting>GET /mop/portalsites/classic/portal.xml
+ <title>URL</title>
+ <programlisting>URL:
/mop/{site-type}sites/{site-name}/{site-layout}</programlisting>
+ </example>
+ <section id="sid-8094332_GateInManagement-readconfigasxmlx">
+
+ <title>config-as-xml</title>
+ <para>Example of reading the site layout as xml for site
classic.</para>
+ <example>
+ <title>HTTP Request</title>
+ <programlisting>GET /mop/portalsites/classic/portal.xml
or
GET /mop/portalsites/classic/portal?op=read-config-as-xml</programlisting>
- </example>
- <example>
- <title>HTTP Response</title>
- <programlisting>HTTP/1.1 200 OK
+ </example>
+ <example>
+ <title>HTTP Response</title>
+ <programlisting>HTTP/1.1 200 OK
Content-Type: application/xml
<portal-config>
@@ -273,52 +277,53 @@
<locale>en</locale>
...
</portal-config></programlisting>
- </example>
- </section>
- <section id="sid-8094332_GateInManagement-exportresourcex">
-
- <title>export-resource</title>
- <para>Example of exporting the site layout for site
classic.</para>
- <example>
- <title>HTTP Request</title>
- <programlisting>GET /mop/portalsites/classic/portal.zip
+ </example>
+ </section>
+ <section id="sid-8094332_GateInManagement-exportresourcex">
+
+ <title>export-resource</title>
+ <para>Example of exporting the site layout for site
classic.</para>
+ <example>
+ <title>HTTP Request</title>
+ <programlisting>GET /mop/portalsites/classic/portal.zip
or
GET /mop/portalsites/classic/portal?op=export-resource</programlisting>
- </example>
- <example>
- <title>HTTP Response</title>
- <programlisting>HTTP/1.1 200 OK
+ </example>
+ <example>
+ <title>HTTP Response</title>
+ <programlisting>HTTP/1.1 200 OK
Content-Type: application/zip
[binary data]</programlisting>
- </example>
+ </example>
+ </section>
</section>
- </section>
- <section id="sid-8094332_GateInManagement-PagesResource">
-
- <title>Pages Resource</title>
- <para>The pages resource represents the pages of the portal. It's the
data defined in the pages.xml used in portal extensions to configure data.</para>
- <example>
- <title>URL</title>
- <programlisting>URL:
/mop/{site-type}sites/{site-name}/pages/{page-name}</programlisting>
- </example>
- <section id="sid-8094332_GateInManagement-readconfigasxmlxx">
+
+ <section id="sid-8094332_GateInManagement-PagesResource">
- <title>config-as-xml</title>
- <para>Example of reading all pages as xml for site classic.</para>
+ <title>Pages Resource</title>
+ <para>The pages resource represents the pages of the portal. It's the
data defined in the pages.xml used in portal extensions to configure data.</para>
<example>
- <title>HTTP Request</title>
- <programlisting>GET /mop/portalsites/classic/pages.xml
+ <title>URL</title>
+ <programlisting>URL:
/mop/{site-type}sites/{site-name}/pages/{page-name}</programlisting>
+ </example>
+ <section id="sid-8094332_GateInManagement-readconfigasxmlxx">
+
+ <title>config-as-xml</title>
+ <para>Example of reading all pages as xml for site
classic.</para>
+ <example>
+ <title>HTTP Request</title>
+ <programlisting>GET /mop/portalsites/classic/pages.xml
or
GET /mop/portalsites/classic/pages?op=read-config-as-xml</programlisting>
- </example>
- <example>
- <title>HTTP Response</title>
- <programlisting>HTTP/1.1 200 OK
+ </example>
+ <example>
+ <title>HTTP Response</title>
+ <programlisting>HTTP/1.1 200 OK
Content-Type: application/xml
<page-set>
@@ -331,19 +336,19 @@
<portlet-application>
...
</page-set></programlisting>
- </example>
- <para>Example of reading the homepage as xml for site
classic.</para>
- <example>
- <title>HTTP Request</title>
- <programlisting>GET /mop/portalsites/classic/pages/homepage.xml
+ </example>
+ <para>Example of reading the homepage as xml for site
classic.</para>
+ <example>
+ <title>HTTP Request</title>
+ <programlisting>GET /mop/portalsites/classic/pages/homepage.xml
or
GET /mop/portalsites/classic/pages/homepage?op=read-config-as-xml</programlisting>
- </example>
- <example>
- <title>HTTP Response</title>
- <programlisting>HTTP/1.1 200 OK
+ </example>
+ <example>
+ <title>HTTP Response</title>
+ <programlisting>HTTP/1.1 200 OK
Content-Type: application/xml
<page-set>
@@ -356,53 +361,53 @@
<portlet-application>
...
</page-set></programlisting>
- </example>
- </section>
- <section id="sid-8094332_GateInManagement-exportresourcexx">
-
- <title>export-resource</title>
- <para>Example of exporting all pages of site classic.</para>
- <example>
- <title>HTTP Request</title>
- <programlisting>GET /mop/portalsites/classic/pages.zip
+ </example>
+ </section>
+ <section id="sid-8094332_GateInManagement-exportresourcexx">
+
+ <title>export-resource</title>
+ <para>Example of exporting all pages of site classic.</para>
+ <example>
+ <title>HTTP Request</title>
+ <programlisting>GET /mop/portalsites/classic/pages.zip
or
GET /mop/portalsites/classic/pages?op=export-resource</programlisting>
- </example>
- <example>
- <title>HTTP Response</title>
- <programlisting>HTTP/1.1 200 OK
+ </example>
+ <example>
+ <title>HTTP Response</title>
+ <programlisting>HTTP/1.1 200 OK
Content-Type: application/zip
[binary data]</programlisting>
- </example>
+ </example>
+ </section>
</section>
- </section>
- <section id="sid-8094332_GateInManagement-NavigationResource">
- <title>Navigation Resource</title>
- <para>The navigation resource represents the navigation of the portal.
It's the data defined in the navigation.xml used in portal extensions to configure
data.</para>
- <example>
- <title>URL</title>
- <programlisting><![CDATA[
- URL:
/mop/{site-type}sites/{site-name}/navigation/{nav-uri}]]></programlisting>
- </example>
- <section id="sid-8094332_GateInManagement-readconfigasxmlxxx">
+ <section id="sid-8094332_GateInManagement-NavigationResource">
- <title>read-config-as-xml</title>
- <para>Example of reading all navigation as xml for site
classic.</para>
+ <title>Navigation Resource</title>
+ <para>The navigation resource represents the navigation of the portal.
It's the data defined in the navigation.xml used in portal extensions to configure
data.</para>
<example>
- <title>HTTP Request</title>
- <programlisting>GET /mop/portalsites/classic/navigation.xml
+ <title>URL</title>
+ <programlisting>URL:
/mop/{site-type}sites/{site-name}/navigation/{nav-uri}</programlisting>
+ </example>
+ <section id="sid-8094332_GateInManagement-readconfigasxmlxxx">
+
+ <title>config-as-xml</title>
+ <para>Example of reading all navigation as xml for site
classic.</para>
+ <example>
+ <title>HTTP Request</title>
+ <programlisting>GET /mop/portalsites/classic/navigation.xml
or
GET /mop/portalsites/classic/navigation?op=read-config-as-xml</programlisting>
- </example>
- <example>
- <title>HTTP Response</title>
- <programlisting>HTTP/1.1 200 OK
+ </example>
+ <example>
+ <title>HTTP Response</title>
+ <programlisting>HTTP/1.1 200 OK
Content-Type: application/xml
<node-navigation>
@@ -419,19 +424,19 @@
<name>sitemap</name>
...
</node-navigation></programlisting>
- </example>
- <para>Example of reading the home node as xml for site
classic.</para>
- <example>
- <title>HTTP Request</title>
- <programlisting>GET /mop/portalsites/classic/navigation/home.xml
+ </example>
+ <para>Example of reading the home node as xml for site
classic.</para>
+ <example>
+ <title>HTTP Request</title>
+ <programlisting>GET /mop/portalsites/classic/navigation/home.xml
or
GET
/mop/portalsites/classic/navigation/home?op=read-config-as-xml</programlisting>
- </example>
- <example>
- <title>HTTP Response</title>
- <programlisting>HTTP/1.1 200 OK
+ </example>
+ <example>
+ <title>HTTP Response</title>
+ <programlisting>HTTP/1.1 200 OK
Content-Type: application/xml
<node-navigation>
@@ -447,113 +452,113 @@
</node>
</page-nodes>
</node-navigation></programlisting>
- </example>
- </section>
- <section
id="sid-8094332_GateInManagement-exportresource_Example">
-
- <title>export-resource Example</title>
- <para>Example of exporting all navigation of site classic.</para>
- <example>
- <title>HTTP Request</title>
- <programlisting>GET /mop/portalsites/classic/navigation.zip
+ </example>
+ </section>
+ <section id="sid-8094332_GateInManagement-exportresourcexxx">
+
+ <title>export-resource</title>
+ <para>Example of exporting all navigation of site
classic.</para>
+ <example>
+ <title>HTTP Request</title>
+ <programlisting>GET /mop/portalsites/classic/navigation.zip
or
GET /mop/portalsites/classic/navigation?op=export-resource</programlisting>
- </example>
- <example>
- <title>HTTP Response</title>
- <programlisting>HTTP/1.1 200 OK
+ </example>
+ <example>
+ <title>HTTP Response</title>
+ <programlisting>HTTP/1.1 200 OK
Content-Type: application/zip
[binary data]</programlisting>
+ </example>
+ </section>
+ </section>
+ <section id="sid-8094332_GateInManagement-ExportandFiltering">
+
+ <title>Export and Filtering</title>
+ <para>
+ Filtering is activated when the
+ <code>filter</code>
+ attribute is passed to an
+ <code>export-resource</code>
+ operation. The filter attribute is a multi-value attribute that is passed as
request parameters of the HTTP request.
+ </para>
+ <note>
+ <title>Note</title>
+ <para>You can either include multiple filter parameters
(?filter=foo:bar&filter=baz:foo-bar) or separate via ';' character
(?filter=foo:bar;baz:foo-bar)</para>
+ </note>
+ <example>
+ <title>Export only registry and pageManagement navigation
nodes</title>
+ <programlisting>GET
/mop/groupsites/platform/administrators/navigation.zip?filter=nav-uri:/administration/registry,/administration/pageManagement</programlisting>
</example>
- </section>
+ <example>
+ <title>Export all site types but user and group</title>
+ <programlisting>GET
/mop.zip?filter=site-type:!user,group</programlisting>
+ </example>
</section>
- <section id="sid-8094332_GateInManagement-ExportandFiltering-1">
+ <section id="sid-8094332_GateInManagement-CommandLineInterfacex">
- <title>Export and Filtering</title>
- <para>
- Filtering is activated when the
- <code>filter</code>
- attribute is passed to an
- <code>export-resource</code>
- operation. The filter attribute is a multi-value attribute that is passed as
request parameters of the HTTP request.
- </para>
- <note>
- <title>Note</title>
- <para>You can either include multiple filter parameters
(?filter=foo:bar&filter=baz:foo-bar) or separate via ';' character
(?filter=foo:bar;baz:foo-bar)</para>
- </note>
- <example>
- <title>Export only registry and pageManagement navigation
nodes</title>
- <programlisting>GET
/mop/groupsites/platform/administrators/navigation.zip?filter=nav-uri:/administration/registry,/administration/pageManagement</programlisting>
- </example>
- <example>
- <title>Export all site types but user and group</title>
- <programlisting>GET
/mop.zip?filter=site-type:!user,group</programlisting>
- </example>
- </section>
- </section>
- <section id="sid-8094332_GateInManagement-CommandLineInterfacex">
-
- <title>Command Line Interface</title>
- <para>The commands included in the management component provide us the tools
to perform management operations on these MOP artifacts: site layout, pages, and
navigation.</para>
- <section id="sid-8094332_GateInManagement-ResourcePaths">
-
- <title>Resource Paths</title>
- <para>The paths of the MOP resources are exactly the same as the REST
URL's (of course without the URL syntax). For example the path of the homepage for the
classic site would be:</para>
- <example>
- <title>Example</title>
- <programlisting>[ /]% cd /mop/portalsites/classic/pages/homepage
+ <title>Command Line Interface</title>
+ <para>The commands included in the management component provide us the
tools to perform management operations on these MOP artifacts: site layout, pages, and
navigation.</para>
+ <section id="sid-8094332_GateInManagement-ResourcePaths">
+
+ <title>Resource Paths</title>
+ <para>The paths of the MOP resources are exactly the same as the REST
URL's (of course without the URL syntax). For example the path of the homepage for the
classic site would be:</para>
+ <example>
+ <title>Example</title>
+ <programlisting>[ /]% cd /mop/portalsites/classic/pages/homepage
[homepage]% pwd
/mop/portalsites/classic/pages/homepage</programlisting>
- </example>
- <note>
- <title>Note</title>
- <para>All resources/paths can be autocompleted by hitting the tab
key.</para>
- </note>
+ </example>
+ <note>
+ <title>Note</title>
+ <para>All resources/paths can be autocompleted by hitting the tab
key.</para>
+ </note>
+ </section>
+ <section id="sid-8094332_GateInManagement-ExportandFilteringx">
+
+ <title>Export and Filtering</title>
+ <para>
+ Filtering is activated when the
+ <code>filter</code>
+ attribute is passed to an
+ <code>export-resource</code>
+ operation. The filter attribute is a multi-value attribute that is passed to
the CLI using the
+ <code>--filter</code>
+ attribute for the
+ <code>export</code>
+ command.
+ </para>
+ <example>
+ <title>Export all portal site types</title>
+ <programlisting>export --file /tmp/mop.zip --filter site-type:portal
/mop</programlisting>
+ </example>
+ <example>
+ <title>Export all sites types but user</title>
+ <programlisting>export --file /tmp/mop.zip --filter site-type:!user
/mop</programlisting>
+ </example>
+ <para>The option can be specified multiple times for multiple
values.</para>
+ <example>
+ <title>Export only the /platform/administrators group
site</title>
+ <programlisting>export --file /tmp/mop.zip --filter site-type:group
--filter site-name:/platform/administrators /mop</programlisting>
+ </example>
+ <para>
+ Also as discussed in the Path Templates section in this document, the filter
attribute can separate different path templates by the
+ <code>;</code>
+ character.
+ </para>
+ <example>
+ <title>Export only pages named homepage, navigation named home for site
classic</title>
+ <programlisting>export --file /tmp/classic.zip --filter
page-name:homepage;nav-uri:home /mop/portalsites/classic</programlisting>
+ </example>
+ <important>
+ <title>Important</title>
+ <para>All three artifacts (site layout, navigation, and pages) are
included in export by default. In other words if you don't specify their path template
in the filter, the data will be included.</para>
+ </important>
+ </section>
</section>
- <section id="sid-8094332_GateInManagement-ExportandFiltering-2">
-
- <title>Export and Filtering</title>
- <para>
- Filtering is activated when the
- <code>filter</code>
- attribute is passed to an
- <code>export-resource</code>
- operation. The filter attribute is a multi-value attribute that is passed to
the CLI using the
- <code>--filter</code>
- attribute for the
- <code>export</code>
- command.
- </para>
- <example>
- <title>Export all portal site types</title>
- <programlisting>export --file /tmp/mop.zip --filter site-type:portal
/mop</programlisting>
- </example>
- <example>
- <title>Export all sites types but user</title>
- <programlisting>export --file /tmp/mop.zip --filter site-type:!user
/mop</programlisting>
- </example>
- <para>The option can be specified multiple times for multiple
values.</para>
- <example>
- <title>Export only the /platform/administrators group site</title>
- <programlisting>export --file /tmp/mop.zip --filter site-type:group
--filter site-name:/platform/administrators /mop</programlisting>
- </example>
- <para>
- Also as discussed in the Path Templates section in this document, the filter
attribute can separate different path templates by the
- <code>;</code>
- character.
- </para>
- <example>
- <title>Export only pages named homepage, navigation named home for site
classic</title>
- <programlisting>export --file /tmp/classic.zip --filter
page-name:homepage;nav-uri:home /mop/portalsites/classic</programlisting>
- </example>
- <important>
- <title>Important</title>
- <para>All three artifacts (site layout, navigation, and pages) are
included in export by default. In other words if you don't specify their path template
in the filter, the data will be included.</para>
- </important>
- </section>
</section>
</chapter>
Modified: epp/docs/branches/5.2/Developer_Guide/en-US/Book_Info.xml
===================================================================
--- epp/docs/branches/5.2/Developer_Guide/en-US/Book_Info.xml 2011-11-24 17:26:22 UTC (rev
8138)
+++ epp/docs/branches/5.2/Developer_Guide/en-US/Book_Info.xml 2011-11-25 00:43:12 UTC (rev
8139)
@@ -1,23 +1,12 @@
-<?xml version='1.0' encoding='utf-8' ?>
-<!DOCTYPE bookinfo PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-<!ENTITY % BOOK_ENTITIES SYSTEM "Developer_Guide.ent">
-%BOOK_ENTITIES;
-<!ENTITY % BOOK_ENTITIES SYSTEM "Developer_Guide.ent">
-%BOOK_ENTITIES;
-<!ENTITY % BOOK_ENTITIES SYSTEM ".ent">
-%BOOK_ENTITIES;
-<!ENTITY % BOOK_ENTITIES SYSTEM "Developer_Guide.ent">
-%BOOK_ENTITIES;
-<!ENTITY % BOOK_ENTITIES SYSTEM "Developer_Guide.ent">
-%BOOK_ENTITIES;
-]>
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<bookinfo id="book-Developer_Guide-Developer_Guide">
<title>Developer Guide</title>
<subtitle>For use with JBoss Enterprise Portal Platform 5</subtitle>
<productname>JBoss Enterprise Portal Platform</productname>
<productnumber>5.2</productnumber>
<edition>5.2.0</edition>
- <pubsnumber>4</pubsnumber>
+ <pubsnumber>5</pubsnumber>
<abstract>
<para>
This guide is intended to assist developers working with JBoss Enterprise
Portal Platform. It assumes a high level of technical knowledge.
Modified: epp/docs/branches/5.2/Developer_Guide/en-US/Preface.xml
===================================================================
--- epp/docs/branches/5.2/Developer_Guide/en-US/Preface.xml 2011-11-24 17:26:22 UTC (rev
8138)
+++ epp/docs/branches/5.2/Developer_Guide/en-US/Preface.xml 2011-11-25 00:43:12 UTC (rev
8139)
@@ -1,21 +1,11 @@
-<?xml version='1.0' encoding='utf-8' ?>
-<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-<!ENTITY % BOOK_ENTITIES SYSTEM "Developer_Guide.ent">
-%BOOK_ENTITIES;
-<!ENTITY % BOOK_ENTITIES SYSTEM "Developer_Guide.ent">
-%BOOK_ENTITIES;
-<!ENTITY % BOOK_ENTITIES SYSTEM ".ent">
-%BOOK_ENTITIES;
-<!ENTITY % BOOK_ENTITIES SYSTEM "Developer_Guide.ent">
-%BOOK_ENTITIES;
-<!ENTITY % BOOK_ENTITIES SYSTEM "Developer_Guide.ent">
-%BOOK_ENTITIES;
-]>
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+
<preface id="pref-Developer_Guide-Preface">
- <title>Preface</title>
- <xi:include href="Common_Content/Conventions.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Feedback.xml"
xmlns:xi="http://www.w3.org/2001/XInclude"> <xi:fallback
xmlns:xi="http://www.w3.org/2001/XInclude"> <xi:include
href="Common_Content/Feedback.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
- </xi:fallback>
- </xi:include>
+ <title>Preface</title>
+ <xi:include href="Common_Content/Conventions.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Feedback.xml"
xmlns:xi="http://www.w3.org/2001/XInclude"> <xi:fallback
xmlns:xi="http://www.w3.org/2001/XInclude"> <xi:include
href="Common_Content/Feedback.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
+ </xi:fallback>
+ </xi:include>
</preface>
Modified: epp/docs/branches/5.2/Developer_Guide/en-US/Revision_History.xml
===================================================================
--- epp/docs/branches/5.2/Developer_Guide/en-US/Revision_History.xml 2011-11-24 17:26:22
UTC (rev 8138)
+++ epp/docs/branches/5.2/Developer_Guide/en-US/Revision_History.xml 2011-11-25 00:43:12
UTC (rev 8139)
@@ -1,21 +1,25 @@
-<?xml version='1.0' encoding='utf-8' ?>
-<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-<!ENTITY % BOOK_ENTITIES SYSTEM "Developer_Guide.ent">
-%BOOK_ENTITIES;
-<!ENTITY % BOOK_ENTITIES SYSTEM "Developer_Guide.ent">
-%BOOK_ENTITIES;
-<!ENTITY % BOOK_ENTITIES SYSTEM ".ent">
-%BOOK_ENTITIES;
-<!ENTITY % BOOK_ENTITIES SYSTEM "Developer_Guide.ent">
-%BOOK_ENTITIES;
-<!ENTITY % BOOK_ENTITIES SYSTEM "Developer_Guide.ent">
-%BOOK_ENTITIES;
-]>
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+
<appendix id="appe-Developer_Guide-Revision_History">
<title>Revision History</title>
<simpara>
<revhistory>
<revision>
+ <revnumber>5.2.0-5</revnumber>
+ <date>Friday Nov 25 2011</date>
+ <author>
+ <firstname>Scott</firstname>
+ <surname>Mumford</surname>
+ <email></email>
+ </author>
+ <revdescription>
+ <simplelist>
+ <member>Staged with updated content.</member>
+ </simplelist>
+ </revdescription>
+ </revision>
+ <revision>
<revnumber>5.2.0-4</revnumber>
<date>Tue Nov 15 2011</date>
<author>
Modified: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/Author_Group.xml
===================================================================
--- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/Author_Group.xml 2011-11-24
17:26:22 UTC (rev 8138)
+++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/Author_Group.xml 2011-11-25
00:43:12 UTC (rev 8139)
@@ -4,54 +4,64 @@
%BOOK_ENTITIES;
]>
<authorgroup>
- <editor>
- <firstname>Luc</firstname>
- <surname>Texier</surname>
- <affiliation>
- <shortaffil>Red Hat</shortaffil>
- <orgdiv>JBoss Engineering</orgdiv>
+ <editor>
+ <firstname>Luc</firstname>
+ <surname>Texier</surname>
+ <affiliation>
+ <shortaffil>Red Hat</shortaffil>
+ <orgdiv>JBoss Engineering</orgdiv>
- </affiliation>
+ </affiliation>
- </editor>
- <editor>
- <firstname>Thomas</firstname>
- <surname>Heute</surname>
- <affiliation>
- <shortaffil>Red Hat</shortaffil>
- <orgdiv>JBoss Engineering</orgdiv>
+ </editor>
+ <editor>
+ <firstname>Thomas</firstname>
+ <surname>Heute</surname>
+ <affiliation>
+ <shortaffil>Red Hat</shortaffil>
+ <orgdiv>JBoss Engineering</orgdiv>
- </affiliation>
+ </affiliation>
- </editor>
- <editor>
- <firstname>Wesley</firstname>
- <surname>Hales</surname>
- <affiliation>
- <shortaffil>Red Hat</shortaffil>
- <orgdiv>JBoss Engineering</orgdiv>
+ </editor>
+ <editor>
+ <firstname>Wesley</firstname>
+ <surname>Hales</surname>
+ <affiliation>
+ <shortaffil>Red Hat</shortaffil>
+ <orgdiv>JBoss Engineering</orgdiv>
- </affiliation>
+ </affiliation>
- </editor>
- <editor>
- <firstname>Scott</firstname>
- <surname>Mumford</surname>
- <affiliation>
- <shortaffil>Red Hat</shortaffil>
- <orgdiv>Engineering Content Services</orgdiv>
+ </editor>
+ <editor>
+ <firstname>Chris</firstname>
+ <surname>Laprun</surname>
+ <affiliation>
+ <shortaffil>Red Hat</shortaffil>
+ <orgdiv>JBoss Engineering</orgdiv>
- </affiliation>
+ </affiliation>
- </editor>
- <othercredit>
- <affiliation>
- <orgname><emphasis role="bold"><ulink type="http"
url="http://www.jboss.org/gatein/">GateIn</ulink></... and
<emphasis role="bold"><ulink type="http"
url="http://www.exoplatform.com">eXo
Platform</ulink></emphasis></orgname>
- <orgdiv>Documentation Teams</orgdiv>
+ </editor>
+ <editor>
+ <firstname>Scott</firstname>
+ <surname>Mumford</surname>
+ <affiliation>
+ <shortaffil>Red Hat</shortaffil>
+ <orgdiv>Engineering Content Services</orgdiv>
- </affiliation>
- <contrib>Based on original product documentation by:</contrib>
+ </affiliation>
- </othercredit>
+ </editor>
+ <othercredit>
+ <affiliation>
+ <orgname><emphasis role="bold"><ulink
type="http"
url="http://www.jboss.org/gatein/">GateIn</ulink></... and
<emphasis role="bold"><ulink type="http"
url="http://www.exoplatform.com">eXo
Platform</ulink></emphasis></orgname>
+ <orgdiv>Documentation Teams</orgdiv>
+
+ </affiliation>
+ <contrib>Based on original product documentation by:</contrib>
+
+ </othercredit>
</authorgroup>
Modified: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/Book_Info.xml
===================================================================
--- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/Book_Info.xml 2011-11-24
17:26:22 UTC (rev 8138)
+++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/Book_Info.xml 2011-11-25
00:43:12 UTC (rev 8139)
@@ -4,30 +4,30 @@
%BOOK_ENTITIES;
]>
<bookinfo
id="book-Reference_Guide_eXo_JCR_1.14-Reference_Guide_eXo_JCR_1.14">
- <title>Reference Guide eXo JCR 1.14</title>
- <subtitle>An in-depth guide to Enterprise Portal Platform
&VZ;</subtitle>
- <productname>JBoss Enterprise Portal Platform</productname>
- <productnumber>5.2</productnumber>
- <edition>5.2.0</edition>
- <pubsnumber>7</pubsnumber>
- <abstract>
- <para>
- This Reference Guide is a high-level usage document. It deals with more advanced
topics than the Installation and User Guides, adding new content or taking concepts
discussed in the earlier documents further. It aims to provide supporting documentation
for advanced users of the JBoss Enterprise Portal Platform product. Its primary focus is
on advanced use of the product and it assumes an intermediate or advanced knowledge of the
technology and terms.
- </para>
+ <title>Reference Guide eXo JCR 1.14</title>
+ <subtitle>An in-depth guide to Enterprise Portal Platform
&VZ;</subtitle>
+ <productname>JBoss Enterprise Portal Platform</productname>
+ <productnumber>5.2</productnumber>
+ <edition>5.2.0</edition>
+ <pubsnumber>9</pubsnumber>
+ <abstract>
+ <para>
+ This Reference Guide is a high-level usage document. It deals with more
advanced topics than the Installation and User Guides, adding new content or taking
concepts discussed in the earlier documents further. It aims to provide supporting
documentation for advanced users of the JBoss Enterprise Portal Platform product. Its
primary focus is on advanced use of the product and it assumes an intermediate or advanced
knowledge of the technology and terms.
+ </para>
- </abstract>
- <corpauthor>
- <inlinemediaobject>
- <imageobject>
- <imagedata fileref="Common_Content/images/title_logo.svg"
format="SVG" />
- </imageobject>
+ </abstract>
+ <corpauthor>
+ <inlinemediaobject>
+ <imageobject>
+ <imagedata fileref="Common_Content/images/title_logo.svg"
format="SVG" />
+ </imageobject>
- </inlinemediaobject>
+ </inlinemediaobject>
- </corpauthor>
- <!-- FOR PUBLICAN --> <xi:include
href="Common_Content/Legal_Notice.xml"
xmlns:xi="http://www.w3.org/2001/XInclude"> <!-- FOR JDOCBOOK:
--> <xi:fallback
xmlns:xi="http://www.w3.org/2001/XInclude"> <xi:include
href="fallback_content/Legal_Notice.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
- </xi:fallback>
- </xi:include>
- <xi:include href="Author_Group.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
+ </corpauthor>
+ <!-- FOR PUBLICAN --> <xi:include
href="Common_Content/Legal_Notice.xml"
xmlns:xi="http://www.w3.org/2001/XInclude"> <!-- FOR JDOCBOOK:
--> <xi:fallback
xmlns:xi="http://www.w3.org/2001/XInclude"> <xi:include
href="fallback_content/Legal_Notice.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
+ </xi:fallback>
+ </xi:include>
+ <xi:include href="Author_Group.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
</bookinfo>
Modified: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/Revision_History.xml
===================================================================
---
epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/Revision_History.xml 2011-11-24
17:26:22 UTC (rev 8138)
+++
epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/Revision_History.xml 2011-11-25
00:43:12 UTC (rev 8139)
@@ -4,138 +4,168 @@
%BOOK_ENTITIES;
]>
<appendix id="appe-Reference_Guide_eXo_JCR_1.14-Revision_History">
- <title>Revision History</title>
- <simpara>
- <revhistory>
- <revision>
- <revnumber>5.2.0-6</revnumber>
- <date>Thu Nov 17 2011</date>
- <author>
- <firstname>Scott</firstname>
- <surname>Mumford</surname>
- <email></email>
+ <title>Revision History</title>
+ <simpara>
+ <revhistory>
+ <revision>
+ <revnumber>5.2.0-9</revnumber>
+ <date>Fri Nov 25 2011</date>
+ <author>
+ <firstname>Scott</firstname>
+ <surname>Mumford</surname>
+ <email></email>
+ </author>
+ <revdescription>
+ <simplelist>
+ <member>Ported latest community WSRP
content.</member>
+ </simplelist>
+ </revdescription>
+ </revision>
+ <revision>
+ <revnumber>5.2.0-8</revnumber>
+ <date>Thu Nov 24 2011</date>
+ <author>
+ <firstname>Scott</firstname>
+ <surname>Mumford</surname>
+ <email></email>
+ </author>
+ <revdescription>
+ <simplelist>
+ <member>Finalized first edit pass of eXoJCR
content.</member>
+ <member>Moved eXoJCR section to Part IV.</member>
+ <member>Clean element ids and fix broken
linkends.</member>
+ </simplelist>
+ </revdescription>
+ </revision>
+ <revision>
+ <revnumber>5.2.0-6</revnumber>
+ <date>Thu Nov 17 2011</date>
+ <author>
+ <firstname>Scott</firstname>
+ <surname>Mumford</surname>
+ <email></email>
- </author>
- <revdescription>
- <simplelist>
- <member>Incorporated GateIn SSO updates.</member>
+ </author>
+ <revdescription>
+ <simplelist>
+ <member>Incorporated GateIn SSO updates.</member>
- </simplelist>
+ </simplelist>
- </revdescription>
+ </revdescription>
- </revision>
- <revision>
- <revnumber>5.2.0-5</revnumber>
- <date>Tue Nov 15 2011</date>
- <author>
- <firstname>Scott</firstname>
- <surname>Mumford</surname>
- <email></email>
+ </revision>
+ <revision>
+ <revnumber>5.2.0-5</revnumber>
+ <date>Tue Nov 15 2011</date>
+ <author>
+ <firstname>Scott</firstname>
+ <surname>Mumford</surname>
+ <email></email>
- </author>
- <revdescription>
- <simplelist>
- <member>Staging for beta release.</member>
+ </author>
+ <revdescription>
+ <simplelist>
+ <member>Staging for beta release.</member>
- </simplelist>
+ </simplelist>
- </revdescription>
+ </revdescription>
- </revision>
- <revision>
- <revnumber>5.2.0-4</revnumber>
- <date>Wed Nov 9 2011</date>
- <author>
- <firstname>Scott</firstname>
- <surname>Mumford</surname>
- <email></email>
+ </revision>
+ <revision>
+ <revnumber>5.2.0-4</revnumber>
+ <date>Wed Nov 9 2011</date>
+ <author>
+ <firstname>Scott</firstname>
+ <surname>Mumford</surname>
+ <email></email>
- </author>
- <revdescription>
- <simplelist>
- <member>Republished for review/feedback.</member>
+ </author>
+ <revdescription>
+ <simplelist>
+ <member>Republished for review/feedback.</member>
- </simplelist>
+ </simplelist>
- </revdescription>
+ </revdescription>
- </revision>
- <revision>
- <revnumber>5.2.0-3</revnumber>
- <date>Wed Nov 2 2011</date>
- <author>
- <firstname>Scott</firstname>
- <surname>Mumford</surname>
- <email></email>
+ </revision>
+ <revision>
+ <revnumber>5.2.0-3</revnumber>
+ <date>Wed Nov 2 2011</date>
+ <author>
+ <firstname>Scott</firstname>
+ <surname>Mumford</surname>
+ <email></email>
- </author>
- <revdescription>
- <simplelist>
- <member>Staged for review of updated Foundations and eXo JCR
content.</member>
+ </author>
+ <revdescription>
+ <simplelist>
+ <member>Staged for review of updated Foundations and eXo
JCR content.</member>
- </simplelist>
+ </simplelist>
- </revdescription>
+ </revdescription>
- </revision>
- <revision>
- <revnumber>5.2.0-2</revnumber>
- <date>Tue Sep 27 2011</date>
- <author>
- <firstname>Scott</firstname>
- <surname>Mumford</surname>
- <email></email>
+ </revision>
+ <revision>
+ <revnumber>5.2.0-2</revnumber>
+ <date>Tue Sep 27 2011</date>
+ <author>
+ <firstname>Scott</firstname>
+ <surname>Mumford</surname>
+ <email></email>
- </author>
- <revdescription>
- <simplelist>
- <member>Incorporated eXo JCR 1.14 documentation.</member>
+ </author>
+ <revdescription>
+ <simplelist>
+ <member>Incorporated eXo JCR 1.14
documentation.</member>
- </simplelist>
+ </simplelist>
- </revdescription>
+ </revdescription>
- </revision>
- <revision>
- <revnumber>5.2.0-5</revnumber>
- <date>Wed Sep 14 2011</date>
- <author>
- <firstname>Scott</firstname>
- <surname>Mumford</surname>
- <email></email>
+ </revision>
+ <revision>
+ <revnumber>5.2.0-5</revnumber>
+ <date>Wed Sep 14 2011</date>
+ <author>
+ <firstname>Scott</firstname>
+ <surname>Mumford</surname>
+ <email></email>
- </author>
- <revdescription>
- <simplelist>
- <member>Added Global Portlet Data section.</member>
+ </author>
+ <revdescription>
+ <simplelist>
+ <member>Added Global Portlet Data section.</member>
- </simplelist>
+ </simplelist>
- </revdescription>
+ </revdescription>
- </revision>
- <revision>
- <revnumber>5.2.0-1</revnumber>
- <date>Mon Aug 29 2011</date>
- <author>
- <firstname>Scott</firstname>
- <surname>Mumford</surname>
- <email></email>
+ </revision>
+ <revision>
+ <revnumber>5.2.0-1</revnumber>
+ <date>Mon Aug 29 2011</date>
+ <author>
+ <firstname>Scott</firstname>
+ <surname>Mumford</surname>
+ <email></email>
- </author>
- <revdescription>
- <simplelist>
- <member>Updating version and resetting pubs/ed numbers.</member>
+ </author>
+ <revdescription>
+ <simplelist>
+ <member>Updating version and resetting pubs/ed
numbers.</member>
- </simplelist>
+ </simplelist>
- </revdescription>
+ </revdescription>
- </revision>
+ </revision>
- </revhistory>
+ </revhistory>
- </simpara>
+ </simpara>
</appendix>
Modified:
epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/images/WSRP/config_self.png
===================================================================
(Binary files differ)
Modified:
epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/images/WSRP/modify_reg_end.png
===================================================================
(Binary files differ)
Modified:
epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/images/WSRP/modify_reg_self_end.png
===================================================================
(Binary files differ)
Modified:
epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/Foundations/Configuring_Services.xml
===================================================================
---
epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/Foundations/Configuring_Services.xml 2011-11-24
17:26:22 UTC (rev 8138)
+++
epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced/Foundations/Configuring_Services.xml 2011-11-25
00:43:12 UTC (rev 8139)
@@ -9,13 +9,19 @@
The eXo Kernel uses dependency injection to create services based on
<filename>configuration.xml</filename> configuration files. The location of
the configuration files determines if services are placed into the
<literal>RootContainer</literal> scope, or into the
<literal>PortalContainer</literal> scope.
</para>
<para>
- When creating a service, you also should declare its existence to the
<emphasis role="bold">Container</emphasis>, therefore you create a
first simple configuration file. Copy the following code to a file called
"configuration.xml" and place this file in a /conf subdirectory of your service
base folder. As you already know the container looks for a
"/conf/configuration.xml" file in each jar-file.
+ When creating a service, you also should declare its existence to the
<emphasis role="bold">Container</emphasis>. This fan be done by
creating a simple configuration file.
+ </para>
+ <para>
+ Copy the following code to a <filename>configuration.xml</filename>
file and save this file in a <filename>/conf</filename> subdirectory of your
service base folder. The container looks for a
<filename>/conf/configuration.xml</filename> file in each jar-file.
</para>
<para>
- All <filename>configuration.xml</filename> files located at
<filename>conf/configuration.xml</filename> in the classpath (any directory,
or any jar in the classpath) will have their services configured in the
<literal>RootContainer</literal> scope. All
<filename>configuration.xml</filename> files located at
<filename>conf/portal/configuration.xml</filename> in the classpath will have
their services configured at the <literal>PortalContainer</literal> scope.
+ All <filename>configuration.xml</filename> files located at
<filename>conf/configuration.xml</filename> in the classpath (any directory,
or any jar in the classpath) will have their services configured in the
<literal>RootContainer</literal> scope.
+ </para>
+ <para>
+ All <filename>configuration.xml</filename> files located at
<filename>conf/portal/configuration.xml</filename> in the classpath will have
their services configured at the <literal>PortalContainer</literal> scope.
</para>
<para>
- Additionally, <emphasis role="bold">portal
extensions</emphasis> can contain configuration in
<filename><replaceable>JBOSS_HOME</replaceable>/server/<replaceable><PROFILE></replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/configuration.xml</filename>,
and will also have their services configured in the
<literal>PortalContainer</literal> scope.
+ Additionally, <emphasis role="bold">portal
extensions</emphasis> can use configuration information stored in
<filename><replaceable>JBOSS_HOME</replaceable>/server/<replaceable><PROFILE></replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/configuration.xml</filename>,
and will also have their services configured in the
<literal>PortalContainer</literal> scope.
</para>
<para>
When eXo kernel reads a configuration, it loads the file from the kernel jar
using the classloader and does not use an internet connection to resolve the file.
@@ -45,7 +51,7 @@
<programlisting language="XML" role="XML"><xi:include
href="../../../extras/Advanced_Development_Foundations/default.xml"
parse="text"
xmlns:xi="http://www.w3.org/2001/XInclude"
/></programlisting>
<para>
- The configuration you find inside the jar file is considered as the
default configuration. If you want to override this default configuration you can do it in
different places outside the jar. When the container finds several configurations for the
same service, the configuration which is found later replaces completely the one found
previously. Let's call this the <emphasis>configuration override
mechanism</emphasis>.
+ The configuration found inside the jar file is considered as the default
configuration. If you want to override this default configuration you can do it in
different places outside the jar. When the container finds several configurations for the
same service, the configuration which is found later replaces completely the one found
previously. Let's call this the <emphasis>configuration override
mechanism</emphasis>.
</para>
<para>
After deploying you find the configuration.xml file in
webapps/portal/WEB-INF/conf Use component registration tags. Let's look at the key tag
that defines the interface and the type tag that defines the implementation. Note that the
key tag is not mandatory, but it improves performance.
Modified:
epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/AuthenticationAndIdentity/SSO.xml
===================================================================
---
epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/AuthenticationAndIdentity/SSO.xml 2011-11-24
17:26:22 UTC (rev 8138)
+++
epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/AuthenticationAndIdentity/SSO.xml 2011-11-25
00:43:12 UTC (rev 8139)
@@ -115,7 +115,7 @@
<title>SSO Integration</title>
<step>
<para>
- Open the
<filename>/<replaceable><JBOSS_HOME></replaceable>/server/<replaceable><PROFILE></replaceable>/deploy/jbossweb.sar/server.xml</filename>
file and uncomment one of the two <parameter>Valve</parameter> entries:
+ Open the
<filename><replaceable><JBOSS_HOME></replaceable>/server/<replaceable><PROFILE></replaceable>/deploy/jbossweb.sar/server.xml</filename>
file and uncomment one of the two <parameter>Valve</parameter> entries:
</para>
<itemizedlist>
<listitem>
@@ -192,7 +192,7 @@
</step>
<step>
<para>
- Open the
<filename><replaceable><JBOSS_HOME></replaceable>/server/all/deploy/jbossweb.sar/server.xml</filename>
file.
+ Open the
<filename><replaceable><JBOSS_HOME></replaceable>/server/all/<replaceable><PROFILE></replaceable>/jbossweb.sar/server.xml</filename>
file.
</para>
</step>
@@ -239,13 +239,13 @@
</step>
<step>
<para>
- Go to <ulink type="http"
url="http://machine1.yourdomain.com:8080/portal">http://machine1.yourdomain.com:8080/portal</ulink>
and login as a user.
+ Go to
<uri>http://machine1.yourdomain.com:8080/portal</uri> and login as a user.
</para>
</step>
<step>
<para>
- Access a private URL on the second host, such as <ulink
type="http"
url="http://machine2.yourdomain.com:8080/portal/dologin">http://machine2.yourdomain.com:8080/portal/dologin</ulink>,
for example.
+ Access a private URL on the second host, such as
<uri>http://machine2.yourdomain.com:8080/portal/dologin</uri>, for example.
</para>
<para>
Now you should be logged directly into
<literal>machine2</literal> thanks to SSO valve.
@@ -327,13 +327,13 @@
</step>
<step>
<para>
- Navigate to <ulink type="http"
url="http://machine1.yourdomain.com:8080/portal/private/classic" /> and
authenticate with the pre-configured user account
"<systemitem>root</systemitem>" (password
"<systemitem>gtn </systemitem>").
+ Navigate to
<uri>http://machine1.yourdomain.com:8080/portal/private/classic</uri> and
authenticate with the pre-configured user account
"<systemitem>root</systemitem>" (password
"<systemitem>gtn </systemitem>").
</para>
</step>
<step>
<para>
- Navigate to <ulink type="http"
url="http://machine1.yourdomain.com:8080/jmx-console" />. You should be
automatically authenticated into the JMX Console.
+ Navigate to
<uri>http://machine1.yourdomain.com:8080/jmx-console</uri>. You should be
automatically authenticated into the JMX Console.
</para>
</step>
@@ -849,7 +849,7 @@
OpenSSO must be purchased from <ulink type="http"
url="http://www.oracle.com/technetwork/middleware/id-mgmt/overview/i...
Oracle </ulink> .
</para>
<para>
- For testing purpose, use OpenSSO_80U2, which can be downloaded from
<ulink type="http"
url="http://download.oracle.com/otn/nt/middleware/11g/oracle_opensso...
Oracle </ulink> .
+ For testing purposes, use OpenSSO_80U2, which can be downloaded from
<ulink type="http"
url="http://download.oracle.com/otn/nt/middleware/11g/oracle_opensso...
</ulink> .
</para>
</step>
Added: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/RH-WSRP.xml
===================================================================
--- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/RH-WSRP.xml
(rev 0)
+++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/RH-WSRP.xml 2011-11-25
00:43:12 UTC (rev 8139)
@@ -0,0 +1,2003 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "Reference_Guide_eXo_JCR_1.14.ent">
+%BOOK_ENTITIES;
+]>
+<chapter
id="chap-Reference_Guide_eXo_JCR_1.14-Web_Services_for_Remote_Portlets_WSRP">
+ <title><remark>Web Services for Remote Portlets
(WSRP)</remark></title>
+ <section
id="sect-Reference_Guide_eXo_JCR_1.14-Web_Services_for_Remote_Portlets_WSRP-Introduction">
+ <title>Introduction</title>
+ <para>
+ The Web Services for Remote Portlets (WSRP) specification defines a web
service interface for accessing and interacting with interactive presentation-oriented web
services.
+ </para>
+ <para>
+ It has been produced through the efforts of the Web Services for Remote
Portlets (WSRP) OASIS Technical Committee. It is based on the requirements gathered and
the proposals made to the committee.
+ </para>
+ <para>
+ Scenarios that motivate WSRP functionality include:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Content hosts, such as portal servers, providing Portlets as
presentation-oriented web services that can be used by aggregation engines.
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ Aggregating frameworks, including portal servers, consuming
presentation-oriented web services offered by content providers and integrating them into
the framework.
+ </para>
+
+ </listitem>
+
+ </itemizedlist>
+ <para>
+ More information on WSRP can be found on the official <ulink
url="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wsrp...;.
We suggest reading the <ulink
url="http://www.oasis-open.org/committees/download.php/10539/wsrp-pr...
for a good, albeit technical, overview of WSRP.
+ </para>
+
+ </section>
+
+ <section
id="sect-Reference_Guide_eXo_JCR_1.14-Web_Services_for_Remote_Portlets_WSRP-Level_of_Support">
+ <title>Level of Support</title>
+ <para>
+ The WSRP Technical Committee defined <ulink
url="http://www.oasis-open.org/committees/download.php/3073">... Use
Profiles</ulink> to help with WSRP interoperability. Terms defined in that document
will be used in this section.
+ </para>
+ <para>
+ JBoss Enterprise Portal Platform provides a
<emphasis>Simple</emphasis> level of support for the WSRP Producer, with the
exception of out-of-band registration. In-band registration and persistent local state
(which are defined at the <emphasis>Complex</emphasis> level) are supported.
+ </para>
+ <para>
+ JBoss Enterprise Portal Platform provides a
<emphasis>Medium</emphasis> level of support for the Consumer, excepting HTML
markup (as JBoss Enterprise Portal Platform itself does not handle other markup types).
Explicit portlet cloning and the <literal>PortletManagement</literal>
interface are supported.
+ </para>
+ <para>
+ The WSRP component has Level 1 Producer and Consumer caching. Cookie handling
is supported properly on the Consumer. The Producer requires cookie initialization (as
this improves interoperability with some consumers).
+ </para>
+ <para>
+ JBoss Enterprise Portal Platform does not support custom window states or
modes, therefore neither does the WSRP component. It does, however, support CSS on both
the Producer (although this is more a function of the portlets than an inherent Producer
capability) and Consumer.
+ </para>
+ <para>
+ JBoss Enterprise Portal Platform &VY; includes implementations of WSRP
1.0 and 2.0.
+ </para>
+ <para>
+ All optional features in WSRP 2 are implemented in JBoss Enterprise Portal
Platform &VY; except support for lifetimes and leasing support.
+ </para>
+ <note>
+ <para>
+ As of version &VZ; of Enterprise Portal Platform, WSRP is only
activated and supported when deployed on JBoss Enterprise Application Server.
+ </para>
+
+ </note>
+
+ </section>
+
+ <section
id="sect-Reference_Guide_eXo_JCR_1.14-Web_Services_for_Remote_Portlets_WSRP-Deploying_WSRP">
+ <title>Deploying WSRP</title>
+ <note>
+ <title>Notational Devices</title>
+ <para>
+ The following list of support files uses the following notational
devices:
+ </para>
+ <variablelist
id="vari-Reference_Guide_eXo_JCR_1.14-Deploying_WSRP-Notations">
+ <title>Notations:</title>
+ <varlistentry>
+
<term><replaceable>JBOSS_HOME</replaceable></term>
+ <listitem>
+ <para>
+ <replaceable>JBOSS_HOME</replaceable> refers to
the directory that your instance of JBoss Enterprise Portal Platform has been
extracted/installed to. For example:
<filename>/home/<replaceable>USERNAME</replaceable>/jboss-epp-<replaceable><VERSION></replaceable>/</filename>
+ </para>
+
+ </listitem>
+
+ </varlistentry>
+ <varlistentry>
+
<term><replaceable>WSRP_PATH</replaceable></term>
+ <listitem>
+ <para>
+ The WSRP files referred to in this section are found in the
<filename><replaceable>JBOSS_HOME</replaceable>/jboss-as/server/<replaceable><PROFILE></replaceable>/deploy/gatein.ear</filename>
directory.
+ </para>
+ <para>
+ For ease of reference this path will be represented by:
<replaceable>WSRP_PATH</replaceable>.
+ </para>
+
+ </listitem>
+
+ </varlistentry>
+ <varlistentry>
+
<term><replaceable>WSRP_VERSION</replaceable></term>
+ <listitem>
+ <para>
+ <replaceable>WSRP_VERSION</replaceable>
represents the version of the WSRP component in use.
+ </para>
+
+ </listitem>
+
+ </varlistentry>
+ <varlistentry>
+
<term><replaceable>PORTAL_VERSION</replaceable></term>
+ <listitem>
+ <para>
+ <replaceable>PORTAL_VERSION</replaceable>
represents the version of JBoss Enterprise Portal Platform in use.
+ </para>
+
+ </listitem>
+
+ </varlistentry>
+
+ </variablelist>
+
+ </note>
+ <para>
+ Starting with version 2.1.0-GA of the component, WSRP is packaged as a JBoss
Enterprise Portal Platform extension and is now self-contained in an easy to install
package named <filename>gatein-wsrp-integration.ear</filename>, deployed
directly in the <filename>deploy</filename> directory of your JBoss
Application Server configuration directory.
+ </para>
+ <para>
+ The extension itself is composed of the following components:
+ </para>
+ <variablelist
id="vari-Reference_Guide_eXo_JCR_1.14-Deploying_WSRP-WSRP_support_files">
+ <title>WSRP support files</title>
+ <varlistentry>
+ <term><filename>META-INF/</filename></term>
+ <listitem>
+ <para>
+ This directory contains files necessary for EAR packaging. The
only file that is of interest from a user perspective is
<filename>gatein-wsse-consumer.xml</filename> which allows you to configure
WS-Security support for the consumer.
+ </para>
+ <para>
+ Refer to <xref
linkend="sect-Reference_Guide_eXo_JCR_1.14-WSRP_and_WS_Security-WS_Security_Configuration"
/> section for more details.
+ </para>
+
+ </listitem>
+
+ </varlistentry>
+ <varlistentry>
+
<term><filename>extension-component-$PORTAL_VERSION.jar</filename></term>
+ <listitem>
+ <para>
+ This archive which contains the components needed to integrate
the WSRP component into JBoss Enterprise Portal Platform. It also includes the default
configuration files for the WSRP producer and the default WSRP consumers.
+ </para>
+
+ </listitem>
+
+ </varlistentry>
+ <varlistentry>
+
<term><filename>extension-config-$PORTAL_VERSION.jar</filename></term>
+ <listitem>
+ <para>
+ This file contains the configuration file needed by the GateIn
extension mechanism to properly register this EAR as an extension.
+ </para>
+
+ </listitem>
+
+ </varlistentry>
+ <varlistentry>
+
<term><filename>extension-war-$PORTAL_VERSION.war</filename></term>
+ <listitem>
+ <para>
+ This file contains the configuration files needed by the GateIn
extension mechanism to properly setup the WSRP service. It includes
<filename>wsrp-configuration.xml</filename> which, in particular, configures
several options for the <code> WSRPServiceIntegration </code> component at the
heart of the WSRP integration in JBoss Enterprise Portal Platform.
+ </para>
+
+ </listitem>
+
+ </varlistentry>
+ <varlistentry>
+ <term><filename>lib/</filename></term>
+ <listitem>
+ <para>
+ This directory contains the different libraries needed by the
WSRP service.
+ </para>
+
+ </listitem>
+
+ </varlistentry>
+ <varlistentry>
+
<term><filename>wsrp-admin-gui-$WSRP_VERSION.war</filename></term>
+ <listitem>
+ <para>
+ This file contains the WSRP Configuration portlet with which you
can configure consumers to access remote servers and how the WSRP producer is configured.
+ </para>
+
+ </listitem>
+
+ </varlistentry>
+ <varlistentry>
+
<term><filename>wsrp-producer-jb5wsss-$WSRP_VERSION.war</filename></term>
+ <listitem>
+ <para>
+ This file contains the producer-side support for WS-Security. The
only file of interest from a user perspective is
<filename>gatein-wsse-producer.xml</filename> which allows you to configure
WS-Security support for the producer.
+ </para>
+ <para>
+ Refer to <xref
linkend="sect-Reference_Guide_eXo_JCR_1.14-WSRP_and_WS_Security-WS_Security_Configuration"
/> for more details.
+ </para>
+
+ </listitem>
+
+ </varlistentry>
+
+ </variablelist>
+ <section
id="sect-Reference_Guide_eXo_JCR_1.14-Deploying_WSRP-Non_default_Ports_or_Hostnames">
+ <title>Non-default Ports or Hostnames</title>
+ <para>
+ JBoss WS (the web service stack that JBoss Enterprise Portal Platform
uses) should update the port and host name used in WSDL. Refer to the JBoss WS <ulink
url="http://community.jboss.org/wiki/JBossWS-UserGuide#Configuration...
guide</ulink> for more information.
+ </para>
+ <para>
+ If the host name and port on which the server runs have been modified,
the configuration for the Consumer used to consume JBoss Enterprise Portal Platform's
"self" Producer will need to be updated. Refer to <xref
linkend="sect-Reference_Guide_eXo_JCR_1.14-Web_Services_for_Remote_Portlets_WSRP-Consuming_Remote_WSRP_Portlets"
/> for directions on how to do this.
+ </para>
+
+ </section>
+
+ <section
id="sect-Reference_Guide_eXo_JCR_1.14-Deploying_WSRP-Using_WSRP_with_SSL">
+ <title>Using WSRP with SSL</title>
+ <para>
+ It is possible to use WSRP over SSL for secure exchange of data. Refer to
these <ulink
url="http://community.jboss.org/wiki/ConfiguringWSRPforuseoverSSL&qu...
for how to do this.
+ </para>
+
+ </section>
+
+
+ </section>
+
+ <section
id="sect-Reference_Guide_eXo_JCR_1.14-Web_Services_for_Remote_Portlets_WSRP-WSRP_and_WS_Security">
+ <title>WSRP and WS-Security</title>
+ <para>
+ Portlets may present different data or options depending on the currently
authenticated user. For remote portlets, this means having to propagate the user
credentials from the consumer back to the producer in a safe and secure manner.
+ </para>
+ <para>
+ The WSRP specification does not directly specify how this should be
accomplished, but delegates this work to the existing WS-Security standards.
+ </para>
+ <note>
+ <title>Web Container Compatibility</title>
+ <para>
+ WSRP and WS-Security is currently only supported on JBoss Enterprise
Portal Platform when running on top of JBoss AS 5.
+ </para>
+
+ </note>
+ <warning>
+ <title>Encryption</title>
+ <para>
+ <emphasis role="bold">The use of encryption is strongly
recommended.</emphasis>
+ </para>
+ <para>
+ Credentials being sent between the consumer and producer should be
encrypted or they will be sent in plain text and could be easily intercepted.
+ </para>
+ <para>
+ You can either configure WS-Security to encrypt and sign the SOAP
messages being sent, or secure the transport layer by using an
<literal>https</literal> endpoint.
+ </para>
+ <para>
+ Failure to encrypt the SOAP message or transport layer will result in the
username and password being sent in plain text.
+ </para>
+
+ </warning>
+ <important>
+ <title>Credentials</title>
+ <para>
+ When the consumer sends the user credentials to the producer, it is
sending the credentials for the currently authenticated user in the consumer. This makes
signing in to remote portlets transparent to end users, but also requires that the
producer and consumer use the same credentials.
+ </para>
+ <para>
+ The username and password must be the same and valid on both servers.
+ </para>
+ <para>
+ The recommended approach for this situation would be to use a common LDAP
configuration. Please see the User Guide at <ulink type="http"
url="docs.redhat.com" /> for information on how to configure LDAP for use
with JBoss Enterprise Portal Platform
+ </para>
+
+ </important>
+ <para>
+ This community Wiki <ulink
url="http://community.jboss.org/wiki/GateInWSRPAndWebServiceSecurity...;,
also provides a step-by-step example on how to configure WSRP with WS-Security.
+ </para>
+ <section
id="sect-Reference_Guide_eXo_JCR_1.14-WSRP_and_WS_Security-WS_Security_Configuration">
+ <title>WS-Security Configuration</title>
+ <para>
+ JBoss Enterprise Portal Platform uses <application>JBossWS
Native</application> to handle ws-security.
+ </para>
+ <para>
+ Refer to the WS-Security section of the <ulink
url="http://www.jboss.org/jbossas/docs/5-x">JBoss AS 5 Administration and
Configuration Guide </ulink> for in-depth configuration options.
+ </para>
+ <para>
+ Please note that since the consumer passes its credentials to the
producer, the consumer will act at the wss client and the producer will act as the wss
server.
+ </para>
+ <para>
+ The following are the JBossWS Native configuration files which need to be
configure for WSRP:
+ </para>
+ <variablelist>
+ <title></title>
+ <varlistentry>
+
<term>gatein-wsrp-integration.ear/META-INF/gatein-wsse-consumer.xml</term>
+ <listitem>
+ <para>
+ BossWS configuration file for the consumer.
+ </para>
+
+ </listitem>
+
+ </varlistentry>
+ <varlistentry>
+
<term>gatein-wsrp-integration.ear/wsrp-producer-jb5wss.war/WEB-INF/conf/gatein-wsse-producer.xml</term>
+ <listitem>
+ <para>
+ JBossWS configuration file for the producer.
+ </para>
+
+ </listitem>
+
+ </varlistentry>
+
+ </variablelist>
+
+ </section>
+
+ <section
id="sect-Reference_Guide_eXo_JCR_1.14-WSRP_and_WS_Security-WS_Security_Producer_Configuration">
+ <title>WS-Security Producer Configuration</title>
+ <para>
+ Other than the JBossWS configuration file mention above, no other
configuration changes should be necessary for the producer.
+ </para>
+
+ </section>
+
+ <section
id="sect-Reference_Guide_eXo_JCR_1.14-WSRP_and_WS_Security-WS_Security_Consumer_Configuration">
+ <title>WS-Security Consumer Configuration</title>
+ <para>
+ The consumer requires some changes before it will function properly with
WS-Security.
+ </para>
+ <para>
+ The consumer needs access to the current servlet request since this is
used to retrieve the currently authenticated user. In order to access this information,
the consumer needs a special servlet-filter added to the portal.
+ </para>
+ <procedure
id="proc-Reference_Guide_eXo_JCR_1.14-WS_Security_Consumer_Configuration-Add_the_servlet_filter">
+ <title>Add the servlet-filter</title>
+ <step>
+ <para>
+ Open
<filename><replaceable><JBOSS_HOME></replaceable>/server/<replaceable><PROFILE></replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/web.xml</filename>
and add the following:
+ </para>
+
+<programlisting role="XML"><!-- Filter to put request and response
in ServletAccess -->
+ <filter>
+ <filter-name>ServletAccessFilter</filter-name>
+
<filter-class>org.gatein.wsrp.servlet.ServletAccessFilter</filter-class>
+ </filter>
+ <filter-mapping>
+ <filter-name>ServletAccessFilter</filter-name>
+ <url-pattern>/*</url-pattern>
+ </filter-mapping>
+</programlisting>
+
+ </step>
+ <step>
+ <para>
+ Check the <guilabel>Enable WS Security</guilabel>
checkbox in the consumer configuration options of the WSRP Configuration portlet
+ </para>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center"
fileref="images/WSRP/config_wss_selected.png" format="PNG"
scalefit="1" valign="middle" width="444" />
+ </imageobject>
+
+ </mediaobject>
+ </step>
+ </procedure>
+
+
+ </section>
+
+ <section>
+ <title>WS-Security Consumer Checklist</title>
+ <para>
+ In order for the consumer to handle ws-security, the following items must
be implemented:
+ </para>
+ <orderedlist>
+ <listitem>
+ <para>
+ The JBossWS configuration files must be configured
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ The filter must be added to the portal's web.xml
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ the enable wss feature must be check in the wsrp admin
+ </para>
+
+ </listitem>
+
+ </orderedlist>
+ <para>
+ The consumer will not properly handle ws-security unless all three items
are correctly configured.
+ </para>
+
+ </section>
+
+ </section>
+
+ <section
id="sect-Reference_Guide_eXo_JCR_1.14-Web_Services_for_Remote_Portlets_WSRP-Making_a_Portlet_Remotable">
+ <title>Making a Portlet Remotable</title>
+ <note>
+ <para>
+ Only JSR-286 (Portlet 2.0) portlets can be made remotable as the
mechanism to expose a portlet to WSRP relies on a JSR-286-only functionality.
+ </para>
+
+ </note>
+ <para>
+ JBoss Enterprise Portal Platform does <emphasis
role="bold">not</emphasis>, by default, expose local portlets for
consumption by remote WSRP consumers.
+ </para>
+ <para>
+ In order to make a portlet remotely available, it must be made
"remotable" by marking it as such in the associated
<filename>portlet.xml</filename>.
+ </para>
+ <para>
+ A specific <code>org.gatein.pc.remotable
container-runtime-option</code> is used to accomplish this. Setting its value to
<code>true</code> makes the portlet available for remote consumption, while
setting its value to <code>false</code> will not publish it remotely.
+ </para>
+ <para>
+ As specifying the remotable status for a portlet is optional, nothing need be
done if portlets do not need to be remotely available.
+ </para>
+ <para>
+ In the following example, the "BasicPortlet" portlet is specified
as being remotable.
+ </para>
+
+<programlisting language="XML" role="XML"><xi:include
href="../extras/WSRP/default255.xml" parse="text"
xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ <para>
+ It is also possible to specify that all the portlets declared within a given
portlet application be remotable by default.
+ </para>
+ <para>
+ This is done by specifying the
<code>container-runtime-option</code> at the
<code>portlet-app</code> element level. Individual portlets can override that
value to not be remotely exposed.
+ </para>
+ <para>
+ For example:
+ </para>
+
+<programlisting language="XML" role="XML"><xi:include
href="../extras/WSRP/default256.xml" parse="text"
xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ <para>
+ This example defines two portlets. As the <code>org.gatein.pc.remotable
container-runtime-option</code> is set to <code>true</code> at the
<code>portlet-app</code> level, all portlets defined in this particular
portlet application are exposed remotely by JBoss Enterprise Portal Platform's WSRP
Producer.
+ </para>
+ <para>
+ It is possible to override this default behavior. Specifying a value for the
<code>org.gatein.pc.remotable container-runtime-option</code> at the
<code>portlet</code> level will take precedence over the default.
+ </para>
+ <para>
+ In the example above, the
<literal>RemotelyExposedPortlet</literal> inherits the remotable status
defined at the <code>portlet-app</code> level since it does not specify a
value for the <code>org.gatein.pc.remotable container-runtime-option</code>.
+ </para>
+ <para>
+ The <literal>NotRemotelyExposedPortlet</literal>, however,
overrides the default behavior and is not remotely exposed.
+ </para>
+ <note>
+ <title>Note</title>
+ <para>
+ Portlets are not remotely exposed if no top-level
<code>org.gatein.pc.remotable container-runtime-option</code> value is set to
<code>true</code>.
+ </para>
+
+ </note>
+
+ </section>
+
+ <section
id="sect-Reference_Guide_eXo_JCR_1.14-Web_Services_for_Remote_Portlets_WSRP-Consuming_WSRP_portlets_from_a_remote_Consumer">
+ <title>Consuming WSRP portlets from a remote Consumer</title>
+ <para>
+ Configuration is extremely variable between different WSRP Consumers. Most,
however, require a specification of the URL for the Producer's WSDL definition. If the
JBoss Enterprise Portal Platform Consumer is not being used, refer to the documentation
for the Consumer that is in use for specific instructions.
+ </para>
+ <para>
+ For instructions on how to specify this URL in JBoss Enterprise Portal
Platform, refer to <xref
linkend="sect-Reference_Guide_eXo_JCR_1.14-Web_Services_for_Remote_Portlets_WSRP-Consuming_Remote_WSRP_Portlets"
/>.
+ </para>
+ <para>
+ JBoss Enterprise Portal Platform's Producer is automatically set up when
a portal instance is deployed with the WSRP service.
+ </para>
+ <para>
+ The WSDL file can be accessed at:
+ </para>
+ <variablelist
id="vari-Reference_Guide_eXo_JCR_1.14-Consuming_WSRP_portlets_from_a_remote_Consumer-File_paths">
+ <title>File paths:</title>
+ <varlistentry>
+ <term>WSRP 1.0:</term>
+ <listitem>
+ <para>
+
<filename>http://<replaceable>{hostname}</replaceable>:<replaceable>{port}</replaceable>/wsrp-producer/v1/MarkupService?wsdl</filename>.
+ </para>
+
+ </listitem>
+
+ </varlistentry>
+ <varlistentry>
+ <term>WSRP 2.0:</term>
+ <listitem>
+ <para>
+
<filename>http://<replaceable>{hostname}</replaceable>:<replaceable>{port}</replaceable>/wsrp-producer/v2/MarkupService?wsdl</filename>.
+ </para>
+
+ </listitem>
+
+ </varlistentry>
+
+ </variablelist>
+ <para>
+ The default hostname is <literal>localhost</literal> and the
default port is <literal>8080</literal>.
+ </para>
+
+ </section>
+
+ <section
id="sect-Reference_Guide_eXo_JCR_1.14-Web_Services_for_Remote_Portlets_WSRP-Consuming_Remote_WSRP_Portlets">
+ <title>Consuming Remote WSRP Portlets</title>
+ <section
id="sect-Reference_Guide_eXo_JCR_1.14-Consuming_Remote_WSRP_Portlets-Overview">
+ <title>Overview</title>
+ <para>
+ To be able to consume WSRP portlets exposed by a remote producer, JBoss
Enterprise Portal Platform's WSRP consumer must be configured to access that remote
producer.
+ </para>
+ <para>
+ Access to a remote producer can be configured using the provided
configuration portlet. Alternatively, it is also possible to configure access to remote
producers using an XML descriptor. The configuration portlet is the recommended method.
+ </para>
+ <para>
+ Once a remote producer has been configured, the portlets that it exposes
are then available in the Application Registry to be added to categories and then to
pages.
+ </para>
+ <!-- Removed as out of date and not in Community version of doc.
+ <para>
+ A default consumer named <literal>self</literal>, that
consumes the portlets exposed by JBoss Enterprise Portal Platform's producer, has been
configured as a way to test the WSRP producer service and to check that portlets are
correctly published via WSRP.
+ </para>
+ -->
+ </section>
+
+ <section
id="sect-Reference_Guide_eXo_JCR_1.14-Consuming_Remote_WSRP_Portlets-Configuring_a_Remote_Producer">
+ <title>Configuring a Remote Producer</title>
+ <para>
+ Access to a remote producer needs to be defined so that portlets can be
consumed within JBoss Enterprise Portal Platform. This section will show how to configure
access to <emphasis role="bold">NetUnity</emphasis>'s public
WSRP producer.
+ </para>
+ <para>
+ Firstly using the configuration portlet and then how the same result can
be accomplished with a producer descriptor, though it is far easier to do so via the
configuration portlet.
+ </para>
+ <important>
+ <title>Chunked Encoding</title>
+ <para>
+ Some WSRP producers, such as Oracle, do not support chunked encoding.
If your producer does not support chunked encoding, it will not be able to properly
connect to the producer.
+ </para>
+ <para>
+ This will manifest itself with the following error:
+ </para>
+
+<screen>Caused by: org.jboss.ws.WSException: Invalid HTTP server response [503] -
Service Unavailable.
+</screen>
+ <para>
+ A workaround for this issue involves editing the
<parameter>chunksize</parameter> setting in the
<filename>standard-jaxws-client-config.xml</filename> file.
+ </para>
+ <para>
+ Refer to <ulink type="http"
url="http://community.jboss.org/wiki/Workaroundwhenchunkedencodingis...
for more information.
+ </para>
+
+ </important>
+ <section
id="sect-Reference_Guide_eXo_JCR_1.14-Configuring_a_Remote_Producer-The_Configuration_Portlet">
+ <title>The Configuration Portlet</title>
+ <para>
+ JBoss Enterprise Portal Platform provides a graphical portlet to
assist with configuring access to, and other facets of, remote WSRP Producers.
+ </para>
+ <para>
+ It is available at: <ulink type="http"
url="http://localhost:8080/portal/login?initialURI=%2Fportal%2Fprivate%2Fclassic%2FwsrpConfiguration&username=root&password=gtn"
/>.
+ </para>
+ <para>
+ The portlet also is a group page for /platform/administrators
+ </para>
+ <para>
+ Although the Configuration Portlet is installed by default in JBoss
Enterprise Portal Platform &VY;., installation instructions are included below should
the portlet ever need to be re-installed:
+ </para>
+ <procedure
id="proc-Reference_Guide_eXo_JCR_1.14-The_Configuration_Portlet-Installing_the_configuration_portlet">
+ <title><emphasis role="bold">Installing the
configuration portlet:</emphasis></title>
+ <step>
+ <para>
+ Log into the portal as an administrator and go to the
Application Registry (Click <ulink
url="http://localhost:8080/portal/private/classic/administration/registry">http://localhost:8080/portal/private/classic/administration/registry</ulink>
if using the default installation).
+ </para>
+
+ </step>
+ <step>
+ <para>
+ Add the WSRP Configuration portlet to the Administration
category. If the Import Applications functionality is used, the WSRP Configuration portlet
will be automatically added to the Administration category.
+ </para>
+
+ </step>
+ <step>
+ <para>
+ Once the portlet is added to a category, it can be added to a
page and used. It is recommended that it be added to the same page as the Application
Registry (as other operations relating to WSRP and adding portlets to categories are
somewhat related). Add the WSRP Configuration portlet to the page using the standard
procedure.
+ </para>
+
+ </step>
+
+ </procedure>
+
+ <section
id="sect-Reference_Guide_eXo_JCR_1.14-The_Configuration_Portlet-Using_the_Configuration_portlet">
+ <title><emphasis role="bold">Using the
Configuration portlet</emphasis></title>
+ <mediaobject>
+ <imageobject role="html">
+ <imagedata align="center"
fileref="images/WSRP/config_init.png" format="PNG"
scale="120" width="444" />
+ </imageobject>
+ <imageobject role="fo">
+ <imagedata align="center"
contentwidth="140mm" fileref="images/WSRP/config_init.png"
format="PNG" width="444" />
+ </imageobject>
+
+ </mediaobject>
+ <para>
+ This screen presents all the configured consumers associated with
their status and possible actions on them.
+ </para>
+ <para>
+ A Consumer can be active or inactive. Activating a Consumer means
that it is ready to act as a portlet provider.
+ </para>
+ <para>
+ Note also that a Consumer can be marked as requiring
<emphasis>refresh</emphasis>, which means that the information held about it
might not be up to date. Refreshing it from the remote Producer will update this
information.
+ </para>
+ <para>
+ This can happen for several reasons: the service description for
that remote Producer has not been fetched yet, the cached version has expired or
modifications have been made to the configuration that could potentially invalidate it,
thus requiring re-validation of the information.
+ </para>
+ <para>
+ To create a new Consumer:
+ </para>
+ <procedure
id="proc-Reference_Guide_eXo_JCR_1.14-Using_the_Configuration_portlet-Creating_a_Consumer">
+ <title><emphasis role="bold">Creating a
Consumer</emphasis></title>
+ <step>
+ <para>
+ Type "<literal>netunity</literal>"
into the "<emphasis role="bold">Create a consumer
named:</emphasis>" field.
+ </para>
+
+ </step>
+ <step>
+ <para>
+ Click on "<emphasis
role="bold">Create consumer</emphasis>" to create a new Consumer
called <literal>netunity</literal>.
+ </para>
+ <mediaobject>
+ <imageobject role="html">
+ <imagedata align="center"
fileref="images/WSRP/config_create.png" format="PNG"
scale="100" />
+ </imageobject>
+ <imageobject role="fo">
+ <imagedata align="center"
contentwidth="140mm" fileref="images/WSRP/config_create.png"
format="PNG" />
+ </imageobject>
+
+ </mediaobject>
+
+ </step>
+ <step>
+ <para>
+ In the next form, set the cache expiration value to
<parameter>300</parameter> seconds.
+ </para>
+
+ </step>
+ <step>
+ <para>
+ Leave the default timeout value for web services (WS)
operations.
+ </para>
+
+ </step>
+ <step>
+ <para>
+ Enter the WSDL URL for the producer in the text field.
+ </para>
+
+ </step>
+ <step>
+ <para>
+ Press the "Refresh & Save" button:
+ </para>
+ <mediaobject>
+ <imageobject role="html">
+ <imagedata align="center"
fileref="images/WSRP/config_wsdl.png" format="PNG"
scale="120" width="444" />
+ </imageobject>
+ <imageobject role="fo">
+ <imagedata align="center"
contentwidth="140mm" fileref="images/WSRP/config_wsdl.png"
format="PNG" width="444" />
+ </imageobject>
+
+ </mediaobject>
+
+ </step>
+
+ </procedure>
+
+ <para>
+ This will retrieve the service description associated with the
Producer which WSRP interface is described by the WSDL file found at the URL entered.
+ </para>
+ <para>
+ In this case, querying the service description will show that the
Producer requires registration, that it requested three registration properties and that
the current configuration is missing values for these properties:
+ </para>
+ <mediaobject>
+ <imageobject role="html">
+ <imagedata align="center"
fileref="images/WSRP/config_missing.png" format="PNG"
scale="120" width="444" />
+ </imageobject>
+ <imageobject role="fo">
+ <imagedata align="center"
contentwidth="140mm" fileref="images/WSRP/config_missing.png"
format="PNG" width="444" />
+ </imageobject>
+
+ </mediaobject>
+ <para>
+ This particular producer requests simple
<literal>Yes</literal> or <literal>No</literal> values for the
three registration properties.
+ </para>
+ <para>
+ Enter <literal>No</literal>,
<literal>Yes</literal> and <literal>No</literal> (in that order)
for the values and then pressing the "Refresh & Save" button should
result in:
+ </para>
+ <mediaobject>
+ <imageobject role="html">
+ <imagedata align="center"
fileref="images/WSRP/config_end.png" format="PNG"
scale="120" width="444" />
+ </imageobject>
+ <imageobject role="fo">
+ <imagedata align="center"
contentwidth="140mm" fileref="images/WSRP/config_end.png"
format="PNG" width="444" />
+ </imageobject>
+
+ </mediaobject>
+ <note>
+ <title>Values</title>
+ <para>
+ Unfortunately there is no automated way to learn about which
possible values (if any) are expected by the remote Producer. Possible values may be
indicated in the registration property description but this is not always the case. Refer
to the specific Producer's documentation.
+ </para>
+
+ </note>
+ <para>
+ The Consumer for the <literal>netunity</literal>
Producer should now be available as a portlet provider and be ready to be used.
+ </para>
+ <para>
+ If the producer had required registration but did not require any
registration properties, as is the case for the <literal>selfv2</literal>
consumer (the consumer that accesses the portlets made remotely available by JBoss
Enterprise Portal Platform's producer via WSRP 2), the following screen would have
appeared after pressing the "Refresh & Save" button:
+ </para>
+ <mediaobject>
+ <imageobject role="html">
+ <imagedata align="center"
fileref="images/WSRP/config_refresh.png" format="PNG"
scale="120" width="444" />
+ </imageobject>
+ <imageobject role="fo">
+ <imagedata align="center"
contentwidth="140mm" fileref="images/WSRP/config_refresh.png"
format="PNG" width="444" />
+ </imageobject>
+
+ </mediaobject>
+
+ </section>
+
+
+ </section>
+
+ <section
id="sect-Reference_Guide_eXo_JCR_1.14-Configuring_a_Remote_Producer-Using_XML">
+ <title>Using XML</title>
+ <para>
+ Although using the WSRP Configuration portlet to configure Consumers
is recommended, the WSRP component provides an alternative way to configure consumers.
+ </para>
+ <para>
+ This is done by editing the
<filename><replaceable><JBOSS_HOME></replaceable>/server/<replaceable><PROFILE></replaceable>/conf/gatein/wsrp-consumers-config.xml</filename>
XML file.
+ </para>
+ <!-- Removed in GateIn revision 8119
+<programlisting language="XML" role="XML"><xi:include
href="../extras/WSRP/default257.xml" parse="text"
xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ <para>
+ The file as shown above specifies access to two producers:
<literal>self</literal>, which consumes JBoss Enterprise Portal Platform's
own WSRP producer (albeit in a version that assumes that the producer requires a value for
an <literal>email</literal> registration property), and
<literal>oracle</literal>, which consumes Oracle's public producer, both
in configurations as shown in the procedure above.
+ </para> --> <note>
+ <title>XML Elements</title>
+ <para>
+ An XML Schema defining which elements are available to configure
Consumers via XML can be found in
<filename><replaceable>WSRP_PATH</replaceable>/lib/wsrp-integration-api-<replaceable>WSRP_VERSION</replaceable>.jar/xsd/gatein_wsrp_consumer_1_0.xsd
</filename>
+ </para>
+
+ </note>
+ <!-- Removed in GateIn revision 8119
+
+ <section
id="sect-Reference_Guide_eXo_JCR_1.14-Consuming_Remote_WSRP_Portlets-Configuring_Access_to_Remote_Producers_via_XML">
+ <title>Configuring Access to Remote Producers via XML</title>
+
+ <para>
+ Again, configuring consumers via XML is done by editing
<filename><replaceable>WSRP_PATH</replaceable>/lib/wsrp-consumer-<replaceable>WSRP_VERSION</replaceable>.jar/conf/wsrp-consumers-config.xml</filename>.
+ </para> --> <formalpara
id="form-Reference_Guide_eXo_JCR_1.14-Using_XML-The_Consumer_Configuration_file">
+ <title>The Consumer Configuration file</title>
+ <para>
+ It is important to understand how the XML Consumers configuration
file is processed. It is read the first time the WSRP service starts and the associated
information is then put under control of the JCR (Java Content Repository).
+ </para>
+
+ </formalpara>
+ <para>
+ Subsequent launches of the WSRP service will use the JCR-stored
information for all producers that are already known to JBoss Enterprise Portal Platform.
More specifically, the <filename>wsrp-consumers-config.xml</filename> file is
scanned for producer identifiers. Any identifier that is already known will be bypassed
and the JCR information associated with this remote producer will be used.
+ </para>
+ <para>
+ The information defined at the XML level is only processed for
producer definition for which no information is already present in the JCR.
+ </para>
+ <para>
+ Therefore, to delete a Producer configuration, the associated
information in the database must be deleted (this can be accomplished using the
configuration portlet as shown in <xref
linkend="sect-Reference_Guide_eXo_JCR_1.14-Configuring_a_Remote_Producer-The_Configuration_Portlet"
/> ).
+ </para>
+ <para>
+ The associated information in
<filename>wsrp-consumers-config.xml</filename> (if such information exists)
must also be removed, otherwise the producer will be re-created the next time the WSRP is
launched.
+ </para>
+ <section
id="sect-Reference_Guide_eXo_JCR_1.14-Using_XML-Required_Configuration_Information">
+ <title>Required Configuration Information</title>
+ <para>
+ The following information needs to be provided to configure
access to a remote Producer:
+ </para>
+ <orderedlist>
+ <listitem>
+ <para>
+ An identifier must be provided for the producer being
configured so that it can be referred to later. This is done in the mandatory
<literal>id</literal> attribute of the
<literal><wsrp-producer></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><endpoint-wsdl-url></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><endpoint-wsdl-url></literal> elements are required for
a functional remote producer configuration.
+ </para>
+
+ </section>
+
+ <section
id="sect-Reference_Guide_eXo_JCR_1.14-Using_XML-Optional_Configuration">
+ <title>Optional Configuration</title>
+ <para>
+ It is also possible to provide additional configuration, which,
in some cases, might be important to establish a proper connection to the remote
producer.
+ </para>
+ <variablelist
id="vari-Reference_Guide_eXo_JCR_1.14-Optional_Configuration-Optional_Configurations">
+ <title>Optional Configurations</title>
+ <varlistentry>
+ <term>Caching</term>
+ <listitem>
+ <para>
+ To prevent unnecessary traffic between the local
consumer and the remote producer, it is possible to cache some of the information sent by
the producer (such as the list of offered portlets) for a given duration.
+ </para>
+ <para>
+ The rate at which the information is refreshed is
defined by the <literal>expiration-cache</literal> attribute of the
<literal><wsrp-producer></literal> element (in seconds).
+ </para>
+ <para>
+ For example; providing a value of
<literal>120</literal> for expiration-cache means that the producer
information will not be refreshed for 2 minutes after it has been accessed. If no value is
provided, JBoss Enterprise Portal Platform will always access the remote producer
regardless of whether the remote information has changed or not.
+ </para>
+ <para>
+ Since, in most instances, the information provided by
the producer does not change often, use of this caching facility to minimize bandwidth
usage is recommended.
+ </para>
+
+ </listitem>
+
+ </varlistentry>
+ <varlistentry>
+ <term>WS Timeout</term>
+ <listitem>
+ <para>
+ It is also possible to define a timeout after which
WS operations are considered as failed. This is helpful to avoid blocking the WSRP
service, as it waits on a service that does not answer.
+ </para>
+ <para>
+ Use the <literal>ws-timeout</literal>
attribute of the <literal><wsrp-producer></literal> element to
specify how many milliseconds the WSRP service will wait for a response from the remote
producer before timing out.
+ </para>
+
+ </listitem>
+
+ </varlistentry>
+ <varlistentry>
+ <term>Pre-registration information</term>
+ <listitem>
+ <para>
+ Some producers require consumers to register with
them before authorizing them to access their offered portlets. If known, some registration
information can be provided in the producer configuration beforehand, so that the consumer
can register with the remote producer when required.
+ </para>
+ <note>
+ <para>
+ Only simple String properties are supported. It
is not possible to configure complex registration data. However, this should be sufficient
for most cases.
+ </para>
+
+ </note>
+ <para>
+ This pre-registration configuration is done via the
<literal><registration-data></literal> element.
+ </para>
+ <para>
+ If the remote producer does not require any
registration properties, only an empty
<literal><registration-data></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><property></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><consumer-name></literal> element. When providing a
consumer name, please remember that it should uniquely identify your consumer.
+ </para>
+
+ </listitem>
+
+ </varlistentry>
+
+ </variablelist>
+
+ </section>
+
+
+ </section>
+
+ <section
id="sect-Reference_Guide_eXo_JCR_1.14-Configuring_a_Remote_Producer-Examples">
+ <title>Examples</title>
+ <para>
+ This is the configuration of the
<literal>selfv1</literal> and <literal>selfv2</literal> consumers
as found in <filename>default-wsrp.xml</filename> with a cache expiring every
500 seconds and with a 50 second timeout for web service operations:
+ </para>
+ <note>
+ <para>
+ This file contains the default configuration and should not need
to be edited. If modifications are required, the recommended practice is to follow the
procedure detailed in <xref
linkend="sect-Reference_Guide_eXo_JCR_1.14-The_Configuration_Portlet-Using_the_Configuration_portlet"
/>.
+ </para>
+
+ </note>
+
+<programlisting language="XML" role="XML"><xi:include
href="../extras/WSRP/default258.xml" parse="text"
xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ <para>
+ This is an example of a WSRP descriptor with registration data and
cache expiring every minute:
+ </para>
+
+<programlisting language="XML" role="XML"><xi:include
href="../extras/WSRP/default259.xml" parse="text"
xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+
+ </section>
+
+
+ </section>
+
+ <section
id="sect-Reference_Guide_eXo_JCR_1.14-Consuming_Remote_WSRP_Portlets-Adding_remote_portlets_to_categories">
+ <title>Adding remote portlets to categories</title>
+ <para>
+ Clicking on the Portlet link in the Application Registry will now show
the remote portlets in the <emphasis role="bold">REMOTE</emphasis>
tab in the left column:
+ </para>
+ <mediaobject>
+ <imageobject role="html">
+ <imagedata align="center"
fileref="images/WSRP/remote_portlets.png" format="PNG"
scale="120" width="444" />
+ </imageobject>
+ <imageobject role="fo">
+ <imagedata align="center" contentwidth="140mm"
fileref="images/WSRP/remote_portlets.png" format="PNG"
width="444" />
+ </imageobject>
+
+ </mediaobject>
+ <para>
+ These portlets are available to be used as regular portlets: they can be
used in categories and added to pages. Using the Import Applications functionality will
also automatically import them into categories based on the keywords they define.
+ </para>
+ <para>
+ More specifically, to add a <emphasis>WSRP</emphasis> portlet
to a category, select <literal>wsrp</literal> in the Application Type
drop-down menu:
+ </para>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center"
fileref="images/WSRP/remote_portlets_category.png" format="PNG"
scalefit="1" valign="middle" />
+ </imageobject>
+
+ </mediaobject>
+
+ </section>
+
+
+ </section>
+
+ <section
id="sect-Reference_Guide_eXo_JCR_1.14-Web_Services_for_Remote_Portlets_WSRP-Consumers_Maintenance">
+ <title>Consumers Maintenance</title>
+ <section
id="sect-Reference_Guide_eXo_JCR_1.14-Consumers_Maintenance-Modifying_a_Currently_Held_Registration">
+ <title>Modifying a Currently Held Registration</title>
+ <section
id="sect-Reference_Guide_eXo_JCR_1.14-Modifying_a_Currently_Held_Registration-Registration_Modification_for_Service_Upgrade">
+ <title>Registration Modification for Service Upgrade</title>
+ <para>
+ Producers often offer several levels of service depending on
consumers' subscription levels (for example). This is implemented at the WSRP level
with the registration concept: producers can assert which level of service to provide to
consumers based on the values of given registration properties.
+ </para>
+ <para>
+ There may also be cases where the registration information has
changed and must be updated. For example, the producer required you to provide a valid
email and the previous email address is not valid anymore and needs to be updated.
+ </para>
+ <para>
+ Therefore at times it may be necessary to modify the registration
that sets the service agreement between a consumer and a producer.
+ </para>
+ <para>
+ For example; the producer requiring an email that was configured in
<xref
linkend="sect-Reference_Guide_eXo_JCR_1.14-Configuring_a_Remote_Producer-The_Configuration_Portlet"
/> . In that case the producer was requiring registration and required a value to be
provided for the <literal>email</literal> property.
+ </para>
+ <para>
+ To update the email address that was provided, the remote producer
must be informed that some registration data has been modified.
+ </para>
+ <para>
+ The following procedure assumes access to the producer has been
configured as previously described.
+ </para>
+ <procedure>
+ <step>
+ <para>
+ Go to the configuration screen for the
<literal>self</literal> producer and change the value of
<literal>email</literal> to <literal>foo(a)example.com</literal>
instead of <literal>example(a)example.com</literal>:
+ </para>
+ <mediaobject>
+ <imageobject role="html">
+ <imagedata align="center"
fileref="images/WSRP/modify_reg_start.png" format="PNG"
scale="100" width="444" />
+ </imageobject>
+ <imageobject role="fo">
+ <imagedata align="center"
contentwidth="140mm" fileref="images/WSRP/modify_reg_start.png"
format="PNG" width="444" />
+ </imageobject>
+
+ </mediaobject>
+
+ </step>
+ <step>
+ <para>
+ Click on "<emphasis role="bold">Update
properties</emphasis>" to save the change. A "<emphasis
role="bold">Modify registration</emphasis>" button should now
appear to let you send this new data to the remote producer:
+ </para>
+ <mediaobject>
+ <imageobject role="html">
+ <imagedata align="center"
fileref="images/WSRP/modify_reg_modify.png" format="PNG"
scale="100" width="444" />
+ </imageobject>
+ <imageobject role="fo">
+ <imagedata align="center"
contentwidth="140mm" fileref="images/WSRP/modify_reg_modify.png"
format="PNG" width="444" />
+ </imageobject>
+
+ </mediaobject>
+
+ </step>
+ <step>
+ <para>
+ Click on <emphasis role="bold">Modify
registration</emphasis> and, if the updated registration details have been accepted
by the remote producer the following should appear:
+ </para>
+ <mediaobject>
+ <imageobject role="html">
+ <imagedata align="center"
fileref="images/WSRP/modify_reg_end.png" format="PNG"
scale="120" width="444" />
+ </imageobject>
+ <imageobject role="fo">
+ <imagedata align="center"
contentwidth="140mm" fileref="images/WSRP/modify_reg_end.png"
format="PNG" width="444" />
+ </imageobject>
+
+ </mediaobject>
+
+ </step>
+
+ </procedure>
+
+
+ </section>
+
+ <section
id="sect-Reference_Guide_eXo_JCR_1.14-Modifying_a_Currently_Held_Registration-Registration_Modification_on_Producer_Error">
+ <title>Registration Modification on Producer Error</title>
+ <para>
+ If a Producer administrator changes the requirements for registered
consumers, invoking operations on the producer may fail with an
<exceptionname>OperationFailedFault</exceptionname>. JBoss Enterprise Portal
Platform will attempt to assist in these cases.
+ </para>
+ <para>
+ This section will discuss an example using the
<literal>self</literal> producer.
+ </para>
+ <para>
+ Assuming that the registration requires a valid value for an
<literal>email</literal> registration property (as has been shown) the
configuration screen for this producer should show:
+ </para>
+ <mediaobject>
+ <imageobject role="html">
+ <imagedata align="center"
fileref="images/WSRP/config_self.png" format="PNG"
scale="120" width="444" />
+ </imageobject>
+ <imageobject role="fo">
+ <imagedata align="center"
contentwidth="140mm" fileref="images/WSRP/config_self.png"
format="PNG" width="444" />
+ </imageobject>
+
+ </mediaobject>
+ <para>
+ If the administrator of the producer now requires an additional value
to be provided for a <literal>name</literal> registration property operations
with this producer will fail.
+ </para>
+ <para>
+ If a registration modification is required, go to the configuration
screen for this remote producer and refresh the information held by the consumer by
pressing "<emphasis role="bold">Refresh &
Save</emphasis>":
+ </para>
+ <mediaobject>
+ <imageobject role="html">
+ <imagedata align="center"
fileref="images/WSRP/modify_reg_self.png" format="PNG"
scale="120" width="444" />
+ </imageobject>
+ <imageobject role="fo">
+ <imagedata align="center"
contentwidth="140mm" fileref="images/WSRP/modify_reg_self.png"
format="PNG" width="444" />
+ </imageobject>
+
+ </mediaobject>
+ <para>
+ The configuration screen now shows the currently held registration
information and the expected information from the producer.
+ </para>
+ <para>
+ Enter a value for the <literal>name</literal> property
and then click on "<emphasis role="bold">Modify
registration</emphasis>". If the producer accepts the new registration data,
the following screen will appear:
+ </para>
+ <mediaobject>
+ <imageobject role="html">
+ <imagedata align="center"
fileref="images/WSRP/modify_reg_self_end.png" format="PNG"
scale="120" width="444" />
+ </imageobject>
+ <imageobject role="fo">
+ <imagedata align="center"
contentwidth="140mm" fileref="images/WSRP/modify_reg_self_end.png"
format="PNG" width="444" />
+ </imageobject>
+
+ </mediaobject>
+ <note>
+ <title><emphasis role="bold">JBoss Enterprise
Portal Platform &VY; and WSRP 1 Exceptions</emphasis></title>
+ <para>
+ In WSRP 1, it can be difficult to ascertain what caused an
<exceptionname> OperationFailedFault </exceptionname> as it is a generic
exception returned by producers during a failed method invocation.
+ </para>
+ <para>
+ An
<exceptionname>OperationFailedFault</exceptionname> failure can be caused by
several different reasons, one of them being a request to modify the registration data.
+ </para>
+ <para>
+ In these instances examining the log files may assist in
gathering more information about the problem.
+ </para>
+ <para>
+ WSRP 2 introduces an exception that is specific to a request to
modify registrations which reduces the ambiguity that currently exists.
+ </para>
+
+ </note>
+
+ </section>
+
+
+ </section>
+
+ <section
id="sect-Reference_Guide_eXo_JCR_1.14-Consumers_Maintenance-Consumer_Operations">
+ <title>Consumer Operations</title>
+ <para>
+ Several operations are available from the consumer list view of the WSRP
configuration portlet:
+ </para>
+ <mediaobject>
+ <imageobject role="html">
+ <imagedata align="center"
fileref="images/WSRP/consumer_operations.png" format="PNG"
scale="120" width="444" />
+ </imageobject>
+ <imageobject role="fo">
+ <imagedata align="center" contentwidth="140mm"
fileref="images/WSRP/consumer_operations.png" format="PNG"
width="444" />
+ </imageobject>
+
+ </mediaobject>
+ <para>
+ The available operations are:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>Configure</term>
+ <listitem>
+ <para>
+ Displays the consumer details and allows user to edit them.
+ </para>
+
+ </listitem>
+
+ </varlistentry>
+ <varlistentry>
+ <term>Refresh</term>
+ <listitem>
+ <para>
+ Forces the consumer to retrieve the service description from
the remote producer to refresh the local information (such as offered portlets,
registration information).
+ </para>
+
+ </listitem>
+
+ </varlistentry>
+ <varlistentry>
+ <term>Activate/Deactivate</term>
+ <listitem>
+ <para>
+ Activates or deactivates a consumer, governing whether it
will be available to provide portlets and receive portlet invocations.
+ </para>
+
+ </listitem>
+
+ </varlistentry>
+ <varlistentry>
+ <term>Register/De-register</term>
+ <listitem>
+ <para>
+ Registers or de-registers a consumer based on whether
registration is required and/or acquired.
+ </para>
+
+ </listitem>
+
+ </varlistentry>
+ <varlistentry>
+ <term>Delete</term>
+ <listitem>
+ <para>
+ Destroys the consumer, after de-registering it if it was
registered.
+ </para>
+
+ </listitem>
+
+ </varlistentry>
+
+ </variablelist>
+ <formalpara
id="form-Reference_Guide_eXo_JCR_1.14-Consumer_Operations-Additional_Functionalities_in_WSRP_2.0">
+ <title><emphasis role="bold">Additional
Functionalities in WSRP 2.0</emphasis></title>
+ <para>
+ In addition to those listed above, the WSRP 2.0 implementation in
JBoss Enterprise Portal Platform &VY; also includes the following functions:
+ </para>
+
+ </formalpara>
+ <variablelist
id="vari-Reference_Guide_eXo_JCR_1.14-Consumer_Operations-Additional_Functions">
+ <title>Additional Functions:</title>
+ <varlistentry>
+ <term>Export</term>
+ <listitem>
+ <para>
+ Exports some or all of the consumer's portlets to be able
to later import them in a different context
+ </para>
+
+ </listitem>
+
+ </varlistentry>
+ <varlistentry>
+ <term>Import</term>
+ <listitem>
+ <para>
+ Imports some or all of previously exported portlets.
+ </para>
+
+ </listitem>
+
+ </varlistentry>
+
+ </variablelist>
+ <section
id="sect-Reference_Guide_eXo_JCR_1.14-Consumer_Operations-Importing_and_Exporting_Portlets">
+ <title><emphasis role="bold">Importing and
Exporting Portlets</emphasis></title>
+ <para>
+ Import and export are new functionalities added in WSRP 2.
+ </para>
+ <para>
+ Exporting a portlet allows a consumer to get an opaque representation
of the portlet which can then be use by the corresponding import operation to reconstitute
it.
+ </para>
+ <para>
+ This is mostly used in migration scenarios during batch operations.
Since JBoss Enterprise Portal Platform does not currently support automated migration of
portal data, the functionality provided as part of WSRP 2 is necessarily less complete
than it could be with full portal support.
+ </para>
+ <para>
+ The import/export implementation in JBoss Enterprise Portal Platform
allows users to export portlets from a given consumer and then import them back to replace
existing portlets assigned to windows on pages by the previously exported portlets.
+ </para>
+ <procedure>
+ <title></title>
+ <step>
+ <para>
+ Click on the
"<guilabel>Export</guilabel>" action for a given consumer to display
the list of portlets currently made available by this specific consumer. An example list
is shown below:
+ </para>
+ <mediaobject>
+ <imageobject role="html">
+ <imagedata align="center"
fileref="images/WSRP/export_portlet_list.png" format="PNG"
scale="120" width="444" />
+ </imageobject>
+ <imageobject role="fo">
+ <imagedata align="center"
contentwidth="150mm" fileref="images/WSRP/export_portlet_list.png"
format="PNG" width="444" />
+ </imageobject>
+
+ </mediaobject>
+
+ </step>
+ <step>
+ <para>
+ Once portlets have been selected, they can be exported by
clicking on the "<guilabel>Export</guilabel>" button. This makes
them available for later import:
+ </para>
+ <mediaobject>
+ <imageobject role="html">
+ <imagedata align="center"
fileref="images/WSRP/export_done.png" format="PNG"
scale="120" width="444" />
+ </imageobject>
+ <imageobject role="fo">
+ <imagedata align="center"
contentwidth="150mm" fileref="images/WSRP/export_done.png"
format="PNG" width="444" />
+ </imageobject>
+
+ </mediaobject>
+
+ </step>
+ <step>
+ <para>
+ The portlets can be re-imported directly by pressing the
"<guilabel>Use for import</guilabel>" button or, on the Consumers
list page, using the "<guilabel>Import</guilabel>" action for a
given consumer.
+ </para>
+ <para>
+ The example below assumes that the second option has been
used and that several sets of previously exported portlets are available to import from.
After clicking the action link, a screen similar to the one below should appear:
+ </para>
+ <mediaobject>
+ <imageobject role="html">
+ <imagedata align="center"
fileref="images/WSRP/export_list.png" format="PNG"
scale="120" width="444" />
+ </imageobject>
+ <imageobject role="fo">
+ <imagedata align="center"
contentwidth="150mm" fileref="images/WSRP/export_list.png"
format="PNG" width="444" />
+ </imageobject>
+
+ </mediaobject>
+ <para>
+ This screen presents the list of available exports with
available operations for each.
+ </para>
+ <variablelist
id="vari-Reference_Guide_eXo_JCR_1.14-Importing_and_Exporting_Portlets-Operations">
+ <title>Operations:</title>
+ <varlistentry>
+ <term>View</term>
+ <listitem>
+ <para>
+ Displays the export details as previously seen
when the export was first performed.
+ </para>
+
+ </listitem>
+
+ </varlistentry>
+ <varlistentry>
+ <term>Delete</term>
+ <listitem>
+ <para>
+ Deletes the selected export, asking you for
confirmation first.
+ </para>
+
+ </listitem>
+
+ </varlistentry>
+ <varlistentry>
+ <term>Use for import</term>
+ <listitem>
+ <para>
+ Selects the export to import portlets from.
+ </para>
+
+ </listitem>
+
+ </varlistentry>
+
+ </variablelist>
+
+ </step>
+ <step>
+ <para>
+ Once you have selected an export to import from, you will see
a screen similar to the one below:
+ </para>
+ <mediaobject>
+ <imageobject role="html">
+ <imagedata align="center"
fileref="images/WSRP/import_start.png" format="PNG"
scale="120" width="444" />
+ </imageobject>
+ <imageobject role="fo">
+ <imagedata align="center"
contentwidth="150mm" fileref="images/WSRP/import_start.png"
format="PNG" width="444" />
+ </imageobject>
+
+ </mediaobject>
+ <para>
+ The screen displays the list of available exported portlets
for the previously selected export. You can select which portlet you want to import by
checking the checkbox next to its name.
+ </para>
+
+ </step>
+ <step>
+ <para>
+ Select the content of which window the imported portlet will
replace. This process is done in three steps:
+ </para>
+ <para>
+ This example assumes that you have the following page called
<literal>page1</literal> which contains two windows called
<literal>NetUnity WSRP 2 Interop - Cache Markup (remote)</literal> and
<literal>/samples-remotecontroller-portlet.RemoteControl (remote)</literal>,
as shown below:
+ </para>
+ <mediaobject>
+ <imageobject role="html">
+ <imagedata align="center"
fileref="images/WSRP/import_original_page.png" format="PNG"
scale="120" width="444" />
+ </imageobject>
+ <imageobject role="fo">
+ <imagedata align="center"
contentwidth="150mm" fileref="images/WSRP/import_original_page.png"
format="PNG" width="444" />
+ </imageobject>
+
+ </mediaobject>
+ <para>
+ In this example, we want to replace the content of the
<literal>/samples-remotecontroller-portlet.RemoteControl (remote)</literal>
with the content of the <literal>/ajaxPortlet.JSFAJAXPortlet</literal> portlet
that was previously exported.
+ </para>
+ <procedure>
+ <title></title>
+ <step>
+ <para>
+ Check the box next to the
<literal>/ajaxPortlet.JSFAJAXPortlet</literal> portlet name to indicate that
you want to import its data.
+ </para>
+
+ </step>
+ <step>
+ <para>
+ Select <literal>page1</literal> in the
list of available pages. The screen will then refresh to display the list of available
windows on that page, similar to the image below:
+ </para>
+ <mediaobject>
+ <imageobject role="html">
+ <imagedata align="center"
fileref="images/WSRP/import_selected_page.png" format="PNG"
scale="120" width="444" />
+ </imageobject>
+ <imageobject role="fo">
+ <imagedata align="center"
contentwidth="150mm" fileref="images/WSRP/import_selected_page.png"
format="PNG" width="444" />
+ </imageobject>
+
+ </mediaobject>
+ <note>
+ <title>Note</title>
+ <para>
+ At this point, you still need to select which
window content you want to replace before being able to complete the import operation
+ </para>
+
+ </note>
+
+ </step>
+ <step>
+ <para>
+ Select the
<literal>/samples-remotecontroller-portlet.RemoteControl (remote)</literal>
window, which enables the "<guilabel>Import</guilabel>" button. This
indicates that all the necessary data to perform the import is available.
+ </para>
+
+ </step>
+ <step>
+ <para>
+ Click the
"<guilabel>Import</guilabel>" button. A screen similar to the one
below will appear:
+ </para>
+ <mediaobject>
+ <imageobject role="html">
+ <imagedata align="center"
fileref="images/WSRP/import_success.png" format="PNG"
scale="120" width="444" />
+ </imageobject>
+ <imageobject role="fo">
+ <imagedata align="center"
contentwidth="150mm" fileref="images/WSRP/import_success.png"
format="PNG" width="444" />
+ </imageobject>
+
+ </mediaobject>
+
+ </step>
+
+ </procedure>
+
+
+ </step>
+ <step>
+ <para>
+ The <literal>page1</literal> page should now show
that the content of <literal>/samples-remotecontroller-portlet.RemoteControl
(remote)</literal> window has been replaced by the content of the
<literal>/ajaxPortlet.JSFAJAXPortlet</literal> imported portlet and that the
window has been renamed appropriately.
+ </para>
+ <mediaobject>
+ <imageobject role="html">
+ <imagedata align="center"
fileref="images/WSRP/import_modified_page.png" format="PNG"
scale="120" width="444" />
+ </imageobject>
+ <imageobject role="fo">
+ <imagedata align="center"
contentwidth="150mm" fileref="images/WSRP/import_modified_page.png"
format="PNG" width="444" />
+ </imageobject>
+
+ </mediaobject>
+
+ </step>
+
+ </procedure>
+
+
+ </section>
+
+
+ </section>
+
+ <section
id="sect-Reference_Guide_eXo_JCR_1.14-Consumers_Maintenance-Erasing_Local_Registration_Data">
+ <title>Erasing Local Registration Data</title>
+ <para>
+ In rare cases, it may be necessary to erase the local data without being
able to de-register first.
+ </para>
+ <para>
+ This can occur when a consumer is registered with a producer that has
been modified by its administrator to not require registration any longer.
+ </para>
+ <para>
+ In this scenario, local registration information can be erased from the
consumer to allow it to resume interacting with the remote producer.
+ </para>
+ <para>
+ To do this click on the "<emphasis role="bold">Erase
local registration</emphasis>" button next to the registration context
information on the consumer configuration screen:
+ </para>
+ <mediaobject>
+ <imageobject role="html">
+ <imagedata align="center"
fileref="images/WSRP/erase_registration.png" format="PNG"
scale="80" width="444" />
+ </imageobject>
+ <imageobject role="fo">
+ <imagedata align="center" contentwidth="140mm"
fileref="images/WSRP/erase_registration.png" format="PNG"
width="444" />
+ </imageobject>
+
+ </mediaobject>
+ <warning>
+ <para>
+ This operation is dangerous as it can result in inability to interact
with the remote producer if invoked when not required. The warning message below will be
displayed before any data is erased.
+ </para>
+ <mediaobject>
+ <imageobject role="html">
+ <imagedata align="center"
fileref="images/WSRP/erase_registration_warning.png" format="PNG"
scale="100" width="444" />
+ </imageobject>
+ <imageobject role="fo">
+ <imagedata align="center"
contentwidth="140mm"
fileref="images/WSRP/erase_registration_warning.png" format="PNG"
width="444" />
+ </imageobject>
+
+ </mediaobject>
+
+ </warning>
+
+ </section>
+
+
+ </section>
+
+ <section
id="sect-Reference_Guide_eXo_JCR_1.14-Web_Services_for_Remote_Portlets_WSRP-Configuring_the_WSRP_Producer">
+ <title>Configuring the WSRP Producer</title>
+ <section
id="sect-Reference_Guide_eXo_JCR_1.14-Configuring_the_WSRP_Producer-Overview">
+ <title>Overview</title>
+ <para>
+ The behavior of the Portal's WSRP Producer can be configured using
the WSRP administration interface, (this is the recommended method), or by editing the
<filename><replaceable>WSRP_PATH</replaceable>/lib/gatein.portal.component.wsrp-<replaceable><VERSION></replaceable>-epp-GA.jar/conf/wsrp-producer-config.xml</filename>
file.
+ </para>
+ <para>
+ Several aspects can be modified with respect to whether registration is
required for consumers to access the Producer's services. An XML Schema for the
configuration format is available at
<filename><replaceable>WSRP_PATH</replaceable>/lib/wsrp-integration-api-<replaceable>WSRP_VERSION</replaceable>.jar/xsd/gatein_wsrp_producer_1_0.xsd
</filename>.
+ </para>
+ <para>
+ An alternative to editing the default
<filename>wsrp-producer-config.xml</filename> file is to make a custom copy
containing the required configuration options.
+ </para>
+ <para>
+ If a copy is used in place of the original, however, the
<filename><replaceable>WSRP_PATH</replaceable>/02portal.war/WEB-INF/conf/wsrp/wsrp-configuration.xml</filename>
<emphasis role="bold">must</emphasis> be updated to reference the
custom file (this file defines the component
<literal>WSRPServiceIntegration</literal> and contains a producer and consumer
configuration location).
+ </para>
+
+ </section>
+
+ <section
id="sect-Reference_Guide_eXo_JCR_1.14-Configuring_the_WSRP_Producer-Default_Configuration">
+ <title>Default Configuration</title>
+ <para>
+ The default producer configuration requires that consumers register with
it before providing access to its services. However it does not require any specific
registration properties (excepting those mandated by the WSRP standard).
+ </para>
+ <para>
+ It does, however, require consumers to be registered before sending them
a full service description. This means that the WSRP producer will not provide the list of
offered portlets and other capabilities to unregistered consumers.
+ </para>
+ <para>
+ The producer also uses the default
<classname>RegistrationPolicy</classname> paired with the default
<classname>RegistrationPropertyValidator</classname>.
+ </para>
+ <para>
+ This allows users to customize how Portal's WSRP Producer decides
whether a given registration property is valid or not (however property validators are
discussed in greater detail in <xref
linkend="sect-Reference_Guide_eXo_JCR_1.14-Configuring_the_WSRP_Producer-Registration_Configuration"
/> ).
+ </para>
+ <para>
+ JBoss Enterprise Portal Platform provides a web interface to configure
the producer's behavior. It can be accessed by clicking on the "<emphasis
role="bold">Producer Configuration</emphasis>" tab of the
"<emphasis role="bold">WSRP</emphasis>" page of the
"<emphasis role="bold">admin</emphasis>" portal.
+ </para>
+ <para>
+ The default configuration should show:
+ </para>
+ <mediaobject>
+ <imageobject role="html">
+ <imagedata align="center"
fileref="images/WSRP/producer_default.png" format="PNG"
scale="110" width="444" />
+ </imageobject>
+ <imageobject role="fo">
+ <imagedata align="center" contentwidth="140mm"
fileref="images/WSRP/producer_default.png" format="PNG"
width="444" />
+ </imageobject>
+
+ </mediaobject>
+ <para>
+ You can specify whether or not the producer will send the full service
description to unregistered consumers, and, if it requires registration, which
<literal>RegistrationPolicy</literal> to use (and, if needed, which
<literal>RegistrationPropertyValidator</literal>), along with required
registration property description for which consumers must provide acceptable values to
successfully register.
+ </para>
+ <para>
+ WSDL URLs to access JBoss Enterprise Portal Platform's WSRP producer
are now displayed in either in WSRP 1 or WSRP 2 mode.
+ </para>
+
+ </section>
+
+ <section
id="sect-Reference_Guide_eXo_JCR_1.14-Configuring_the_WSRP_Producer-Registration_Configuration">
+ <title>Registration Configuration</title>
+ <para>
+ In order to have consumers register with Portal's producer the
Portal's behavior with respect to registration must be configured.
+ </para>
+ <para>
+ Registration is optional, as are registration properties. The producer
can require registration without requiring consumers to pass any registration properties
as is the case in the default configuration.
+ </para>
+ <para>
+ The following section discusses configuring a producer's registration
behavior from a blank state:
+ </para>
+ <mediaobject>
+ <imageobject role="html">
+ <imagedata align="center"
fileref="images/WSRP/producer_blank.png" format="PNG"
width="700" />
+ </imageobject>
+ <imageobject role="fo">
+ <imagedata align="center" contentwidth="140mm"
fileref="images/WSRP/producer_blank.png" format="PNG"
width="444" />
+ </imageobject>
+
+ </mediaobject>
+ <procedure>
+ <step>
+ <para>
+ To allow unregistered consumers to see the list of offered
portlets, leave the first checkbox ("<emphasis role="bold">Access to
full service description requires consumers to be registered.</emphasis>")
unchecked.
+ </para>
+
+ </step>
+ <step>
+ <para>
+ To specify, however, that consumers will need to be registered to
be able to interact with the producer, check the second box ("<emphasis
role="bold">Requires registration. Modifying this information will trigger
invalidation of consumer registrations."</emphasis>).
+ </para>
+ <para>
+ The screen will refresh and display:
+ </para>
+ <mediaobject>
+ <imageobject role="html">
+ <imagedata align="center"
fileref="images/WSRP/producer_registration.png" format="PNG"
width="700" />
+ </imageobject>
+ <imageobject role="fo">
+ <imagedata align="center"
contentwidth="140mm" fileref="images/WSRP/producer_registration.png"
format="PNG" width="444" />
+ </imageobject>
+
+ </mediaobject>
+
+ </step>
+ <step>
+ <para>
+ The fully-qualified name for the
<classname>RegistrationPolicy</classname> and
<classname>RegistrationPropertyValidator</classname> can be specified here.
The default values are acceptable. Refer to <xref
linkend="sect-Reference_Guide_eXo_JCR_1.14-Registration_Configuration-Customization_of_Registration_Handling_Behavior"
/> for more information.
+ </para>
+
+ </step>
+ <step>
+ <para>
+ To add a registration property called
<literal>email</literal> click "<emphasis role="bold">Add
property</emphasis>" and enter the appropriate information in the fields,
providing a description for the registration property that can be used by consumers to
determine its purpose:
+ </para>
+ <mediaobject>
+ <imageobject role="html">
+ <imagedata align="center"
fileref="images/WSRP/producer_email.png" format="PNG"
width="700" />
+ </imageobject>
+ <imageobject role="fo">
+ <imagedata align="center"
contentwidth="140mm" fileref="images/WSRP/producer_email.png"
format="PNG" width="444" />
+ </imageobject>
+
+ </mediaobject>
+
+ </step>
+ <step>
+ <para>
+ Press "Save" to record the modifications.
+ </para>
+
+ </step>
+
+ </procedure>
+
+ <note>
+ <para>
+ At this time, only String (<literal>xsd:string</literal>)
properties are supported.
+ </para>
+
+ </note>
+ <note>
+ <para>
+ If consumers are already registered with the producer, modifying the
configuration of required registration information will trigger the invalidation of held
registrations, requiring consumers to modify their registration before being able to
access the producer again. The consumer side of that process is documented in <xref
linkend="sect-Reference_Guide_eXo_JCR_1.14-Modifying_a_Currently_Held_Registration-Registration_Modification_on_Producer_Error"
/>.
+ </para>
+
+ </note>
+ <section
id="sect-Reference_Guide_eXo_JCR_1.14-Registration_Configuration-Customization_of_Registration_Handling_Behavior">
+ <title>Customization of Registration Handling
Behavior</title>
+ <para>
+ Registration handling behavior can be customized by users to suit
their Producer needs. This is done with an implementation of the
<classname>RegistrationPolicy</classname> interface.
+ </para>
+ <para>
+ This interface defines methods that are called by Portal's
Registration service so that decisions can be made appropriately. A default registration
policy that provides basic behavior is provided and should be enough for most user needs.
+ </para>
+ <para>
+ While the default registration policy provides default behavior for
most registration-related aspects, one aspect requires specific configuration: whether a
given value for a registration property is acceptable by the WSRP Producer.
+ </para>
+ <para>
+ This is done by plugging a
<classname>RegistrationPropertyValidator</classname> into the default
registration policy. This allows users to define their own validation mechanism.
+ </para>
+ <para>
+ Refer to the <trademark
class="trade">Javadoc</trademark> for
<classname>org.gatein.registration.RegistrationPolicy</classname> and
<classname>org.gatein.registration.policies.RegistrationPropertyValidator</classname>
for more details on what is expected of each method.
+ </para>
+ <para>
+ A defined registration policy is required for the producer to be
correctly configured. Do this by specifying the qualified class name of the registration
policy.
+ </para>
+ <para>
+ As it is anticipated that most users will use the default
registration policy, it is possible to provide the class name of a custom property
validator instead to customize the default registration policy behavior. Note that
property validators are only used by the default policy.
+ </para>
+ <note>
+ <para>
+ Since the policy or the validator are defined via their class
name and dynamically loaded, it is important to ensure that the identified class is
available to the application server.
+ </para>
+ <para>
+ One way to accomplish that is to deploy the policy implementation
as a JAR file in the AS instance deploy directory.
+ </para>
+ <para>
+ Note also that, since both policies and validators are
dynamically instantiated, they must provide a default, no-argument constructor.
+ </para>
+
+ </note>
+
+ </section>
+
+
+ </section>
+
+ <section
id="sect-Reference_Guide_eXo_JCR_1.14-Configuring_the_WSRP_Producer-WSRP_Validation_Mode">
+ <title>WSRP Validation Mode</title>
+ <para>
+ The lack of conformance kit and the wording of the WSRP specification
leaves room for differing interpretations, resulting in interoperability issues. It is
therefore possible to encounter issues when using consumers from different vendors.
+ </para>
+ <para>
+ Experience of these issues has produced a way to relax the validation
that the WSRP producer performs on the data provided by consumers to help with
interoperability by accepting data that would normally be invalid.
+ </para>
+ <para>
+ Note that the our validation algorithm is only relaxed on aspects of the
specification that are deemed harmless such as invalid language codes.
+ </para>
+ <para>
+ By default, the WSRP producer is configured in strict mode. If you
experience issues with a given consumer, you may attempt to relax the validation mode.
Un-checking the "Use strict WSRP compliance" checkbox on the Producer
configuration screen to do this.
+ </para>
+
+ </section>
+
+
+ </section>
+
+ <section
id="sect-Reference_Guide_eXo_JCR_1.14-Web_Services_for_Remote_Portlets_WSRP-Removing_WSRP">
+ <title>Removing WSRP</title>
+ <para>
+ If you are not going to use WSRP in your JBoss Enterprise Portal Platform
instance, the WSRP configuration files may be left in place. They will not adversely
affect your installation.
+ </para>
+ <para>
+ However, if you wish to completely remove WSRP from your portal installation,
remove the <filename>gatein-wsrp-integration.ear</filename> file from your
application server deploy directory.
+ </para>
+ <!-- <para>
+ However, if you wish to completely remove WSRP from your portal installation,
follow this procedure:
+ </para>
+ <procedure>
+ <title></title>
+ <step>
+ <para>
+ Navigate to the
<filename><replaceable>JBOSS_HOME</replaceable>/server/<replaceable><PROFILE></replaceable>/conf/gatein/</filename>
directory of your JBoss Enterprise Portal Platform instance.
+ </para>
+ <substeps>
+ <step>
+ <para>
+ Open the <filename>configuration.xml</filename>
file and remove the following lines:
+ </para>
+
+<programlisting language="XML"
role="XML"><value>
+ <string>wsrp-producer</string>
+</value>
+</programlisting>
+
+ </step>
+
+ </substeps>
+
+ </step>
+ <step>
+ <para>
+ Navigate up two directory levels and into the
<filename>deploy/gatein.ear/</filename> directory (For example:
<command>cd ../../deploy/gatein.ear/</command>).
+ </para>
+
+ </step>
+ <step>
+ <para>
+ Remove the following files:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <filename>wsrp-admin-gui.war</filename>
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ <filename>wsrp-producer.war</filename>
+ </para>
+
+ </listitem>
+
+ </itemizedlist>
+
+ </step>
+ <step>
+ <para>
+ Navigate into the <filename>lib/</filename> subdirectory
and remove the following files:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+
<filename>gatein.portal.component.wsrp-PORTAL_VERSION.jar</filename>
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+
<filename>wsrp-common-WSRP_VERSION.jar</filename>
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+
<filename>wsrp-consumer-WSRP_VERSION.jar</filename>
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+
<filename>wsrp-integration-api-WSRP_VERSION.jar</filename>
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+
<filename>wsrp-producer-lib-WSRP_VERSION.jar</filename>
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+
<filename>wsrp-wsrp1-ws-WSRP_VERSION.jar</filename>
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+
<filename>wsrp-wsrp2-ws-WSRP_VERSION.jar</filename>
+ </para>
+
+ </listitem>
+
+ </itemizedlist>
+
+ </step>
+ <step>
+ <para>
+ Return to the <filename>gatein.ear/</filename> directory
and move into the <filename>META-INF/</filename> subdirectory.
+ </para>
+ <substeps>
+ <step>
+ <para>
+ Open the <filename>application.xml</filename>
file and remove the following modules:
+ </para>
+
+<programlisting language="XML"
role="XML"><module>
+ <web>
+ <web-uri>wsrp-admin-gui.war</web-uri>
+ <context-root>wsrp-admin-gui</context-root>
+ </web>
+</module>
+</programlisting>
+
+<programlisting language="XML"
role="XML"><module>
+ <web>
+ <web-uri>wsrp-producer.war</web-uri>
+ <context-root>wsrp-producer</context-root>
+ </web>
+</module>
+</programlisting>
+
+ </step>
+ <step>
+ <para>
+ Save and exit the file.
+ </para>
+
+ </step>
+
+ </substeps>
+
+ </step>
+ <step>
+ <para>
+ Return to the <filename>gatein.ear/</filename> directory
and navigate into the <filename>02portal.war/WEB-INF/conf/</filename>
subdirectory.
+ </para>
+ <substeps>
+ <step>
+ <para>
+ Remove the <filename>wsrp/</filename> directory.
+ </para>
+
+ </step>
+ <step>
+ <para>
+ Open the <filename>configuration.xml</filename>
file and remove the following line:
+ </para>
+
+<programlisting language="XML" role="XML"><import
profiles="jboss">war:/conf/wsrp/wsrp-configuration.xml</import>
+</programlisting>
+
+ </step>
+ <step>
+ <para>
+ Save and exit the file.
+ </para>
+
+ </step>
+
+ </substeps>
+
+ </step>
+ <step>
+ <para>
+ From your current location, navigate into the
<filename>portal/</filename> subdirectory.
+ </para>
+ <substeps>
+ <step>
+ <para>
+ Open the
<filename>portal-configuration.xml</filename> file and remove the line:
+ </para>
+
+<programlisting language="XML"
role="XML"><value>org.exoplatform.portal.pom.spi.wsrp.WSRPState</value>
+</programlisting>
+
+ </step>
+ <step>
+ <para>
+ Save and exit the file.
+ </para>
+
+ </step>
+
+ </substeps>
+
+ </step>
+ <step>
+ <para>
+ Return to the <filename>conf/</filename> directory and
move into the <filename>jcr/</filename> subdirectory.
+ </para>
+ <substeps>
+ <step>
+ <para>
+ Open the
<filename>jcr-configuration.xml</filename> file and remove the line:
+ </para>
+
+<programlisting language="XML" role="XML"><property
name="wsrp"
value="http://www.gatein.org/jcr/wsrp/1.0/"/>
+</programlisting>
+
+ </step>
+ <step>
+ <para>
+ Remove the following configuration file references:
+ </para>
+
+<programlisting language="XML"
role="XML"><value>war:/conf/wsrp/consumers-configuration-nodetypes.xml</value>
+<value>war:/conf/wsrp/producer-configuration-nodetypes.xml</value>
+<value>war:/conf/wsrp/producer-registrations-nodetypes.xml</value>
+<value>war:/conf/wsrp/producer-pc-nodetypes.xml</value>
+<value>war:/conf/wsrp/migration-nodetypes.xml</value>
+</programlisting>
+
+ </step>
+ <step>
+ <para>
+ Save and exit the file.
+ </para>
+
+ </step>
+ <step>
+ <para>
+ Open the
<filename>repository-configuration.xml</filename> and remove the <emphasis
role="bold">WSRP</emphasis> workspace:
+ </para>
+
+<programlisting language="XML" role="XML">
+ <workspace name="wsrp-system">
+ <container>
+ <properties>
+ <property name="source-name"
value="${gatein.jcr.datasource.name}${container.name.suffix}"/>
+ <property name="dialect"
value="${gatein.jcr.datasource.dialect}"/>
+ <property name="multi-db" value="false"/>
+ <property name="update-storage"
value="true"/>
+ <property name="max-buffer-size"
value="204800"/>
+ <property name="swap-directory"
value="${gatein.jcr.data.dir}/swap/wsrp${container.name.suffix}"/>
+ </properties>
+ <value-storages>
+ <value-storage id="gadgets"
+ >
+ <properties>
+ <property name="path"
value="${gatein.jcr.storage.data.dir}/wsrp${container.name.suffix}"/>
+ </properties>
+ <filters>
+ <filter property-type="Binary"/>
+ </filters>
+ </value-storage>
+ </value-storages>
+ </container>
+ <initializer>
+ <properties>
+ <property name="root-nodetype"
value="nt:unstructured"/>
+ <property name="root-permissions"
value="*:/platform/administrators read;*:/platform/administrators
add_node;*:/platform/administrators set_property;*:/platform/administrators
remove"/>
+ </properties>
+ </initializer>
+ <cache enabled="true">
+ <properties>
+ <property name="jbosscache-configuration"
value="${gatein.jcr.cache.config}" />
+ <property name="jgroups-configuration"
value="${gatein.jcr.jgroups.config}" />
+ <property name="jgroups-multiplexer-stack"
value="true" />
+ <property name="jbosscache-cluster-name"
value="jcr-${container.name.suffix}-wsrp-system" />
+ </properties>
+ </cache>
+ <query-handler>
+ <properties>
+ <property name="index-dir"
value="${gatein.jcr.index.data.dir}/wsrp-system${container.name.suffix}"/>
+ <property name="changesfilter-class"
value="${gatein.jcr.index.changefilterclass}" />
+ <property name="jbosscache-configuration"
value="${gatein.jcr.index.cache.config}" />
+ <property name="jgroups-configuration"
value="${gatein.jcr.jgroups.config}" />
+ <property name="jgroups-multiplexer-stack"
value="true" />
+ <property name="jbosscache-cluster-name"
value="jcrindexer-${container.name.suffix}-wsrp-system" />
+ <property name="max-volatile-time" value="60"
/>
+ </properties>
+ </query-handler>
+ <lock-manager>
+ <properties>
+ <property name="time-out" value="15m" />
+ <property name="jbosscache-configuration"
value="${gatein.jcr.lock.cache.config}" />
+ <property name="jgroups-configuration"
value="${gatein.jcr.jgroups.config}" />
+ <property name="jgroups-multiplexer-stack"
value="true" />
+ <property name="jbosscache-cluster-name"
value="jcrlock-${container.name.suffix}-wsrp-system" />
+ <property name="jbosscache-cl-cache.jdbc.table.name"
value="jcrlock_wsrp_system" />
+ <property name="jbosscache-cl-cache.jdbc.table.create"
value="true" />
+ <property name="jbosscache-cl-cache.jdbc.table.drop"
value="false" />
+ <property name="jbosscache-cl-cache.jdbc.table.primarykey"
value="pk" />
+ <property name="jbosscache-cl-cache.jdbc.fqn.column"
value="fqn" />
+ <property name="jbosscache-cl-cache.jdbc.node.column"
value="node" />
+ <property name="jbosscache-cl-cache.jdbc.parent.column"
value="parent" />
+ <property name="jbosscache-cl-cache.jdbc.datasource"
value="${gatein.jcr.datasource.name}${container.name.suffix}" />
+ </properties>
+ </lock-manager>
+ </workspace>
+</programlisting>
+
+ </step>
+
+ </substeps>
+
+ </step>
+ <step>
+ <title>Optional:</title>
+ <para>
+ Remove any references to <emphasis>WSRP</emphasis> from
the following files:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+
<filename>gatein.ear/01eXoResources.war/META-INF/MANIFEST.MF</filename>
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+
<filename>gatein.ear/META-INF/MANIFEST.MF</filename>
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+
<filename>gatein.ear/02portal.war/META-INF/MANIFEST.MF</filename>
+ </para>
+
+ </listitem>
+
+ </itemizedlist>
+
+ </step>
+
+ </procedure> -->
+ </section>
+
+
+</chapter>
+
Modified: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/WSRP.xml
===================================================================
--- epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/WSRP.xml 2011-11-24
17:26:22 UTC (rev 8138)
+++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/WSRP.xml 2011-11-25
00:43:12 UTC (rev 8139)
@@ -1,2003 +1,1370 @@
<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-<!ENTITY % BOOK_ENTITIES SYSTEM "Reference_Guide_eXo_JCR_1.14.ent">
-%BOOK_ENTITIES;
-]>
-<chapter
id="chap-Reference_Guide_eXo_JCR_1.14-Web_Services_for_Remote_Portlets_WSRP">
- <title>Web Services for Remote Portlets (WSRP)</title>
- <section
id="sect-Reference_Guide_eXo_JCR_1.14-Web_Services_for_Remote_Portlets_WSRP-Introduction">
- <title>Introduction</title>
- <para>
- The Web Services for Remote Portlets (WSRP) specification defines a web
service interface for accessing and interacting with interactive presentation-oriented web
services.
- </para>
- <para>
- It has been produced through the efforts of the Web Services for Remote
Portlets (WSRP) OASIS Technical Committee. It is based on the requirements gathered and
the proposals made to the committee.
- </para>
- <para>
- Scenarios that motivate WSRP functionality include:
- </para>
+ <!ENTITY % BOOK_ENTITIES SYSTEM "../Reference_Guide.ent">
+ %BOOK_ENTITIES;
+ ]>
+<chapter id="wsrp">
+ <title>Web Services for Remote Portlets (WSRP)</title>
+
+ <section>
+ <title>Introduction</title>
+ <para>The Web Services for Remote Portlets specification defines a web
service interface for accessing and
+ interacting with interactive presentation-oriented web services. It has been
produced through the efforts of
+ the Web Services for Remote Portlets (WSRP) OASIS Technical Committee. It is
based on the requirements
+ gathered and on the concrete proposals made to the committee.
+ </para>
+
+ <para>Scenarios that motivate WSRP functionality include:
<itemizedlist>
<listitem>
- <para>
- Content hosts, such as portal servers, providing Portlets as
presentation-oriented web services that can be used by aggregation engines.
- </para>
-
+ <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>
+ <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>
- </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>
+ <para>More information on WSRP can be found on the
+ <ulink
url="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wsrp...
website for WSRP</ulink>.
+ We suggest reading the
+ <ulink
url="http://www.oasis-open.org/committees/download.php/10539/wsrp-pr...
+ for a good, albeit technical, overview of WSRP.
+ </para>
+ </section>
- </section>
-
- <section
id="sect-Reference_Guide_eXo_JCR_1.14-Web_Services_for_Remote_Portlets_WSRP-Level_of_Support">
- <title>Level of Support</title>
- <para>
- The WSRP Technical Committee defined <ulink
url="http://www.oasis-open.org/committees/download.php/3073">... Use
Profiles</ulink> to help with WSRP interoperability. Terms defined in that document
will be used in this section.
- </para>
- <para>
- JBoss Enterprise Portal Platform provides a
<emphasis>Simple</emphasis> level of support for the WSRP Producer, with the
exception of out-of-band registration. In-band registration and persistent local state
(which are defined at the <emphasis>Complex</emphasis> level) are supported.
- </para>
- <para>
- JBoss Enterprise Portal Platform provides a
<emphasis>Medium</emphasis> level of support for the Consumer, excepting HTML
markup (as JBoss Enterprise Portal Platform itself does not handle other markup types).
Explicit portlet cloning and the <literal>PortletManagement</literal>
interface are supported.
- </para>
- <para>
- The WSRP component has Level 1 Producer and Consumer caching. Cookie handling
is supported properly on the Consumer. The Producer requires cookie initialization (as
this improves interoperability with some consumers).
- </para>
- <para>
- JBoss Enterprise Portal Platform does not support custom window states or
modes, therefore neither does the WSRP component. It does, however, support CSS on both
the Producer (although this is more a function of the portlets than an inherent Producer
capability) and Consumer.
- </para>
- <para>
- JBoss Enterprise Portal Platform &VY; includes implementations of WSRP
1.0 and 2.0.
- </para>
- <para>
- All optional features in WSRP 2 are implemented in JBoss Enterprise Portal
Platform &VY; except support for lifetimes and leasing support.
- </para>
- <note>
- <para>
- As of version &VZ; of Enterprise Portal Platform, WSRP is only
activated and supported when deployed on JBoss Enterprise Application Server.
- </para>
+ <section id="wsrp_support">
+ <title>Level of support in JBoss Enterprise Portal Platform</title>
+ <para>The WSRP Technical Committee defined
+ <ulink
url="http://www.oasis-open.org/committees/download.php/3073">... Use
Profiles</ulink>
+ to help with WSRP interoperability. We will refer to terms defined in that
document in
+ this section.
+ </para>
- </note>
+ <para>JBoss Enterprise Portal Platform provides a Simple level of support for
our WSRP Producer except that out-of-band registration
+ is not currently handled. We support in-band registration and persistent local
state (which are
+ defined at the Complex level).
+ </para>
- </section>
-
- <section
id="sect-Reference_Guide_eXo_JCR_1.14-Web_Services_for_Remote_Portlets_WSRP-Deploying_WSRP">
- <title>Deploying WSRP</title>
- <note>
- <title>Notational Devices</title>
- <para>
- The following list of support files uses the following notational
devices:
- </para>
- <variablelist
id="vari-Reference_Guide_eXo_JCR_1.14-Deploying_WSRP-Notations">
- <title>Notations:</title>
- <varlistentry>
-
<term><replaceable>JBOSS_HOME</replaceable></term>
- <listitem>
- <para>
- <replaceable>JBOSS_HOME</replaceable> refers to
the directory that your instance of JBoss Enterprise Portal Platform has been
extracted/installed to. For example:
<filename>/home/<replaceable>USERNAME</replaceable>/jboss-epp-<replaceable><VERSION></replaceable>/</filename>
- </para>
+ <para>On the Consumer side, JBoss Enterprise Portal Platform provides a
Medium level of support for WSRP, except that we only handle
+ HTML markup (as JBoss Enterprise Portal Platform itself doesn't handle other
markup types). We do support explicit portlet
+ cloning and we fully support the PortletManagement interface.
+ </para>
- </listitem>
+ <para>As far as caching goes, we have Level 1 Producer and Consumer. We
support Cookie handling properly on the
+ Consumer and our Producer requires initialization of cookies (as we have found
that it improved interoperabilty
+ with some consumers). We don't support custom window states or modes, as
JBoss Enterprise Portal Platform doesn't either. We do,
+ however, support CSS on both the Producer (though it's more a function of
the portlets than inherent Producer
+ capability) and Consumer.
+ </para>
- </varlistentry>
- <varlistentry>
-
<term><replaceable>WSRP_PATH</replaceable></term>
- <listitem>
- <para>
- The WSRP files referred to in this section are found in the
<filename><replaceable>JBOSS_HOME</replaceable>/jboss-as/server/<replaceable><PROFILE></replaceable>/deploy/gatein.ear</filename>
directory.
- </para>
- <para>
- For ease of reference this path will be represented by:
<replaceable>WSRP_PATH</replaceable>.
- </para>
+ <para>While we provide a complete implementation of WSRP 1.0, we do need to
go through the
+ <ulink
url="http://www.oasis-open.org/committees/download.php/6018">...
statements</ulink>
+ and perform more interoperability testing (an area that needs to be better
supported by the WSRP Technical
+ Committee and Community at large).
+ </para>
- </listitem>
+ <para>JBoss Enterprise Portal Platform supports WSRP 2.0 with a complete
implementation of the non-optional features. The only
+ features that we have not implemented is support for lifetimes and leasing
+ support.
+ </para>
- </varlistentry>
- <varlistentry>
-
<term><replaceable>WSRP_VERSION</replaceable></term>
- <listitem>
- <para>
- <replaceable>WSRP_VERSION</replaceable>
represents the version of the WSRP component in use.
- </para>
+ <note>
+ <para>As of version &VY; of JBoss Enterprise Portal Platform, WSRP is
only activated and supported
+ when JBoss Enterprise Portal Platform is deployed on JBoss Application
Server.
+ </para>
+ </note>
+ </section>
- </listitem>
+ <section>
+ <title>Deploying JBoss Enterprise Portal Platform's WSRP
services</title>
+ <para>
+ JBoss Enterprise Portal Platform provides a complete support of WSRP 1.0 and 2.0
standard interfaces and offers both consumer and
+ producer services. Starting with version 2.1.0-GA of the component, WSRP is
packaged as a JBoss Enterprise Portal Platform
+ extension and is now self-contained in an easy to install package named
+
<filename>$JBOSS_PROFILE_HOME/deploy/gatein-wsrp-integration.ear</filename>
+ where
+ <filename>$JBOSS_PROFILE_HOME</filename>
+ refers to your JBoss AS profile directory
(<filename>default</filename>, for instance).
+ </para>
+ <para>
+ The extension itself is composed of the following components, assuming
+ <code>$WSRP_VERSION</code>
+ (at the time of the writing, it was 2.1.0-GA) is the version of the WSRP
component and
+ <code>$PORTAL_VERSION</code>
+ (at the time of the writing, it was &VY;) is the current JBoss Enterprise
Portal Platform version:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <filename>META-INF</filename>
+ contains files necessary for EAR packaging. The only file that is of
interest from a user perspective
+ is
+ <filename>gatein-wsse-consumer.xml</filename>
+ which allows you to configure WS-Security support for the consumer.
Please see the
+ <link linkend="wss_configuration">WSRP and
WS-Security</link> section for more details.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+
<filename>extension-component-$PORTAL_VERSION.jar</filename>, which contains
the components needed to
+ integrate the WSRP component into JBoss Enterprise Portal Platform. It
also includes the default configuration files for
+ the WSRP producer and the default WSRP consumers.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <filename>extension-config-$PORTAL_VERSION.jar</filename>,
which contains the configuration file
+ needed by the GateIn extension mechanism to properly register this EAR
as an extension.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <filename>extension-war-$PORTAL_VERSION.war</filename>,
which contains the configuration files
+ needed by the GateIn extension mechanism to properly setup the WSRP
service. It includes
+ <filename>wsrp-configuration.xml</filename>
+ which, in particular, configures several options for the
+ <code>WSRPServiceIntegration</code>
+ component at the heart of the WSRP integration in JBoss Enterprise
Portal Platform.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <filename>lib</filename>, which contains the different
libraries needed by the WSRP service.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <filename>wsrp-admin-gui-$WSRP_VERSION.war</filename>,
which contains the WSRP Configuration portlet
+ with which you can configure consumers to access remote servers and how
the WSRP producer is
+ configured.
+ </para>
+ </listitem>
+ <listitem>
+
<para><filename>wsrp-producer-jb5wsss-$WSRP_VERSION.war</filename>,
which contains the producer-side
+ support for WS-Security. The only file of interest from a user
perspective is
+ <filename>gatein-wsse-producer.xml</filename> which allows
you to configure WS-Security support for
+ the producer. Please see the <link
linkend="wss_configuration">WSRP and WS-Security</link> section
+ for more details.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ If you're not going to use WSRP in JBoss Enterprise Portal Platform, it
won't adversely affect your installation to leave it
+ as-is. Otherwise, you can just remove the
+ <filename>gatein-wsrp-integration.ear</filename>
+ file from your AS deploy directory.
+ </para>
- </varlistentry>
- <varlistentry>
-
<term><replaceable>PORTAL_VERSION</replaceable></term>
- <listitem>
- <para>
- <replaceable>PORTAL_VERSION</replaceable>
represents the version of JBoss Enterprise Portal Platform in use.
- </para>
-
- </listitem>
-
- </varlistentry>
-
- </variablelist>
-
- </note>
+ <section id="wsrp-ports">
+ <title>Considerations to use WSRP when running JBoss Enterprise Portal
Platform on a non-default port or hostname</title>
<para>
- Starting with version 2.1.0-GA of the component, WSRP is packaged as a JBoss
Enterprise Portal Platform extension and is now self-contained in an easy to install
package named <filename>gatein-wsrp-integration.ear</filename>, deployed
directly in the <filename>deploy</filename> directory of your JBoss
Application Server configuration directory.
- </para>
+ JBoss WS (the web service stack that JBoss Enterprise Portal Platform uses)
should take care of the details of updating the
+ port and host name used in WSDL. See the
+ <ulink
url="http://community.jboss.org/wiki/JBossWS-UserGuide#Configuration...
WS user guide on that
+ subject
+ </ulink>
+ for more details.
+ </para>
<para>
- The extension itself is composed of the following components:
- </para>
- <variablelist
id="vari-Reference_Guide_eXo_JCR_1.14-Deploying_WSRP-WSRP_support_files">
- <title>WSRP support files</title>
- <varlistentry>
- <term><filename>META-INF/</filename></term>
- <listitem>
- <para>
- This directory contains files necessary for EAR packaging. The
only file that is of interest from a user perspective is
<filename>gatein-wsse-consumer.xml</filename> which allows you to configure
WS-Security support for the consumer.
- </para>
- <para>
- Refer to <xref
linkend="sect-Reference_Guide_eXo_JCR_1.14-WSRP_and_WS_Security-WS_Security_Configuration"
/> section for more details.
- </para>
+ Of course, if you have modified you have modified the host name and port on
which your server runs, you will
+ need to
+ update the configuration for the consumer used to consume JBoss Enterprise
Portal Platform's 'self' producer. Please refer to
+ the
+ <xref linkend="consumer_configuration"/>
+ to learn how to do so.
+ </para>
+ </section>
+ </section>
- </listitem>
-
- </varlistentry>
- <varlistentry>
-
<term><filename>extension-component-$PORTAL_VERSION.jar</filename></term>
- <listitem>
- <para>
- This archive which contains the components needed to integrate
the WSRP component into JBoss Enterprise Portal Platform. It also includes the default
configuration files for the WSRP producer and the default WSRP consumers.
- </para>
-
- </listitem>
-
- </varlistentry>
- <varlistentry>
-
<term><filename>extension-config-$PORTAL_VERSION.jar</filename></term>
- <listitem>
- <para>
- This file contains the configuration file needed by the GateIn
extension mechanism to properly register this EAR as an extension.
- </para>
-
- </listitem>
-
- </varlistentry>
- <varlistentry>
-
<term><filename>extension-war-$PORTAL_VERSION.war</filename></term>
- <listitem>
- <para>
- This file contains the configuration files needed by the GateIn
extension mechanism to properly setup the WSRP service. It includes
<filename>wsrp-configuration.xml</filename> which, in particular, configures
several options for the <code> WSRPServiceIntegration </code> component at the
heart of the WSRP integration in JBoss Enterprise Portal Platform.
- </para>
-
- </listitem>
-
- </varlistentry>
- <varlistentry>
- <term><filename>lib/</filename></term>
- <listitem>
- <para>
- This directory contains the different libraries needed by the
WSRP service.
- </para>
-
- </listitem>
-
- </varlistentry>
- <varlistentry>
-
<term><filename>wsrp-admin-gui-$WSRP_VERSION.war</filename></term>
- <listitem>
- <para>
- This file contains the WSRP Configuration portlet with which you
can configure consumers to access remote servers and how the WSRP producer is configured.
- </para>
-
- </listitem>
-
- </varlistentry>
- <varlistentry>
-
<term><filename>wsrp-producer-jb5wsss-$WSRP_VERSION.war</filename></term>
- <listitem>
- <para>
- This file contains the producer-side support for WS-Security. The
only file of interest from a user perspective is
<filename>gatein-wsse-producer.xml</filename> which allows you to configure
WS-Security support for the producer.
- </para>
- <para>
- Refer to <xref
linkend="sect-Reference_Guide_eXo_JCR_1.14-WSRP_and_WS_Security-WS_Security_Configuration"
/> for more details.
- </para>
-
- </listitem>
-
- </varlistentry>
-
- </variablelist>
- <section
id="sect-Reference_Guide_eXo_JCR_1.14-Deploying_WSRP-Non_default_Ports_or_Hostnames">
- <title>Non-default Ports or Hostnames</title>
- <para>
- JBoss WS (the web service stack that JBoss Enterprise Portal Platform
uses) should update the port and host name used in WSDL. Refer to the JBoss WS <ulink
url="http://community.jboss.org/wiki/JBossWS-UserGuide#Configuration...
guide</ulink> for more information.
- </para>
- <para>
- If the host name and port on which the server runs have been modified,
the configuration for the Consumer used to consume JBoss Enterprise Portal Platform's
"self" Producer will need to be updated. Refer to <xref
linkend="sect-Reference_Guide_eXo_JCR_1.14-Web_Services_for_Remote_Portlets_WSRP-Consuming_Remote_WSRP_Portlets"
/> for directions on how to do this.
- </para>
-
- </section>
-
- <section
id="sect-Reference_Guide_eXo_JCR_1.14-Deploying_WSRP-Using_WSRP_with_SSL">
- <title>Using WSRP with SSL</title>
- <para>
- It is possible to use WSRP over SSL for secure exchange of data. Refer to
these <ulink
url="http://community.jboss.org/wiki/ConfiguringWSRPforuseoverSSL&qu...
for how to do this.
- </para>
-
- </section>
-
-
- </section>
-
- <section
id="sect-Reference_Guide_eXo_JCR_1.14-Web_Services_for_Remote_Portlets_WSRP-WSRP_and_WS_Security">
+ <section>
+ <title>Securing WSRP</title>
+ <section>
+ <title>Considerations to use WSRP with SSL</title>
+ <para>It is possible to use WSRP over SSL for secure exchange of data.
Please refer to the
+ <ulink
url="http://community.jboss.org/wiki/ConfiguringWSRPforuseoverSSL&qu...
+ on how to do so from
+ <ulink
url="http://community.jboss.org/wiki/GateIn">GateIn's
wiki</ulink>.
+ </para>
+ </section>
+ <section>
<title>WSRP and WS-Security</title>
- <para>
- Portlets may present different data or options depending on the currently
authenticated user. For remote portlets, this means having to propagate the user
credentials from the consumer back to the producer in a safe and secure manner.
+ <para>Portlets may present different data or options depending on the
currently authenticated user. For remote
+ portlets, this means having to propagate the user credentials from the
consumer back to the producer in
+ a safe and secure manner. The WSRP specification does not directly specify
how this should be
+ accomplished, but delegates this work to the existing WS-Security
standards.
</para>
- <para>
- The WSRP specification does not directly specify how this should be
accomplished, but delegates this work to the existing WS-Security standards.
- </para>
- <note>
- <title>Web Container Compatibility</title>
- <para>
- WSRP and WS-Security is currently only supported on JBoss Enterprise
Portal Platform when running on top of JBoss AS 5.
- </para>
-
+ <note>
+ <title>Web Container Compatibility</title>
+ <para>WSRP and WS-Security is currently only supported on JBoss
Enterprise Portal Platform when running on top of JBoss
+ AS 5.
+ </para>
</note>
- <warning>
- <title>Encryption</title>
- <para>
- <emphasis role="bold">The use of encryption is strongly
recommended.</emphasis>
- </para>
- <para>
- Credentials being sent between the consumer and producer should be
encrypted or they will be sent in plain text and could be easily intercepted.
- </para>
- <para>
- You can either configure WS-Security to encrypt and sign the SOAP
messages being sent, or secure the transport layer by using an
<literal>https</literal> endpoint.
- </para>
- <para>
- Failure to encrypt the SOAP message or transport layer will result in the
username and password being sent in plain text.
- </para>
-
+ <warning>
+ <title>Encryption</title>
+ <para>You will want to encrypt the credentials being sent between the
consumer and producer, otherwise they
+ will be sent in plain text and could be easily intercepted. You can
either configure WS-Security to
+ encrypt and sign the SOAP messages being sent, or secure the transport
layer by using an https endpoint.
+ Failure to encrypt the soap message or transport layer will result in the
username and password being
+ sent in plain text. <emphasis role="bold">Use of
encryption is strongly recommended.</emphasis>
+ </para>
</warning>
- <important>
- <title>Credentials</title>
- <para>
- When the consumer sends the user credentials to the producer, it is
sending the credentials for the currently authenticated user in the consumer. This makes
signing in to remote portlets transparent to end users, but also requires that the
producer and consumer use the same credentials.
- </para>
- <para>
- The username and password must be the same and valid on both servers.
- </para>
- <para>
- The recommended approach for this situation would be to use a common LDAP
configuration. Please see the User Guide at <ulink type="http"
url="docs.redhat.com" /> for information on how to configure LDAP for use
with JBoss Enterprise Portal Platform
- </para>
-
+ <important>
+ <title>Credentials</title>
+ <para>When the consumer sends the user credentials to the producer, it is
sending the credentials for the
+ currently authenticated user in the consumer. This makes signing in to
remote portlets transparent
+ to end users, but also requires that the producer and consumer use the
same credentials. This means
+ that the username and password must be the same and valid on both
servers.
+ </para>
+ <para>The recommended approach for this situation would be to use a common
ldap configuration. Please
+ see the user guide on how to configure ldap for use with JBoss Enterprise
Portal Platform
+ </para>
</important>
- <para>
- This community Wiki <ulink
url="http://community.jboss.org/wiki/GateInWSRPAndWebServiceSecurity...;,
also provides a step-by-step example on how to configure WSRP with WS-Security.
+ <para>The GateIn Wiki article, <ulink
url="http://community.jboss.org/wiki/GateInWSRPAndWebServiceSecurity...
+ GateIn WSRP and Web Service Security</ulink>, also provides a
step-by-step example on how to configure
+ WSRP with WS-Security.
</para>
- <section
id="sect-Reference_Guide_eXo_JCR_1.14-WSRP_and_WS_Security-WS_Security_Configuration">
- <title>WS-Security Configuration</title>
- <para>
- JBoss Enterprise Portal Platform uses <application>JBossWS
Native</application> to handle ws-security.
- </para>
- <para>
- Refer to the WS-Security section of the <ulink
url="http://www.jboss.org/jbossas/docs/5-x">JBoss AS 5 Administration and
Configuration Guide </ulink> for in-depth configuration options.
- </para>
- <para>
- Please note that since the consumer passes its credentials to the
producer, the consumer will act at the wss client and the producer will act as the wss
server.
- </para>
- <para>
- The following are the JBossWS Native configuration files which need to be
configure for WSRP:
- </para>
- <variablelist>
- <title></title>
- <varlistentry>
-
<term>gatein-wsrp-integration.ear/META-INF/gatein-wsse-consumer.xml</term>
- <listitem>
- <para>
- BossWS configuration file for the consumer.
- </para>
-
- </listitem>
-
- </varlistentry>
- <varlistentry>
-
<term>gatein-wsrp-integration.ear/wsrp-producer-jb5wss.war/WEB-INF/conf/gatein-wsse-producer.xml</term>
- <listitem>
- <para>
- JBossWS configuration file for the producer.
- </para>
-
- </listitem>
-
- </varlistentry>
-
- </variablelist>
-
+ <section id="wss_configuration">
+ <title>WS-Security Configuration</title>
+ <para>JBoss Enterprise Portal Platform uses JBossWS Native to handle
ws-security. Please see the WS-Security section of the
+ <ulink
url="http://www.jboss.org/jbossas/docs/5-x">JBoss
AS 5 Administration and Configuration Guide
+ </ulink> for indepth configuration options. Please note that since
the consumer passes its credentials
+ to the producer, the consumer will act at the wss client and the producer
will act as the wss server.
+ </para>
+ <para> The following are the JBossWS Native configuration files which
need to be configure for WSRP:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+
<filename>gatein-wsrp-integration.ear/META-INF/gatein-wsse-consumer.xml</filename>:
JBossWS
+ configuration file for the consumer.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+
<filename>gatein-wsrp-integration.ear/wsrp-producer-jb5wss.war/WEB-INF/conf/gatein-wsse-producer.xml
+ </filename>: JBossWS configuration file for the producer.
+ </para>
+ </listitem>
+ </itemizedlist>
</section>
-
- <section
id="sect-Reference_Guide_eXo_JCR_1.14-WSRP_and_WS_Security-WS_Security_Producer_Configuration">
- <title>WS-Security Producer Configuration</title>
- <para>
- Other than the JBossWS configuration file mention above, no other
configuration changes should be necessary for the producer.
- </para>
-
+ <section>
+ <title>WS-Security Producer Configuration</title>
+ <para>
+ Other than the JBossWS configuration file mention above, no other
configuration changes should be necessary
+ for the producer.
+ </para>
</section>
-
- <section
id="sect-Reference_Guide_eXo_JCR_1.14-WSRP_and_WS_Security-WS_Security_Consumer_Configuration">
- <title>WS-Security Consumer Configuration</title>
- <para>
- The consumer requires some changes before it will function properly with
WS-Security.
- </para>
- <para>
- The consumer needs access to the current servlet request since this is
used to retrieve the currently authenticated user. In order to access this information,
the consumer needs a special servlet-filter added to the portal.
- </para>
- <procedure
id="proc-Reference_Guide_eXo_JCR_1.14-WS_Security_Consumer_Configuration-Add_the_servlet_filter">
- <title>Add the servlet-filter</title>
- <step>
- <para>
- Open
<filename><replaceable><JBOSS_HOME></replaceable>/server/<replaceable><PROFILE></replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/web.xml</filename>
and add the following:
- </para>
-
-<programlisting role="XML"><!-- Filter to put request and response
in ServletAccess -->
- <filter>
- <filter-name>ServletAccessFilter</filter-name>
-
<filter-class>org.gatein.wsrp.servlet.ServletAccessFilter</filter-class>
- </filter>
- <filter-mapping>
- <filter-name>ServletAccessFilter</filter-name>
- <url-pattern>/*</url-pattern>
- </filter-mapping>
+ <section>
+ <title>WS-Security Consumer Configuration</title>
+ <para>The consumer requires a few changes before it will function
properly with WS-Security. The consumer
+ needs access to the current servlet request since this is used to
retrieve the currently authenticated
+ user. In order for the consumer to access this information, it needs a
special servlet-filter added to
+ the portal.
+ </para>
+ <para>In
<filename>gatein.ear/02portal.war/WEB-INF/web.xml</filename> add the following
information:
+ </para>
+<programlisting role="XML"><![CDATA[<!-- Filter to put request and
response in ServletAccess -->
+ <filter>
+ <filter-name>ServletAccessFilter</filter-name>
+
<filter-class>org.gatein.wsrp.servlet.ServletAccessFilter</filter-class>
+ </filter>
+ <filter-mapping>
+ <filter-name>ServletAccessFilter</filter-name>
+ <url-pattern>/*</url-pattern>
+ </filter-mapping>]]>
</programlisting>
+ <para>
+ Finally, in the WSRP Configuration portlet, in the consumer configuration
options, you will need to check the 'Enable WS Security' checkbox:
+ </para>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/WSRP/config_wss_selected.png"
format="PNG" align="center" valign="middle"
scalefit="1"/>
+ </imageobject>
+ </mediaobject>
+ </section>
+ <section>
+ <title>WS-Security Consumer Checklist</title>
+ <para>
+ In order for the consumer to handle ws-security, the following steps must be
completed properly
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>The JBossWS configuration files must be
configured</para>
+ </listitem>
+ <listitem>
+ <para>The filter must be added to the portal's
web.xml</para>
+ </listitem>
+ <listitem>
+ <para>the enable wss feature must be check in the wsrp
admin</para>
+ </listitem>
+ </itemizedlist>
+ <para>The consumer will not properly handle ws-security unless all 3 are
properly configured</para>
+ </section>
+ </section>
+ </section>
- </step>
- <step>
- <para>
- Check the <guilabel>Enable WS Security</guilabel>
checkbox in the consumer configuration options of the WSRP Configuration portlet
- </para>
- <mediaobject>
- <imageobject>
- <imagedata align="center"
fileref="images/WSRP/config_wss_selected.png" format="PNG"
scalefit="1" valign="middle" width="444" />
- </imageobject>
+ <section>
+ <title>Making a portlet remotable</title>
+ <important>
+ <para>
+ Only JSR-286 (Portlet 2.0) portlets can be made remotable as the mechanism to
expose a portlet to WSRP
+ relies on a JSR-286-only functionality.
+ </para>
+ </important>
+ <para>JBoss Enterprise Portal Platform does
+ <emphasis role="bold">NOT</emphasis>, by default, expose
local portlets for consumption
+ by remote WSRP consumers. In order to make a portlet remotely available, it must
be made "remotable" by marking
+ it as such in the associated
+ <filename>portlet.xml</filename>. This is accomplished by using a
specific
+ <code>org.gatein.pc.remotable container-runtime-option</code>.
Setting its value to
+ <code>true</code>
+ makes the portlet available for remote consumption, while setting its value to
+ <code>false</code>
+ will not publish it remotely. As specifying the remotable status for a portlet
is optional, you do not need to
+ do anything if you don't need your portlet to be available remotely.
+ </para>
+ <para>In the following example, the "BasicPortlet" portlet is
specified as being remotable.
+ </para>
+ <example>
+ <title>Example</title>
+ <para>
+ <programlisting><![CDATA[
+<?xml version="1.0" standalone="yes"?>
+<portlet-app
xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd"
+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+
xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_2...
http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd"
+ version="2.0">
+<portlet-app>
+ <portlet>
+ <portlet-name>BasicPortlet</portlet-name>
- </mediaobject>
- </step>
- </procedure>
-
+ ...
- </section>
-
- <section>
- <title>WS-Security Consumer Checklist</title>
- <para>
- In order for the consumer to handle ws-security, the following items must
be implemented:
- </para>
- <orderedlist>
- <listitem>
- <para>
- The JBossWS configuration files must be configured
- </para>
+ <container-runtime-option>
+ <name>org.gatein.pc.remotable</name>
+ <value>true</value>
+ </container-runtime-option>
+ </portlet>
+</portlet-app>]]></programlisting>
+ </para>
- </listitem>
- <listitem>
- <para>
- The filter must be added to the portal's web.xml
- </para>
+ </example>
+ <para>
+ It is also possible to specify that all the portlets declared within a given
portlet application to be
+ remotable by default. This is done by specifying the
+ <code>
+ container-runtime-option
+ </code>
+ at the
+ <code>portlet-app</code>
+ element level. Individual portlets can override that value to not be remotely
exposed. Let's look at an
+ example:
+ </para>
+ <example>
+ <title>Example</title>
+ <para>
+ <programlisting><![CDATA[
+<?xml version="1.0" standalone="yes"?>
+<portlet-app
xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd"
+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+
xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_2...
http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd"
+ version="2.0">
+<portlet-app>
- </listitem>
- <listitem>
- <para>
- the enable wss feature must be check in the wsrp admin
- </para>
+ <portlet>
+ <portlet-name>RemotelyExposedPortlet</portlet-name>
+ ...
+ </portlet>
+ <portlet>
+ <portlet-name>NotRemotelyExposedPortlet</portlet-name>
+ ...
+ <container-runtime-option>
+ <name>org.gatein.pc.remotable</name>
+ <value>false</value>
+ </container-runtime-option>
+ </portlet>
- </listitem>
+ <container-runtime-option>
+ <name>org.gatein.pc.remotable</name>
+ <value>true</value>
+ </container-runtime-option>
+</portlet-app>]]>
+ </programlisting>
+ </para>
- </orderedlist>
- <para>
- The consumer will not properly handle ws-security unless all three items
are correctly configured.
- </para>
+ </example>
- </section>
+ <para>
+ In the example above, we defined two portlets. The
+ <code>org.gatein.pc.remotable container-runtime-option</code>
+ being set to
+ <code>true</code>
+ at the
+ <code>portlet-app</code>
+ level, all portlets defined in this particular portlet application are exposed
remotely by JBoss Enterprise Portal Platform's
+ WSRP
+ producer.
+ Note, however, that it is possible to override the default behavior: specifying
a value for the
+ <code>org.gatein.pc.remotable container-runtime-option</code>
+ at the
+ <code>portlet</code>
+ level will take precedence over the default. In the example above, the
+ <varname>RemotelyExposedPortlet</varname>
+ inherits the remotable status defined at the
+ <code>portlet-app</code>
+ level since it does not specify a value for
the<code>org.gatein.pc.remotable container-runtime-option</code>.
+ The<varname>NotRemotelyExposedPortlet</varname>, however, overrides
the default behavior and is not remotely
+ exposed. Note that in the absence of a top-level
+ <code>org.gatein.pc.remotable container-runtime-option</code>
+ value set to<code>true</code>, portlets are NOT remotely exposed.
+ </para>
+ </section>
- </section>
-
- <section
id="sect-Reference_Guide_eXo_JCR_1.14-Web_Services_for_Remote_Portlets_WSRP-Making_a_Portlet_Remotable">
- <title>Making a Portlet Remotable</title>
- <note>
- <para>
- Only JSR-286 (Portlet 2.0) portlets can be made remotable as the
mechanism to expose a portlet to WSRP relies on a JSR-286-only functionality.
- </para>
+ <section>
+ <title>Consuming JBoss Enterprise Portal Platform's WSRP portlets from a
remote Consumer</title>
+ <para>WSRP Producers vary a lot as far as how they are configured. Most of
them require that you specify
+ the URL for the Producer's WSDL definition. Please refer to the remote
producer's documentation for specific
+ instructions. For instructions on how to do so in JBoss Enterprise Portal
Platform, please refer to
+ <xref linkend="consumer_configuration"/>.
+ </para>
+ <para>
+ JBoss Enterprise Portal Platform's Producer is automatically set up when you
deploy a portal instance with the WSRP service.
+ You can access the WSDL file at
+
<filename>http://{hostname}:{port}/wsrp-producer/v2/MarkupService?wsdl</filename>.
If you wish to use only the
+ WSRP 1 compliant version of the producer, please use the WSDL file found at
+
<filename>http://{hostname}:{port}/wsrp-producer/v1/MarkupService?wsdl</filename>.
+ The default hostname is
+ <literal>localhost</literal>
+ and the default port is 8080.
+ </para>
+ </section>
- </note>
+ <section id="consumer_configuration">
+ <title>Consuming remote WSRP portlets in JBoss Enterprise Portal
Platform</title>
+ <section>
+ <title>Overview</title>
<para>
- JBoss Enterprise Portal Platform does <emphasis
role="bold">not</emphasis>, by default, expose local portlets for
consumption by remote WSRP consumers.
- </para>
+ To be able to consume WSRP portlets exposed by a remote producer, JBoss
Enterprise Portal Platform's WSRP consumer needs to
+ know how to access that remote producer. One can configure access to a remote
producer using the provided
+ configuration portlet. Alternatively, it is also possible to configure access
to remote producers using an
+ XML descriptor, though it is recommended (and easier) to do so via the
configuration portlet.
+ </para>
<para>
- 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>
+ Once a remote producer has been configured, the portlets that it exposes are
then available in the
+ Application Registry to be added to categories and then to pages.
+ </para>
+ </section>
+
+ <section id="consumer_gui">
+ <title>Configuring a remote producer using the configuration
portlet</title>
<para>
- A specific <code>org.gatein.pc.remotable
container-runtime-option</code> is used to accomplish this. Setting its value to
<code>true</code> makes the portlet available for remote consumption, while
setting its value to <code>false</code> will not publish it remotely.
- </para>
- <para>
- As specifying the remotable status for a portlet is optional, nothing need be
done if portlets do not need to be remotely available.
- </para>
- <para>
- In the following example, the "BasicPortlet" portlet is specified
as being remotable.
- </para>
-
-<programlisting language="XML" role="XML"><xi:include
href="../extras/WSRP/default255.xml" parse="text"
xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
- <para>
- It is also possible to specify that all the portlets declared within a given
portlet application be remotable by default.
- </para>
- <para>
- This is done by specifying the
<code>container-runtime-option</code> at the
<code>portlet-app</code> element level. Individual portlets can override that
value to not be remotely exposed.
- </para>
- <para>
- For example:
- </para>
-
-<programlisting language="XML" role="XML"><xi:include
href="../extras/WSRP/default256.xml" parse="text"
xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
- <para>
- This example defines two portlets. As the <code>org.gatein.pc.remotable
container-runtime-option</code> is set to <code>true</code> at the
<code>portlet-app</code> level, all portlets defined in this particular
portlet application are exposed remotely by JBoss Enterprise Portal Platform's WSRP
Producer.
- </para>
- <para>
- It is possible to override this default behavior. Specifying a value for the
<code>org.gatein.pc.remotable container-runtime-option</code> at the
<code>portlet</code> level will take precedence over the default.
- </para>
- <para>
- In the example above, the
<literal>RemotelyExposedPortlet</literal> inherits the remotable status
defined at the <code>portlet-app</code> level since it does not specify a
value for the <code>org.gatein.pc.remotable container-runtime-option</code>.
- </para>
- <para>
- The <literal>NotRemotelyExposedPortlet</literal>, however,
overrides the default behavior and is not remotely exposed.
- </para>
+ Let's work through the steps of defining access to a remote producer
using the configuration portlet so that its portlets can be
+ consumed within JBoss Enterprise Portal Platform. We will configure access to
NetUnity's public WSRP producer.
+ </para>
+
<note>
- <title>Note</title>
- <para>
- Portlets are not remotely exposed if no top-level
<code>org.gatein.pc.remotable container-runtime-option</code> value is set to
<code>true</code>.
+ <para>
+ Some WSRP producers do not support chunked encoding that is activated by
default by JBoss WS. If your
+ producer does not support chunked encoding, your consumer will not be able
to properly connect to the
+ producer. This will manifest itself with the following error:
+ <code>Caused by: org.jboss.ws.WSException: Invalid HTTP server
response [503] - Service
+ Unavailable</code>.
+ Please see this GateIn's
+ <ulink
url="http://community.jboss.org/wiki/Workaroundwhenchunkedencodingis...
page
+ </ulink>
+ for more details.
</para>
+ </note>
- </note>
-
- </section>
-
- <section
id="sect-Reference_Guide_eXo_JCR_1.14-Web_Services_for_Remote_Portlets_WSRP-Consuming_WSRP_portlets_from_a_remote_Consumer">
- <title>Consuming WSRP portlets from a remote Consumer</title>
<para>
- Configuration is extremely variable between different WSRP Consumers. Most,
however, require a specification of the URL for the Producer's WSDL definition. If the
JBoss Enterprise Portal Platform Consumer is not being used, refer to the documentation
for the Consumer that is in use for specific instructions.
- </para>
- <para>
- For instructions on how to specify this URL in JBoss Enterprise Portal
Platform, refer to <xref
linkend="sect-Reference_Guide_eXo_JCR_1.14-Web_Services_for_Remote_Portlets_WSRP-Consuming_Remote_WSRP_Portlets"
/>.
- </para>
- <para>
- JBoss Enterprise Portal Platform's Producer is automatically set up when
a portal instance is deployed with the WSRP service.
- </para>
- <para>
- The WSDL file can be accessed at:
- </para>
- <variablelist
id="vari-Reference_Guide_eXo_JCR_1.14-Consuming_WSRP_portlets_from_a_remote_Consumer-File_paths">
- <title>File paths:</title>
- <varlistentry>
- <term>WSRP 1.0:</term>
- <listitem>
- <para>
-
<filename>http://<replaceable>{hostname}</replaceable>:<replaceable>{port}</replaceable>/wsrp-producer/v1/MarkupService?wsdl</filename>.
- </para>
+ JBoss Enterprise Portal Platform provides a portlet to configure access
(among other functions) to remote WSRP Producers
+ grahically. Starting with &VY;, the WSRP configuration portlet is
installed by default. You
+ can find it at
+ <ulink
+
url="http://localhost:8080/portal/login?initialURI=%2Fportal%2Fprivate%2Fclassic%2FwsrpConfiguration&username=root&password=gtn">
+
http://localhost:8080/portal/login?initialURI=%2Fportal%2Fprivate%2Fclass...
+ </ulink>
+ </para>
- </listitem>
-
- </varlistentry>
- <varlistentry>
- <term>WSRP 2.0:</term>
- <listitem>
- <para>
-
<filename>http://<replaceable>{hostname}</replaceable>:<replaceable>{port}</replaceable>/wsrp-producer/v2/MarkupService?wsdl</filename>.
- </para>
-
- </listitem>
-
- </varlistentry>
-
- </variablelist>
<para>
- The default hostname is <literal>localhost</literal> and the
default port is <literal>8080</literal>.
- </para>
+ You should see a screen similar to:
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/WSRP/config_init.png"
format="PNG" align="center" valign="middle"
+ scalefit="1"/>
+ </imageobject>
+ </mediaobject>
+ This screen presents all the configured Consumers associated with their
status and possible actions on
+ them. A Consumer can be active or inactive. Activating a Consumer means that
it is ready to act as a
+ portlet provider. Note also that a Consumer can be marked as requiring
refresh meaning that the
+ information held about it might not be up to date and refreshing it from the
remote Producer might be a
+ good idea. This can happen for several reasons: the service description for
that remote Producer has not
+ been fetched yet, the cached version has expired or modifications have been
made to the configuration
+ that could potentially invalidate it, thus requiring re-validation of the
information.
+ </para>
- </section>
-
- <section
id="sect-Reference_Guide_eXo_JCR_1.14-Web_Services_for_Remote_Portlets_WSRP-Consuming_Remote_WSRP_Portlets">
- <title>Consuming Remote WSRP Portlets</title>
- <section
id="sect-Reference_Guide_eXo_JCR_1.14-Consuming_Remote_WSRP_Portlets-Overview">
- <title>Overview</title>
- <para>
- To be able to consume WSRP portlets exposed by a remote producer, JBoss
Enterprise Portal Platform's WSRP consumer must be configured to access that remote
producer.
+ <note>
+ <para>
+ The WSRP configuration didn't use to be installed by default in
previous versions of JBoss Enterprise Portal Platform.
+ We include here the legacy instructions on how to install this portlet in
case you ever need to
+ re-install it.
</para>
- <para>
- Access to a remote producer can be configured using the provided
configuration portlet. Alternatively, it is also possible to configure access to remote
producers using an XML descriptor. The configuration portlet is the recommended method.
- </para>
- <para>
- Once a remote producer has been configured, the portlets that it exposes
are then available in the Application Registry to be added to categories and then to
pages.
- </para>
- <!-- Removed as out of date and not in Community version of doc.
<para>
- A default consumer named <literal>self</literal>, that
consumes the portlets exposed by JBoss Enterprise Portal Platform's producer, has been
configured as a way to test the WSRP producer service and to check that portlets are
correctly published via WSRP.
+ Use the usual procedure to log in as a Portal administrator and go to the
Application
+ Registry. With the default install, you can just go to
+ <ulink
+
url="http://localhost:8080/portal/login?initialURI=%2Fportal%2Fprivate%2Fclassic%2Fadministration%2Fregistry&username=root&password=gtn">
+
http://localhost:8080/portal/login?initialURI=%2Fportal%2Fprivate%2Fclass...
+ </ulink>
+ Add the WSRP Configuration portlet to the Administration category. If you
use the Import Applications
+ functionality, the WSRP Configuration portlet will be automatically added
to the Administration
+ category.
</para>
- -->
- </section>
-
- <section
id="sect-Reference_Guide_eXo_JCR_1.14-Consuming_Remote_WSRP_Portlets-Configuring_a_Remote_Producer">
- <title>Configuring a Remote Producer</title>
- <para>
- Access to a remote producer needs to be defined so that portlets can be
consumed within JBoss Enterprise Portal Platform. This section will show how to configure
access to <emphasis role="bold">NetUnity</emphasis>'s public
WSRP producer.
- </para>
- <para>
- Firstly using the configuration portlet and then how the same result can
be accomplished with a producer descriptor, though it is far easier to do so via the
configuration portlet.
- </para>
- <important>
- <title>Chunked Encoding</title>
- <para>
- Some WSRP producers, such as Oracle, do not support chunked encoding.
If your producer does not support chunked encoding, it will not be able to properly
connect to the producer.
- </para>
- <para>
- This will manifest itself with the following error:
- </para>
-
-<screen>Caused by: org.jboss.ws.WSException: Invalid HTTP server response [503] -
Service Unavailable.
-</screen>
- <para>
- A workaround for this issue involves editing the
<parameter>chunksize</parameter> setting in the
<filename>standard-jaxws-client-config.xml</filename> file.
- </para>
- <para>
- Refer to <ulink type="http"
url="http://community.jboss.org/wiki/Workaroundwhenchunkedencodingis...
for more information.
- </para>
-
- </important>
- <section
id="sect-Reference_Guide_eXo_JCR_1.14-Configuring_a_Remote_Producer-The_Configuration_Portlet">
- <title>The Configuration Portlet</title>
- <para>
- JBoss Enterprise Portal Platform provides a graphical portlet to
assist with configuring access to, and other facets of, remote WSRP Producers.
- </para>
- <para>
- It is available at: <ulink type="http"
url="http://localhost:8080/portal/login?initialURI=%2Fportal%2Fprivate%2Fclassic%2FwsrpConfiguration&username=root&password=gtn"
/>.
- </para>
- <para>
- The portlet also is a group page for /platform/administrators
- </para>
- <para>
- Although the Configuration Portlet is installed by default in JBoss
Enterprise Portal Platform &VY;., installation instructions are included below should
the portlet ever need to be re-installed:
- </para>
- <procedure
id="proc-Reference_Guide_eXo_JCR_1.14-The_Configuration_Portlet-Installing_the_configuration_portlet">
- <title><emphasis role="bold">Installing the
configuration portlet:</emphasis></title>
- <step>
- <para>
- Log into the portal as an administrator and go to the
Application Registry (Click <ulink
url="http://localhost:8080/portal/private/classic/administration/registry">http://localhost:8080/portal/private/classic/administration/registry</ulink>
if using the default installation).
- </para>
-
- </step>
- <step>
- <para>
- Add the WSRP Configuration portlet to the Administration
category. If the Import Applications functionality is used, the WSRP Configuration portlet
will be automatically added to the Administration category.
- </para>
-
- </step>
- <step>
- <para>
- Once the portlet is added to a category, it can be added to a
page and used. It is recommended that it be added to the same page as the Application
Registry (as other operations relating to WSRP and adding portlets to categories are
somewhat related). Add the WSRP Configuration portlet to the page using the standard
procedure.
- </para>
-
- </step>
-
- </procedure>
-
- <section
id="sect-Reference_Guide_eXo_JCR_1.14-The_Configuration_Portlet-Using_the_Configuration_portlet">
- <title><emphasis role="bold">Using the
Configuration portlet</emphasis></title>
- <mediaobject>
- <imageobject role="html">
- <imagedata align="center"
fileref="images/WSRP/config_init.png" format="PNG"
scale="120" width="444" />
- </imageobject>
- <imageobject role="fo">
- <imagedata align="center"
contentwidth="140mm" fileref="images/WSRP/config_init.png"
format="PNG" width="444" />
- </imageobject>
-
- </mediaobject>
- <para>
- This screen presents all the configured consumers associated with
their status and possible actions on them.
- </para>
- <para>
- A Consumer can be active or inactive. Activating a Consumer means
that it is ready to act as a portlet provider.
- </para>
- <para>
- Note also that a Consumer can be marked as requiring
<emphasis>refresh</emphasis>, which means that the information held about it
might not be up to date. Refreshing it from the remote Producer will update this
information.
- </para>
- <para>
- This can happen for several reasons: the service description for
that remote Producer has not been fetched yet, the cached version has expired or
modifications have been made to the configuration that could potentially invalidate it,
thus requiring re-validation of the information.
- </para>
- <para>
- To create a new Consumer:
- </para>
- <procedure
id="proc-Reference_Guide_eXo_JCR_1.14-Using_the_Configuration_portlet-Creating_a_Consumer">
- <title><emphasis role="bold">Creating a
Consumer</emphasis></title>
- <step>
- <para>
- Type "<literal>netunity</literal>"
into the "<emphasis role="bold">Create a consumer
named:</emphasis>" field.
- </para>
-
- </step>
- <step>
- <para>
- Click on "<emphasis
role="bold">Create consumer</emphasis>" to create a new Consumer
called <literal>netunity</literal>.
- </para>
- <mediaobject>
- <imageobject role="html">
- <imagedata align="center"
fileref="images/WSRP/config_create.png" format="PNG"
scale="100" />
- </imageobject>
- <imageobject role="fo">
- <imagedata align="center"
contentwidth="140mm" fileref="images/WSRP/config_create.png"
format="PNG" />
- </imageobject>
-
- </mediaobject>
-
- </step>
- <step>
- <para>
- In the next form, set the cache expiration value to
<parameter>300</parameter> seconds.
- </para>
-
- </step>
- <step>
- <para>
- Leave the default timeout value for web services (WS)
operations.
- </para>
-
- </step>
- <step>
- <para>
- Enter the WSDL URL for the producer in the text field.
- </para>
-
- </step>
- <step>
- <para>
- Press the "Refresh & Save" button:
- </para>
- <mediaobject>
- <imageobject role="html">
- <imagedata align="center"
fileref="images/WSRP/config_wsdl.png" format="PNG"
scale="120" width="444" />
- </imageobject>
- <imageobject role="fo">
- <imagedata align="center"
contentwidth="140mm" fileref="images/WSRP/config_wsdl.png"
format="PNG" width="444" />
- </imageobject>
-
- </mediaobject>
-
- </step>
-
- </procedure>
-
- <para>
- This will retrieve the service description associated with the
Producer which WSRP interface is described by the WSDL file found at the URL entered.
- </para>
- <para>
- In this case, querying the service description will show that the
Producer requires registration, that it requested three registration properties and that
the current configuration is missing values for these properties:
- </para>
- <mediaobject>
- <imageobject role="html">
- <imagedata align="center"
fileref="images/WSRP/config_missing.png" format="PNG"
scale="120" width="444" />
- </imageobject>
- <imageobject role="fo">
- <imagedata align="center"
contentwidth="140mm" fileref="images/WSRP/config_missing.png"
format="PNG" width="444" />
- </imageobject>
-
- </mediaobject>
- <para>
- This particular producer requests simple
<literal>Yes</literal> or <literal>No</literal> values for the
three registration properties.
- </para>
- <para>
- Enter <literal>No</literal>,
<literal>Yes</literal> and <literal>No</literal> (in that order)
for the values and then pressing the "Refresh & Save" button should
result in:
- </para>
- <mediaobject>
- <imageobject role="html">
- <imagedata align="center"
fileref="images/WSRP/config_end.png" format="PNG"
scale="120" width="444" />
- </imageobject>
- <imageobject role="fo">
- <imagedata align="center"
contentwidth="140mm" fileref="images/WSRP/config_end.png"
format="PNG" width="444" />
- </imageobject>
-
- </mediaobject>
- <note>
- <title>Values</title>
- <para>
- Unfortunately there is no automated way to learn about which
possible values (if any) are expected by the remote Producer. Possible values may be
indicated in the registration property description but this is not always the case. Refer
to the specific Producer's documentation.
- </para>
-
- </note>
- <para>
- The Consumer for the <literal>netunity</literal>
Producer should now be available as a portlet provider and be ready to be used.
- </para>
- <para>
- If the producer had required registration but did not require any
registration properties, as is the case for the <literal>selfv2</literal>
consumer (the consumer that accesses the portlets made remotely available by JBoss
Enterprise Portal Platform's producer via WSRP 2), the following screen would have
appeared after pressing the "Refresh & Save" button:
- </para>
- <mediaobject>
- <imageobject role="html">
- <imagedata align="center"
fileref="images/WSRP/config_refresh.png" format="PNG"
scale="120" width="444" />
- </imageobject>
- <imageobject role="fo">
- <imagedata align="center"
contentwidth="140mm" fileref="images/WSRP/config_refresh.png"
format="PNG" width="444" />
- </imageobject>
-
- </mediaobject>
-
- </section>
-
-
- </section>
-
- <section
id="sect-Reference_Guide_eXo_JCR_1.14-Configuring_a_Remote_Producer-Using_XML">
- <title>Using XML</title>
- <para>
- Although using the WSRP Configuration portlet to configure Consumers
is recommended, the WSRP component provides an alternative way to configure consumers.
- </para>
- <para>
- This is done by editing the
<filename><replaceable><JBOSS_HOME></replaceable>/server/<replaceable><PROFILE></replaceable>/conf/gatein/wsrp-consumers-config.xml</filename>
XML file.
- </para>
- <!-- Removed in GateIn revision 8119
-<programlisting language="XML" role="XML"><xi:include
href="../extras/WSRP/default257.xml" parse="text"
xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
- <para>
- The file as shown above specifies access to two producers:
<literal>self</literal>, which consumes JBoss Enterprise Portal Platform's
own WSRP producer (albeit in a version that assumes that the producer requires a value for
an <literal>email</literal> registration property), and
<literal>oracle</literal>, which consumes Oracle's public producer, both
in configurations as shown in the procedure above.
- </para> --> <note>
- <title>XML Elements</title>
- <para>
- An XML Schema defining which elements are available to configure
Consumers via XML can be found in
<filename><replaceable>WSRP_PATH</replaceable>/lib/wsrp-integration-api-<replaceable>WSRP_VERSION</replaceable>.jar/xsd/gatein_wsrp_consumer_1_0.xsd
</filename>
- </para>
-
- </note>
- <!-- Removed in GateIn revision 8119
-
- <section
id="sect-Reference_Guide_eXo_JCR_1.14-Consuming_Remote_WSRP_Portlets-Configuring_Access_to_Remote_Producers_via_XML">
- <title>Configuring Access to Remote Producers via XML</title>
-
<para>
- Again, configuring consumers via XML is done by editing
<filename><replaceable>WSRP_PATH</replaceable>/lib/wsrp-consumer-<replaceable>WSRP_VERSION</replaceable>.jar/conf/wsrp-consumers-config.xml</filename>.
- </para> --> <formalpara
id="form-Reference_Guide_eXo_JCR_1.14-Using_XML-The_Consumer_Configuration_file">
- <title>The Consumer Configuration file</title>
- <para>
- It is important to understand how the XML Consumers configuration
file is processed. It is read the first time the WSRP service starts and the associated
information is then put under control of the JCR (Java Content Repository).
- </para>
-
- </formalpara>
- <para>
- Subsequent launches of the WSRP service will use the JCR-stored
information for all producers that are already known to JBoss Enterprise Portal Platform.
More specifically, the <filename>wsrp-consumers-config.xml</filename> file is
scanned for producer identifiers. Any identifier that is already known will be bypassed
and the JCR information associated with this remote producer will be used.
- </para>
- <para>
- The information defined at the XML level is only processed for
producer definition for which no information is already present in the JCR.
- </para>
- <para>
- Therefore, to delete a Producer configuration, the associated
information in the database must be deleted (this can be accomplished using the
configuration portlet as shown in <xref
linkend="sect-Reference_Guide_eXo_JCR_1.14-Configuring_a_Remote_Producer-The_Configuration_Portlet"
/> ).
- </para>
- <para>
- The associated information in
<filename>wsrp-consumers-config.xml</filename> (if such information exists)
must also be removed, otherwise the producer will be re-created the next time the WSRP is
launched.
- </para>
- <section
id="sect-Reference_Guide_eXo_JCR_1.14-Using_XML-Required_Configuration_Information">
- <title>Required Configuration Information</title>
- <para>
- The following information needs to be provided to configure
access to a remote Producer:
- </para>
- <orderedlist>
- <listitem>
- <para>
- An identifier must be provided for the producer being
configured so that it can be referred to later. This is done in the mandatory
<literal>id</literal> attribute of the
<literal><wsrp-producer></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><endpoint-wsdl-url></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><endpoint-wsdl-url></literal> elements are required for
a functional remote producer configuration.
- </para>
-
- </section>
-
- <section
id="sect-Reference_Guide_eXo_JCR_1.14-Using_XML-Optional_Configuration">
- <title>Optional Configuration</title>
- <para>
- It is also possible to provide additional configuration, which,
in some cases, might be important to establish a proper connection to the remote
producer.
- </para>
- <variablelist
id="vari-Reference_Guide_eXo_JCR_1.14-Optional_Configuration-Optional_Configurations">
- <title>Optional Configurations</title>
- <varlistentry>
- <term>Caching</term>
- <listitem>
- <para>
- To prevent unnecessary traffic between the local
consumer and the remote producer, it is possible to cache some of the information sent by
the producer (such as the list of offered portlets) for a given duration.
- </para>
- <para>
- The rate at which the information is refreshed is
defined by the <literal>expiration-cache</literal> attribute of the
<literal><wsrp-producer></literal> element (in seconds).
- </para>
- <para>
- For example; providing a value of
<literal>120</literal> for expiration-cache means that the producer
information will not be refreshed for 2 minutes after it has been accessed. If no value is
provided, JBoss Enterprise Portal Platform will always access the remote producer
regardless of whether the remote information has changed or not.
- </para>
- <para>
- Since, in most instances, the information provided by
the producer does not change often, use of this caching facility to minimize bandwidth
usage is recommended.
- </para>
-
- </listitem>
-
- </varlistentry>
- <varlistentry>
- <term>WS Timeout</term>
- <listitem>
- <para>
- It is also possible to define a timeout after which
WS operations are considered as failed. This is helpful to avoid blocking the WSRP
service, as it waits on a service that does not answer.
- </para>
- <para>
- Use the <literal>ws-timeout</literal>
attribute of the <literal><wsrp-producer></literal> element to
specify how many milliseconds the WSRP service will wait for a response from the remote
producer before timing out.
- </para>
-
- </listitem>
-
- </varlistentry>
- <varlistentry>
- <term>Pre-registration information</term>
- <listitem>
- <para>
- Some producers require consumers to register with
them before authorizing them to access their offered portlets. If known, some registration
information can be provided in the producer configuration beforehand, so that the consumer
can register with the remote producer when required.
- </para>
- <note>
- <para>
- Only simple String properties are supported. It
is not possible to configure complex registration data. However, this should be sufficient
for most cases.
- </para>
-
- </note>
- <para>
- This pre-registration configuration is done via the
<literal><registration-data></literal> element.
- </para>
- <para>
- If the remote producer does not require any
registration properties, only an empty
<literal><registration-data></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><property></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><consumer-name></literal> element. When providing a
consumer name, please remember that it should uniquely identify your consumer.
- </para>
-
- </listitem>
-
- </varlistentry>
-
- </variablelist>
-
- </section>
-
-
- </section>
-
- <section
id="sect-Reference_Guide_eXo_JCR_1.14-Configuring_a_Remote_Producer-Examples">
- <title>Examples</title>
- <para>
- This is the configuration of the
<literal>selfv1</literal> and <literal>selfv2</literal> consumers
as found in <filename>default-wsrp.xml</filename> with a cache expiring every
500 seconds and with a 50 second timeout for web service operations:
- </para>
- <note>
- <para>
- This file contains the default configuration and should not need
to be edited. If modifications are required, the recommended practice is to follow the
procedure detailed in <xref
linkend="sect-Reference_Guide_eXo_JCR_1.14-The_Configuration_Portlet-Using_the_Configuration_portlet"
/>.
- </para>
-
- </note>
-
-<programlisting language="XML" role="XML"><xi:include
href="../extras/WSRP/default258.xml" parse="text"
xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
- <para>
- This is an example of a WSRP descriptor with registration data and
cache expiring every minute:
- </para>
-
-<programlisting language="XML" role="XML"><xi:include
href="../extras/WSRP/default259.xml" parse="text"
xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
-
- </section>
-
-
- </section>
-
- <section
id="sect-Reference_Guide_eXo_JCR_1.14-Consuming_Remote_WSRP_Portlets-Adding_remote_portlets_to_categories">
- <title>Adding remote portlets to categories</title>
- <para>
- Clicking on the Portlet link in the Application Registry will now show
the remote portlets in the <emphasis role="bold">REMOTE</emphasis>
tab in the left column:
+ Now that the portlet is added to a category, it can be added to a page and
used. We recommend adding
+ it to the same page as the Application Registry as operations relating to
WSRP and adding portlets to
+ categories are somewhat related as we will see. Go ahead and add the WSRP
Configuration portlet to the
+ page using the standard procedure.
</para>
- <mediaobject>
- <imageobject role="html">
- <imagedata align="center"
fileref="images/WSRP/remote_portlets.png" format="PNG"
scale="120" width="444" />
- </imageobject>
- <imageobject role="fo">
- <imagedata align="center" contentwidth="140mm"
fileref="images/WSRP/remote_portlets.png" format="PNG"
width="444" />
- </imageobject>
+ </note>
+ <para>
+ Next, we create a new Consumer which we will call
<literal>netunity</literal>. Type
+ "<literal>netunity</literal>" in
+ the "Create a consumer named:" field then click on "Create
consumer":
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/WSRP/config_create.png"
format="PNG" align="center" valign="middle"
+ scalefit="1"/>
+ </imageobject>
</mediaobject>
- <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>
-
+ You should now see a form allowing you to enter/modify the information about
the Consumer.
+ Set the cache expiration value to 300 seconds, leave the default timeout
value for web services (WS)
+ operations and enter the WSDL URL for the producer in the text field
+ and press the "Refresh & Save" button:
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/WSRP/config_wsdl.png"
format="PNG" align="center" valign="middle"
+ scalefit="1"/>
+ </imageobject>
</mediaobject>
+ This will retrieve the service description associated with the Producer which
WSRP interface is described
+ by the WSDL file found at the URL you just entered. In our case, querying the
service description will
+ allow us to learn that the Producer requires registration, requested three
registration properties and that
+ we are missing values for these properties:
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/WSRP/config_missing.png"
format="PNG" align="center" valign="middle"
+ scalefit="1"/>
+ </imageobject>
+ </mediaobject>
+ This particular producer requests simple
+ <literal>Yes</literal>
+ or
+ <literal>No</literal>
+ values for the three registration properties. Entering
<literal>No</literal>,
+ <literal>Yes</literal>
+ and
+ <literal>No</literal>
+ (in that order) for the values and then pressing the "Refresh &
Save" button should result in:
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/WSRP/config_end.png"
format="PNG" align="center" valign="middle"
+ scalefit="1"/>
+ </imageobject>
+ </mediaobject>
- </section>
-
+ <note>
+ <para>At this point, there is no automated way to learn about which
possible values (if any) are
+ expected by the remote Producer. Sometimes, the possible values will be
indicated in the
+ registration
+ property description but this is not always the case... Please refer to
the specific Producer's
+ documentation.
+ </para>
+ </note>
+ </para>
- </section>
-
- <section
id="sect-Reference_Guide_eXo_JCR_1.14-Web_Services_for_Remote_Portlets_WSRP-Consumers_Maintenance">
- <title>Consumers Maintenance</title>
- <section
id="sect-Reference_Guide_eXo_JCR_1.14-Consumers_Maintenance-Modifying_a_Currently_Held_Registration">
- <title>Modifying a Currently Held Registration</title>
- <section
id="sect-Reference_Guide_eXo_JCR_1.14-Modifying_a_Currently_Held_Registration-Registration_Modification_for_Service_Upgrade">
- <title>Registration Modification for Service Upgrade</title>
- <para>
- Producers often offer several levels of service depending on
consumers' subscription levels (for example). This is implemented at the WSRP level
with the registration concept: producers can assert which level of service to provide to
consumers based on the values of given registration properties.
- </para>
- <para>
- There may also be cases where the registration information has
changed and must be updated. For example, the producer required you to provide a valid
email and the previous email address is not valid anymore and needs to be updated.
- </para>
- <para>
- Therefore at times it may be necessary to modify the registration
that sets the service agreement between a consumer and a producer.
- </para>
- <para>
- For example; the producer requiring an email that was configured in
<xref
linkend="sect-Reference_Guide_eXo_JCR_1.14-Configuring_a_Remote_Producer-The_Configuration_Portlet"
/> . In that case the producer was requiring registration and required a value to be
provided for the <literal>email</literal> property.
- </para>
- <para>
- To update the email address that was provided, the remote producer
must be informed that some registration data has been modified.
- </para>
- <para>
- The following procedure assumes access to the producer has been
configured as previously described.
- </para>
- <procedure>
- <step>
- <para>
- Go to the configuration screen for the
<literal>self</literal> producer and change the value of
<literal>email</literal> to <literal>foo(a)example.com</literal>
instead of <literal>example(a)example.com</literal>:
- </para>
- <mediaobject>
- <imageobject role="html">
- <imagedata align="center"
fileref="images/WSRP/modify_reg_start.png" format="PNG"
scale="100" width="444" />
- </imageobject>
- <imageobject role="fo">
- <imagedata align="center"
contentwidth="140mm" fileref="images/WSRP/modify_reg_start.png"
format="PNG" width="444" />
- </imageobject>
+ <para>
+ If we had been dealing with a producer which required registration but
didn't require any registration
+ properties, as is the case for the
+ <literal>selfv2</literal>
+ consumer (the consumer that accesses the portlets made remotely available by
JBoss Enterprise Portal Platform's producer via
+ WSRP 2), we'd have seen something similar to, after pressing the
"Refresh & Save" button:
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/WSRP/config_refresh.png"
format="PNG" align="center" valign="middle"
+ scalefit="1"/>
+ </imageobject>
+ </mediaobject>
+ </para>
+ </section>
- </mediaobject>
+ <section id="consumer_xml">
+ <title>Configuring access to remote producers via XML</title>
- </step>
- <step>
- <para>
- Click on "<emphasis role="bold">Update
properties</emphasis>" to save the change. A "<emphasis
role="bold">Modify registration</emphasis>" button should now
appear to let you send this new data to the remote producer:
- </para>
- <mediaobject>
- <imageobject role="html">
- <imagedata align="center"
fileref="images/WSRP/modify_reg_modify.png" format="PNG"
scale="100" width="444" />
- </imageobject>
- <imageobject role="fo">
- <imagedata align="center"
contentwidth="140mm" fileref="images/WSRP/modify_reg_modify.png"
format="PNG" width="444" />
- </imageobject>
+ <para>While we recommend you use the WSRP Configuration portlet to
configure Consumers, we provide an
+ alternative way to configure consumers by adding an XML file called
+ <filename>wsrp-consumers-config.xml</filename> in the
+ <filename>$JBOSS_PROFILE_HOME/conf/gatein/</filename>
directory.
+ <note>
+ <para>An XML Schema defining which elements are available to
configure Consumers via XML can be found
+ in
+ <filename>
+
$JBOSS_PROFILE_HOME/deploy/gatein-wsrp-integration.ear/lib/wsrp-integration-api-$WSRP_VERSION.jar/xsd/gatein_wsrp_consumer_1_0.xsd
+ </filename>
+ </para>
+ </note>
+ <important>
+ <para>
+ It is important to note that once the XML configuration file for
consumers has been read upon
+ the WSRP service first start, the associated information is put under
control of JCR (Java Content
+ Repository). Subsequent launches of the WSRP service will use the
JCR-stored information and ignore
+ the content of the XML configuration file.
+ </para>
- </mediaobject>
+ <!--<para>It is important to note how the XML consumers
configuration file is processed. It is read the first
+ time the WSRP service starts and the associated information is then put
under control of JCR (Java
+ Content Repository). Subsequent launches of the WSRP service will use
the JCR-stored information for
+ all producers already known to JBoss Enterprise Portal Platform. More
specifically, the
+ <filename>wsrp-consumers-config.xml</filename>
+ file is scanned for producer identifiers.
+ Any identifier that is already known will be bypassed and the JCR
information associated with this
+ remote producer will be used. The information defined at the XML level
is only processed for producer
+ definition for which no information is already present in JCR.
Therefore, if you wish to delete a
+ producer configuration, you need to delete the associated information
in the database (this can be
+ accomplished using the configuration portlet as we saw in
+ <xref linkend="consumer_gui"/>)
+ <emphasis>AND</emphasis>
+ remove the associated information in
+ <filename>wsrp-consumers-config.xml</filename>
+ (if such information exists) as the producer will be re-created the
next time the WSRP is launched if
+ that information is not removed.
+ </para>-->
+ </important>
+ </para>
- </step>
- <step>
- <para>
- Click on <emphasis role="bold">Modify
registration</emphasis> and, if the updated registration details have been accepted
by the remote producer the following should appear:
- </para>
- <mediaobject>
- <imageobject role="html">
- <imagedata align="center"
fileref="images/WSRP/modify_reg_end.png" format="PNG"
scale="120" width="444" />
- </imageobject>
- <imageobject role="fo">
- <imagedata align="center"
contentwidth="140mm" fileref="images/WSRP/modify_reg_end.png"
format="PNG" width="444" />
- </imageobject>
+ <section>
+ <title>Required configuration information</title>
- </mediaobject>
+ <para>Let's now look at which information needs to be provided to
configure access to a remote producer.
+ </para>
- </step>
+ <para>First, we need to provide an identifier for the producer we are
configuring so that we can refer to it
+ afterwards. This is accomplished via the mandatory
+ <literal>id</literal>
+ attribute of the
+ <literal><wsrp-producer></literal>
+ element.
+ </para>
- </procedure>
-
+ <para>JBoss Enterprise Portal Platform also needs to learn about the
remote producer's endpoints to be able to connect to the
+ remote web services and perform WSRP invocations. This is accomplished by
specifying the URL for the
+ WSDL description for the remote WSRP service, using the
+ <literal><endpoint-wsdl-url></literal>
+ element.
+ </para>
- </section>
-
- <section
id="sect-Reference_Guide_eXo_JCR_1.14-Modifying_a_Currently_Held_Registration-Registration_Modification_on_Producer_Error">
- <title>Registration Modification on Producer Error</title>
- <para>
- If a Producer administrator changes the requirements for registered
consumers, invoking operations on the producer may fail with an
<exceptionname>OperationFailedFault</exceptionname>. JBoss Enterprise Portal
Platform will attempt to assist in these cases.
- </para>
- <para>
- This section will discuss an example using the
<literal>self</literal> producer.
- </para>
- <para>
- Assuming that the registration requires a valid value for an
<literal>email</literal> registration property (as has been shown) the
configuration screen for this producer should show:
- </para>
- <mediaobject>
- <imageobject role="html">
- <imagedata align="center"
fileref="images/WSRP/config_self.png" format="PNG"
scale="120" width="444" />
- </imageobject>
- <imageobject role="fo">
- <imagedata align="center"
contentwidth="140mm" fileref="images/WSRP/config_self.png"
format="PNG" width="444" />
- </imageobject>
+ <para>Both the
+ <literal>id</literal>
+ attribute and
+ <literal><endpoint-wsdl-url></literal>
+ elements are required for a functional remote producer configuration.
+ </para>
+ </section>
- </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 &
Save</emphasis>":
- </para>
- <mediaobject>
- <imageobject role="html">
- <imagedata align="center"
fileref="images/WSRP/modify_reg_self.png" format="PNG"
scale="120" width="444" />
- </imageobject>
- <imageobject role="fo">
- <imagedata align="center"
contentwidth="140mm" fileref="images/WSRP/modify_reg_self.png"
format="PNG" width="444" />
- </imageobject>
+ <section>
+ <title>Optional configuration</title>
+ <para>It is also possible to provide addtional configuration, which, in
some cases, might be important to
+ establish a proper connection to the remote producer.
+ </para>
- </mediaobject>
- <para>
- The configuration screen now shows the currently held registration
information and the expected information from the producer.
- </para>
- <para>
- Enter a value for the <literal>name</literal> property
and then click on "<emphasis role="bold">Modify
registration</emphasis>". If the producer accepts the new registration data,
the following screen will appear:
- </para>
- <mediaobject>
- <imageobject role="html">
- <imagedata align="center"
fileref="images/WSRP/modify_reg_self_end.png" format="PNG"
scale="120" width="444" />
- </imageobject>
- <imageobject role="fo">
- <imagedata align="center"
contentwidth="140mm" fileref="images/WSRP/modify_reg_self_end.png"
format="PNG" width="444" />
- </imageobject>
+ <para>One such optional configuration concerns caching. To prevent
useless roundtrips between the local
+ consumer and the remote producer, it is possible to cache some of the
information sent by the producer
+ (such as the list of offered portlets) for a given duration. The rate at
which the information is
+ refreshed is
+ defined by the
+ <literal>expiration-cache</literal>
+ attribute of the
+ <literal><wsrp-producer></literal>
+ element which specifies the refreshing period in seconds. For example,
providing a value of 120 for
+ expiration-cache means that the producer information will not be refreshed
for 2 minutes after it has
+ been somehow accessed. If no value is provided, JBoss Enterprise Portal
Platform will always access the remote producer
+ regardless of whether the remote information has changed or not. Since, in
most instances, the
+ information provided by the producer does not change often, we recommend
that you use this caching
+ facility to minimize bandwidth usage.
+ </para>
- </mediaobject>
- <note>
- <title><emphasis role="bold">JBoss Enterprise
Portal Platform &VY; and WSRP 1 Exceptions</emphasis></title>
- <para>
- In WSRP 1, it can be difficult to ascertain what caused an
<exceptionname> OperationFailedFault </exceptionname> as it is a generic
exception returned by producers during a failed method invocation.
- </para>
- <para>
- An
<exceptionname>OperationFailedFault</exceptionname> failure can be caused by
several different reasons, one of them being a request to modify the registration data.
- </para>
- <para>
- In these instances examining the log files may assist in
gathering more information about the problem.
- </para>
- <para>
- WSRP 2 introduces an exception that is specific to a request to
modify registrations which reduces the ambiguity that currently exists.
- </para>
+ <para>It is also possible to define a timeout after which WS operations
are considered as failed. This is
+ helpful to avoid blocking the WSRP service, waiting forever on the service
that doesn't answer. Use the
+ <literal>ws-timeout</literal>
+ attribute of the
+ <literal><wsrp-producer></literal>
+ element to specify how many milliseconds the WSRP service will wait for a
response from the remote
+ producer before timing out and giving up.
+ </para>
- </note>
-
- </section>
-
-
- </section>
-
- <section
id="sect-Reference_Guide_eXo_JCR_1.14-Consumers_Maintenance-Consumer_Operations">
- <title>Consumer Operations</title>
- <para>
- Several operations are available from the consumer list view of the WSRP
configuration portlet:
+ <para>Additionally, some producers require consumers to register with
them before authorizing them to access
+ their offered portlets. If you know that information beforehand, you can
provide the required
+ registration information in the producer configuration so that the
consumer can register with the remote
+ producer when required.
+ <note>
+ <para>At this time, though, only simple String properties are
supported and it is not possible to
+ configure complex registration data. This should, however, be
sufficient for most cases.
+ </para>
+ </note>
</para>
- <mediaobject>
- <imageobject role="html">
- <imagedata align="center"
fileref="images/WSRP/consumer_operations.png" format="PNG"
scale="120" width="444" />
- </imageobject>
- <imageobject role="fo">
- <imagedata align="center" contentwidth="140mm"
fileref="images/WSRP/consumer_operations.png" format="PNG"
width="444" />
- </imageobject>
- </mediaobject>
- <para>
- The available operations are:
+ <para>Registration configuration is done via the
+ <literal><registration-data></literal>
+ element. Since JBoss Enterprise Portal Platform can generate the mandatory
information for you, if the remote producer does
+ not require any registration properties, you only need to provide an
empty
+ <literal><registration-data></literal>
+ element. Values for the registration properties
+ required by the remote producer can be provided via
+ <literal><property></literal>
+ elements. See the example below for more details. Additionally, you can
override the default consumer
+ name automatically provided by JBoss Enterprise Portal Platform via the
+ <literal><consumer-name></literal>
+ element. If you choose to provide a consumer name, please remember that
this should uniquely identify
+ your consumer.
</para>
- <variablelist>
- <varlistentry>
- <term>Configure</term>
- <listitem>
- <para>
- Displays the consumer details and allows user to edit them.
- </para>
+ </section>
- </listitem>
+ <section>
+ <title>Examples</title>
- </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>
+ <para>
+ Here is the configuration of the
+ <literal>selfv1</literal>
+ and
+ <literal>selfv2</literal>
+ consumers as found in
+
<filename>$JBOSS_PROFILE_HOME/deploy/gatein-wsrp-integration.ear/lib/extension-component-$WSRP_VERSION.jar/conf/wsrp-consumers-config.xml</filename>
+ with a cache expiring every 500 seconds and with a 50 second timeout for
web service operations.
+ <note>
+ <para>
+ This file contains the default configuration and you shouldn't
need to edit it. If you want to make
+ modifications to it, we recommend that you follow the procedure
detailed in
+ <xref linkend="consumer_gui"/>.
+ </para>
+ </note>
+ </para>
- </listitem>
+ <example>
+ <title>Example</title>
+ <para>
+ <programlisting><![CDATA[
+<?xml version='1.0' encoding='UTF-8' ?>
+<deployments
xmlns="http://www.gatein.org/xml/ns/gatein_wsrp_consumer_1_0"
+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+
xsi:schemaLocation="http://www.gatein.org/xml/ns/gatein_wsrp_consume...
http://www.jboss.org/portal/xsd/gatein_wsrp_consumer_1_0.xsd">
+ <deployment>
+ <wsrp-producer id="selfv1" expiration-cache="500"
ws-timeout="50000">
+
<endpoint-wsdl-url>http://localhost:8080/wsrp-producer/v1/MarkupService?wsdl</endpoint-wsdl-url>
+ <registration-data/>
+ </wsrp-producer>
+ </deployment>
+ <deployment>
+ <wsrp-producer id="selfv2" expiration-cache="500"
ws-timeout="50000">
+
<endpoint-wsdl-url>http://localhost:8080/wsrp-producer/v2/MarkupService?wsdl</endpoint-wsdl-url>
+ <registration-data/>
+ </wsrp-producer>
+ </deployment>
+</deployments>]]>
+ </programlisting>
+ </para>
- </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>
+ </example>
- </listitem>
+ <para>Here is an example of a WSRP descriptor with registration data
and cache expiring every minute:
+ </para>
- </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>
+ <example>
+ <title>Example</title>
+ <para>
+ <programlisting><![CDATA[
+<?xml version='1.0' encoding='UTF-8' ?>
+<deployments
xmlns="http://www.gatein.org/xml/ns/gatein_wsrp_consumer_1_0"
+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+
xsi:schemaLocation="http://www.gatein.org/xml/ns/gatein_wsrp_consume...
http://www.jboss.org/portal/xsd/gatein_wsrp_consumer_1_0.xsd">
+<deployments>
+ <deployment>
+ <wsrp-producer id="AnotherProducer"
expiration-cache="60">
+
<
endpoint-wsdl-url>http://example.com/producer/producer?WSDL</endpoi...
+ <registration-data>
+ <property>
+ <name>property name</name>
+ <lang>en</lang>
+ <value>property value</value>
+ </property>
+ </registration-data>
+ </wsrp-producer>
+ </deployment>
+</deployments>]]></programlisting>
+ </para>
+ </example>
+ </section>
+ </section>
- </listitem>
+ <section>
+ <title>Adding remote portlets to categories</title>
+ <para>
+ If we go to the Application Registry and examine the available portlets by
clicking on the
+ Portlet link, you will now be able to see remote portlets if you click on the
REMOTE tab in the left
+ column:
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/WSRP/remote_portlets.png"
format="PNG" align="center" valign="middle"
+ scalefit="1"/>
+ </imageobject>
+ </mediaobject>
+ </para>
- </varlistentry>
- <varlistentry>
- <term>Delete</term>
- <listitem>
- <para>
- Destroys the consumer, after de-registering it if it was
registered.
- </para>
+ <para>
+ These portlets are, of course, available to be used such as regular portlets:
they can be used in
+ categories and added to pages. If you use the Import Applications
functionality, they will also be
+ automatically imported in categories based on the keywords they define.
+ </para>
- </listitem>
+ <para>
+ More specifically, if you want to add a WSRP portlet to a category, you can
access these portlets by
+ selecting
+ <literal>wsrp</literal>
+ in the Application Type drop-down menu:
+ <mediaobject>
+ <imageobject>
+ <imagedata
fileref="images/WSRP/remote_portlets_category.png" format="PNG"
align="center"
+ valign="middle"
+ scalefit="1"/>
+ </imageobject>
+ </mediaobject>
+ </para>
+ </section>
+ </section>
- </varlistentry>
+ <section>
+ <title>Consumers maintenance</title>
- </variablelist>
- <formalpara
id="form-Reference_Guide_eXo_JCR_1.14-Consumer_Operations-Additional_Functionalities_in_WSRP_2.0">
- <title><emphasis role="bold">Additional
Functionalities in WSRP 2.0</emphasis></title>
- <para>
- In addition to those listed above, the WSRP 2.0 implementation in
JBoss Enterprise Portal Platform &VY; also includes the following functions:
- </para>
+ <section>
+ <title>Modifying a currently held registration</title>
- </formalpara>
- <variablelist
id="vari-Reference_Guide_eXo_JCR_1.14-Consumer_Operations-Additional_Functions">
- <title>Additional Functions:</title>
- <varlistentry>
- <term>Export</term>
- <listitem>
- <para>
- Exports some or all of the consumer's portlets to be able
to later import them in a different context
- </para>
-
- </listitem>
-
- </varlistentry>
- <varlistentry>
- <term>Import</term>
- <listitem>
- <para>
- Imports some or all of previously exported portlets.
- </para>
-
- </listitem>
-
- </varlistentry>
-
- </variablelist>
- <section
id="sect-Reference_Guide_eXo_JCR_1.14-Consumer_Operations-Importing_and_Exporting_Portlets">
- <title><emphasis role="bold">Importing and
Exporting Portlets</emphasis></title>
- <para>
- Import and export are new functionalities added in WSRP 2.
- </para>
- <para>
- Exporting a portlet allows a consumer to get an opaque representation
of the portlet which can then be use by the corresponding import operation to reconstitute
it.
- </para>
- <para>
- This is mostly used in migration scenarios during batch operations.
Since JBoss Enterprise Portal Platform does not currently support automated migration of
portal data, the functionality provided as part of WSRP 2 is necessarily less complete
than it could be with full portal support.
- </para>
- <para>
- The import/export implementation in JBoss Enterprise Portal Platform
allows users to export portlets from a given consumer and then import them back to replace
existing portlets assigned to windows on pages by the previously exported portlets.
- </para>
- <procedure>
- <title></title>
- <step>
- <para>
- Click on the
"<guilabel>Export</guilabel>" action for a given consumer to display
the list of portlets currently made available by this specific consumer. An example list
is shown below:
- </para>
- <mediaobject>
- <imageobject role="html">
- <imagedata align="center"
fileref="images/WSRP/export_portlet_list.png" format="PNG"
scale="120" width="444" />
- </imageobject>
- <imageobject role="fo">
- <imagedata align="center"
contentwidth="150mm" fileref="images/WSRP/export_portlet_list.png"
format="PNG" width="444" />
- </imageobject>
-
- </mediaobject>
-
- </step>
- <step>
- <para>
- Once portlets have been selected, they can be exported by
clicking on the "<guilabel>Export</guilabel>" button. This makes
them available for later import:
- </para>
- <mediaobject>
- <imageobject role="html">
- <imagedata align="center"
fileref="images/WSRP/export_done.png" format="PNG"
scale="120" width="444" />
- </imageobject>
- <imageobject role="fo">
- <imagedata align="center"
contentwidth="150mm" fileref="images/WSRP/export_done.png"
format="PNG" width="444" />
- </imageobject>
-
- </mediaobject>
-
- </step>
- <step>
- <para>
- The portlets can be re-imported directly by pressing the
"<guilabel>Use for import</guilabel>" button or, on the Consumers
list page, using the "<guilabel>Import</guilabel>" action for a
given consumer.
- </para>
- <para>
- The example below assumes that the second option has been
used and that several sets of previously exported portlets are available to import from.
After clicking the action link, a screen similar to the one below should appear:
- </para>
- <mediaobject>
- <imageobject role="html">
- <imagedata align="center"
fileref="images/WSRP/export_list.png" format="PNG"
scale="120" width="444" />
- </imageobject>
- <imageobject role="fo">
- <imagedata align="center"
contentwidth="150mm" fileref="images/WSRP/export_list.png"
format="PNG" width="444" />
- </imageobject>
-
- </mediaobject>
- <para>
- This screen presents the list of available exports with
available operations for each.
- </para>
- <variablelist
id="vari-Reference_Guide_eXo_JCR_1.14-Importing_and_Exporting_Portlets-Operations">
- <title>Operations:</title>
- <varlistentry>
- <term>View</term>
- <listitem>
- <para>
- Displays the export details as previously seen
when the export was first performed.
- </para>
-
- </listitem>
-
- </varlistentry>
- <varlistentry>
- <term>Delete</term>
- <listitem>
- <para>
- Deletes the selected export, asking you for
confirmation first.
- </para>
-
- </listitem>
-
- </varlistentry>
- <varlistentry>
- <term>Use for import</term>
- <listitem>
- <para>
- Selects the export to import portlets from.
- </para>
-
- </listitem>
-
- </varlistentry>
-
- </variablelist>
-
- </step>
- <step>
- <para>
- Once you have selected an export to import from, you will see
a screen similar to the one below:
- </para>
- <mediaobject>
- <imageobject role="html">
- <imagedata align="center"
fileref="images/WSRP/import_start.png" format="PNG"
scale="120" width="444" />
- </imageobject>
- <imageobject role="fo">
- <imagedata align="center"
contentwidth="150mm" fileref="images/WSRP/import_start.png"
format="PNG" width="444" />
- </imageobject>
-
- </mediaobject>
- <para>
- The screen displays the list of available exported portlets
for the previously selected export. You can select which portlet you want to import by
checking the checkbox next to its name.
- </para>
-
- </step>
- <step>
- <para>
- Select the content of which window the imported portlet will
replace. This process is done in three steps:
- </para>
- <para>
- This example assumes that you have the following page called
<literal>page1</literal> which contains two windows called
<literal>NetUnity WSRP 2 Interop - Cache Markup (remote)</literal> and
<literal>/samples-remotecontroller-portlet.RemoteControl (remote)</literal>,
as shown below:
- </para>
- <mediaobject>
- <imageobject role="html">
- <imagedata align="center"
fileref="images/WSRP/import_original_page.png" format="PNG"
scale="120" width="444" />
- </imageobject>
- <imageobject role="fo">
- <imagedata align="center"
contentwidth="150mm" fileref="images/WSRP/import_original_page.png"
format="PNG" width="444" />
- </imageobject>
-
- </mediaobject>
- <para>
- In this example, we want to replace the content of the
<literal>/samples-remotecontroller-portlet.RemoteControl (remote)</literal>
with the content of the <literal>/ajaxPortlet.JSFAJAXPortlet</literal> portlet
that was previously exported.
- </para>
- <procedure>
- <title></title>
- <step>
- <para>
- Check the box next to the
<literal>/ajaxPortlet.JSFAJAXPortlet</literal> portlet name to indicate that
you want to import its data.
- </para>
-
- </step>
- <step>
- <para>
- Select <literal>page1</literal> in the
list of available pages. The screen will then refresh to display the list of available
windows on that page, similar to the image below:
- </para>
- <mediaobject>
- <imageobject role="html">
- <imagedata align="center"
fileref="images/WSRP/import_selected_page.png" format="PNG"
scale="120" width="444" />
- </imageobject>
- <imageobject role="fo">
- <imagedata align="center"
contentwidth="150mm" fileref="images/WSRP/import_selected_page.png"
format="PNG" width="444" />
- </imageobject>
-
- </mediaobject>
- <note>
- <title>Note</title>
- <para>
- At this point, you still need to select which
window content you want to replace before being able to complete the import operation
- </para>
-
- </note>
-
- </step>
- <step>
- <para>
- Select the
<literal>/samples-remotecontroller-portlet.RemoteControl (remote)</literal>
window, which enables the "<guilabel>Import</guilabel>" button. This
indicates that all the necessary data to perform the import is available.
- </para>
-
- </step>
- <step>
- <para>
- Click the
"<guilabel>Import</guilabel>" button. A screen similar to the one
below will appear:
- </para>
- <mediaobject>
- <imageobject role="html">
- <imagedata align="center"
fileref="images/WSRP/import_success.png" format="PNG"
scale="120" width="444" />
- </imageobject>
- <imageobject role="fo">
- <imagedata align="center"
contentwidth="150mm" fileref="images/WSRP/import_success.png"
format="PNG" width="444" />
- </imageobject>
-
- </mediaobject>
-
- </step>
-
- </procedure>
-
-
- </step>
- <step>
- <para>
- The <literal>page1</literal> page should now show
that the content of <literal>/samples-remotecontroller-portlet.RemoteControl
(remote)</literal> window has been replaced by the content of the
<literal>/ajaxPortlet.JSFAJAXPortlet</literal> imported portlet and that the
window has been renamed appropriately.
- </para>
- <mediaobject>
- <imageobject role="html">
- <imagedata align="center"
fileref="images/WSRP/import_modified_page.png" format="PNG"
scale="120" width="444" />
- </imageobject>
- <imageobject role="fo">
- <imagedata align="center"
contentwidth="150mm" fileref="images/WSRP/import_modified_page.png"
format="PNG" width="444" />
- </imageobject>
-
- </mediaobject>
-
- </step>
-
- </procedure>
-
-
- </section>
-
-
- </section>
-
- <section
id="sect-Reference_Guide_eXo_JCR_1.14-Consumers_Maintenance-Erasing_Local_Registration_Data">
- <title>Erasing Local Registration Data</title>
- <para>
- In rare cases, it may be necessary to erase the local data without being
able to de-register first.
+ <section>
+ <title>Registration modification for service upgrade</title>
+ <para>
+ Producers often offer several levels of service depending on
consumers' subscription levels (for
+ example). This is implemented at the WSRP level with the registration
concept: producers can assert which
+ level of service to provide to consumers based on the values of given
registration properties.
</para>
- <para>
- 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>
+ There might also be cases where you just want to update the registration
information because it has
+ changed. For example, the producer required you to provide a valid email
and the previously email
+ address is not valid anymore and needs to be updated.
</para>
- <para>
- In this scenario, local registration information can be erased from the
consumer to allow it to resume interacting with the remote producer.
+ <para>
+ It is therefore sometimes necessary to modify the registration that
concretizes the service agreement
+ between a consumer and a producer. Let's take the example of a
producer requiring a valid email (via an
+ <literal>email</literal>
+ registration property) as part of its required information that consumers
need to provide to be properly
+ registered.
</para>
- <para>
- 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>
+ Suppose now that we would like to update the email address that we
provided to the remote producer when
+ we first registered. We will need to tell the producer that our
registration data has been modified.
+ Let's see how to do this. Select the consumer for the remote producer
in the available consumers list to
+ display its configuration. Assuming you want to change the email you
registered with to
+ <literal>foo(a)example.com</literal>, change its value in the
field for the
+ <literal>email</literal>
+ registration property:
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/WSRP/modify_reg_start.png"
format="PNG" align="center" valign="middle"
+ scalefit="1"/>
+ </imageobject>
+ </mediaobject>
+ Now click on "Update properties" to save the change. A
"Modify registration" button should now appear to
+ let you send this new data to the remote producer:
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/WSRP/modify_reg_modify.png"
format="PNG" align="center"
+ valign="middle" scalefit="1"/>
+ </imageobject>
+ </mediaobject>
+ Click on this new button and, if everything went well and your updated
registration has been accepted by
+ the remote producer, you should see something similar to:
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/WSRP/modify_reg_end.png"
format="PNG" align="center" valign="middle"
+ scalefit="1"/>
+ </imageobject>
+ </mediaobject>
</para>
- <mediaobject>
- <imageobject role="html">
- <imagedata align="center"
fileref="images/WSRP/erase_registration.png" format="PNG"
scale="80" width="444" />
- </imageobject>
- <imageobject role="fo">
- <imagedata align="center" contentwidth="140mm"
fileref="images/WSRP/erase_registration.png" format="PNG"
width="444" />
- </imageobject>
- </mediaobject>
- <warning>
- <para>
- This operation is dangerous as it can result in inability to interact
with the remote producer if invoked when not required. The warning message below will be
displayed before any data is erased.
- </para>
- <mediaobject>
- <imageobject role="html">
- <imagedata align="center"
fileref="images/WSRP/erase_registration_warning.png" format="PNG"
scale="100" width="444" />
- </imageobject>
- <imageobject role="fo">
- <imagedata align="center"
contentwidth="140mm"
fileref="images/WSRP/erase_registration_warning.png" format="PNG"
width="444" />
- </imageobject>
+ </section>
- </mediaobject>
+ <section id="reg_mod_error">
+ <title>Registration modification on producer error</title>
- </warning>
+ <para>
+ It can also happen that a producer administrator decided to change its
requirement for registered
+ consumers. JBoss Enterprise Portal Platform will attempt to help you in
this situation. Let's walk through an example using
+ the <literal>selfv2</literal> consumer. Let's assume that
registration is requiring a valid value for an
+ <literal>email</literal>
+ registration property. If you go to the configuration screen for this
consumer, you should see:
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/WSRP/config_self.png"
format="PNG" align="center" valign="middle"
+ scalefit="1"/>
+ </imageobject>
+ </mediaobject>
- </section>
-
+ Now suppose that the administrator of the producer now additionaly
requires a value to be provided for a
+ <literal>name</literal>
+ registration property. We will actually see how to do perform this
operation
+ in JBoss Enterprise Portal Platform when we examine how to configure JBoss
Enterprise Portal Platform's producer in
+ <xref linkend="producer_config"/>.
+ Operations with this producer will now fail. If you suspect that a
registration modification is required,
+ you should go to the configuration screen for this remote producer and
refresh the information held by
+ the consumer by pressing "Refresh & Save":
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/WSRP/modify_reg_self.png"
format="PNG" align="center" valign="middle"
+ scalefit="1"/>
+ </imageobject>
+ </mediaobject>
- </section>
-
- <section
id="sect-Reference_Guide_eXo_JCR_1.14-Web_Services_for_Remote_Portlets_WSRP-Configuring_the_WSRP_Producer">
- <title>Configuring the WSRP Producer</title>
- <section
id="sect-Reference_Guide_eXo_JCR_1.14-Configuring_the_WSRP_Producer-Overview">
- <title>Overview</title>
- <para>
- The behavior of the Portal's WSRP Producer can be configured using
the WSRP administration interface, (this is the recommended method), or by editing the
<filename><replaceable>WSRP_PATH</replaceable>/lib/gatein.portal.component.wsrp-<replaceable><VERSION></replaceable>-epp-GA.jar/conf/wsrp-producer-config.xml</filename>
file.
- </para>
- <para>
- Several aspects can be modified with respect to whether registration is
required for consumers to access the Producer's services. An XML Schema for the
configuration format is available at
<filename><replaceable>WSRP_PATH</replaceable>/lib/wsrp-integration-api-<replaceable>WSRP_VERSION</replaceable>.jar/xsd/gatein_wsrp_producer_1_0.xsd
</filename>.
- </para>
- <para>
- An alternative to editing the default
<filename>wsrp-producer-config.xml</filename> file is to make a custom copy
containing the required configuration options.
- </para>
- <para>
- If a copy is used in place of the original, however, the
<filename><replaceable>WSRP_PATH</replaceable>/02portal.war/WEB-INF/conf/wsrp/wsrp-configuration.xml</filename>
<emphasis role="bold">must</emphasis> be updated to reference the
custom file (this file defines the component
<literal>WSRPServiceIntegration</literal> and contains a producer and consumer
configuration location).
- </para>
+ As you can see, the configuration screen now shows the currently held
registration information and
+ the expected information from the producer. Enter a value for the
+ <literal>name</literal>
+ property
+ and then click on "Modify registration". If all went well and
the producer accepted your new registration
+ data, you should see something similar to:
+ <mediaobject>
+ <imageobject>
+ <imagedata
fileref="images/WSRP/modify_reg_self_end.png" format="PNG"
align="center"
+ valign="middle" scalefit="1"/>
+ </imageobject>
+ </mediaobject>
- </section>
-
- <section
id="sect-Reference_Guide_eXo_JCR_1.14-Configuring_the_WSRP_Producer-Default_Configuration">
- <title>Default Configuration</title>
- <para>
- The default producer configuration requires that consumers register with
it before providing access to its services. However it does not require any specific
registration properties (excepting those mandated by the WSRP standard).
+ <note>
+ <para>WSRP 1 makes it rather difficult to ascertain for sure what
caused an
+ <exceptionname>OperationFailedFault</exceptionname>
+ as it is the generic exception returned by
+ producers if something didn't quite happen as expected during a
method invocation. This means that
+ <exceptionname>OperationFailedFault</exceptionname>
+ can be caused by several different reasons, one
+ of them being a request to modify the registration data. Please take
a look at the log files to see
+ if you can gather more information as to what happened. WSRP 2
introduces an exception that is
+ specific to a request to modify registrations thus reducing the
ambiguity that exists when using WSRP 1.
+ </para>
+
+ </note>
</para>
- <para>
- It does, however, require consumers to be registered before sending them
a full service description. This means that the WSRP producer will not provide the list of
offered portlets and other capabilities to unregistered consumers.
- </para>
- <para>
- The producer also uses the default
<classname>RegistrationPolicy</classname> paired with the default
<classname>RegistrationPropertyValidator</classname>.
- </para>
- <para>
- This allows users to customize how Portal's WSRP Producer decides
whether a given registration property is valid or not (however property validators are
discussed in greater detail in <xref
linkend="sect-Reference_Guide_eXo_JCR_1.14-Configuring_the_WSRP_Producer-Registration_Configuration"
/> ).
- </para>
- <para>
- JBoss Enterprise Portal Platform provides a web interface to configure
the producer's behavior. It can be accessed by clicking on the "<emphasis
role="bold">Producer Configuration</emphasis>" tab of the
"<emphasis role="bold">WSRP</emphasis>" page of the
"<emphasis role="bold">admin</emphasis>" portal.
- </para>
- <para>
- The default configuration should show:
- </para>
- <mediaobject>
- <imageobject role="html">
- <imagedata align="center"
fileref="images/WSRP/producer_default.png" format="PNG"
scale="110" width="444" />
- </imageobject>
- <imageobject role="fo">
- <imagedata align="center" contentwidth="140mm"
fileref="images/WSRP/producer_default.png" format="PNG"
width="444" />
- </imageobject>
+ </section>
+ </section>
+ <section>
+ <title>Consumer operations</title>
+ <para>
+ Several operations are available from the consumer list view of the WSRP
configuration portlet:
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/WSRP/consumer_operations.png"
format="PNG" align="center" valign="middle"
+ scalefit="1"/>
+ </imageobject>
</mediaobject>
- <para>
- 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>
+ The available operations are:
+ <itemizedlist>
+ <listitem>
+ <para>Configure: displays the consumer details and allows user to
edit them</para>
+ </listitem>
+ <listitem>
+ <para>Refresh: forces the consumer to retrieve the service
description from the remote producer to
+ refresh
+ the local information (offered portlets, registration information,
etc.)
+ </para>
+ </listitem>
+ <listitem>
+ <para>Activate/Deactivate: activates/deactivates a consumer,
governing whether it will be available to
+ provide portlets and receive portlet invocations
+ </para>
+ </listitem>
+ <listitem>
+ <para>Register/Deregister: registers/deregisters a consumer based
on whether registration is required
+ and/or acquired
+ </para>
+ </listitem>
+ <listitem>
+ <para>Delete: destroys the consumer, after deregistering it if it
was registered</para>
+ </listitem>
+ <listitem>
+ <para>Export: exports some or all of the consumer's portlets
to be able to later import them in a
+ different context
+ </para>
+ </listitem>
+ <listitem>
+ <para>Import: imports some or all of previously exported
portlets</para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <note>
+ <para>
+ Import/Export functionality is only available to WSRP 2 consumers of
producers that support this optional
+ functionality. Import functionality is only available if portlets had
previously been exported.
</para>
- <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>
+ </note>
+ </section>
- </section>
-
- <section
id="sect-Reference_Guide_eXo_JCR_1.14-Configuring_the_WSRP_Producer-Registration_Configuration">
- <title>Registration Configuration</title>
- <para>
- In order to have consumers register with Portal's producer the
Portal's behavior with respect to registration must be configured.
- </para>
- <para>
- Registration is optional, as are registration properties. The producer
can require registration without requiring consumers to pass any registration properties
as is the case in the default configuration.
- </para>
- <para>
- The following section discusses configuring a producer's registration
behavior from a blank state:
- </para>
- <mediaobject>
- <imageobject role="html">
- <imagedata align="center"
fileref="images/WSRP/producer_blank.png" format="PNG"
width="700" />
- </imageobject>
- <imageobject role="fo">
- <imagedata align="center" contentwidth="140mm"
fileref="images/WSRP/producer_blank.png" format="PNG"
width="444" />
- </imageobject>
+ <section>
+ <title>Importing and exporting portlets</title>
+ <para>Import and export are new functionalities added in WSRP 2. Exporting
a portlet allows a consumer to get
+ an opaque representation of the portlet which can then be use by the
corresponding import operation to
+ reconstitute it. It is mostly used in migration scenarios during batch
operations. Since JBoss Enterprise Portal Platform
+ does not currently support automated migration of portal data, the
functionality that we provide as part of
+ WSRP 2 is necessarily less complete than it could be with full portal
support.
+ </para>
+ <para>The import/export implementation in JBoss Enterprise Portal Platform
(available since 3.1) allows users to export portlets
+ from a given consumer.
+ These portlets can then be used to replace existing content on pages. This is
accomplished by assigning
+ previously exported portlets to replace the content displayed by windows on
the portal's pages. Let us walk
+ through an example to make things clearer.
+ </para>
+ <para>Clicking on the "Export" action for a given consumer will
display the list of portlets currently made
+ available by this specific consumer. An example of such a list is shown
below:
+ </para>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/WSRP/export_portlet_list.png"
format="PNG" align="center" valign="middle"/>
+ </imageobject>
+ </mediaobject>
+ <para>Once portlets have been selected, they can be exported by clicking
on the "Export" button thus making
+ them available for later import:
+ </para>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/WSRP/export_done.png"
format="PNG" align="center" valign="middle"/>
+ </imageobject>
+ </mediaobject>
+ <para>You can re-import the portlets directly by pressing the "Use
for import" button or, on the Consumers list
+ page, using the "Import" action for a given consumer. Let's
assume that you used that second option and that
+ you currently have several available sets of previously exported portlets to
import from. After clicking the
+ action link, you should see a screen similar to the one below:
+ </para>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/WSRP/export_list.png"
format="PNG" align="center" valign="middle"/>
+ </imageobject>
+ </mediaobject>
+ <para>As you can see this screen presents the list of available exports
with available operations for each.
+ <itemizedlist>
+ <listitem>
+ <para>View: displays the export details as previously seen when
the export was first performed</para>
+ </listitem>
+ <listitem>
+ <para>Delete: deletes the selected export, asking you for
confirmation first</para>
+ </listitem>
+ <listitem>
+ <para>Use for import: selects the export to import portlets
from</para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>Once you've selected an export to import from, you will see a
screen similar to the one below:</para>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/WSRP/import_start.png"
format="PNG" align="center" valign="middle"/>
+ </imageobject>
+ </mediaobject>
+ <para>The screen displays the list of available exported portlets for the
previously selected export. You can
+ select which portlet you want to import by checking the checkbox next to its
name. Next, you need to select
+ the content of which window the imported portlet will replace. This process
is done in three steps. Let's
+ assume in this example that you have the following page called
+ <literal>page1</literal>
+ and containing two windows called
+ <literal>NetUnity WSRP 2 Interop - Cache Markup
(remote)</literal>
+ and
+ <literal>/samples-remotecontroller-portlet.RemoteControl
(remote)</literal>
+ as shown below:
+ </para>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/WSRP/import_original_page.png"
format="PNG" align="center" valign="middle"/>
+ </imageobject>
+ </mediaobject>
+ <para>In this example, we want to replace the content of the
+ <literal>/samples-remotecontroller-portlet.RemoteControl
(remote)</literal>
+ by the content of the
+ <literal>/ajaxPortlet.JSFAJAXPortlet</literal>
+ portlet that we previously exported. To do so, we will check the checkbox
next to the
+ <literal>/ajaxPortlet.JSFAJAXPortlet</literal>
+ portlet name to indicate that we want to import its data and then select the
+ <literal>page1</literal>
+ in the list of available pages. The screen will then refresh to display the
list of available windows on
+ that page, similar to the one seen below:
+ </para>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/WSRP/import_selected_page.png"
format="PNG" align="center" valign="middle"/>
+ </imageobject>
+ </mediaobject>
+ <para>Note that, at this point, we still need to select the window which
content we want to replace before
+ being able to complete the import operation. Let's select the
+ <literal>/samples-remotecontroller-portlet.RemoteControl
(remote)</literal>
+ window, at which point the "Import" button will become enabled,
indicating that we now have all the
+ necessary data to perform the import. If all goes well, pressing that button
should result in a screen
+ similar to the one below:
+ </para>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/WSRP/import_success.png"
format="PNG" align="center" valign="middle"/>
+ </imageobject>
+ </mediaobject>
+ <para>If you now take a look at the
+ <literal>page1</literal>
+ page, you should now see that the content
+ <literal>/samples-remotecontroller-portlet.RemoteControl
(remote)</literal>
+ window has been replaced by the content of the
+ <literal>/ajaxPortlet.JSFAJAXPortlet</literal>
+ imported portlet and the window renamed appropriately:
+ </para>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/WSRP/import_modified_page.png"
format="PNG" align="center" valign="middle"/>
+ </imageobject>
+ </mediaobject>
+ </section>
+ <section>
+ <title>Erasing local registration data</title>
+ <para>
+ There are rare cases where it might be required to erase the local
information without being able to
+ deregister first. This is the case when a consumer is registered with a
producer that has been modified by
+ its administrator to not require registration anymore. If that ever was to
happen (most likely, it won't),
+ you can erase the local registration information from the consumer so that it
can resume interacting with
+ the remote producer. To do so, click on "Erase local registration"
button next to the registration context
+ information on the consumer configuration screen:
+ </para>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/WSRP/erase_registration.png"
format="PNG" align="center" valign="middle"/>
+ </imageobject>
+ </mediaobject>
+ <para>
+ <emphasis>Warning:</emphasis>
+ This operation is dangerous as it can result in inability to interact with
the remote producer if invoked
+ when not required. A warning screen will be displayed to give you a chance to
change your mind:
+ </para>
+ <mediaobject>
+ <imageobject>
+ <imagedata
fileref="images/WSRP/erase_registration_warning.png" format="PNG"
align="center"
+ valign="middle"/>
+ </imageobject>
+ </mediaobject>
+ </section>
+ </section>
+
+ <section id="producer_config">
+ <title>Configuring JBoss Enterprise Portal Platform's WSRP
Producer</title>
+ <section>
+ <title>Overview</title>
+ <para>
+ The preferred way to configure the behavior of Portal's WSRP Producer is
via the WSRP configuration portlet.
+ Alternatively, it is possible to add an XML file called
+ <filename>wsrp-producer-config.xml</filename>
+ in the
+ <filename>$JBOSS_PROFILE_HOME/conf/gatein/</filename>
+ directory.
+ Several aspects can be modified with respects to whether registration is
required for consumers to access
+ the Producer's services.
+ <note>
+ <para>An XML Schema defining which elements are available to
configure Consumers via XML can be found
+ in
+ <filename>
+
$JBOSS_PROFILE_HOME/deploy/gatein-wsrp-integration.ear/lib/wsrp-integration-api-$WSRP_VERSION.jar/xsd/gatein_wsrp_producer_1_0.xsd
+ </filename>
+ </para>
+ </note>
+ <important>
+ <para>
+ It is important to note that once the XML configuration file for the
producer has been read upon
+ the WSRP service first start, the associated information is put under
control of JCR (Java Content
+ Repository). Subsequent launches of the WSRP service will use the
JCR-stored information and ignore
+ the content of the XML configuration file.
+ </para>
+ </important>
+ <note>
+ <para>
+ The default configuration file for the producer can be found at
+
<filename>$JBOSS_PROFILE_HOME/deploy/gatein-wsrp-integration.ear/lib/extension-component-$WSRP_VERSION.jar/conf/wsrp-producer-config.xml</filename>
+ </para>
+ </note>
+ </para>
+ </section>
+ <section>
+ <title>Default configuration</title>
+ <para>
+ The default producer configuration is to require that consumers register with
it before providing access its
+ services but does not require any specific registration properties (apart
from what is mandated by the
+ WSRP standard). It does, however, require consumers to be registered before
sending them a full service
+ description. This means that our WSRP producer will not provide the list of
offered portlets and other
+ capabilities to unregistered consumers. The producer also uses the default
+ <classname>RegistrationPolicy</classname>
+ paired with the default
+ <classname>RegistrationPropertyValidator</classname>. We will
look into property
+ validators in greater detail later in<xref
linkend="registration-configuration"/>. Suffice to say for now
+ that this allows users to customize how Portal's WSRP Producer decides
whether a given registration property
+ is valid or not.
+ </para>
+ <para>
+ JBoss Enterprise Portal Platform provides a web interface to configure the
producer's behavior. You can access it
+ by clicking on the "Producer Configuration" tab of the
"WSRP" page of the "admin" portal. Here's what you
+ should see with the default configuration:
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/WSRP/producer_default.png"
format="PNG" align="center" valign="middle"
+ scalefit="1"/>
+ </imageobject>
</mediaobject>
- <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>
+ As would be expected, you can specify whether or not the producer will send
the full service description to
+ unregistered consumers, and, if it requires registration, which
+ <classname>RegistrationPolicy</classname>
+ to use (and, if needed, which
+ <classname>RegistrationPropertyValidator</classname>), along with
required
+ registration property description for which consumers must provide acceptable
values to successfully
+ register.
+ </para>
+ <para>New in JBoss Enterprise Portal Platform, we now display the WSDL
URLs to access JBoss Enterprise Portal Platform's WSRP producer either in WSRP 1
+ or WSRP 2 mode.
+ </para>
+ </section>
- </step>
- <step>
- <para>
- To specify, however, that consumers will need to be registered to
be able to interact with the producer, check the second box ("<emphasis
role="bold">Requires registration. Modifying this information will trigger
invalidation of consumer registrations."</emphasis>).
- </para>
- <para>
- The screen will refresh and display:
- </para>
- <mediaobject>
- <imageobject role="html">
- <imagedata align="center"
fileref="images/WSRP/producer_registration.png" format="PNG"
width="700" />
- </imageobject>
- <imageobject role="fo">
- <imagedata align="center"
contentwidth="140mm" fileref="images/WSRP/producer_registration.png"
format="PNG" width="444" />
- </imageobject>
+ <section id="registration-configuration">
+ <title>Registration configuration</title>
+ <para>
+ In order to require consumers to register with Portal's producer before
interacting with it, you need to
+ configure Portal's behavior with respect to registration. Registration is
optional, as are registration
+ properties. The producer can require registration without requiring consumers
to pass any registration
+ properties as is the case in the default configuration. Let's configure
our producer starting with a blank
+ state:
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/WSRP/producer_blank.png"
format="PNG" align="center" valign="middle"
+ scalefit="1"/>
+ </imageobject>
+ </mediaobject>
+ We will allow unregistered consumers to see the list of offered portlets so
we leave the first checkbox
+ ("Access to full service description requires consumers to be
registered.") unchecked. We will, however,
+ specify that consumers will need to be registered to be able to interact with
our producer. Check the second
+ checkbox ("Requires registration. Modifying this information will
trigger invalidation of consumer
+ registrations."). The screen should now refresh and display:
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/WSRP/producer_registration.png"
format="PNG" align="center"
+ valign="middle" scalefit="1"/>
+ </imageobject>
+ </mediaobject>
+ You can specify the fully-qualified name for your
+ <classname>RegistrationPolicy</classname>
+ and
+ <classname>RegistrationPropertyValidator</classname>
+ there. We will keep the default value. See
+ <xref linkend="custom_registration"/>
+ for more details. Let's add, however, a registration property called
+ <literal>email</literal>. Click "Add property" and
enter the appropriate information in the fields,
+ providing a description for the registration property that can be used by
consumers to figure out its
+ purpose:
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/WSRP/producer_email.png"
format="PNG" align="center" valign="middle"
+ scalefit="1"/>
+ </imageobject>
+ </mediaobject>
+ Press "Save" to record your modifications.
- </mediaobject>
+ <note>
+ <para>At this time, only String (xsd:string) properties are
supported. If your application requires more
+ complex properties, please let us know.
+ </para>
+ </note>
- </step>
- <step>
- <para>
- The fully-qualified name for the
<classname>RegistrationPolicy</classname> and
<classname>RegistrationPropertyValidator</classname> can be specified here.
The default values are acceptable. Refer to <xref
linkend="sect-Reference_Guide_eXo_JCR_1.14-Registration_Configuration-Customization_of_Registration_Handling_Behavior"
/> for more information.
- </para>
+ <note>
+ <para>If consumers are already registered with the producer,
modifying the configuration of required
+ registration
+ information will trigger the invalidation of held registrations,
requiring consumers to modify their
+ registration before being able to access the producer again. We saw the
consumer side of that process
+ in
+ <xref linkend="reg_mod_error"/>.
+ </para>
- </step>
- <step>
- <para>
- To add a registration property called
<literal>email</literal> click "<emphasis role="bold">Add
property</emphasis>" and enter the appropriate information in the fields,
providing a description for the registration property that can be used by consumers to
determine its purpose:
- </para>
- <mediaobject>
- <imageobject role="html">
- <imagedata align="center"
fileref="images/WSRP/producer_email.png" format="PNG"
width="700" />
- </imageobject>
- <imageobject role="fo">
- <imagedata align="center"
contentwidth="140mm" fileref="images/WSRP/producer_email.png"
format="PNG" width="444" />
- </imageobject>
-
- </mediaobject>
-
- </step>
- <step>
- <para>
- Press "Save" to record the modifications.
- </para>
-
- </step>
-
- </procedure>
-
- <note>
- <para>
- At this time, only String (<literal>xsd:string</literal>)
properties are supported.
- </para>
-
</note>
- <note>
- <para>
- If consumers are already registered with the producer, modifying the
configuration of required registration information will trigger the invalidation of held
registrations, requiring consumers to modify their registration before being able to
access the producer again. The consumer side of that process is documented in <xref
linkend="sect-Reference_Guide_eXo_JCR_1.14-Modifying_a_Currently_Held_Registration-Registration_Modification_on_Producer_Error"
/>.
- </para>
+ </para>
- </note>
- <section
id="sect-Reference_Guide_eXo_JCR_1.14-Registration_Configuration-Customization_of_Registration_Handling_Behavior">
- <title>Customization of Registration Handling
Behavior</title>
- <para>
- Registration handling behavior can be customized by users to suit
their Producer needs. This is done with an implementation of the
<classname>RegistrationPolicy</classname> interface.
- </para>
- <para>
- This interface defines methods that are called by Portal's
Registration service so that decisions can be made appropriately. A default registration
policy that provides basic behavior is provided and should be enough for most user needs.
- </para>
- <para>
- While the default registration policy provides default behavior for
most registration-related aspects, one aspect requires specific configuration: whether a
given value for a registration property is acceptable by the WSRP Producer.
- </para>
- <para>
- This is done by plugging a
<classname>RegistrationPropertyValidator</classname> into the default
registration policy. This allows users to define their own validation mechanism.
- </para>
- <para>
- Refer to the <trademark
class="trade">Javadoc</trademark> for
<classname>org.gatein.registration.RegistrationPolicy</classname> and
<classname>org.gatein.registration.policies.RegistrationPropertyValidator</classname>
for more details on what is expected of each method.
- </para>
- <para>
- A defined registration policy is required for the producer to be
correctly configured. Do this by specifying the qualified class name of the registration
policy.
- </para>
- <para>
- As it is anticipated that most users will use the default
registration policy, it is possible to provide the class name of a custom property
validator instead to customize the default registration policy behavior. Note that
property validators are only used by the default policy.
- </para>
- <note>
- <para>
- Since the policy or the validator are defined via their class
name and dynamically loaded, it is important to ensure that the identified class is
available to the application server.
- </para>
- <para>
- One way to accomplish that is to deploy the policy implementation
as a JAR file in the AS instance deploy directory.
- </para>
- <para>
- Note also that, since both policies and validators are
dynamically instantiated, they must provide a default, no-argument constructor.
- </para>
-
- </note>
-
- </section>
-
-
- </section>
-
- <section
id="sect-Reference_Guide_eXo_JCR_1.14-Configuring_the_WSRP_Producer-WSRP_Validation_Mode">
- <title>WSRP Validation Mode</title>
- <para>
- The lack of conformance kit and the wording of the WSRP specification
leaves room for differing interpretations, resulting in interoperability issues. It is
therefore possible to encounter issues when using consumers from different vendors.
+ <section id="custom_registration">
+ <title>Customization of Registration handling behavior</title>
+ <para>
+ Registration handling behavior can be customized by users to suit their
Producer needs. This is
+ accomplished by providing an implementation of the
+ <classname>RegistrationPolicy</classname>
+ interface. This interface defines methods that are called by Portal's
Registration service so that
+ decisions can be made appropriately. A default registration policy that
provides basic
+ behavior is provided and should be enough for most user needs.
</para>
- <para>
- 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>
+ While the default registration policy provides default behavior for most
registration-related aspects,
+ there is still one aspect that requires configuration: whether a given
value for a registration property
+ is acceptable by the WSRP Producer. This is accomplished by plugging a
+ <classname>RegistrationPropertyValidator</classname>
+ in the default registration policy. This allows users to define their own
validation mechanism.
</para>
- <para>
- Note that the our validation algorithm is only relaxed on aspects of the
specification that are deemed harmless such as invalid language codes.
+ <para>
+ Please refer to the
+ <trademark class="trade">Javadoc</trademark>
+ for
+
<classname>org.gatein.registration.RegistrationPolicy</classname>
+ and
+
<classname>org.gatein.registration.policies.RegistrationPropertyValidator</classname>
+ for more
+ details on what is expected of each method.
</para>
- <para>
- 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>
+ <para>Defining a registration policy is required for the producer to be
correctly configured. This is
+ accomplished by specifying the qualified class name of the registration
policy. Since we anticipate that
+ most users will use the default registration policy, it is possible to
provide the class
+ name of your custom property validator instead to customize the default
registration policy behavior.
+ Note that property validators are only used by the default policy.
- </section>
-
-
- </section>
-
- <section
id="sect-Reference_Guide_eXo_JCR_1.14-Web_Services_for_Remote_Portlets_WSRP-Removing_WSRP">
- <title>Removing WSRP</title>
+ <note>
+ <para>Since the policy or the validator are defined via their
class name and dynamically loaded, it is
+ important that you make sure that the identified class is available
to the application server. One
+ way
+ to accomplish that is to deploy your policy implementation as JAR
file in your AS instance deploy
+ directory. Note also that, since both policies and validators are
dynamically instantiated, they
+ must
+ provide a default, no-argument constructor.
+ </para>
+ </note>
+ </para>
+ </section>
+ </section>
+ <section id="strict-mode">
+ <title>WSRP validation mode</title>
+ <para>The lack of conformance kit and the wording of the WSRP
specification leaves room for differing
+ interpretations, resulting in interoperability issues. It is therefore
possible to encounter issues when
+ using consumers from different vendors. We have experienced such issues and
have introduced a way to relax
+ the validation that our WSRP producer performs on the data provided by
consumers to help with
+ interoperability by accepting data that would normally be invalid. Note that
we only relax our validation
+ algorithm on aspects of the specification that are deemed harmless such as
invalid language codes.
+ </para>
<para>
- If you are not going to use WSRP in your JBoss Enterprise Portal Platform
instance, the WSRP configuration files may be left in place. They will not adversely
affect your installation.
- </para>
- <para>
- However, if you wish to completely remove WSRP from your portal installation,
remove the <filename>gatein-wsrp-integration.ear</filename> file from your
application server deploy directory.
- </para>
- <!-- <para>
- However, if you wish to completely remove WSRP from your portal installation,
follow this procedure:
- </para>
- <procedure>
- <title></title>
- <step>
- <para>
- Navigate to the
<filename><replaceable>JBOSS_HOME</replaceable>/server/<replaceable><PROFILE></replaceable>/conf/gatein/</filename>
directory of your JBoss Enterprise Portal Platform instance.
- </para>
- <substeps>
- <step>
- <para>
- Open the <filename>configuration.xml</filename>
file and remove the following lines:
- </para>
-
-<programlisting language="XML"
role="XML"><value>
- <string>wsrp-producer</string>
-</value>
-</programlisting>
+ By default, the WSRP producer is configured in strict mode. If you experience
issues with a given consumer,
+ you might want to try to relax the validation mode. This is accomplished by
unchecking the "Use strict WSRP
+ compliance." checkbox on the Producer configuration screen.
+ </para>
+ </section>
- </step>
-
- </substeps>
-
- </step>
- <step>
- <para>
- Navigate up two directory levels and into the
<filename>deploy/gatein.ear/</filename> directory (For example:
<command>cd ../../deploy/gatein.ear/</command>).
- </para>
-
- </step>
- <step>
- <para>
- Remove the following files:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <filename>wsrp-admin-gui.war</filename>
- </para>
-
- </listitem>
- <listitem>
- <para>
- <filename>wsrp-producer.war</filename>
- </para>
-
- </listitem>
-
- </itemizedlist>
-
- </step>
- <step>
- <para>
- Navigate into the <filename>lib/</filename> subdirectory
and remove the following files:
- </para>
- <itemizedlist>
- <listitem>
- <para>
-
<filename>gatein.portal.component.wsrp-PORTAL_VERSION.jar</filename>
- </para>
-
- </listitem>
- <listitem>
- <para>
-
<filename>wsrp-common-WSRP_VERSION.jar</filename>
- </para>
-
- </listitem>
- <listitem>
- <para>
-
<filename>wsrp-consumer-WSRP_VERSION.jar</filename>
- </para>
-
- </listitem>
- <listitem>
- <para>
-
<filename>wsrp-integration-api-WSRP_VERSION.jar</filename>
- </para>
-
- </listitem>
- <listitem>
- <para>
-
<filename>wsrp-producer-lib-WSRP_VERSION.jar</filename>
- </para>
-
- </listitem>
- <listitem>
- <para>
-
<filename>wsrp-wsrp1-ws-WSRP_VERSION.jar</filename>
- </para>
-
- </listitem>
- <listitem>
- <para>
-
<filename>wsrp-wsrp2-ws-WSRP_VERSION.jar</filename>
- </para>
-
- </listitem>
-
- </itemizedlist>
-
- </step>
- <step>
- <para>
- Return to the <filename>gatein.ear/</filename> directory
and move into the <filename>META-INF/</filename> subdirectory.
- </para>
- <substeps>
- <step>
- <para>
- Open the <filename>application.xml</filename>
file and remove the following modules:
- </para>
-
-<programlisting language="XML"
role="XML"><module>
- <web>
- <web-uri>wsrp-admin-gui.war</web-uri>
- <context-root>wsrp-admin-gui</context-root>
- </web>
-</module>
-</programlisting>
-
-<programlisting language="XML"
role="XML"><module>
- <web>
- <web-uri>wsrp-producer.war</web-uri>
- <context-root>wsrp-producer</context-root>
- </web>
-</module>
-</programlisting>
-
- </step>
- <step>
- <para>
- Save and exit the file.
- </para>
-
- </step>
-
- </substeps>
-
- </step>
- <step>
- <para>
- Return to the <filename>gatein.ear/</filename> directory
and navigate into the <filename>02portal.war/WEB-INF/conf/</filename>
subdirectory.
- </para>
- <substeps>
- <step>
- <para>
- Remove the <filename>wsrp/</filename> directory.
- </para>
-
- </step>
- <step>
- <para>
- Open the <filename>configuration.xml</filename>
file and remove the following line:
- </para>
-
-<programlisting language="XML" role="XML"><import
profiles="jboss">war:/conf/wsrp/wsrp-configuration.xml</import>
-</programlisting>
-
- </step>
- <step>
- <para>
- Save and exit the file.
- </para>
-
- </step>
-
- </substeps>
-
- </step>
- <step>
- <para>
- From your current location, navigate into the
<filename>portal/</filename> subdirectory.
- </para>
- <substeps>
- <step>
- <para>
- Open the
<filename>portal-configuration.xml</filename> file and remove the line:
- </para>
-
-<programlisting language="XML"
role="XML"><value>org.exoplatform.portal.pom.spi.wsrp.WSRPState</value>
-</programlisting>
-
- </step>
- <step>
- <para>
- Save and exit the file.
- </para>
-
- </step>
-
- </substeps>
-
- </step>
- <step>
- <para>
- Return to the <filename>conf/</filename> directory and
move into the <filename>jcr/</filename> subdirectory.
- </para>
- <substeps>
- <step>
- <para>
- Open the
<filename>jcr-configuration.xml</filename> file and remove the line:
- </para>
-
-<programlisting language="XML" role="XML"><property
name="wsrp"
value="http://www.gatein.org/jcr/wsrp/1.0/"/>
-</programlisting>
-
- </step>
- <step>
- <para>
- Remove the following configuration file references:
- </para>
-
-<programlisting language="XML"
role="XML"><value>war:/conf/wsrp/consumers-configuration-nodetypes.xml</value>
-<value>war:/conf/wsrp/producer-configuration-nodetypes.xml</value>
-<value>war:/conf/wsrp/producer-registrations-nodetypes.xml</value>
-<value>war:/conf/wsrp/producer-pc-nodetypes.xml</value>
-<value>war:/conf/wsrp/migration-nodetypes.xml</value>
-</programlisting>
-
- </step>
- <step>
- <para>
- Save and exit the file.
- </para>
-
- </step>
- <step>
- <para>
- Open the
<filename>repository-configuration.xml</filename> and remove the <emphasis
role="bold">WSRP</emphasis> workspace:
- </para>
-
-<programlisting language="XML" role="XML">
- <workspace name="wsrp-system">
- <container>
- <properties>
- <property name="source-name"
value="${gatein.jcr.datasource.name}${container.name.suffix}"/>
- <property name="dialect"
value="${gatein.jcr.datasource.dialect}"/>
- <property name="multi-db" value="false"/>
- <property name="update-storage"
value="true"/>
- <property name="max-buffer-size"
value="204800"/>
- <property name="swap-directory"
value="${gatein.jcr.data.dir}/swap/wsrp${container.name.suffix}"/>
- </properties>
- <value-storages>
- <value-storage id="gadgets"
- >
- <properties>
- <property name="path"
value="${gatein.jcr.storage.data.dir}/wsrp${container.name.suffix}"/>
- </properties>
- <filters>
- <filter property-type="Binary"/>
- </filters>
- </value-storage>
- </value-storages>
- </container>
- <initializer>
- <properties>
- <property name="root-nodetype"
value="nt:unstructured"/>
- <property name="root-permissions"
value="*:/platform/administrators read;*:/platform/administrators
add_node;*:/platform/administrators set_property;*:/platform/administrators
remove"/>
- </properties>
- </initializer>
- <cache enabled="true">
- <properties>
- <property name="jbosscache-configuration"
value="${gatein.jcr.cache.config}" />
- <property name="jgroups-configuration"
value="${gatein.jcr.jgroups.config}" />
- <property name="jgroups-multiplexer-stack"
value="true" />
- <property name="jbosscache-cluster-name"
value="jcr-${container.name.suffix}-wsrp-system" />
- </properties>
- </cache>
- <query-handler>
- <properties>
- <property name="index-dir"
value="${gatein.jcr.index.data.dir}/wsrp-system${container.name.suffix}"/>
- <property name="changesfilter-class"
value="${gatein.jcr.index.changefilterclass}" />
- <property name="jbosscache-configuration"
value="${gatein.jcr.index.cache.config}" />
- <property name="jgroups-configuration"
value="${gatein.jcr.jgroups.config}" />
- <property name="jgroups-multiplexer-stack"
value="true" />
- <property name="jbosscache-cluster-name"
value="jcrindexer-${container.name.suffix}-wsrp-system" />
- <property name="max-volatile-time" value="60"
/>
- </properties>
- </query-handler>
- <lock-manager>
- <properties>
- <property name="time-out" value="15m" />
- <property name="jbosscache-configuration"
value="${gatein.jcr.lock.cache.config}" />
- <property name="jgroups-configuration"
value="${gatein.jcr.jgroups.config}" />
- <property name="jgroups-multiplexer-stack"
value="true" />
- <property name="jbosscache-cluster-name"
value="jcrlock-${container.name.suffix}-wsrp-system" />
- <property name="jbosscache-cl-cache.jdbc.table.name"
value="jcrlock_wsrp_system" />
- <property name="jbosscache-cl-cache.jdbc.table.create"
value="true" />
- <property name="jbosscache-cl-cache.jdbc.table.drop"
value="false" />
- <property name="jbosscache-cl-cache.jdbc.table.primarykey"
value="pk" />
- <property name="jbosscache-cl-cache.jdbc.fqn.column"
value="fqn" />
- <property name="jbosscache-cl-cache.jdbc.node.column"
value="node" />
- <property name="jbosscache-cl-cache.jdbc.parent.column"
value="parent" />
- <property name="jbosscache-cl-cache.jdbc.datasource"
value="${gatein.jcr.datasource.name}${container.name.suffix}" />
- </properties>
- </lock-manager>
- </workspace>
-</programlisting>
-
- </step>
-
- </substeps>
-
- </step>
- <step>
- <title>Optional:</title>
- <para>
- Remove any references to <emphasis>WSRP</emphasis> from
the following files:
- </para>
- <itemizedlist>
- <listitem>
- <para>
-
<filename>gatein.ear/01eXoResources.war/META-INF/MANIFEST.MF</filename>
- </para>
-
- </listitem>
- <listitem>
- <para>
-
<filename>gatein.ear/META-INF/MANIFEST.MF</filename>
- </para>
-
- </listitem>
- <listitem>
- <para>
-
<filename>gatein.ear/02portal.war/META-INF/MANIFEST.MF</filename>
- </para>
-
- </listitem>
-
- </itemizedlist>
-
- </step>
-
- </procedure> -->
- </section>
-
-
+ </section>
</chapter>
-