GreaterCause B2B Integration


To understand the B2B requirement for the Web service required by the GreaterCause application, let's recap the use cases. Once the portal provider is registered in the GreaterCause.com site by the site administrator, a portal-alliance is formed between GreaterCause.com and the portal provider. This relationship allows the portal provider to provide a pass-through or gateway component, also called a portlet, on the portal page for redirecting portal users to the GreaterCause.com site. This portlet is responsible for displaying the list of available campaigns, such as NPOs featured by the portal provider.

Note

A portlet can be implemented as part of the portal infrastructure provided by vendors, or as part of a JSP using a custom tag. It is left to the readers to decide how a portlet is integrated into a portal page. In the following discussion, we assume that the portlet is housed in a JSP page using a custom tag.

The campaigns for featuring selected NPOs are created by the portal administrator using the Create Campaign functionality offered by the GreaterCause.com site. This Create Campaign Use Case was discussed in Chapters 1 and 2, and developed in Chapters 1, 2, 5, and 7. Note that the campaigns are created and stored in the GreaterCause data store; these portal-domain– specific featured NPOs must be extracted by the respective portal domains and displayed in the portlet. The campaign list is obtained only once and cached locally by the portal domain; the portlet is subsequently populated from the local cache. The solution discussed in the chapter is part of the realization of the Cache Featured-NPOs use case discussed in Chapter 1. To access the list of featured-NPOs from the GreaterCause data store, the portlet can make a call to the FeaturedNPOQueryService Web service for retrieving the list of campaigns related to the portal domain, which it can subsequently caches in the ServletContext (the Application Scope). This is an oversimplification of the caching strategy; there are several caching strategies possible for handling caching of campaigns. FeaturedNPOQueryService is a Web service that exposes a method called getFeaturedNPOs. This method returns an array of FeaturedNPODTO objects; we have used an array because the SOAP encoding does not support the Collection API. The B2B scenario uses the request-response message interaction. The corresponding interaction semantics are depicted in Figure 8-2.

click to expand
Figure 8-2: Request-response–based interaction

WebLogic Web services implement the Java API for XML-based RPC (JAX-RPC) as part of a client JAR that client applications can use to invoke both WebLogic and non-WebLogic Web services. Although the knowledge of JAX-RPC is not essential for implementing Web services when using vendor-provided tools, you can refer to http://java.sun.com/xml/jaxrpc/index.html to read more on this subject. The generated client includes a proxy for invoking the operations of a Web service. Because the GreaterCause Web service is called FeaturedNPOQueryService, the client JAR created for accessing the Web service uses the a factory class FeaturedNPOQueryService_Impl to get the related stub implementation FeaturedNPOQueryServiceSoap_Stub using this stub which the Web service method is called. Before proceeding with implementation details, let's review the architecture provided by WebLogic for servicing client requests. The request-response message exchange pattern of Figure 8-2 is explained here.

  1. The client application sends a SOAP message by invoking the Web service method on FeaturedNPOQueryServiceSoap interface. This interface is implemented by the FeaturedNPOQueryServiceSoap_Stub. Based on the URI in the request, the server identifies the Web service and passes the XML payload to the Web service.

  2. The FeaturedNPOQueryService Web service identifies the operation to be performed. For FeaturedNPOQueryService, the server-side components generated for the Web service embed a reference to the stateless session bean Campaign on which the identified operation must be called. The implementation of the Campaign bean and pertinent use case is explained in Chapter 7.

  3. The FeaturedNPOQueryService Web service transforms the parameters in the SOAP Body using the appropriate encoding scheme to Java objects; this may require using appropriate deserializer class. For non-built-in data types, a deserializer class is created as part of Web service creation process. For our sample application, the FeaturedNPODTO deserializer class is automatically created by the vendor tool. This is discussed in the implementation section to follow.

  4. The FeaturedNPOQueryService Web service invokes the appropriate method that accesses the Campaign bean. The Campaign bean's method processes the request and creates a response.

  5. The FeaturedNPOQueryService Web service converts the response object from Java to XML using the appropriated serializer class for the array of FeaturedNPODTO objects; this serialized array of FeaturedNPODTO objects is packaged into a SOAP message response.

  6. The FeaturedNPOQueryService Web service sends the SOAP message response back to the client application that invoked the Web service.

  7. The client SOAP runtime transforms the response value in the SOAP Body using the appropriate encoding scheme to Java objects; this may require using an appropriate deserializer class. For non-built-in data types, a deserializer class is created as part of Web service creation process. For our sample application, the FeaturedNPODTO array deserializer class is automatically created by the vendor tool. This is discussed in the implementation section to follow.

