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 by `MyHelloService` is in `<INSTALL>``/jwstutorial12/examples/jaxrpc/helloservice`/.

> These are the basic steps for creating the service:

> 1. Code the service endpoint interface and implementation class.
> 2. Build, generate, and package the files required by the service.
> 3. Deploy the WAR file that contains 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>``/jwstutorial12/examples/jaxrpc/helloservice/` directory and type the following:

>     ant build

> The preceding command executes these `ant` tasks:

> - `compile-service`
> - `generate-sei-service`
> - `package-service`
> - `process-war`

> #### compile-service

> This task compiles `HelloIF.java` and `HelloImpl.java`, writing the class files to the `build` subdirectory.

> #### generate-sei-service

> The `generate-sei-service` task runs the `wscompile` tool, which defines the service by creating the `model.gz` file in the `build` directory. The `model.gz` file contains the internal data structures that describe the service. The `generate-sei-service` task runs `wscompile` as follows:

>     wscompile -define -d build -nd build
>     -classpath build config-interface.xml -model build/model.gz

> 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 the `build` subdirectory. The tool reads the following `config-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 tells `wscompile` 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 the `helloservice` 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 the `jar` command and bundles the files into a WAR file named `dist/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. The `hello-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.xml

> The class files were created by the `compile-service` target discussed in a previous section. The `web.xml` file is the deployment descriptor for the Web application that implements the service. Unlike the `web.xml` file, the `jaxrpc-ri.xml` file is not part of the specifications and is implementation-specific. The `jaxrpc-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 as `targetNamespaceBase`, are used in the WSDL file, which is created by the `process-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 the `urlPattern` value (`/hello`) is part of the service's URL, which is described in the section Verifying the Deployment).

> #### process-war

> This `ant` task runs the `wsdeploy` tool as follows:

>     wsdeploy -o dist/hello-jaxrpc.war
>     dist/hello-jaxrpc-portable.war

> 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 the `hello-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 of `hello-jaxrpc-portable.war` file into a deployable WAR file named `dist/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 the `hello-jaxrpc.war` file that was created by `wsdeploy`.

> ### Deploying the Service

> Type the following command:

>     ant deploy

> #### Verifying the Deployment

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

>     http://localhost:8080/hello-jaxrpc/hello

> The browser should display a page titled Web Services, which lists the port name `MyHello` with a status of `ACTIVE`. 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 the `HelloWorld` service. This portion corresponds to the prefix of the `hello-jaxrpc.war` file. The `/hello` string of the URL is the alias of the servlet. This string 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 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:

>     ant undeploy

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.