JavaEJBWorking with JAX-RPC

Working with JAX-RPC content and product recommendations are editorially independent. We may make money when you click on links to our partners. Learn More.

This is Chapter 11: Working with JAX-RPC from the book Java APIs for XML Kick Start (ISBN:0-672-32434-2) written by Aoyon Chowdhury and Parag Choudhary, published by Sams Publishing.

In This Chapter

  • JAX-RPC Working Mechanism

  • Constituents of a JAX-RPC Server and Client

  • JAX-RPC Packages

  • The javax.xml.rpc Package

  • The xrpcc Tool

  • The Types Supported by JAX-RPC

  • The CarPartRequest Web Service

  • The CarPartRequestClient Application

RPC stands for remote procedure calls. RPC is used for making procedure or function calls and receiving the responses, both over the network. During the days of procedural languages, this was the de facto method by which distributed applications communicated with each other. This often involved fairly complex socket programming to exchange data between the two remote applications.

However, the growth of object-oriented programming saw a steady decline in the use of procedural languages for business applications. It became evident that using object-oriented paradigms could result in a better return on investment (in terms of scalability, development time, and so on). So, the world of business applications moved from procedural languages to object-oriented languages, such as Java. However, this led a new level of complexity in communication between distributed applications. Methods in object-oriented languages could not only return and take as parameters simple data types, but also complex objects such as vectors. With increasing complexity, it became increasingly difficult to use RPC to represent complex objects. Another complexity stemmed from the fact that more often than not, the distributed applications are on heterogeneous systems. This means that the data exchanged between two applications written in different languages must be coded so that it can be used by these applications.

These complexities led to the gradual decline of RPC for low-level socket communications and the development of a plethora of alternative techniques. In the Java world, the primary new approach is Remote Method Invocation (RMI). Although useful in its own way, RMI has its own set of issues.

RMI is very resource-intensive because it needs to use quite a few classes. Also, JRMP, the backbone of RMI, is poor on performance. Of course, you could go ahead and write your own remote protocol, but that is not necessarily the easiest of programming tasks. Additionally, as clients make RMI calls, sockets need to be opened and maintained—this also adds to the overhead. RMI also requires that the objects that can be called be bound to a server such as LDAP, an RMI registry, or a JNDI service. RMI is Java-only. This leads to the issue that the communicating parties have to be on Java to use RMIs, which is very difficult to ensure in a heterogeneous environment like the Internet. Finally, RMI-based applications require a lot of coding effort because there are quite a number of interfaces and classes that need to be implemented. So, while RMI solved the problem of how to exchange objects, it still had its complexities in terms of performance and simplicity of use.

But how did RPC come back in fashion? The proliferation of the Internet and the emergence of XML gave rise to the possibility of using XML as an RPC mechanism. The fall of RPC was primarily for two reasons: the necessity of using socket programming to provide a transport mechanism for data, and the difficulty in representing complex objects. The ubiquity of the Internet meant that almost every imaginable system had support for HTTP, so it could be used as the transport mechanism of choice. The rise of XML ensured that it was possible to textually describe objects in a standard way that could be understood by all systems, regardless of the environments and languages. The XML-based SOAP specification provides the necessary standard mechanism by which to use RPC. In this chapter, you will learn about the JAX-RPC mechanism of using XML-RPC, as well as how to use APIs defined in the JAX-RPC specification to create a Web service and a client.

JAX-RPC Working Mechanism

JAX-RPC uses SOAP and HTTP to do RPCs over the network. The SOAP specification defines the necessary structure, encoding rules, a convention for doing RPCs, and its corresponding responses. The RPCs and responses are transmitted over the network using HTTP as the primary transport mechanism.

From an application developer's point of view, an RPC-based system has two aspects: the server side (the Web service) and the client side. The Web service exposes the procedures that can be executed, and the client does the actual RPC over the network.

As discussed in earlier chapters, a Web service environment is based on open standards such as SOAP, HTTP, and WSDL. It is therefore possible that a Web service or a client wasn't developed using the Java platform. However, JAXR-RPC provides the mechanism that enables a non-Java client to connect to a Web service developed using Java platform, and vice versa. This chapter will focus on the development of a Web service and a client using JAX-RPC.