The view (JSP) containing the portlet uses FeaturedNPOQueryService's client-side jar file, generated automatically by the vendor tool; which employs a WSDL document for defining the correct SOAP message semantics between the client and the server. Now that we have an understanding of the overall architecture and the interaction semantics between the client view and the GreaterCause.com domain, let's explore the FeaturedNPOQueryService Web service's implementation.

Web Service Implementation

Without using a tool like BEA WebLogic Workshop, developing a Web service in Java implies writing a large amount of code to interface with a SOAP library and possibly with WSDL or UDDI. Tools like BEA WebLogic Workshop automate the creation of Web services, handle all the SOAP protocol coding, and allow the developers to focus on implementing the business logic. For example, in the case of the FeaturedNPOQueryService Web service, we have implemented only the necessary EJB and left the generation of WSDL, the Web service client-side proxies, and server-side components to the Workshop. Therefore our implementation responsibility is reduced to proper use of EJB programming model.

This section of the document describes step-by-step the design and implementation of FeaturedNPOQueryService using BEA WebLogic Workshop. We test this service using a simple JSP. Readers who would like to create FeaturedNPOQueryService should follow the instructions for installing WebLogic platform provided in Chapter 9. The focus of our discussion is creation and consumption of a Web service, as such we spend very little time explaining the tool itself; information regarding Workshop is available at www.bea.com; a user manual also accompanies the download, and is accessible from the Workshop's Help menu option.

Design Considerations

In this section, we briefly discuss some design aspects for implementing server-side components. Let's recap our requirement: the FeaturedNPOQueryService must expose a single getFeaturedNPOs method (contract) to the outside world. The method getFeaturedNPOs accepts two parameters, a PortalID and a RegionCode, both of String type; the Web service returns an array of type FeaturedNPODTO; this array consists of all the global campaigns, and regional campaigns for the region specified in the method signature.

  • Deciding between synchronous or asynchronous operation The synchronous interaction employ the RPC-oriented semantics; in this scenario a SOAP message sent to a Web service is paired with a response from the Web service. Using the asynchronous interaction semantics the client does not expect a response from the Web service; the back-end components return void, also in-out parameters cannot be specified in the operation signature. The web-services.xml deployment descriptor uses the invocation-style attribute for the operation element for specifying this behavior; you can specify either "one-way" or "request-response"; the default value is "request-response". From the requirements, it is apparent that we will be using the default "request-response" style for a synchronous Web service.

  • Deciding the type of back-end component The FeaturedNPOQueryService uses the stateless session bean for providing the core implementation. The Campaign EJB was developed as part of the GreaterCause application in Chapter 7. This EJB employs the Session Fa ade pattern whose operation getFeaturedNPOs implements the required business logic and implements the necessary semantics for interacting with pertinent CMP Entity beans; the return value is implemented using the Data Transfer Object pattern. The J2EE component architecture used for creating the Campaign bean provides a solid foundation on which we can build the FeaturedNPOQueryService Web service; the use of EJB automatically provides several features such as security management, resource pooling, container managed transactions, and persistence services. Alternately, one can use Java classes, or a JMS message consumer or producer, such as a message-driven bean; for these alternate implementations and associated design rationale, please consult vendor documentation.

    Although the Web services cannot use stateful session beans, one can mimic a conversational Web service by creating a persistent unique ID and associate it with the conversational state stored in a data store using JDBC or Entity beans.

  • Deciding between RPC-oriented or document-oriented Document-oriented Web service operation can support only one parameter of any supported data type; this style uses literal encoding. RPC-oriented Web service operation has no restrictions on the number of parameters. The FeaturedNPOQueryService employs document-oriented semantics.

  • Data types Built-in data types are specified by the JAX-RPC specification. Using these data types offers automatic conversion between XML and the corresponding Java representation. For Web service operations that employ non-built-in data types as parameters and return values, one must create the serialization class that converts the data between its XML and Java representation. For our FeaturedNPOQueryService, the data type mapping and accompanying serializer classes are automatically generated by the vendor tool. For manually assembling serializer classes, please refer to the vendor documentation.

