Java API for XML-based RPC (JAX-RPC): A Primer

Introduction

The RPC (Remote Procedure Call) mechanism enables a remote procedure call from a client to be communicated to a remote server. An example use of an RPC mechanism is in a distributed client/server model. A server defines a service as a collection of procedures that are callable by remote clients. A client calls procedures to access service defined by the server.

In XML-based RPC, a remote procedure call is represented using an XML based protocol. The SOAP 1.1 specification defines an XML based protocol for exchange of information in a decentralized, distributed environment. SOAP defines a convention for representation of remote procedure calls and responses. This is in addition to the definition of the SOAP envelope and encoding rules

An XML based RPC server application can define, describe and export a web service as an RPC based service. WSDL (Web Service Description Language) specifies an XML format for describing a service as a set of endpoints operating on messages. An abstract description of such service can be bound to an XML based protocol and underlying transport. A service client invokes an RPC service.

This article describes the Java API for XML-based RPC (JAX-RPC) in more detail. JAX-RPC is being worked on under the Java Community Process as the JSR-101.

JAX-RPC: Concepts

Service Definition

A JAX-RPC service endpoint is defined and deployed using the Java platform. A JAX-RPC service endpoint is capable of use by service clients deployed on any platform. A JAX-RPC service endpoint definition makes no assumption that the service be only used by a Java-based service client. The converse is also true. A Java service client is capable of invoking an XML-based RPC service endpoint deployed on any non-Java platform.

We illustrate an example stock quote service endpoint that defines and implements the following Java interface.

Service Definition Interface: StockQuoteProvider
package com.example;
public interface StockQuoteProvider extends java.rmi.Remote {
    public float getLastTradePrice (String tickerSymbol) throws java.rmi.RemoteException;
    // .. Other remote method
}

In this example, the stock quote service endpoint definition starts with a Java interface as shown in the above code example. This interface is called a service definition interface. Note that the service developer could have started from the stock quote service description in a WSDL document and mapped it to the corresponding Java service definition interface. JAX-RPC specifies the standard mapping of the WSDL definitions to Java representation and mapping of the XML data types to the Java types. JAX-RPC also specifies the standard mapping from the Java definitions to the XML and WSDL definitions.

A JAX-RPC service endpoint can be realized (or implemented) using the Java 2 Platform, Enterprise Edition (J2EE) component model. This example uses a stateless session bean for realizing the stock quote service. A servlet based endpoint is another possible implementation of a JAX-RPC service endpoint

JAX-RPC specifies the service endpoint model for a JAX-RPC service developed and deployed on a servlet container based JAX-RPC implementation. The JAX-RPC also specifies the Java 2 Platform, Standard Edition (J2SE) based service endpoint model. The JAX-RPC specification does not specify the service endpoint model for a JAX-RPC service developed using the Enterprise JavaBeans (EJB) component model. The EJB endpoint model for JAX-RPC services would be specified in the JSR-109 and EJB 2.1 specifications.

Service Deployment

Once a JAX-RPC service endpoint has been defined and implemented, the JAX-RPC deployer deploys the service on a server-side container based JAX-RPC runtime system. The deployment step depends on the type of component that has been used to realize a JAX-RPC service endpoint.

The example stock quote service endpoint is realized as a stateless session bean and is deployed on an EJB container. The deployment step includes the generation of container specific artifacts based on the service definition interface. A container provided deployment tool provides support for the deployment of the JAX-RPC service endpoints.

During the deployment of a JAX-RPC service endpoint, the deployment tool configures one or more protocol bindings for this service endpoint. A binding ties an abstract service endpoint definition to a specific protocol and transport. An example of a binding is SOAP 1.1 protocol binding over HTTP.

Next, the deployment tool creates one or more service endpoints for this JAX-RPC service. Each service endpoint is bound to a specific protocol and transport, and has an assigned endpoint address based on this protocol binding.

Service Description

The deployment tool exports the stock quote service as a WSDL document. The WSDL description of the stock quote service enables service clients (on any platform) to access this service and its endpoints.

A Java-to-WSDL mapping tool (typically part of a container provided deployment tool) maps the example StockQuoteProvider service definition interface to the following service description in a WSDL document:

WSDL description of the Stock Quote Service
<?xml version="1.0"?>
<definitions name="StockQuote" targetNamespace="http://example.com/stockquote.wsdl"

<xmlns:tns="http://example.com/stockquote.wsdl"
<xmlns:xsd="http://www.w3.org/2001/XMLSchema"
<xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
<xmlns="http://schemas.xmlsoap.org/wsdl/">

<message name="GetLastTradePriceInput">
  <part name="tickerSymbol" type="xsd:string"/>
