10.4 Development guidelines

Previous page
Table of content
Next page

  < Day Day Up > 


10.4 Development guidelines

In this section, we start with a brief look at installing and configuring the Web Services Gateway. After that we walk through the process of implementing a gateway solution, based on three simple steps:

  • Deploying the Web Services Gateway service

  • Exporting the WSDL service implementation file

  • Creating the Web service client

10.4.1 Installing and configuring the Web Services Gateway

Web Services Gateway is essentially a J2EE application installed in the WebSphere Application Server runtime. For this scenario, we installed the gateway on a stand-alone IBM WebSphere Application Server base V5.0.2 server. Details for completing the installation can be found in the WebSphere InfoCenter article, Installing the gateway into a stand-alone application server at:

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

Configuring the gateway

After the gateway has been installed and started it must be configured. To configure the Web Services Gateway:

  1. Open the IBM Web Services Gateway systems administration console, shown in Figure 10-4. For the default installation on server1, the URL for accessing the console will be:

    click to expand
    Figure 10-4: IBM Web Services Gateway systems administration console

    :9080/wsgw/admin/">http://<hostname>:9080/wsgw/admin/

  2. Click Gateway → Configure in the navigation panel on the left to configure the gateway.

  3. In the Configure Gateway window, set the following properties:

    • Namespace URI for services

      The gateway namespace URI will appear in WSDL files exported from the gateway. Keep in mind that Java clients generated from the WSDL need to convert the gateway namespace to a Java package.

      Note 

      Take care when specifying the namespace URI for services. If you need to change the namespace URI, you will need to redeploy all of your deployed services.

    • WSDL URI for exported definitions

      This is the URI that Web service clients will use to access the WSDL file and the exposed Web service.

    Our gateway configuration settings are shown in Figure 10-5.

    click to expand
    Figure 10-5: Configuring the Web Services Gateway

  4. Click Apply Changes to configure the gateway.

Deploying a channel

There are two types of channels provided with the Web Services Gateway:

  • Apache SOAP Channel

  • SOAP/HTTP Channel

Both channel types support SOAP 1.1 compatible Web services that use the RPC SOAP messaging style. The SOAP/HTTP Channel adds support for document messaging style, and for passing attachments in a MIME message.

Two versions of each channel type are supplied with the gateway, so you can set up separate channels for inbound and outbound requests. This also provides a simple way to grant different access rights to users within your organization from those outside your organization.

In our scenario, we are using the SOAP/HTTP Channel because we are using the document style SOAP message format.

To deploy a SOAP/HTTP Channel:

  1. Click Channels → Deploy in the navigation panel on the left to deploy a channel.

  2. In the Deploy Channel window, the following fields are required:

    • Channel Name: SOAPHTTPChannel1

    • Home Location: SOAPHTTPChannel1Bean

    • End Point Address: http://<hostname>[:<port>]/wsgwsoaphttp1

    • Async Reply Context Name: leave blank (not supported)

    • Async Reply Context Value: leave blank (not supported)

    See the InfoCenter article, Web services gateway - Channel deployment details if you need channel settings for other channel types, or for clustered environments.

    Our channel settings are shown in Figure 10-6.

    click to expand
    Figure 10-6: Deploying a gateway channel

  3. Click OK to deploy the channel.

10.4.2 Deploying the Web Services Gateway service

Once the gateway is configured and the required channel deployed, you can deploy the service. There are two steps involved:

  • Provide gateway access to the WSDL file (and any files it imports) for the target Web service you want to deploy.

  • Use the gateway systems administration console to deploy the service.

Accessing the target WSDL from the gateway

The WSDL file for the service you want to deploy needs to be accessible by the gateway. The gateway and Web service client applications will also need access to any WSDL files or XML schemas imported by the service WSDL.

If your service WSDL includes imports, our recommendation is to make the WSDL and any imports available via an HTTP URL. This way both the gateway and clients can access the required files from the same location. Ideally, these HTTP URLs should point to documents on a related Web server.

