cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From da...@cocoon.zones.apache.org
Subject [DAISY] Created: WSRP Support
Date Tue, 30 Aug 2005 11:50:56 GMT
A new document has been created.

http://cocoon.zones.apache.org/daisy/documentation/682.html

Document ID: 682
Branch: main
Language: default
Name: WSRP Support
Document Type: Document
Created: 8/30/05 11:50:55 AM
Creator (owner): Carsten Ziegeler
State: draft

Parts
=====

Content
-------
Mime type: text/xml
Size: 17408 bytes
Content:
<html>
<body>

<h1>General information</h1>

<p>The Web Services for Remote Portlets (WSRP) specification defines a web
service interface for accessing and interacting with interactive
presentation-oriented web services. This documentation explains the usage of
WSRP portlets including explanation about the functional process.</p>

<p>The latest version of the Cocoon Portal implements a WSRP consumer to allow
the usage of WSRP portlets. A WSRP portlets is provided by WSRP producers that
allow access over standardized web services - the WSRP interfaces. The Cocoon
Portal supports verson 1.0 of the WSRP specification by integrating the Apache
WSRP4J framework.</p>

<p>For further information about WSRO see:<br/>
  - Oasis: Committee that defines the WSRP specification<br/>
   
<a href="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wsrp">http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wsrp</a>
<br/>
  - Apache: Standard open source implementation of WSRP in Java   <br/>
    <a href="http://ws.apache.org/wsrp4j">http://ws.apache.org/wsrp4j</a></p>

<h1> Enabling WSRP</h1>

<p>The demo of the Cocoon Portal included in the Cocoon distribution comes with
WSRP enabled. However, depending on your use case it's possible to
disable/enable the WSRP support of the portal in the cocoon.xconf. If you're
just interested in how to use WSRP, you can skip this section for now.</p>

<p>The WSRP consumer of the portal makes use of four components in the
cocoon.xconf: the WSRP event aspect, the WSRP coplet adapter, the WSRP portlet
window aspect and the user context provider. If you want to disable WSRP, you
should uncomment these four components and their usage (explained below).</p>

<pre>  &lt;!-- Event Aspect configuration --&gt;
 &lt;component class="org.apache.cocoon.components.ExtendedComponentSelector"
            role="org.apache.cocoon.portal.event.aspect.EventAspectSelector"&gt;
      ...
   &lt;!-- This aspect is required for wsrp: --&gt;
   &lt;aspect class="org.apache.cocoon.portal.wsrp.adapter.WSRPEventAspect" logger="portal"
name="wsrp"/&gt;
 &lt;/component&gt;
   
    &lt;!-- Coplet Adapter configuration --&gt;
    &lt;component class="org.apache.cocoon.components.ExtendedComponentSelector"
               role="org.apache.cocoon.portal.coplet.adapter.CopletAdapterSelector"&gt;
      ...
   &lt;!-- This is the wsrp adapter --&gt;
   &lt;coplet-adapter class="org.apache.cocoon.portal.wsrp.adapter.WSRPAdapter" logger="portal"
name="wsrp"&gt;
     &lt;!-- This is the wsrp configuration containing the producers etc. --&gt;
  &lt;parameter name="wsrp-config" value="profiles/wsrp-config.xml"/&gt;
   &lt;/coplet-adapter&gt;
 &lt;/component&gt;</pre>

<pre>&lt;!-- Renderer Aspect configuration --&gt;
 &lt;component class="org.apache.cocoon.components.ExtendedComponentSelector"
            role="org.apache.cocoon.portal.layout.renderer.aspect.RendererAspectSelector"&gt;
   ...
      &lt;aspect class="org.apache.cocoon.portal.wsrp.adapter.WSRPPortletWindowAspect"
logger="portal" name="wsrp-window"/&gt;
      ...
    &lt;/component&gt;</pre>

<pre>    &lt;!--  User Context Provider for WSRP --&gt;
    &lt;component class="org.apache.cocoon.portal.wsrp.consumer.UserContextProviderImpl"
logger="portal"
               role="org.apache.cocoon.portal.wsrp.consumer.UserContextProvider"/&gt;</pre>

<p>All of these components have to be configured to be used by the various parts
of the Cocoon Portal. Again, if you want to disable the WSRP support, you have
to uncomment the usage as well.</p>

<p>The event manager needs to be aware of the events dealing with WSRP,
therefore we have to configure the WSRP event aspect on the event manager:</p>