FeaturedNPOQueryService Implementation Using BEA WebLogic Workshop

Constructing and deploying Web services using the BEA WebLogic Workshop involves several steps. These are summarized here, followed by additional details on how the vendor tool assists in accomplishing these steps.

  1. Set up the development environment.

  2. Create the stateless EJB that will expose its method through the Web service. Deploy the EJB.

  3. Create the Web service that exposes the stateless EJB business method.

  4. Create serialization classes that convert Java objects to its XML representation and vice versa.

  5. Generate client proxies for accessing the Web service. Build a test client and verify the working of the Web service.

  6. Deploy the Web service to a production server.

Setting Up the Development Environment BEA WebLogic Server 7.0 provides templates for creating server domains that are preconfigured for offering different test and development environments. Using the Domain Configuration Wizard we must first create the WebLogic Workshop domain (for detailed insructions please refer to Chapter 9). This domain has support for the Workshop IDE that creates JAX-RPC– compliant client and server runtime components. The runtime components created by the Workshop IDE interpose between the client call on the Web service and the server-side component servicing the request.

The Workshop IDE is installed with the WebLogic server installation. Workshop requires that a Workshop domain server be up and running for creating Web services. You can configure Workshop to use a specific server as shown in Figure 8-3. After starting the workshop IDE, choose Tools/Preferences, select the paths tab and provide the werver-related information. Observe that the domain directory selected is the workshopDomain directory created by the Domain Configuration Wizard. The startWebLogic.cmd script in $(workshopDomain) directory configures the environment for use with the Workshop IDE. If a server pertaining to the domain identified in Figure 8-3 is already running, Workshop will indicate this by a green light at the bottom of the screen; the server can be started using the Tools option in the menu bar.

click to expand
Figure 8-3: Selecting the WebLogic server

Creating the Stateless EJB In Chapter 6 and 7, we created the Campaign entity bean and the Campaign stateless session bean. We simply add an additional getFeaturedNPOs method on the stateless session bean. This method returns an array of FeaturedNPODTO objects. We have used an array because the SOAP encoding does not support the Collection API. In the .jws class file (to be discussed shortly), we associate this method and associated Home and Remote interfaces with the method exposed by the Web service. For assisting the tool in identifying the Home and Remote interfaces, copy the client jar for the EJB to the ${workshopDomain}\applications\ GreaterCauseWebService\WEB-INF\lib directory.

Please refer to Chapter 9 for additional information on creating GreaterCauseEJBClient.jar file and setting up of Data Source for accessing the database server. Please ensure that the GreaterCause application is deployed before attempting to access the Web service. The GreaterCauseEJBClient.jar is supplied with the download and can also be generated using the Ant build script explained in Chapter 9.

Creating the Web Service Web services are organized by projects in Workshop; therefore, create a new project under any name; say GreaterCauseWebService. This name is subsequently used by Workshop for hot deploying a web application _appsdir_GreaterCauseWebService_ dir that is accessible by HTTP clients for testing the Web Service.

We are now ready to create Web services under this project. From the menu, select File | New | New Web Service; provide a name for the Web service, as shown in Figure 8-4; call this service FeaturedNPOQueryService.

click to expand
Figure 8-4: Setting upFeaturedNPOQueryService

Workshop creates a .jws file under the ${workshopDomain}\applications\ GreaterCauseWebService. This is the main class file that will create a link between the Web service seen by the outside world to the server component actually providing the service; a control interface CampaignControl.ctrl (an EJB Control for this example) is used within this .jws class file to provide additional information about the server-side component interfaces and the corresponding JNDI names. Workshop uses a set of custom tags based on Javadoc technology to inject specialized behavior and information, in classes and interfaces, required by Workshop in the generation of a Web service. These tags begin with @jws: and are not explained in the following discussion because they are fairly intuitive in what they represent; for complete details please refer to the vendor documentation. Figure 8-5 illustrates the directory structure once the project directory for GreaterCauseWebService is created.

