We have here a very simple service that returns a list of products. Our implementation class creates the same list from scratch, but you could get it from a database instead. That's left as an exercise for the reader.

We abstract this with an java interface, always a good idea when using something over the network.

package be.ooxs.examples.wsaxis.common;

import java.util.List;

public interface CatalogService {
	public List<Product> getAvailableProducts();
}

We also have some helper classes that encapsulate data, you might know this as the DTO pattern.

Here is the Price

package be.ooxs.examples.wsaxis.common;

import java.math.BigDecimal;

public class Price {
	private BigDecimal value;

	public BigDecimal getValue() {
		return value;
	}

	public void setValue(BigDecimal value) {
		this.value = value;
	}
	
}

Here is the product:

package be.ooxs.examples.wsaxis.common;

public class Product {
	private String name;
	private String sku;
	private Price unitPrice;
	
	public String getName() {
		return name;
	}
	public void setName(String name) {
		this.name = name;
	}
	public String getSku() {
		return sku;
	}
	public void setSku(String sku) {
		this.sku = sku;
	}
	public Price getUnitPrice() {
		return unitPrice;
	}
	public void setUnitPrice(Price unitPrice) {
		this.unitPrice = unitPrice;
	}
	public String toPlainString(){
		return "Product "+name+" "+sku+" price: "+unitPrice.getValue();
	}
	
}
	

Here we have the Web Service Deployment Descriptor (wsdd) , an AXIS specific file.

<?xml version="1.0" encoding="UTF-8"?>

<deployment xmlns="http://xml.apache.org/axis/wsdd/"
	xmlns:java="http://xml.apache.org/axis/wsdd/providers/java">

	<service name="cat" provider="java:RPC">
		<parameter name="className"
			value="be.ooxs.examples.wsaxis.provider.CatalogServiceMemoryBased" />
		<parameter name="interfaceName"
			value="be.ooxs.example.wsaxis.common.CatalogService" />
		<parameter name="allowedMethods" value="*" />
		<namespace>http://catalog.ooxs.be/</namespace>

		<beanMapping qname="ns:Price" xmlns:ns="http://example.ooxs.be/"
			languageSpecificType="java:be.ooxs.examples.wsaxis.common.Price" />

		<beanMapping qname="ns:Product" xmlns:ns="http://example.ooxs.be/"
			languageSpecificType="java:be.ooxs.examples.wsaxis.common.Product" />

	</service>
</deployment>
	

When the AXIS servlet is running, we can use the AdminClient to deploy our service.

Although you can deploy the service at run time, you still need to provide the classes to the AXIS instance. This means in practice restarting that AXIS instance.

This is a Linux script file (bash), but it is a plain java invocation. It should be trivial to do this on other platforms...

	
export AXIS= your/path/to/axis/lib

export CLASSPATH="../classes":
export CLASSPATH=$CLASSPATH"$AXIS/axis-ant.jar":"$AXIS/axis.jar":
export CLASSPATH=$CLASSPATH"$AXIS/commons-discovery-0.2.jar":"$AXIS/commons-logging-1.0.4.jar":
export CLASSPATH=$CLASSPATH"$AXIS/jaxrpc.jar":"$AXIS/log4j-1.2.8.jar":"$AXIS/log4j.properties":
export CLASSPATH=$CLASSPATH"$AXIS/saaj.jar":"$AXIS/wsdl4j-1.5.1.jar"

java -cp $CLASSPATH org.apache.axis.client.AdminClient deployCatalog.wsdd -lhttp://localhost:8080/axis/servlet/AxisServlet
	

This is the WSDL generated by AXIS, formatted for your comfort

<wsdl:definitions targetNamespace="http://catalog.ooxs.be/">

<wsdl:definitions targetNamespace="http://catalog.ooxs.be/">
<!--
WSDL created by Apache Axis version: 1.4
-->

	<wsdl:types>

		<schema targetNamespace="http://catalog.ooxs.be/">
			<import namespace="http://xml.apache.org/xml-soap"/>
			<import namespace="http://schemas.xmlsoap.org/soap/encoding/"/>

			<complexType name="ArrayOf_xsd_anyType">

				<complexContent>

					<restriction base="soapenc:Array">
						<attribute ref="soapenc:arrayType" wsdl:arrayType="xsd:anyType[]"/>
					</restriction>
				</complexContent>
			</complexType>
		</schema>

		<schema targetNamespace="http://xml.apache.org/xml-soap">
			<import namespace="http://catalog.ooxs.be/"/>
			<import namespace="http://schemas.xmlsoap.org/soap/encoding/"/>

			<complexType name="Vector">

				<sequence>
					<element maxOccurs="unbounded" minOccurs="0" name="item" type="xsd:anyType"/>
				</sequence>
			</complexType>
		</schema>
	</wsdl:types>

	<wsdl:message name="getAvailableProductsResponse">
		<wsdl:part name="getAvailableProductsReturn" type="impl:ArrayOf_xsd_anyType"/>
	</wsdl:message>
	<wsdl:message name="getAvailableProductsRequest">

	</wsdl:message>

	<wsdl:portType name="CatalogServiceMemoryBased">

		<wsdl:operation name="getAvailableProducts">
			<wsdl:input message="impl:getAvailableProductsRequest" name="getAvailableProductsRequest"/>
			<wsdl:output message="impl:getAvailableProductsResponse" name="getAvailableProductsResponse"/>
		</wsdl:operation>
	</wsdl:portType>

	<wsdl:binding name="catSoapBinding" type="impl:CatalogServiceMemoryBased">
		<wsdlsoap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/>

		<wsdl:operation name="getAvailableProducts">
			<wsdlsoap:operation soapAction=""/>

			<wsdl:input name="getAvailableProductsRequest">
				<wsdlsoap:body encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" namespace="http://catalog.ooxs.be/" use="encoded"/>
			</wsdl:input>

			<wsdl:output name="getAvailableProductsResponse">
				<wsdlsoap:body encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" namespace="http://catalog.ooxs.be/" use="encoded"/>
			</wsdl:output>
		</wsdl:operation>
	</wsdl:binding>

	<wsdl:service name="CatalogServiceMemoryBasedService">

		<wsdl:port binding="impl:catSoapBinding" name="cat">
			<wsdlsoap:address location="http://localhost:8080/ExampleWSWithAxis2/services/cat"/>
		</wsdl:port>
	</wsdl:service>
