# Copyright 2003-2006 The Apache Software Foundation. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. # $Id$ ********** Apache WSRP4J ********** http://portals.apache.org/wsrp4j ********* Note: The WSRP4J trunk is unstable at the moment. This README is out of date. The trunk will become stable in the next two weeks or so, and the docs will be updated accordingly. Until then, a stable WSRP4J with accurate README's is found at: https://svn.apache.org/repos/asf/wsrp4j-0.4-SNAPSHOT-prepluto11/ Adventurous users can look at the brief notes in README.UNSTABLE if they wish to continue. - Elliot Metsger 8/22/2007 (esm@apache.org) ********* Contents -------- 1. Introduction 2. Software requirements 3. Basic installation and configuration 4. Environment variables 5. Building and installation 6. How to enable DB-persistence 7. Known problems 1. Introduction ------------ WSRP4J is the Java language reference implementation of the OASIS WSRP specification, which is a web services protocol for aggregating content and interactive web applications from remote sources. WSRP allows content and application providers to provide their services to organizations running portals in a very easily consumable form. 2. Software requirements --------------------- This software has been developed and tested with: * Operating system. It should be possible to compile and execute this distribution in Unix-like operating systems and any version of MS-Windows. The following combinations have been tested with the current repository: - Ubuntu 6.06 LTS 'Dapper Drake'. * An implementation of J2SE 1.4 or upper. - Sun's J2SE 1.4, 5.0 and 6.0 have been tested. * Subversion revision control system client. * Apache Maven 1.x and 2.x. Maven 1.x is used to build and deploy Apache Pluto sources, while Maven 2.x is used by WSRP4J sources. Both are used for managing the projects (compile, generate JavaDoc, jars, wars, ...). - Apache Maven 1.0.2 and 2.0.5 have been tested. * Apache Pluto 1.0.1 (source). * An application server conforming to Servlet 2.3 and JSP 1.2. - Apache Tomcat 5.5.16 has been tested. * An XSLT processor conforming to JAXP 1.3. - Apache Xalan-Java 2.7.0 has been tested. * The JTA transaction API jar from Sun (needed for persistence-db module) * (Optional) A relational database and JDBC driver. - The examples assume you are using HSQLDB 1.8.0.7. 3. Basic installation and configuration ------------------------------------ All of the following examples assume that lines started with '$' are to be executed on a shell console. 3.1 Basic installation and configuration of Subversion -------------------------------------------------- * Installation of Subversion on Unix-like operating systems: Most distributions include subversion as a downloadable package from their servers. Check your distribution documentation on how to install new packages. Another option is to download the distribution from their website at: http://subversion.tigris.org/project_packages.html 3.2 Basic installation and configuration of Apache Maven ---------------------------------------------------- For WSRP4J you will need both Maven 1.x (for Pluto) and 2.x (for WSRP4J). * Installation of Apache Maven 1.0.2 on Unix-like operating systems: - Download the .tar.gz binary package of Maven 1.0.2 from: http://maven.apache.org/maven-1.x/start/download.html - Unpack the distribution on some directory (like ~/local): $ cd ~/local $ tar xvzf ~/downloads/maven-1.0.2.tar.gz - Check that your distribution is working properly by executing Maven: $ cd ~/local/maven-1.0.2/bin $ export MAVEN_HOME=~/local/maven-1.0.2 $ ./maven --version * Installation of Apache Maven 2.0.5 on Unix-like operating systems: - Download the .tar.gz binary package of Maven 2.0.5 from: http://maven.apache.org/download.html - Unpack the distribution on some directory (like ~/local): $ cd ~/local $ tar xvzf ~/downloads/maven-2.0.5-bin.tar.gz - Check that your distribution is working properly by executing Maven: $ cd ~/local/maven-2.0.5/bin $ export MAVEN_HOME=~/local/maven-2.0.5 $ ./mvn --version 3.3 Basic installation and configuration of Apache Tomcat ----------------------------------------------------- * Installation of Apache Tomcat 5.5.16 on Unix-like operating systems: - Download the .tar.gz binary package of Tomcat 5.5.16 from: http://archive.apache.org/dist/tomcat/tomcat-5/ - Unpack the distribution on some directory (like ~/local): $ cd ~/local $ tar xvzf ~/downloads/apache-tomcat-5.5.16.tar.gz - Check that your distribution is working properly by executing Tomcat: $ cd ~/local/apache-tomcat-5.5.16/bin $ export CATALINA_HOME=~/local/apache-tomcat-5.5.16 $ ./startup.sh Then wait some seconds and point your browser to: http://localhost:8080 3.4 Basic installation and configuration of Apache Xalan-Java --------------------------------------------------------- * Installation of Apache Xalan-Java 2.7.0 on Unix-like operating systems: We will need an XSLT processor for Tomcat to use, and Xalan is one of the best options. - Download Apache Xalan-Java 2.7.0 binary from: http://xml.apache.org/xalan-j/downloads.html - Unpack xalan-j_2_7_0-bin.tar.gz to any directory and copy the following files to $CATALINA_HOME/common/endorsed: * serializer.jar * xalan.jar * xercesImpl.jar * xml-apis.jar - Tomcat will need to be restarted for the changes to take effect. - **IMPORTANT** Due to an error on iBiblio, it's necessary to install serializer jar into your local maven repository (see Section 6). Execute: $ mvn install:install-file -DgroupId=xalan -DartifactId=serializer \ -Dversion=2.7.0 -Dpackaging=jar -Dfile=serializer.jar 3.5 Basic installation and configuration of JTA (Java Transaction API) jar ---------------------------------------------------------------------- * Due to licensing issues, the JTA jar can't be dowloaded from iBiblio, you have to manually download and install it on your local maven repository. This file is needed by Hibernate for wsrp4j-persistence-db - Dowload the file jta-1_0_1B-classes.zip (JTA 1.0.1B) from: http://java.sun.com/products/jta/ - Install the file jta-1_0_1B-classes.zip to your Maven repository: $ mvn install:install-file -DgroupId=javax.transaction \ -DartifactId=jta -Dversion=1.0.1B -Dpackaging=jar \ -Dfile=jta-1_0_1B-classes.zip 3.6 (Optional) Basic installation and configuration of HSQLDB 1.8.0.7 ----------------------------------------------------------------- * If you want to use the persistence-db module, you need a relational database and a driver to connect to the database. The examples assume you have installed HSQLDB. - Download hsqldb_1_8_0_7.zip from: http://www.hsqldb.org/ - Unpack the file and copy hsqldb-1.8.0.7.jar to $CATALINA_HOME/commmon/lib: $ cp hsqldb-1.8.0.7.jar $CATALINA_HOME/common/lib This is needed by the Tomcat DataSource configured to connect to the db. - Start HSQLDB: $ java -classpath hsqldb.jar org.hsqldb.Server - You can stop HSQLDB anytime using Ctrl-C. 3.7 Basic installation and configuration of Apache Pluto ---------------------------------------------------- * Installation of Apache Pluto 1.0.1 on Unix-like operating systems: - Download Apache Pluto 1.0.1 source from their svn repository: $ cd ~/local $ svn checkout https://svn.apache.org/repos/asf/portals/pluto/tags/release-1.0.1/ pluto-1.0.1 - Copy build.properties.sample to build.properties, edit build.properties and customize the maven.tomcat.home and maven.tomcat.version.major variables for your environment. - Run Maven 1.x to build the project: $ export MAVEN_HOME=~/local/maven-1.0.2; export PATH=$MAVEN_HOME/bin:$PATH $ maven fullDeployment - Start tomcat, wait some seconds and point your browser to: http://localhost:8080/pluto/portal 4. Environment variables --------------------- This is an excerpt of my "~/.bashrc". Adapt it to your needs: # Apache Maven export MAVEN_HOME=~/local/maven-2.0.4 export PATH=$MAVEN_HOME/bin:$PATH # Apache Tomcat export CATALINA_HOME=~/local/apache-tomcat-5.5.16 export PATH=$CATALINA_HOME/bin:$PATH # Apache Pluto export PLUTO_HOME=~/local/pluto-1.0.1 5. Building and installation ------------------------- Set up all software requirements (see Section 3). Set up all environment variables (see Section 4). Execute ". ~/.bashrc" if necessary. For WSRP4J you will need Maven 2.0.X. Assuming you have downloaded the svn trunk repos to ~/local/wsrp4j: - Copy build.properties.sample to build.properties. - Edit build.properties and enter your Tomcat installation dir for both Proxyportlet and Producer. These parameters will setup the location of your installation in WSRP4J configuration files, but won't actually deploy your applications to tomcat, you have to manually add them later. For a basic installation, set the same path on both variables. - Run Maven and generate packages for each module: $ mvn package * Goal description: $ mvn compile Compile sources $ mvn package Compile and build jars for libraries and wars for webapps $ mvn clean Remove all generated artifacts - Copy producer/target/wsrp4j-producer.war to $CATALINA_HOME/webapps dir. - Start Tomcat. - Check that producer is working by pointing your browser to: http://localhost:8080/wsrp4j-producer/WSRP4JProducer ** NOTE ** Don't try to obtain the wsdl through the links shown as due to an Axis bug they will throw an exception (see Section 6) The default method used to call Axis services is HTTP POST, but Axis also provides a method for calling them using a GET request, which you can use to test producer. Example: http://localhost:8080/wsrp4j-producer/services/WSRPServiceDescriptionService?method=getServiceDescription This will call the method getServiceDescription() of the WSRPServiceDescriptionService and return the response. You can find a basic producer configuration utility in: http://localhost:8080/wsrp4j-producer/ It will allow you to view the deployed portlets and to upload new portlet applications. Read the instructions on the page on how to use it. - Point your browser to Pluto Portal Admin page: http://localhost:8080/pluto/portal/adminportletapp - Use the Deploy War Admin Portlet to deploy testportlet/target/wsrp4j-testportlet.war. Enter a title and submit the portlet. Click on the hotdeploy link to view your portlet on PlutoPortal. - Point your browser again to Pluto Portal Admin page and use again the War portlet, but this time upload consumer-proxyportlet/target/wsrp4j-proxyportlet.war. Enter a title, a layout of 2x2 and submit. Then select your portlets like this: * Row1 - Column 1: ProducerConfig * Row1 - Column 2: PortletConfig * Row2 - Column 1: WSRP4JPortletA * Row2 - Column 2: WSRP4JPortletB Submit again and restart Tomcat. - Start the Axis TCP Tunnel utility for monitoring the WSRP traffic between the consumer and the producer. It will wait incoming connections on port 9001 and will forward them to the local WSRP4J Producer: $ cd tools $ ./tunnel-9001.sh You probably want the "XML Format" option activated on the TCP Tunnel for enabling XML indentation. - Point your browser again to PlutoPortal and on the menu on the left select the WSRP4J Proxyportlet you deployed before. - Enjoy your WSRP portlets :-) The configuration portlets provided with proxyportlet can customize your producers and deployed portlets. Take into account that by default they are configured to use their corresponding TCP Tunnel, so start each script on tools/ dir accordingly or you will get a nice connection refused exception. The PortletConfig portlet bundled with proxyportlet will allow you to add new remote portlets to proxyportlet. Unfortunately, the default PlutoPortal distribution does not support dynamic reloading of portlet.xml contents, that is, that file will only be processed once when you deploy proxyportlet for the first time, and subsequent modifications on it won't be automatically deployed. You can manually add new modifications by stopping Tomcat and executing: $ cd $PLUTO_HOME $ export MAVEN_HOME=~/local/maven-1.0.2; export PATH=$MAVEN_HOME/bin:$PATH $ maven deploy -Ddeploy=$CATALINA_HOME/webapps/wsrp4j-proxyportlet Then restart Tomcat and your new wsrp portlets will be deployed on proxyportlet ConfigPortlet. Other portals (like Apache Jetspeed) do support dynamic reloading of portlet.xml contents. If you want the Axis-generated sources from WSDL files in commons/src/wsdl, then edit commons/pom.xml and uncomment the antrun-plugin in the section, then rebuild the project. The Axis-generated sources will be located in directory commons/target/generated-sources/wsdl. This files won't be used for actually building the libraries, the ones used are under commons/src/java/. See commons/src/wsdl/README.txt for more details. WSRP4J also includes a standalone Swing application for consuming remote WSRP portlets (consumer-swingconsumer module). For executing it, you have to copy some files and directories to any other directory (like ~/local/wsrp4j-swingconsumer) and execute the following: $ cp consumer-swingconsumer/target/wsrp4j-swingconsumer-jar-with-dependencies.jar \ ~/local/wsrp4j-swingconsumer $ svn export consumer-swingconsumer/src/resources/persistence \ ~/local/wsrp4j-swingconsumer/persistence $ cd ~/local/wsrp4j-swingconsumer $ java -jar wsrp4j-swingconsumer-jar-with-dependencies.jar Keep in mind that this app is no longer maintained and doesn't support forms, only links. Don't forget to start the corresponding tunnel.sh from tools/ directory. The log is stored on file wsrp4j-swingconsumer.log. 6. How to enable DB-persistence ---------------------------- DB persistence can be enabled on both wsrp4j-producer and wsrp4j-proxyportlet, on any of them or none. The default behaviour is the XML files based persistence. 6.1 Enabling DB-persistence on wsrp4j-producer ------------------------------------------ The jar files for persistence are included on the lib/ directory of the war file wsrp4j-producer.war. Configuration files: - META-INF/context.xml - 6.2 Enabling DB-persistence on wsrp4j-proxyportlet ---------------------------------------------- 7. Known problems -------------- * Currently the WSRP4J Producer component does not implement 'WSRP Producer URL Writing' (see WSRP Specification Section 10.2.2). The support for templates on WSRP4J ProxyPortlet is **experimental** as well. * The WSRP4J Producer config servlet won't run correctly until an actual call to the Axis servlet is made. This is due to the design of the pluto provider interface in commmons-producer and producer. * Due to Axis bug AXIS-2096, the wsdl generation of the WSRP services served by Axis in wsrp4j-producer will fail. * Currently, Apache Xalan distribution on iBiblio doesn't include serializer jar, so it must be manually added to the local Maven repository.