</message>
<message name="GetLastTradePriceOutput">
  <part name="return" type="xsd:float"/>
</message>

<portType name="StockQuoteProvider">
  <operation name="GetLastTradePrice">
    <input message="tns:GetLastTradePriceInput"/>
    <output message="tns:GetLastTradePriceOutput"/>
  </operation>
</portType>

<binding name="StockServiceSoapBinding"
  type="tns:StockQuoteProvider">
 <soap:binding style="rpc"
  transport="http:/schemas.xmlsoap.org/soap/http">
 <operation name="GetLastTradePrice">
 <soap:operation
   soapAction="http://example.com/GetLastTradePrice"/>
 <input>soap:body use="encoded"
   namespace="http://example.com/stockquote"
   encodingStyle="http://schemas.xmlsoap.org/soap/encoding">
 </input>
 <output><soap:body use="encoded"
   namespace="http://example.com/stockquote"
   encodingStyle="http://schemas.xmlsoap.org/soap/encoding">
 </output>
 </operation>
</binding>
<service name="StockQuoteService">
 <port name="StockQuoteProviderPort"
  binding="tns:StockServiceSoapBinding">
  <soap:address location="http://example.com/StockQuoteService">
 </port>
</service>
</definitions>

In the above WSDL service description, the following are important points to note:

• The StockQuoteService includes a single port StockQuoteProviderPort with the StockServiceSoapBinding binding.


• The binding StockServiceSoapBinding binds the StockQuoteProviderPort port to the SOAP 1.1 protocol over HTTP.


• The address for the StockQuoteProviderPort port is http://example.com/StockQuoteService.


• The port type for StockQuoteProviderPort is defined as StockQuoteProvider. The StockQuoteProvider port type includes a single operation getLastTradePrice that takes a ticker symbol of the type string and returns a float as the last trade price for this ticker symbol.

Service Invocation

A service client uses a JAX-RPC service by invoking remote methods on a service endpoint. Note that a JAX-RPC service client can call a service endpoint that has been defined and deployed on a non-Java platform. The converse is also true. The XML-based RPC services are typically defined, deployed and used on heterogeneous environments and platforms. Interoperability of various JAX-RPC implementations with other vendor products is an extremely important goal for the JAX-RPC specification.

A service client uses the WSDL document (that describes the stock quote service) to import the stock quote service. A WSDL-to-Java mapping tool generates client side artifacts (includes stub class, service definition interface and additional classes) for the stock quote service and its ports. Note that a service client may use dynamic invocation interface (DII) or a dynamic proxy mechanism instead of a generated stub class to invoke a remote method on a service endpoint.

The JAX-RPC service client programming model describes how a service client looks up and invokes a remote method on a service endpoint.

The following code snippet shows an illustrative example of how a service client invokes a remote method on the imported stock quote service. This example uses a generated stub class:

Example: Invoking a Service Endpoint javax.xml.rpc.Service service = ServiceFactory.newInstance().createService(...);
com.example.StockQuoteProvider sqp = (com.example.StockQuoteProvider)service.getPort(StockQuoteProvider.class);
float quotePrice = sqp.getLastTradePrice(.ACME.);

The JAX-RPC supports creation of a dynamic proxy for invoking a service endpoint. A dynamic proxy class supports a service definition interface dynamically at runtime without requiring any code generation of a stub class that implements a specific service definition interface. The following example shows the use of a dynamic proxy for invoking an operation on the target service endpoint. Note that this example does not use any generated stub class that implements the StockQuoteProvider service definition interface:

Example: Dynamic Proxy javax.xml.rpc.Service service = ServiceFactory.newInstance().createService(...);
com.example.StockQuoteProvider sqp = (com.example.StockQuoteProvider)service.getPort(
        portName, StockQuoteProvider.class);
float price = sqp.getLastTradePrice("ACME");

The javax.xml.rpc.Call interface provides support for the dynamic invocation of an operation on the target service endpoint. The following code example shows the typical use of the dynamic invocation interface (DII) Call API.:

Example: Dynamic Invocation Interface javax.xml.rpc.Service service = ServiceFactory.newInstance().createService(...);
javax.xml.rpc.Call call = service.createCall(portName, "getLastTradePrice");
// This example assumes that addParameter and setReturnType methods are not required to be called
Object[] inParams = new Object[] {"ACME"};
Float quotePrice = (Float)call.invoke(inParams);

Summary

This article provided a brief introduction to the JAX-RPC 1.0. We covered the basic concepts in the JAX-RPC model for defining, deploying, describing and invoking a JAX-RPC service endpoint.

For more details, please refer to the following:

• JAX-RPC 1.0 Specification


• The JAX-RPC Reference Implementation in the Java XML Pack