Deploying via descriptors

To really use the flexibility available to you in Axis, you should get familiar with the Axis Web Service Deployment Descriptor (WSDD) format. A deployment descriptor contains a bunch of things you want to "deploy" into Axis - i.e. make available to the Axis engine. The most common thing to deploy is a Web Service, so let's start by taking a look at a deployment descriptor for a basic service (this file is samples/userguide/example3/deploy.wsdd):

<deployment xmlns="http://xml.apache.org/axis/wsdd/"
    xmlns:java="http://xml.apache.org/axis/wsdd/providers/java">
  <service name="MyService" provider="java:RPC">
    <parameter name="className" value="samples.userguide.example3.MyService"/>
    <parameter name="allowedMethods" value="*"/>
  </service>
</deployment>

Pretty simple, really - the outermost element tells the engine that this is a WSDD deployment, and defines the "java" namespace. Then the service element actually defines the service for us. A service is a targeted chain (see the Architecture Guide), which means it may have any/all of: a request flow, a pivot Handler (which for a service is called a "provider"), and a response flow. In this case, our provider is "java:RPC", which is built into Axis, and indicates a Java RPC service. The actual class which handles this is org.apache.axis.providers.java.RPCProvider. We'll go into more detail later on the different styles of services and their providers.

We need to tell the RPCProvider that it should instantiate and call the correct class (e.g. samples.userguide.example3.MyService), and we do so by including <parameter> tags, giving the service one parameter to configure the class name, and another to tell the engine that any public method on that class may be called via SOAP (that's what the "*" means; we could also have restricted the SOAP-accessible methods by using a space or comma separated list of available method names).

<service name="MyService"...>
  <parameter name="scope" value="value"/>
  ...
</service>

Using the AdminClient

Once we have this file, we need to send it to an Axis server in order to actually deploy the described service. We do this with the AdminClient, or the "org.apache.axis.client.AdminClient" class. If you have deployed Axis on a server other than Tomcat, you may need to use the -p <port> argument. The default port is 8080. A typical invocation of the AdminClient looks like this:

% java org.apache.axis.client.AdminClient deploy.wsdd
<Admin>Done processing</Admin>

This command has now made our service accessible via SOAP. Check it out by running the Client class - it should look like this:

% java samples.userguide.example3.Client
  -lhttp://localhost:8080/axis/services/MyService "test me!"
You typed : test me!
%

If you want to prove to yourself that the deployment really worked, try undeploying the service and calling it again. There's an "undeploy.wsdd" file in the example3/ directory which you can use just as you did the deploy.wsdd file above. Run the AdminClient on that file, then try the service Client again and see what happens.

You can also use the AdminClient to get a listing of all the deployed components in the server:

% java org.apache.axis.client.AdminClient list
<big XML document returned here>

In there you'll see services, handlers, transports, etc. Note that this listing is an exact copy of the server's "server-config.wsdd" file, which we'll talk about in more detail a little later.

More deployment - Handlers and Chains

Now let's start to explore some of the more powerful features of the Axis engine. Let's say you want to track how many times your service has been called. We've included a sample handler in the samples/log directory to do just this. To use a handler class like this, you first need to deploy the Handler itself, and then use the name that you give it in deploying a service. Here's a sample deploy.wsdd file (this is example 4 in samples/userguide):

<deployment xmlns="http://xml.apache.org/axis/wsdd/"
    xmlns:java="http://xml.apache.org/axis/wsdd/providers/java">
  <!-- define the logging handler configuration -->
  <handler name="track" type="java:samples.userguide.example4.LogHandler">
    <parameter name="filename" value="MyService.log"/>
   </handler>

  <!-- define the service, using the log handler we just defined -->
  <service name="LogTestService" provider="java:RPC">
    <requestFlow>
      <handler type="track"/>
    </requestFlow>

    <parameter name="className" value="samples.userguide.example4.Service"/>
    <parameter name="allowedMethods" value="*"/>
  </service>
</deployment>

The first section defines a Handler called "track" that is implemented by the class samples.userguide.example4.LogHandler. We give this Handler an option to let it know which file to write its messages into.

Then we define a service, LogTestService, which is an RPC service just like we saw above in our first example. The difference is the <requestFlow> element inside the <service> - this indicates a set of Handlers that should be invoked when the service is invoked, before the provider. By inserting a reference to "track", we ensure that the message will be logged each time this service is invoked.

Remote Administration

Note that by default, the Axis server is configured to only accept administration requests from the machine on which it resides - if you wish to enable remote administration, you must set the "enableRemoteAdmin" property of the AdminService to true. To do this, find the "server-config.wsdd" file in your webapp's WEB-INF directory. In it, you'll see a deployment for the AdminService. Add an option as follows:

<service name="AdminService" provider="java:MSG">
  <parameter name="className" value="org.apache.axis.util.Admin"/>
  <parameter name="allowedMethods" value="*"/>
  <parameter name="enableRemoteAdmin" value="true"/>
</service>

WARNING: enabling remote administration may give unauthorized parties access to your machine. If you do this, please make sure to add security to your configuration!

RPC services

RPC services are the default in Axis. They are what you get when you deploy services with <service ... provider="java:RPC"> or <service ... style="RPC">. RPC services follow the SOAP RPC and encoding rules, which means that the XML for an RPC service will look like the "echoString" example above - each RPC invocation is modeled as an outer element which matches the operation name, containing inner elements each of which maps to a parameter of the operation. Axis will deserialize XML into Java objects which can be fed to your service, and will serialize the returned Java object(s) from your service back into XML. Since RPC services default to the soap section 5 encoding rules, objects will be encoded via "multi-ref" serialization, which allows object graphs to be encoded. (See the SOAP spec for more on multi-ref serialization.)

Document / Wrapped services

Document services and wrapped services are similar in that neither uses the SOAP encoding for data; it's just plain old XML schema. In both cases, however, Axis still "binds" Java representations to the XML (see the databinding section for more), so you end up dealing with Java objects, not directly with XML constructs.

A good place to start in describing the difference between document and wrapped services is with a sample SOAP message containing a purchase order:

<soap:Envelope xmlns="http://xml.apache.org/axis/wsdd/"
    xmlns:java="http://xml.apache.org/axis/wsdd/providers/java">
  <soap:Body>
    <myNS:PurchaseOrder xmlns:myNS="http://commerce.com/PO">
      <item>SK001</item>
      <quantity>1</quantity>
      <description>Sushi Knife</description>
    </myNS:PurchaseOrder>
  </soap:Body>
</soap:Envelope>

The relevant schema for the PurchaseOrder looks like this:

<schema targetNamespace="http://commerce.com/PO">
  <complexType name="POType">
    <sequence>
      <element name="item" type="xsd:string"/>
      <element name="quantity" type="xsd:int"/>
      <element name="description" type="xsd:string"/>
    </sequence>
  </complexType>
  <element name="PurchaseOrder" type="POType"/>
</schema>

For a document style service, this would map to a method like this:

public void method(PurchaseOrder po)

In other words, the ENTIRE <PurchaseOrder> element would be handed to your method as a single bean with three fields inside it. On the other hand, for a wrapped style service, it would map to a method like this:

public void purchaseOrder(String item, int quantity, String description)

Note that in the "wrapped" case, the <PurchaseOrder> element is a "wrapper" (hence the name) which only serves to indicate the correct operation. The arguments to our method are what we find when we "unwrap" the outer element and take each of the inner ones as a parameter.

The document or wrapped style is indicated in WSDD as follows:

<service ... style="document"> for document style
<service ... style="wrapped"> for wrapped style

In most cases you won't need to worry about document or wrapped services if you are starting from a WSDL document (see below).

Message services

Finally, we arrive at "Message" style services, which should be used when you want Axis to step back and let your code at the actual XML instead of turning it into Java objects. There are four valid signatures for your message-style service methods:

public Element [] method(Element [] bodies);
public SOAPBodyElement [] method (SOAPBodyElement [] bodies);
public Document method(Document body);
public void method(SOAPEnvelope req, SOAPEnvelope resp);

The first two will pass your method arrays of either DOM Elements or SOAPBodyElements - the arrays will contain one element for each XML element inside the <soap:body> in the envelope.

The third signature will pass you a DOM Document representing the <soap:body>, and expects the same in return.

The fourth signature passes you two SOAPEnvelope objects representing the request and response messages. This is the signature to use if you need to look at or modify headers in your service method. Whatever you put into the response envelope will automatically be sent back to the caller when you return. Note that the response envelope may already contain headers which have been inserted by other Handlers.

Message Example

A sample message service can be found in samples/message/MessageService.java. The service class, MessageService, has one public method, echoElements, which matches the first of the three method signatures above:

public Element[] echoElements(Element [] elems)

The MsgProvider handler calls the method with an array of org.w3c.dom.Element objects that correspond to the immediate children of the incoming message's SOAP Body. Often, this array will contain a single Element (perhaps the root element of some XML document conforming to some agreed-upon schema), but the SOAP Body can handle any number of children. The method returns an Element[] array to be returned in the SOAP body of the response message.

Message services must be deployed with a WSDD file. Here is the full WSDD for the MessageService class:

<deployment name="test" xmlns="http://xml.apache.org/axis/wsdd/"
    xmlns:java="http://xml.apache.org/axis/wsdd/providers/java"
    xmlns:xsi="http://www.w3.org/2000/10/XMLSchema-instance">
  <service name="MessageService" style="message">
    <parameter name="className" value="samples.message.MessageService"/>
    <parameter name="allowedMethods" value="echoElements"/>
  </service>
</deployment>

Note that the "style" attribute is different from the RPC deployment example. The "message" style tells Axis that this service is to be handled by org.apache.axis.providers.java.MsgProvider rather than org.apache.axis.providers.java.RPCProvider.

You can test this service by deploying it, then running samples.message.TestMsg (look at the source to see what the test driver does).

Standard mappings from WSDL to Java

If the WSDL says that an object can be nillable, that is the caller may choose to return a value of nil, then the primitive data types are replaced by their wrapper classes, such as Byte, Double, Boolean, etc.

SOAP Encoding Datatypes

Alongside the XSD datatypes are the SOAP 'Section 5' datatypes that are all nillable, and so only ever map to the wrapper classes. These types exist because they all support the "ID" and "HREF" attributes, and so will be used when in an RPC-encoded context to support multi-ref serialization.

RemoteExceptions map to SOAP Faults

If the server method throws a java.rmi.RemoteException then this will be mapped into a SOAP Fault. The faultcode of this will contain the classname of the fault. The recipient is expected to deserialize the body of the fault against the classname.

Obviously, if the recipient does not know how to create an instance of the received fault, this mechanism does not work. Unless you include information about the exception class in the WSDL description of the service, or sender and receiver share the implementation, you can only reliably throw java.rmi.RemoteException instances, rather than subclasses.

When an implementation in another language receives such an exception, it should see the name of the class as the faultCode, but still be left to parse the body of the exception. You need to experiment to find out what happens there.

Exceptions are represented as wsdl:fault elements

If a method is marked as throwing an Exception that is not an instance or a subclass of java.rmi.RemoteException, then things are subtly different. The exception is no longer a SOAP Fault, but described as a wsdl:fault in the WSDL of the method. According to the JAX-RPC specification, your subclass of Exception must have accessor methods to access all the fields in the object to be marshalled and a constructor that takes as parameters all the same fields (i.e, arguments of the same name and type). This is a kind of immutable variant of a normal JavaBean. The fields in the object must be of the datatypes that can be reliably mapped into WSDL.

If your exception meets this specification, then the WSDL describing the method will describe the exception too, enabling callers to create stub implementations of the exception, regardless of platform.

Again, to be sure of interoperability, you need to be experiment a bit. Remember, the calling language may not have the notion of Exceptions, or at least not be as rigorous as Java in the rules as to how exceptions must be handled.

Java Collections

Some of the Collection classes, such as Hashtable, do have serializers, but there is no formal interoperability with other SOAP implementations, and nothing in the SOAP specifications which covers complex objects. The most reliable way to send aggregate objects is to use arrays. In particular, .NET cannot handle them, though many Java SOAP implementations can marshall and unmarshall hash tables.

Arbitrary Objects without Pre-Registration

You cannot send arbitrary Java objects over the wire and expect them to be understood at the far end. With RMI you can send and receive Serializable Java objects, but that is because you are running Java at both ends. Axis will only send objects for which there is a registered Axis serializer. This document shows below how to use the BeanSerializer to serialize any class that follows the JavaBean pattern of accessor and mutator. To serve up objects you must either register your classes with this BeanSerializer, or there must be serialization support built in to Axis.

Remote References

Remote references are neither part of the SOAP specification, nor the JAX-RPC specification. You cannot return some object reference and expect the caller to be able to use it as an endpoint for SOAP calls or as a parameter in other calls. Instead you must use some other reference mechanism, such as storing them in a HashMap with numeric or string keys that can be passed over the wire.

Deploying custom mappings - the <typeMapping> tag

Now that you've built your serializers and deserializers, you need to tell Axis which types they should be used for. You do this with a typeMapping tag in WSDD, which looks like this:

<typeMapping qname="ns:local" xmlns:ns="someNamespace"
    languageSpecificType="java:my.java.thingy"
    serializer="my.java.Serializer"
    deserializer="my.java.DeserializerFactory"
    encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>

This looks a lot like the <beanMapping> tag we saw earlier, but there are three extra attributes. One, serializer, is the Java class name of the Serializer factory which gets the serializer to be used to marshal an object of the specified Java class (i.e., my.java.thingy) into XML. Another, deserializer, is the class name of a Deserializer factory that gets the deserializer to be used to unmarshall XML into the correct Java class. The final attribute, the encodingStyle, which is SOAP encoding.

(The <beanMapping> tag is really just shorthand for a <typeMapping> tag with serializer="org.apache.axis.encoding.ser.BeanSerializerFactory", deserializer="org.apache.axis.encoding.ser.BeanDeserializerFactory", and encodingStyle="http://schemas.xmlsoap.org/soap/encoding/", but clearly it can save a lot of typing!)

Deploying array mappings - the <arrayMapping> tag

Another variation around typeMapping is arrayMapping. The arrayMapping tag is useful for advanced users wanting to exatly control how their arrays are serialized throught the wire.

<arrayMapping qname="ns:ArrayOfthingy" xmlns:ns="someNamespaceURI"
             languageSpecificType="java:my.java.array.thingy[]"
			 innerType="ns2:thingy" xmlns:ns2="anotherNamespaceURI"
             encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>

No need here to specify a serializer/deserializer couple, the arrayMapping tag is only about arrays (no List, ...). The added attribute (innerType) is used to tell Axis what precisely is the item type of the Array.

Client-side bindings

You'll find the Axis WSDL-to-Java tool in "org.apache.axis.wsdl.WSDL2Java". The basic invocation form looks like this:

% java org.apache.axis.wsdl.WSDL2Java (WSDL-file-URL)

This will generate only those bindings necessary for the client. Axis follows the JAX-RPC specification when generating Java client bindings from WSDL. For this discussion, assume we executed the following:

% cd samples/addr
% java org.apache.axis.wsdl.WSDL2Java AddressBook.wsdl

The generated files will reside in the directory "AddressFetcher2". They are put here because that is the target namespace from the WSDL and namespaces map to Java packages. Namespaces will be discussed in detail later.

There is an Ant Task to integrate this action with an Ant based build process.

Types

The Java class generated from a WSDL type will be named from the WSDL type. This class will typically, though not always, be a bean. For example, given the WSDL (the WSDL used throughout the WSDL2Java discussion is from the Address Book sample):

<xsd:complexType name="phone">
  <xsd:all>
    <xsd:element name="areaCode" type="xsd:int"/>
    <xsd:element name="exchange" type="xsd:string"/>
    <xsd:element name="number" type="xsd:string"/>
  </xsd:all>
</xsd:complexType>

WSDL2Java will generate:

public class Phone implements java.io.Serializable {
  public Phone() {...}
  public int getAreaCode() {...}
  public void setAreaCode(int areaCode) {...}
  public java.lang.String getExchange() {...}
  public void setExchange(java.lang.String exchange) {...}
  public java.lang.String getNumber() {...}
  public void setNumber(java.lang.String number) {...}
  public boolean equals(Object obj) {...}
  public int hashCode() {...}
}

Mapping XML to Java types : Metadata

Notice in the mapping above, the XML type name is "phone" and the generated Java class is "Phone" - the capitalization of the first letter has changed to match the Java coding convention that classes begin with an uppercase letter. This sort of thing happens a lot, because the rules for expressing XML names/identifiers are much less restrictive than those for Java. For example, if one of the sub-elements in the "phone" type above was named "new", we couldn't just generate a Java field called "new", since that is a reserved word and the resultant source code would fail to compile.

To support this kind of mapping, and also to enable the serialization/deserialization of XML attributes, we have a type metadata system which allows us to associate Java data classes with descriptors which control these things.

When the WSDL2Java tool creates a data bean like the Phone class above, it notices if the schema contains any attributes, or any names which do not map directly to Java field/property names. If it finds any of these things, it will generate a static piece of code to supply a type descriptor for the class. The type descriptor is essentially a collection of field descriptors, each of which maps a Java field/property to an XML element or attribute.

To see an example of this kind of metadata, look at the "test.encoding.AttributeBean" class in the Axis source, or generate your own bean from XML which uses attributes or names which would be illegal in Java.

Holders

This type may be used as an inout or out parameter. Java does not have the concept of inout/out parameters. In order to achieve this behavior, JAX-RPC specifies the use of holder classes. A holder class is simply a class that contains an instance of its type. For example, the holder for the Phone class would be:

package samples.addr.holders;

public final class PhoneHolder implements javax.xml.rpc.holders.Holder {
  public samples.addr.Phone value;

  public PhoneHolder() {
  }

  public PhoneHolder(samples.addr.Phone value) {
    this.value = value;
  }
}

A holder class is only generated for a type if that type is used as an inout or out parameter. Note that the holder class has the suffix "Holder" appended to the class name, and it is generated in a sub-package with the "holders".

The holder classes for the primitive types can be found in javax.xml.rpc.holders.

PortTypes

The Service Definition Interface (SDI) is the interface that's derived from a WSDL's portType. This is the interface you use to access the operations on the service. For example, given the WSDL:

<message name="empty">
<message name="AddEntryRequest">
  <part name="name" type="xsd:string"/>
  <part name="address" type="typens:address"/>
</message>
<portType name="AddressBook">
  <operation name="addEntry">
    <input message="tns:AddEntryRequest"/>
    <output message="tns:empty"/>
  </operation>
</portType>

WSDL2Java will generate:

public interface AddressBook extends java.rmi.Remote {
  public void addEntry(String name, Address address) throws
      java.rmi.RemoteException;
}

A note about the name of the SDI. The name of the SDI is typically the name of the portType. However, to construct the SDI, WSDL2Java needs information from both the portType and the binding. (This is unfortunate and is a topic of discussion for WSDL version 2.)

JAX-RPC says (section 4.3.3): "The name of the Java interface is mapped from the name attribute of the wsdl:portType element. ... If the mapping to a service definition interface uses elements of the wsdl:binding ..., then the name of the service definition interface is mapped from the name of the wsdl:binding element."

Note the name of the spec. It contains the string "RPC". So this spec, and WSDL2Java, assumes that the interface generated from the portType is an RPC interface. If information from the binding tells us otherwise (in other words, we use elements of the wsdl:binding), then the name of the interface is derived instead from the binding.

Why? We could have one portType - pt - and two bindings - bRPC and bDoc. Since document/literal changes what the interface looks like, we cannot use a single interface for both of these bindings, so we end up with two interfaces - one named pt and another named bDoc - and two stubs - bRPCStub (which implements pt) and bDocStub (which implements bDoc).

Ugly, isn't it? But you can see why it's necessary. Since document/literal changes what the interface looks like, and we could have more than one binding referring to a single portType, we have to create more than one interface, and each interface must have a unique name.

Bindings

A Stub class implements the SDI. Its name is the binding name with the suffix "Stub". It contains the code which turns the method invocations into SOAP calls using the Axis Service and Call objects. It stands in as a proxy (another term for the same idea) for the remote service, letting you call it exactly as if it were a local object. In other words, you don't need to deal with the endpoint URL, namespace, or parameter arrays which are involved in dynamic invocation via the Service and Call objects. The stub hides all that work for you.

Given the following WSDL snippet:

<binding name="AddressBookSOAPBinding" type="tns:AddressBook">
  ...
</binding>

WSDL2Java will generate:

public class AddressBookSOAPBindingStub extends org.apache.axis.client.Stub
    implements AddressBook {
  public AddressBookSOAPBindingStub() throws org.apache.axis.AxisFault {...}

  public AddressBookSOAPBindingStub(URL endpointURL,
      javax.xml.rpc.Service service) throws org.apache.axis.AxisFault {...}

  public AddressBookSOAPBindingStub(javax.xml.rpc.Service service)
      throws org.apache.axis.AxisFault {...}

  public void addEntry(String name, Address address)
      throws RemoteException {...}
}

Services

Normally, a client program would not instantiate a stub directly. It would instead instantiate a service locator and call a get method which returns a stub. This locator is derived from the service clause in the WSDL. WSDL2Java generates two objects from a service clause. For example, given the WSDL:

<service name="AddressBookService">
  <port name="AddressBook" binding="tns:AddressBookSOAPBinding">
    <soap:address location="http://localhost:8080/axis/services/AddressBook"/>
  </port>
</service>

WSDL2Java will generate the service interface:

public interface AddressBookService extends javax.xml.rpc.Service {
  public String getAddressBookAddress();

  public AddressBook getAddressBook() throws javax.xml.rpc.ServiceException;

  public AddressBook getAddressBook(URL portAddress)
      throws javax.xml.rpc.ServiceException;
}

WSDL2Java will also generate the locator which implements this interface:

public class AddressBookServiceLocator extends org.apache.axis.client.Service
    implements AddressBookService {
  ...
}

The service interface defines a get method for each port listed in the service element of the WSDL. The locator is the implementation of this service interface. It implements these get methods. It serves as a locator for obtaining Stub instances. The Service class will by default make a Stub which points to the endpoint URL described in the WSDL file, but you may also specify a different URL when you ask for the PortType.

A typical usage of the stub classes would be as follows:

public class Tester {
  public static void main(String [] args) throws Exception {
    // Make a service
    AddressBookService service = new AddressBookServiceLocator();

    // Now use the service to get a stub which implements the SDI.
    AddressBook port = service.getAddressBook();

    // Make the actual call
    Address address = new Address(...);
    port.addEntry("Russell Butek", address);
  }
}

Server-side bindings

Just as a stub is the client side of a Web Service represented in Java, a skeleton is a Java framework for the server side. To make skeleton classes, you just specify the "--server-side --skeletonDeploy true" options to WSDL2Java. For instance, using the AddressBook.wsdl as we had above:

% java org.apache.axis.wsdl.WSDL2Java --server-side
    --skeletonDeploy true AddressBook.wsdl

You will see that WSDL2Java generates all the classes that were generated before for the client, but it generates a few new files:

If you don't specify the "--skeletonDeploy true" option, a skeleton will not be generated. Instead, the generated deploy.wsdd will indicate that the implementation class is deployed directly. In such cases, the deploy.wsdd contains extra meta data describing the operations and parameters of the implementation class. Here is how you run WSDL2Java to deploy directly to the implementation:

% java org.apache.axis.wsdl.WSDL2Java --server-side AddressBook.wsdl

And here are the server side files that are generated:

Bindings

public class AddressBookSOAPBindingSkeleton implements AddressBook,
    org.apache.axis.wsdl.Skeleton {
  private AddressBook impl;

  public AddressBookSOAPBindingSkeleton() {
    this.impl = new AddressBookSOAPBindingImpl();
  }

  public AddressBookSOAPBindingSkeleton(AddressBook impl) {
    this.impl = impl;
  }

  public void addEntry(java.lang.String name, Address address)
      throws java.rmi.RemoteException {
    impl.addEntry(name, address);
  }
}

public class AddressBookSOAPBindingImpl implements AddressBook {
  public void addEntry(String name, Address address)
      throws java.rmi.RemoteException {
  }
}

Services

The tool also builds you a "deploy.wsdd" and an "undeploy.wsdd" for each service for use with the AdminClient. These files may be used to deploy the service once you've filled in the methods of the Implementation class, compiled the code, and made the classes available to your Axis engine.

Step 1: Provide a Java interface or class

Write and compile a Java interface (or class) that describes the web service interface. Here is an example interface that describes a web services that can be used to set/query the price of widgets (samples/userguide/example6/WidgetPrice.java):

package samples.userguide.example6;

/**
 * Interface describing a web service to set and get Widget prices.
 **/
public interface WidgetPrice {
  public void setWidgetPrice(String widgetName, String price);
  public String getWidgetPrice(String widgetName);
}

Note: If you compile your class with debug information, Java2WSDL will use the debug information to obtain the method parameter names.

Step 2: Create WSDL using Java2WSDL

Use the Java2WSDL tool to create a WSDL file from the interface above.

Here is an example invocation that produces the wsdl file (wp.wsdl) from the interface described in the previous section (entered all on one line):

% java org.apache.axis.wsdl.Java2WSDL -o wp.wsdl
    -l"http://localhost:8080/axis/services/WidgetPrice"
    -n  "urn:Example6" -p"samples.userguide.example6" "urn:Example6"
    samples.userguide.example6.WidgetPrice

Where:

• -o indicates the name of the output WSDL file
• -l indicates the location of the service
• -n is the target namespace of the WSDL file
• -p indicates a mapping from the package to a namespace. There may be multiple mappings.
• the class specified contains the interface of the webservice.

The output WSDL document will contain the appropriate WSDL types, messages, portType, bindings and service descriptions to support a SOAP rpc, encoding web service. If your specified interface methods reference other classes, the Java2WSDL tool will generate the appropriate xml types to represent the classes and any nested/inherited types. The tool supports JAX-RPC complex types (bean classes), extension classes, enumeration classes, arrays and Holder classes.

The Java2WSDL tool has many additional options which are detailed in the reference guide. There is an Ant Task to integrate this action with an Ant based build process.

Step 3: Create Bindings using WSDL2Java

Use the generated WSDL file to build the appropriate client/server bindings for the web service (see WSDL2Java):

% java org.apache.axis.wsdl.WSDL2Java -o . -d Session -s -S true
    -Nurn:Example6 samples.userguide.example6 wp.wsdl

This will generate the following files:

• WidgetPriceSoapBindingImpl.java : Java file containing the default server implementation of the WidgetPrice web service.
  You will need to modify the *SoapBindingImpl file to add your implementation (see samples/userguide/example6/WidgetPriceSoapBindingImpl.java).
• WidgetPrice.java: New interface file that contains the appropriate java.rmi.Remote usages.
• WidgetPriceService.java: Java file containing the client side service interface.
• WidgetPriceServiceLocator.java: Java file containing the client side service implementation class.
• WidgetPriceSoapBindingSkeleton.java: Server side skeleton.
• WidgetPriceSoapBindingStub.java: Client side stub.
• deploy.wsdd: Deployment descriptor
• undeploy.wsdd: Undeployment descriptor
• (data types): Java files will be produced for all of the other types and holders necessary for the web service. There are no additional files for the WidgetPrice web service.

Now you have all of the necessary files to build your client/server side code and deploy the web service!

org.apache.axis.MessageContext

The answer to most "where do I find..." questions for an Axis web service is "in the MessageContext." Essentially everything Axis knows about a given request/response can be retrieved via the MessageContext. Here Axis stores:

• A reference to the AxisEngine
• The request and response messages (org.apache.axis.Message objects available via getter and setter methods)
• Information about statefulness and service scope (whether the service is maintaining session information, etc.)
• The current status of processing (whether or not the "pivot" has been passed, which determines whether the request or response is the current message)
• Authentication information (username and password, which can be provided by a servlet container or other means)
• Properties galore. Almost anything you would want to know about the message can be retrieved via MessageContext.getProperty(). You only need to know the name of the property. This can be tricky, but it is usually a constant, like those defined in org.apache.axis.transport.http.HTTPConstants. So, for example, to retrieve the ServletContext for the Axis Servlet, you would want: ((HttpServlet)msgC.getProperty(HTTPConstants.MC_HTTP_SERVLET)).getServletContext();

From within your service, the current MessageContext object is always available via the static method MessageContext.getCurrentContext(). This allows you to do any needed customization of the request and response methods, even from within an RPC service that has no explicit reference to the MessageContext.

org.apache.axis.Message

An org.apache.axis.Message object is Axis's representation of a SOAP message. The request and response messages can be retrieved from the MessageContext as described above. A Message has:

• MIME headers (if the message itself has MIME information)
• Attachments (if the message itself has attachments)
• A SOAPPart (and a convenience method for quick retrieval of the SOAPPart's SOAPEnvelope). The SOAPPart gives you access to the SOAP "guts" of the message (everything inside the <soap:Envelope> tags)

org.apache.axis.SOAPEnvelope

As you can see, starting with the MessageContext lets you work your way down through the API, discovering all the information available to you about a single request/response exchange. A MessageContext has two Messages, which each have a SOAPPart that contains a SOAPEnvelope. The SOAPEnvelope, in turn, holds a full representation of the SOAP Envelope that is sent over the wire. From here you can get and set the contents of the SOAP Header and the SOAP Body. See the Javadocs for a full list of the properties available.