</wsdl:definitions>

Although one of the big selling points for web services is that it is loosely coupled, a client is still bound (coupled) to the service by its interface - that is the operations with their arguments and return values. That is not necessarily the same thing as a Java interface.

In an environment where both end points - consumer and provider - are implemented in Java and under your control, it is a good idea to share a common set of interfaces and classes. In our example those shared, common classes are

• CatalogService
• Product
• Price

We need to a little bit of tedious repetitive coding:

import javax.xml.namespace.QName;
import javax.xml.rpc.ServiceException;

import org.apache.axis.client.Call;
import org.apache.axis.client.Service;
import org.apache.axis.encoding.ser.BeanDeserializerFactory;
import org.apache.axis.encoding.ser.BeanSerializerFactory;
...

public static void main(String[] args){
	Service service = new Service();
	Call call = (Call) service.createCall();
	
	//Configure address, operation name and carefully map each type used in the service
	call.setTargetEndpointAddress(new java.net.URL("http://localhost:8080/ExampleWSWithAxis2/services/cat"));
	call.setOperationName(new QName("http://soapinterop.org/", "getAvailableProducts"));
	call.registerTypeMapping(Price.class, 
		new QName("http://example.ooxs.be/", "Price"), 
		BeanSerializerFactory.class, 
		BeanDeserializerFactory.class);
	call.registerTypeMapping(Product.class, 
		new QName("http://example.ooxs.be/", "Product"), 
		BeanSerializerFactory.class, 
		BeanDeserializerFactory.class);
	
	Object o = call.invoke(new Object[] {});
	
	Object[] array = (Object[]) o;
	for (Object object : array) {
		System.out.println(((Product) object).toPlainString());
	}
	System.out.println("Done");
}
...	

OK that is the basic stuff.

But I would feel bad about giving bad examples. Here is a slightly refactored version that is a better starting point and example.

First an abstract base class that can be extended for each separate service you will use.

package be.ooxs.examples.wsaxis.consumer;

import java.net.MalformedURLException;
import java.rmi.RemoteException;
import java.util.HashMap;
import java.util.Map;
import java.util.Map.Entry;

import javax.xml.namespace.QName;
import javax.xml.rpc.ServiceException;

import org.apache.axis.client.Call;
import org.apache.axis.client.Service;
import org.apache.axis.encoding.ser.BeanDeserializerFactory;
import org.apache.axis.encoding.ser.BeanSerializerFactory;

import be.ooxs.examples.wsaxis.common.Price;
import be.ooxs.examples.wsaxis.common.Product;

public abstract class AbstractServiceConsumer {
	private Map<QName, Class<?>> registeredParameterTypes;
	{
		//in production environment, use Spring IOC instead
		registeredParameterTypes = new HashMap<QName, Class<?>>();
		registeredParameterTypes.put(new QName("http://example.ooxs.be/", "Price"), Price.class);
		registeredParameterTypes.put(new QName("http://example.ooxs.be/", "Product"), Product.class);
	}

	private void configureParameterTypes(Call call) {
		for (Entry<QName, Class<?>> entry : registeredParameterTypes.entrySet()) {
			registerSOAPType(call, entry.getValue(), entry.getKey());
		}
	}

	private void registerSOAPType(Call call, Class<?> javaClass, QName qName) {
		call.registerTypeMapping(javaClass, qName, BeanSerializerFactory.class, BeanDeserializerFactory.class);
	}

	protected Object invoke(String methodName) throws RemoteException, MalformedURLException, ServiceException {
		String endpoint = "http://localhost:8080/ExampleWSWithAxis2/services/cat";

		Service service = new Service();
		Call call = (Call) service.createCall();

		configureParameterTypes(call);
		call.setTargetEndpointAddress(new java.net.URL(endpoint));
		call.setOperationName(new QName("http://soapinterop.org/", "getAvailableProducts"));

		Object o = call.invoke(new Object[] {});
		return o;
	}

	protected <T> List<T> convert(Object[] array, Class<T> type) {
		List<T> list = new ArrayList<T>();
		for (Object object : array) {
			list.add(type.cast(object));
		}
		return list;
	}

}

Next, a concrete implementation for our CatalogService

package be.ooxs.examples.wsaxis.consumer;

import java.util.ArrayList;
import java.util.List;
import java.util.logging.Level;
import java.util.logging.Logger;

import be.ooxs.examples.wsaxis.common.CatalogService;
import be.ooxs.examples.wsaxis.common.Product;

public class SimpleCatalogConsumer extends AbstractServiceConsumer implements CatalogService {

	@Override
	public List<Product> getAvailableProducts() {
		try {
			Object o = invoke("getAvailableProducts");
			Object[] array = (Object[]) o;
			return convert(array, Product.class);
		} catch (Exception exception) {
			Logger.getLogger(SimpleCatalogConsumer.class.getName()).log(Level.SEVERE, "getAvailableProducts threw Exception", exception);
			throw new RuntimeException(exception);
		}
	}

}