Web services client programming for WebSphere Process Server

Learn how to compose Web services clients from external WebSphere® servers using SOAP/HTTP and SOAP/JMS to interact with IBM® WebSphere Process Server Version 6.0.1 using WebSphere Integration Developer for application development.

Share:

Geoffrey Beers (gbeers@us.ibm.com), Software Engineer, IBM

Geoffrey BeersGeoffrey Beers is a software engineer at IBM in Rochester, Minnesota. He works in the Bringup Lab and SWAT team for WebSphere Process Server. You can reach Geoffrey at beersga@yahoo.com.



Wendy Butt (wkbutt@ca.ibm.com), Software Engineer, IBM

Wendy ButtWendy Butt is a software engineer at the IBM Toronto Software Lab in Markham, Ontario. She works on the SWAT Team for WebSphere Integration Developer and WebSphere Process Server. Previously, she worked on the Scenarios Development team for WebSphere Studio Application Developer Integration Edition, where she built sample applications illustrating how to use the product. You can reach Wendy at wkbutt@ca.ibm.com.



21 August 2006

Introduction

A service oriented architecture (SOA) enables service clients to invoke service providers in a consistent and flexible manner. The WebSphere Process Server (hereafter called Process Server) integration platform leverages WebSphere Application Server (hereafter called Application Server) to take advantage of a Java™ 2, Enterprise Edition (J2EE) infrastructure to solve complex integration challenges. Process Server and WebSphere Integration Developer (hereafter called Integration Developer) together provide a comprehensive set of capabilities for designing, implementing and deploying integration solutions.

In this article, we'll explore Web service bindings in a Process Server environment. We'll look at Web services exposed both as SOAP/HTTP and SOAP/JMS, which are hosted on Process Server. You'll also learn how to invoke these Process Server applications through client applications installed on remote non-Process Server environments.

First, we'll provide a basic understanding of the runtime used by Process Server to facilitate client-to-service communication. Next, we'll briefly discuss how business objects are used to represent data within Process Server. Finally, we'll analyze a simple order processing use case, and show you how to expose the application component using SOAP/HTTP and SOAP/JMS Web service bindings.

In our example, we'll develop applications and configure the server for remote Web service clients using the following non-Process Server client environments:

  • WebSphere Application Server 6.0.2
  • WebSphere Application Server 5.1.1

After completing this article, you should have a basic understanding of Process Server, the Service Component Architecture programming model, and what you need to do to invoke a Process Server application component from a non-Process Server environment, using Web service bindings.


Service Component Architecture

Service Component Architecture (SCA) is the runtime used to provide SOA capabilities in Process Server. The SCA runtime provides a layer of abstraction that protects the integration developer from the details of the underlying infrastructure. In this section, we'll describe some of the fundamental SCA concepts necessary for understanding the SCA client programming model used in our sample. For detailed information about SCA, see the Business Process Management Version 6.0 Information Center.

Service module imports and exports

In SCA, a service module represents the deployment unit for SCA services. A service module is a self-contained unit of logic that can act standalone or as part of a complex integration solution. One or more service components can be grouped within a service module, and references are used to link service components to other service components or to service imports. Exports expose services provided by the service module for invocation from external clients. Service bindings provide detailed information about service imports and exports. Figure 2 shows a high-level view of component-level import and export bindings.

Figure 1. Component with import and export bindings
Component with import and export bindings

Service Component Architecture bindings

Service bindings are used on imports and exports to isolate the infrastructure details necessary for a client to invoke a service. Until now you've been able to assemble SCA components in a service module using the necessary business logic to meet the integration requirements. However, bindings are specifically used to separate the infrastructure details from the integration logic. SCA provides a number of binding options:

  • SCA binding - SCA bindings are typically used for module-to-module invocations. They require very little configuration and use different transports depending on the client invocation style (synchronous, asynchronous, and so on).
  • JMS binding - Java Messaging Service (JMS) bindings make service components accessible via the JMS. A JMS binding contains information such as the queue and necessary connection factory information.
  • Web service binding - Web service bindings describe how service components can be invoked using common Web service invocation techniques. Web service bindings in Process Server can be exposed using one of two transport methods: SOAP/HTTP and SOAP/JMS. Web service bindings are the simplest binding types, and are also the most compatible with clients that wish to invoke Web services. Because Web services are run on a standard protocol and are not application-specific, they offer greater compatibility than SCA and JMS bindings. However, because of their simplicity and compatibility, they also lack some of the advanced features found in SCA and JMS binding types.

    Web service export bindings are exposed to external clients. Web service import bindings invoke external Web services found in other modules, or in other environments outside of Process Server.

