Home TOC |
![]() ![]() ![]() |
A Simple Example: HelloWorld
This example shows you how to use JAX-RPC to create a Web service named
HelloWorld
. A remote client of theHelloWorld
service can invoke thesayHello
method, which accepts a string parameter and then returns a string.HelloWorld at Runtime
Figure 9-1 shows the structure of the
HelloWorld
service after it's been deployed. Here's what happens at runtime:
- To call a remote procedure, the
HelloClient
program invokes a method on a stub, a local object that represents the remote service.- The stub invokes routines in the JAX-RPC runtime system of the reference implementation.
- The runtime system converts the remote method call into a SOAP message and then transmits the message as an HTTP request.
- When the server receives the HTTP request, the JAX-RPC runtime system extracts the SOAP message from the request and translates it into a method call.
- The JAX-RPC runtime system invokes the method on the tie object.
- The tie object invokes the method on the implementation of the
HelloWorld
service.Figure 9-1 The
HelloWorld
Example at RuntimeThe application developer only provides the top layers in the stacks depicted by Figure 9-1. Table 9-1 shows where the layers originate.
HelloWorld Files
To create a service with JAX-RPC, an application developer needs to provide just a few files. For the
HelloWorld
example, these files are in thedocs/tutorial/examples/jaxrpc/hello
subdirectory:
HelloIF.java
- the service definition interfaceHelloImpl.java
- the service definition implementation class, it implements theHelloIF
interfaceconfig.xml
- a configuration file read by thexrpcc
tool, which creates the stub and tie classesweb.xml
- a deployment descriptor for the Web component (a servlet) that dispatches to the serviceHelloClient.java
- the remote client that contacts the service and then invokes thesayHello
methodSetting Up
Before you try out the
HelloWorld
example, you must perform these tasks:
- Install the required software.
- Set the necessary environment variables.
- Change some values in the
common/build.properties
file.- Start Tomcat.
Required Software
For a list of the required software and supported operating systems, see the Release Notes of the Java Web Services Developer Pack.
The Java Web Services Developer Pack includes Tomcat and the
ant
build utility. You must use the included version of Tomcat to run the examples in this tutorial. Although you may use a separate installation ofant
, we recommend that you run the included version in order to avoid problems caused by incompatible versions.Environment Variables
Before you try out the
HelloWorld
example, you must set some environment variables. For more information, see the Release Notes of the Java Web Services Developer Pack.Editing common/build.properties
Several of the ant targets that you will run in this chapter rely on values that are set in the
common/build.properties
file. Before running these targets, you must first make some changes to this file.
- In a text editor, open the
docs/tutorial/examples/jaxrpc/common/build.properties
file.- Change the
username
andpassword
values to the ones that you entered on the Create Tomcat User dialog of the installer. If you don't remember these values, go to the <JWSDP_HOME>/conf/tomcat-users.xml
file and examine theuser
element that has aroles
attribute with the valuemanager
.- If you are on a Windows system, you may skip this step. If you are on a UNIX system, change the value of the
script-suffix
property tosh
. For Windows, the value should bebat
, which is the default.- Save the
common/build.properties
file and exit the editor.Starting Tomcat
To start Tomcat, type the following command in a terminal window:
startup.shstartupTo shut down (stop) Tomcat, type this command:
shutdown.shshutdownBuilding and Installing the Service
The basic steps for developing a JAX-RPC Web service are as follows.
- Code the service definition interface and implementation class.
- Compile the service definition code of step 1.
- Create the configuration file.
- Generate the ties.
- Create the deployment descriptor.
- Install the service on Tomcat.
The sections that follow describe each of these steps in more detail.
Coding the Service Definition Interface and Implementation Class
A service definition interface declares the methods that a remote client may invoke on the service. The interface must conform to a few rules:
- It extends the
java.rmi.Remote
interface.- It must not have constant declarations, such as
public final static
.- The methods must throw the
java.rmi.RemoteException
or one of its subclasses. (The methods may also throw service-specific exceptions.)- Method parameters and return types must be supported JAX-RPC types. See the section Types Supported By JAX-RPC.
In this example, the service definition interface is
HelloIF.java
:package hello; import java.rmi.Remote; import java.rmi.RemoteException; public interface HelloIF extends Remote { public String sayHello(String s) throws RemoteException; }In addition to the interface, you'll need to code the class that implements the interface. In this example, the implementation class is called
HelloImpl
:package hello; public class HelloImpl implements HelloIF { public String message = new String("Hello "); public String sayHello(String s) { return new String(message + s); } }Compiling the Service Definition Code
To compile
HelloIF.java
andHelloImpl.java
, go to thedocs/tutorial/examples/jaxrpc/hello
directory and type the following:ant compile-serverThis command places the resulting class files in the
build/shared
subdirectory.Creating the Configuration File
The
config.xml
file contains information needed by thexrpcc
tool, which you'll run in the next section.In the file listing that follows, note the values defined in the
<service>
element. The name of the service,HelloWorld
, will be used as the prefix of theHelloWorldImpl
class name. Generated by thexrpcc
tool, theHelloWorldImpl
is instantiated by the client class (see Coding the Client). ThepackageName
attribute,hello
, is the name of the package of the classes generated byxrpcc
. In the<interface>
subelement, thename
attribute corresponds to the fully qualified name of the service definition interface,hello.HelloIF
. TheservantName
attribute is the name of the interface's implementation class,hello.HelloImpl
.<?xml version="1.0" encoding="UTF-8"?> <configuration xmlns="http://java.sun.com/jax-rpc-ri/xrpcc-config"> <rmi name="HelloWorldService" targetNamespace="http://hello.org/wsdl" typeNamespace="http://hello.org/types"> <service name="HelloWorld" packageName="hello"> <interface name="hello.HelloIF" servantName="hello.HelloImpl"/> </service> </rmi> </configuration>For more information about the syntax of the tool's configuration file, see the section Configuration File.
Note: Although required for the reference implementation of JAX-RPC, the configuration file andxrpcc
tool are not defined in the specifications. Their syntax and usage may change in future releases.
Generating the Ties
Ties are lower-level classes on the server that enable it to communicate with the client. (On the client, the corresponding classes are called stubs.) To generate the ties, you run the
xrpcc
tool. The tool also creates a properties file and a WSDL file. Used internally by the reference implementation, the properties file is not defined in the specifications. For information about the relationship between JAX-RPC technology and WSDL files, please refer to the JAX-RPC Specification.In this example, the
xrpcc
tool reads the service definition interface and the configuration file. (Alternatively, the tool may read a WSDL file instead of the interface. See Starting With a WSDL Document for more information.)The
xrpcc
tool is a script:xrpcc.sh
for UNIX orxprcc.bat
for Windows. To create the ties, go to thedocs/tutorial/examples/jaxrpc/hello
directory and run the tool as follows. (Type the command on a single line.)xrpcc.sh -classpath build/shared -server -d build/server config.xmlxrpcc.bat -classpath build\shared -server -d build\server config.xmlThe -
classpath
option refers to the directory into which the server files were compiled. The-d
option denotes the destination directory for the generated files. See the section Syntax for the full syntax of thexrpcc
tool.As a shortcut, instead of running the
xrpcc
command as shown previously, you can simply type the following:ant xrpcc-serverCreating the Deployment Descriptor
A deployment descriptor is an XML file that provides configuration information for the Web server about the Web components (JSP pages or servlets) that are in a Web application. Because the
HelloWorld
service is deployed as a servlet, the deployment descriptor has some elements that are related to the service. This section describes only those elements; for more information about deployment descriptors, see the Java Servlet Specification.Let's take a quick look at a couple of the elements in the deployment descriptor (
web.xml
). First, note theHelloWorld_Config.properties
value of the<init-param>
element. This properties file was generated by thexrpcc
tool. The name of the file is theHelloWorld
service name (which was defined in the configuration file) appended by the_Config.properties
string. The value of the<url-pattern>
element,/jaxrpc/*
, is part of the URL that designates the service's endpoint. This URL is passed to theHelloClient
program as a command-line parameter. See Running the Client.The
web.xml
deployment descriptor follows:<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN" "http://java.sun.com/j2ee/dtds/web-app_2_3.dtd"> <web-app> <display-name>HelloWorldApplication</display-name> <description>Hello World Application</description> <servlet> <servlet-name>JAXRPCEndpoint</servlet-name> <display-name>JAXRPCEndpoint</display-name> <description> Endpoint for Hello World Application </description> <servlet-class> com.sun.xml.rpc.server.http.JAXRPCServlet </servlet-class> <init-param> <param-name>configuration.file</param-name> <param-value> /WEB-INF/HelloWorld_Config.properties </param-value> </init-param> <load-on-startup>0</load-on-startup> </servlet> <servlet-mapping> <servlet-name>JAXRPCEndpoint</servlet-name> <url-pattern>/jaxrpc/*</url-pattern> </servlet-mapping> <session-config> <session-timeout>60</session-timeout> </session-config> </web-app>Installing the Service
The
HelloWorld
service is implemented as a Web application that runs on Tomcat. To install the Web application, go to thedocs/tutorial/examples/jaxrpc/hello
directory and type the following command:ant installIf this command fails, you should verify that you followed the instructions in Editing common/build.properties and Starting Tomcat.
In this example, the
install
target depends on another target (setup-web-inf
), which copies the class files and the deployment descriptor (web.xml
) to thebuild/WEB-INF
directory. The contents of theWEB-INF
directory match the contents of the WAR file described in Optional: Packaging the Service.Verifying the Installation
To verify that the
HelloWorld
service has been installed, open a browser window and specify this URL:http://localhost:8080/jaxrpc-hello/jaxrpcThe browser should display these lines:
A Web Service is installed at this URL. It supports the following ports: "HelloIF" (http://localhost:8080/jaxrpc-hello/jaxrpc/HelloIF)(For an explanation of the elements in the URL, see Running the Client.)
You can use this approach to verify the deployment of any service that is created with the JAX-RPC reference implementation. For example, to verify the service documented in A DII Client Example, you would specify the following URL:
http://localhost:8080/jaxrpc-dynamic/jaxrpcRemoving the Service
At this point in the tutorial, do not remove the service. When you are finished with this example, you can remove the
HelloWorld
service by typing this command:ant removeFor information about reloading the service, see the section Iterative Development.
Building and Running the Client
To develop a JAX-RPC client, you follow these steps:
- Generate the stubs.
- Code the client.
- Compile the client code.
- Package the client classes into a JAR file.
- Run the client.
The following sections describe each of these steps.
Generating the Stubs
In addition to generating the ties for the server, the
xrpcc
tool also generates the stubs for the client. To create the stubs, go to thedocs/tutorial/examples/jaxrpc/hello
directory and run the tool as follows. (Type the command on a single line.)xrpcc.sh -classpath build/shared -client -d build/client config.xmlxrpcc.bat -classpath build\shared -client -d build\client config.xmlThe -
classpath
option refers to the directory containing the class files that you created in Compiling the Service Definition Code. The-d
option denotes the destination directory for the generated files. See the section Syntax for the full syntax of thexrpcc
tool.As a shortcut, instead of running the
xrpcc
command as shown previously, you can simply type the following:ant xrpcc-clientCoding the Client
The
HelloClient
is a stand-alone program that calls thesayHello
method of theHelloWorld
service. It makes this call through a stub, a local object which acts as a proxy for the remote service.In the code listing that follows, note the names of the
HelloIF_Stub
andHelloWorldImpl
classes, which were generated by thexrpcc
tool. TheHelloIF
prefix matches the name of the service definition interface and theHelloWorld
prefix corresponds to the service name specified in the configuration file. TheHelloWorldImpl
class is the implementation of a service as described in the JAX-RPC Specification. The client gets a reference to the stub by calling thegetHelloIF
method of theHelloWorldImpl
class, which was created when you ran thexrpcc
tool.The
args[0]
parameter of thestub._setProperty
method is a URI that denotes the address of the target service port. For details on this URI, see Running the Client.The source code for the
HelloClient
follows:package hello; public class HelloClient { public static void main(String[] args) { try {
HelloIF_Stub stub = (HelloIF_Stub) (new HelloWorld_Impl().getHelloIF()); stub._setProperty( javax.xml.rpc.Stub.ENDPOINT_ADDRESS_PROPERTY, args[0]); System.out.println(stub.sayHello("Duke!"));} catch (Exception ex) { ex.printStackTrace(); } } }
Compiling the Client Code
Because the client code refers to classes generated by the
xrpcc
tool, be sure to run the tool before compiling the client. To compile the client, go to thedocs/tutorial/examples/jaxrpc/hello
directory and type the following:ant compile-clientPackaging the Client
To package the client into a JAR file, go to the
docs/tutorial/examples/jaxrpc/hello
directory and type the following command:ant jar-clientThis command creates the
dist\hello-client.jar
file.Running the Client
To run the
HelloClient
program, go to thedocs/tutorial/examples/jaxrpc/hello
directory and type the following:ant runThe program should display this line:
Hello Duke!The
run
target ofant
executes this command:java -classpath <cpath>
hello.HelloClient <endpoint>
The classpath includes the
hello-client.jar
file that you created in the preceding section, as well as several JAR files that are part of the JAX-RPC reference implementation. In order to run the client remotely, all of these JAR files must reside on the remote client's computer.The command-line parameter for the
HelloClient
program is the service endpoint:http://localhost:8080/jaxrpc-hello/jaxrpc/HelloIFThe
jaxrpc-hello
portion of the URL is the context of the servlet that implements theHelloWorld
service. This portion corresponds to the prefix of thejaxrpc-hello.war
file. Thejaxrpc
string matches the value of the<url-pattern>
element of theweb.xml
deployment descriptor. And finally,HelloIF
is the name of the interface that defines the service.Iterative Development
In order to show you each step of development, the previous sections instructed you to type several
ant
commands. To save time, after you've installed the application (withant install
), you can iterate through these steps:
- Test the application.
- Edit the source files.
- Execute
ant build
.- Execute
ant reload.
- Execute
ant run
.The
build
target compiles the code, runs thexrpcc
tool, and packages the client JAR file. Thereload
target updates the Web application on Tomcat with your latest changes.Optional: Packaging the Service
A service is packaged in a Web application archive (WAR), a JAR file whose contents are defined by the Java Servlet Specification. WAR files make it easy to distribute the service for deployment at various sites. For JAX-RPC, a WAR file contains the following files:
- One or more service definition interfaces
- Each service definition has a single interface, but a WAR file may contain the files for more than one service. In this example, the service definition interface is
HelloIF.class
.- One or more service definition classes that implement the interfaces
- For each service definition interface, you must provide a corresponding service implementation class (
HelloImpl.class)
.- Classes for pluggable serializers and deserializers
- This example does not require these files. (See the JAX-RPC Specification for more information.)
- Other files required by the service implementation classes
- Examples of these files are: helper classes, JPEG images, and XML documents. Because it's so simple, the
HelloImpl
class does not need any of these other files.- A deployment descriptor
- All WAR files require a deployment descriptor (
web.xml
).- An optional WSDL file that describes the service
- In a previous section, you created the
HelloWorldService.wsdl
file by running thexrpcc
tool.In addition to the preceding list of files, in the JAX-RPC reference implementation a WAR file also contains several files generated by the
xrpcc
tool: tie, servlet, and helper classes; and a server configuration file (HelloWorld_Config.properties
).To package the
HelloWorld
service, go to thedocs/tutorial/examples/jaxrpc/hello
directory and type the following:ant packageThis command creates the
dist/jaxrpc-hello.war
file. To deploy the WAR file, you copy the WAR file to Tomcat'swebapps
directory.On Tomcat, deployment and installation are similar, yet subtly different. (For more information, see the Tomcat documentation on the
Manager
application.) In this release, you must shut down and restart Tomcat every time you redeploy a WAR file. Because this requirement will slow you down during iterative development, we recommend that you use theant
targetsinstall
andreload
. The deployment operation is appropriate for production, not development, environments.
Home TOC |
![]() ![]() ![]() |