Wednesday, February 06, 2008

Guide To Setup A Running WSRP4J - Producer and Consumer


A simple test page with the consumer a portlet in jetspeed 2.1 (Tomcat console above port 8081) and the producer in pluto 1.0.1 release (tomcat console beloew port 8080)

I. Introduction

WSRP is an open standard proposed by OASIS for several years. The spec now is sponsored by a number of
big names like IBM and BEA. There are currently two active implementation of the spec. One is wsrp4j from
Apache foundation (still a incubator project, been developed since 2002). The other one is a subproject of
dev.java.net Open-Portal.

I have been exposed and done lot of development on the Apache's wsrp4j project. Thus, in this guide I will
mainly discuss wsrp4j implementation.

At this point, wsrp4j project is still under heavy development and re-construction. It is almost impossible
to get the trunk snapshot in the project repository and make it work without pulling all your hair out to figure
out how to set it up properly. This mostly caused by the lack of documentation and support from its developers.

Still, there is a stable (enough) revision which we can use to make a perfect wsrp4j environment.
The wsrp4j revison I use here is 440430 along with pluto portal 1.0.1 release for setting up a producer.
Jetspeed 2.1 (latest version currently) will be used as a container for wsrp4j consumer (wsrp4j-proxyportlet).
Of course, you can use pluto to setup wsrp4j consumer as well. But that is very easy to do.
Plus, pluto portal doesn't provide a lot of bell and whistle in the GUI side as Jetspeed portal does.

II. Weapons Needed

- JDK 5
- maven 2.1 for bulding wsrp4j revison 440430
- maven 1.0.2 for bulding pluto 1.0.1
- Tomcat 5 (hosting the wsrp producer)
- Jetspeed 2.1 (hosting the wsrp consumer)

III. The Battle

1. Setting up Pluto 1.0.1

Download the source version of Pluto 1.0.1
Unzip/tar the file and change the build.properties.sample to build.properties
Edit the build.properties file to make sure the path to Tomcat is correct
Maven 1.0.2 is used to build this copy of Pluto so set your MAVEN_HOME accordingly
run 'maven fullDeployment' to build the project.
Once this finish, start your tomcat and point browser to
http://localhost:8080/pluto/portal to test

Shutdown Tomcat before deploying WSRP4J.

-------------------------------------------------------------

2. Obtaining WSRP4J From SVN 440430

Get wsrp4j source in subversion
svn -r 440430 co https://svn.apache.org/repos/asf/portals/wsrp4j/trunk

This version of WSRP4J is built using Maven 2, in our case Maven 2.0.4 was used.

After checking out the source code from Subversion, only a few modifications are needed in order for this version to work correctly.

Enter the source code’s root directory and edit the
build.properties.sample file to include the location of Tomcat:
maven.tomcat.home=/path/to/tomcat

Then rename this file to
build.properties

Issue this command to compile WSRP4J:
mvn install

This command will compile and package the consumers and producer as WAR archives.

-------------------------------------------------------------

3. Deploying and Fixing WSRP4J 440430 Producer

The WSRP Test Portlet is located at
testportlet/target/wsrp4j-testportlet.war
this can be deployed via Pluto’s admin interface.

To deploy the producer, copy
producer/target/wsrp4j-producer.war to $TOMCAT/webapps

Only a few fixes need to be implemented in this version of WSRP4J:

There is a missing XML, file copy
producer/src/xml/wsrp4j-producer.xml
to
$TOMCAT/conf/Catalina/loclahost/

This will enable crossContext for the WSRP4J producer. If this is not done the logs show an error
Unable to find dispatcher for context wsrp4j producer

There is also a jar file that needs removing
$TOMCAT/webapps/wsrp4j-producer/WEB-INF/lib/pluto-1.0.1.jar
This causes an exception about a class not being found org.exolab.castor.mapping.Mapping....
Leave the pluto-portal-1.0.1.jar alone.

From the installed version of wsrp, located in

$TOMCAT/webapps/wsrp4j-producer

This file needs editing to match the running environment:

