Download
FAQ History |
![]() ![]() ![]() |
API
Search Feedback |
Creating a Web Service with JAX-RPC
This section shows how to build and deploy a simple Web service called
MyHelloService
. A later section, Creating Web Service Clients with JAX-RPC, provides examples of JAX-RPC clients that access this service. The source code required byMyHelloService
is in<INSTALL>
/jwstutorial13/examples/jaxrpc/helloservice
/.These are the basic steps for creating the service:
The sections that follow cover these steps in greater detail.
Note: Before proceeding, you should try out the introductory examples in Chapter 3. Make sure that you've followed the instructions in Setting Up.
Coding the Service Endpoint Interface and Implementation Class
A service endpoint interface declares the methods that a remote client may invoke on the service. In this example, the interface declares a single method named
sayHello
.A service endpoint 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 endpoint interface is
HelloIF.java
:package helloservice; 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 the class that implements the interface. In this example, the implementation class is called
HelloImpl
:package helloservice; public class HelloImpl implements HelloIF { public String message ="Hello"; public String sayHello(String s) { return message + s; } }Building the Service
To build
MyHelloService
, in a terminal window go to the<INSTALL>
/jwstutorial13/examples/jaxrpc/helloservice/
directory and type the following:The preceding command executes these
ant
tasks:compile-service
This task compiles
HelloIF.java
andHelloImpl.java
, writing the class files to thebuild
subdirectory.generate-sei-service
The
generate-sei-service
task runs thewscompile
tool, which defines the service by creating themodel.gz
file in thebuild
directory. Themodel.gz
file contains the internal data structures that describe the service. Thegenerate-sei-service
task runswscompile
as follows:The
-define
flag instructs the tool to read the service endpoint interface and to create a WSDL file. The-d
and-nd
flags tell the tool to write output to thebuild
subdirectory. The tool reads the followingconfig-interface.xml
file:<?xml version="1.0" encoding="UTF-8"?> <configuration xmlns="http://java.sun.com/xml/ns/jax-rpc/ri/config"> <service name="MyHelloService" targetNamespace="urn:Foo" typeNamespace="urn:Foo" packageName="helloservice"> <interface name="helloservice.HelloIF"/> </service> </configuration>The
config.xml-interface
file tellswscompile
to create a model file with the following information:
- The service name is
MyHelloService
.- The WSDL namespace is
urn:Foo
. (To understand this namespace, you need to be familiar with WSDL technology. See Further Information)- The classes for the
MyHelloService
are in thehelloservice
package.- The service endpoint interface is
helloservice.HelloIF
.(If you are familiar with SOAP and WSDL, note that by default the service will be rpc/encoded. For doc/literal, see Advanced JAX-RPC Examples.)
package-service
The
package-service
target runs thejar
command and bundles the files into a WAR file nameddist/hello-portable.war
. This WAR file is not ready for deployment because it does not contain the tie classes. You'll learn how to create a deployable WAR file in the next section. Thehello-portable.war
contains the following files:WEB-INF/classes/hello/HelloIF.class WEB-INF/classes/hello/HelloImpl.class WEB-INF/jaxrpc-ri.xml WEB-INF/model.gz WEB-INF/web.xmlThe class files were created by the
compile-service
target discussed in a previous section. Theweb.xml
file is the deployment descriptor for the Web application that implements the service. Unlike theweb.xml
file, thejaxrpc-ri.xml
file is not part of the specifications and is implementation-specific. Thejaxrpc-ri.xml
file for this example follows:<?xml version="1.0" encoding="UTF-8"?> <webServices xmlns="http://java.sun.com/xml/ns/jax-rpc/ri/dd" version="1.0" targetNamespaceBase="urn:Foo" typeNamespaceBase="urn:Foo" urlPatternBase="/ws"> <endpoint name="MyHello" displayName="HelloWorld Service" description="A simple web service" interface="helloservice.HelloIF" model="/WEB-INF/model.gz" implementation="hello.HelloImpl"/> <endpointMapping endpointName="MyHello" urlPattern="/hello"/> </webServices>Several of the
webServices
attributes, such astargetNamespaceBase
, are used in the WSDL file, which is created by theprocess-war
task described in the next section. (WSDL files can be complex and are not discussed in this tutorial. See Types Supported By JAX-RPC). Note that theurlPattern
value (/hello
) is part of the service's URL, which is described in the section Verifying the Deployment).process-war
This
ant
task runs thewsdeploy
tool as follows:The
wsdeploy
tool performs these tasks:
- Reads the
dist/hello-jaxrpc-portable.war
file as input- Gets information from the
jaxrpc-ri.xml
file that's inside thehello-jaxrpc-portable.war
file- Generates the tie classes for the service
- Generates a WSDL file named
MyHelloService.wsdl
- Packages the tie classes, the
MyHelloService.wsdl
file, and the contents ofhello-jaxrpc-portable.war
file into a deployable WAR file nameddist/hello-jaxrpc.war
Note that the
wsdeploy
tool does not deploy the service; instead, it creates a WAR file that is ready for deployment. In the next section, you will deploy the service in thehello-jaxrpc.war
file that was created bywsdeploy
.Deploying the Service
Type the following command:
Verifying the 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 ofACTIVE
. This page also lists the URL of the service's WSDL file.The
hello-jaxrpc
portion of the URL is the context path of the servlet that implements theHelloWorld
service. This portion corresponds to the prefix of thehello-jaxrpc.war
file. The/hello
string of the URL is the alias of the servlet. This string matches the value of theurlPattern
attribute of thejaxrpc-ri.xml
file. Note that the forward slash in the/hello
value ofurlPattern
is required. For a full listing of thejaxrpc-ri.xml
file, see the section, package-service.Undeploying the Service
At this point in the tutorial, do not undeploy the service. When you are finished with this example, you can undeploy the service by typing this command:
Download
FAQ History |
![]() ![]() ![]() |
API
Search Feedback |
All of the material in The Java(TM) Web Services Tutorial is copyright-protected and may not be published in other works without express written permission from Sun Microsystems.