The examples in this article focus entirely on Web service bindings.

Business objects

The final part of the SOA infrastructure is the business object. Now that you know a little about SCA and how you find and invoke services, you need to understand how the data used in the invocation is represented. Process Server uses business objects for this purpose. A business object is an implementation of the Service Data Object (SDO) specification, published by IBM and BEA Systems, to provide a simplified view of data and data access.


Order processing use case

Now that you understand the building blocks (sCA and Business objects) for our integration scenario; let's take a more detailed look at the requirements for our use case. To provide a frame of reference for our discussion and sample, we based the artifacts on a simple Order Processing use case. The Order Processing service is hosted in Process Server. Clients who want to submit orders issue requests to this remote service, as shown in Figure 2.

Figure 2. Client calls to a Process Server component
Client calls to a Process Server component

For consistency, all clients on the various server configurations invoke the same Process Server order processing module.

The order is represented by a business object that contains a number of simple type attributes and an array of order line items as shown in Figure 3.

Figure 3. Order processing business object
Order processing business object

We used a mix of common types to demonstrate a variety of possible data types. Keep in mind this is not an exclusive list of data types, but you can use this sample and expand it to meet your particular needs.

The order processing service provides two Web Services Descrption Language (WSDL) operations to submit orders:

  • A one-way operation that takes an order as an input.
  • A request-response operation that receives an order as input and returns an order as output.
Figure 4. WSDL operations for order process
WSDL operations for order process

The sample order module contains an OrderProcessing Java component. The Java components print the values of the inbound order when the one way operation is invoked.

************ Order Processing (OneWay) service invoked from client *********
<?xml version="1.0" encoding="UTF-8"?>
<order:Order xsi:type="order:Order" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:order="http://OrderProcessing">
  <orderId>orderId</orderId>
  <customerId>customerId</customerId>
  <orderDate>2002-01-01Z</orderDate>
  <orderStatus>submitted</orderStatus>
  <totalPrice>124.0</totalPrice>
  <orderLineItems>
    <orderId>orderId</orderId>
    <itemId>ItemId</itemId>
    <quantity>100</quantity>
    <orderDate>2002-01-01Z</orderDate>
    <orderLineStatus>submited</orderLineStatus>
    <price>24.0</price>
  </orderLineItems>
  <orderLineItems>
    <orderId>orderId</orderId>
    <itemId>itemId</itemId>
    <quantity>22</quantity>
    <orderDate>2002-01-01Z</orderDate>
    <orderLineStatus>backorder</orderLineStatus>
    <price>100.0</price>
  </orderLineItems>
</order:Order>

When the request-response operation is invoked, the Java component updates the orderId and orderStatus attributes on the order and the order line items business objects, prints the resulting business object, and returns the outcome to the client.

************ Order Processing (RequestResponse) service invoked from client *********
************ retrieve the order line array *********
************ 0 *********
************ 1 *********
************ returning order to client *********
<?xml version="1.0" encoding="UTF-8"?>
<order:Order xsi:type="order:Order"
	 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
	 xmlns:order="http://OrderProcessing">
  <orderId>123-abc</orderId>
  <customerId>customerId</customerId>
  <orderDate>2002-01-01Z</orderDate>
  <orderStatus>submitted</orderStatus>
  <totalPrice>124.0</totalPrice>
  <orderLineItems>
    <orderId>orderId</orderId>
    <itemId>ItemId</itemId>
    <quantity>100</quantity>
    <orderDate>2002-01-01Z</orderDate>
    <orderLineStatus>submitted</orderLineStatus>
    <price>24.0</price>
  </orderLineItems>
  <orderLineItems>
    <orderId>orderId</orderId>
    <itemId>itemId</itemId>
    <quantity>22</quantity>
    <orderDate>2002-01-01Z</orderDate>
    <orderLineStatus>submitted</orderLineStatus>
    <price>100.0</price>
  </orderLineItems>
</order:Order>

Figure 5 shows the order processing service in the Integration Developer assembly editor.

Figure 5. Order processing assembly diagram
Order processing assembly diagram

In this scenario, you essentially have two SCA modules -- a non-Process Server client module, and a service module hosted on Process Server.


Install and run the Web service samples

Now you're ready to install and run the order processing sample. You must already have Process Server installed and started.