click to expand
Figure 8-5: Project directories used by Workshop

Workshop hot deploys a web module in the WebLogic server; this module is named _appsdir_GreaterCauseWebService_dir, it has the context GreaterCauseWebService, and its path is defined as ${workshopDomain}\applications\GreaterCauseWebService; this is illustrated in Figure 8-6. This can be verified by accessing the WebLogic console using http://localhost:7001/console; in the left hand frame select workshopDomain | Deployments | Web Applications | _appdir_GreaterCauseWebServe_dir.

click to expand
Figure 8-6: Testing module deployed by Workshop

This testing module is used by Workshop to provide a console and test environment for the Web service before it is deployed; this is shown in Figure 8-7. The test page, also called the test view, is launched using the menu option Debug | Start, or Debug | Restart. The test page should be launched only after a Web service is successfully configured as explained in the subsequent steps.

click to expand
Figure 8-7: Launching the test environment

Workshop provides the design view for enabling creation of the EJB control and the corresponding .jws class file, as shown in Figure 8-8. The getCampaigns method was created selecting the Add Method option available on the Add Operation drop-down. The Web service is going to expose this method to the outside world. The variable "campaign" represents the CampaignControl; this control interface was created using the Add EJB Control option (Figure 8-9) available on the Add Control drop-down; the control shows all the business methods exposed by the Campaign session bean.

click to expand
Figure 8-8: Design view

click to expand
Figure 8-9: Configure CampaignControl.ctrl file

The Add EJB Control provides the dialog box shown in Figure 8-9.

Once the EJB control is configured, the CampaignControl.ctrl file defines the following interface. We use CampaignControl in the FeaturedNPOQueryService.jws class file, as shown in Figure 8-10.

click to expand
Figure 8-10: Source view for FeatureNPOService.jws

 import weblogic.jws.*; import weblogic.jws.control.*; /** *  @jws:ejb home-jndi-name="ejb/com.gc.services.managecampaigns.CampaignHome" *  @editor-info:ejb home="GreaterCauseClient.jar" bean="GreaterCauseClient.jar" */ public interface CampaignControl   extends com.gc.services.managecampaigns.CampaignHome,   // home interface           com.gc.services.managecampaigns.CampaignRemote, // bean interface           weblogic.jws.control.SessionEJBControl          // control interface {} 

Figure 8-10 shows the source view of the .jws file that ties the various components of the FeaturedNPOQueryService Web service. The .jws file and the control file are used for creating the client runtime and the server runtime classes and interfaces.

With the .jws completed, we are now ready to generate the client-side proxies and the server-side components that will provide access to the getCampaignNPOs method on the Campaign session bean. Use the menu option Debug | Build (or Debug | Start).At this time access the WebLogic console using http://localhost:7001/console; in the left hand frame select workshopDomain | Deployments | EJB. Note that Workshop has hot deployed a new ejb module GreaterCauseWebService.FeaturedNPOQueryService_EJB whose ejb-jar file path is ${workshopDomain}\mySever\.jwscompile\_jwsdir_GreaterCauseWebService\ EJB\FeaturedNPOQueryServiceEJB.jar. Peeking inside the FeaturedNPOQueryServiceEJB.jar at the specified directory will show that there are two server-side stateless EJBs that provide infrastructure support for interacting with the Web service; these EJBs have various environment entries, specified in ejb-jar.xml deployment descriptor, that are Web service–specific. One of the environment entries, ServiceURI, for the RemoteDispatcherBean provides the URI for the test view; this URI is /GreaterCauseWebService/FeaturedNPOQueryService.jws; this URI, as discussed earlier, is automatically invoked by selecting Debug | Start (or Debug | Restart) in the Workshop IDE.

At this stage, we can quickly test the Web service by using the test form in the test view, and providing the Portal ID and Region Code. The resulting array, represented in XML, is depicted in Figure 8-11. The WSDL associated with the FeaturedNPOQueryService is shown in Appendix D. This array will be embedded in the SOAP response message when the Web service is accessed.

