JAX-RPC

 

Overview

Java API for XML-based RPC allows clients to execute procedures on remote systems using HTTP, SOAP, and WSDL.

  1. A client app invokes a method on a stub, which invokes the JAX-RPC runtime system, which converts the remote method call into a SOAP message, and transmits it as an HTTP request.

  2. The JAX-RPC runtime system on the server translates the SOAP message into a method call, and then invokes the method on an object.

  3. The method's response is translated back into a SOAP message and sent back to the client as an HTTP response.

  4. The client system extracts the SOAP message from the HTTP response and then translates it into a method response for the client program.

Stubs are generated by the wscompile tool. Ties are generated by the wsdeploy tool.

 

HelloWorld Example

  1. Create the following files:

    HelloIF.java Service definition interface
    HelloImpl.java Service Definition Class. Implements HelloIF.java
    HelloClient.java Remote client that contacts the service and then invokes the sayHello method
    config.xml Config file read by wscompile
    jaxrpc-ri.xml Config file read by the wsdeploy
    web.xml Deployment descriptor for the Web component (a servlet) that dispatches to the service

     

  2. Set up your Tomcat environment:

    • PATH
    • Build Properties file
    • Restart Tomcat

     

  3. Build and Deploy the service

     

  4. Build and Run the Client

 

Compile Service Definition

Compile HelloIF.java and HelloImpl.java by going to...

$JWSDP_HOME/location/of/source

...and type the following...

ant compile-server

The resulting class files are placed in ../build/shared

 

Create the WAR File

Create the WAR file by executing:

ant setup-web-inf
ant package

The setup-web-inf target copies the class and XML files to the build/WEB-INF subdirectory. The package target runs the jar command and bundles the files into a WAR file named dist/hello-portable.war:

WEB-INF/classes/hello/HelloIF.class
WEB-INF/classes/hello/HelloImpl.class
WEB-INF/jaxrpc-ri.xml
WEB-INF/web.xml

Attributes such as targetNamespaceBase are used in the WSDL file, which you'll create in the next section. WSDL(files can be complex and are not discussed in this tutorial. See Further Information.) Note that the urlPattern value (/hello) is part of the service's URL, which is described in the section Verify the Deployment).

For more information about jaxrpc-ri.xml syntax, see the jax-rpc-ri-dd.xsd XML Schema file.

 

Generate the Tie Classes and the WSDL File

To generate the tie classes and the WSDL file, run... 

ant process-war

...and then run... 

wsdeploy -tmpdir build/wsdeploy-generated 
         -o dist/hello-deployable.war dist/hello-portable.war

Tie classes and a WSDL file named MyHello.wsdl are generated using information from the jaxrpc-ri.xml file inside hello-portable.war. They are packaged, along with the contents of hello-portable.war, into a deployable WAR file named dist/hello-jaxrpc.war

 

Deploy the Service

To deploy the service, type the following: 

ant deploy

For subsequent deployments, run ant redeploy To undeploy a service: 

ant undeploy

 

Verify Deployment

To verify that the service has been successfully deployed, open a browser window and specify the service endpoint's URL:

The browser should display a page titled Web Services, which lists the port name MyHello with a status of ACTIVE. This page also has a URL to the service's WSDL file.

The hello-jaxrpc portion of the URL is the context path of the servlet that implements the HelloWorld service. This portion corresponds to the prefix of the hello-jaxrpc.war file. The /hello string of the URL matches the value of the urlPattern attribute of the jaxrpc-ri.xml file. Note that the forward slash in the /hello value of urlPattern is required. For a full listing of the jaxrpc-ri.xml file, see Package the WAR File.

 

Generate Stubs

After generating Hello.wsdl, you can create a stub by going to...

$JWSDP_HOME/docs/tutoriexamples/jaxrpc/hello

...and executing...

ant generate-stubs

...and then running... 

wscompile -gen:client -d build/client -classpath build/shared config.xml

The location of Hello.wsdl is specified by the <wsdl> element in config.xml: 

<?xml version="1.0" encoding="UTF-8"?>