If your service WSDL doesn't import other files, you can place the WSDL on the local file system of the gateway node, since clients will be able to access all the required service definitions via the gateway.

For this example, we use the InventoryDoc service we created in Chapter 9, "Using document style Web services" on page 183. It imports two XML schema files. To provide access to the InventoryDoc service description:

  1. Create a new folder called wsdl under the <WAS_HOME>\installedApps\<node_name>\wsgw.server1.<node_name>.e ar\wsgw.war folder on your Web Services Gateway node.

  2. Locate the following files in the ITSOTargetAppEJB\ejbModule\META-INF\wsdl folder under your WebSphere Studio workspace for the ABC Electronics sample:

    • InventoryDoc.wsdl

    • InventoryReply.xsd

    • InventoryRequest.xsd

  3. Copy these files to the new wsdl folder on your gateway node. In our case, the WSDL file will now be accessible in the gateway administrative console Web module with the following URL:

    • http://wsgw1.itso.ral.ibm.com:9080/wsgw/wsdl/InventoryDoc.wsdl

  4. Edit the WSDL to make sure any imports will be accessible from client applications. As shown in Example 10-1, our InventoryDoc.wsdl contains two relative imports that need to be updated. We changed:

    • schemaLocation="InventoryReply.xsd" to "http://wsgw1.itso.ral.ibm.com:9080/wsgw/wsdl/InventoryReply.xsd"

    • schemaLocation="InventoryRequest.xsd" to "http://wsgw1.itso.ral.ibm.com:9080/wsgw/wsdl/InventoryRequest.xsd"

    Example 10-1: InventoryDoc.wsdl before changes to import schemaLocations

    start example 
     ... <wsdl:types>   <xsd:schema elementFormDefault="qualified"       targetNamespace="http://inventory.ws.itso.ibm.com"       xmlns:reply="http://reply.inventory.ws.itso.ibm.com"       xmlns:request="http://request.inventory.ws.itso.ibm.com">   <xsd:import namespace="http://reply.inventory.ws.itso.ibm.com"       schemaLocation="InventoryReply.xsd"/>   <xsd:import namespace="http://request.inventory.ws.itso.ibm.com"       schemaLocation="InventoryRequest.xsd"/>   <xsd:element name="getDeliveryDate"> ...
    end example

  5. Save your changes.

Note 

We deployed our service WSDL and XML schema files to the gateway administrative console Web module for simplicity only. In a production environment, it would make more sense to deploy these files to an appropriate Web server.

Deploying the gateway service

To deploy InventoryDoc.wsdl as a gateway service:

  1. Open the Web Services Gateway systems administration console and click Services → Deploy in the navigation panel on the left.

  2. In the Deploy Gateway Service window, we set the following fields:

    • Gateway Service Name: InventoryDocWsgw

    • Channels: click to select SOAPHTTPChannel1

    • WSDL Location:

      http://wsgw1.itso.ral.ibm.com:9080/wsgw/wsdl/InventoryDoc.wsdl

    • Location Type: URL

    We accepted the defaults for the remaining fields. Our gateway service settings are shown in Figure 10-6.

    click to expand
    Figure 10-7: Deploying a gateway service

  3. Click OK to deploy the service.

10.4.3 Exporting the WSDL file

When the service is deployed, the gateway generates new WSDL files that can be shared with clients of your Web service. The gateway-generated WSDL implementation definition file has the gateway as the service end-point, and it imports the WSDL interface definition file that contains bindings and portType information.

