Example 1: Deploying a Web Service WAR on Geronimo


The first example in this chapter shows how to configure and deploy a WAR file that contains a Web service on Geronimo. This particular WAR file, called progeronws.war, implements a JAX-RPC based Web service using a servlet.

The Web services has an endpoint interface that has one single method. This method returns the names of the authors of this book.

All of the code files in this Web service are in the com.wrox.progeronimo Java package. Table 14-1 summarizes the Java classes that make up the Web service and their responsibilities.

Table 14-1: Java Classes in the Servlet Web Service Example
Open table as spreadsheet

Java Class

Description

AuthorsLocator

This is the JAX-RPC Service Endpoint Interface that is implemented by the Web service. It is a Java interface.

AuthorsLister

This is the actual implementation of the Web service. This Java class implements the AuthorsLocator interface.

AuthorWS, GetAuthors, GetAuthorsResponse

JAX-RPC helper classes that are generated by JAX-RPC tool. These classes are generated using the wscompile tool in Sun’s JWSDP mentioned earlier.

The actual JAX-RPC SEI for this Web service is AuthorsLocator. For reference, the Java code is shown in the following listing.

 package com.wrox.progeronimo; public interface AuthorsLocator extends java.rmi.Remote {     public String [] getAuthors() throws java.rmi.RemoteException; }

The only thing to note is that the interface has only one method called getAuthors().

Using this interface, and a Web services code generation tool (such as wscompile from the SUN JWSDP), the WSDL for the Web service can be generated. The JAX-RPC mapping file (containing WSDL to JAX-RPC mappings) can also be generated using the tool. Web services developers are familiar with these tools and can generate these two files from the SEI readily.

These two files are vital for the deployment of the Web service. Geronimo will parse these files and generate the necessary object serializer and tie classes to support the Web service during deployment. In this example, the two files are called:

  • AuthorsWS.wsdl

  • mapping.xml

These file are mainly of interest to developers and will not be listed here.

To properly deploy the Web service, the mapping.xml file must be placed under the WEB-INF directory of the WAR alongside the standard web.xml deployment descriptor. The WSDL file, on the other hand, should be placed into a wsdl subdirectory underneath the WEB-INF directory.

Also required is a J2EE Web service deployment descriptor called webservices.xml.

The webservices.xml Web Service Deployment Descriptor

To deploy one or more Web services in Geronimo, you must provide their description in a J2EE deployment descriptor called webservices.xml. This descriptor should be placed in the WEB-INF directory of the associated Web services WAR file.

The deployment descriptor provides a description of the following:

  • The Web services that will be deployed

  • Any dependencies of the Web services to be deployed

More specifically, it describes to the container, and ties together, the following:

  • The Web service description in the WSDL file

  • The JAX-RPC mappings in the mapping file

  • The JAX-RPC SEI that the Web service implements

  • The Java bean component that actually implement the Web service

The root element of this descriptor is a <webservices> element. This element contains one or more <webservice-description> subelements. The version attribute on this root element is required and must contain the value of “1.1”, as the following XML fragment illustrates:

 <webservices xmlns="http://java.sun.com/xml/ns/j2ee" version="1.1"> ... </webservices>

Each <webservice-description> element inside the <webservices> root element describes a Web service that will be deployed by Geronimo, and it can have the subelements shown in Table 14-2.

Table 14-2: Inside the <webservice> Element
Open table as spreadsheet

Subelement

Mandatory

Description

webservice-description-name

Yes

Provides a name to reference the Web service by.

wsdl-file

Yes

The WSDL file that describes the Web service to the container.

jaxrpc-mapping-file

Yes

The JAX-RPC mapping file that maps JAX-RPC to the Web service.

port-component

Yes

The description of the port component - the component that implements the service endpoint (that is, the Web service implementation).

The webservices.xml file for this example is shown in the following listing:

 <?xml version="1.0" encoding="UTF-8"?> <webservices xmlns="http://java.sun.com/xml/ns/j2ee" version="1.1">     <webservice-description>         <webservice-description-name>Wrox Author List</webservice-description-name>         <wsdl-file>WEB-INF/wsdl/AuthorsWS.wsdl</wsdl-file>         <jaxrpc-mapping-file>WEB-INF/mapping.xml</jaxrpc-mapping-file>         <port-component>             <port-component-name>AuthorsWS</port-component-name>             <wsdl-port>AuthorsLocatorPort</wsdl-port>             <service-endpoint interface>com.wrox.progeronimo.AuthorsLocator</service-endpoint-interface>             <service-impl-bean>                <servlet-link>AuthorsServer</servlet-link>             </service-impl-bean>         </port-component>     </webservice-description> </webservices>

From this listing, you can see that the <port-component> element describes the Web service implementation in detail to the container. It can contain the subelements shown in Table 14-3.

