9.2 Developing a Web Service Using Stateless Session Beans

Stateless session beans are particularly well suited for developing Web services. Web services and stateless session beans share significant features of statelessness, and they each have no specific instance identity. Because Web services endpoints that are described using WSDL are stateless that is, they do not hold state on behalf of clients across client requests they map nicely into stateless session beans.

Moreover, Web services do not have an instance-specific identity. This means that a request message from a client is not targeted at any particular instance of a Web service. Stateless session beans likewise do not have an instance-specific identity. As a result, each stateless session bean type can be mapped to a WSDL port type. Each operation within the port type maps to a business method of the stateless session bean.

The EJB 2.1 architecture, recently developed as part of the Java Community Process, explains how to develop a Web service using a stateless session bean. This chapter discusses how the EJB 2.1 architecture specifies implementing Web services with stateless session beans.

When developing a Web service using a stateless session bean, the developer should note some differences in the bean's usage. To begin with, the Web service developer does not use the stateless session bean's home interface, as the Web services model does not include the use of the factory pattern implied by the home interface. In addition, the developer models the stateless session bean's business logic interface as a JAX-RPC service endpoint interface.

A developer of a Web services interface needs to follow a few simple rules. The Web services interface extends java.rmi.Remote, and its methods throw the java.rmi.RemoteException exception.

Methods of the Web services interface use one of the following types: Java primitive types, Java classes that are JAX-RPC value types, Java mappings of MIME (Multipurpose Internet Mail Extensions) types such as java.awt.Image for the MIME type image/gif and javax.xml.transform.Source for the MIME type text/xml or arrays of any of those types. Web services interface methods are not allowed to use remote reference types.

JAX-RPC value types are Java classes that do not implement the java.rmi.Remote interface. To achieve the same semantics as Java serialization, the value type's class must also implement the java.io.Serializable interface, and the class should have only public, nontransient fields. This restriction is needed because the default mapping of JAX-RPC interfaces to WSDL maps only the public, nontransient fields.

9.2.1 Developing a New Web Service

There are two approaches for developing a new Web service using stateless session beans:

  1. Start with a Java interface for the Web service In this approach, you first create one or more Java service endpoint interfaces containing the business methods to be provided by the Web service. You then use a tool that implements the JAX-RPC standard to map the Java interfaces to a WSDL document describing the Web service. The tool generates the WSDL interface, and you program the code at the familiar level of Java interfaces, without dealing with the details of WSDL documents. Starting with a Java interface is the simplest approach for Java developers.

  2. Start with a WSDL description of the Web service In this approach, you first obtain a WSDL document for the Web service. This WSDL document might have been developed jointly with the users of the service, which might be another enterprise, or it might be a publicly available service specified by a standards body. Once you obtain the WSDL document, you use a tool that implements the JAX-RPC standard to generate the Java service endpoint interfaces one for each port type in the WSDL.

With either approach, you ultimately obtain a set of service endpoint interfaces for the Web service that you are developing. The service endpoint interface contains the business methods that you need to implement in the stateless session bean class. There will be one stateless session bean for each service endpoint interface.

The stateless session bean implementation class is implemented using the same programming model as described in previous chapters. There is only one restriction: if the bean does not have home and component interfaces local or remote then the getEJBObject/getEJBLocalObject and getEJBHome/getEJBLocalHome methods of the SessionContext interface should not be invoked. Of course, in special cases, a stateless session bean may have a Web service endpoint interface as well as remote or local home and component interfaces, in which case this restriction does not apply. One new method on the SessionContext interface is the getMessageContext method. This method returns a JAX-RPC SOAPMessageContext object, from which the bean can access the SOAP message that was sent by the client to get access to headers and other information not available from other method parameters.

For more advanced uses, a bean may also provide JAX-RPC Handler classes. Handlers are like interceptors that have access to the low-level SOAP messages. The handler's handleRequest method is invoked by the container after receiving the SOAP request message but before invoking the bean's business method. The handler's handleResponse method is invoked by the container after the bean's business method completes but before sending the SOAP response message back to the client. A handler may examine, modify, add, or remove SOAP headers in the request or response messages. Examples of handler use include getting security information such as principal names and credentials; encrypting or signing message bodies; specifying transaction context, and so forth. Handlers may set properties in the JAX-RPC MessageContext, and these properties can be obtained by the stateless session bean class. Refer to the JAX-RPC tutorial, which is part of the Java™ Web Services Tutorial, at http:/java.sun.com/webservices for more information on programming handlers.