* $TOMCAT/webapps/wsrp4j-producer/wsdl/wsrp_service.wsdl needs to have the correct host and port numbers.

!!!Important: Also copy the wsrp4j-config.properties from the wsrp4j-proxyportlet/WEB-INF to the wsrp4j-producer/WEB-INF

-------------------------------------------------------------

4. Setup a test Portlet in the Producer:

Edit $TOMCAT/webapps/wsrp4j-producer/WEB-INF/data/portletentityregistry.xml
This will add the wsrp4j-testportlet to the producer
<application id="0">
<definition-id>wsrp4j-testportlet</definition-id>
<portlet id="1">
<definition-id>wsrp4j-testportlet.WSRP4JTestPortlet</definition-id>
</portlet>
</application>

Note:
definition-id (for Application) = portlet_WebApp_Dir
definition-id (for portlet) = portlet_name in the portlet application
You can find the portlet name in the portlet.xml file in the portlet application.

-------------------------------------------------------------

Extra step: Do this step if you want to test the producer using the consumer inside pluto

Deploy the wsrp4j-proxyportlet.war using the pluto deployment admin interface.

Edit the
$TOMCAT\webapps\wsrp4j-proxyportlet\WEB-INF\persistence\producers\org.apache.wsrp4j.commons.consumer.driver.ProducerImpl@wsrp4j-8081.xml
Note:
The file name can be different. But it alwaays ends with ProducerImp****
Change the port number to match your producer listen port. It is 8080 if you follow this guide from the beginning.

Create a file in TOMCAT/conf/Catalina/localhost/wsrp4j-proxyportlet.xml
This is the content:


<context path="/WSRP4JResourceProxy" docbase="wsrp4j-proxyportlet" crosscontext="true">
</context>


Edit $TOMCAT/webapps/pluto/WEB-INF/data/portletentityregistry.xml
Locate the application id for wsrp4j-proxyportlet you deployed earlier. And modify it so that it look similar to this

<application id="7">
<definition-id>wsrp4j-proxyportlet</definition-id>
<portlet id="0">
<definition-id>wsrp4j-proxyportlet.WSRP4JConsumer</definition-id>
<preferences>
<pref-name>wsrp_parent_handle</pref-name>
<pref-value>0.1</pref-value>
<read-only>false</read-only>
</preferences>
<preferences>
<pref-name>wsrp_producer_id</pref-name>
<pref-value>1</pref-value>
<read-only>false</read-only>
</preferences>
</portlet>
</application>


There are two important parameters:
The producer id: this is what you get from the file
$TOMCAT\webapps\wsrp4j-proxyportlet\WEB-INF\persistence\producers\org.apache.wsrp4j.commons.consumer.driver.ProducerImpl@wsrp4j-8081.xml

The portlet handle: this is what you get from the file
$TOMCAT/webapps/wsrp4j-producer/WEB-INF/data/portletentityregistry.xml with
application id is 0 and portlet handle is 1. Hence it's 0.1!!!

One last thing, to display the remote portlet on pluto:
Edit
$TOMCAT\webapps\pluto\WEB-INF\data\pageregistry.xml
Location the wsrp4j-proxyportlet fragment and make it similar to this

<fragment name="wsrp4j-proxyportlet" type="page">
<navigation>
<title>wsrp4j-consumer</title>
<description>wsrp4j-consumer</description>
</navigation>
<fragment name="row1" type="row">
<fragment name="col1" type="column">
<fragment name="p1" type="portlet">
<property name="portlet" value="7.0">
</fragment><!-- end of portlet frag -->
</fragment><!-- end of col frag -->
</fragment><!-- end of row frag -->
</fragment><!-- end of 'page' frag -->


Pay attention to the line
in which 7.0 is what you get from
$TOMCAT/webapps/pluto/WEB-INF/data/portletentityregistry.xml edited earlier above.
Again, application = 7 and portlet = 0. Hence, it's 7.0!!!

Att his point , start TOMCAT and go to
htttp://localhost:8080/pluto/portal
Click on wsrp4j-proxyportlet link. You should be able to see the remote portlet.
If you succeed, congrats and you can move on to setup consumer in Jetspeed 2.1
If you don't ,then please go back and examine the steps above.
Missing one minor step and you could mess up the whole dang thing.