<configuration xmlns="http://java.sun.com/xml/ns/jax-rpc/ri/config">

  <wsdl location="http://domain:port/hello-jaxrpc/hello?WSDL" 
        packageName="hello"/>

</configuration>

The tasks performed by the wscompile tool depend on the contents of the config.xml file. For more information about the syntax of the config.xml file, see the XML Schema file: jax-rpc-ri-config.xsd.

 

Code the Client

HelloClient is a stand-alone program that calls the sayHello method of the HelloWorld service. It makes this call through a stub, a local object which acts as a proxy for the remote service. Because the stubs is created before runtime (by wscompile), it is usually called a static stub.

To create the stub, HelloClient invokes a private method named createProxy. Note that the code in this method is implementation-specific and might not be portable because it relies on the MyHello_Impl object. (The MyHello_Impl class was generated by wscompile in the preceding section.) After it creates the stub, the client program casts the stub to the type HelloIF, the service definition interface.

The source code for HelloClient follows: 

package hello;

import javax.xml.rpc.Stub;

public class HelloClient 
{
    public static void main(String[] args) 
    {
        try 
        {
            Stub stub = createProxy();
            HelloIF hello = (HelloIF)stub;
            System.out.println(hello.sayHello("Duke!"));
        } 
        catch  Exception(ex) 
        {
            ex.printStackTrace();
        }
    }    

    private static Stub createProxy() 
    {
        // Note: MyHello_Impl is implementation-specific.
        return (Stub)(new MyHello_Impl().getHelloIFPort());
    }
}

 

Compile the Client Code

Be sure to Generate stubs before compile the client.

To compile the client, go to the $JWSDP_HOME/docs/tutoriexamples/jaxrpc/hello directory and run:

ant compile-client

 

Package the Client

To package the client into a JAR file:

ant jar-client

This command creates the dist/hello-client.jar file.

 

Run the Client

To run the HelloClient program, type the following: 

ant run

The program should display this line: 

Hello Duke!

The ant run target executes this command: 

java -classpath <cpath> hello.HelloClient

The classpath includes the hello-client.jar file that you created in the preceding section, as well as several JAR files that belong to the Java WSDP. In order to run the client remotely, all of these JAR files must reside on the remote client's computer.

 

Iterative Development

After you've initially deployed the service, you can iterate through these steps:

  1. Test the application.
  2. Edit the source files.
  3. Execute ant build to create the deployable WAR file.
  4. Execute ant redeploy to undeploy and deploy the service.
  5. Execute ant build-static to create the JAR file for a client with static stubs.
  6. Execute ant run.

 

Types Supported By JAX-RPC

Behind the scenes, JAX-RPC maps types of the Java programming language to XML/WSDL definitions. For example, JAX-RPC maps the java.lang.String class to the xsd:string XML data type. Application developers don't need to know the details of these mappings, but they should be aware that not every class in the Java 2 Standard Edition (J2SE) can be used as a method parameter or return type in JAX-RPC.

 

J2SE SDK Classes

JAX-RPC supports the following J2SE SDK classes: 

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.math.BigDecimal
java.math.BigInteger

java.util.Calendar
java.util.Date

This release of JAX-RPC also supports several implementation classes of the java.util.Collection interface. See Table 9-2.

Subinterface
 Implementation Classes
List ArrayList
LinkedList
Stack
Vector
Map
HashMap
Hashtable
Properties
TreeMap
Set
HashSet
TreeSet

 

Primitives

JAX-RPC supports the following primitive types of the Java programming language: 

boolean
byte
double
float
int
long
short

 

Arrays

JAX-RPC supports arrays with members of supported JAX-RPC types. Examples of supported arrays are int[] and String[]. Multidimensional arrays, such as BigDecimal[][], are also supported.

 

Custom Application Classes

The states of custom application classes can be passed between clients and remote services as method parameters or return values. To be supported, an application class must conform to the following rules:

The class may contain public, private, or protected fields. For its value to be passed (or returned) during a remote call, a field must meet these requirements:

 

JavaBeans Components