Table 14-3: Subelements of the <port-component> Element
Open table as spreadsheet

Subelement

Mandatory

Description

description

No

A human-readable description of the Web service.

display-name

No

A name used to identify the Web service in monitoring utilities and tools.

icon

No

The name of a file containing the graphical icon to represent the Web service when displayed in monitoring utilities and tools.

port-component-name

Yes

The name used to identify this port component-Web service implementation component.

wsdl-port

Yes

The name of the Web service port, as defined in the WSDL file.

service-endpointinterface

Yes

The JAX-RPC SEI Java interface that is implemented by the Web service implementation.

service-impl-bean

Yes

The actual Java component that implements the Web service.

handler

No

An optional hook for a callback before invocation of the Web service for custom security or other logic implementation.

The <service-impl-bean> element tells Geronimo the actual Java software component that implements the Web service. This component maybe a Web-tier servlet, or a business-tier EJB. You can specify either a <servlet-link> subelement or an <ejb-link> subelement, as shown in Table 14-4.

Table 14-4: Details of <service-impl-bean>
Open table as spreadsheet

Subelement

Description

servlet-link

The link to the name associated with the servlet that implements the Web service.

ejb-link

The link to the name associated with the session EJB that implements the Web service.

The <handler> subelement is optional part of the <port-component> element. This element enables you to specify a callback handler method to process custom SOAP headers. A developer may want to do this to create customized security. If you do specify a <handler>, Table 14-5 describes the possible subelements.

Table 14-5: Content from the <handler> Element
Open table as spreadsheet

Subelement

Mandatory

Description

handler-name

Yes

Name used to reference the handler.

handler-class

Yes

Fully qualified Java class name of the handler code.

init-param

No

Optional initialization parameters for the handler.

soap-header

No

Optionally specify the SOAP header that will be processed by the handler.

soap-role

No

Optionally specify the SOAP role of the handler.

The web.xml Deployment Descriptor for JAX-RPC Web Service

The standard J2EE Web application deployment descriptor, web.xml, will declare the Java class associated with the servlet and also an application context path for the servlet. The following listing shows web.xml for this example:

 <?xml version="1.0" encoding="ISO-8859-1"?> <web-app xmlns="http://java.sun.com/xml/ns/j2ee"     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"     version="2.4">     <description>    Wrox Professional Geronimo Example     </description>     <display-name>Wrox Professional Geronimo Example</display-name>    <servlet>         <servlet-name>AuthorsServer</servlet-name>         <servlet-class>com.wrox.progeronimo.AuthorsLister</servlet-class>     </servlet>         <servlet-mapping>       <servlet-name>AuthorsServer</servlet-name>       <url-pattern>/listerservice</url-pattern>     </servlet-mapping> </web-app>

The Java class that implements the Web service, as mentioned in Table 14-1, is the com.wrox .progeronimo.AuthorsLister class. This class implements the JAX-RPC SEI called AuthorsLocator. In this web.xml file, this class is named AuthorsServer via the <servlet> element. Look back at the webservices.xml deployment descriptor and you will see that this is the name that the <servlet-link> inside the <service-impl-bean> element refers to. This is the Java class that the container will look for to handle the Web services requests.

The <servlet-mapping> element maps the Web service servlet to the /listerservice context path. This path is relative to the root context of the application. The root context of the application can be controlled via a Geronimo-specific deployment plan named geronimo-web.xml. This plan is discussed in the sections “Specifying the Context Root for the Web Service” and “Deploying the Web Service,” later in this chapter.

Optional <service-ref> for Client Access to External Web Services

As mentioned previously, both Web tier and business-tier Geronimo components may be consumers of external Web services. Although this example does not involve external Web services, the following discussion explores this optional element in the web.xml file.

Like other reference elements, <service-ref> enables a client component to look up the Web service, by name via the container-supported JNDI API. The main purpose of the <service-ref> element is to fully describe, to the container, the properties of the Web service to be accessed by the client.

To configure access for an external Web service, you will need the following:

  1. The WSDL file for the external Web service

  2. The JAX-RPC mapping file (can be generated from the WSDL using a tool)

  3. The Java JAX-RPC Service Interface implemented by the Web service

The subelements allowed in the <service-ref> element include those shown in Table 14-6.

Table 14-6: The <service-ref> External Web Service Reference
Open table as spreadsheet

Subelement

Mandatory

Description

service-ref-name

Yes

Reference name to the external service. This reference can be located via JNDI lookup by the client.

service-interface

Yes

The JAX-RPC service interface implemented by the Web service.

wsdl-file

Yes

The WSDL file that describes the Web service.

jaxrpc-mapping

Yes

The JAX-RPC mapping file that maps the Web services endpoint to JAX-RPC.

