Level: Intermediate Jeffrey Liu, Software developer, IBM
Yen Lu, Advisory software developer, IBM
05 Aug 2003 JSR-109 facilitates the building of interoperable Web services in the Java 2 Platform, Enterprise Edition (J2EE) environment. It standardizes the deployment of Web services in a J2EE container. This article discusses the server and client programming models defined by JSR-109 and provides code examples.
A crucial objective of Web services is to achieve interoperability across heterogeneous platforms and runtimes. Integrating Web services into the Java 2 Platform, Enterprise Edition (J2EE) environment is a big step forward in achieving this goal. JAX-RPC (JSR-101) took the first step into this direction by defining a standard set of Java APIs and a programming model for developing and deploying Web services on the Java platform. JSR-109 builds upon JAX-RPC. It defines a standard mechanism for deploying a Web service in the J2EE environment, more specifically, in the area of Enterprise JavaBean (EJB) technology and servlet containers. Both of these specifications will be integrated into the J2EE 1.4 specification. Together they serve as the basis of Web services for J2EE.
This article describes how JSR-109 works with an emphasis on its benefits and illustrates some example scenarios. Before you begin, you should have a working knowledge of the following:
- WSDL
- XML
- Web services
- JAX-RPC (JSR-101)
- EJB components
Roles in Web services for J2EE development
The J2EE platform defines several roles in the application development cycle. They include: J2EE product provider, application component provider (developer), application assembler, deployer, system administrator, and tool provider. In an attempt to integrate Web services development into the J2EE platform, JSR-109 defines additional responsibilities for some of the existing J2EE platform roles. The J2EE product provider is assigned the task of providing the Web services run time support defined by JAX-RPC, Web services container, Web services for J2EE platform APIs, features defined by JAX-RPC and JSR-109, and tools for Web services for J2EE development. In the actual Web services for J2EE development flow, the developer, assembler, and deployer are assigned specific responsibilities. Figure 1 illustrates the Web services for J2EE development flow.
Figure 1. Web services for J2EE development flow
In general, a developer is responsible for providing the following:
- Web service definition
- Implementation of the Web service
- Structural information for the Web service
- Implementation of handlers
- Java programming language and WSDL mappings
- Packaging of all Web service related artifacts into a J2EE module
Figure 2 summarizes a developer's responsibilities in the server and client programming models. We will present further details on each of these programming models later in this article. Figure 2 also illustrates which specific resources each of these responsibilities touches upon. For example, the Web service definition is provided in the form of a WSDL file, the structural information of the Web service and the Java <=> WSDL mapping are defined in webservices.xml and jaxrpcmapping.xml, respectively. These two XML files are deployment descriptors defined in the server programming model.
Figure 2. Role of a developer
An assembler takes the J2EE modules developed by a developer, and assembles them into a complete J2EE application. An assembler is responsible for the following:
- Assembling modules into an Enterprise Application Archive (EAR)
- Configuring the modules within the application, for example, resolving module dependencies
- Configuring handlers
Figure 3 summarizes an assembler's responsibilities.
Figure 3. Role of an assembler
A deployer is responsible for the following:
- Resolving endpoint addresses for Web services contained in the EAR
- Generating stubs for Web services using deployment tools provided by a Web Services for J2EE product provider
- Resolving the WSDL documents used for each service reference
- Resolving port access declared by a port component reference
- Deploying the enterprise application
Figure 4 summarizes a deployer's responsibilities.
Figure 4. Role of a deployer
Benefits of JSR-109
Prior to JSR-109, the procedure for deploying a Web service was highly coupled to the destination runtime. Deploying a Web service to Apache Axis is quite different from deploying to Apache SOAP. Organizations that have deployed Web services in the past would require some strong arguments as to why they should switch to the JSR-109 deployment model given their previous investments.
The motivation for JSR-109 is to promote the building of interoperable and portable Web services in the J2EE environment. JSR-109 leverages existing J2EE technology and provides industrial standards for Web services deployment. It clearly defines requirements that a Web service for J2EE product provider must support. It allows a J2EE Web service to be configurable via XML-based deployment descriptors and hides the complexity of the system from Web service developers, assemblers and deployers. Knowing how JSR-109 works allows you to configure a J2EE Web service without having to explore and learn the implementation details of the underlying system. Finally, as JSR-109 is adopted by Web server providers, the process of migration and deployment should become a routine procedure.
 |
