Configuring SCA HTTP binding to enable real-life scenarios

You can use HTTP bindings supported by IBM WebSphere Integration Developer Version 6.1 in many common real-life integration scenarios involving Service Component Architecture (SCA) applications. For example, by properly configuring the HTTP bindings you can expose SCA applications as a simple HTTP URL using HTTP export binding; enable SCA applications to consume third party XML Web services using HTTP import binding; and use HTTP bindings to integrate multiple SCA applications.

Using a downloadable, hands-on, sophisticated example SCA application, you see how to configure the key HTTP binding attributes to enable these scenarios. It is intended for WebSphere business integration consultants and developers who want to integrate SCA applications using HTTP infrastructure.

You should have a good understanding of an SCA application's structure, common SCA components (Java™ Component, BPEL component, Mediation Flow, XSL transformation map), SCA bindings and their common configuration attributes (Function selector, Data binding), SCA mediation, the WebSphere Integration Developer 6.1 tooling environment, and HTTP infrastructure. Understanding the sample Web client code requires some knowledge of JavaScript and basic HTML. For help in learning more about these topcis see Resources.

Share:

Eugene Kharlamov (eugenek@ca.ibm.com), Advisory Software Engineer, WebSphere Integration Developer, IBM

Eugene Kharlamov photoEugene Kharlamov is a Software Developer on the IBM Integration Bus Development Team. He has 15 years of experience with IBM in product development and consultant roles for different WebSphere products. You can contact Eugene at eugenek@ca.ibm.com.



Mihnea Galeteanu (mihneag@ca.ibm.com), Staff Software Engineer, WebSphere Integration Modeler , IBM

Mihnea Galeteanu photoMihnea Galeteanu is a Software Engineer at the IBM Toronto Lab, Ontario. He works on the business process editor for WebSphere Business Modeler.



26 March 2008

Introduction

The SCA HTTP Binding was introduced in Version 6.1 of WebSphere Integration Developer (hereafter called Integration Developer) and WebSphere Process Server (hereafter, Process Server). This binding uses the HTTP data transfer protocol which is widely used throughout the world.

Enabling this new binding in the WebSphere Business Integration (WBI) world helps you to easily compose HTTP-based services and to enhance the accessibility, performance, and scalability of your SCA applications. You can use the binding to enable an SCA application to consume a wide variety of HTTP-based applications existing on the World Wide Web. You can also create end points that are consumable by HTTP clients, including those that can run in a simple Web browser. Finally, you can now more easily integrate your WebSphere business integration applications with new emerging Web 2.0 technologies.

This article provides a fully configured sample application and walks you through several common scenarios to create and configure HTTP SCA import and export bindings. You see how to use HTTP bindings to make this application consumable by HTTP clients, how to consume an external HTTP XML service, and how to integrate SCA application modules using HTTP. You learn about specific configuration points that are required for each scenario. Last but not least, you see how you can use a custom mediation module and custom data binding with HTTP bindings to perform common tasks in a very simple way.

This article is not intended to explain every HTTP binding configuration attribute or possible usage scenario.

Introducing the use cases

Four scenarios illustrate the common capabilities of the HTTP bindings.

  • Scenario 1: Expose an SCA application through an HTTP GET operation that returns a response message in XML format.

    The sample application demonstrates how the HTTP export binding can use plain XML or Atom feed format. In this case, a client running in a Web browser invokes the sample SCA application through the simple HTTP URL that defines the application's entry point. The full power of a business integration application is exposed using the familiar Web browser user interface.

  • Scenario 2: Expose an SCA application through an HTTP POST operation which accepts requests in XML format.

    This scenario showcases the use of AJAX as the front-end to an SCA application. It is a great starting point for anyone wishing to build a rich internet application that uses a SCA backend.

  • Scenario 3: Enable an SCA application to invoke an external service through an HTTP GET request.

    In this scenario, the service response format is XML. You see how to easily integrate third party, light-weight Web services, such as Atom/RSS feeds and REST services, into any SCA application.

  • Scenario 4: Use HTTP bindings as an integration point for multiple SCA applications that use the HTTP infrastructure as a communication mechanism.

    In this scenario, you see how to easily configure one SCA application to invoke another SCA application through HTTP Import and Export bindings.