Figure 11.1
Communication exchange between a JAX-RPC client program and a Web service.

Before we discuss the communication exchange process, you need to understand what stubs and ties are. Stubs are local objects that represent the remote procedures. Ties are classes that reside on the server and enable communication with the client.

It is assumed that the client is aware of the Web service and the remote procedure that it can execute on the Web service. This is what happens:

  1. The client calls the method on the stub that represents the remote procedure.

  2. The stub executes the necessary routines on the JAX-RPC runtime system.

  3. The runtime system converts this method call into a SOAP message and transmits the message to the server as an HTTP request.

  4. The server, upon receipt of the SOAP message, invokes the methods on the JAX-RPC runtime. The JAX-RPC runtime converts the SOAP request into a method call.

  5. The JAX-RPC runtime then calls the method on the tie object.

  6. Finally, the tie object calls the method on the implementation of the Web service.

  7. The response to the RPC call is sent in a SOAP response message as an HTTP response.

Now let's look at the physical implementation of a JAX-RPC-based server and client.

Constituents of a JAX-RPC Server and Client

Figure 11.2 shows the physical implementation of a JAX-RPC-based system.

Figure 11.2
Physical implementation of a JAX-RPC-based system.

A JAX-RPC-based system has the following constituents:

  • The Web service

  • The container in which the Web service is located

  • The ties

  • The WSDL file

  • The client application

  • The stubs

  • The JAX-RPC runtime classes

The Web service is represented by two files: the service definition interface, and the corresponding implementation class. The service definition interface and the implementation class are collectively known as the service endpoint. An application developer has to write the interface and the implementation class constituting the service endpoint. As you will see later, the service definition interface extends the Remote interface of the rmi package and declares the methods that can be executed remotely.

The service endpoint is deployed in a container-based JAX-RPC runtime system. Typically, this is either a servlet or a stateless session bean deployed on an EJB container. In this chapter, we will use the Tomcat Web server and a servlet as the container for the service endpoint.

The ties are lower-level classes that are used by the server to communicate with the client. These are created by a tool called xrpcc.bat (or, if you are a Unix user).

The xrpcc tool also creates the WSDL file. A WSDL file is an XML document that describes the remote procedure call in a platform-independent way. This file enables the Web service to be accessible by clients, even if they are not on the Java platform. As an application developer, you need to run the xrpcc tool to generate the ties and the WSDL document. The WSDL document defines the parameters that a method can take, as well as the method's return value, which is expressed as an XML schema definition (XSD) data type. The JAX-RPC mechanism provides a direct mapping of these XSD data types to Java language types. For example, if a procedure returns a String value, then the WSDL document will describe the return type as xsd:string. Similarly, if a WSDL document declares that a method can take an xsd:dateTime type as parameter, then the JAX-RPC mechanism maps that to the Calendar data type in the Web service. As a developer, you won't need to worry about these mappings, because they are handled automatically by the xrpcc tool.

The client application is the application that makes the remote procedure call on the Web service. As an application developer, you need to create the application program.

The stubs are the local objects that represent the remote service. You can create the stubs by using the xrpcc tool.

In some scenarios, it's possible that the client is not aware of the signature of the remote procedure or the name of the service until runtime. To handle such cases, the client can use the dynamic invocation interface (DII). A client that uses the dynamic invocation interface does not use static stubs. A client that uses the DII is also more complex to code and implement than clients that use static stubs.

The JAX-RPC runtime classes are provided with the reference implementation.

Now let's look at the packages that make up the JAX-RPC environment.

JAX-RPC Packages

The JAX-RPC specification defines the following packages:

  • javax.xml.rpc

  • javax.xml.rpc.encoding

  • javax.xml.rpc.handler

  • javax.xml.rpc.handler.soap

  • javax.xml.rpc.holders

  • javax.xml.rpc.server

  • javax.xml.rpc.soap