click to expand
Figure 8-11: XMLized FeaturedNPODTO array

Optionally, one can use the "Test XML" tab to hand code the parameters sent as part of the SOAP Body element. The resulting SOAP request message and response message are shown in their entirety in Figure 8-12. Please note that to avoid naming conflict for clients using the FeaturedNPODTO class, the Web service defines the namespace http://www.GreaterCause.com as the namespace for the result set. All serializer classes use this namespace as the package name for the FeaturedNPODTO class. More on serialization classes in the following subsection.

click to expand
Figure 8-12: SOAP request and response

Unhandled exceptions in the .jws class file will result in SOAP Fault to be sent back to the client. You must add an appropriate try/catch block in the .jws file for exception handling. One of the techniques used for propagating server-side errors is to convert the exception to a meaningful code or a message and send it in the response. Recall that the SOAP:style="rpc" declaration allows specification of out or in-out parameters for an operation; for synchronous request-response message pattern using RPC-oriented style, an out parameter can hold the application-level errors. Out and in-out parameters must implement the javax.xml.rpc.holders.Holder interface as shown in the following code; for standard data type, use one of the JAX-RPC Holder classes or the built-in Holder classes provided by the server vendor.

 public String someMethod(String param1, javax.xml.rpc.holders.IntHolder param2) {     param2.value = 100;     return param2; } 

Optionally, a javax.xml.rpc.soap.SOAPFaultException (or a subclass) can be thrown to ensure that the client application receives appropriate information of a server-side exception.

Creating Serialization Classes When the data types of the parameters and return values in a Web service are of built-in data types, the server automatically converts the data between Java object and its XML representation. Built-in SOAP data types are defined by the namespace http://schemas.xmlsoap.org/soap/encoding; additional details are available in Section 5 of the SOAP specification. Serialization classes are required only for non-built-in data types. Creating non-built-in data types involves several steps. However, we have let the tool do all the work described in each of these steps.

  1. Create the XML schema data type representation to describe the structure of the non-built-in data type.

  2. Create the Java data type representation to represent the XML in terms of a Java object.

  3. Write the serialization class that performs conversion of Java objects to XML and vice versa.

  4. Create the data type mapping file that contains information about the non-built-in data type's Java class, serializer, deserializer, and so on.

The mapping file shown below in created as part of the Java Proxy generation process (explained in the next section) and is available in the proxy jar file (FeaturedNPOQueryService.jar) under the name FeaturedNPOQueryService.xml. Please note that this mapping is created only when @jws:protocol soap-style="document" is specified in the FeaturedNPOQueryService.jws class file (this is the default). A different mapping is generated when soap-style="rpc" is specified.

 <type-mapping>   <type-mapping-entry       deserializer="com.GreaterCause.www.ArrayOfFeaturedNPODTOSequenceCodec"       class-name="com.GreaterCause.www.FeaturedNPODTO[]"       xmlns:p1="http://www.GreaterCause.com/" type="p1:ArrayOfFeaturedNPODTO"         serializer="com.GreaterCause.www.ArrayOfFeaturedNPODTOSequenceCodec">     </type-mapping-entry>     <type-mapping-entry         deserializer="com.GreaterCause.www.GetCampaignsResponseCodec"         class-name="com.GreaterCause.www.GetCampaignsResponse"         xmlns:p2="http://www.GreaterCause.com/" type="p2:getCampaignsResponse"         serializer="com.GreaterCause.www.GetCampaignsResponseCodec">     </type-mapping-entry>     <type-mapping-entry         deserializer="com.GreaterCause.www.FeaturedNPODTOCodec"         class-name="com.GreaterCause.www.FeaturedNPODTO"         xmlns:p3="http://www.GreaterCause.com/" type="p3:FeaturedNPODTO"         serializer="com.GreaterCause.www.FeaturedNPODTOCodec">       </type-mapping-entry>       <type-mapping-entry deserializer="com.GreaterCause.www.GetCampaignsCodec"           class-name="com.GreaterCause.www.GetCampaigns"           xmlns:p4="http://www.GreaterCause.com/" type="p4:getCampaigns"           serializer="com.GreaterCause.www.GetCampaignsCodec">       </type-mapping-entry>     </type-mapping> 

