Previous Section Next Section

Configuring Axis

There are four different types of configuration files. Each will contain the same type of data, but the outermost XML element will vary:

  • client-config.xmlgraphics/book.gif— This is the configuration information for the Axis engine when it is invoked on the client. This file needs to be in the current working directory of the client application. This file has the format

    <engineConfig>
  …configuration XML…
</engineConfig>

  • server-config.xmlgraphics/book.gif— This is the configuration information for the Axis engine when it is invoked on the server. This file needs to be in the servlet engine's axis/WEB-INF directory in the HTTP case, or in the current working directory for other transports. This file has the format

    <engineConfig>
  …configuration XML…
</engineConfig>

  • deploy.xmlgraphics/book.gif— This is the file used by the AdminClient graphics/book.gif to deploy new handlers, chains, and services. The AdminClient is an administrative tool used for deploying and undeploying Axis resources (such as handlers and chains). The AdminClient uses a document-centric Web service—it takes the XML file passed to it and sends it to the Axis server for processing (more later). Unlike the first two configuration files, the name of this file can be anything. This file has the format

    <m:deploy xmlns:m="AdminService">
   …configuration XML…
</m:deploy>

  • undeploy.xmlgraphics/book.gif— This is the file used by the AdminClient to undeploy resources. The AdminClient will remove any named resources listed as immediate child elements of the undeploy XML element. Unlike the first two configuration files, the name of this file can be anything. This file has the format

    <m:undeploy xmlns:m="AdminService">
   …resources to be removed…
</m:undeploy>

In the first three cases, ...configuration XML... section will contain one of the following XML elements:

  • handler
<handler name="handler_name" class="class_name">
  [<option name="option_name" value="option_value"/>]…
</handler>

Example:
<!-- Define an EMail handler -->
<handler name="EMail" class="com.skatestown.services.EMailHandler" />

    Defines a single handler named handler_name whose class is given by class_name.The optional name/value pairs are defined by each specific handler and will be available to the handler at runtime.

  • chain
<chain name="chain_name" { flow="list_of_handlers" |
       request="list_of_handlers" pivot="handler_name"
       response="list_of_handlers"} >
  [<option name="option_name" value="option_value"/>]…
</chain>

Example:
<!--Define a chain consisting of 2 handlers, a Java RPC Dispatcher
   and the Email handler from chapter 3 -->
<chain name="myChain" flow="RPCDispatcher, Email" />

    Defines a chain called chain_name that consists of either the list of handlers specified in the flow attribute or the handlers specified by the request pivot and response attributes combined. The optional name/value pairs will be available to the chain at runtime. There are two reserved chain names: global.request and global.response. These names should be used when defining the global chains.

  • service
<service name="service_name" [request="list_of_handlers"]
         [pivot="handler_name"]                   
         [response="list_of_handlers"]>
  [<option name="option_name" value="option_value"/>]…
</service>

    Example:

    <!-- Define a service chain with the "RPCDispatcher" at the pivot-point
     and Email handler to mail the response. The class and method name
     that the RPCDispatcher will use are passed in as options -->
<service name="InventoryCheck" pivot="RPCDispatcher" response="Email">
   <option name="className"
    value="com.skatestown.services.InventoryCheck"/>
   <option name="methodName" value="doCheck"/>
</service>

    Defines a service chain consisting of the list of handlers specified in the request, pivot, and response attributes combined. The optional name/value pairs will be available to the service at runtime. The name specified here should match the namespace URI of the first body entry of the incoming SOAP request message.

  • transport
<transport name="transport_name" [request="list_of_handlers"]                     
           [pivot="handler_name"]           
           [response="list_of_handlers"]>
  [<option name="option_name" value="option_value"/>]…
</transport>

    Example:

    <!-- Define a transport specific chain that will invoke a "uudecode"
     handler on the request message and the "uuencode" handler on the
     response message – these will only be invoked for those messages
     that come in using the "file" transport -->
<transport name="file" request="uudecode" response="uuencode"/>

    Defines a transport chain consisting of the list of handlers specified in the request, pivot, and response attributes combined. The optional name/value pairs will be available to the transport chain at runtime. The name specified on this definition must match the name of the transport specified by the transport listener on the setTransportName() method.

  • beanMappings
<beanMappings>
  <x:name xmlns:x="namespace_uri" classname="class_name" />
</beanMappings>

    Example:

    <beanMappings>
  <x:po xmlns:x="http://www.skatestown.com/ns/po"
        classname="www.skatestown.com.data.PO" />
</beanMappings>

    Defines the bean serializer/deserializer class (class_name) to be used for the bean named name in the namespace namespace_uri. This is a convenient way of using the default Java bean serializer and deserializer for your Java beans. We'll give more details about serializers and deserializers in the "Data Encoding/Decoding" section.

  • typeMappings
