JAX-RPC

The Java API for XML-based RPC (JAX-RPC) specification enables you to develop SOAP-based interoperable and portable web services and web service clients. JAX-RPC 1.1 provides core APIs for developing and deploying web services on a Java™ platform and is a part of the Web Services for Java Platform, Enterprise Edition (Java EE) platform. The Java EE platform enables you to develop portable web services.

WebSphere® Application Server implements JAX-RPC 1.1 standards.

The JAX-RPC standard covers the programming model and bindings for using Web Services Description Language (WSDL) for Web services in the Java language. JAX-RPC simplifies development of web services by shielding you from the underlying complexity of SOAP communication.

On the surface, JAX-RPC looks like another instantiation of remote method invocation (RMI). Essentially, JAX-RPC enables clients to access a web service as if the web service was a local object mapped into the client's address space even though the web service provider is located in another part of the world. The JAX-RPC is done by using the XML-based protocol SOAP, which typically rides on top of HTTP.

JAX-RPC defines the mappings between the WSDL port types and the Java interfaces, as well as Java language and Extensible Markup Language (XML) schema types.

A JAX-RPC web service can be created from a JavaBeans or a enterprise bean implementation. You can specify the remote procedures by defining remote methods in a Java interface. You only need to code one or more classes that implement the methods. The remaining classes and other artifacts are generated by the web service vendor's tools. The following is an example of a web service interface:
package com.ibm.mybank.ejb;
import java.rmi.RemoteException;
import com.ibm.mybank.exception.InsufficientFundsException;
/**
	* Remote interface for Enterprise Bean: Transfer
	*/
public interface Transfer_SEI extends java.rmi.Remote {
			public void transferFunds(int fromAcctId, int toAcctId, float amount)
						throws java.rmi.RemoteException;

}
The interface definition in JAX-RPC must follow specific rules:
  • The interface must extend java.rmi.Remote just like RMI.
  • Methods must create java.rmi.RemoteException.
  • Method parameters cannot be remote references.
  • Method parameter must be one of the parameters supported by the JAX-RPC specification. The following list are examples of method parameters that are supported. For a complete list of method parameters see the JAX-RPC specification.
    • Primitive types: boolean, byte, double, float, short, int and long
    • Object wrappers of primitive types: java.lang.Boolean, java.lang.Byte, java.lang.Double, java.lang.Float, java.lang.Integer, java.lang.Long, java.lang.Short
    • java.lang.String
    • java.lang.BigDecimal
    • java.lang.BigInteger
    • java.lang.Calendar
    • java.lang.Date
  • Methods can take value objects which consist of a composite of the types previously listed, in addition to aggregate value objects.

A client creates a stub and invokes methods on it. The stub acts like a proxy for the web service. From the client code perspective, it seems like a local method invocation. However, each method invocation gets marshaled to the remote server. Marshaling includes encoding the method invocation in XML as prescribed by the SOAP protocol.

The following are key classes and interfaces needed to write web services and web service clients:
  • Service interface: A factory for stubs or dynamic invocation and proxy objects used to invoke methods
  • ServiceFactory class: A factory for Services.
  • loadService

    The loadService method is provided in WebSphere Application Server Version 6.0 to generate the service locator which is required by a JAX-RPC implementation. If you recall, in previous versions there was no specific way to acquire a generated service locator. For managed clients you used a JNDI method to get the service locator and for non-managed clients, you were required to instantiate IBM's specific service locator ServiceLocator service=new ServiceLocator(...); which does not offer portability. The loadService parameters include:

    • wsdlDocumentLocation: A URL for the WSDL document location for the service or null.
    • serviceName: A qualified name for the service
    • properties: A set of implementation-specific properties to help locate the generated service implementation class.
  • isUserInRole
    The isUserInRole method returns a boolean indicating whether the authenticated user for the current method invocation on the endpoint instance is included in the specified logical role.
    • role: The role parameter is a String specifying the name of the role.
  • Service
  • Call interface: Used for dynamic invocation
  • Stub interface: Base interface for stubs

If you are using a stub to access the web service provider, most of the JAX-RPC API details are hidden from you. The client creates a ServiceFactory (java.xml.rpc.ServiceFactory). The client instantiates a Service (java.xml.rpc.Service) from the ServiceFactory. The service is a factory object that creates the port. The port is the remote service endpoint interface to the web service. In the case of DII, the Service object is used to create Call objects, which you can configure to call methods on the Web service's port.

For a complete list of the supported standards and specifications, see the web services specifications and API documentation.