8.6 Development guidelines

---

8.6 Development guidelines

Normally, when implementing a Router solution, the interface of the service is determined by an existing application (in ABC Electronics, the Wholesale department application). In other cases, you implement a Web service interface that encapsulates one or more operations of an existing application.

If you plan to implement a Router Pattern, all the service providers have to use the same service interface (targetNamespace, operations, etc.) and the same binding (RPC or Document, literal or encoded, etc.). If there is any difference between the service interface of the different providers, you will have to implement a request filter that transforms the incoming message to the service provider format.

Before implementing the Router solution, confirm that both the client and Web service applications are working properly. For example, try connecting them directly, without going through the gateway.

8.6.1 Implementation process

The section outlines the procedures used to implement the solutions for the ABC Electronics scenario.

Note 

This process assumes the following conditions:

• An enterprise application called WSWholesale1EAR exists. It contains an EJB module with an EJB called WSWholesale1EJB. The EJB is coded to return a delivery date for a part number supplied by the client.

• A second enterprise application called WSWholesale2EAR also exists. It is similar to the first Wholesale application.

This section will describe the process used to create Web services from the two EJBs, register them to the UDDI Registry and the Web Services Gateway, and create a client to access the newly created Web services.

This process also assumes that:

• A third enterprise application called WSRetailEAR has been created and skeleton code has been added. The only thing missing is the code that invokes the Web services through the Web Services Gateway.

Here is a summary of the necessary steps:

1. Web-service-enable the target application. The solution assumes that the Wholesale systems have implemented their delivery date applications using an EJB which can easily be converted to a Web service.

2. Register the business and services in the UDDI registry. This step is the same regardless of the stage you are implementing, however, in stage 1 and 2 (intra-enterprise) you might elect to use a private UDDI registry. In stage 3, you might consider using a commercial UDDI registry.

3. Create and deploy the filter application (stages 2 and 3).

4. Create the Web Services Gateway services and export the WSDL.

5. Export the Web services definition from the Web Services Gateway.

6. Web service enable the source application using the WSDL exported from the Web Services Gateway. The Retail system needs to have the proper information to call the Web services.

7. Test the source and target applications in the WebSphere Studio test environment.

8. Deploy the source and target applications in your WebSphere Application Server runtime environment.

8.6.2 Web service enable the target application

Figure 8-13 shows the steps involved in creating the Web services enabled target application using the stateless session bean from our sample code.

Figure 8-13: Web service development for target application

Let's walk through the process shown in Figure 8-13 for our target application.

Note 

This discussion assumes two existing applications for the Wholesale function, called WSWholesale1EAR and WSWholesale2EAR. Each has an EJB module (WSWholesale1EJB and WSWholesale2EJB). For this exercise, they both run on the same host at http://wholesale1:9081.

These directions work for both applications. We use WSWholesale1EAR as an example. To do this for Wholesale2, just substitute Wholesale2 wherever you see Wholesale1.

We have already created a simple EJB application using IBM WebSphere Studio Application Developer that looks like the structure shown in Figure 8-14.

Figure 8-14: Wholesale application

Testing the EJB using WebSphere Studio: 

A simple method of testing an EJB deployed to the WebSphere Studio test environment is to use the Universal Test Client. After you have deployed the new application to a server and started the server, simply do these steps:

1. Select the server, right-click, and select Run universal test client.

2. When the test client starts, click the JNDI Explorer link. Expand the ejb and folder so you can see a reference to the EJB home interface. Click this link.

3. To create an instance of the bean, expand EJB in the References window until you see the create() method for the EJB. Click this link.

4. In the Parameters window click Invoke, then Work With Object. An instance will be added in the References window. The new name will be EJBname_1.

5. Expand the new EJB instance to list the methods. To test a method, click it and a window will open allowing you enter input parameters and invoke the method. The results will be shown in the same window.

We can create an RPC style Web service using this EJB as follows:

1. Create a service endpoint interface for the Web service in a new package.

   1. Using WebSphere Studio, switch to the J2EE Perspective and click the Project Navigator tab.

   2. Navigate to the WSWholesale1EJB → ejbModule folder.

   3. Right-click the ejbModule folder and select New → Package. Set the package name to com.ibm.itso.wholesale.inventory. Click Finish to create the package.

   4. Create the service endpoint interface by copying the Inventory EJB remote Interface, Inventory.java, from the com.ibm.itso.ejb.inventory package to Inventory.java in the new com.ibm.itso.wholesale.inventory package.

   5. Edit the new Inventory.java file, so that it extends java.rmi.Remote, as shown in Example 8-1.

      Example 8-1: Inventory service endpoint interface

       package com.ibm.itso.wholesale.inventory; public interface Inventory extends java.rmi.Remote {    public String getDeliveryDate(String partNo)       throws java.rmi.RemoteException; } 