<pre>    &lt;component class="org.apache.cocoon.portal.event.impl.DefaultEventManager"
logger="portal" role="org.apache.cocoon.portal.event.EventManager"&gt;
   &lt;event-aspects&gt;
         ...
        &lt;!-- Comment the following out if you don't need WSRP: --&gt;
        &lt;aspect type="wsrp"/&gt;
         ...
   &lt;/event-aspects&gt;
 &lt;/component&gt;</pre>

<p>The portal manager needs to be aware of dealing with WSRP portlets, therefore
we have to configure the WSRP coplet adapter as an aspect of the portal manager:
</p>

<pre>    &lt;component class="org.apache.cocoon.portal.impl.PortalManagerImpl"
logger="portal" role="org.apache.cocoon.portal.PortalManager"&gt;
      &lt;aspects&gt;
        ...
        &lt;!-- wsrp support: --&gt;
        &lt;aspect adapter="wsrp"/&gt;
      &lt;/aspects&gt;
    &lt;/component&gt;</pre>

<p>The last step is to configure an own renderer for the WSRP portlets. You can
configure/define this renderer according to your needs, but be sure to include
the wsrp-window aspect. This aspect is required for rendering the title bar
containing the icons.</p>

<pre>    &lt;!-- Renderer configuration --&gt;
    &lt;component class="org.apache.cocoon.components.ExtendedComponentSelector" role="org.apache.cocoon.portal.layout.renderer.RendererSelector"&gt;
      ...
   &lt;renderer class="org.apache.cocoon.portal.layout.renderer.impl.AspectRenderer"
             logger="portal"
             name="wsrp-window"&gt;
     &lt;aspects&gt;
    &lt;aspect type="xslt"&gt;
   &lt;parameter name="style" value="{portal-skin:skin.basepath}/styles/window.xsl"/&gt;
    &lt;/aspect&gt;
          &lt;aspect type="parameter"&gt;
            &lt;parameter name="tag-name" value="window"/&gt;
    &lt;/aspect&gt;
          &lt;aspect type="wsrp-window"&gt;
            &lt;parameter name="root-tag" value="false"/&gt;
          &lt;/aspect&gt;
          &lt;aspect type="coplet-removing"/&gt;
          &lt;aspect type="history"/&gt;
          &lt;aspect type="coplet-cinclude"/&gt;
        &lt;/aspects&gt;
      &lt;/renderer&gt;
      ...
    &lt;/component&gt;</pre>

<h1>Defining WSRP portlets</h1>

<h2>The WSRP Coplet Adapter</h2>

<p>The Cocoon Portal uses the concept of coplet adapters to integrate different
types of portlets (Cocoon pipelines, JSR 168, WSRP etc.). The adapter component
is configured in the cocoon.xconf as we have seen above. The portal application
defines a coplet base data using the adapter. You can find the configuration for
the demo portal in the profiles/copletbasedata directory which is located in the
directory containing the portal demo. The portal.xml contains the configuration:
</p>

<pre>    &lt;coplet-base-data id="WSRP"&gt;
      &lt;coplet-adapter&gt;wsrp&lt;/coplet-adapter&gt;
        &lt;configuration&gt;
          &lt;name&gt;buffer&lt;/name&gt;
          &lt;value xsi:type="java:java.lang.Boolean"&gt;true&lt;/value&gt;
        &lt;/configuration&gt;
      &lt;/coplet-adapter&gt;
    &lt;/coplet-base-data&gt;</pre>

<p>This file defines a corresponding adapter to use WSRP. The configuration
"buffer" decides if the streamed content should be buffered before it is send
into the pipeline. Buffering is required if during streaming of the portlet
content an error might occur. Without buffering a part of the portlet content
has been already streamed into the pipeline and can't be reset on an error. This
results in a broken page. Therefore buffering should always be turned on for
WSRP.</p>

<h2>The WSRP Configuration</h2>

<p>The Cocoon Portal uses a central configuration for WSRP. Currently this
configuration holds all WSRP producers. The demo of the portal contains already
a sample configuration for the WSRP4J producers running locally.</p>

<p>The WSRP configuration is in the profiles/wsrp-config.xml file inside the
portal directory. If you want to use a different location, you can configure it
as a parameter on the WSRP coplet adapter in the cocoon.xconf. This is the
sample wsrp-config.xml:</p>