Creating a Cross-Server-Compatible Web Service WAR

Unlike other J2EE deployment descriptors, there is no Geronimo container-specific version of webservices.xml. This means that it is straightforward to create deployable WAR archives of Web services that can run on Geronimo or any other J2EE 1.4–compatible servers.

Important

There is one restriction for Geronimo that needs to be catered for when creating or generating the WSDL description file. The element in <wsdl:types> that describes the request message for an operation must have the same name as the operation itself. In this example, it would be the GetAuthors operation. Some WSDL generation tool may not fulfill this requirement, leading to the necessity to modify the generated WSDL file.

The example WAR file is created in a server-independent, J2EE 1.4–complaint manner, and should be deployable on other compatible container.

Specifying the Context Root for the Web Service

Finally, it is necessary to provide an application context root for the Web service. Like any other WAR deployment, this can accomplish by creating a Geronimo-specific deployment plan for the WAR. This plan can be geronimo-web.xml placed in the WEB-INF directory of the WAR, or it can be supplied separately to the deployer during the deployment of the WAR.

The following is the geronimo-web.xml deployment plan that is used to deploy the sample servlet-based Web services:

 <?xml version="1.0" encoding="UTF-8"?> <web-app   xmlns="http://geronimo.apache.org/xml/ns/j2ee/web-1.1"     xmlns:naming="http://geronimo.apache.org/xml/ns/naming-1.1"     xmlns:security="http://geronimo.apache.org/xml/ns/security-1.1"     xmlns:sys="http://geronimo.apache.org/xml/ns/deployment-1.1">  <sys:environment>     <sys:moduleId>       <sys:groupId>wrox</sys:groupId>       <sys:artifactId>progeronws</sys:artifactId>       <sys:version>1.0</sys:version>       <sys:type>car</sys:type>     </sys:moduleId> </sys:environment>     <context-root>/authorsws</context-root> </web-app>

This plan places the root context of the Web service to /authorsws. Back in the web.xml deployment descriptor, the servlet that implements the Web service is mapped to the context path /listerservice. Combining the root context with the context path of the servlet, the Web service can be accessed at the following URL:

http://localhost:8080/authorsws/listerservice

Within the progeronws.war, the geronimo-web.xml file is already placed under the WEB-INF directory. This alleviates the need for an external plan during deployment of the Web service.

Deploying the Web Service

Geronimo does not have a special option to deploy a Web service. Instead, it relies on existing deployment mechanisms for WAR and EAR application archives.

To deploy the servlet-based Web service, all you need to do is to deploy the progeronws.war archive. This can be accomplished via the command line and by supplying the system/manager for username/ password:

deploy deploy progeronws.war

Or, you can use the Web console to deploy the WAR file, as shown in Figure 14-5.

image from book
Figure 14-5: Deploying the Web service WAR using the Web console

Once deployed, you can try to access the WSDL of the Web service using the following URL:

http://localhost:8080/authorsws/listerservice?wsdl

If you get an XML file display in your browser similar to that in Figure 14-6, then the Web service has been deployed successfully.

image from book
Figure 14-6: Accessing the WSDL of the Web service using a browser

Trying Out the Example with a Standalone Web Service Client

To actually invoke the getAuthors() method of the Web service, you will need a Web service client.

The creation and coding of a standalone Web service client is beyond the scope of this book. The code download includes a JAX-RPC-based client that can access the example’s Web service. You will find the source code and binaries in the client subdirectory.

To run this client, you must have the following:

  1. Apache Ant 1.6.5 or later installed (from http://ant.apache.org)

  2. The JWSDP downloaded and installed (from http://java.sun.com/webservices/jwsdp/index.jsp)

Find the build.properties file in the client directory and make sure that you edit this to set the first line to point to your JWSDP installation directory. See the highlight portion of the following build .properties file fragment:

 jwsdphome=c:/jwsdp16 jwsdpshared=${jwsdphome}/jwsdp-shared jaxphome=${jwsdphome}/jaxp jaxrpchome=${jwsdphome}/jaxrpc saajhome=${jwsdphome}/saaj ....

To run the client, first ensure that the Web service is deployed on Geronimo. Then, in the client subdirectory, enter the following command:

ant run

A successful run of the client will display the name of all three authors, obtained from the servlet-based Web service hosted on Geronimo. Figure 14-7 shows the output from the client.

image from book
Figure 14-7: A successful run of the standalone Web service client

Now that you’ve successfully deployed a Web service implemented by a Web-tier servlet component, it is an opportune time to try a Web service implemented by a business-tier EJB. The next example exposes the interface of an EJB as a Web service.




Professional Apache Geronimo
Professional Apache Geronimo (Wrox Professional Guides)
ISBN: 0471785431
EAN: 2147483647
Year: 2004
Pages: 148

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net