Getting Started with JAX-RPC

Print-friendly Version

Java APIs for XML-based Remote Procedure Call (JAX-RPC) help with Web service interoperability and accessibility by defining Java APIs that Java applications use to develop and access Web services. JAX-RPC fully embraces the heterogeneous nature of Web services -- it allows a JAX-RPC client to talk to another Web service deployed on a different platform and coded in a different language. Similarly, it also allows clients on other platforms and coded in different languages to talk to a JAX-RPC service. JAX-RPC also defines the mapping between WSDL service descriptions and Java interfaces.

This article introduces the JAX-RPC technology and describes its client and server programming models. JAX-RPC hides the complexity of underlying protocols and message-level processing from application developers crafting Web services using the Java 2 platform. The API combines XML with Remote Procedure Call (RPC), which is a mechanism enabling clients to execute procedures on distributed or remote systems, so that developers can build Web services and clients. The JAX-RPC remote procedure calls  are represented by an XML infoset and they are carried over a network transport. While the JAX-RPC APIs  rely on a XML-based protocol and a network transport, the APIs themselves are independent of a specific protocol or transport. The current JAX-RPC implementation relies on the SOAP 1.1 protocol and HTTP 1.1 network transport.

SOAP and WSDL are language-neutral standards defined by the World Wide Web Consortium (W3C). SOAP is a lightweight, XML-based protocol for exchange of information in a decentralized, distributed environment. The core of this protocol is a SOAP envelope. The envelope defines a framework for describing what is in a message and how to process it. SOAP defines a set of encoding rules for expressing instances of application-defined data types. It defines a convention for representing RPC requests and responses. The SOAP specification also defines a transport-binding framework for exchanging messages using an underlying protocol.

WSDL specifies an XML format for describing a Web service as a set of endpoints operating on messages. The operations and messages are defined abstractly and then bound to a concrete network protocol (HTTP) and a message format (SOAP) to define an endpoint (or port). Related ports are combined into abstract endpoints, also called services. WSDL describes the Web service in a standard format: it specifies the service's location and the operations exposed by the port in the service. The JAX-RPC reference implementation, available in the Java Web Services Developer Pack Early Access 2 (JWSDP EA2) release, includes a tool that can parse existing WSDL files or generate WSDL files for a Web service.

An Example Application: SunReg Web Service

This article uses an example enterprise Web service to illustrate the JAX-RPC concepts and programming models. This enterprise Web service, called SunReg, allows employees in an organization to inquire about and register for various courses offered by their internal education center. SunReg allows employees to send queries about the courses offered by the education center. The Web service provides the employee with information about each course, such as course description, the campus where the course is conducted, and the duration of the course. Employees can also use SunReg to enroll in specific courses of their interest. The employee and course information is stored in a database. Figure 1 shows a use case diagram for the SunReg Web service.

The SunReg application exposes these functions as Web services to all employees of the organization. Employees access the Web service using browser-based clients, such as applets or Java applications. In addition, a client on a different platform can access the Web service using a different language. This kind of interoperability is achieved because JAX-RPC adheres to SOAP 1.1 and WSDL 1.1 standards.

Figure 1. The SunReg Web service allows users to look for a course and register for a course.

SunReg is developed, deployed, and published as a JAX-RPC Web service endpoint. Once developed, an endpoint is deployed in a container that supports the JAX-RPC runtime system, which in turn supports the underlying XML-based protocol and transport. The Web service endpoint can be a servlet-based endpoint deployed on a servlet container or a stateless session bean. JWSDP provides Tomcat as the servlet container, which is what we used for the SunReg Web service endpoint. JWSDP also provides a Java-to-WSDL mapping tool that can publish the service description along with the endpoint.

Once the service is deployed and published, clients import the WSDL and typically use the WSDL-to-Java mapping tool to generate client-side artifacts for invoking this service endpoint.

A Note About Software Versions Used in This Example

In this article, we use the JAX-RPC reference implementation that comes bundled with JWSDP EA2 for developing and deploying our Web service. The JAX-RPC implementation in JWSDP EA2 is based on the 0.7 version of the specification. The code examples in this article are compatible with the JWSDP EA2 release, current at this writing. The JWSDP first customer release, currently planned for mid-June, will incorporate the latest revisions of the JAX-RPC specification. The code samples here will need an update at that time; look for updates or advice about migrating applications on this Web site about that time.