Sample application description

The download contains a Project Interchange archive file ( Application.zip). It contains the fully-configured sample application, ready to be deployed and run. You can import it into your workspace, explore the application, and then deploy and run it on the WebSphere Process Server 6.1 test environment.

The sample SCA application illustrates the scenarios mentioned above. The goal of the application is to expose an internal data source of Customers (in this case a simple XML file) to the Web using a couple of Web 2.0 technologies: a Google map and an Atom feed. To display the fictitious Customers on the map, the application uses a third party REST service, geocoder.ca, which can return the latitude and longitude of any address in the United States and Canada.

The application includes two SCA modules, a library module and a client Web application. The library module contains common WSDL interface and business objects. The CustomerLocations mediation module (Figure 1) exposes the application to the outside world through HTTP bindings. It contains two HTTP export bindings, CustomerLocationsExportAsFeed and CustomerLocationsExportAsXML, and the custom CustomerLocations mediation component that processes the URL query and forwards the request to another SCA Component using an HTTP import binding, GetCustomersWithLocationsHTTPImport, which invokes the Customers SCA module using HTTP.

Figure 1. CustomerLocations application assembly
Figure 1. CustomerLocations application assembly

Figure 2 shows theCustomers module which consists of the GetCoordinates HTTP import binding that invokes the external REST service provided by geocoder.ca. It also includes an HTTP export binding component, GetCustomersWithLocationsExport,invoked by the HTTP import binding component from the CustomerLocations mediation module. A simple Java component named GetCustomers loads an XML file (see Customers\sca\component\java\impl\Customers.xml ) and returns a list of Customers business objects.

The HTTP export binding, AddCustomerExport, is used by an external application to add new Customers to our XML repository by simply POSTing XML over HTTP. The BPEL component, GetCustomersWithLocations, ties it all together by invoking the REST service (described above, from geocoder.ca) for each Customer retrieved from our XML repository.

Figure 2. Customers application assembly
Figure 2. Customers application assembly

The HTTPExportToGoogleMap Web project contains an HTML page (customersMap.html) that creates a mashup to display the Customers' locations on the Google map, as shown in Figure 3. It also enables filtering of the Customers that are displayed based on their type.

Figure 3. Google map client displays customer location
Figure 3. Google map client displays customer location

Figure 4 shows another HTML page, addCustomer.html, that lets you add new customers to the data source by invoking an SCA HTTP Export binding component through the HTTP POST method.

Figure 4. HTML form client to add new customers
Figure 4. HTML form client to add new customers

Scenario 1: Configuring an HTTP export binding for GET requests

The HTTP export binding enables an SCA application to be exposed to Web browsers, or any other HTTP-enabled client application, using HTTP methods such as GET or POST.

This scenario shows how to configure an HTTP export binding ( CustomerLocationsExportAsXML) to accept GET requests from, and to return an XML-formatted response to, an HTML page running in a Web browser.

You can use either of these techniques for handling simple dynamic GET requests that contain query parameters in the request URL:

  • Provide a custom data binding that is capable of setting a business object's fields by parsing the query parameters.
  • Handle this conversion in a mediation module with custom mediation or with an XSL transformation.

The sample application showcases the second option, XSL transformation, which does not require writing any custom Java code.

To provide the response to the calling application in XML format, you use the HTTPStreamDataBindingXMLdata binding, as shown in Figure 5. This binding, which is provided by Integration Developer, supports business object to XML conversion.

Next, you define a function selector for the HTTP SCA export. Using the HTTP request it receives, the function selector determines and locates the method on the SCA interface to invoke.Integration Developer provides two selectors:

  • One function selector, UrlMethodFunctionSelector, combines a request HTTP method with a method binding context path fragment to find the target operation on the SCA interface.
  • The other function selector HeaderHTTPFunctionSelector requires a custom HTTP header to contain the native method key pointing to the target operation. You can find more about this function selector in Scenario 4: Configuring SCA module-to-module integration over HTTP.