Of all these packages, the one that you need to be concerned about as an application developer is the javax.xml.rpc package. It contains the interfaces that you will be using while developing the clients that use JAX-RPC mechanisms to perform remote procedure calls.

The classes of the other packages are used by the JAX-RPC runtime, or by xrpcc to generate stubs, ties, and the WSDL document.

The javax.xml.rpc Package

The javax.xml.rpc package contains the three interfaces, two classes, and two exceptions that you will use for developing JAX-RPC-based clients.

The javax.xml.rpc Interfaces

The interfaces in the javax.xml.rpc package are as follows:

  • Call—The Call interface is used by a client that uses the DII to call a remote procedure. The Call interface provides a number of methods with which a client can access the remote procedures.

  • Service—The Service interface is essentially used as a factory to create instances of the Call interface.

  • Stub—The Stub interface is the base interface for the stub classes. Instances of the stub classes represent the procedures at the server. A client calls the method on a stub, and it is up to the stub to take up the remote procedure call from then on.

The javax.xml.rpc Classes

The classes in the javax.xml.rpc package are as follows:

  • ServiceFactory—The ServiceFactory is an abstract factory class that enables you to create instances of the Service interface.

  • NamespaceConstants—The NamespaceConstants class contains the constants that are used in JAX-RPC for namespace prefixes and URIs. For example, the NSPREFIX_SCHEMA_XSD represents the namespace prefix for the XML schema XSD.

  • ParameterMode—The ParameterMode class is an enumeration for parameter mode. It defines three constants that determine whether the parameter is of IN, OUT, or INOUT type. This class is used in the addParmeter(..) methods of the Call interface to determine the type of parameter that is being added.

The javax.xml.rpc Exceptions

The exceptions in the javax.xml.rpc package are as follows:

  • JAXRPCException—The JAXRPCException is thrown when the JAX-RPC runtime fails to operate as expected.

  • ServiceException—The ServiceException is thrown when the methods of the Service interface or the ServiceFactory class fail to execute as expected.

Now let's take a detailed look at the xrpcc tool.

The xrpcc Tool

The xrpcc tool creates the following for you:

  • The stubs and ties.

  • A server configuration file. This file is not part of the JAX-RPC specification as such, but it is used by the Tomcat Web server.

  • If the Web service is a JAX-RPC implementation, the xrpcc tool generates the WSDL document describing the Web service from the RMI interface.

  • If the Web service is not a JAX-RPC implementation, you can use the xrpcc tool to generate the RMI interfaces that your JAX-RPC client can use to connect to the Web service. The xrpcc tool will use the WSDL file to generate the RMI interfaces.

To generate these files, the xrpcc tool reads a configuration XML file called config.xml. Depending on whether you start with the RMI interface or the WSDL document, the config.xml file will differ. Let's look at both of the syntaxes. Later on in the chapter, you will see an actual implementation of the config.xml file for the sample CarPartRequest Web service that you will create.

The config.xml File Syntax When Starting with RMI Interfaces

When starting with RMI interfaces, the config.xml file should have the following syntax:

<?xml version="1.0" encoding="UTF-8"?>
<configuration xmlns="">
 <service name="Name of the service"
     packageName="Package name that stores the web service classes"
     targetNamespace="Target namespace of the generated WSDL document"
     typeNameSpace="Target namespace for the schema portion of the generated 
WSDL document"
  <interface name="name of the service endpoint interface"
     servantName="Implementation class for the endpoint interface"
     soapAction="(Optional)String to be used as the SOAP action
for all operations in the corresponding port"
     soapActionBase="(Optional) Prefix for SOAPAction string">
User defined type mapping of Java to WSDL

After the mandatory XML declaration and namespace definition line, the configuration file begins with the service element. This element defines the name of the Web service and the package name. The name parameter takes the service name. This information is used when generating the WSDL document for the Web service. The value of the name parameter is used as the name of the WSDL document. It is also used as the value of the name parameter of the definitions element of the WSDL document. The targetNamespace and typeNamespace parameters define where the generated WSDL file and its schema definition will be hosted. The interface element describes the interfaces exposed by the Web service and the implementation class of the interface.