<pre>   &lt;wsrp-config&gt;
      &lt;producers&gt;
        &lt;producer id="prod_localhost_8081"&gt;
          &lt;markup-interface-url&gt;http://localhost:8081/wsrp/wsrp4j/WSRPBaseService&lt;/markup-interface-url&gt;
          &lt;service-description-interface-url&gt;http://localhost:8081/wsrp/wsrp4j/WSRPServiceDescriptionService&lt;/service-description-interface-url&gt;
          &lt;registration-interface-url&gt;http://localhost:8081/wsrp/wsrp4j/WSRPRegistrationService&lt;/registration-interface-url&gt;
          &lt;portlet-management-interface-url&gt;http://localhost:8081/wsrp/wsrp4j/WSRPPortletManagementService&lt;/portlet-management-interface-url&gt;
        &lt;/producer&gt;
      &lt;/producers&gt;
    &lt;/wsrp-config&gt;</pre>

<p>Each producer has to be registered here.A producer is uniquely identified by
it's id. The id is specified as an attribute on the producer element. As the
identifier has to be unique, it is advisable to include the host and the port of
the producer, like in the example:  "prod_&lt;host&gt;_&lt;port&gt;".</p>

<p>The producer requires some configuration: the urls of the different
web-services. Whereas the markup-interface-url and the
service-description-interface-url are required, the registration-interface-url
and the portlet-management-url are optional. Each url is configured using an
element with the value being the url of the web-service.</p>

<p>Once the producer is configured, we can start defining portlets using this
producer. This is done in the usual fashion as a configuration of the coplet
data.</p>

<h2>Coplet Data Configuration</h2>

<p>You can have a look at the global coplet data configuration in the
"profiles/copletdata" directory of the demo portal. In the portal.xml you will
find a WSRP sample using the standard WSRP4J test portlet:</p>

<pre>    &lt;coplet-data id="wsrp-test-portlet" name="standard"&gt;
      &lt;title&gt;WSRP-Test-Portlet&lt;/title&gt;
      &lt;coplet-base-data&gt;WSRP&lt;/coplet-base-data&gt;
      &lt;attribute&gt;
        &lt;name&gt;producer-id&lt;/name&gt;
        &lt;value xsi:type="java:java.lang.String"&gt;prod_localhost_8081&lt;/value&gt;
      &lt;/attribute&gt;
      &lt;attribute&gt;
        &lt;name&gt;portlet-handle&lt;/name&gt;
        &lt;value xsi:type="java:java.lang.String"&gt;0.1&lt;/value&gt;
      &lt;/attribute&gt;
      &lt;attribute&gt;
        &lt;name&gt;use-pipeline&lt;/name&gt;
        &lt;value xsi:type="java:java.lang.Boolean"&gt;true&lt;/value&gt;
      &lt;/attribute&gt;
    &lt;/coplet-data&gt;</pre>

<p>The coplet-base-data element references the coplet base data object for the
WSRP support as explained above. Using the title element you can set a standard
window title for this portlet. This title will be used if the WSRP portlet
doesn't provide its own title.</p>

<p>The following elements define the required attributes for this portlet. The
first attribute sets the producer to be used. The name of the attribute is
"producer-id" and the value contains the unique name of the WSRP producer
as defined in the WSRP configuration (see above). A producer can define
more than one portlet, therefore each portlet offered by the producer has a
unique handle. With the "portlet-handle" attribute, you have to define this
unique handle for the portlet you want to use.<br/>
 The content of a WSRP portlet is by default not send through the pipeline. This
is in order to avoid unnecessary HTML parsing. Instead the content is added by
the<br/>
 serializer after the pipeline has finished. If you want to send the content
of a WSRP portlet through the pipeline for further processing, you can set the
attribute "use-pipeline" to "true".</p>

<h2>Creating Instances</h2>

<p>The final step is to create one or more instances of the WSRP portlet for the
acutal user. Again, this is done in the usual way by adding instances to the
coplet instance data profile. The sample portal contains already such a
definition in the file "profiles/copletinstancedata/portal.xml":</p>

<pre>   &lt;coplet-instance-data id="WSRP-Test-1" name="standard"&gt;
      &lt;coplet-data&gt;wsrp-test-portlet&lt;/coplet-data&gt;
    &lt;/coplet-instance-data&gt;</pre>

<p>It is possible to create more than one instance of the same WSRP portlet.
Each coplet instance data gets a unique id (using the id attribute) and has a
reference to the defined coplet data (using the coplet-data element).</p>

<h1>Using WSRP portlets</h1>

<p>    As usual the final step is to add the WSRP portlet somewhere in the
portal page<br/>
    of the user. The demo portal already contains a WSRP portlet: if you log
into<br/>
    the portal there is a separate tab named "WSRP" containing the portlet.</p>