JAX-RPC also supports JavaBeans components, which must conform to the same set of rules as application classes. In addition, a JavaBeans component must have a getter and setter method for each bean property. The type of the bean property must be a supported JAX-RPC type. For an example of a JavaBeans component, see the section JAX-RPC Distributor Service.

 

A Dynamic Proxy Client Example

The client in the section, A Simple Example: HelloWorld, used a static stub for the proxy. In contrast, the client example in this section calls a remote procedure through a dynamic proxy, a class that is created during runtime. Before creating the proxy class, the client gets information about the service by looking up its WSDL document.

 

Dynamic Proxy HelloClient Listing

Here is the full listing for the HelloClient.java file of the $JWSDP_HOME/docs/tutoriexamples/jaxrpc/proxy directory. 

package proxy;

import java.net.URL;
import javax.xml.rpc.Service;
import javax.xml.rpc.JAXRPCException;
import javax.xml.namespace.QName;
import javax.xml.rpc.ServiceFactory;

public class HelloClient 
{

    public static void main(String[] args) 
    {
        try 
        {

            String UrlString =
                "http://domain:port/ProxyHelloWorld.wsdl";
            String nameSpaceUri = "http://proxy.org/wsdl";
            String serviceName = "HelloWorld";
            String portName = "HelloIFPort";

            URL helloWsdlUrl = new URL(UrlString);
            
            ServiceFactory serviceFactory =
                ServiceFactory.newInstance();
            
            Service helloService =
                serviceFactory.createService(helloWsdlUrl, 
                new QName(nameSpaceUri, serviceName));
            
            HelloIF myProxy = (HelloIF) helloService.getPort(
                new QName(nameSpaceUri, portName), 
                proxy.HelloIF.class); 

            System.out.println(myProxy.sayHello("Buzz"));

        } 
        catch  Exception(ex) 
        {
            ex.printStackTrace();
        } 
    } 
}

 

Build and Run the Dynamic Proxy Example

Perform the following steps:

  1. If you haven't already done so, follow the instructions in Setting Up.
  2. Go to the $JWSDP_HOME/docs/tutoriexamples/jaxrpc/proxy directory.
  3. Type the following commands: 
      ant build
  ant deploy
  ant build-dynamic
  ant run

The client should display the following line: 

A dynamic proxy hello to Buzz!

 

A Dynamic Invocation Interface (DII) Client Example

With the dynamic invocation interface (DII), a client can call a remote procedure even if the signature of the remote procedure or the name of the service are unknown until runtime.

Because of its flexibility, a DII client can be used in a service broker that dynamically discovers services, configures the remote calls, and executes the calls. For example, an application for an online clothing store might access a service broker that specializes in shipping. This broker would use the Java API for XML Registries (JAXR) to locate the services of the shipping companies that meet certain criteria, such as low cost or fast delivery time. At runtime, the broker uses DII to call remote procedures on the Web services of the shipping companies. As an intermediary between the clothing store and the shipping companies, the broker offers benefits to all parties. For the clothing store, it simplifies the shipping process, and for the shipping companies, it finds customers.

 

DII HelloClient Listing

Here is the full listing for the HelloClient.java file of the $JWSDP_HOME/docs/tutoriexamples/jaxrpc/dynamic directory. 

package dynamic;

import javax.xml.rpc.Call;
import javax.xml.rpc.Service;
import javax.xml.rpc.JAXRPCException;
import javax.xml.namespace.QName;
import javax.xml.rpc.ServiceFactory;
import javax.xml.rpc.ParameterMode;

public class HelloClient 
{

    private static String endpoint =
        "http://domain:port/dynamic-jaxrpc/dynamic";
    private static String qnameService = "Hello";
    private static String qnamePort = "HelloIF";

    private static String BODY_NAMESPACE_VALUE = 
        "http://dynamic.org/wsdl";
    private static String ENCODING_STYLE_PROPERTY =
        "javax.xml.rpc.encodingstyle.namespace.uri"; 
    private static String NS_XSD = 
        "http://www.w3.org/2001/XMLSchema";
    private static String URI_ENCODING =
         "http://schemas.xmlsoap.org/soap/encoding/";