The config.xml file can have only one service element. However, depending on the number of Web services and the interfaces exposed by each of the Web services, there can be multiple interface elements.

The typeMappingRegistry element provides the mechanism to define your own type mappings between XML schema types and Java types. This is an optional entry.

The config.xml File Syntax When Starting with a WSDL Document

When starting with a WSDL document, the config.xml file should have the following syntax:

<?xml version="1.0" encoding="UTF-8"?>
<configuration xmlns="">
   location="URL to the WSDL document"
   packageName="Name of the package for the generated interfaces and 
implementation classes">
WSDL to Java type mapping information

The wsdl element defines the URL address to the WSDL document, and the package name in which the generated stubs, ties, and RMI interfaces will be created when the xrpcc tool is run.

The optional element typeMappingRegistry enables you to define your own type mappings between XML schema data types and Java types.

The Types Supported by JAX-RPC

As you learned previously, the xrpcc tool automatically creates the mapping between the Java types and the XML data types used in the WSDL document. However, not all Java types are directly supported by the JAX-RPC mechanism. Therefore, you need to know the Java types that are supported by the JAX-RPC.

The JAX-RPC specification ensures support for a number of J2SE classes and primitive data types, user-defined classes, and Java beans. The specification also provides a mechanism to support the classes that are not directly supported by JAX-RPC. We'll examine each of them now in greater detail.

Java Types Support

The Java types supported by JAX-RPC are a combination of J2SE classes and primitive data types:

  • String

  • Boolean

  • Byte

  • Double

  • Float

  • Integer

  • Long

  • Short

  • BigDecimal

  • BigInteger

  • Calendar

  • Date

  • boolean

  • byte

  • double

  • float

  • int

  • long

  • Arrays of these classes and primitive types

Application Classes

In addition to these J2SE classes and primitive data types, JAX-RPC also provides support for the application classes of your application. For example, you might have a Java application dealing with car parts inventory. In the application, you might have classes such as EngineSpecs, EngineOrder, and so on. You can use such classes while developing Web services; they're called value types in the JAX-RPC specification. However, for a Java class to be supported by the JAX-RPC specification, it must follow the following rules:

  • It must have a public default constructor.

  • It must not implement (directly or indirectly) the java.rmi.Remote interface. However, other than the java.rmi.Remote interface, it can implement any other interface or extend other Java classes.

  • It can contain public, private, protected, and package-level fields. However, for the value of a public field to be passed, it must be a supported JAX-RPC type as specified earlier, and should not be final or transient.

  • It may contain any type of methods.

  • It may contain static or transient fields.

  • If the Java class is a JavaBean component, it must have the getter and setter methods defined for each of the bean properties. Additionally, the bean properties must consist of the data types supported by JAX-RPC.

Unsupported Java Classes

There are several classes, such as the classes of the Java Collections Framework, that are not directly supported by JAX-RPC. However, the specification provides a method by which you can use pluggable serializers and deserializers to provide support for such unsupported classes. The discussion of how to provide support for these unsupported Java classes is beyond the scope of this book; for more information on this, refer to the JAX-RPC specification.

So far in this chapter, you have learned about how the JAX-RPC mechanism works along with the other necessary background details. Now you will create a simple Web service and a client that performs RPCs over the Internet using JAX-RPC as the building blocks.

The CarPartRequest Web Service

The CarPartRequest Web service is a simple Web service that exposes a method called getCarPartRequest that reports the status of a specified engine type. This method takes a string specifying the name of the engine type as its only parameter, and returns a string describing the status of the engine type. A remote client of the CarPartRequest Web service will connect to the Web service and do an RPC on the getCarPartRequest method.

To create the Web service and its remote client, the following files need to be created:

  • The service definition interface file, called

  • The service definition implementation file, called

  • The config.xml file. This is the configuration file read by the xrpcc tool to generate the stubs and ties.

  • The web.xml file. This is the deployment descriptor for the Web service.

  • The file. This is the remote client that connects to the Web service and does a RPC on the getPartRequest method.

Creating the Service Definition Interface