2. Open a command window and change to WSWholesale1EJB \ejbModule in your Studio workspace folder.

3. Generate a Web Services Description Language (WSDL) file from the service endpoint interface. We used the command shown in Example 8-2. Note that this command assumes we will use /Wholesale1 as the root context and services/InventoryWholesale1 to access the EJB.

   Example 8-2: Generating WSDL using Java2WSDL

    c:\WebSphere\appserver\bin\java2wsdl -verbose -implClass com.ibm.itso.ejb.inventory.InventoryBean -location http://wholesale1:9081/Wholesale1/services/InventoryWholesale1 -output c:\Workspace\WSWholesale1EJB\ejbModule\META-INF\wsdl\Wholesale1Direct.wsdl -style rpc -use literal -voidReturn ONEWAY com.ibm.itso.wholesale.inventory.Inventory 

4. Using the WSDL file created in the previous step, generate the Web services deployment descriptors and classes using the WSDL2Java tool. We used the command shown in Example 8-3.

   Example 8-3: Generating server deployment descriptors and classes using WSDL2Java

    C:\WebSphere\AppServer\bin\WSDL2Java -verbose -role server -container ejb -output C:\Workspace\WSWholesale1EJB\ejbModule c:\Workspace\WSWholesale1EJB\ejbModule\META-INF\wsdl\Wholesale1Direct.wsdl 

   Note 

   The deployment descriptors and class files will not be regenerated when the tool is re-run, unless the existing files have been removed first.

5. Right-click the EJB project and select Refresh. You should see the generated files shown in Figure 8-15.

   
   Figure 8-15: Generated files

   The webservices.xml deployment descriptor defines the set of Web services that are being deployed in the Web service-enabled J2EE container.

6. Navigate to WSWholesale1EJB → ejbModule → META-INF and edit webservices.xml. Set the ejb-link element to Inventory, as shown in Example 8-4.

   Example 8-4: Updating webservices.xml

    ...             <service-impl-bean >                <ejb-link>Inventory</ejb-link>             </service-impl-bean> ... 

   The ejb-link element corresponds to the ejb-name element of the required EJB, as defined in ejb-jar.xml.

7. Run the endptEnabler command line tool to add an HTTP router module to the EAR file.

   Tip 

   This step is only required if the Web service is implemented in an EJB module.

   In WebSphere Studio V5.1, right-click the EAR project, and select Web Services → Endpoint Enabler from the pop-up menu.

   Note 

   Alternatively, you could also use the command shown in Example 8-5. To do this you first need to export the WSWholesale1EAR project to an EAR file:

   1. Right click the WSWholesale1EAR project and select Export....

   2. Select EAR file and click Next.

   3. Select the destination you want the EAR file to be exported to, for example:

       C:\WebSphere\AppServer\installableApps\WSWholesale1EAR.ear 

   4. Click Finish.

   5. Run the endptEnabler command:

       C:\WebSphere\AppServer\bin\endptEnabler WSWS2004I: IBM WebSphere Application Server Release 5 WSWS2005I: Web Services Enterprise Archive Endpoint Enabler Tool. WSWS2007I: (C) COPYRIGHT International Business Machines Corp. 1997, 2003. WSWS2006I: Please enter the name of your EAR file: WSWholesale1EAR.ear WSWS2003I: Backing up EAR file to: WSWholesale1EAR.ear~ WSWS2016I: Loading EAR file: WSWholesale1EAR.ear WSWS2017I: Found EJB Module: WSWholesale1EJB.jar WSWS2029I: Enter http router name for EJB Module WSWholesale1EJB [WSWholesale1EJB_HTTPRouter.war]: WSWholesale1EJB_HTTPRouter.war WSWS2030I: Enter http context root for EJB Module WSWholesale1EJB [/WSWholesale1EJB]: Wholesale1 WSWS2024I: Adding http router for EJB Module WSWholesale1EJB.jar. WSWS2036I: Saving EAR file WSWholesale1EAR.ear... WSWS2037I: Finished saving the EAR file. WSWS2018I: Finished processing EAR file WSWholesale1EAR.ear. 

   Example 8-5: RouterBean.java

    public FilterAction filterRequest(WSIFRequest req, WSIFResponse resp)    throws FilterException, WSGWException {    try {       InitialContext initialContext = new InitialContext();       RoutingHome routingHome =          (RoutingHome)PortableRemoteObject.narrow(                initialContext.lookup("websphere/WSGW/Routing"), RoutingHome.class);       RoutingRemote routing = routingHome.create();       WSIFMessage message = req.getIncomingMessage();       String partNumber = ((JROMStringValue)message.getObjectPart("partNo")).getValue();       if (Integer.parseInt(partNumber)<100) {          routing.setSelectedTargetServiceIdentity(req, "InventoryServiceWholesale1");       } else {          routing.setSelectedTargetServiceIdentity(req, "InventoryServiceWholesale2");       }    } catch (Exception e) {       System.out.println(e.getMessage());       e.printStackTrace();    }    return null; } 