<p>    If you look into the layout file at "profiles/layout/portal.xml", you
will see<br/>
    the usage of the portlet:</p>

<p>    &lt;coplet-layout name="coplet" layout-renderer-name="wsrp-window"&gt;
<br/>
   &lt;coplet-instance-data&gt;WSRP-Test-1&lt;/coplet-instance-data&gt;<br/>
 &lt;/coplet-layout&gt;</p>

<p>    It is required that the coplet layout uses the special "wsrp-window"
renderer<br/>
    for rendering a WSRP portlet. The "wsrp-window" renderer is responsible for
<br/>
    rendering the special title bar containing the icons for the WSRP functions
<br/>
    like view, edit or help.     </p>

<p> III. d) Layouting<br/>
 -----------------</p>

<p> The WSRP specification defines some css styles for the consumer. The Cocoon
Portal<br/>
 already contains an empty css definition for WSRP. You'll find the file in the
<br/>
 corresponding skin directory: "css/wsrp.css".</p>

<p>    The following sections can be configured: fonts, messages, sections,
tables, forms<br/>
    and menus.</p>

<p> III. b) Pipelining<br/>
 -----------------------------</p>

<p>    The WSRP portlet might use/display different resources like images.
Therefore the<br/>
    portal sitemap contains a special pipeline for delivering these resources:
</p>

<p>    &lt;!--  WSRP Resources --&gt;<br/>
    &lt;map:match pattern="wsrprsc"&gt;<br/>
      &lt;map:read src="{request-param:wsrp-url}"/&gt;<br/>
    &lt;/map:match&gt;</p>

<p> III. e) Logging<br/>
 ---------------------</p>

<p>    The WSRP part of the Cocoon Portal uses the standard portal logger for
all<br/>
    logging purpuses. By default, all log entries go into the portal.log in
<br/>
    the logs directory. You can adjust the settings in the logkit.xconf.</p>

<p>    Providing User Information</p>

<p>    WSRP allows exchanging information about the user between the consumer
and the<br/>
    producer. As these information are portal application specific, the default
<br/>
    implementation of the Cocoon Portal is only sending the user id (used to
<br/>
    authenticate the user).<br/>
    It is possible to customize this information by implementing a<br/>
    org.apache.cocoon.portal.wsrp.consumer.UserContextProvider and configuring
it<br/>
    in the cocoon.xconf.</p>

<h2>    Customizing the WSRP4J integration</h2>

<h2>    If you have special needs it's possible to customize the WSRP4J
integration. <br/>
    The integration itself is implement in several components you can subclass
<br/>
    and then use your own implementation.</h2>

<h2>    You can specify your own implementation using the following parameter
names as a<br/>
    configuration on the WSRPAdapter:<br/>
    user-registry-class : org.apache.wsrp4j.consumer.UserRegistry.<br/>
    session-handler-class : org.apache.wsrp4j.consumer.SessionHandler<br/>
    producer-registry-class : org.apache.wsrp4j.consumer.ProducerRegistry<br/>
    portlet-registry-class : org.apache.wsrp4j.consumer.PortletRegistry<br/>
    url-template-composer-class : org.apache.wsrp4j.consumer.URLTemplateComposer
<br/>
    url-rewriter-class : org.apache.wsrp4j.consumer.URLRewriter<br/>
    portlet-driver-registry-class :
org.apache.wsrp4j.consumer.PortletDriverRegistry<br/>
    url-generator-class : org.apache.wsrp4j.consumer.URLGenerator<br/>
    portlet-driver-class : org.apache.wsrp4j.consumer.PortletDriver</h2>

<h2>Adding Producers at runtime</h2>

<p>The Cocoon Portal uses the wsrp configuration (as explained above) to
configure all available WSRP producers. However, it is possible to add producers
at runtime<br/>
using the WSRP adapter. Create a
"org.apache.cocoon.portal.wsrp.consumer.ProducerDescription" object. You have to
set a unique id, the markup interface url and the service description interface
url; the registration interface url and portlet management interface url are
optional.</p>

<p>Lookup the WSRP adapter from a ServiceManager and invoke the addProducer()
method:</p>

<pre>ServiceSelector selector = (ServiceSelector)serviceManager.lookup(CopletAdapter.ROLE
+ "Selector");
WSRPAdapter adapter = (WSRPAdapter)selector.select("wsrp");</pre>

<pre>adapter.addProducer(description);</pre>

<pre>selector.release(adapter);
serviceManager.release(selector);</pre>

</body>
</html>

Collections
===========
The document belongs to the following collections: documentation

Mime
View raw message