Apache Incubator Project Site > Apache Incubator Projects
Apollo
 

Deploy the service to the Apollo webapp

Introduction

Once you've written and compiled the required classes, you will need to deploy your service to the webapp. The distribution contains a "webapps" directory which contains a "wsrf" webapp. An Ant script is provided for deploying the FileSystem example. We will discuss how the script works so you will be able to build your own scripts.

How to manually deploy 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.

    You will need to copy your WSDL file to an appropriate location in the webapp. We recommend you put it in the wsrf/WEB-INF/classes/wsdl directory. This will allow Axis to reference it from the classpath and avoids the need to hard-code a location on your filesystem. We will use this location 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 wsrf/WEB-INF/classes/ directory so that your service can be created by Axis and Apollo.

  3. Update the jndi-config.xml file.

    The jndi-config.xml contains information about yoru service, resource, home and resource key. This information is necessary for Apollo 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 for the FileSystem:

       <service name="filesystem">
          <resource name="home" type="example.filesystem.FileSystemHome">
             <resourceParams>
                <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>resourceKeyName</name>
                   <value>{http://ws.apache.org/resource/example/filesystem}ResourceId</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 the 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 resourceKeyName represents the WS-Addressing-header name to be used for your resource id. This can be anything you like and is configurable here. 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 Apollo. This file is located in the wsrf/WEB-INF/ directory. The file contains a deployment entry for each Web service. An example is the FileSystem service:

        <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 that we've made an 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.

Deploying the FileSystem Example

To deploy the FileSystem example we will need to generate XmlBean code from the WSDL, compile all classes and deploy it to the webapp. An Ant script is provided for handling all of these steps.

You should make sure to copy the Apollo webapp from the included webapps directory to your Tomcat installation/webapps directory, and that the environment variable CATALINA_HOME is set and pointing to your Tomcat installation.

You will need to change your directory to the docs/tutorial directory. You will then need to run the command:

>ant generate

You will now need to change your directory to the docs/tutorial/generated/filesystem directory. You will need to replace the FilesystemResource.init() and FilesystemHome.getInstance(..) (generated under src) methods with the contents of the files in the directory docs/tutorial/generated/filesystem/method_impls

You will then need to run the command:

>ant compile deploy

This will compile and deploy the code. You can now start Tomcat.

Note
This step assumes you have installed Apache Ant. If not, you can get it here