The simple HTML client in the sample application cannot set the custom header. Therefore, for this scenario, you use the first selector, UrlMethodFunctionSelector, as shown in Figure 5.

Figure 5. Function selector and data binding configuration
Figure 5. Function selector and data binding configuration

The function selector defines the value of a native method for the method binding. For the function selector required by this scenario, you need to make sure that the method binding contains a native method attribute in a specific format (<Context path>@<HTTP method>), for example, as shown in Figure 6.

Figure 6. Native method configuration
Figure 6. Native method configuration

Important: Make sure that the HTTP Method Settings list contains the HTTP method(s) used by this operation; in this scenario, we use GET, as shown in Figure 7.

Figure 7. HTTP method configuration
Figure 7. HTTP method configuration

The URL context path for the HTTP export binding consists of the context path specified on the Binding (Figure 8) and Method bindings (Figure 9) configuration panels. You specify the first URL context path token on the Binding tab configuration panel (Figure 8).

Figure 8. Binding context path configuration
Figure 8. Binding context path configuration

Specify the second URL context path token on the Method bindings =>Generic tab configuration panel (Figure 9).

Figure 9. Method binding context path configuration
Figure 9. Method binding context path configuration

Figure 10 shows the Summary tab panel which displays the combined context path for each method binding.

The full value of the context path includes the Web application name as a first element of the combined context path. To invoke this export, you only need to specify the host and port in front of the context path:

http://localhost:9080/CustomerLocationsWeb/CustomerLocationsExportAsXML/getCustomers
Figure 10. Summary panel with combined context path
Figure 10. Summary panel with combined context path

After you have completed configuring all of the attributes for the HTTP export binding as just described, it is enabled to be invoked from a Web browser.

An XSL transformation maps incoming URL query parameters to corresponding fields on business objects as required by the interface operation (Figure 11). To see how to use the transformation for this purpose, within the mediation flow editor for the CustomerLocations component, double-click on the Extract Type From Query String node (Figure 11a).

Figure 11. XSL transformation map editor
Figure 11. XSL transformation map editor
Figure 11a. Mediation module editor
Figure 11a. Mediation module editor

Inside the inline map, the invocation URL is stored inside the transient context (Figure 11b).

Figure 11b. Inline map in the XSL transformation map editor
Figure 11b. Inline map in the XSL transformation map editor

The URL value stored in the context is used later on in the more advanced Scenario 1A where the response of the operation is transformed into an Atom feed format.

So far, you have seen how to configure the HTTP export binding to return an XML response to the invoking application.

Now, install this application on your server, and point your browser to:

http://localhost:9080/CustomerLocationsWeb/
CustomerLocationsExportAsXML/getCustomers?type=Software

You see an XML document that contains all the Customers of type Software and the coordinates (latitude and longitude) corresponding to their address.

For a sample use of this service inside an HTML page, see HTTPExportToGoogleMap\WebContent\customersMap.html inside the download.

Scenario 1A: Configuring HTTP response to be an Atom feed

To see a more advanced example that returns an Atom feed instead of a plain XML document, refer to the getCustomersAsFeed interface operation implementation in the CustomerLocationsmediation (Figure 12).

Figure 12. Atom feed implementation components in the mediation flow editor
Figure 12. Atom feed implementation components in the mediation flow editor

This advanced flow and the simple flow described above look similar; in fact, they use the same XSLT Transformation file, CustomerLocations\XSLTransformation2_req_1.map, in the Extract Type From Query String node). However, before returning the response to the invoking application, the advanced flow transforms the list of Customersusing a second XSL Transformation into an Atom feed (Figure 13).

Figure 13.Atom feed XSL transformation map
Figure 13.Atom feed XSL transformation map