A service definition interface is a standard J2SE interface definition file that declares the methods that a remote client can execute. A definition file has to abide by the following rules:

  • It must extend the java.rmi.Remote interface.

  • There should be no constant declarations.

  • All the methods must necessarily throw the java.rmi.RemoteException or one of its subclasses. Additionally, the methods can also throw service-specific exceptions.

  • The parameters and return types must be the data types supported by the JAX-RPC specifications.

With the rules defined, let's now create the CarPartRequestIF service definition interface:

  1. Create an empty file called

  2. You want to put the Web service classes in a package called CarPartReq, so specify the package definition.

  3. Import the Remote and RemoteException classes.

  4. Specify the declaration for getCarPartRequest method.

Open the text editor of your choice and create an empty file called

Enter the following lines of code:

package CarPartReq;

import java.rmi.Remote;
import java.rmi.RemoteException;

public interface CarPartRequestIF extends Remote {
  public String getCarPartRequest(String s) throws RemoteException;

Next you need to define the implementation class for the service definition interface.

Creating the Service Definition Interface Implementation Class

The implementation class will basically define the getCarPartRequest method. The method takes the name of the engine as its only parameter. If the engine name is Engine 1, the getCarPartRequest method should report that Engine 1 is out of stock. For all other engine types, it should say that the engine has been shipped.

To create the implementation class, select the text editor of your choice and create a file called In that file, enter the following lines of code:

package CarPartReq;

public class CarPartRequestImpl implements CarPartRequestIF {