Also note that we refer to the JWSDP installation directory as JWSDP_HOME through out this article.

Developing a Service

As noted already, a JAX-RPC service endpoint represents a Web service endpoint. When you're ready to create a service endpoint, you:

• Write only two classes. One class exposes the service method signatures and the other class provides the method implementations.
• Define an XML configuration file that contain instructions to generate various client-side and server-side artifacts required by JAX-RPC. This configuration file is consumed by the Java-to-WSDL mapping tool.
• Define a web.xml file that specifies the deployment descriptor for service deployment in a servlet container.

Coding the Service Endpoint Interface

You start by defining two classes. First you define the class that represents the remote interface to the service; this is the service endpoint interface. It contains the signatures for the methods that a client may invoke on the service. The service endpoint interface extends the java.rmi.Remote interface, and its methods must throw the java.rmi.RemoteException. Although each method can throw a service-specific exception, to keep the application simple we do not include them in the examples with this article.  Code Sample 1 shows code for the service endpoint interface for SunReg, named SunRegPort.

Code Sample 1: The service endpoint interface, SunRegPort

public interface SunRegPort implements java.rmi.Remote {
     public Course[] getCourseInfo() throws 
         RemoteException;
     public void registerCourseInfo(Employee emp, 
         Course[] courseArray)
             throws RemoteException;
}

As required, the service endpoint interface, SunRegPort, implements the java.rmi.Remote interface. It provides two methods: getCourseInfo and registerCourseInfo.

Employees use getCourseInfo to obtain information about the courses available in the education center. It's possible to add as a convenience method, a second, overloaded getCourseInfo method that offers an optional search criteria.

Employees use the registerCourseInfo method to sign up for courses they have selected. You can set up registerCourseInfo to throw a service-specific exception to indicate if the employee is not allowed to register for a particular course.

The classes Employee and Course in Code Sample 1 describe the Employee and Course entities in this Web service. These classes are defined as JAX-RPC value types. Figure 2 shows the details of the two classes.

Figure 2: Course and Employee JAX-RPC Value types

Course and Employee value types are defined according to the JavaBeans pattern defined by the JAX-RPC specification. All the member variables of the value types are declared as private. The data type of each member variable is a JAX-RPC-supported data type. Each member variable has a getter and setter method as defined by the JavaBeans design pattern.

Coding the Service Endpoint Class

The service endpoint class provides an actual implementation of the methods defined in the service endpoint interface. (You can also call a service implementation class a servant, as we do later in this article.) Code Sample 2 shows the service implementation class for SunRegPort, named SunRegImpl.

Code Sample 2: The service implementation class SunRegImpl

import java.xml.rpc.server.ServiceLifecycle;

public class SunRegImpl implements SunRegPort, 
    ServiceLifecycle {
    Connection dbConnection = null;
    public void init(Object context) {
       String dbUrl =
   ((ServletContext)context).getInitParameter("dbUrl");
      dbConnection = DriverManager.getConnection(dbUrl);
      //other relevant code
   }
      public void destroy() {
      //release the database connection
   }
   public Course[] getCourseInfo() {
   //get course information using the database 
   //connection
   }
   public void registerCourseInfo(Employee emp, 
       Course[] courseArray) {
      //register for the course information using 
      //the database connection
   }
}

The SunRegImpl class contains the implementations for the methods getCourseInfo and registerCourseInfo. (Code Sample 2 does not show those two method implementations because they are relevant only to the application.) SunRegImpl also extends the java.xml.rpc.server.ServiceLifecycle interface, which is an important part of defining a service.

Through the implementation of the ServiceLifecycle interface, the JAX-RPC runtime system manages the life cycle of the service endpoint objects. SunRegImpl implements the init and destroy methods inherited from the ServiceLifecycle interface. The JAX-RPC runtime system invokes the init method for the initialization of the service endpoint object. The service endpoint uses the init method to initialize its configuration and set up access to any external resources. The context parameter in the init method enables the endpoint to access the endpoint context provided by the underlying JAX-RPC runtime system. The JAX-RPC runtime invokes the destroy method when it determines that the service endpoint object no longer handles remote invocations.

