Document/Literal Web Services on the Sun Application Server 8

Back to Web Services Resources and Tutorials

Setting Up Your Environment

You will need the Sun application server (to use the wscompile utility and for the application server itself) and of course Java SE 5. Links are below. The versions may differ by the time you see this; results are not expected to vary, but the version numbers are provided here as a record of what versions were used during the production of this tutorial:

After installing these packages, prepend the bin directories of the J2SE and Sun app-server packages to your path, and verify that the Sun Application server starts correctly.

Back to Top

Starting with a WSDL File

As was mentioned in the introduction to this tutorial, we will emphasize interoperability and the use of the WSDL file as the starting point. Create a directory to hold this project and create a subdirectory called wsdl. For this tutorial, the project directory is called tutorial. Within the wsdl directory, create a file called tutorial.wsdl.

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

Generating a Simple Service

The wscompile tool is found in the bin directory of the application server.

wscompile operates in 3 modes:

Not made clear from the descriptions of these options is that -import is used when starting with a WSDL file. The other options create the WSDL file from the RMI interface. wscompile requires a configuration file For details, see the wscompile man page. We will use wscompile twice; once to generate the tie (skeleton) and once to generate the stub. To keep the sources separate (mainly, to avoid cluttering the server-side archive with client classes), we'll direct the output from wscompile into two different source directories.

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>
(or get it from here).

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
Note that classes are generated in the Java package com.example and that a JAX-RPC mapping file has been placed into the descriptors directory. wscompile compiles the classes, in addition to generating them. You will need to modify the server implementation class and rebuild, however.

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;
  }
}
Recompile by including the jaxrpc-api.jar and jaxrpc-impl.jar files (from the Sun application server lib directory) in your classpath. At the top level of your tutorial directory, create a directory called 
webapp/WEB-INF/classes
(this means we'll be deploying the web service as a servlet) and then execute the following command from the src/server directory, appropriately substituting the path to your installation of the Sun application server: 
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

Packaging and Deploying the Service

In addition to the WSDL file, three deployment descriptors are need to successfully deploy your document/literal web service on Sun. They are

These three files are well-known descriptors for servlets and webservices; examples of the first two for this tutorial are web.xml and webservices.xml. The JAX-RPC mapping file was generated by wscompile. Some features of these files:
  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.

It is now time to package and deploy the web service. The three 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
  classes
    com
      example
        - PingRequestType.class
        - PingResponseType.class
        - TutorialPT.class
        - TutorialPT_Impl.class
        - TutorialService.class
  wsdl
    - tutorial.wsdl
To package the webservice into a file called tutorial.war, execute the following command from the tutorial's top-level directory: 
jar cvf tutorial.war -C webapp .
This file can then be dropped onto the autodeploy directory of your running Sun "domain1" domain (or whatever domain you choose, of course). To verify that the web service has deployed correctly, attempt to retrieve the web servcie WSDL at 
http://host:port/tutorial/ping?wsdl
(substitute your hostname and port number) and verify that the WSDL file is available. This check only verifies that the web service has deployed, but not necessarily that it has deployed correctly. To test further, look at the client tutorials under Web Services Resources and Tutorials.

Back to Top
Back to Web Services Resources and Tutorials