The endptEnabler tool makes the following changes to the EAR file:

• Adds a Web module to the EAR file that contains the HTTP router for the EJB module and sets the context root for the Web module in application.xml.

  Note 

  If you used the WebSphere Studio Endpoint Enable wizard, the context root for the Web module is automatically chosen for you. Open the EAR deployment descriptor and if necessary, alter the context root to match the context you used earlier in the -location attribute of the Jave2WSDL command (see Example 8-2 on page 172. In this example, the context is /Wholesale1.

  

• Adds servlet and servlet-mapping elements to the Web module deployment descriptor. These elements map the Web service endpoint URL to the Web services router servlet, and are added for each Web service in the module.

  Note 

  The URL mappings must match the values you used in the -location attribute of the Jave2WSDL command (see Example 8-2 on page 172) - in this example, "services/InventoryWholesale1".

  

• Adds a routerModule element to ibm-webservices-bnd.xmi in the EJB module.

The EAR file is now ready to deploy in the IBM WebSphere Application Server V5.0.2 runtime.

8. Generate the EJB deployment code:

   1. Select, then right-click the WSWholesale1EAR project, and select Generate → Deploy and RMIC Code from the pop-up menu.

   2. In the Generate Deploy and RMIC Code window, click Select all to select all the EJBs, then click Finish.

Testing the Web service using WebSphere Studio: 

A simple method of testing the Web service you have created is to use the Web Services Explorer. To use the Web Services Explorer, right-click the WSDL file for the Web service and select Web Services -> Test with Web Services Explorer. The Explorer will start in a Web browser window. From there you can select the Web service method you want to test, or add / change the Web service endpoints.

8.6.3 Register the services in the UDDI Registry

In this scenario, the private UDDI Registry shipped with the WebSphere Application Server Network Deployment and Enterprise packages was used. To make Web services available through the private UDDI registry, follow these steps:

1. Install the UDDI Registry. The UDDI Registry used in this scenario was installed from and deployed on WebSphere Application Server Enterprise V5.0.2 with the 5021 fix applied.

   Once the application server and the Web services features have been installed and brought up to the correct fixpack level, you will need to complete the installation of the UDDI Registry using the instructions in the InfoCenter.

   The UDDI Registry is an enterprise application that runs on an application server, so this process includes creating a database for the UDDI Registry to store data in and installing the UDDI Registry application. Scripts are provided to do this.

2. Register the business.

3. Add a technical model of the Web service.

4. Add the service to the business, associating the correct technical model to the service.

Register the business

The first step in setting up the UDDI Registry is to publish the business in the registry.

1. Open the UDDI registry console:

   (http://uddi.itso.ral.ibm.com:9080/uddigui/)

2. Select the Publish tab and click Add a business under the Advanced Publish menu.

3. Enter the business name, select a language, and click the Add button to the right of the Language field. This allows you to add multiple names for the same business. It doesn't actually publish the business yet. That doesn't happen until you click the Publish Business button, once you have completed the rest of the fields.

4. Add a description if you like and click the Add button to the right.

   
   Figure 8-16: Register the business

5. Click Publish Business. This causes the business to be published to the UDDI Registry, and a page is displayed showing the business details.

Add a technical model

Add a technical model (tModel) for Wholesale 1 by doing these steps:

1. Select the Publish tab and click Add a technical model under the Advanced Publish menu.

2. Enter the following values: (where there is a blue Add link, you must click that to add the data you enter in the fields to the left).

   • Name: InventoryWholesale1

   • Description: Inventory of Wholesale 1 (click Add)

   • Locator (describe the technical model with taxonomies)

     • Locator Type: unspsc

     • Locator Key name: (blank)

     • Locator Key value: wsdlSpec

     (Click Add)

   • Overview URL (a URL pointing to an overview document, a description of the document, and a Language field):

     http://wholesale1:9081/Wholesale1/services/InventoryWholesale1/wsdl/Wholesale1Direct.wsdl

   
   Figure 8-17: Add a technical model

3. Click the Publish Technical Model link to create the technical model in the UDDI Registry.

Add a service to the business

Follow these steps:

1. Select Show owned entities under the Publish tab.

2. Locate the business and click the Add service button.

3. Enter the relevant data (click Add where applicable):

   • Service Name: InventoryWholesale1

   • Description: Inventory Service of Wholesale1

   • Access points (points to the Service):

   • URL Type address: wholesale1:9083/Wholesale1/services/InventoryWholesale1/wsdl/Wholesale1Direct.wsdl

   • Locator (add references to taxonomies to the service)

   • Technical Model (associate existing tModels to the Service): InventoryWholesale1

   
   Figure 8-18

4. After completion of those areas required, click the Publish Service button to publish the service to the UDDI Registry with the current form contents.

8.6.4 Create the filter

A filter is simply an EJB running in an enterprise application. To create the filter, do the following steps with WebSphere Studio:

1. Create an enterprise application. (ITSORouterApp in the scenario).

2. Create an EJB project. (ITSORouterAppEJB in the scenario).

3. Create a session bean. (RouterBean in the scenario). The easiest way is to use the J2EE Hierarchy view in the J2EE perspective. Select the Session Beans folder, right-click, and select New->Session Bean. The values we used are shown in Figure 8-19 and Figure 8-20.

   
   Figure 8-19: Create a session bean for the filter

   
   Figure 8-20: Create a session bean for the filter

   When you create an EJB filter, you have to use the following interfaces:

   • com.ibm.wsgw.beans.FilterHome

   • com.ibm.wsgw.beans.FilterRemote

Tip 

To develop the filter, you need to have the wsgwejb.jar, which comes in the <WAS_Enterprise_HOME>/lib directory in your build path.

Important: 

The support of filter programming is supported only in WebSphere Application Server Enterprise.

Figure 8-21 shows the results of the Enterprise Bean wizard.

Figure 8-21: Developing a filter with WebSphere Studio

A filter can get the list of potential target services from the Web Services Gateway Routing service. The Home object for this service must implement the com.ibm.wsgw.beans.RoutingHome interface and be located in JNDI at websphere/WSGW/Routing.

The sequence of events is as follows:

1. The filter is called with a WSIFRequest.

2. The filter obtains the list of potential target services from the Routing service.

3. The filter selects the target service.

4. The filter calls the Routing service to set the target service (note that doing this clears any prior selection of a target service's port).

Each target service is identified by its unique target service definition location and target service identity information (which might not be unique). To select the target service, your filter can either get the table of mappings from the target service location to identity information, then choose a target service to use; or it can call setSelectedTargetServiceIdentity with the required identity string (relying on the target service identity information being carefully defined).

The routing service then selects the first target service it finds (for the current gateway service) with identity information matching that specified (using String.equals()).

Note 

When you use Routing to set the target service or the target port, the Routing service updates the request context. Because the request context has changed, you then need to set the request object in the FilterAction object that you return from the filterRequest method.

The filter can also use the Routing service to select the target port for the service invocation.

Example 8-5 shows how to determine the target service using a filter.

Note that the target services identified here haven't been defined to the Web Services Gateway yet. Later, when you define them, the target service identity information (see Figure 8-26 on page 190) must match with the filter code.

Deploy the filter

To deploy the filter, you have to install the enterprise application that contains the filter. Later, you will also need to configure the filter to the Web Services Gateway. Follow these steps:

1. Export the EAR file from WebSphere Studio to the <was_install>/installableapps directory.

1. Using the WebSphere administrative console for server1 (where the Web Services Gateway application is installed), select Applications->Install New Application.

2. Browse to the ear file (ITSORouterApp for our scenario), select it and click Next.

3. As you proceed through the application installation, the steps may vary depending on the features of the application (whether it uses security, a database, etc.). As you go through the install, make sure the JNDI name for the EJB is correct.

Refer to Figure 8-22.

Figure 8-22: Installing the filter application - panel 3

4. Complete the installation and start the application.

8.6.5 Define the services and filter to Web Services Gateway

Before you define a Web service to the Web Services Gateway, deploy the resources (channels, filters, UDDI references and security bindings) that the Web service uses.

1. Install the Web Services Gateway. The Web Services Gateway used in this scenario was installed from and deployed on WebSphere Application Server Enterprise V5.0.2 with the 5021 fix applied.

   Once the application server and the Web services features have been installed and brought up to the correct fixpack level, you will need to complete the installation of the Web Services Gateway using the instructions in the InfoCenter.

   The Web Services Gateway is an enterprise application that runs on an application server, so this process includes creating a database for the Web Services Gateway to store data in, and installing the Web Services Gateway applications. Scripts are provided to do this.

2. Perform the initial configuration of the gateway, including the namespace URI. If you change the namespace URI, you break the link back to the Web Services Gateway for every Web service that you have already deployed. So you must set the namespace URI before you deploy any Web services.

3. Add a channel to handle incoming SOAP requests.

4. Add a reference to the UDDI Registry.

5. Deploy the Web services to the gateway. If you aren't using a filter to route service requests, you will need to create one service for each service provider (InventoryWholesale1 and InventoryWholesale2). If you are using a filter to route requests, you will only need to create one service, with two target services (InventoryWholesale1 and InventoryWholesale2).

Initial configuration

1. Open the Web Services Gateway administration console at:

   http://wsgw_host:9080/wsgw/admin/

2. Select the Configure option under Gateway.

3. Enter the following values (Figure 8-23):

   • Namespace URI for services: urn:ibmwsgw. (default)

   • WSDL URI for exported definitions: http://wsgw_host:port/wsgw

   
   Figure 8-23: Initial gateway configuration

4. Click Apply Changes.

Add a channel

To deploy a channel for incoming SOAP requests (Figure 8-24):

1. Select Deploy under the Channels menu option.

2. Enter the following values:

   • Channel Name: SOAPHTTPChannel1

   • Home Location: SOAPHTTPChannel1Bean

   • End Point Address: http://wsgw:9080/wsgwsoaphttp1

3. Click OK.

Figure 8-24: Add a channel

Add a UDDI reference

To deploy a UDDI Reference (Figure 8-25):

1. Select Deploy under the UDDI References menu option.

2. Enter the following values:

   • Name: UDDIPrivateRegistry

   • inquiryURL: http://uddi:9080/uddisoap/inquiryapi

   • publishURL: http://uddi:9080/uddisoap/publishapi

   • userName: authorized user ID

   • password:

3. Click OK.

Figure 8-25: Add a UDDI reference

Deploy the Web services

To deploy a Web service (Figure 8-26), follow these steps:

1. Select Deploy under the Services menu option.

2. Enter the appropriate values for the service. In this scenario, the values used for the InventoryWholesale1 service were:

   • Gateway Service Name: InventoryWholesale1

   • Message part representation: Generic classes

   • Channels: SOAPHTTPChannel1

   • UDDI References: UDDIPrivateRegistry

   • WSDL Location: uddiReference,serviceKey

     The service key can be obtained in the UDDI Registry by switching to the Publish tab and selecting:

     Show owned entities -> ABC Electronics/Show services -> InventoryWholesale1.

   • Location Type: UDDI

   • Target Service Name: InventoryService

   • Target Service Namespace: http://inventory.wholesale.itso.ibm.com

   • Target Service Identity Information: InventoryServiceWholesale1

   • Business Key: Business Key (for example, BC01B8BC-7A9F-4F56-86FE-61AB5D61FE75)

     The business key can be obtained in the UDDI Registry by switching to the Publish tab and selecting:

     Show owned entities -> ABC Electronics/Show services -> InventoryWholesale1

Figure 8-26: Deploying a service - part 1

Figure 8-27: Deploying a service - part 2

Note that the target service identity information matches the code in the filter (see Example 8-5 on page 184).

Note 

If you are not using a UDDI Registry, you will need to make the WSDL file available to the gateway. A simple way to do this is to create a new folder for the WSDL files in the application folder for the Web Services Gateway application. For example:

<WAS_HOME>/installedApps/<node_name>/wsgw.server1.<node_name>.ea r/wsgw.war/wsdl

Then copy the WSDL file from the WebSphere Studio workspace to the new folder.

When defining the service, simply select URL as the location type and enter the URL for the wsdl file. In this case, the URL would look like:

http://<wsgw_node>:9080/wsgw/wsdl/<wsdl_file>.wsdl

Repeat the process to deploy each service. For our stage1 application, both InventoryWholesale1 (Figure 8-28) and InventoryWholesale2 (Figure 8-29) need to be deployed.

Figure 8-28: Service for Wholesale1

Figure 8-29: Service for Wholesale2

In stage 2, only one service is deployed (InventoryWholesale) but has two target services. To create a service with multiple target services, create a new service using the method just described.

During the process you will add the first target service. To add two service targets to the same service definition, you first create a service and specify one of the services as the target (for example, Wholesale1). Once the service is created, you can list the service and add a second target service (Wholesale2).

Then, after creating the service, add the second Web service target.

3. Click Apply Changes to update the service (Figure 8-30).

   
   Figure 8-30: Two target services for one service

Configure the filter

To configure the filter (Figure 8-31), follow these steps:

1. Select the Deploy option under the Filters menu.

2. Enter the filter name and the home location (JNDI name) of the EJB Filter and click OK. The home location is the same as specified during the filter install (see Figure 8-22 on page 185).

3. Find the service you want to add the filter to (Wholesale) by selecting List under the Services option, then selecting the service.

4. Add the filter to the service by selecting the filter name in the Request Filter field.

   You can add multiple filters to a service (Figure 8-32). The position selected determines the order in which the filters are executed. In this instance, there is one filter, so the position is "At the end". Click Add.

   
   Figure 8-31: Deploy the filter to the gateway

   
   Figure 8-32: Adding a filter to a service

8.6.6 Export the Web service definition

The Web Services Gateway dynamically generates WSDL files for the Web services it is serving (one file for the interface and one file for the implementation). You have to copy this definition to build your client application (in our case, the Retail application).

In the Exported WSDL Definitions section, there are two pairs of WSDL links. Both pairs link to (a) the external WSDL implementation definition, and (b) the external WSDL interface definition:

• To view details of the associated external WSDL for the service, use the first pair.

• To return the WSDL for use by application programs that need the WSDL definitions for the service, use the second pair.

If there is an error generating the WSDL, then a blank page is returned.

Note 

To help your service users locate the WSDL documents for services that are deployed to the Web Services Gateway, the gateway also supports the WS-Inspection specification. To open a WS-Inspection document which contains references to the WSDL documents for all of the gateway-deployed services, you issue an HTTP GET against:

• http://host:port/wsgw/wsinspection.wsil

Here, host and port are the host name and port number that your HTTP server is listening on.

Export the WSDL from the Web Services Gateway

From the Web Services Gateway admin console, follow these steps:

1. You will need a place in the application to store the WSDL files (Figure 8-33). From WebSphere Studio, create a new folder called wsdl under WSRetailWeb/WebContent/WEB-INF.

   
   Figure 8-33: View the WSDL

2. Select the service (for example, InventoryWholesale1) and right-click External WSDL implementation definition.

   Select Save Target As.. and save the file as InventoryWholesale1WSGW-Impl.wsdl file in the WSRetailWeb/WebContent/WEB-INF/wsdl folder (Figure 8-34).

   
   Figure 8-34: Create a WSDL file in WebSphere Studio

3. Follow the same steps to save the external WSDL interface definition as InventoryWholesale1WSGW-Interface.wsdl.

4. Repeat the process to create the InventoryWholesale2WSGW-Impl.wsdl and the InventoryWholesale2WSGW-Interface.wsdl files.

8.6.7 Web service-enable the source application

Figure 8-35 shows the steps involved in Web services-enabling the source (client) application.

Figure 8-35: Web service development for source application

Let's walk through the process shown in Figure 8-35 for our source application.

When developing a Web services client, you must have access to a server application. This could be developed by a separate department within your organization, which will supply the WSDL file defining their server. In our example, we use the target application described in 8.6.2, "Web service enable the target application" on page 170.

Web service-enabling our source application is simply a matter of generating the required deployment descriptors and proxy classes from the gateway-generated WSDL files for the target application.

Note 

If you are connecting directly to the Web service without going through the Web Services Gateway, the WSDL comes directly from the target system. If you are using a Web Services Gateway, the WSDL is created and stored at the Gateway.

1. In the previous process, you exported the WSDL files from the Web Services Gateway to your source application. Before proceeding it is a good idea to test the operation of the Web service, both directly and through the gateway. It is simple to do this using the Web Services Explorer in WebSphere Studio.

   1. Right-click the -Impl WSDL file in the source application, and select Web Services → Test with Web Services Explorer (Figure 8-36).

      
      Figure 8-36: Using the Web Service Explorer to test the Web service

   2. Select getDeliveryDate and enter a part number.

   3. Click Go.

   Make sure the results are correct. If there are any problems, repeat the process using the WSDL from the target application to see if the problem lies with the gateway definitions or with the Web service itself.

   Once you are sure the Web service is working, continue by creating the client code.

2. Using WebSphere Studio, switch to the J2EE Perspective and click the Project Navigator tab. Navigate to the WSRetailWeb → WebContent → WEB-INF →wsdl folder.

3. Select the WSDL file, right-click and select Web Services →Generate Client.

   Note 

   The WSDL files determine how the Web service will be accessed. If you are accessing the service directly, you will have a single WSDL file generated by the target application. If you are using a Web Services Gateway, you will select the implementation WSDL file generated at the gateway. Our sample application allows the user to select whether to access Wholesale1 or Wholesale2 directly, using the gateway, or via the filter. The following process illustrates the client generation using the WSDL for Wholesale1 generated at the gateway.

   4. Select Java Proxy as the proxy type (default) and click Next.

   5. Select Use Defaults for the client-side environment selection and click Next.

   6. Make sure the correct WSDL file is selected. If you are using WSDL files generated at the Web Services Gateway, select the implementation WSDL file. It has a reference to the interface WSDL file.

   7. Take the defaults on the next panel (generate proxy) and click Finish.

   The generated files are highlighted in Figure 8-37.

   
   Figure 8-37: Generated client binding files and deployment descriptors

4. In our sample application, we will eventually offer several options to the user. These options allow the user to select Wholesale1 or Wholesale2 either directly or via the gateway. In order to do this, we repeated this process for each option and as each client code portion was generated, we renamed the classes to a unique name. To do this, we used the rename option for the class and selected each option beneath. This ensured that every reference to the class was changed, including those in the binding files (Figure 8-38).

   
   Figure 8-38: Renaming the classes

5. Note that the webservicesclient.xml deployment descriptor defines the JNDI name for accessing the Web service and the associated service endpoint interface to be used. This descriptor is generated automatically be the Web Services Client wizard (Figure 8-39).

   
   Figure 8-39: Service references for Web services

6. Add client application code to invoke the Web service on the target application.

   To invoke getDeliveryDate on the target application, we added the code shown in Example 8-6. We added this code to the com.ibm.itso.command. WSGWW1WebServiceBean command bean in our WSRetailWeb module.

   Example 8-6: Web service client code for getDeliveryDate

    package com.ibm.itso.command; import ibmwsgw.Wholesale1; import java.net.URL; import javax.naming.*; import com.ibm.itso.wholesale1.inventory.Inventory; public class WSGWW1WebServiceBean extends CommandBean { ...    public String getDeliveryDate(String partNumber) throws Exception {       String deliveryDate = null;       try {          InitialContext initialContext = new InitialContext();          Wholesale1 inventoryWholesale1 = (Wholesale1) initialContext.lookup(                          "java:comp/env/service/Wholesale1");          //Request the Service Endpoint from the Service          Inventory inventory = inventoryWholesale1.getInventorySOAPHTTPBindingPort();          //Get the quote          deliveryDate = inventory.getDeliveryDate(partNumber);       } catch (Exception e) {          writeToLog("Exception: " + e.toString());          throw new Exception(e.toString());       }       writeToLog("Exit - getDeliveryDate");       return deliveryDate; } 

Changing the Web service endpoint URL

By default, the endpoint proxy class (InventoryServiceLocator in our example) will use the endpoint address specified in the WSDL file when the proxy class was originally generated. It is likely that the endpoint address used will change over time, as the client application moves though the development, test, and production environments, for example. You can set the endpoint address in several ways:

1. When getting an instance of the generated endpoint class from the Service interface, you can optionally pass an endpoint address that will override the default address obtained from the WSDL file. Compare the following approach with that used in Example 8-6 on page 203:

       // Request the Service Endpoint from the Service    //  overriding the default endpoint address    Inventory inventory = inventoryService.getInventory(new java.net.URL(       "http://localhost:9080/WSWholesale1EAR/services/Inventory")); 

2. When deploying your client application to WebSphere Application Server, you can specify the Deploy WebServices option, as shown in Figure 8-40.

   
   Figure 8-40: Deploying Web services using the WebSphere administrative console

   WebSphere will regenerate the deployment code based on the Web services client deployment descriptors, updating it with the current endpoint address from the WSDL file. Similar to EJB deployment, this only needs to be performed when the deployment details have changed.

   Example 8-7 shows how the endpoint address is specified in the WSDL file for our Inventory service.

   Example 8-7: Setting the endpoint address in the WSDL file

    ... <wsdl:service name="InventoryService">     <wsdl:port name="Inventory" binding="intf:InventorySoapBinding">       <wsdlsoap:address location="http://localhost:9080/ITSOWholesale1/services/Inventory"/>     </wsdl:port>   </wsdl:service> ... 

The second option is recommended in most cases. Using this method, the endpoint address can be specified at application packaging/deployment time using the Web services deployment features of the application server.

8.6.8 Best practices

This section covers best practices and recommendations.

Place all of the WSDL in one file

WebSphere Studio V5.0 creates three files for the WSDL (interface, binding, implementation). WebSphere Studio V5.1 puts the WSDL into a single file. If you are using WebSphere Studio prior to V5.1, it is a good idea to combine the WSDL into one file to eliminate any problems the gateway might encounter parsing include statements.

Handling SOAP fault messages

Example 8-8 shows the recommended way to create and return a SOAP fault message from the GatewayFilter.filterResponse method.

Example 8-8: Creating and returning a SOAP fault message from a filterResponse method

 public FilterAction filterResponse(WSIFRequest wsifRequest, WSIFResponse wsifResponse)       throws FilterException, WSGWException, RemoteException { // Construct the fault message WSIFMessage faultMessage = new WSIFDefaultMessage(); faultMessage.setObjectPart(WSIFConstants.SOAP_FAULT_ACTOR,"mySoapFaultActor"); faultMessage.setObjectPart(WSIFConstants.SOAP_FAULT_CODE,"mySoapFaultCode"); faultMessage.setObjectPart(WSIFConstants.SOAP_FAULT_STRING,"mySoapFaultString"); faultMessage.setObjectPart("stackTrace","myStackTraceDetails"); faultMessage.setObjectPart("otherDetails","myOtherDetails"); // repeat faultMessage.setObjectPart("aaaa","bbbb"); for each additional detail element // Set the fault message into the wsifResponse object wsifResponse.setFaultMessage(faultMessage); wsifResponse.setIsFault(true); // Return the updated response in the filterAction object FilterAction filterAction = new FilterAction(); filterAction.setUpdatedResponse(wsifResponse); filterAction.setContinueProcessing(false); return filterAction; } 

Handling exceptions for the Web Services Gateway

During normal processing of a Web service invocation, a fault message might be generated by the target service, and is passed back to the channel to be sent to the originator. As far as the Web Services Gateway is concerned there is no difference between processing a normal output message and processing a fault message.

But when an exception occurs during processing of a request, the channel needs some way to decide what to do with the exception. What is needed is a service that provides a pluggable handler that can look at the message, exception and other information to decide whether the exception should be thrown back to the originator, or whether a fault message should be constructed.

This service is not provided with the Web Services Gateway, but the gateway does contain an interface to encapsulate such a service. The ExceptionHandler interface allows channels to call an exception handling service, and allows the exceptions to be reported to a third party for analysis.

The Home object for this service must implement the com.ibm.wsgw.beans.ExceptionHandlerHome interface and be located in JNDI at websphere/WSGW/ExceptionHandlerService.

Capturing Web service invocation information

The Web Services Gateway has not implemented a service that stores operational messages, but it does contain an interface (the MessageWarehouse interface) to encapsulate such a service. This interface is driven by channels on receipt of requests and before sending responses.

If you have your own system for handling (classifying, storing and retrieving) operational messages, you can potentially use it to log the gateway's operational messages through the MessageWarehouse interface.

The Home object for this service must implement the com.ibm.wsgw.beans.MessageWarehouseHome interface and be located in JNDI at websphere/WSGW/MessageWarehouse.

Monitoring SOAP messages

You can trace the XML messages exchanged between a Web service client and the server. In this section we look at two tools:

• The TCPMon tool provided with IBM WebSphere Application Server V5.0

• The TCP/IP Monitor Server provided with WebSphere Studio Application Developer

WebSphere TCPMon tool

The TCPMon tool allows SOAP messages to be traced by redirecting messages from one port to another, displaying the contents as they go. The WebSphere application server normally listens on port 9080. To trace messages sent to the application server, TCPMon can be configured, for example, to listen on port 9088 and redirect messages to 9080. The client is modified to use port 9088 to access the Web service.

This tool is provided with IBM WebSphere Application Server V5.0.2. It allows you to view the contents of the SOAP messages exchange between the source and target applications, as shown in Figure 8-41.

Figure 8-41: Tracing SOAP messages using TCPMon

You can start TCPMon from a command window as follows:

    set CLASSPATH=%CLASSPATH%;<WAS_HOME>\lib\webservices.jar    <WAS_HOME>\java\bin\java com.ibm.ws.webservices.engine.utils.tcpmon 

For further details on TCPMon, see the InfoCenter article Tracing Web services messages at:

• http://www.ibm.com/software/webservers/appserv/infocenter.html

The SOAP request for our getDeliveryDate() method is shown in Example 8-9.

Example 8-9: SOAP request for getDeliveryDate

 POST /WSWholesale1EAR/services/Inventory HTTP/1.0 Content-Type: text/xml; charset=utf-8 Accept: application/soap+xml, application/dime, multipart/related, text/* User-Agent: IBM WebServices/1.0 Host: localhost Cache-Control: no-cache Pragma: no-cache SOAPAction: "" Content-Length: 427 <?xml version="1.0" encoding="UTF-8"?>    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"       xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"       xmlns:xsd="http://www.w3.org/2001/XMLSchema"       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">       <soapenv:Body>          <getDeliveryDate xmlns="http://inventory.wholesale.itso.ibm.com">             <partNo xmlns="">12345</partNo>          </getDeliveryDate>       </soapenv:Body>    </soapenv:Envelope> 

The SOAP response for the getDeliveryDate() method is shown in Example 8-10.

Example 8-10: SOAP response for getDeliveryDate

 HTTP/1.1 200 OK Server: WebSphere Application Server/5.0 Content-Type: text/xml; charset=utf-8 Content-Language: en-US Connection: close <?xml version="1.0" encoding="UTF-8"?>    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"       xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"       xmlns:xsd="http://www.w3.org/2001/XMLSchema"       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">       <soapenv:Body>          <getDeliveryDateResponse xmlns="http://inventory.wholesale.itso.ibm.com">             <getDeliveryDateReturn xmlns="">09/12/2003</getDeliveryDateReturn>          </getDeliveryDateResponse>       </soapenv:Body>    </soapenv:Envelope> 

TCP/IP Monitor Server

The TCP/IP Monitor Server provided with WebSphere Studio Application Developer (shown in Figure 8-42) also allows tracing of SOAP messages. It works in a similar way to the WebSphere TCPMon tool. To use the TCP/IP Monitor Server, create a new Server and Configuration and select Other → TCP/IP Monitor Server for the server type.

Figure 8-42: Tracing SOAP messages using WebSphere Studio TCP/IP Monitor Server

• Back up your configuration.

  The Web Services Gateway offers a very easy way to make a backup of the entire configuration of the gateway. This backup does not include the filter implementation, which resides in a separated Enterprise Application.

---