The required components for handling non-built-in data types are provided as part of the Java Proxy creation process, which is discussed in the following section.

Generating Client Runtime and Building a Test Client Before we can compile the client code, we need to obtain the client runtime. In order to do this, use the menu option Debug | Start to launch the Web service's personalized page (the test view); as discussed earlier, this page provides testing and other supporting functions. Select the Overview tab and click Java Proxy; this will download the proxy classes required for making calls to the Web service; this client JAR file is name FeaturedNPOQueryService.jar. The client jar file includes service-specific classes, stubs, and interfaces required by the client to invoke the Web service. The classes, stubs, and interfaces are based on the implementation of the JAX-RPC API.

If the GreaterCause application is deployed, you can use a simple JSP FeaturedNPOQueryService.jsp to test our Web service; the FeaturedNPOQueryService.jar is installed in the web module's WEB-INF\lib directory. All of the WebLogic proxy classes belong to the weblogic.jws.proxies package, therefore this package is referenced in the import attribute of the page directive.

Note

Once you have generated FeaturedNPOQueryService.jar (Java Proxy), add it to GreaterCause/build/archives directory of the source distribution. The Ant build process explained in Chapter 9 will ensure that this jar file is added to the WEB-INF\lib directory. Please follow the instructions in Chapter 9 for correctly setting the domain directory in the GC.Properties file used by the Ant build script.

The view FeaturedNPOQueryService.jsp, shown here, generates the response shown in Figure 8-13. All of the WebLogic proxy classes belong to the weblogic.jws.proxies package, therefore this package is referenced in the import attribute of the page directive.

click to expand
Figure 8-13: FeaturedNPOQueryService response

 <%@ page contentType="text/html;charset=UTF-8" language="java"     import="weblogic.jws.proxies.FeaturedNPOQueryService_Impl,              weblogic.jws.proxies.FeaturedNPOQueryServiceSoap,              java.rmi.RemoteException,              com.GreaterCause.www.FeaturedNPODTO" %> <html><body> <% try {     FeaturedNPOQueryService_Impl webservice = new FeaturedNPOQueryService_Impl();     FeaturedNPOQueryServiceSoap webserviceProxy =         webservice.getFeaturedNPOQueryServiceSoap();     FeaturedNPODTO[] npoList =         (FeaturedNPODTO[])webserviceProxy.getCampaigns("ACME","NORCAL");     for (int i=0; i < npoList.length; i++) {         FeaturedNPODTO dto = (FeaturedNPODTO) npoList[i]; %>         NPO Name: <%= dto.getNpoName() %><br>         Region Code <%= dto.getRegionCode() %><br>         EIN: <%= dto.getEin() %><br>         Start Date: <%= dto.getStartDate() %><br>         End Date: <%= dto.getEndDate() %><p> <% } } catch (RemoteException ex) {     ... rest of the code ... } %> </body></html> 

For using the proxy jar outside of the WebLogic server, or for stand-alone Java clients, you need another jar file containing supporting classes. This jar is downloadable by using the Proxy Support Jar link on the Web service's page.

Deploying to a Production Server To deploy the FeaturedNPOQueryService on the production server, change the hostname element's value from localhost to the production machine in the weblogic-jws-config.xml file located in the WEB-INF directory. Compile the Web application as an EAR file and deploy the EAR file on the production server.

 <config>    <protocol>http</protocol>    <hostname>localhost</hostname>    <http-port>7001</http-port>    <https-port>7002</https-port>    <jws>        <class-name>FeaturedNPOQueryService</class-name>        <protocol>http</protocol>    </jws>     <jws>        <class-name>FeaturedNPOQueryServiceSecure</class-name>        <protocol>https</protocol>    </jws> </config> 

Note the use of https protocol in the protocol element for FeaturedNPOQueryServiceSecure. For the Web service to use SSL, make sure that the WSDL specifies https instead of http.




Practical J2ee Application Architecture
Practical J2EE Application Architecture
ISBN: 0072227117
EAN: 2147483647
Year: 2003
Pages: 111
Authors: Nadir Gulzar

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