You are viewing a plain text version of this content. The canonical link for it is here.
Posted to wsrp4j-dev@portals.apache.org by dl...@apache.org on 2006/12/14 20:21:36 UTC
svn commit: r487311 - /portals/wsrp4j/trunk/README.txt
Author: dlouzan
Date: Thu Dec 14 11:21:35 2006
New Revision: 487311
URL: http://svn.apache.org/viewvc?view=rev&rev=487311
Log:
Added detailed documentation on how to build & install wsrp4j.
Modified:
portals/wsrp4j/trunk/README.txt
Modified: portals/wsrp4j/trunk/README.txt
URL: http://svn.apache.org/viewvc/portals/wsrp4j/trunk/README.txt?view=diff&rev=487311&r1=487310&r2=487311
==============================================================================
--- portals/wsrp4j/trunk/README.txt (original)
+++ portals/wsrp4j/trunk/README.txt Thu Dec 14 11:21:35 2006
@@ -13,45 +13,299 @@
# limitations under the License.
-Mavenized version of the repository (requires Maven 2.x)
+ ********** Apache WSRP4J **********
+ http://portals.apache.org/wsrp4j
-- Copy build.properties.sample to build.properties
- $ cp build.properties.sample 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.
-
-- Run Maven:
- $ mvn <goal>
-
-Goal description:
-
-$ mvn compile
- Compile sources
-
-$ mvn package
- Compile and build jars for libraries and wars for webapps
-
-$ mvn clean
- Remove all generated artifacts
-
-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 <plugins>
-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 below commons/src/java/. See
-commons/src/wsdl/README.txt for more details.
-
-The proxyportlet and producer wars are located on their respective
-target directories (consumer-proxyportlet/target/wsrp4j-proxyportlet.war and
-producer/target/wsrp4j-producer.war).
-
-For deploying the proxyportlet, just install Pluto 1.0.1 with PlutoPortal and
-use the admin portlet bundled with PlutoPortal to deploy wsrp4j-proxyportlet.war
-The default producer configuration files supplied with proxyportlet assume you
-have started the corresponding tunnel script from tools/ directory. This tunnel
-tool will allow you to view the wsrp messages exchanged between the consumer
-and the producer.
+Contents
+--------
+
+1. Introduction
+2. Software requirements
+3. Basic installation and configuration
+4. Environment variables
+5. Building and installation
+6. 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 and 5.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.4 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.
+
+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.4 on Unix-like operating systems:
+
+ - Download the .tar.gz binary package of Maven 2.0.4 from:
+ http://maven.apache.org/download.html
+
+ - Unpack the distribution on some directory (like ~/local):
+ $ cd ~/local
+ $ tar xvzf ~/downloads/maven-2.0.4-bin.tar.gz
+
+ - Check that your distribution is working properly by executing Maven:
+ $ cd ~/local/maven-2.0.4/bin
+ $ export MAVEN_HOME=~/local/maven-2.0.4
+ $ ./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 ~/dowloads/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.
+
+ 3.5 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.4. 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)
+
+ - 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 Producer 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 later modifications on it won't be automatically
+ deployed. You can manually add new modifications by stopping Tomcat and
+ executing:
+ $ cd $PLUTO_HOME
+ $ maven deploy -Ddeploy=$CATALINA_HOME/webapps/wsrp4j-proxyportlet
+ Then start 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 <plugins>
+ 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 below
+ commons/src/java/. See commons/src/wsdl/README.txt for more details.
+
+ The proxyportlet and producer wars are located on their respective
+ target directories (consumer-proxyportlet/target/wsrp4j-proxyportlet.war and
+ producer/target/wsrp4j-producer.war).
+
+ For deploying the proxyportlet, just install Pluto 1.0.1 with PlutoPortal and
+ use the admin portlet bundled with PlutoPortal to deploy
+ wsrp4j-proxyportlet.war. The default producer configuration files supplied
+ with proxyportlet assume you have started the corresponding tunnel script
+ from tools/ directory. This tunnel tool will allow you to view the wsrp
+ messages exchanged between the consumer and the producer.
+
+6. Known problems
+ --------------
+
+ * Currently the WSRP4J Producer component does not implement 'WSRP Producer
+ URL Writing' (see WSRP Specification Section 10.2.2).
+
+ * Due to Axis bug AXIS-2096, the wsdl generation of the WSRP services served
+ by Axis in wsrp4j-producer will fail.