  public String getCarPartRequest(String s) {

    if (s.equals("Engine 1"))
      return new String("Engine 1 is currently out of stock");

      return new String("Your requested engine
 is in stock. It will be shipped shortly");

Now you need to create the config.xml file.

Creating the config.xml File

As mentioned earlier, the config.xml file is the configuration file that the xrpcc tool reads to create the stubs, ties, and the WSDL document for the Web service. To create the config.xml file, select a text editor and create a file called config.xml. In that file, enter the following lines of code:

<?xml version="1.0" encoding="UTF-8"?>
  <service name="CarPartRequest"
   <interface name="CarPartReq.CarPartRequestIF"

Let's take a closer look at this file. The name parameter of the service element is CarPartRequest. The xrpcc tool will use this name as the prefix to the implementation class file that is generated when you run the xrpcc tool for creating stubs and ties. This implementation class file is different from the one that you created earlier. The value of the packageName parameter is the name of the package of the classes generated by xrpcc. This should match the package name that you specified in the service definition interface and its corresponding implementation class.

The value in the name parameter of the interface element is the fully qualified name of the service definition interface, which is CarPartReq.CarPartRequestIF in this case. The value of the servantName parameter has to be the fully qualified name of the implementation class of the service definition interface.

Now let's generate the stubs, ties, and the WSDL document:

  1. Generate the class file for the Web service definition (compile the file).

  2. Generate the class file for the Web service definition implementation (compile the file).

  3. Run the xrpcc tool to generate the stubs, ties, and the WSDL document.

To generate the class file for the Web service definition interface, enter the following line of code at the command prompt:

javac -d .

To generate the class file for the service definition interface implementation, enter the following line of code at the command prompt:

javac -classpath .

Next you need to run the xrpcc tool. This will generate the stubs, ties, and the WSDL file for the Web service. To run the xrpcc tool, enter the following command at the command prompt:

xrpcc -both -classpath . -d . config.xml

The -both option creates the stubs, ties, and the WSDL document describing the Web service. The following files will be created under the CarPartReq folder:

  • CarPartRequest.class

  • CarPartRequestIF.class

  • CarPartRequestIF_Stub.class

  • CarPartRequestIF_Tie.class

  • CarPartRequestImpl.class

  • CarPartRequest_Impl.class

  • CarPartRequest_SerializerRegistry.class

  • CarPartRequestIF_GetCarPartRequest_RequestStruct.class

  • CarPartRequestIF_GetCarPartRequest_RequestStruct_SOAPSerializer.class

  • CarPartRequestIF_GetCarPartRequest_ResponseStruct.class

  • CarPartRequestIF_GetCarPartRequest_ResponseStruct_SOAPSerializer. class

Additionally, it will also create the file in the location where you ran the xrpcc tool. As you will see shortly, the file is read by the deployment descriptor (web.xml) file while loading the Web service.

Next you will create the web.xml file for the Web service.

Creating the web.xml File

The web.xml file is an XML file that provides configuration information about a Web application to the Web server. Because the Web service you are creating is installed as a servlet, the deployment descriptor will contain information pertaining to the Web service.

To create the deployment descriptor, create an empty file called web.xml. In the web.xml file, enter the following lines of code:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE web-app
  PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN"
  <description>Car Parts Order System</description>
   <description>Servlet to handle Car Part Request</description>

Let's look at the parts of the web.xml file that pertain to the CarPartRequest Web service. The value of the servlet-class element refers to the servlet that can support the JAX-RPC-based Web service. For this example, you'll use the servlet that's shipped with the reference implementation. The value of the init-param element is the file that was generated by the xrpcc tool.

Next the url-pattern element of the web.xml file determines the URL of the service's endpoint. Finally, you put a timeout of 60 seconds if the Web service fails to respond within that time.

Deploying the Web Service

Next you need to install the Web service on the Web server. To do so, create a folder called CarPartRequestApp. In the CarPartRequestApp folder, create a folder called WEB-INF. Inside the WEB-INF folder, copy over the web.xml and the files and create a folder called classes. In the classes folder, copy over the CarPartReq folder that was created when you compiled the Web service interface and definition files and ran the xrpcc tool. Your directory structure should now look like the one shown in Figure 11.3.

Figure 11.3
The directory structure for the CarPartRequest Web service.

After the files are copied over, you will create a Web application archive WAR file and deploy it with Tomcat. To create the WAR file, go to the CarPartRequestApp folder and enter the following command at the command prompt:

jar cvf CarPartRequest.war *

This will create the Tomcat-deployable Web application archive for you. To run the Web service, copy the CarPartRequest.war file into the webapps folder.

Now start up Tomcat. Next launch a Web browser and go to http://localhost:8080/CarPartRequest/jaxrpc to verify the installation.

The browser should show the contents as displayed in Figure 11.4.

Figure 11.4
The CarPartRequest Web service.

Let's summarize what has been done so far. You created the Web service endpoint interface and its implementation class. Then you created the configuration file for the xrpcc tool. After that, you compiled the service endpoint interface and its implementation class, and ran the xrpcc tool to generate the stubs, ties, and WSDL document. Finally, you created the Web application archive for the CarPartRequest Web service and deployed it in the Tomcat Web server.

Now you will create the client application for the CarPartRequest Web service.

The CarPartRequestClient Application

The CarPartRequestClient application will connect to the Web service and execute the remote procedure getPartRequest. The CarPartRequestClient will call the getPartRequest method through the stub. Remember that when you ran the xrpcc tool, it created the stub, CarPartRequestIF_Stub.class, and the implementation of the service, CarPartRequest_Impl.class. You can get a reference to the stub by using the getCarPartRequestIFPort method of the CarPartRequest_Impl class.

After obtaining the reference to the stub, you will use the _setProperty method to provide the URI of the service to the client application. The URI to the service will be provided as a command-line parameter.

To create the client application, create a file called In this file, enter the following lines of code:

package CarPartReq;

public class CarPartRequestClient {
  public static void main(String[] args) {
    try {
      CarPartRequestIF_Stub stub =
(new CarPartRequest_Impl().getCarPartRequestIFPort());
      System.out.println(stub.getCarPartRequest("Engine 2"));
    } catch (Exception ex) {

The code discussed so far is available in the MyJAXRPCExample folder.

Next you need to compile the client. To do so, enter the following at the command prompt:

javac -classpath .;d:jwsdp-1_0commonlibjaxrpc-ri.jar;
d:jwsdp-1_0commonlibjaxp-api.jar -d . *

This creates CarPartRequestClient.class in the CarPartReq folder.

Get the Free Newsletter!

Subscribe to Developer Insider for top news, trends & analysis

Latest Posts

Related Stories