The basic steps are:

  1. The Web client uses a generated Java proxy, which provides a remote procedure call interface to the Web service.
  2. The Web services engine running on Process Server receives the request, and invokes the Process Server application, which exposes a Web services export binding type. The Web services export binding can either be invoked via SOAP/HTTP or SOAP/JMS. We'll show examples using both Web service invocation methods.
Figure 6. Order processing Web service export
Order processing Web service export

When a Web services export binding is created in Integration Developer, an .export file, as well as an export .wsdl file, are created within the Process Server environment. The export .wsdl imports the interface WSDL defined in the component bound to the export. The interface WSDL then imports any dependent XSDs that are used to define data types within the WSDL types. The export .wsdl is exposed to the Web service client, and must also be included in the client application, along with any other dependent WSDLs and XSDs.

You can deploy the client application to any server that supports invoking remote Web services. However, there are certain artifacts in the server application that you must include within the client. You can install the client on the same Process Server instance containing the Web service application. However, because Web services are more practical in a remote invocation environment, this set-up is not very practical in a real-world environment. Most often the client that invokes the remote order processing Web service is on an environment that is separate from the Web service. We'll test this configuration with a remote client installed on Application Server 5.1.2 and 6.0.2.

The client package contains:

  1. A WSDL file containing the service and binding details.
  2. A WSDL file containing the portType of the Web service.
  3. XSD files supporting the business objects used in your interface.

Install the order processing service on Process Server

Deploy the OrderProcessApp.EAR to Process Server using the WebSphere Integrated Test Environment or exported as an EAR and installed through the administrative console. If you install using the administrative console, start the application. The application is now ready to accept Web service calls.

Build and test a SOAP/JMS client with Application Server V6.0.2

You must do some additional configuration on Application Server 6.0.2 using the administrative console when using SOAP/JMS with a remote Web service client:

  1. Configure Application Server to invoke remote SOAP/JMS Web services installed on Process Server.
  2. Create a bus with a messaging engine on the Application Server 6.0.2 server, in order for the SOAP/JMS remote Web service call to work properly:
    1. In the administrative console for the Application Server 6.0.2 server, select Service Integration – Buses.
    2. Select New.
    3. Provide a bus name. This name should be different from the bus name used in the Process Server environment.
    4. Leave the default settings for the other fields, then click OK and Save.
    5. Now select the newly created bus. Under Additional Properties, select Bus members.
    6. Add a bus member. Because this is a single server environment, you can accept the default settings. Click OK and then Save. When the bus member is added, a messaging engine is also created. The messaging engine name is similar to the bus name.
    7. After saving any outstanding changes, restart the Application Server. If you created the bus properly, you'll see a bus with a bus member and a messaging engine.

Now you need build the client application using Application Server V6.0.2. Once the application is built, deploy it to the Application Server 6.0.2-based Integrated Test Environment in Integration Developer.

  1. In Integration Developer, make sure you've added an the Application Server 6.0.2 server to your test environment, because you'll be deploying the application on Application Server 6.0.2, not Process Server.
  2. Create a new Dynamic Web Project.
  3. Import the files into your Web project.
  4. From the Resource perspective, expand the WebContent folder and copy the necessary files from the Process Server application into your Web project. Typically, the necessary files from the Process Server application are the Export .wsdl file, the interface .wsdl file, and any .xsd files that are used in the WSDL definition. It most cases, you can copy the wsdl folder from your Process Server application into your client web project, as shown in Figure 7. For the order processing application, the relevant artifacts are Order.xsd, OrderLineItem.xsd, OrderProcessingExport_processOrderHttp_Service.wsdl, processOrder.wsdl. You also need to copy the xsd-includes folder, which contains the http.OrderProcessing.xsd file.
    Figure 7. Web client file structure
    Web client file structure
  5. Open OrderProcessingExport_processOrderHttp_Service.wsdl and change the addresslocation attribute to use the real hostname of the remote Web service application. By default, the name is localhost because the Export .wsdl is originally created within the Process Server application when the Web service export binding is generated. When it is moved to a remote client application, the hostname needs to be changed to reflect the true location of the Web service.
  6. Rebuild the project and ensure there are no errors. You may see some WS-I compliance warnings. These are irrelevant and do not hinder the performance of the application.
  7. Generate the Web service client Java proxy.
  8. From the menu, select File => New => Other. Expand Web Services and select Web Service Client. Click Next.
  9. Select Java proxy. Also check Test the Web service, which generates some JSP pages that invoke your Java proxy. Click Next.
    Figure 8. Web service client proxy
    Web service client proxy
  10. Specify the Export WSDL OrderProcessingExport_processOrderHttp_Service.wsdl as the Web service, and click Next.
    Figure 9. Web service client export
    Web service client export
  11. Specify the client-side environment specifications. By default the Client project and EAR project are selected, so you can keep these default settings. Click Next.
    Figure 10. Client-side environment settings
    Client-side environment settings
  12. Because we chose to generate a Web proxy, leave the defaults on the Web service proxy page and click Finish.
    Figure 11. Web service proxy
  13. The Java proxy code is generated. You may see the following warning. Click Yes.
    Figure 12. File overwrite warning
    File overwrite warning
  14. After the Java proxy code is created, you're given the option to create JSP code to test the client application. This step is purely optional and is to be used for testing purposes only. The generated JSP code allows you to test the methods to make sure they are working properly, but likely won't be used in a real-world solution as the user interface is incomplete.

    Furthermore, the tooling which generates the JSP code is unable to handle the arrays. In the case of the order processing application, this means the JSP form generated to test the Java proxy won't have input fields for the OrderLineItems. You'll need to customize the JSP code to handle the OrderLineItems.

    This problem refers only to the JSP code generation, and not the Java proxy code that is generated from the Export WSDL. In other words, the Java proxy code does contain methods to handle arrays of business objects. Therefore, the problem exists only in the JSP test client. Since this JSP code is used for testing and likely won't be used in a production environment, the effect of this is minimal.

    Figure 13. Test the Web service client
    Test the Web service client
  15. After the JSP client is created, a Web browser displays in Integration Developer from which you can test the remote Web service. The application should be automatically installed to the Integrated Test Environment for the Application Server 6.0.2 server instance. You can also export an EAR and install it to Application Server using the administrative console.
  16. Once you've verified that the remote Web service sends a valid response back to the client application, you can develop a customized JSP application, tailored to your requirements. You don't need to modify or re-create the Java proxy code unless the specifications for the remote WSDL or XSD files change.

