Creating a Simple Service - Java

---

Note - All the examples in the rest of this chapter refer to the J2EE Reference Implementation. However, the information required and the techniques used are common across all implementations of JAX-RPC. Basically, the tools might change but the artifacts and information you have to provide as a developer don't.

---

The initial service is servlet-based and will just pass strings back and forth to exchange greetings. After you are comfortable with this simple service, we will move on to look at how to provide a Web Service
front-end for a session EJB.

Files and Tools

In common with other J2EE components, a J2EE-based Web Service implementation consists of multiple parts:

• A reference to the implementation of the functionality to be exposed by the Web Service, which can point to simple Java classes bundled with the component or which can refer to one
  or more EJBs

• Code that maps between the exposed functionality and the container—for example, skeletons (or ties) and serializers

• A WSDL definition of the interface implemented by the service

• Configuration files that tell the J2EE implementation more about how the service should be deployed and the services it requires from its container

A Web Service client has similar code and configuration files but does not carry an interface definition or service implementation information.

All the configuration files are encoded in XML. Some of them are reasonably simple and can easily be created by hand. Other files,
such as the WSDL interface definition, are far more complex and will typically be generated by tools. The stubs and skeletons required will also be automatically generated. To generate the stubs, skeletons,
and WSDL interface definition, we will use the wscompile tool provided
as part of the J2EE Reference Implementation.

Defining the Interface and Implementation

As with RMI, a remote interface definition is central to the use of JAX-RPC. This interface is either written by a developer and then used to generate a WSDL file, or the Java interface is generated from a pre-provided WSDL file. In the examples we look at today, the WSDL file is generated from the Java interface definition. The Java interface definition must extend java.rmi.Remote and all methods must be declared as throwing java.rmi.RemoteException. The simple Web Service is based around a simple Java Remote interface, Greeting, containing a single method called sayHelloTo(). The sayHelloTo() method takes a single String parameter—the name of the person to greet—and returns the resultant greeting. The Greeting interface is shown in Listing 20.1.

Listing 20.1 Interface for the Greeting Service (Greeting.java)

package wsexamples;
import java.rmi.Remote;
import java.rmi.RemoteException;
public interface Greeting extends Remote
{
public String sayHelloTo(String name) throws RemoteException;
}

The sayHelloTo() method is the Web Service equivalent of the "Hello World!" program used as a first step in learning programming languages such as C and Java. In Web Service terms, the method is simple because it takes a single parameter and returns a single value. These values are both strings, and strings are easily marshaled between the on-the-wire XML representation used by SOAP and the internal java.lang.String type.

The Greeting interface is implemented by the GreetingImplementation
class. The sayHelloTo() method simply appends the name passed in
onto a suitable greeting and passes back the resultant string. The GreetingImplementation class is shown in Listing 20.2.

Listing 20.2 Implementation of the Greeting Service (GreetingImplementation.java)

package wsexamples;
public class GreetingImplementation implements Greeting
{
public String sayHelloTo(String name)
{
return "Hi there " + name;
}
}

As you can see, there is nothing special about the
GreetingImplementation class. If you did not know that Greeting was
a Remote interface, the rest of the class gives you no indication. As stated earlier, this first example will be a servlet-based Web Service. However, there is no servlet definition in the interface or implementation. As the creation of a servlet to implement a given interface is something of a predictable task, all this can be automated. Think of the implementation class as being like the bean class in an EJB—it will get surrounded by "scaffolding" as it is deployed and configured. This "scaffolding" consists of the fixed infrastructure provided by J2EE, such as the SOAP routing servlet discussed earlier, and some files specifically generated for your service, such as the
Web Service stub and skeleton files.

Web Service Compiler Configuration File

When you created EJBs earlier, you had to include various configuration files to tell the container about the EJB and its requirements. The same principle applies for a JAX-RPC Web Service. Somehow, a variety of artifacts must be created that describe the service for potential clients and help to integrate the service with its container. In the J2EE Reference Implementation, the main tool for this is wscompile. The wscompile tool can generate WSDL, server-side scaffolding, and client-side scaffolding. For the time being, you will concentrate on the WSDL and server-side scaffolding.