Server programming model
The server programming model attempts to standardize the deployment of Web services in the J2EE environment. More specifically, it defines the deployment of a servlet-based implementation bean in the Web container and the deployment of a stateless session EJB implementation in the EJB container. Both types of service implementations use a Service Endpoint Interface (SEI) -- refer to JAX-RPC (JSR-101) -- to define the method signatures of the Web service. The SEI must follow the Java programming language and WSDL mapping rules defined by JAX-RPC. The service implementation bean must implement all the methods defined in the SEI. For EJB service implementation, the SEI methods must be a subset of the EJB component's remote interface methods. The lifecycle of the service implementation bean is controlled by its associated container. In general, a service implementation bean will go through four phases: the instantiation phase, the initialization phase, the execution phase and the removal phase. The lifecycle starts off when the container creates an instance of the service implementation bean by calling its newInstance method. The container then initializes the bean via its container specific method. For a servlet-based
implementation bean, the init method is called. For an EJB implementation, the setSessionContext and the ejbCreate methods are called. The
service implementation bean is now ready to handle service requests. The lifecycle ends when the bean is removed from the container. This will result in the destroy and ejbRemove methods being called for the Web and EJB implementations, respectively. Figure 5 shows the lifecycle of a servlet-based implementation bean and Figure 6 shows the lifecycle of a session EJB component.
Figure 5. Lifecycle of a servlet-based implementation bean
Figure 6. Lifecycle of a session EJB
A service implementation bean must not carry any state as the container may create and pool multiple instances of the bean to optimize requests handling.
A Web service must be interoperable not only in the J2EE environment, but also across heterogeneous platforms. To achieve this, a WSDL is
used as the contract of a Web service. The mapping between an SEI and a WSDL file must follow the Java programming language and WSDL mapping rules defined by JAX-RPC. We will not go into details about these mapping rules as they are beyond the scope of this article. Building on top of JAX-RPC, JSR-109 defines two XML-based
deployment descriptors to specify the Web service deployment characteristics in the J2EE environment. The two deployment descriptors are
webservices.xml and jaxrpcmapping.xml.
The file webservices.xml defines the structural information of the deployed Web services. Each service defined in a WSDL file is mapped to a corresponding Web service description in webservices.xml. You can think of a Web service description as a service offered by an enterprise application. Figure 7 shows an example mapping between WSDL services and Web service descriptions.
Figure 7. Mapping between WSDL services and Web services descriptions
Each webservice-description element must contain a name, a reference to a WSDL file, a reference to a JAX-RPC mapping file and one or more port components. The Web service description name is defined via the webservice-description-name element which must be unique within webservices.xml. The wsdl-file element and the jaxrpc-mapping-file element define the location of the WSDL file and the JAX-RPC mapping file, respectively, inside the J2EE module. The remaining component for a Web service shown in the figure is the port defined by the wsdl:port element. A port component defines the server view of a Web service. It provides the access point and implementation details of a Web service. A port component is directly related to a WSDL port. Figure 8 illustrates the various relationships.
Figure 8. WSDL port to port component relationship
As shown in Figure 8, a port component references its related WSDL port via the wsdl-port element. The namespaceURI element defines the target namespace of the WSDL port (blue arrows), and the localpart element defines the local name of the WSDL port (red arrows). In addition to the WSDL port reference, every port component has a reference to the SEI and the service implementation bean.
The service-endpoint-interface element defines the fully qualified class name of the SEI, and the service-impl-bean element defines the
implementation of the Web service. For a servlet-based implementation bean, a servlet-link element is used to reference the Web service
implementation servlet defined in the Web module's web.xml. Figure 9 shows the mapping between webservices.xml and web.xml.
For an EJB implementation, an ejb-link element is used to reference the EJB defined in the EJB module's ejb-jar.xml. Figure 10 shows the mapping between webservices.xml and ejb-jar.xml.
Figure 9. WSDL port to port component relationship
Figure 10. WSDL port to port component relationship
JSR-109 also standardizes the support for JAX-RPC handlers. Handlers are similar to servlet filters defined in the
servlet 2.3 specification. In the server programming model, a handler can pre-process a request before it is dispatched to a Web service endpoint, and it can post-process a response before it is sent to a client. In general, a handler can access and modify the SOAP request header and content if the SOAP binding protocol is used. However, a handler cannot change the nature of the request message. For example, redirecting the request, changing the operation name, changing the number of message parts, or modifying part types.
Since handlers operate on a specific Web service endpoint, they are declared as part of the port component. In webservices.xml, a handler is
defined via the handler element, the handler-class element specifies the fully qualified class name of the handler. Furthermore, in the server programming model, a handler can be configured with initial parameters, SOAP headers and SOAP roles. Figure 11 shows a port
component with handlers configured.
Figure 11. Port component with handlers
The init-param elements provide initialization parameters to a handler during its initialization phase, more specifically, when a container calls the handler's init method. The soap-header elements define qualified names of SOAP headers that a handler will process. SOAP headers whose qualified names are not on the list will be ignored. The soap-role elements contain SOAP actor definitions that a handler will play as a role. This wraps up the discussion on the server programming model defined by JSR-109. The client programming model will be discussed next.
Client programming model
The client programming model provides a client view of a Web service in the J2EE environment. Run time details, such as protocol binding and transport are transparent to a client. A client invokes a Web service in the same way as invoking a method locally. JSR-109 specifies three mechanisms for invoking a Web service:
- Static stub
- Dynamic proxy
- Dynamic Invocation Interface (DII)
Static stub is a Java class that is statically bound to an SEI, a WSDL port and port component. It is also tied to a specific protocol binding and transport. A stub class defines all the methods that an SEI defines, therefore, a client can invoke methods of a Web service directly via the stub class. It is extremely easy to use and requires no configuration. However, the major disadvantage of a stub class is that the slightest change of a Web service definition may be enough to render a stub class useless, in this case, the stub class must be regenerated. A stub class is very handy in situation where you want to create a client to a production Web service that is very stable and is not likely to change its definition.
Dynamic proxy, as its name suggests, supports an SEI dynamically at run time without requiring any code generation of a stub class that implements a specific SEI. A dynamic proxy can be obtained during run time by providing an SEI. It is not as statically bound as a stub class, but it requires an SEI to be instantiated. It is invoked in the same way as a stub class is invoked. A dynamic proxy can be very useful during the Web services development cycle. A Web service's definition, more specifically, its SEI may undergo a lot of changes over a period of time. Using a stub class to test the Web service could be very tedious because a stub class needs to be regenerated every time the SEI changes. In this case, a dynamic proxy is more suitable because it only needs to be re-instantiated (rather than regenerated as in the case of a static stub) whenever the SEI changes.
DII defines a javax.xml.rpc.Call object instance for dynamic invocation. Unlike static stub and dynamic proxy, a javax.xml.rpc.Call object
must be configured before it can be used. A client has to provide the following:
- The operation name
- Parameter names, types and modes (in, out or inout)
- Port type and address of target service endpoint
- Protocol and transport properties
This is not very convenient. However, the major benefit of this scheme is that since a javax.xml.rpc.Call object is not bound to anything, the client will not be as adversely impacted by changes made to a Web service definition as the other two cases. You can think of DII as being analogous to Java reflection where access to classes, methods and fields are configured dynamically at runtime.
The client programming model works in a fashion similar to the server programming model. It uses two XML-based deployment descriptors to specify the deployment characteristics of a client. The two deployment descriptors are webservicesclient.xml and jaxrpcmapping.xml. Each Web service referenced by a client is represented by a service-ref element in webservicesclient.xml. Each service reference must have a name and a service
interface. The addition of one or more port component references provides the interface of the Web service, a wsdl-file element that points to the
service's WSDL file, a jaxrpc-mapping-file element that points to the client's Java and WSDL mapping file, and a service-qname element that defines the qualified name of the specific WSDL service being referenced. Figure 12 shows an example of a service reference definition for the Stock Quote service described in the previous section.
Figure 12. Service Reference for the Stock Quote Service
The service-interface element specifies the fully qualified class name of the JAX-RPC Service interface, and the port-component-ref element defines the SEI. A Service interface is the Java representation of a Web service in the client programming model. This interface must implement javax.xml.rpc.Service. It can be used to create a stub class, dynamic proxy or javax.xml.rpc.Call object. A stub class must implement the SEI as the SEI defines the signature of the Web service. Figures 13 and 14 show a Service interface and an SEI for the
Stock Quote service, respectively.
Figure 13. Service Interface for the Stock Quote Service
Figure 14. Service Endpoint Interface for the Stock Quote Service
Unlike the server programming model, client side handlers are associated with service references instead of port component references. They can process a request before it is sent to the service endpoint, and a response before it is returned to the client stub, proxy or javax.xml.rpc.Call object. Handlers are defined the same way as those defined for the server programming model except that they have one more configurable parameter, port names. Because they are associated with service references instead of port component references, port names can be used to associate handlers with WSDL ports. With port names, you can restrict which handlers to run when a service endpoint (WSDL port) is invoked. Figure 15 shows an example of a logging handler specified for the Stock Quote service. In this case, the logging handler will only be run when the GetQuote port is invoked, but not the Purchase port.
Figure 15. Handler for the Stock Quote Service
JAX-RPC mapping
The last piece to the JSR-109 puzzle is the mechanism for standardizing the Java <=> WSDL mappings. JAX-RPC provides the rules for these mappings while JSR-109 provides a XML-based deployment descriptor standardized representation. This deployment descriptor has no standard file
name; its name is determined by the jaxrpc-mapping-file element in webservices.xml and webservicesclient.xml. The structure of the JAX-RPC mapping file matches very closely with the structure of a WSDL file. The very first thing that you will see in a JAX-RPC mapping file is the relationship between Java packages and XML namespace. The package-mapping element provides the qualification for entities of a J2EE Web service. Figure 16 shows an example of such a mapping.
Figure 16. Java Package to XML Namespace Mapping
As discussed in previous sections, each service offered by an enterprise application is represented as a wsdl:service element in a WSDL file. In the JAX-RPC mapping file, this is represented as a service-interface-mapping element. Contained within this element, is the mapping for the fully qualified class name of the Service interface, WSDL service names, and WSDL port names. The Service interface is the Java representation of the Web service, it must implement the javax.xml.rpc.Service interface. Figure 17 shows these mapping relationships.
Figure 17. WSDL Service to Service Interface Mapping
In addition to WSDL service and WSDL port mappings, the JAX-RPC mapping file also provides mappings for WSDL bindings, WSDL port types, WSDL messages, and WSDL parts. They are mapped to the service-endpoint-interface-mapping element. As shown in Figure 18, the service-endpoint-interface-mapping element also defines the fully qualified class name of the SEI. In this case, it is sample.GetQuotePortType.
Figure 18. WSDL Port Type to Service Endpoint Interface Mapping
The most interesting ingredient of the JAX-RPC mapping file is the Java <=> XML type mapping. JSR-109 defines a standard representation for XML schema type definition and element declaration in the JAX-RPC mapping file. Both of them are mapped to the java-xml-type-mapping element. The java-xml-type-mapping element contains four crucial pieces of information. They are:
- The fully qualified class name of the JavaBean components representation of the XML schema type defined in the class-type element.
- The fully qualified XML schema type defined in the root-type-qname element.
- The scope of the XML schema type defined in the qname-scope element. Possible values are simpleType, complexType and element.
- The relationship between Java data members or JavaBean components properties and XML schema elements. The variable-mapping element defines such relationship.
Figure 19 shows a detailed example of this mapping.
Figure 19. XML Schema Type to Java XML Type Mapping
The WSDL file, server deployment descriptor (webservices.xml), client deployment descriptor (webservicesclient.xml), and JAX-RPC mapping file for the Stock Quote service example used throughout this article can be found in the Resources section of this article.
Future improvements
JSR-109 provides a preliminary standardized mechanism for deploying Web services in the J2EE environment. There is still room for future improvements, especially in the area of security. Although the demand for secure Web services is as important as having interoperable Web services, the challenge to standardize a security model across heterogeneous platform remains. As for JSR-109, it defines the security requirements that it attempts to address, but the actual standardization is deferred to a future release of the specification. Security requirements include the following:
- Credential based authentication. For example, HTTP BASIC-AUTH.
- Authorization defined by the enterprise security model.
- Integrity and confidentiality using XML encryption and XML.
- Digital signature.
- Audit.
- Non-repudiation.
Besides security improvements, there are areas where JSR-109 can improve that are directly related to JAX-RPC. For example, JAX-RPC defines an in-depth Java <=> XML serialization and deserialization framework. However, JSR-109 does not provide any support in this area. In addition, JSR-109 did not provide a complete representation for the type mapping rules defined by JAX-RPC. It lacks the support for MIME types. For example, JAX-RPC allows java.lang.String to be mapped to MIME type: text/plain, however, JSR-109 cannot support this mapping as there is no standard representation for MIME types in the JAX-RPC mapping file.
Hopefully, some of these issues will be addressed in a future release of the JSR-109 specification. This will provide a more integrated, interoperable and portable architecture for building Web services.
Conclusion
This article discussed how JSR-109 standardizes the deployment of Web service and Web service clients in the J2EE environment. It has provided code examples of how the server and client programming models work. Integrating JAX-RPC and JSR-109 into the J2EE 1.4 specification is the next
milestone for building interoperable and portable Web services in the J2EE environment.
Download | Name | Size | Download method |
|---|
| ws-jsrartcode.zip | 4KB | HTTP |
Resources
About the authors  | | | Jeffrey Liu is a software developer on the Web Services Tools Team at the IBM Toronto Lab. |
| | | Yen Lu is an advisory software developer on the Web Services Tools Team at the IBM Toronto Lab. |
Rate this page
| 