Build and test a SOAP/HTTP client with Application Server V5.1.2

Build the client application using Application Server V5.1.2. Once the application is built, deploy it to the Test Environment server in WebSphere Studio Application Developer (hereafter referred to as Application Developer):

  1. Create a new Dynamic Web Project.
  2. Import the files into your Web project, as shown in Figure 14.
    Figure 14. File structure for Web service client
    File structure for Web service client
  3. You need to change some files to avoid an error when generating the proxy. The wizard to generate the proxy expects the XSD and WSDL files to be in the same folder, at the same level.
    1. Move http.OrderProcessing.xsd up one level to the wsdl folder and delete the xsd-includes folder. If you don't do this, you'll get an error later when you try to generate the proxy.
    2. Open http.OrderProcessing.xsd in the text editor and change the schemaLocation values to reflect the new locations of the files, as shown in Figure 15:
      Figure 15. Change the schemaLocation paths in http.OrderProcessing.xsd file
      Change the schemaLocation paths in http.OrderProcessing.xsd file
    3. Open processOrder.wsdl in the text editor and change the schemaLocation value to reflect the new location, as shown in Figure 16:
      Figure 16. Change the schemaLocation in the WSDL interface
      Change the schemaLocation in the WSDL interface
    4. Open the OrderProcessingExport_processOrderHttp_Service.wsdl file and change the address information to use the real hostname of the remote Process Server Web service you want to invoke. By default the hostname is localhost.
    5. Rebuild the project and ensure there are no errors. You may see the following warnings, which you can ignore:
      Figure 17. List of WS-I compliance warnings
      List of WS-I compliance warnings
  4. Next, generate the Web service client Java proxy.
    1. From the menu, select File => New => Other.
    2. In the New wizard, select Web Services from the tree on the left, and Web Service Client from the table on the right.
    3. Click Next and select Java Proxy. Check Test the generated proxy to generate some JSP pages which invoke your Java proxy.
    4. Click Next and ensure the Web and EAR projects are selected.
    5. Click Next. Specify the service WSDL OrderProcessingExport_processOrderHttp_Service.wsdl as the Web service.
    6. Click Finish. You will see the following warning message:
      Figure 18. Warning for array handling
      Warning for array handling

      The tooling was unable to handle the array of OrderLineItem. This means the JSP form generated to test the Java proxy will not have input fields for the OrderLineItems. You can manually edit the JSP to handle the array; however, for this sample it's not necessary. Click OK. The wizard doesn't close until the server is started and the application is published.

  5. If you check out the Tasks view, you'll notice the following errors:
    Figure 19. Errors during project build
    Errors during project build

    Most of these errors are due to the tooling failing to copy the business object xsd files into the WEB-INF folder. Copy Order.xsd and OrderLineItem.xsd into the WEB-INF/wsdl folder and rebuild the project to get rid of most of these errors,as shown in Figure 20:

    Figure 20. Copy XSD files to WEB-INF folder
    Copy XSD files to WEB-INF folder

    The following errors may remain after rebuilding the project:

    Figure 21. Remaining errors during build
    Remaining errors during build
  6. If the name of the interface you exported in Integration Developer began with an uppercase letter, you won't see these errors. In order to get rid of the errors, open ProcessOrderProxy.java and change any class/method references to use an uppercase "P" wherever "processOrder" occurs. This example requires four changes. Save but do not close the file. You should now see no errors in the Tasks view.
  7. Now you can invoke the JSP, which invokes your Java proxy, which invokes the Web service running on Process Server. Right-click MyWebProject => WebContent => sample => ProcessOrderProxy => TestClient.jsp and select Run on Server from the menu.