For example, SunReg can use the context passed in the init method to obtain a handle to an external resource. In SunRegImpl in Code Sample 2, notice that the init method obtains a handle to a database. External resources, such as databases and so forth, are defined in the associated web.xml file, as we explain later in the section Defining the Deployment Descriptor.

Defining the Configuration File

Next, you need to define a configuration file to generate the various server-side artifacts required by the JAX-RPC runtime. This configuration file specifies the name of the service (or services) and its endpoint interface and class. This configuration file, called config.xml in our case and shown in Code Sample 3, follows the JAX-RPC specification, but is also specific to the particular JAX-RPC implementation. While its syntax may vary from one implementation to another, the configuration file contains the information required by the xrpcc tool.

Code Sample 3: The configuration file for SunReg

<?xml version="1.0" encoding="UTF-8"?>
<configuration xmlns="http://java.sun.com/jax-rpc-ri/xrpcc-config">
   <rmi name="SunReg"
      targetNamespace="http://sunreg.org/wsdl"

      typeNamespace="http://sunreg.org/types">
      <service name="SunRegService"
        packageName="sunreg">
         <interface name="SunRegPort"
            servantName="SunRegImpl"/>

      </service>
   </rmi>
</configuration>

Take a more detailed look at the significant attributes in the configuration file:

• The rmi element includes name, typeNamespace, and targetNamespace attributes:
• The name attribute of the rmi element (SunReg in the code sample) is used to generate the WSDL file for publication in a public registry.
• The typeNamespace attribute defines the name space in the WSDL document for types generated by the xrpcc tool.
• The targetNamespace attribute is used for qualifying everything else in the WSDL document.
• The service element includes name and packageName attributes:
• The name attribute of the service element, SunRegService in the above code, is used to generate a properties file that the servlet-based JAX-RPC runtime uses for dispatching the request to tie-and-servant combination.
• The packageName attribute specifies the package in which xrpcc tool generates all the artifacts.

Defining the Deployment Descriptor

Because we intend to deploy SunReg on JWSDP as a WAR (Web archive file) file, we need to create a web.xml file for SunReg. The web.xml file contains information important for deploying the service, such as mapping the service to an URL, specifying the location of the configuration file in the WAR file, and so forth. Code Sample 4 shows the web.xml for deploying the SunReg service on a JWSDP container.

Code Sample 4: The web.xml for deploying the SunReg service on a JWSDP container

