Configure Axis Web Services
Return prewritten WSDL from an AXIS Web service
by Kevin Jones
March 5, 2003
Web services are probably the largest growing area of development at the moment. They promise to
provide interoperability across platforms and languages. Web services are built around XML, XML
Schema, Simple Object Access Protocol (SOAP), and Web Services Description Language (WSDL).
XML is used as the common description between systems, Schema is used to describe the data
carried in the XML payload, and SOAP is used (among other things) to provide a way of framing XML
messages.
So what is WSDL? It's the Interface Definition Language (IDL) of the Web services world. A WSDL
document describes a Web service in detail, the messages the Web service will send, the data types
used in those messages, the style of the messages, and also the location of the service. A WSDL
document can be used to generate server-side skeletons and/or client-side stubs.
When creating a Web service the WSDL should be your starting point as it provides the contract that
both the client and the service must adhere to. A typical recommendation when creating a Web
service is to start with the WSDL and use it to generate the server-side skeletons, and then use these
skeletons as the basis of the Web service implementation. However, many developers do not like
writing WSDL for several reasons. WSDL is complex and tedious, and currently many of the tools for
writing WSDL are error prone and incomplete, although this is changing. Instead, what developers do
is write the Web service and then rely on the toolkits they use to generate the WSDL dynamically for
them. Toolkits do this dynamic generation based on information provided by the developer as part of
the application and by using reflection to discover type information about the code used to implement
the Web service.
Axis is an open source toolkit that is developed as part of Apache. It is available from xml.apache.org,
and at the time of this writing was at version 1.0 with version 1.1 to appear shortly. Axis allows
developers to write Java code and deploy that code as a Web service. There are several ways of
deploying as a Web service; for example, the simplest way is to place a file with a JWS extension into
an Axis Web application. This file will contain Java source code. Any public methods in a JWS file are
exposed as methods on the Web service. However, use of JWS files, while good for demonstration
purposes, is currently too simplistic for real-world development—although, this will change in later
versions of Axis.
Instead, most Axis users will write standard Java code and then make that code available as a Web
service. This service requires a description. Let's look at a simple example. Imagine a Java class that
looks like this:
public class MathService
{
public double add(
double d1, double d2)
{
return d1+d2;
}
}
You can deploy this class as a Web service in Axis by providing a server-config.wsdd file that contains
this section:
<service name="MathService"
provider="java:RPC"
style="wrapped" use=
"literal">
<parameter name="className"
value=" MathService"/>
<parameter name=
"allowedMethods" value=
"*"/>
</service>
To obtain the WSDL from this service a client could browse to the URL
http://localhost/MyService/services/MathService?wsd, which would produce the WSDL in Listing 1.
This WSDL is generated dynamically from the information in server-config.wsdd, and by reflecting over
the Java class. Many, if not all, Web services toolkits will provide tools to consume this WSDL, which
means that you can use the toolkit to read the WSDL from which the toolkit will generate the clientside stubs that are able to invoke the Web service described by this WSDL. Once you have the stubs
you can then write the client implementation that uses these stubs.
Add a Parameter
So far so good. But suppose you follow the recommendation of always starting with the WSDL.
Starting with the WSDL means that you as a developer write WSDL that would be similar to the WSDL
shown in Listing 1, but not necessarily exactly the same, and you can then generate your server-side
code. But now what happens is you deploy the server, the client browses to the ?wsdl URL, and Axis
returns generated WSDL. This process seems to be both a waste of server-side resources, because
Axis needs to regenerate WSDL that you've already written, and also wrong, because you would like
the client to use your handwritten WSDL rather than the Axis-generated WSDL.
What you require, then, is to be able to configure Axis to return WSDL that you provide and not to
generate new WSDL for each request. In Axis achieving this requirement is trivial; you can add a
configuration parameter to server-config.wsdd. The parameter to add is called wsdlFile, and it goes in
the service section of the wsdd file:
<service name="MathService"
provider="java:RPC"
style="wrapped"
use="literal">
<parameter name="className"
value=" MathService"/>
<parameter name=
"allowedMethods" value=
"*"/>
<wsdlFile>/MathService.wsdl
</wsdlFile>
</service>
The only question now is where to out the MathService.wsdl file. Because Web applications can be
loaded from places other than the file system—for example, from a War file—Axis cannot rely on file
IO to load the WSDL. Instead, Axis tries to load the WSDL as a resource, which means that the WSDL
must be somewhere on the Web application's classpath, and the safest place to put the WSDL is into
the application's WEB-INF/classes directory. Axis will load and find the WSDL there.
So what have we done? WSDL is a key ingredient when building Web services. As a Web services
developer you should start with WSDL and from that generate the necessary client- and server-side
code. Most toolkits, including Axis, will consume WSDL automatically to produce clients and produce
WSDL from deployed services. However, if you create the WSDL yourself you should override the
default generation mechanism provided by your toolkit. In Axis this is trivial: add a <wsdlFile> entry to
the server-config.wsdd file, and then add the WSDL document to the correct location in the Web
application, typically the WEB-INF/classes directory.
About the Author
Kevin Jones is a developer with more than 15 years of experience. He has spent the last four years
researching and teaching Java programming and most recently investigating HTTP and XML. Kevin
lives in the U.K. and works for DevelopMentor, a training company based in the United States and
Europe that specializes in technical training on Java and Microsoft platforms. Reach Kevin at
kevinj@develop.com.