    public static void main(String[] args) 
    {
        try 
        {

            ServiceFactory factory = 
                ServiceFactory.newInstance();
            Service service = 
                factory.createService(new QName(qnameService));
    
            QName port = new QName(qnamePort);
    
            Call call = service.createCall(port);
            call.setTargetEndpointAddress(endpoint);
    
            call.setProperty(Call.SOAPACTION_USE_PROPERTY, 
                new Boolean(true));
             call.setProperty(Call.SOAPACTION_URI_PROPERTY,"");
            call.setProperty(ENCODING_STYLE_PROPERTY,
               URI_ENCODING);
            QName QNAME_TYPE_STRING = 
                new QName(NS_XSD, "string");
            call.setReturnType(QNAME_TYPE_STRING);


            call.setOperationName(
                new QName(BODY_NAMESPACE_VALUE "sayHello"));
            call.addParameter("String_1", QNAME_TYPE_STRING, 
                ParameterMode.IN);
            String[] params = { "Duke!" };

            String result = (String)call.invoke(params);
            System.out.println(result);

        } 
        catch  Exception(ex) 
        {
            ex.printStackTrace();
        }
    }
}

 

Build and Run the DII Example

Perform the following steps:

  1. If you haven't already done so, follow the instructions in Setting Up.
  2. Go to the $JWSDP_HOME/docs/tutoriexamples/jaxrpc/dynamic directory.
  3. Type the following commands: 
      ant build
  ant deploy
  ant build-dynamic
  ant run

The client should display the following line: 

A dynamic hello to Duke!

 

Security for JAX-RPC

In this section, you'll learn how to create JAX-RPC service applications that use HTTP/SSL for basic or mutual authentication. If the topic of authentication is new to you, please refer to the chapter Web Application Security.

 

Note: The instructions in this section apply only to version 1.4 of the J2SE SDK.

 

There are certain steps you take to configure a JAX-RPC Web service endpoint for HTTP/S basic and mutual authentication:

Detailed instructions for these steps follow.

 

Basic Authentication Over SSL

The steps for configuring a Web service for basic authentication over HTTP/S are outlined here. Refer to the section Mutual Authentication Over SSL for the steps for configuring the same service with mutual authentication.

 

Generating SSL Certificates for Basic Authentication

You use keytool to generate SSL certificates and export them to the appropriate server and client keystores. Keep in mind that the server and client keystores are created in the directory from which you run keytool.

  1. Go to the $JWSDP_HOME/docs/tutoriexamples/jaxrpc/security directory.
  2. Run keytool to generate the server keystore with a default password of changeit.
    UNIX:
    Specify the server name, such as domain, and user identity information as arguments to keytool. Enter the following: 
    $JAVA_HOME/bin/keytool -genkey -alias tomcat-server -dname 
"CN=<server name>, OU=<organizational unit>, O=<organization>, 
L=<locality>, S=<state>, C=<country code>", -keyalg RSA -
keypass changeit -storepass changeit -keystore server.keystore
    Windows:
    The keytool utility prompts you to enter the server name, organizational unit, organization, locality, state, and country code. Note that enter the server name in response to the first prompt, which asks for first and last names. Enter the following: 
    %JAVA_HOME%\bin\keytool -genkey -alias tomcat-server -keyalg 
RSA -keypass changeit -storepass changeit -keystore 
server.keystore
  3. Export the generated server certificate.
    The keytool command is the same for UNIX and Windows. On UNIX, enter the following: 
    $JAVA_HOME/bin/keytool -export -alias tomcat-server -storepass 
changeit -file server.cer -keystore server.keystore
  4. Generate the client keystore.
    UNIX: 
    $JAVA_HOME/bin/keytool -genkey -alias tomcat-client -dname 
"CN=<client name>, OU=<organizational unit>, O=<organization>, 
L=<locality>, S=<state>, C=<country code>", -keyalg RSA -
keypass changeit -storepass changeit -keystore client.keystore
    Windows:
    The keytool utility prompts you to enter the client's server name, organizational unit, organization, locality, state, and country code. Note that enter the server name in response to the first prompt, which asks for first and last names. Enter the following: 
    %JAVA_HOME%\bin\keytool -genkey -alias tomcat-client -keyalg 
