Back to Web Services Resources and Tutorials

• Setting Up Your Environment
• Starting with a WSDL File
• Generating a Simple Service
• Packaging and Deploying the Service

• JBoss 4.0.3 SP1
• Sun Application Server 8.1 2005Q2 UR2
• J2SE 5.0 Update 6

Back to Top

A simple example WSDL file for this tutorial can be found here. This isn't a WSDL tutorial, so the details of the file won't be discussed here, other than to note that the portType defines a single operation, "PingRequest", the style is "document" and the use attribute is "literal". The WS-I Basic Profile 1.1 restricts style/use values to RPC/Literal and Document/Literal, while .NET tools (as of this writing) do not support RPC/Literal, so Document/Literal appears to be the best choice for interoperability.

Back to Top

Create a src directory at the top level of your tutorial, then create under it two directories named client and server. Also, at the same level, create a directory called descriptors, where we will store various mapping files and deployment descriptors. At the top level of your tutorial, create a file called config.xml with the following contents:

<?xml version="1.0" encoding="UTF-8"?> 
<configuration xmlns="http://java.sun.com/xml/ns/jax-rpc/ri/config"> 
  <wsdl location="wsdl/tutorial.wsdl"
        packageName="com.example"
        targetNamespace="http://example.com/schema/tutorial" />
</configuration> 

Now, generate the server-side classes with the following:

wscompile -import -keep -d src/server -f:documentliteral,wsi config.xml -mapping descriptors/jaxrpc-mapping.xml

The wscompile tool created a couple of bean classes corresponding to the complex types defined in the WSDL types section: PingRequestType.java and PingResponseType.java. Since this is just an example web service, modify the server implementation class to return a ping response that combines the ping request with some additional information:

package com.example;
public class TutorialPT_Impl implements com.example.TutorialPT, java.rmi.Remote 
{
  public com.example.PingResponseType pingRequest(com.example.PingRequestType request) 
    throws java.rmi.RemoteException
  {   
    com.example.PingResponseType _retVal = new com.example.PingResponseType();
   _retVal.setResponseParam("This is the response to request '" + request.getRequestParam() + "'");
    return _retVal;
  }
}

webapp/WEB-INF/classes

javac -cp C:/Sun/AppServer/lib/jaxrpc-api.jar;C:/Sun/AppServer/lib/jaxrpc-impl.jar -d ../../webapp/WEB-INF/classes com/example/*.java

Back to Top

1. In web.xml, the "servlet-class" refers to the implementation class, that is, the class which implements the wscompile-generated RMI interface. It isn't really a servlet, but this is the convention used to deploy a web service as a servlet; the webservices.xml descriptor supplies the needed additional information.
2. In webservices.xml, specify the location of the WSDL file and the mapping file. Note from the example here that the WSDL file is in a directory called wsdl under the WEB-INF directory; this is a mandatory, not optional, location for the WSDL file.
3. Also, in webservices.xml, the "wsdl-port" refers to the "port" defined in the "service" element in the WSDL file. Note the definition of the namespace prefix as an attribute of "wsdl-port".
4. In webservices.xml, the "servlet-link" element refers to the "servlet-name" from the web.xml file.

The ws4ee-deployment.xml file is the JBossWS version of the Axis deploy.wsdd file; it is needed to supply type mappings for your document element classes. The absence or misconfiguration of this file is a common reason for postings related to deployment problems. For this tutorial, the file (which can be found here) looks as follows:

<deployment xmlns='http://xml.apache.org/axis/wsdd/'
            xmlns:java='http://xml.apache.org/axis/wsdd/providers/java'
            xmlns:soap='http://schemas.xmlsoap.org/soap/encoding/'
            xmlns:xsi='http://www.w3.org/2000/10/XMLSchema-instance'
            xmlns:xsd='http://www.w3.org/2001/XMLSchema'>
    
  <typeMapping xmlns:tutorial="http://example.com/schema/tutorial"
               serializer="org.jboss.axis.encoding.ser.BeanSerializerFactory"
               encodingStyle="" 
               qname="tutorial:PingRequest"
               deserializer="org.jboss.axis.encoding.ser.BeanDeserializerFactory"
               type="java:com.example.PingRequestType" />

  <typeMapping xmlns:tutorial="http://example.com/schema/tutorial"
               serializer="org.jboss.axis.encoding.ser.BeanSerializerFactory"
               encodingStyle="" 
               qname="tutorial:PingResponse"
               deserializer="org.jboss.axis.encoding.ser.BeanDeserializerFactory"
               type="java:com.example.PingResponseType" />

</deployment>

It is now time to package and deploy the web service. The four descriptors mentioned above should be in the WEB-INF directory of the webapp; additionally, the WSDL file should be in a directory called wsdl under WEB-INF. The server class files should be in a directory called classes under the WEB-INF directory. The exploded view should look as follows:

  webappDir
    WEB-INF
      - web.xml
      - webservices.xml
      - jaxrpc-mapping.xml
      - ws4ee-deployment.xml
      classes
        com
          example
            - PingRequestType.class
            - PingResponseType.class
            - TutorialPT.class
            - TutorialPT_Impl.class
            - TutorialService.class
      wsdl
        - tutorial.wsdl

jar cvf tutorial.war -C webapp .

http://host:port/ws4ee

• tutorial.war#Tutorial/Tutorial (wsdl)
  • pingRequest

Back to Top
Back to Web Services Resources and Tutorials