The feed business object is instantiated through the transformation such that:

  1. The title is assigned a static value.
  2. The feed link's href value is assigned from the transient context. For example:
    http://localhost:9080/CustomerLocationsWeb/
    CustomerLocationsExportAsFeed/getCustomersAsFeed?type=Software

    Tip: Remember that we stored the invoking URL in the transient context in the Extract Type From Query String transformation for this purpose.

  3. For each Customer a corresponding feed entry is created in the Inline map (Figure 14).
Figure 14. Href mapping using XSL transformation
Figure 14. Href mapping using XSL transformation

Within the inline map, the name of the customer becomes the title of the feed entry. In addition, the latitude and longitude are appended to a Google Map URL and set on the entry's link href value (for example, http://maps.google.com/maps?f=q&q=30.399601+-97.718431+&z=14) such that when you click on the feed entry in the Sage viewer, the location of this customer displays on the map.

To access the feed, as shown in Figure 15, point your browser to:

http://localhost:9080/CustomerLocationsWeb/
CustomerLocationsExportAsFeed/getCustomersAsFeed?type=Software
Figure 15. Atom feed XML output view
Figure 15. Atom feed XML output view

This feed can also be displayed by Atom feed readers such as Sage (Figure 16).

Figure 16. Atom feed Sage output view
Figure 16. Atom feed Sage output view

Select a feed entries, and your browser is redirected to a Google Map URL (according to the mapping explained above) that contains the latitude and longitude corresponding to the address for that specific Customer (Figure 17).

Figure 17. Atom feed entry output view
Figure 17. Atom feed entry output view

Scenario 2: Configuring an HTTP export binding for POST requests

This scenario shows how to configure the AddCustomerExportHTTP Export in the Customers module to receive HTTP POST requests in XML format over HTTP. You see only the differences between this configuration and Scenario 1 for the GET request.

The method bindings settings must indicate that the export is expecting a POST request. So, the native method and HTTP Method Settings list must include POST as a value (Figures 18 and 19).

Figure 18.Native method configuration
Figure 18.Native method configuration
Figure 19. HTTP methods configuration
Figure 19. HTTP methods configuration

Then, see Scenario 1 for the additional detailed requirements for configuring an HTTP Export configuration.

For an example of using the XMLHttpRequest to invoke the interface operation exposed by this HTTP Export, please refer to HTTPExportToGoogleMap\WebContent\addCustomer.html in the download. Listing 1 shows the format of the XML document that is posted to /CustomersWeb/AddCustomerExport/addCustomer.

Listing 1. XML document format
<?xml version='1.0' encoding='UTF-8'?>
<addCustomer xmlns='http://CustomersLib/AddCustomer'>
<name>testName</name>
<type>testType</type>
<address>testAddress</address>
</addCustomer>

Important: The namespace of the XML document must be the same as the namespace of the AddCustomerinterface whose operation you are trying to invoke.

Scenario 3: Configuring HTTP import binding

The SCA HTTP import binding enables SCA applications to directly invoke external services over HTTP, as opposed to using SOAP over HTTP which is what the SOAP Web service bindings support. In the sample application, the Customers module uses an HTTP import component to invoke the geocoder.ca REST service by passing any North American address as a query parameter on an HTTP GET request. The returned XML response message contains the latitude and longitude of the given address. To see a sample response of this service, append a North American address to this URL:

http://geocoder.ca/?geoit=xml&locate

For example, if you point a Web browser to the following URL, the browser displays coordinates for a given address in the format shown in Listing 2.

http://geocoder.ca/?geoit=xml&locate=8200%20Warden%20Avenue,%20markham,%20ON
Listing 2. Sample response from the Geocoder service
<geodata>
<latt>43.851361</latt>
<longt>-79.332975</longt>
</geodata>

In this scenario, the HTTP import binding component (GetCoordinates) uses a custom data binding class to facilitate the manipulation of both the request and response HTTP messages.