RSA -keypass changeit -storepass changeit -keystore 
client.keystore
  5. Import the server certificate into the client's keystore.
    For basic authentication, it is only necessary to import the server certificate into the client keystore. The keytool command is the same for UNIX and Windows. On UNIX, enter the following: 
    $JAVA_HOME/bin/keytool -import -v -trustcacerts -alias tomcat-
server -file server.cer -keystore client.keystore -keypass 
changeit -storepass changeit

 

Adding an SSL Connector to Tomcat

In this section you will add the SSL Connector by running admintool, a utility that is included with the Java WSDP. For more information on the tool, see the appendix, Tomcat Administration Tool

  1. Follow the instructions in Adding an SSL Connector in admintool. In the right pane displayed by admintool, enter the values shown in Table 9-3.

Field Value
Type
 HTTPS
Port
 8443
Keystore
Name 		$JWSDP_HOME/docs/tutoriexamples/jaxrpc/security/server.keystore
Keystore
Password
 changeit

  1. Restart Tomcat.
  2. Make sure that the SSL Connector has been added by following the instructions in Verifying SSL Support.

 

Adding Security Elements to web.xml

The files for this example are in the $JWSDP_HOME/docs/tutoriexamples/jaxrpc/security directory. For authentication over SSL, the web.xml file includes the <security-constraint> and <login-config> elements: 

<security-constraint>
  <web-resource-collection>
    <web-resource-name>SecureHello</web-resource-name>
    <url-pattern>/security</url-pattern>
    <http-method>GET</http-method>
    <http-method>POST</http-method>
  </web-resource-collection>
  <auth-constraint>
    <role-name>manager</role-name>
  </auth-constraint>
</security-constraint>
<login-config>
  <auth-method>BASIC</auth-method>
</login-config>

Note that the <role-name> element specifies manager, a role that has already been specified in the $JWSDP_HOME/conf/tomcat-users.xml file. To learn how to update the tomcat-users.xml file with admintool, see Managing Roles.

 

Setting Security Properties in the Client Code

The source code for the client is in the HelloClient.java file of the $JWSDP_HOME/docs/tutoriexamples/jaxrpc/security directory. For basic authentication over SSL, the client code must set several security-related properties.

trustStore Property

The value of the trustStore property is the fully qualified name of the client.keystore file: 

$JWSDP_HOME/docs/tutoriexamples/jaxrpc/security/client.key
store

In a preceding section, Generating SSL Certificates for Basic Authentication, you created the client.keystore file by running the keytool utility. The client specifies the trustStore property as follows: 

System.setProperty("javax.net.ssl.trustStore", trustStore);
trustStorePassword Property

The trustStorePassword property is the password of the J2SE SDK keystore. In a previous section, you specified the default value of this password (changeit) when running keytool. The client sets the trustStorePassword property in the following line: 

System.setProperty("javax.net.ssl.trustStorePassword", 
   trustStorePassword);
Username and Password Properties

The username and password values correspond to the manager role, which is specified in the $JWSDP_HOME/conf/tomcat-users.xml file. (See Managing Roles and Users.) The installer utility of the Java WSDP automatically added the username and password values to the tomcat-users.xml file.

The client sets the username and password properties as follows: 

stub._setProperty(javax.xml.rpc.Stub.USERNAME_PROPERTY, 
    username);
stub._setProperty(javax.xml.rpc.Stub.PASSWORD_PROPERTY, 
    password);

 

Build and Runn the Example for Basic Authentication Over SSL

Perform the following steps:

  1. If you haven't already done so, follow the instructions in Setting Up.
  2. Follow the instructions in Generating SSL Certificates for Basic Authentication and in Adding an SSL Connector to Tomcat. Don't forget to restart Tomcat.
  3. Go to the $JWSDP_HOME/docs/tutoriexamples/jaxrpc/security directory.
  4. Type the following commands: 
      ant build
  ant deploy
  ant build-static
  ant run-security