Build and test a SOAP/JMS client with Application Server V6.0.2

The method for creating a SOAP/JMS client in Application Server V6.0.2 is very similar to creating a SOAP/HTTP client. As mentioned earlier, you must configure Process Server to support SOAP/JMS. You must also complete the following steps to configure the client:

  1. In Integration Developer make sure that you've added an Application Server V6.0.2 server to your test environment, because you'll deploy the application on Application Server 6.0.2, not Process Server.
  2. Create a new Dynamic Web Project.
  3. Import the files into your Web project.
  4. From the Resource perspective, expand the WebContent folder and copy the necessary files from the Process Server application into your Web project. Typically, the necessary files from the Process Server application are the Export .wsdl file, the interface .wsdl file, and any .xsd files that are used in the WSDL definition. You can usually copy the wsdl folder from your Process Server application into your client Web project. For the the order processing application, the relevant artifacts are Order.xsd, OrderLineItem.xsd, OrderProcessingExport_processOrderJms_Service.wsdl, processOrder.wsdl. You also need to copy the xsd-includes folder, which contains the http.OrderProcessing.xsd file.
  5. Open OrderProcessingExport_processOrderJms_Service.wsdl with a text editor. Add the jndiProviderURL field to the addresslocation. The jndiProviderURL field specifies the remote JMS provider with its bootstrap address port (2809 by default). For example, the jndiProviderURL may look like iiop://gbeers.rchland.ibm.com:2809/. Notice that the jndiProviderURL attribute is separated with "&&".
    <soap:address location="jms:/queue?destination=jms/OrderProcExport&
    connectionFactory=jms/OrderProcExportQCF&
    targetService=OrderProcExport_processOrderJMSPort&
    jndiProviderURL=iiop://gbeers:2809/"/>
  6. Rebuild the project and ensure there are no errors. You may see some WS-I compliance warnings, which you can ignore. These are irrelevant and don't affect the performance of the application.
  7. Generate the Web service client Java proxy:
    1. From the menu, select File => New => Other. Expand Web Services and select Web Service Client. Click Next.
    2. Select Java proxy. Check Test the Web service to generate some JSP pages which invoke your Java proxy. Click Next.
    3. Specify the Export WSDL OrderProcessingExport_processOrderJms_Service.wsdl as the Web service. Click Next.
    4. Specify the client-side environment specifications. By default the Client project and EAR project should be selected, so you can probably keep the default settings. Click Next.
    5. Since you chose earlier to generate a Web proxy, leave the defaults on the Web service proxy page Click Finish.
    6. The Java proxy code is generated. If you see a warning notifying you of path link problems, click Yes.
  8. As with SOAP/HTTP, you can generate a JSP test proxy to test the Web service invocation.

The tooling that generates the JSP code is unable to handle the arrays. In order processing application, this means the JSP form generated to test the Java proxy won't have input fields for the OrderLineItems. You'll need to customize the JSP code to handle the OrderLineItems.

This problem refers only to the JSP code generation, and not the Java proxy code that is generated from the Export WSDL, which does contain methods to handle arrays of business objects. Therefore, the problem exists only in the JSP test client. Since this JSP code is used for testing and is not likely to be used in a production environment the effects of this are minimal.


Conclusion

In this article, you've learned how the flexibility of the SCA runtime and client programming model allows Web service clients to invoke Process Server services. You can select from many options for client programming based on your unique business requirements: interaction style, operation type, binding type to name a few.

Resources

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere
ArticleID=155275
ArticleTitle=Web services client programming for WebSphere Process Server
publish-date=08212006