JAX-RPC

Introduction

JAX-RPC is a Java API for XML based RPC allowing for executing methods on remote systems. Generally, it describes the relationship between SOAP 1.1, WSDL 1.1, XML and Java. The API provides both, a client and a server programming model.

Client Programming Model

In order to access a web service from a client written in Java, three APIs have been made available.

• Generated Stubs
• Dynamic Proxies
• DII (Dynamic Invocation Interface)

In this context, generated stubs, which base on the Java RMI programming model, are further discussed.

Generated Stubs

[figure]

The figure above demonstrates the procedure of accessing a web service.

1) A Client operates on a remote interface (the “endpoint interface”) to invoke a remote service 2) A Stub is generated that handles the method invocation and transforms the RPC call into an XML based protocol, such as SOAP. 3) The SOAP message is sent via HTTP (or other transport protocols). 4) The web service processes the request and sends a SOAP Response Message. 5) This SOAP message is transformed in either a value or an exception (if SOAP default is declared in the WSDL document)

As a matter of fact, a developer must not generate or parse SOAP messages. It is the JAX-RPC runtime system that converts the APIs calls and responses to and from SOAP messages.

The role of WSDL

Both, endpoint interface and stub, rely on the WSDL document which needs to be at the client’s disposal. Whereas the JAX-RPC compiler receives the necessary information for generating the endpoint interface in the <portType> and <message> pieces of the WSDL document, it can find the data for the stub in the <binding> and <port> part.

The endpoint interface

The endpoint interface serves as the remote interface extending java.rmi.Remote. Each methods throws a java.rmi.RemoteException.

In order to express the data types of the XML based definition in the Java programming language JAX-RPC provides a mapping. For instance, xsd:string is mapped to the java.lang.String class. Furthermore, the compiler is also able to map nillable and complex types. Thus, certain Java datatypes such as char can not be mapped.

WSDL document:

<message name ="reservationRequest">
    <part name ="name" type="xsd:string"/>
    <part name ="idNumber" type="xsd:string"/>
    <part name ="date" type = "xsd:dateTime"/>
    <part name ="carType" type = "xsd:string"/>
    <part name ="price" type = "xsd:float"/>
</message> 
<message name = "reservationResponse">
    <part name = "param2" type="xsd:int"/>
</message>
<portType name = "TaxiProcessor">
   <operation name = "book">
     <input message = "reservationRequest"/>
     <output message = "tns:reservationResponse"/>
   </operation>
</portType>

Endpoint Interface:

public interface TaxiProcessor extends java.rmi.Remote {
  public int book (String name, String idNumber, java.util.Calendar date,
  String carType, float price)
  throws java.rmi.RemoteException;
}

The stub

The stub converts the method invocation on the endpoint interface into a SOAP message. Therefore it needs the <binding> piece of the WSDL element. This part provides the messaging style, the operation name, and the encoding style to use in the SOAP message body. Additionally, the port part describes the location of the Web Service, so that the compiler can generate the specific stub.

The service interface

The service interface can be compared to the home interface. Unlike the stub and the endpoint interface, which are generated at deployment time, the service interface is generated at runtime. Its purpose is to get an instance of the generated stub. Therefore, it provides methods helping to obtain the stub.

How does EJB use JAX-RPC generated stubs?

Bound to a specific namespace, the EJB obtains a reference to a resource factory from JNDI ENC. It receives the service interface and invokes its “getStub” method to get an instance of the stub. Finally it can use the stub to invoke the web service’s operations.

...
public class TaxiAgentBean implements javax.ejb.SessionBean {
...
// obtain a reference to a resource factory from JNDI ENC
TaxiProcessorService webService = (TaxiProcessorService) jndiContext.lookup(
„java:comp/env/service/TaxiProcessorService“);
// get the stub
Processor endpointStub = webService.getProcessorPort();
... /any code
// use stub to invoke operations on web service
endpointStub.book(customerName, idNumber ,date, carType, price);
...
}