The client should display the following line: 

Hello Duke (secure)

 

Mutual Authentication Over SSL

To configure and create a JAX-RPC service with mutual authentication, follow all of the steps in the preceding section (Basic Authentication Over SSL) up to and including the command ant build-static. Then, follow these steps:

  1. Export the generated client certificate.
    The keytool command is the same for UNIX and Windows. On UNIX, enter the following: 
    $JAVA_HOME/bin/keytool -export -alias tomcat-client -storepass 
changeit -file client.cer -keystore client.keystore
  2. Import the client certificate into the server's keystore.
    The keytool command is the same for UNIX and Windows. On UNIX, enter the following: 
    $JAVA_HOME/bin/keytool -import -v -trustcacerts -alias tomcat-
client -file client.cer -keystore server.keystore -keypass 
changeit -storepass changeit
  3. Run the application: 
    ant run-security

The client should display the following line: 

Hello Duke (secure)

Acknowledgement: This section includes material from the "Web Services Security Configuration" white paper, written by Rahul Sharma and Beth Stearns.

 

JAX-RPC on the J2EE SDK 1.3.1

In the example of this section, a stand-alone JAX-RPC client makes a remote call on a JAX-RPC service that is deployed as a servlet on the J2EE SDK. The servlet locates a stateless session bean and then invokes a method on the bean.

 

Note: The instructions in this section apply only to version 1.3.1 of the J2EE SDK.

 

 

Prerequisites

This section is for advanced users who are familiar with the following:

To learn about EJB and J2EE technologies, see the J2EE Tutorial:

To run this example, you'll need to download and install the J2EE SDK, which is available at the following URL:

 

Note: On the page of the preceding URL, be sure to read the section, Supported Operating Systems and Required Software. The J2EE SDK 1.3.1 does not support Windows 95, 98, ME, or XP.

 

 

Example Code

The example files are located in the $JWSDP_HOME/docs/tutoriexamples/jaxrpc/toejb directory. The greeting subdirectory contains the source code for the stateless session bean named GreetingEJB. You don't have to compile or package the bean, because it's already packaged in a J2EE application archive named GreetingApp.ear. This EAR file is in the provided-jars subdirectory.

At runtime, a JAX-RPC client named HelloClient makes a remote call to the sayHello method of the JAX-RPC Web service: 

System.out.println(stub.sayHello("Buzz!"));

Next, the sayHello method of the HelloImpl class invokes the sayHey method of GreetingEJB: 

public String sayHello String(name) 
{

        String result = null;

        try 
        {
            Context initial = new InitialContext();
            Context myEnv =
               (Context)initial.lookup("java:comp/env");
            Object objref = myEnv.lookup("ejb/SimpleGreeting");
 
            GreetingHome home = 
                (GreetingHome)PortableRemoteObject.narrow
                (objref, GreetingHome.class);
 
            Greeting salutation = home.create();
            result = salutation.sayHey(name);
 
        } 
        catch  Exception(ex) 
        {
            System.out.println("Exception in sayHello: " 
                + ex.getMessage());
        }

        return result;

}

Here is the sayHey method of the GreetingBean class of the GreetingEJB stateless session bean: 

public String sayHey String(name) 
{
       return "Hey " + name + "!";
}

 

Package the JAX-RPC Client and Web Service

  1. If your PATH environment variable includes <J2EE_HOME>/bin, change the PATH so that $JWSDP_HOME/bin precedes <J2EE_HOME>/bin.
  2. In a terminal window, go to the $JWSDP_HOME/docs/tutoriexamples/jaxrpc/toejb directory.
  3. In a text editor, open the build.xml file and set the value of j2ee.home to the location of your J2EE SDK installation.
  4. Type the following commands: 
      ant build
  ant build-static

The preceding commands will create the toejb-jaxrpc.war and toejb-client.jar files in the dist subdirectory.

 

Setting Up the J2EE SDK 1.3.1

  1. If Tomcat is running, shut it down.
  2. If the j2ee server is running, stop it.
  3. Set the PATH environment variable so that <J2EE_HOME>/bin precedes $JWSDP_HOME/bin.

 

