Author: aakanksha_writer
Date: 2013-01-23 10:47:09 -0500 (Wed, 23 Jan 2013)
New Revision: 9073
Modified:
epp/docs/branches/6.0/Reference_Guide/en-US/Revision_History.xml
epp/docs/branches/6.0/Reference_Guide/en-US/modules/PortalDevelopment/DefaultPortalNavigationConfiguration.xml
epp/docs/branches/6.0/Reference_Guide/en-US/modules/WSRP.xml
Log:
Updated chapter Portal Development and WSRP extensions
Modified: epp/docs/branches/6.0/Reference_Guide/en-US/Revision_History.xml
===================================================================
--- epp/docs/branches/6.0/Reference_Guide/en-US/Revision_History.xml 2013-01-23 00:39:56
UTC (rev 9072)
+++ epp/docs/branches/6.0/Reference_Guide/en-US/Revision_History.xml 2013-01-23 15:47:09
UTC (rev 9073)
@@ -7,6 +7,22 @@
<title>Revision History</title>
<simpara>
<revhistory>
+ <revision>
+ <revnumber>6.0.0-33</revnumber>
+ <date>Wed Jan 23 2013</date>
+ <author>
+ <firstname>Aakanksha</firstname>
+ <surname>Singh</surname>
+ <email/>
+ </author>
+ <revdescription>
+ <simplelist>
+ <member>Rebased changes for
https://docs.jboss.org/author/display/GTNPORTAL35/Portal+Navigation+Confi...
</member>
+ <member>Rebased changes for
https://docs.jboss.org/author/display/GTNPORTAL35/Working+with+WSRP+exten...
+ </simplelist>
+ </revdescription>
+ </revision>
+
<revision>
<revnumber>6.0.0-32</revnumber>
<date>Wed Jan 23 2013</date>
Modified:
epp/docs/branches/6.0/Reference_Guide/en-US/modules/PortalDevelopment/DefaultPortalNavigationConfiguration.xml
===================================================================
---
epp/docs/branches/6.0/Reference_Guide/en-US/modules/PortalDevelopment/DefaultPortalNavigationConfiguration.xml 2013-01-23
00:39:56 UTC (rev 9072)
+++
epp/docs/branches/6.0/Reference_Guide/en-US/modules/PortalDevelopment/DefaultPortalNavigationConfiguration.xml 2013-01-23
15:47:09 UTC (rev 9073)
@@ -166,16 +166,7 @@
</warning>
</listitem>
</varlistentry>
- <varlistentry>
- <term>Subnodes</term>
- <listitem>
- <para>
- Subnodes can also be created using the following XML structure
- </para>
- <programlisting language="XML"
role="XML"><xi:include
xmlns:xi="http://www.w3.org/2001/XInclude"
href="../../extras/PortalDevelopment_DefaultPortalNavigationConfiguration/subpage.xml"
parse="text"/></programlisting>
- </listitem>
- </varlistentry>
- <varlistentry>
+ <varlistentry>
<term>pages.xml</term>
<listitem>
<para>
@@ -184,7 +175,7 @@
<para>
Each application can decide whether to render the portlet border,
the window state, the icons, or the portlet mode.
</para>
-<!-- DOC NOTE: look into including some actual examples of 'container
tags' from sharedlayout.xml in place here. --> <programlisting
language="XML" role="XML"><xi:include
xmlns:xi="http://www.w3.org/2001/XInclude"
href="../../extras/PortalDevelopment_DefaultPortalNavigationConfiguration/pages.xml"
parse="text"/></programlisting>
+
</listitem>
</varlistentry>
</variablelist>
@@ -216,5 +207,5 @@
The example below shows a dashboard with all of the default gadgets included,
as well as an extra currency converter gadget sourced from <ulink
url="http://www.google.com/ig/directory?synd=open"
type="http">Google Gadgets</ulink>.
</para>
<programlisting language="XML" role="XML"><xi:include
xmlns:xi="http://www.w3.org/2001/XInclude"
href="../../extras/PortalDevelopment_DefaultPortalNavigationConfiguration/gadgets.xml"
parse="text"/></programlisting>
- </section>
+ </section>
</chapter>
Modified: epp/docs/branches/6.0/Reference_Guide/en-US/modules/WSRP.xml
===================================================================
--- epp/docs/branches/6.0/Reference_Guide/en-US/modules/WSRP.xml 2013-01-23 00:39:56 UTC
(rev 9072)
+++ epp/docs/branches/6.0/Reference_Guide/en-US/modules/WSRP.xml 2013-01-23 15:47:09 UTC
(rev 9073)
@@ -1814,7 +1814,7 @@
</ulink> and
<ulink
url="https://github.com/gatein/gatein-wsrp/blob/master/producer/src/...
-
<classname>org.gatein.registration.policies.RegistrationPropertyValidator</classname>
+
<classname>org.gatein.registration.policies.RegistrationPropertyValidator</classname>
</ulink> for more
details on what is expected of each method.
</para>
@@ -1824,7 +1824,7 @@
<title>DefaultRegistrationPolicy</title>
<mediaobject>
<imageobject>
- <imagedata fileref="images/WSRP/producer_default.png"
width="666"/>
+ <imagedata width="666"
fileref="images/WSRP/producer_default.png"/>
</imageobject>
</mediaobject>
</figure>
@@ -1877,4 +1877,316 @@
</para>
</section>
</section>
+ <section>
+ <title>Working with WSRP Extensions</title>
+ <section>
+ <title>Overview</title>
+ <para>
+ The WSRP specifications allows for implementations to extend the protocol using
+ <ulink
url="http://docs.oasis-open.org/wsrp/v2/wsrp-2.0-spec-os-01.html#_Ex...
+ . GateIn Portal, as of its WSRP implementation version 2.2.0, provides a way for
client code (e.g. portlets) to interact with such extensions in the form of several
classes and interfaces gathered within the
+ <ulink
url="https://github.com/gatein/gatein-wsrp/tree/master/api/src/main/...
package </ulink>
+ , the most important ones being
+ <code>InvocationHandlerDelegate</code>
+ ,
+ <code>ConsumerExtensionAccessor</code>
+ and
+ <code>ProducerExtensionAccessor</code>
+ .
+ </para>
+ <para>
+ To be able to use this API, you will need to include the
+ <code>wsrp-integration-api-$WSRP_VERSION.jar</code>
+ file to your project, where
+ <code>$WSRP_VERSION</code>
+ is the version of the GateIn Portal WSRP implementation you wish to use,
2.2.2.Final being the current one. This can be done by adding the following dependency to
your maven project:
+ </para>
+ <informalexample>
+ <programlisting>
+<dependency>
+ <groupId>org.gatein.wsrp</groupId>
+ <artifactId>wsrp-integration-api</artifactId>
+ <version>$WSRP_VERSION</version>
+</dependency>
+</programlisting>
+ </informalexample>
+ <section>
+ <title>InvocationHandlerDelegate infrastructure</title>
+ <para>
+ Using the
+ <code>InvocationHandlerDelegate</code>
+ infrastructure, custom behavior can now be inserted on either consumer or
producer sides to enrich WSRP applications before and/or after portlet requests and/or
responses. Please refer to the Javadoc for
+ <ulink
url="https://github.com/gatein/gatein-wsrp/blob/master/api/src/main/...
+
<code>org.gatein.wsrp.api.extensions.InvocationHandlerDelegate</code>
+ </ulink>
+ for more details on this interface and how to implement it.
+ </para>
+ <warning>
+ <para>
+ Since
+ <code>InvocationHandlerDelegate</code>
+ is a very generic interface, it could potentially be used for more than simply
working with WSRP extensions. Moreover, since it has access to internal GateIn Portal
classes, it is important to be treat access to these internal classes as
+ <emphasis role="strong">read-only</emphasis>
+ to prevent any un-intentional side-effects.
+ </para>
+ </warning>
+ </section>
+ <section>
+ <title>Injecting InvocationHandlerDelegate implementations</title>
+ <para>
+ Implementations of
+ <code>InvocationHandlerDelegate</code>
+ <emphasis role="strong">must</emphasis>
+ follow the same constraints as
+ <code>RegistrationPolicy</code>
+ implementations as detailed in
+ <ulink
url="https://docs.jboss.org/author/pages/viewpage.action?pageId=5426...
of Registration handling behavior</ulink>
+ section of the
+ <ulink
url="https://docs.jboss.org/author/pages/viewpage.action?pageId=5426...
GateIn's WSRP Producer</ulink>
+ chapter, in essence, they
+ <emphasis role="strong">must</emphasis>
+ follow the Java
+ <ulink
url="http://docs.oracle.com/javase/7/docs/api/java/util/ServiceLoade...
+ <code>ServiceLoader</code>
+ </ulink>
+ architectural pattern and be deployed in the appropriate
+ <code>$JBOSS_HOME/gatein/extensions</code>
+ directory.
+ </para>
+ <para>
+ You can specify only one
+ <code>InvocationHandlerDelegate</code>
+ implementation per side: one implementation for the consumer and another one for
the producer. This is accomplished by passing the fully classified class name to the
appropriate system property when the portal is started:
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>
+ <para>WSRP side</para>
+ </entry>
+ <entry>
+ <para>System property</para>
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <para>consumer</para>
+ </entry>
+ <entry>
+ <para>org.gatein.wsrp.consumer.handlers.delegate</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>producer</para>
+ </entry>
+ <entry>
+ <para>org.gatein.wsrp.producer.handlers.delegate</para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ <section id="sid-55477864_WorkingwithWSRPextensions-Example">
+ <title>Example</title>
+ <informalexample>
+ <programlisting>./standalone.sh
-Dorg.gatein.wsrp.consumer.handlers.delegate=com.example.FooInvocationHandlerDelegate</programlisting>
+ </informalexample>
+ <para>
+ will inject the
+ <code>com.example.FooInvocationHandlerDelegate</code>
+ class on the consumer side, assuming that class implements the
+
<code>org.gatein.wsrp.api.extensions.InvocationHandlerDelegate</code>
+ interface and is packaged and deployed appropriately as explained above.
+ </para>
+ </section>
+ </section>
+ <section
id="sid-55477864_WorkingwithWSRPextensions-Accessingextensionsfromclientcode">
+ <title>Accessing extensions from client code</title>
+ <para>
+ You can access extensions from client code using
+ <code>ConsumerExtensionAccessor</code>
+ and
+ <code>ProducerExtensionAccessor</code>
+ on the consumer and producer, respectively. Each interface provides several
methods but you should only have to ever call two of them on each, as shown in the
following table:
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>
+ <para>Interface</para>
+ </entry>
+ <entry>
+ <para>Relevant methods</para>
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <para>
+ <code>ConsumerExtensionAccessor</code>
+ </para>
+ </entry>
+ <entry>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <code>public void addRequestExtension(Class targetClass,
Object extension)</code>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <code>public List<UnmarshalledExtension>
getResponseExtensionsFrom(Class responseClass)</code>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <code>ProducerExtensionAccessor</code>
+ </para>
+ </entry>
+ <entry>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <code>List<UnmarshalledExtension>
getRequestExtensionsFor(Class targetClass)</code>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <code>void addResponseExtension(Class wsrpResponseClass,
Object extension)</code>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ <para>Please refer to the Javadoc for these classes for more
details.</para>
+ <note>
+ <para>We currently only support adding and accessing extensions from a
core subset of WSRP classes pertaining to markup, interaction, resource or event requests
and responses, as follows:</para>
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>
+ <para>Request classes</para>
+ </entry>
+ <entry>
+ <para>Response classes</para>
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <para>
+ <code>org.oasis.wsrp.v2.InteractionParams</code>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <code>org.oasis.wsrp.v2.MarkupResponse</code>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <code>org.oasis.wsrp.v2.EventParams</code>
+ </para>
+ </entry>
+ <entry>
+ <para>
+
<code>org.oasis.wsrp.v2.BlockingInteractionResponse</code>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <code>org.oasis.wsrp.v2.MarkupParams</code>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <code>org.oasis.wsrp.v2.HandleEventsResponse</code>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <code>org.oasis.wsrp.v2.ResourceParams</code>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <code>org.oasis.wsrp.v2.ResourceResponse</code>
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </note>
+ <note>
+ <para>
+ We
+ <emphasis role="strong">strongly</emphasis>
+ recommend that you use
+ <code>org.w3c.dom.Element</code>
+ values as extensions for interoperability purposes.
+ </para>
+ </note>
+ </section>
+ </section>
+ <section>
+<title>Example implementation</title>
+ <para>
+ We also provide a complete, end-to-end example to get you started, which you can
find at
+ <ulink
url="https://github.com/gatein/gatein-wsrp/tree/master/examples/invo...
+ . This example shows how
+ <code>ExampleConsumerInvocationHandlerDelegate</code>
+ , a consumer-side
+ <code>InvocationHandlerDelegate</code>
+ implementation, can add information extracted from the consumer and pass it along
to the producer, working in conjunction with
+ <code>ExampleProducerInvocationHandlerDelegate</code>
+ , the associated producer-side
+ <code>InvocationHandlerDelegate</code>
+ , to establish a round-trip communication channel outside of the standard WSRP
protocol, implementing the following scenario:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <code>ExampleConsumerInvocationHandlerDelegate</code>
+ attaches to the consumer to add the current session id as an extension to
render requests sent to the producer.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <code>ExampleProducerInvocationHandlerDelegate</code>
+ provides the counterpart of
+ <code>ExampleConsumerInvocationHandlerDelegate</code>
+ on the producer. It checks incoming render requests for potential extensions
matching what
+ <code>ExampleConsumerInvocationHandlerDelegate</code>
+ sends and adds an extension of its own to the render response so that the
consumer-side delegate can know that the information it passed was properly processed.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <sidebar>
+ <para>To activate the InvocationHandlerDelegates on both the consumer and
producer, start your GateIn Portal instance as follows:</para>
+ </sidebar>
+</section>
+
+ </section>
</chapter>