-------------------------------------------------------------

5. Install Jetspeed-2

Download the jetspeed 2.1 installer JAR from
http://www.apache.org/dyn/closer.cgi/portals/jetspeed-2/binaries/jetspeed-2.1.3-installer.jar
This comes without any demo.

Install the jetspeed by running
java -jar jetspeed-2.1.3-installer.jar

Note: If you install both tomcat producer and jetspeed in the same PC, make sure you have them run on different ports!!!

During the installation, make sure you DO NOT select "Save PSML to Database". Theoretically, you can still can use this option
but I haven't had any chance to learn how to create/edit a page using the database yet.

After the installation, copy these files in your producer TOMCAT/common/endorsed/ to your jetspeed/common/endorsed
xercesImpl.jar, xml-apis.jar

In your jetspeed/shared/lib, make sure you have:
pluto-1.0.1.jar and portlet-api-1.0.jar

Next, deploy the wsrp4j-proxyportlet.war to Jetspeed by copying that file to
jetspeed/webapps/jetspeed/WEB-INF/deploy

You may need to bounce JetSpeed a time or two to get the wsrp4j-proxyportlet exploded

After the wsrp4j-proxyportlet.war get exploded in jetspeed/webapps/wsrp4j-proxyportlet, we need to edit the producer info in this file
jetspeed/webapps/wsrp4j-proxyportlet/WEB-INF/persistence/producers/org.apache.wsrp4j.commons.consumer.driver.ProducerImpl@wsrp4j-8081.xml

Change the port number to the correct one of your producer.

Create a file in TOMCAT/conf/Catalina/localhost/wsrp4j-proxyportlet.xml
This is the content:

<Context path="/WSRP4JResourceProxy" docBase="wsrp4j-proxyportlet"
crossContext="true">
</context>

Now, let create a page in Jetspeed to display a remote portlet

Create a simple page
jetspeed/webapps/jetspeed/WEB-INF/pages/wsrp4j.psml

You can copy the content here:

<?xml version="1.0" encoding="UTF-8"?>
<page id="/wsrp4j.psml" hidden="false">
<security-constraints>
<security-constraints-ref>public-view</security-constraints-ref>
</security-constraints>
<title>Welcome to Jetspeed 2</title>
<short-title>Welcome to Jetspeed 2</short-title>
<defaults skin="blue" decorator="tigris" decorator="tigris">
<fragment id="dp-1" type="layout" name="jetspeed-layouts::VelocityOneColumn">
<fragment id="dp-12" type="portlet" name="j2-admin::LoginPortlet">
<property name="row" value="3">
<property name="column" value="0">
</fragment>
<fragment id="P-117c25c3b64-10000" type="portlet" name="wsrp4j-proxyportlet::WSRP4JConsumer">
<property name="row" value="0">
<property name="column" value="0">
<preference name="wsrp_producer_id" readonly="false">
<value>1</value>
</preference>
<preference name="wsrp_portlet_handle" readonly="false">
<value>0.1</value>
</preference>
</fragment>
</fragment>
<metadata name="title" lang="fr">Bienvenue a Jetspeed</metadata>
<metadata name="title" lang="ja">Jetspeed 2 ?????</metadata>
<metadata name="title" lang="es">¡Bienvenido a Jetspeed 2!</metadata>
<metadata name="title" lang="hu">Köszönti a Jetspeed 2!</metadata>
<metadata name="title" lang="zh">????Jetspeed 2</metadata>
<metadata name="title" lang="zh_TW">????Jetspeed 2</metadata>
<metadata name="title" lang="ko">Jetspeed 2 ? ?? ?? ?????</metadata>
</page>

Next, bounce JetSPeed server and point your browser to
http://localhost:/jetspeed/portal/wsrp4j.psml

You should see your remote portlet get render.

Credit:
To build wsrp4j producer I get the guide from http://www.acet.rdg.ac.uk/projects/vre/wsrpinst.php