To export the WSDL file generated by the Web Services Gateway:

  1. Open the Web Services Gateway systems administration console and click Services → List in the navigation panel on the left.

  2. In the List of Gateway Services window, click the required service, InventoryDocWsgw in our case.

  3. In the Service: InventoryDocWsgw window:

    1. Scroll down to the Exported WSDL definitions section.

    2. Right-click External WSDL implementation definition (WSDL only) and select Save Target As… from the pop-up menu, as shown in Figure 10-8.

      click to expand
      Figure 10-8: Exporting the WSDL implementation definition file

    3. Save the WSDL file to the required location. We saved the file as InventoryDocWsgw.wsdl under the ITSOSourceAppWeb\WebContent\WEB-INF\wsdl folder in our WebSphere Studio workspace.

We are now ready to Web service-enable our source application using the gateway-generated WSDL implementation definition file for our target service.

Restriction: 

The WebSphere V5.0.2 Web Services Gateway does not support XML schema-type elements that use the ref attribute. To work around this restriction, you can re-factor any WSDL or XML schema files that use the ref attribute to use nested elements or the type attribute instead.

10.4.4 Web service-enabling the source application

See Figure 8-11 on page 167 for an overview of the Web service development process for a source application. Let's walk through this process for our source application.

To Web service-enable the source application using the gateway-generated WSDL implementation definition file:

  1. Open a command window.

  2. Using the gateway WSDL file exported in 10.4.3, "Exporting the WSDL file" on page 226, generate the Web service client deployment descriptors and classes using the WSDL2Java tool. We used the command shown in Example 10-2.

    Example 10-2: Generating client deployment descriptors and classes using WSDL2Java

    start example 
     C:\WebSphere\AppServer\bin\WSDL2Java -verbose -role client -container web    -output C:\workspace\ITSOSourceAppWeb\WebContent    C:\workspace\ITSOSourceAppWeb\WebContent\WEB-INF\wsdl\InventoryDocWsgw.wsdl WSWS3185I: Info: Parsing XML file:  C:\...\WEB-INF\wsdl\InventoryDocWsgw.wsdl Retrieving document at 'http://wsgw1.itso.ral.ibm.com:9080/wsgw/ServiceInterface?name=InventoryDocWsgw', relative to 'C:\workspace\ITSOSourceAppWeb\WebContent\WEB-INF\wsdl\InventoryDocWsgw.wsdl'. WSWS3282I: Info: Generating C:\...\itso\ws\inventory\request\InventoryRequest.java. WSWS3282I: Info: Generating C:\...\itso\ws\inventory\request\InventoryRequest_Helper.java. WSWS3282I: Info: Generating C:\...\itso\ws\inventory\request\InventoryRequest_Ser.java. WSWS3282I: Info: Generating C:\...\itso\ws\inventory\request\InventoryRequest_Deser.java. WSWS3282I: Info: Generating C:\...\itso\ws\inventory\reply\InventoryReply.java. WSWS3282I: Info: Generating C:\...\itso\ws\inventory\reply\InventoryReply_Helper.java. WSWS3282I: Info: Generating C:\...\itso\ws\inventory\reply\InventoryReply_Ser.java. WSWS3282I: Info: Generating C:\...\itso\ws\inventory\reply\InventoryReply_Deser.java. WSWS3282I: Info: Generating C:\...\itso\ws\inventory\UpdateInventory.java. WSWS3282I: Info: Generating C:\...\itso\ws\inventory\UpdateInventory_Helper.java. WSWS3282I: Info: Generating C:\...\itso\ws\inventory\UpdateInventory_Ser.java. WSWS3282I: Info: Generating C:\...\itso\ws\inventory\UpdateInventory_Deser.java. WSWS3282I: Info: Generating C:\...\itso\ws\inventory\reply\Header.java. WSWS3282I: Info: Generating C:\...\itso\ws\inventory\reply\Header_Helper.java. WSWS3282I: Info: Generating C:\...\itso\ws\inventory\reply\Header_Ser.java. WSWS3282I: Info: Generating C:\...\itso\ws\inventory\reply\Header_Deser.java. WSWS3282I: Info: Generating C:\...\itso\ws\inventory\reply\Body.java. WSWS3282I: Info: Generating C:\...\itso\ws\inventory\reply\Body_Helper.java. WSWS3282I: Info: Generating C:\...\itso\ws\inventory\reply\Body_Ser.java. WSWS3282I: Info: Generating C:\...\itso\ws\inventory\reply\Body_Deser.java. WSWS3282I: Info: Generating C:\...\itso\ws\inventory\request\Header.java. WSWS3282I: Info: Generating C:\...\itso\ws\inventory\request\Header_Helper.java. WSWS3282I: Info: Generating C:\...\itso\ws\inventory\request\Header_Ser.java. WSWS3282I: Info: Generating C:\...\itso\ws\inventory\request\Header_Deser.java. WSWS3282I: Info: Generating C:\...\itso\ws\inventory\request\Body.java. WSWS3282I: Info: Generating C:\...\itso\ws\inventory\request\Body_Helper.java. WSWS3282I: Info: Generating C:\...\itso\ws\inventory\request\Body_Ser.java. WSWS3282I: Info: Generating C:\...\itso\ws\inventory\request\Body_Deser.java. WSWS3282I: Info: Generating C:\...\itso\ws\inventory\InventoryDoc.java. WSWS3282I: Info: Generating C:\...\itso\ws\inventory\InventoryDocSOAPHTTPBindingStub.java. WSWS3282I: Info: Generating C:\...\ral\itso\wsgw1\InventoryDocWsgw.java. WSWS3282I: Info: Generating C:\...\ral\itso\wsgw1\InventoryDocWsgwLocator.java. WSWS3282I: Info: Generating C:\...\WEB-INF\webservicesclient.xml. WSWS3282I: Info: Generating C:\...\WEB-INF\ibm-webservicesclient-bnd.xmi. WSWS3282I: Info: Generating C:\...\WEB-INF\ibm-webservicesclient-ext.xmi. WSWS3282I: Info: Generating C:\...\WEB-INF\InventoryDocWsgw_mapping.xml.
    end example

  3. In WebSphere Studio, move the generated Java source files from the Web module's WebContent folder to its JavaSource folder:

    1. Right click the ITSOSourceAppWeb project and select Refresh from the pop-up menu. The generated files should now appear in the Studio workspace.

    2. Move the com.ibm.itso.ws.inventory and com.ibm.ral.itso.wsgw1 packages in the ITSOSourceAppWeb\WebContent folder to the ITSOSourceAppWeb\JavaSource folder.

  4. 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 10-3. We added this code to the com.ibm.itso.command.GatewayBean command bean in our ITSOSourceAppWeb module.

    Example 10-3: Web service client code for getDeliveryDate

    start example 
     public String getDeliveryDate(String partNumber) throws Exception {    String deliveryDate = null;    try {       Context ctx = new InitialContext();       InventoryDocWsgw service = (InventoryDocWsgw) ctx.lookup(          "java:comp/env/service/InventoryDocWsgw");       // Request the Service Endpoint from the Service       InventoryDoc port = service.getInventoryDocSOAPHTTPBindingPort();       // Generate XML document for update inventory request       InventoryRequest reqMsg =          new InventoryRequestBuilder(APP_NAME, partNumber);       // Get the quote       InventoryReply repMsg = port.getDeliveryDate(reqMsg);       // Get the delivery date from the XML reply document       Date date = (repMsg.getBody()).getDeliveryDate();       SimpleDateFormat dateFormatter = new SimpleDateFormat(DATE_PATTERN);       deliveryDate = dateFormatter.format(date);    } catch (Exception e) {       //...    }    return deliveryDate; }
    end example

  5. Test, then deploy the source and target applications in your IBM WebSphere Application Server V5.0.2 runtime environment.

The document style SOAP request between the source application and the gateway for getDeliveryDate is shown in Example 10-4.

Example 10-4: SOAP request for getDeliveryDate: source to gateway

start example 
 POST /wsgwsoaphttp1/soaphttpengine/urn%3Awsgw1.itso.ral.ibm.com%23InventoryDocWsgw 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: 618 <?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.ws.itso.ibm.com">             <InventoryRequest>                <Header xmlns="">                   <SourceName>ITSOSourceApp</SourceName>                   <Version>1</Version>                   <CreateDate>2003-09-09T00:33:20.981Z</CreateDate>                </Header>                <Body xmlns="">                   <PartNumber>12345</PartNumber>                </Body>             </InventoryRequest>          </getDeliveryDate>       </soapenv:Body>    </soapenv:Envelope>
end example

The SOAP response between the gateway and the source application for getDeliveryDate is shown in Example 10-5.

Example 10-5: SOAP response for getDeliveryDate: gateway to source

start example 
 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"?>    <Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">       <Body>          <getDeliveryDateResponse xmlns="http://inventory.ws.itso.ibm.com"              xmlns:ns-445461426="http://inventory.ws.itso.ibm.com"              xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"              xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"              xmlns:xsd="http://www.w3.org/2001/XMLSchema"              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">             <InventoryReply>                <Header xmlns="">                   <SourceName>ITSOTargetApp</SourceName>                   <Version>1</Version>                   <CreateDate>2003-09-09T00:33:28.842Z</CreateDate>                </Header>                <Body xmlns="">                   <PartNumber>12345</PartNumber>                   <DeliveryDate>2003-09-15</DeliveryDate>                </Body>             </InventoryReply>          </getDeliveryDateResponse>       </Body>    </Envelope>
end example

The document style SOAP request between the gateway and the target application for getDeliveryDate is shown in Example 10-6.

Example 10-6: SOAP request for getDeliveryDate: gateway to target

start example 
 POST /ITSOTargetApp/services/InventoryDoc 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: 676 <?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.ws.itso.ibm.com"              xmlns:ns-445461426="http://inventory.ws.itso.ibm.com">             <InventoryRequest>                <Header xmlns="">                   <SourceName>ITSOSourceApp</SourceName>                   <Version>1</Version>                   <CreateDate>2003-09-09T00:33:20.981Z</CreateDate>                </Header>                <Body xmlns="">                   <PartNumber>12345</PartNumber>                </Body>             </InventoryRequest>          </getDeliveryDate>       </soapenv:Body>     </soapenv:Envelope>
end example

The SOAP response between the target application and the gateway for getDeliveryDate is shown in Example 10-7.

Example 10-7: SOAP response for getDeliveryDate: target to gateway

start example 
 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.ws.itso.ibm.com">             <InventoryReply>                <Header xmlns="">                   <SourceName>ITSOTargetApp</SourceName>                   <Version>1</Version>                   <CreateDate>2003-09-09T00:33:28.842Z</CreateDate>                </Header>                <Body xmlns="">                   <PartNumber>12345</PartNumber>                   <DeliveryDate>2003-09-15</DeliveryDate>                </Body>             </InventoryReply>          </getDeliveryDateResponse>       </soapenv:Body>    </soapenv:Envelope>
end example


 < Day Day Up > 


Previous page
Table of content
Next page
Patterns Direct Connections for Intra- And Inter-Enterprise. Direct Connections for Intra- And Inter-Enterprise (IBM Redbook) (Paperback)
Patterns Direct Connections for Intra- And Inter-Enterprise. Direct Connections for Intra- And Inter-Enterprise (IBM Redbook) (Paperback)
ISBN: N/A
EAN: N/A
Year: 2003
Pages: 139
BUY ON AMAZON
High-Speed Signal Propagation[c] Advanced Black Magic
SQL Tips & Techniques (Miscellaneous)
Mastering Delphi 7
GO! with Microsoft Office 2003 Brief (2nd Edition)
Cisco ASA: All-in-One Firewall, IPS, and VPN Adaptive Security Appliance
DNS & BIND Cookbook
flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net
Privacy policy