Accessing Web Services From J2EE Components: Design Details

We will consider an example application that has a J2EE[TM] component that needs to access web services of different applications. This is illustrated by the document-oriented application available under the bpcatalog project hosted at java.net. That entry has several web service applications to illustrate passing XML documents using different strategies, and each application has a service endpoint that accepts a purchase order. Each endpoint is designed with a different interface and different endpoint implementation to handle the purchase order. For this example, let's focus on the design of the client application that accesses the deployed services.

Let's take a look at the client application, and how it accesses the web service endpoint that is designed to use an XML document as a schema-defined type. This example shows how a web application with a J2EE web component such as a Servlet can access web services of other applications.

The application consists of these major entities:

This UML drawing shows the basic structure of the client application.

J2EE Client

Front Controller

The client allows the user to choose from different web services each of which illustrate a different strategy for passing XML documents. It is a set of JSP pages that lets a user fill in a form for a purchase order and submit the form. All the client requests go through the centralized front controller that controls the flow of requests. The front controller calls the request handler. Code Example 1 shows the front controller making a call to the request handler and also forwarding the request to an error page if an error occurred during the processing of the request.

     resp.setContentType("text/html");
        String responseURL = null;
        String fullURL = req.getRequestURI();
        // get the screen name
        String selectedURL = null;
        int lastPathSeparator = fullURL.lastIndexOf("/") + 1;
        if (lastPathSeparator != -1) {        
            selectedURL = fullURL.substring(lastPathSeparator, fullURL.length());
        }
        responseURL = getResponseURL(selectedURL);   

        if (selectedURL.equals("invokeservice.do")) {
            try {
                handler.handle(req,resp);

            } catch (RequestHandlerException re) {
                req.setAttribute("error_message", re.getMessage());
                responseURL = getResponseURL("error.do");
            }
        }
        getServletConfig().getServletContext()
                .getRequestDispatcher(responseURL).forward(req, resp);

Code Example 1:  Snippet From FrontController.java

Request Handler

The request handler handles the incoming requests and calls the appropriate Business Delegate to access the web service endpoint. The request handler also provides an appropriate response. The request handler sets the response message by setting an attribute on the request for use in the client JSP pages. The request handler throws a RequestHandlerException in situations where the user can take a corrective action and recover from the error. Code Example 2 shows the request handler calling the appropriate business delegate to handle the request. Note that the request handler creates a purchase order object from the request parameters.
  
          if(request.getParameter("type").equals("String")){
                ret = stringPOService.submitPO(po);
            } else if(request.getParameter("type").equals("Object")){
                ret = schemaPOService.submitPO(po);
            } else if(request.getParameter("type").equals("AnyType")){
                ret = anyTypePOService.submitPO(po);
            } else if(request.getParameter("type").equals("Any")){
                ret = anyPOService.submitPO(po);
            } else if(request.getParameter("type").equals("Attachment")){
                ret = attachmentPOService.submitPO(po);
            }           
            request.setAttribute("result", ret);   

Code Example 2: Snippet From RequestHandler.java

Business Delegate

The business delegate makes a JAX-RPC call to the endpoint that accepts a document as a schema-defined type. Code Example 3 shows the business delegate calling the web service endpoint. Note that the SchemaPOServiceBD uses the service locator pattern that is explained in the catalog entry on Updating Your Service Locator to Support Web Services.

  SchemaDefinedPurchaseOrderServiceSEI port = (SchemaDefinedPurchaseOrderServiceSEI)         
   serviceLocator.getServicePort(JNDINames.SCHEMA_SERVICE_REF, SchemaDefinedPurchaseOrderServiceSEI.class);
  ...
  String ret = port.submitPO(order);
Code Example 3:  Snippet From SchemaPOServiceBD.java

Deployment Descriptors

The client must specify a service reference in its web.xml file. Here is a snippet from web.xml:

<service-ref>
    <description>Schema defined Purchase Order Service Client</description>
    <service-ref-name>service/SchemaDefinedPurchaseOrderService</service-ref-name>
    <service-interface>
        com.sun.j2ee.blueprints.docoriented.client.objectposervice.SchemaDefinedPurchaseOrderService
    </service-interface>
    <wsdl-file>WEB-INF/wsdl/SchemaDefinedPurchaseOrderService.wsdl</wsdl-file>
    <jaxrpc-mapping-file>WEB-INF/schemadefinedpurchaseorderservice-mapping.xml</jaxrpc-mapping-file>
    <service-qname      
      xmlns:servicens="urn:SchemaDefinedPurchaseOrderService">servicens:SchemaDefinedPurchaseOrderService
    </service-qname>
</service-ref>
Code Example 4:  Snippet From web.xml

Web Service Applications Accessed by the Client Application

There are five web service applications that can be accessed by the client application discussed above. Each application has a service interface and a service endpoint that receives a purchase order XML document. The applications are similar, but they differ in the strategy for passing the XML document. These applications are each discussed in detail in the catalog entry for those topics.

The service applications are all deployed and their interface can be view in the associated WSDL file referred to in this table.

Document as a String
WSDL for the StringPurchaseOrderService
Document as a Schema-defined type
WSDL for the SchemaDefinedPurchaseOrderService
Document as xsd:anyType
WSDL for the AnyTypePurchaseOrderService
Document as a xsd:any
WSDL for the AnyPurchaseOrderService
Document as attachment
WSDL for the AttachmentPurchaseOrderService


© Sun Microsystems 2005. All of the material in The Java BluePrints Solutions Catalog is copyright-protected and may not be published in other works without express written permission from Sun Microsystems.