Installation in PageBox framework

Implementation

Support of Publishing framework is implemented through a new class loader, ClassPathLoader. ClassPathLoader has been tested with Cocoon, SOAP, Xerces, Xalan but it can be used with most Java libraries.

Functions:

• Serving and caching library classes and resources - like regular class loaders
• Caching servlet instances such as org.apache.soap.server.http.RPCRouterServlet for SOAP
• Returning resources from archives with getResourceAsStreamFromArchive method

Version 1.0.4 introduces a mapping mechanism similar to <servlet-mapping>. Why don't we support standard web.xml for Presentation archives and ClassPathLoader libraries?

We could support <servlet-mapping> and <servlet-name>/<servlet-class> without too much effort. <init-param> has more impact. We need to give access to initialization parameters through ServletConfig.getInitParameter; therefore we have to implement our own implementation of Servlet objects or reuse the Application implementation. In the first case we significantly increase the footprint of PageBox. The second option compromizes portability and raises legal issues with commercial products.

We consider the first option but for the moment we only provide a simple mappping using a property file.

Installation steps

1. Download - the hard way
   • J2SE JDK 1.3 from Sun site
   • JavaMail 1.2 and JavaBeans Activation framework (JAF) 1.0.1 from Sun site
   • Cocoon 1.8.2 and SOAP 2.1 from Apache site
   • JSPservlet for Application server
   • Network processors
   • Xerces patch
   • Cocoon patch
   • Loopback servers required by the demo
   • Demo

   For the moment it is the only validated configuration. You can run different combinations but it is likely to require some porting effort. Contact us in case of problem. For more information look at components.

2. Download - the automated way

   You can use the new Configurator (version 1.0.4 released on April 16 2001) that automates the process. For more information see Configurator.

   Configurator downloads files from http://pagebox.net and http://pagebox.sourceforge.net. It reports download problems. In case of failure just restart it.

   Note that Configurator is not a command line but a servlet. You need first to install Tomcat or Resin and then copy configurator.war in webapps directory. The reason is that we designed it primarily for remote deployment (on ASPs). It is really automated: you should be done by setting only two parameters, ID and Cache path.

3. JSPservlet web.xml setting

   See web.xml parameter section below and JSPservlet documentation.

4. cocoon.properties setting

   See Cocoon parameters section below.

5. Tomcat setting

   See Tomcat documentation for more information. You need to add a context path like this to servlet.xml:

   <Context path="/cocoon"
       docBase="/myDir/myWAR"
       crossContext="true"
       debug="1"
       reloadable="false"
       trusted="true" >
   </Context>

   where myWAR contains a WEB-INF directory.

6. Resin setting

   See Resin documentation for more information. You need to add a context path like this to servlet.xml:

   <web-app id='/cocoon' app-dir='/myDir/myWAR'/>

   where myWAR contains a WEB-INF directory.

7. Loopback SOAP server registration

   See the SOAP registration section below.

Example:

<init-param>
<param-name>ClassPath</param-name>
<param-value>

E:/cocoonSupport/InputSource.jar;E:/cocoonSupport/lib/xerces_1_2.jar;E:/cocoonSupport/lib/turbine-pool.jar; E:/cocoonSupport/lib/w3c.jar;E:/cocoonSupport/lib/bsf.jar;E:/cocoonSupport/lib/xalan_1_2_D02.jar; E:/cocoonSupport/lib/fop_0_15_0.jar;E:/cocoonSupport/CocoonPatch.jar;E:/cocoonSupport/lib/cocoon.jar; E:/cocoonSupport/lib/xml.jar;E:/jaf-1.0.1/activation.jar;E:/javamail-1.2/mail.jar; E:/soap-2_1/lib/soap.jar;E:/cocoonSupport/loopback.jar;E:/cocoonSupport/cocoonSupport.jar
</param-value>
<description>Archive to check in classloader</description>
</init-param>
<init-param>
<param-name>PageboxMapping</param-name>
<param-value>C:/TEMP/cocoonSupport/mapping-cocoon.properties</param-value>
<description>Mapping property file</description>
</init-param>
<!-- Cocoon properties -->
<init-param>
<param-name>properties</param-name>
<param-value>WEB-INF/cocoon.properties</param-value>
<description>Cocoon properties</description>
</init-param>
<!-- SOAP properties -->
<init-param>
<param-name>faultListener</param-name>
<param-value>org.apache.soap.server.DOMFaultListener</param-value>
</init-param>


ClassPath

ClassPath contains the list of the libraries loaded by ClassPathLoader, separated by the OS-dependent path separator.

For Cocoon 1.8,2 we need the following libraries in that order:

• xerces_1_2.jar
• turbine-pool.jar
• w3c.jar
• bsf.jar
• xalan_1_2_D02.jar
• fop_0_15_0.jar
• cocoon.jar

For Apache SOAP 2.1, we need the following libraries in that order:

• activation.jar
• mail.jar
• soap.jar

In case of Cocoon, all needed (and supported) libraries are included in Cocoon package.

In case of Soap, you can use the Cocoon Xerces but you need to download JavaMail and JavaBeans Activation Framework (JAF). We used JavaMail 1.2 and JAF 1.0.1 in our tests. Note that if you use SOAP in SMTP mode, you need additional JavaMail archive.

As you can see we need large set of libraries with potential incompatibilities - which is good news for ClassPathLoader because it allows to run different sets of libraries in the same JVM :-)

We also need to add Xerces and Cocoon patches, InputSource.jar and CocoonPatch.jar. They are described in components. Patches must be put in front of the patched archives.

Eventually we need to add Network process archive, named cocoonSupport.jar. On the example, we also added loopback.jar that contains HTTP and SOAP loopback Web services - for demo purpose we invoke ourself -.

PageboxMapping

PageboxMapping contains the path of a property file like this:

.xml=org.apache.cocoon.Cocoon
rpcrouter=org.apache.soap.server.http.RPCRouterServlet
messagerouter=org.apache.soap.server.http.MessageRouterServlet
loopbackHTTP=loopback.loopbackServlet

When the key starts with a dot (.), then it is considered as a suffix. We write here every URL ending with .xml must be served by org.apache.cocoon.Cocoon. The example means the same as <url-pattern>*.xml</url-pattern>

When the key doesn't start with a dot, then it is considered as the last part of URL. We write .../rpcrouter must be served by org.apache.soap.server.http.RPCRouterServlet.

Cocoon and SOAP parameters As embedded servlets are served the ServletConfig of the handling JSPservlet, you simply need to specify embedded servlet parameters in JSPservlet <init-param> like on the example.

Cocoon parameters are specified in a cocoon.properties file. For the support of our processors you simply need to add two lines in cocoon.properties:

processor.type.CocoonHTTP = cocoonSupport.CocoonNetwork		HTTP processor
processor.type.CocoonSOAP = cocoonSupport.CocoonSOAP		SOAP processor

SOAP registration

You must register loopbackSOAP with the following command:

java org.apache.soap.server.ServiceManagerClient
rpcrouter_url deploy DeploymentDescriptor.xml

where DeploymentDescriptor.xml was defined like this:

<?xml version="1.0"?> <isd:service xmlns:isd="http://xml.apache.org/xml-soap/deployment"
    id="urn:loopbackSOAP">
  <isd:provider type="java"
    scope="Request"
    methods="getDocument">
    <isd:java class="loopback.loopbackSOAP"/>
  </isd:provider>
  <isd:faultListener>org.apache.soap.server.DOMFaultListener</isd:faultListener>
</isd:service>

• Presentation of Cocoon/SOAP integration
• Components of Cocoon/SOAP integration