The next step is to declare the service endpoint interface in the deployment descriptor of the stateless session bean. You do this by using the service-endpoint element in the bean's XML deployment descriptor.

To deploy the Web service in an EJB container, you also need to include a special Web services deployment descriptor, which is defined by the Web Services for J2EE specification. The Web services deployment descriptor is in the form of a webservices.xml file that is included in the ejb-jar file. This deployment descriptor ties together the Web service components the WSDL document describing the Web service, the stateless session bean, its Web service endpoint interface, any Handler classes, and a JAX-RPC mapping file into a Web service port that can be deployed into a J2EE server. The JAX-RPC mapping file, which is itself an XML document, provides details of how the Java service endpoint interface was generated from the WSDL. The mapping file contains at a minimum the package name of the Java interfaces for each namespace declared in the WSDL. It may also contain details of the mapping for each XML type into the corresponding Java type. Fortunately, developers don't need to hand-code this mapping XML file; the JAX-RPC tool used to generate the Java service interface can usually be used to create the mapping file, too, in case it is necessary to provide the complete mapping for each type.

Finally, all the Java classes and interfaces the bean implementation class, the Web service endpoint interface class, and the Handler classes and the XML descriptors WSDL document, JAX-RPC mapping file, EJB deployment descriptor ejb-jar.xml, and the Web services deployment descriptor webservices.xml are packaged together into an ejb-jar file.

When this JAR file is deployed into a J2EE container supporting Web services, the container generates all the necessary implementation classes and code for translating Web service requests sent by clients using SOAP over HTTP into invocations on instances of the stateless session bean class. The container also updates the WSDL document with the address and TCP/IP port numbers at which the Web service can be accessed. The WSDL service may be published to a registry, such as an UDDI registry, or the container may simply make the WSDL document available as a file, which can then be provided by other means to users of the service.

Java clients of the Web service use the WSDL document provided by the Web service. The clients generate a Java interface from the WSDL document, using a JAX-RPC-compliant tool, and then they program to that Java interface.

Non-Java clients must start from the WSDL description of the Web service and use language-specific tools and mechanisms to access the Web service. Section 9.4, Accessing a Web Service from an Enterprise Bean, on page 312 discusses how to access a Web service from an enterprise bean.

When you develop a Web service using a stateless session bean, you typically expose large-grained operations through the bean's Web service interface. Then, clients of the Web service access these operations through the service's interface. You may implement these large-grained operations by using a set of finer-grained session or entity beans. The stateless session bean acts as an aggregator, or facade, to the internal enterprise beans implementing the application's functionality. The stateless session bean's function is to serve the Web services view of the application; this is usually a restricted and controlled view that administrators of the enterprise carefully decide to expose to other enterprises.

9.2.2 Exposing Existing Stateless Session Bean as Web Service

The EJB architecture gives you a way to expose existing stateless session bean implementations as Web services. You can expose a stateless session bean implementation as a Web service by creating a JAX-RPC service endpoint interface from the stateless session bean's remote interface.

The JAX-RPC service endpoint interface needs to follow the rules for service endpoint interfaces described in the preceding section. This means that the interface can include only those business methods of the stateless session bean's remote interface that follow the JAX-RPC rules for allowed types. If the application's existing beans do not follow the JAX-RPC rules, one way to enable the application for Web services is to develop "wrapper" beans that do follow the rules.

Using a JAX-RPC-compliant tool, the new service endpoint interface is used to generate the WSDL document for the Web service. Clients can then use this WSDL document to access the Web service. In addition, the deployment descriptor of the existing bean needs to be enhanced to declare the new service endpoint interface. After the service endpoint interface for the existing stateless session bean has been created, the interface should be packaged into the bean's JAR file, along with the bean's home, remote, and implementation classes; the EJB deployment descriptor; and the Web services deployment descriptor, as described in the preceding section.



Applying Enterprise Javabeans
Applying Enterprise JavaBeans(TM): Component-Based Development for the J2EE(TM) Platform
ISBN: 0201702673
EAN: 2147483647
Year: 2003
Pages: 110

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