<typeMappings>
  <x:name xmlns:x="namespace_uri" type="soap_type" serializer="class_name"
              deserializerFactory="class_name" />
</typeMappings>

Example:
<typeMappings>
  <x:PO xmlns:x="http://www.skatestown.com/ns/po" type="po"
        serializer="serializePO"
        deserializerFactory="deserializePOFactory" />
</typeMappings>

    Defines a mapping between the type found in the SOAP message (soap_type) in the specified snamespace namespace_uri with the specified serializer and deserializer. We'll give more details about serializers and deserializers in the "Data Encoding/Decoding" section.

The fourth configuration file, undeploy.xml, has a slightly different format. In this file, you just list the types of resources to be undeployed and their names. For example:

<m:undeploy xmlns:m="AdminService">
  <handler name="logger" />
  <service name="DoCheck" />
  <transport name="file" />
</m:undeploy>

In this example, three resources will be undeployed: a handler named logger, a service chain named DoCheck, and a transport chain named file.

Configuration Methods

You can configure the Axis server two ways: You can modify the server-config.xml file directly by adding or removing the XML configuration data, or you can use the AdminClient tool. This tool lets you remotely modify the server's configuration. By default, Axis will only allow the AdminClient to be run from the same machine as the server (for security reasons), but this is easily changed (see the "Security" section).

To run the AdminClient, you must first create an XML file with the list of changes to be made. Inside this XML file should be just the list of resources (handlers, chains, services, and so on) that should be deployed or undeployed. As previously shown, the XML's root element should be named deploy in the case where new resources are being added and undeploy when they are being removed. Once all the deployment information is placed in an XML file, you can invoke AdminClient:

> java org.apache.axis.client.AdminClient
    -l http://localhost:8080/axis/servlet/AxisServlet deploy.xml

Note that this assumes an HTTP transport and that the Axis servlet is available and waiting for requests on the specified URL (http://localhost:8080/axis/servlet/AxisServlet). This invocation will work for deploying new resources to an Axis engine running as a server. To add new resources to an Axis client engine, you'll need to modify the client-config.xml file used by the client Axis engine. This file will reside in the current working directory. Following is one of the sample XML files from Chapter 3 that is used as input to the AdminClient:

<m:deploy xmlns:m="AdminService">
  <handler name="URLMapper" class="org.apache.axis.handlers.http.URLMapper"/>
  <handler name="ActionHandler"
           class="org.apache.axis.handlers.http.HTTPActionHandler"/>

  <transport name="http" request="URLMapper"/>

  <!-- Chapter 3 example 3 services -->
  <handler name="EMail" class="com.skatestown.services.EMailHandler"/>
  <service name="InventoryCheck" pivot="RPCDispatcher" response="EMail">
    <option name="className" value="com.skatestown.services.InventoryCheck"/>
    <option name="methodName" value="doCheck"/>
  </service>

  <!-- Chapter 3 example 4 services -->
  <service name="POSubmission" pivot="MsgDispatcher">
    <option name="className" value="com.skatestown.services.POSubmission"/>
    <option name="methodName" value="doSubmission"/>
  </service>

</m:deploy>

Although it is possible to run the AdminClient tool to change the configuration information of the Axis client engine, it is easier to simply modify the client-config.xml file that resides in the current working directory.

Once a Web resource is deployed, either to the client or the server, it will be available until it is undeployed—even across servlet engine restarts.

At the time of publication, Axis' deployment XML files use a very simple XML definition format. Although this format works for now, it doesn't quite support the full features that Axis is planning to have. Eventually, Axis will switch to a new XML format called Web Services Deployment Descriptor (WSDD) graphics/book.gif. Although WSDD is still under development, it should be more robust than the current XML deployment file. One other advantage is that WSDD will have a WSDL flavor that should allow for Web services that are defined in WSDL to be deployed by having the WSDD point to their WSDL file. But all of this is still being designed.

By default, Axis will have several handlers, chains, and services automatically deployed. If a server-config.xml file is not found in the appRoot/WEB-INF directory by the Axis server, Axis will default to have the following pre-deployed:

  • JWSProcessor service— Looks for and processes JWS files (JWS was briefly discussed in Chapter 3, and will be discussed in more detail later in this chapter).

  • RPCProvider handler— Locates and invokes a Java class method.

  • AdminService service— Takes as input an XML document that will be interpreted as a deployment data XML file containing the list of new handlers, chains, and services to deploy (or undeploy).

  • HTTPSender handler— Is used by an Axis client to send a SOAP request to a SOAP server. It can also be used on the server side when a message should be sent to another SOAP server using HTTP (for example, an intermediary).

If a client-config.xml file is not found, then Axis will default to having just one handler pre-deployed: the HTTPSender, for use in sending a SOAP request over HTTP.
    Previous Section Next Section