wscompile requires a variety of information about the artifacts you need to create. You define this information in an XML-encoded configuration file. The root element is configuration and its sole attribute indicates that the file conforms to the RI's JAX-RPC schema:

<configuration xmlns="http://java.sun.com/xml/ns/jax-rpc/ri/config">

Within this root element you will typically define one of two child elements:

• service—Contains information to help generate a WSDL file
  based on a Remote interface

• wsdl—Defines information about a Web Service definition
  from which a Remote interface is to be generated

The element you require will depend on whether you are starting from a Java interface definition or starting from WSDL. In this case, you will start from the code and generate the WSDL. Although this is convenient as a learning exercise, it is not the best practice to follow when creating industrial-strength Web Services. Some of the reasons for this are discussed in the section "Starting from WSDL" later today.

In this case, because you are generating a WSDL file from a Remote interface, you need a service element within the root. The attributes of this element define the following:

• The name of the service (name) that is to be defined in the WSDL description.

• The target namespace (targetNamespace) within which the service's messages and message parts are to be defined.

• The namespace (typeNamespace) within which the service's data types are to be defined.

• The package into which generated Java artifacts are to be placed (packageName). Because you are only defining a WSDL document at the moment, this is not used, but it must still be provided; otherwise, wscompile will fail.

The resultant element will look something like this:

<service name="GreetingService"
targetNamespace="urn:J2EE21Examples" 
typeNamespace="urn:J2EE21ExamplesTypes" 
packageName="wsexamples"
>

Each service element can contain one or more interface elements. The interface element describes a Web Service endpoint that is exposed as part of the service. The name attribute defines the name of the Java interface that implements the methods to be exposed. This should be set to the fully qualified name of the interface you created earlier (you can also specify the name of the implementation, or servant, class using the servantName attribute although this does not affect the generation of the WSDL):

<interface name="wsexamples.Greeting" servantName=
"wsexamples.GreetingImplementation"/>

Listing 20.3 shows a full wscompile configuration file that will generate the WSDL for the simple Greeting interface shown earlier.

Listing 20.3 wscompile Web Service Configuration File (config-service.xml)

<?xml version="1.0" encoding="UTF-8"?>
<configuration 
xmlns="http://java.sun.com/xml/ns/jax-rpc/ri/config">
<service 
name="GreetingService" 
targetNamespace="urn:J2EE21Examples"
typeNamespace="urn:J2EE21ExamplesTypes"
packageName="wsexamples">
<interface name="wsexamples.Greeting" servantName=
"wsexamples.GreetingImplementation"/>
</service>
</configuration>

You define which artifacts you want wscompile to generate using command-line options. Once you have created the configuration file shown in Listing 20.3, you can use wscompile to generate the WSDL description and mapping file for the Greeting service.

Under Microsoft Windows:

wscompile -define -classpath %CLASSPATH%;classes -nd ws\generated –mapping
 ws\

generated\mapping.xml ws\config-service.xml

Under Unix:

wscompile -define -classpath $CLASSPATH:classes -nd ws/generated –mapping
 ws/

generated/mapping.xml ws/config-service.xml

The line shown assumes that the compiled classes for Greeting and GreetingImplementation reside in the classes subdirectory and that the configuration file is in the ws subdirectory. The –define flag indicates that you want just the service definition at the moment (no server or client artifacts), the –nd flag indicates that the resultant WSDL file should be placed in the ws/generated subdirectory, and the –mapping flag indicates where the generated mapping file is to be saved.

The code for all of today's examples is on the Web site that accompanies this book. You will find them in the examples directory for Day 20. With the code supplied on the accompanying Web site, you can use the following Ant command to build the supplied Greeting service, which includes the creation of the WSDL and the mapping file:

asant build