<web-app>
   <context-param>
      <param-name>dbUrl</param-name>

      <param-value>jdbc:cloudscape:sunregDB</param-value>
   </context-param>
   <servlet>
      <servlet-name>SunregEndpoint</servlet-name>
      <servlet-class>com.sun.xml.rpc.server.http.JAXRPCServlet
      </servlet-class>

      <init-param>
         <param-name>configuration.file</param-name>
         <param-value>
             /WEB-INF/SunRegService_Config.properties
         </param-value>
      </init-param>

      <load-on-startup>0</load-on-startup>
   </servlet>
   <servlet-mapping> 
      <servlet-name>SunregEndpoint
      </servlet-name>
      <url-pattern>/jaxrpc/*</url-pattern>

   </servlet-mapping>
</web-app>

Notice in Code Sample 4 that the web.xml file specifies dbUrl as a context parameter, which means its value applies to all the servlets defined in the WAR file. Recall that the servant implementation init method (in SunRegImpl in Code Sample 2) obtained this context parameter value to make a JDBC connection to the database.

The servlet class JAXRPCServlet is available in the JAX-RPC server runtime (that is, it is in the jaxrpc-ri.jar file found in the directory JWSDP_HOME/common/lib), and it is responsible for dispatching a request from a stub to a tie-and-servant combination within the container. The tie-and-servant combination is dictated by the _Config.properties file, which in our example is SunRegService_Config.properties. The _Config.properties file is specified to the servlet as an init-param. The xrpcc tool generates this properties file. The name of this file is derived from the name attribute of the service element in the config.xml file.

Finally, you specify the url-pattern attribute for the endpoint. This determines the service endpoint URL for the Web service.

Compiling the Service

You compile the service endpoint interface and service endpoint class using a Java compiler.

Then you generate the various server-side artifacts required by the JAX-RPC runtime by inputting the configuration tool to the Java-to-WSDL mapping tool, xrpcc, which comes bundled with JWSDP. One of the required artifacts is the WSDL service description. Recall that a service endpoint is mapped to a WSDL service description. This WSDL document describes the service endpoint in terms of abstract definitions of port types, operations, messages, and concrete protocol binding.

You'll find the xrpcc tool in the directory JWSDP_HOME/bin. It is executed by entering xrpcc.sh or xprcc.bat from that directory. The xrpcc tool generates stub, tie, and other client-side and server-side artifacts required by the JAX-RPC runtime. The command to generate the files is:

xrpcc.sh -both -keep -d classes config.xml

The options to the xrpcc tool are:

• -both instructs the xrpcc tool to generate both client-side and server-side artifacts.
• -keep instructs the tool to keep the intermediate generated source files.
• -d specifies the destination directory for generated artifacts.

Alternatively, you can generate just the client-side and server-side artifacts by specifying either the -client or -server option to the xrpcc tool instead of specifying the -both option. Because the options -client, -server, and -both are mutually exclusive you can use only one of the options with the xrpcc tool.

Among the various artifacts generated by the xrpcc tool, stubs and ties are the most important. Stubs and ties are classes that enable communication between a service endpoint and a service client. The stub class sits on the client side, between the service client and the JAX-RPC client runtime system. The stub class is responsible for converting a request from a JAX-RPC service client to a SOAP message and sending it across to the service endpoint using the specified protocol (in our case HTTP). It also converts the response from the service endpoint, which it receives in the form of a SOAP message, to the format required by the client. Converting a client request to SOAP format is called marshalling; converting back from SOAP format to a client response is unmarshalling. Similarly, the tie class resides on the server side, between the service endpoint and the JAX-RPC runtime system. The tie class handles marshalling and unmarshalling the data between the service endpoint class and the SOAP format. A stub is a local object that acts as a proxy for the service endpoint, as illustrated in Figure 3.

Figure 3: JAX-RPC runtime and generated classes

In addition to stubs and ties, the xrpcc tool generates its client-side implementation classes for the service, as explained in Invoking the Service.

The xrpcc tool also generates a properties file that associates each servant with a generated tie file (on the server side). The name of this file is formed by appending _Config.properties to the name attribute of the service element in the XML configuration file. There is one such properties file per service element. Thus, for the service SunRegService, the xrpcc compiler generates a SunRegService_Config.properties file.

The xrpcc tool also generates a WSDL file that describes the service in a standard format.

Although it's not recommended to edit the _Config.properties file, it is possible to do so. We appended a line in the SunRegService_Config.properties to make the WSDL service description accessible over the Web. We added, as the last line in SunRegService_Config.properties, the following line:

wsdl.location=/WEB-INF/SunReg.wsdl

That line makes our WSDL service description available from the service endpoint simply by appending ?WSDL to the service endpoint. Note that we have to exclude the port information when accessing the WSDL from the endpoint. We also need to ensure that the SunReg.wsdl file is packaged into the WEB-INF directory of the WAR file.

Deploying the Service

Once the xrpcc tool has completed its job, you must package and deploy the service on a servlet container (we used Tomcat for the example application). The service endpoint interface, service endpoint class, and web.xml file, along with other generated artifacts and configuration properties file, are bundled into a standard WAR file (see Code Sample 5 for the structure of the sample WAR file). Because we want the WSDL service description for SunReg to be accessible by the service endpoint, we also need to bundle SunReg.wsdl in the WAR file. The WAR file is then deployed on to the servlet container. Successful deployment results in an URL (endpoint) that a client can use to access the service, as illustrated in Figure 4.

Figure 4: Deploying the service and related files. The developer writes two Java language files, two XML files, and the client application.

Note that there are generated files in addition to the ones shown in Figure 4. All of the generated files are packaged to the WAR file. The structure of the WAR file for SunReg looks like Code Sample 5.

Code Sample 5: The structure of the web.xml WAR file for the example SunReg application

META-INF/
META-INF/MANIFEST.MF
WEB-INF/
WEB-INF/classes/
WEB-INF/classes/sunreg/
WEB-INF/classes/sunreg/Course.class
WEB-INF/classes/sunreg/Employee.class
WEB-INF/classes/sunreg/SunRegPort.class
WEB-INF/classes/sunreg/SunRegImpl.class
WEB-INF/classes/sunreg/SunRegPort_Tie.class
WEB-INF/classes/sunreg/Course_SOAPSerializer.class
WEB-INF/classes/sunreg/Employee_SOAPSerializer.class
WEB-INF/classes/sunreg/GetCourseInfo_RequestStruct.class
WEB-INF/classes/sunreg/GetCourseInfo_ResponseStruct.class
WEB-INF/classes/sunreg/RegisterCourseInfo_RequestStruct.class
WEB-INF/classes/sunreg/RegisterCourseInfo_ResponseStruct.class
WEB-INF/classes/sunreg/GetCourseInfo_RequestStruct_SOAPSerializer.class
WEB-INF/classes/sunreg/GetCourseInfo_ResponseStruct_SOAPSerializer.class
WEB-INF/classes/sunreg/

RegisterCourseInfo_RequestStruct_SOAPSerializer.class
WEB-INF/classes/sunreg/

RegisterCourseInfo_ResponseStruct_SOAPSerializer.class
WEB-INF/classes/sunreg/GetCourseInfo_ResponseStruct_SOAPBuilder.class
WEB-INF/classes/sunreg/RegisterCourseInfo_RequestStruct_SOAPBuilder.class
WEB-INF/classes/sunreg/SunRegService_SerializerRegistry.class
WEB-INF/SunRegService_Config.properties
WEB-INF/SunReg.wsdl
WEB-INF/web.xml

In this web.xml file, SunRegPort_Tie refers to the tie class. Furthermore, each method invocation and response is modeled as a struct (based on the SOAP 1.1 specification). Thus, the xrpcc tool generates _RequestStruct and _ResponseStruct classes for each method defined in the remote interface. Classes ending in _SOAPSerializer are used for serializing and deserializing the value types and the structs. Classes ending in _SOAPBuilder are helper classes used by _SOAPSerializer classes. SunRegService_SerializerRegistry registers all serializer classes for the JAX-RPC runtime.

How might a client access the SunReg service? If the SunReg service is packaged into a WAR file named SunReg.war and deployed on a servlet container installed on the host howru at port 8080, the URL for the endpoint accessible to a JAX-RPC client is:

http://howru:8080/SunReg/jaxrpc

Note that jaxrpc comes from the url-pattern defined in the web.xml file. When an employee accesses this URL in a browser window, the browser displays the message shown in Figure 5.

Figure 5. The display that appears when a user accesses http://howru:8080/SunReg/jaxrpc in a browser

The browser shows all the ports supported at this endpoint. Each port is mapped to a Java interface. Thus, the Web browser displays SunRegPort as a port supported at the endpoint:

http://howru:8080/SunReg/jaxrpc/SunRegPort

The WSDL description for the service can be accessed by clicking the "here" link or it can be found at the URL:

http://howru:8080/sunreg/jaxrpc?WSDL

Invoking the Service

The JAX-RPC Web service endpoint is available to any type of client, regardless of the language or platform used by that client. A service client invokes a service endpoint using one of the following methods:

• Stub-based programming model. This model involves code generation using the WSDL-to-Java mapping tool.
• Dynamic Invocation Interface (DII). DII is a call interface that supports programmatic creation and invocation of a RPC request.
• Dynamic proxies

First let's discuss using the stub-based programming model to invoke the service. There are two approaches with this model. You can generate stubs from a service endpoint interface by running the xrpcc tool with either the -both option or -client option. More commonly, you can generate stubs by importing the published service description, WSDL, in the xrpcc tool.

Generating Stubs from the Service Endpoint Interface

To generate stubs from the service endpoint interface, you provide either the -both or -client option when invoking the xrpcc tool, as described earlier in this article under Compiling the Service.

To access this Web service, you need to write three lines of code in the client application, as follows:

• Get a handle to the service's generated stub file.
• Set the target endpoint. The target endpoint is the URL where the Web service is installed.
• Invoke the service method through the stub reference.

Code sample 6 shows an example.

Code Sample 6: Accessing the Web Service

SunRegPort_Stub stub = (SunRegPort_Stub)(new 
    SunRegService_Impl().getSunRegPort());
stub._setProperty(Stub.ENDPOINT_ADDRESS_PROPERTY,
    "http://howru:8080/sunreg/jaxrpc/SunRegIF");
Course[] courseArray = stub.getCourseInfo();

The xrpcc tool generates its client-side implementation classes for the service, as we discussed earlier. A client-side implementation class enables the client to get a handle to the stub of the service endpoint interface. The xrpcc tool forms the name of the client implementation file by appending _Impl to the name attribute of the service element in the XML configuration file. Thus, the SunReg-generated client implementation file is called SunRegService_Impl. This generated implementation file includes a get method, getSunRegPort, which returns a reference to the stub for the service endpoint interface.

After getting a reference to the stub, you set the endpoint address on it by invoking the _setProperty method on the stub. The Stub.ENDPOINT_ADDRESS_PROPERTY refers to javax.xml.rpc.service.endpoint.address. It is a property that describes the service endpoint address. The client uses the stub reference to invoke methods on the service.

When the client invokes a method on the service through the stub, the stub marshals the request into a SOAP message and transmits the SOAP packet to the JAX-RPC servlet deployed in the servlet container. The JAX-RPC servlet looks at the SunRegService_Config.properties file for the appropriate tie-and-servant combination, and then dispatches the request to that tie-and-servant combination. The method response goes back to the client along the same path.

An employee can browse the course information and can invoke registerCourseInfo on the stub to select courses. When the employee selects a course, the servant, which is deployed on the container, uses the already established database connection to store the employee's selection information in the database. The servant can also send an email to the employee and his manager regarding the date and time of the course.

Typically, an enterprise has a system administrator handle the complexities of generating stubs and editing the configuration files. The users of the application see a well-formed graphical user interface that includes hooks to the actual JAX-RPC application.

An application can be run as an applet if the correct permissions are set. To run this application as an applet, you must give permissions to the applet sandbox security model, as shown in Code Sample 7.

Code Sample 7: Setting up the application to run as an applet

grant {
   permission java.util.PropertyPermission
      "com.sun.xml.rpc.streaming.XMLWriterFactory",
         "read";
   permission java.util.PropertyPermission
      "com.sun.xml.rpc.streaming.XMLReaderFactory",
         "read";
};

Generating Stubs from WSDL

Because the WSDL service description for SunReg has already been published, we can generate the various client-side artifacts by importing the WSDL into the xrpcc tool. To do this, you use the -client option when you invoke the xrpcc tool and provide a configuration file.

Because the Web service is already installed, starting from WSDL does not require generating server-side artifacts (such as tie files). The xrpcc tool does not expect service definition files as input; instead, it expects as input the XML configuration file with the information about the WSDL file. A WSDL file, which is the file published in the public registry, describes a complete Web service in a standard format. In addition, a WSDL file describes how to access the Web service: it contains the port offered by the service and the endpoint where the service is installed. A port is the WSDL equivalent to a remote Java interface (for example, SunRegPort when starting from a service endpoint interface). An endpoint is usually the URL to the service embedded within the WSDL file. Less often, an endpoint may be the service's URI (Uniform Resource Identifer).

Keep in mind that you do not need to know these WSDL details. Usually, you use a tool to generate WSDL files or to interpret already generated WSDL files. The xrpcc tool that comes bundled with JWSDP is one such tool.

Returning to the SunReg example application, generating clients from the service endpoint interface is most useful when all employees access the same set of courses. It's conceivable that some departments within the organization may want to filter the set of courses available for their employees. To filter courses, they can use the xrpcc tool to import the WSDL file and generate stub files. They can then use these stubs to filter the courses. Let's look at how to do this.

To begin, assume that the SunReg service is deployed in a servlet-based container, just as in the description of generating stubs from the service endpoint interface earlier in this section. The endpoint has been published and we have added the wsdl.location name and value pair to the SunRegService_Config.properties file, making the WSDL accessible. (See Compiling the Service, above, if you need to refresh your recollection of that technique.) Now, the Payroll department decides to filter courses for its employees. To do this, the Payroll department's system administrator obtains the WSDL file published by SunReg and feeds it to the xrpcc tool along with the XML configuration file, shown in Code Sample 8.

Code Sample 8: The contents of the XML configuration file, config.xml

<configuration
   xmlns="http://java.sun.com/jax-rpc-ri/xrpcc-config">
   <wsdl name="SunRegService"
      location="http://howru:8080/sunreg/jaxrpc?WSDL"

      packageName="sunreg" />
</configuration>

Notice that the config.xml file for generating stubs from a WSDL is different than the configuration file starting from a service endpoint interface. For the WSDL model, the configuration file specifies three pieces of information:

• The name of the Web service, the wsdl name attribute. The xrpcc tool generates the service implementation file from the service name and appends _Impl to the service name, SunRegService_Impl in our case.
• The location of the WSDL. The configuration file also includes a location attribute with an URL that points to the location of the WSDL. The payroll system administrator can copy the WSDL locally and then use it. Alternatively, he may decide to specify the location as an URL, which in our case is http://howru:8080/SunReg/jaxrpc?WSDL.
• The name of the WSDL package. The packageName attribute specifies the fully qualified name of the package for the generated classes and interfaces from the WSDL.

Using this information, the tool generates the necessary client-side artifacts. Note that the WSDL accessible by the location attribute ?WSDL is preconfigured with the correct endpoint URL within the service element of WSDL.

From the client application's perspective, invoking methods on this Web service is similar to that of the model where stubs were generated from the service endpoint interface. The client first invokes the new statement to instantiate a new instance of the xrpcc-generated client service implementation file. Then, the client uses the getSunRegPort method to get a reference to the service's stub. This step is equivalent to getting a reference to a remote interface. Because the endpoint is included in the WSDL file, the xrpcc tool generates stubs preconfigured with the endpoint. These preconfigured stubs mean that the client does not have to set the target endpoint, a step the client had to do when generating stubs from the service endpoint interface. The client can invoke a method on the service through the stub reference obtained from the getSunRegPort method. For example, the client invokes stub.getCourseInfo:

SunReg_Impl stub = SunRegIF_Stub(new 
    SunReg_Impl()).getSunRegIF();
Course[] courseArray = stub.getCourseInfo();

Invoking getCourseInfo returns all the courses offered by SunReg. The Payroll department's system administrator can filter the courses and provide a new interface for the users in the Payroll department. This demonstrates the extent of the work to modify the behavior of an existing Web service for a targeted audience.

Dynamic Invocation Interface

Sometimes the xrpcc tool does not have the requisite tools to parse the WSDL and generate client-side artifacts. When this happens, the client uses a dynamic invocation interface (DII) instead. Using DII, a client can call a service or a remote procedure on a service without knowing the exact service name or the procedure's signature ahead of time. A DII client can discover this information at runtime, making use of a service broker that can dynamically look up the service and its remote procedures. You can refer to the Java Web Services Developer Pack tutorial for an example of a DII client.

Conclusion

This article explains some of the basic JAX-RPC programming concepts. It describes the JAX-RPC client and server programming models and provides some simple examples to illustrate their use. The article is intended to give developers a good grasp of how to use JAX-RPC to develop or use Web services.

Forthcoming articles will explore JAX-RPC and related topics in more depth. They will also bring the reader to the current revision of the JAX-RPC technology. Feel free to post your questions to the jaxrpc-interest alias.

For More Information

• The JAX-RPC home page
• The JAX-RPC interest alias
• The Java Web Services Developer Pack
• Java Web Services Developer Pack Tutorial
• Introduction to Web Services by Ed Ort
• Java Technology & Web Services home page
• Forums for Web services
• SOAP

About the Authors

Arun Gupta is leading the effort to test the JAX-RPC implementation at Sun Microsystems, Inc. He has been with the JAX-RPC group since its inception and has been a significant contributor in evolving the technology. Arun has also worked with CORBA and other distributed technologies in Java. You'll find him active at jaxrpc-interest alias.

Beth Stearns is the principal partner of ComputerEase Publishing, a computer consulting firm she founded in 1982. Her client list includes Sun Microsystems, Inc., Silicon Graphics, Inc., Oracle Corporation, and Xerox Corporation. Among her publications are the "Java Native Interface" chapter in "The Java Tutorial Continued" book in the Addison Wesley Java series, "The EJB Programming Guide" for Inprise Corporation, and "Understanding EDT", a guide to Digital Equipment Corporation's text editor. Most recently, she co-authored with Vlada Matena of the Addison Wesley Java series book, "Applying Enterprise JavaBeans: Component-Based Development for the J2EE Platform." Beth has also contributed to two books recently published in the Addison-Wesley Java Series: "Designing Enterprise Applications with the J2EE Platform, Second Edition" and "The J2EE Tutorial."