The RESTImportBinding data binding class (Customers\rest\RESTImportBinding.java)implements two methods. The convertToNativeData()method reads the address field from the request business object passed to the SCA interface operation, and it appends it to the query parameters of the URL to call the geocoder.ca service.

Listing 3. Sample implementation of convertToNativeData() method
public void convertToNativeData() throws DataBindingException 
{
   DataObject dataObject = getDataObject();
   try 
   {
	//Get value for the address attribute from the data object
      String address = 
         URLEncoder.encode(dataObject.getString("address"), "UTF-8");
  	
      //Get HTTP control parameters
      HTTPControl controlParameters = getControlParameters();
	
      //Update URL with the customer address
	String url = controlParameters.getDynamicOverrideURL() + address;	

      //Set dynamic override URL	
      controlParameters.setDynamicOverrideURL(url);
    } catch (UnsupportedEncodingException e) {}		
}

The convertFromNativeData()method reads the response XML data and sets the appropriate fields on the response business object.

Listing 4. Sample implementation of convertFromNativeData() method
public void convertFromNativeData(HTTPInputStream arg0) 
    throws DataBindingException, IOException 
{
   //Get a service manager and business object factory
   ServiceManager serviceManager = ServiceManager.INSTANCE;
   BOFactory bofactory = (BOFactory)  
      serviceManager.locateService("com/ibm/websphere/bo/BOFactory");

   //Create a new Coordinates data object
   DataObject coordinates =
      bofactory.create("http://CustomersLib","Coordinates");

   //Parse response XML object 		
   ByteArrayOutputStream out = new ByteArrayOutputStream();
   byte[] buf = new byte[1024];
   int read = -1;
   while((read = arg0.read(buf, 0, 1024)) != -1) 
   {
	out.write(buf,0, read);
   }		
   DocumentBuilderFactory factory = 
      DocumentBuilderFactory.newInstance();
   factory.setNamespaceAware(false);
   try 
   {
      Document rdf = factory.newDocumentBuilder().parse(
         new ByteArrayInputStream(out.toByteArray()));

      //Set data object attributes based on the response data
	coordinates.setString("latitude", XPathAPI.selectSingleNode(rdf,
         "/geodata/latt/text()").getNodeValue());
	coordinates.setString("longitude", XPathAPI.selectSingleNode(rdf, 
         "/geodata/longt/text()").getNodeValue());
   }
   catch(Exception e) {}

   //Set coordinates response data object
   setDataObject(coordinates);
}

