apache > ws.apache
Pubscribe
 

Deploy the service to the Pubscribe Web Application

Introduction

The quickest way to deploy your WS Resource is to use the generated build scripts. The scripts compile and delploy your WS Resource to the Pubscribe Web application, which is an Apache-Axis Web application. This section describes how to use the generated build scripts and also how the script works so you can build your own scripts.

Using the generated build scripts

The Wsdl2Java tool generates an Ant build script that is used to compile and deploy your WS Resource. The script is located in the output directory under the subdirectory for you WS Resource (e.g., generated/ service_name ).

To compile and deploy using the Ant script

  1. In your output directory, edit build.properties and modify the pubscribe.webapp.dir. If you are using Tomcat and have CATALINA_HOME set, you do not need to modify this property.
  2. From a command prompt, change directories to generated/ service_name
  3. Run:
	ant compile deploy 

Start Tomcat and verify that the service is deployed by going to http://localhost:8080/pubscribe/services

Manually Deploying your Service

In this section we will describe how to manually deploy your service. We will describe each step in the process.

  1. Copy your WSDL file.

    Your WSDL file needs to be copied to an appropriate location in the webapp. We recommend you put it in the pubscribe/WEB-INF/classes/wsdl directory. This allows Axis to reference it from the classpath and avoids the need to hard-code a location on your file system. This location is used when registering the service in the server-config.wsdd file.

  2. Copy your classes.

    You will need to copy any .class files, generated by Wsdl2Java or hand written, to the pubscribe/WEB-INF/classes/ directory so that your service can be created by Axis and Pubscribe.

  3. Update the jndi-config.xml file.

    The jndi-config.xml contains information about your service, resource, home and resource key. This information is necessary for Pubscribe to create your home and handle requests for your service. It will setup the in-memory JNDI context for your classes. Here is the entry that was used for the FileSystem example:

       <service name="filesystem">
          <resource name="home" type="example.filesystem.FileSystemHome">
             <resourceParams>
                <parameter>
                   <name>baseWebappUrl</name>
                   <value>http://$IP_ADDRESS$:8080/pubscribe</value>
                </parameter>
                <parameter>
                   <name>serviceClassName</name>
                   <value>example.filesystem.FileSystemService</value>
                </parameter>
                <parameter>
                   <name>resourceClassName</name>
                   <value>example.filesystem.FileSystemResource</value>
                </parameter>
                <parameter>
                   <name>wsdlTargetNamespace</name>
                   <value>http://ws.apache.org/resource/example/filesystem</value>
                </parameter>
                <parameter>
                   <name>resourceIdentifierReferenceParameterName</name>
                   <value>{http://ws.apache.org/resource/example/filesystem}ResourceIdentifier</value>
                </parameter>
             </resourceParams>
          </resource>
       </service>

    The name attribute is a unique name in the config file to denote your service in JNDI. The resource "name" attribute is used for locating your home instance, and is named home. Notice serviceClassName points to the clasname for the service class. The same is said for the resourceClassName. The wsdlTargetNamespace is the target namespace from your WSDL.

    The baseWebappUrl parameter is used to define the URL of your Web application. You can include a static host, or as an alternative, you can use the following markers which are replaced at runtime:

    • $IP_ADDRESS$ - An attempt is made to determine the IP address at runtime. (Do not use on multi-homed systems).
    • $HOST_NAME$ - An attempt is made to determine the host name at runtime.

    The resourceIdentifierReferenceParameterName parameter represents the name of the WS-Addressing-header that is used to extract a unique resource identifier to lookup a specific WS-Resource instance. This value should be a QName that includes the local reference parameter name in the format {namespaceURI}localPart, where namesapaceURI and localPart are the namespace and URI and local part of the qualified name of the reference paramater that should contain the resource identifier. If you omit this entry, it is assumed that the service is a SINGLETON service and no resource id is expected in the WS-Addressing headers.

  4. Update the server-config.wsdd file

    The server-config.wsdd file is the configuration file for the Axis SOAP engine, which is bundled with Pubscribe. This file is located in the pubscribe/WEB-INF/ directory. See the Axis documentation for complete instructions about server-config.wsdd

    The file contains a deployment entry for each Web service. For example, the FileSystem service example is:

        <service name="filesystem" provider="java:WSRF" style="document" use="literal">
          <wsdlFile>/wsdl/FileSystem.wsdl</wsdlFile>      
          <requestFlow>
             <handler type="java:org.apache.axis.handlers.JAXRPCHandler">
                <parameter name="className" value="org.apache.axis.message.addressing.handler.AxisServerSideAddressingHandler"/>
                <parameter name="referencePropertyNames" value="*"/>
             </handler>
          </requestFlow>      
       </service>

    The service name attribute is the endpoint name and should be the same as the port's name attribute from your WSDL file. This will ensure people consuming your WSDL will be able to invoke your service.

    Notice the entry for wsdlFile which points to the /wsdl/FileSystem.wsdl. This translates to the wsdl directory under the WEB-INF/classes directory.

    The last part is the requestFlow. This xml fragment is necessary to ensure the requests are routed through the WS-Addressing handler. This is static and should always be present. We did not define it globally in case there were other services defined which will not use WS-Addressing.