Note: In all subsequent steps, <J2EE_HOME>/bin must precede $JWSDP_HOME/bin in the PATH environment variable.

 

  1. In a terminal window, run the following command:

UNIX: 

  $JWSDP_HOME/bin/jwsdponj2ee.sh $J2EE_HOME

Windows: 

  $JWSDP_HOME\bin\jwsdponj2ee.bat %J2EE_HOME%

The jwsdponj2ee script adds Java WSDP libraries to the J2EE SDK and then changes the Web server port of the J2EE SDK from 8000 to 8080. After you've finished running this example, you may want to follow the instructions in Undo the Effects of jwsdponj2ee.

  1. In a terminal window, start the j2ee server: 
      j2ee -verbose
  2. Both the Java WSDP and the J2EE SDK have utilities called deploytool. In the steps that follow, run the J2EE SDK's deploytool. To make sure that your PATH points to the J2EE SDK's deploytool, type this command: 
      deploytool -version

The tool should display the following line: 

  The deployment tool version is 1.3.1
  1. Run the J2EE SDK's deploytool: 
      deploytool

 

Deploy the GreetingEJB Session Bean

  1. In the deploytool utility, open the GreetingApp.ear file, which is located in the directory named $JWSDP_HOME/docs/tutoriexamples/jaxrpc/toejb/provided-jars.
  2. In the tree, expand GreetingApp. Note that it contains an enterprise bean named GreetingEJB and a J2EE application client named GreetingClient. This client was created to test the bean and will not be run in this example.
  3. Deploy the GreetingApp application.

 

Deploy the JAX-RPC Service

  1. In deploytool, create a new application named HelloApp.
  2. Add the toejb-jaxrpc.war file to HelloApp. This WAR file is in the directory named $JWSDP_HOME/docs/tutoriexamples/jaxrpc/toejb/dist.
  3. Specify the reference to GreetingEJB.
    1. In the tree, select HelloWorldApplication.

    2. On the EJB Refs tab, add an entry with the values shown in the following table.

      Field
      		 Value
      Coded Name
      		 ejb/SimpleGreeting
      Type
      		 Session
      Interfaces
      		 Remote
      Home Interface
      		 toejb.greeting.GreetingHome
      Local/Remote Interface
      		 toejb.greeting.Greeting
  4. Specify the JNDI name of GreetingEJB.
    1. In the tree, select HelloApp.

    2. On the JNDI Names tab, enter MyGreeting in the JNDI Name field at the bottom.
  5. Set the context root for the servlet.
    1. In the tree, select HelloApp.

    2. On the Web Context tab, enter toejb-jaxrpc in the Context-Root field.
  6. Deploy the HelloApp application.

If you have problems deploy the application, you may find it helpful to compare the HelloApp.ear file you created with the CompareHelloApp.ear file in the provided-jars subdirectory. The HelloWorldApplication in the CompareHelloApp.ear file has the correct settings and may be deployed as is.

 

Run the JAX-RPC Client

  1. In a terminal window, go to the directory named $JWSDP_HOME/docs/tutoriexamples/jaxrpc/toejb.
  2. Type the following command: 
      ant run

The client should display the following line: 

  Hey Buzz!!

 

Undo the Effects of jwsdponj2ee

In the section, Setting Up the J2EE SDK 1.3.1, you ran the jwsdponj2ee script, which made some changes to the J2EE SDK installation. To undo these changes, perform the following:

  1. Stop the j2ee server.
  2. In a text editor, open the <J2EE_HOME>/config/web.properties file and change the value of the http.port property from 8080 to 8000.
  3. In a text editor, open the userconfig script of the <J2EE_HOME>/bin directory and comment out the statement that sets the J2EE_HOME variable.

 

Creating a JAX-RPC Service With deploytool

In the examples of the preceding sections, you executed Ant tasks to build and install services. In this section, however, you'll create a service with deploytool instead of Ant. The deploytool utility automatically performs these tasks:

The client in this example is a dynamic proxy, similar to the one described in A Dynamic Proxy Client Example. At runtime, the client accesses the WSDL document that's installed by deploytool. The source code for this HelloClient program is in the $JWSDP_HOME/docs/tutoriexamples/jaxrpc/dephello directory.

Before trying out the example in this section, you should be familiar with the basic operations of deploytool. For a quick introduction, see Deploy the Application Using deploytool.

 

Compile the Source Code

  1. If you haven't already done so, follow the instructions in Setting Up.
  2. In a terminal window, go to the $JWSDP_HOME/docs/tutoriexamples/jaxrpc/dephello directory.
  3. Type the following:
    ant build
    The build target performs these tasks:
    • Compiles the service interface and implementation class
    • Compiles the client
    • Packages the client into the dist/dephello-client.jar file

 

Build the Web Application

In this section, you will package the service into a WAR file by running the New Web Application wizard of deploytool. After you start the wizard (File->New Web Application), the following dialogs appear:

  1. Introduction
    1. Read this dialog to learn more about the wizard.
    2. Click Next.
  2. WAR File dialog
    1. In the Module File Name field, enter MyHello.war.
    2. In the War Display Name field, enter MyHelloWAR.
    3. Click Edit.
  3. Edit Contents dialog
    1. Navigate to the following directory, which contains the service interface and implementation class. 
          $JWSDP_HOME/docs/tutoriexamples/jaxrpc/dephello/
      build/shared
    2. Add HelloIF.class and HelloImpl.class to the field labelled Contents of MyHelloWAR.
    3. Click OK.
    4. Click Next.
  4. Choose Component Type dialog
    1. Select the JAX-RPC Endpoint radio button.
    2. Click Next.
  5. JAX-RPC Default Settings dialog
    1. In the WSDL Target Namespace Base String field, enter the following: 
          http://wombat.com/wsdl/
    2. In the Schema Target Namespace Base String field, enter the following: 
          http://wombat.com/xsd/
    3. In the Endpoint Alias Base String field, enter /jaxrpc.
    4. Click Next.
  6. JAX-RPC Endpoint dialog
    1. In the EndPoint Interface combo box, select dephello.HelloIF.
    2. In the EndPoint Class combo box, select dephello.HelloImpl.
    3. In the Endpoint Name field, enter MyHelloWorld.
    4. In the Endpoint Display Name field, enter MyHelloWorld.
    5. Leave the Alias field blank.
    6. Click Next.
  7. JAX-RPC Model dialog
    1. Select the Use Default Settings radio button.
    2. Click Next.
  8. Review Settings dialog
    1. Take a quick look at the two XML files displayed by this dialog. The file shown at the top of the dialog is the web.xml file that will be packaged in the WAR file. The file displayed at the bottom is the jaxrpc-ri.xml file, also to be packaged in the WAR file. The jaxrpc-ri.xml file is implementation-specific and is not defined by the specifications.
    2. Click Finish.

The deploytool utility now creates the MyHello.war file.

 

Deploy the Web Application

  1. From the main menu of deploytool, select Tools->Deploy.
  2. In the Text Input dialog, enter /jaxrpc-dephello for the Web context.
  3. The Deployment Console dialog appears and displays this line: 
      OK - Installed application at context path /jaxrpc-dephello
  4. Click Close.

 

Check the Status of the Web Service

In a browser, go to the following URL:

The browser displays a page showing the status of the MyHelloWorld port (or endpoint) name. This page also shows the URL for the WSDL document:

This is the URL that the HelloClient program will use to locate the WSDL document that was created during deployment.

 

Note: If you have problems deploying the Web service, you may find it helpful to compare your MyHello.war file with the CompareMyHello.war file of the dephello/provided-jars subdirectory.

 

 

Runn the Client

  1. In a terminal window, go to the directory named $JWSDP_HOME/docs/tutoriexamples/jaxrpc/dephello.
  2. Type the following command: 
      ant run

The client should display the following line: 

  A dynamic proxy hello to Murphy!

 

Further Information

For more information about JAX-RPC and related technologies, refer to the following:

 

Home