You set this data binding on the HTTP import binding component Binding configuration panel (Figure 20). The same configuration panel specifies the static part of the URL of the external service (http://geocoder.ca/?geoit=xml&locate=) and the HTTP method (GET) that will be used for invocation.

Figure 20. HTTP Import endpoint URL and data binding configuration
Figure 20. HTTP Import endpoint URL and data binding configuration

Every method binding (Figure 21) can override information specified on the Binding tab configuration panel.

Figure 21. HTTP import method binding URL and HTTP method configuration
Figure 21. HTTP import method binding URL and HTTP method configuration

But in this case it is redundant because there is only one method binding for the method getCoordinates().

Scenario 4: Configuring SCA module-to-module integration over HTTP

In this scenario, the Customers and CustomerLocations SCA modules are integrated using HTTP bindings. The easiest way to create a matching HTTP import binding component in Integration Developer is to drag one module's HTTP export from the Business Integration view and drop it on to the Assembly Diagram of the second module. A new HTTP import component, with attributes matching the source HTTP export binding, is created. In the sample application, GetCustomersWithLocationsHTTPImport component was created by dragging GetCustomersWithLocationsExport to the CustomerLocations assembly editor.

In this case, you specify HeaderHTTPFunctionSelector for the HTTP export binding component(Figure 22), which uses a custom HTTP header TargetFunctionName from the request to locate the target operation on the SCA interface. It uses XML data binding for the request and response. You specify the name of the export as a default part of the context path on the Binding tab configuration panel.

Figure 22. HTTP Export function selector and data binding configuration
Figure 22. HTTP Export function selector and data binding configuration

Specify the method binding part of the context path on the Method binding => Generic tab configuration panel. By default, it matches the name of the method on the getCustomers interface. The format of the native method is different from that in Scenario 1 mentioned above where a different function selector was used (Figure 23). In this case, the value of the configured native method must match the value passed by the client in the TargetFunctionName HTTP header.

Figure 23. Method binding context path and native method configuration
Figure 23. Method binding context path and native method configuration

To enable this HTTP export binding to process either the default GET HTTP method or another method (for example, POST), specify it on the Method bindings => HTTP Method Settings tab configuration panel (Figure 24).

Figure 24. Method binding HTTP methods configuration
Figure 24. Method binding HTTP methods configuration

The same values specified on the Method bindings configuration panel always override values specified on the binding levels, except for the Context path attribute. Context path values are combined to construct the complete URL context path for each method binding (Figure 25).

Figure 25. Summary context path
Figure 25. Summary context path

After the HTTP export binding component is fully configured, create and configure a new HTTP import binding. First, decide what method binding of the HTTP import binding component will be used to invoke the target HTTP export binding URL.

On the Method binding => Generic tab configuration panel, make sure that the endpoint URL points to a valid deployed URL exposed by the HTTP export binding. WebSphere Integration Developer assumes that the host name is localhost and port 80. You might want to change these values, depending on the target deployment server host name and HTTP port. In this scenario the port is 9080.

Specify the correct invocation HTTP method supported by the target HTTP export binding component (Figure 26). In this scenario, Export supports POST and GET, and the HTTP import binding component is configured to use method POST.

Figure 26. Method binding endpoint URL and HTTP method configuration
Figure 26. Method binding endpoint URL and HTTP method configuration

While integrating two HTTP bindings, make sure that HTTP import provides all required information for the target HTTP Export function selector. In this scenario, the target function selector uses TargetFunctionName http header (Figure 27). Therefore, you specify this header value on the Method Bindings => HTTP Headers tab configuration panel. The value of the header must match the native method name specified on the export.

Figure 27. Method binding HTTP headers configuration
Figure 27. Method binding HTTP headers configuration

After the HTTP import is configured, this integration scenario is complete.

Running the application

After the configuration for all the scenarios is complete, you can deploy and run the client HTML pages in the Web browser using the following URL:

http://localhost:9080/HTTPExportToGoogleMap/customersMap.html

The page displays customer locations pinned on the Google map. Wait a few seconds while the customer locations display on the map.

To add a new customer, use:

http://localhost:9080/HTTPExportToGoogleMap/addCustomer.html

You need to deploy both enterprise applications to the target server (Figure 28) in order to run the client. The HTTPExportToGoogleMap Web project, which contains the Google Map and the Atom Feed examples, is automatically deployed, along with CustomerLocationsApp,because it was specified in the list of that mediation module's dependencies.

Figure 28. Server with deployed applications
Figure 28. Server with deployed applications

Conclusion

You have seen the primary configuration topics and possible solutions that enable SCA applications to work in the most common HTTP-related real-life scenarios in Integration Developer 6.1. These scenarios can be implemented in a fairly straight forward fashion.

You have also seen a fully-configured, non-trivial SCA sample application that is capable of handling dynamic URLs, POST and GET methods, Atom feed requests, and so on. This application was built using a set of tools familiar to any WebSphere business integration consultant or developer, and it required almost no custom Java code. The sample application demonstrated the use of custom data binding as a useful and simple implementation option for handling the message formats of external services.

In summary, WebSphere business integration HTTP binding capabilities help make the SCA application a well-integrated player in the business world of the World Wide Web.


Downloads

DescriptionNameSize
Sample application codeApplication.zip48 KB
Sample application codeApplication6101.zip51 KB

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 Business process management on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Business process management, WebSphere
ArticleID=297237
ArticleTitle=Configuring SCA HTTP binding to enable real-life scenarios
publish-date=03262008