Using SCA HTTP binding in typical real-life scenarios with WebSphere Integration Developer

This article is created based on readers' feedback to the first article that described some of the aspects of the Service Component Architecture (SCA) HTTP binding configuration for advanced usage scenarios. The focus of the first article was on Web 2.0 technologies.

Share:

Eugene Kharlamov (eugenek@ca.ibm.com), Software Developer, IBM Integration Bus Development Team, 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.



John Green (green@ca.ibm.com), Release Architect, IBM

Author photoJohn Green is a WebSphere Integration Developer Release Architect at the IBM Toronto Lab, Ontario, Canada.



01 April 2009

This article will address some common scenarios that involve SCA HTTP binding, but not covered by the first article. These scenarios include using IBM® WebSphere® Integration Developer Version 6.2 (hereafter called Integration Developer) for:

  • Configuring SCA HTTP import and export bindings for handling simple plain-text POST and GET requests with variable parameters.
  • Handling JSON requests using the JSON data format handler.
  • Creating and configuring the custom function selector that uses URL query parameters.
  • Handling ATOM feed.
  • Enabling SCA HTTP import binding to communicate with services using SSL protocol.

The purpose of this article is to provide hands-on examples to help build an SCA application using HTTP bindings. It is intended for WebSphere Business Integration (hereafter called Business Integration) consultants and application developers who are interested in integrating SCA applications using an HTTP infrastructure.

You need a good understanding of an SCA application's structure, common SCA components (Java™ component), SCA bindings and their common configuration attributes (function selector, data handlers), Integration Developer tooling environment, and HTTP infrastructure. Understanding the provided sample Web client code requires some knowledge of JavaScript and basic HTML. Understanding of the provided sample custom data handler, data binding, and function selector require understanding of the Java programming language.

Introduction

The SCA HTTP binding is designed to connect SCA applications with existing Web applications. Typically, existing Web applications use HTTP GET requests using a query with variable parameters to retrieve data from the server. The HTTP response content depends on the URL parameters. HTTP POST requests containing name-value pairs are frequently used for updating and creating data on the target server. HTML forms using plain text format for the request body provide the simplest way of creating and sending such requests. Since these use cases are so simple and powerful, at the same time, they have become extremely popular. While Integration Developer and IBM WebSphere Process Server (hereafter called Process Server) provide tooling and runtime support for these scenarios, there is no provided data format handler that handles these use cases. This article will describe how a sample implementation of the data binding and handler can be built and configured to solve this issue. Encapsulating this transformation algorithm into the Java handler class makes it easy to re-use, share, and distribute it across multiple applications or deployment servers.

SCA Export bindings use a component called Function Selector that is responsible for selecting the target operation. In the case of using SCA HTTP export binding for connecting SCA application to the Web, HTTP request provides multiple attributes and parameters that you can use as the criteria for selecting the target operation. Integration Developer provides flexibility for configuring the HTTP export binding with the custom function selector, in addition to the number of out-of-the-box selectors. In many cases, selectors shipped with the product may be sufficient. But there are cases when custom function selector may be more useful. This article will cover both implementation options.

JavaScript Object Notation (JSON) is the Internet application format rapidly gaining popularity within the Web development community. It uses the extremely popular Web development language Java Script. IBM provides a JSON data handler in Integration Developer. This article will explain how this JSON data handler works and how to integrate SCA HTTP bindings with Web applications that use JSON format for the request and response body format.

Another common popular Web format is Atom feeds. Our last article described how to use third party XML schema and XML binding to support this format by the SCA HTTP binding. Integration Developer 6.2 provides an Atom feed business object schema and data handler. This article will demonstrate how to configure and use these new features.

It is hard to imagine a real-life Web enterprise application that would not use Secure Socket Layer (SSL) protocol. SCA HTTP import binding configuration allows users to configure SSL. This article will provide step-by-step instructions on how to configure the SCA HTTP binding configuration attributes for SSL.

This article helps you understand all of the above mentioned topics by demonstrating the sample application configuration or step-by-step instructions.


Scenarios

  • Scenario 1: Configure an SCA application to be exposed via HTTP URL accepting variable query parameters. It will use HTTP GET method to retrieve the application data. HTTP export binding will use a custom configurable data binding for parsing the variable part of the URL and populating the business object fields based on the configuration settings.
  • Scenario 2: Enable the SCA HTTP export binding for selecting the correct operation on the SCA interface based on the request URL query parameters. We will explain how the out-of-the-box function selector can be configured to perform this task. As a more flexible alternative, the sample application will demonstrate how to use the custom configurable function selector for selecting target operation based on the information available in the HTTP request.
  • Scenario 3: Expose a SCA application via an HTTP endpoint that accepts POST requests in the plain text format created by HTML forms. This scenario showcases the use of the custom data handler that transforms plain text POST request data into the business object. The custom configurable data handler will be using configuration parameters to map between the business object fields and POST request parameters.
  • Scenario 4: Enable a SCA application to invoke an external service that returns response in JSON format using an out-of-the-box JSON data format handler.
  • Scenario 5: Enable a SCA application to be invoked by an Atom feed client. In this case, SCA HTTP export binding will send a response in the Atom feed format. The sample application will demonstrate how to configure the HTTP export component and map out-of-the-box Atom feed business object to a generic business object.
  • Scenario 6: Enable an SCA application to invoke an HTTP URL via SSL. We will provide detailed step-by-step instructions.

Figure 1 (see enlarged Figure 1) shows the sample integration solution, CustomerSolution, with the HTTP endpoints implementing the above mentioned scenarios.

Figure 1. Customer solution
Customer solution

Sample applications description

If you read our first article, you find that the new sample application familiar. The new application intentionally re-uses some slightly modified parts from the previous application so that you can focus on the new features.

The application is designed to demonstrate all of the above mentioned scenarios except SSL. The application consists of the client JSP page (SimpleListCustomers.jsp) that displays the list of the existing customers stored locally in the XML file (Figure 2).

Figure 2. Customers' list
Customers' list

By selecting the Map link for the customer, a new HTML page is launched (customersMap.html), displaying the selected customer's home and current geographical locations on the Google® map (Figure 3). The fictitious current location coordinates are generated in a random manner.

Figure 3. Customer location map
Customer location map

Selecting the Name link launches another JSP page (ProcessCustomer.jsp) that displays pre-populated HTML form (Figure 4) that you can use for updating the customer's type and address.

Figure 4. Customer update form
Customer update form

By selecting the Add a new customer link, the user can launch the same form (Figure 5) with empty fields for adding a new customer.

Figure 5. New customer form
New customer form

To display the home location on the map for the selected fictitious Customer, the application uses a third party HTTP XML service, which returns the latitude and longitude for the given customer's address. A fictitious current location coordinates is generated by the external HTTP JSON service. For simplicity, both services are implemented as JSPs (GetHomeCoordinates.jsp, GetLocationCoordinatesJSON.jsp) in the separate Web application (GenerateCustomerLocationService). From our main SCA application point of view, they are external HTTP services that are invoked using HTTP URL as any other service of this kind. XML and JSON are used as the service response formats.

You can also view the customers using the Atom feed client (Figure 6). Clicking on the customer entry opens a Google map for the customer's home location.

Figure 6. Firefox Sage Atom feed client view of the Customers
Firefox Sage Atom feed client view of the Customers

To demonstrate all of the above mentioned features, our application includes one SCA module Customers, the library module CustomersLib, a client Web application HTTPExportToGoogleMap, and a Web application GenerateCustomerLocationService, providing a simulated external HTTP/JSON service.

The library module contains common WSDL interfaces, business objects and custom Java classes for data handler, data bindings, and the function selector.

The Customers module (Figure 7) contains:

  • Three HTTP export bindings (AddCustomerExportText, GetCustomersWithLocationsExport, and GetAtomFeedCustomers)
  • A custom mediation component (AtomFeedMappingComponent) that performs mapping for the Atom feed scenario
  • HTTP import binding (GetCoordinates) used to invoke the external HTTP XML service
  • A simple Java component (GetCustomers) that can read and update an XML file (Customers.xml) and returns a list of customers
  • Another HTTP import binding (GetCurrentCoordinates) that invokes a simulated external HTTP/JSON service that returns fictitious current coordinates for the given customer
Figure 7. Customers module assembly
Customers module assembly

The SCA HTTP export component (AddCustomerExportText) is invoked by the HTML form that adds a new or updates an existing customer. Another SCA HTTP export component (GetCustomersWithLocationsExport) is invoked by a simple GET HTTP request with no body and returns XML formatted response containing the list of all the customers in the XML file. The SCA HTTP export component (GetAtomFeedCustomers) uses the Atom feed data handler and the interface that uses the out-of-the-box Atom feed business object. The BPEL component (GetCustomersWithLocations) ties it all together by invoking the above mentioned HTTP services by retrieving home and current coordinates for each Customer.

The HTTPExportToGoogleMap Web project contains the following pages:

  • SimpleListCustomers.jsp: JSP page that invokes URL using GET request and populates HTML table with the customers' data received from the SCA application in XML format.
  • customersMap.html: HTML page that uses a mashup to display home and current locations of the selected customer on the Google map.
  • ProcessCustomer.jsp: JSP page that is used to display a HTML form for updating an existing customer or adding a new customer. It invokes the SCA HTTP export component (AddCustomerExportText) using HTTP POST plain text request.
  • SubmitRequest.html: A utility HTML page that is used to complete the update/create process. The browser is redirected to it once the POST request is sent by ProcessCustomer.jsp.

The GenerateCustomerLocationService Web project contains the JSP pages GetHomeCoordinates.jsp and GetLocationCoordinatesJSON.jsp that return home and simulated current location coordinates. These JSP URLs are invoked by the sample SCA application as an external service through the HTTP SCA import components (GetCoordinates, GetCurrentCoordinates). The JSP GetLocationCoordinatesJSON.jsp generates the response in the JSON format. Note that this JSP uses the JSON tag library. json.tld and json-taglib-0.4.1.jar are downloadable from http://json-taglib.sourceforge.net/.


Scenario 1. Transforming the HTTP URL query parameters into the business object

It would not be a mistake to say that HTTP GET requests with variable query parameters are the most common way to retrieve data from the Web. Therefore, it is reasonable to provide a simple way of mapping native HTTP GET request query parameters to the fields of the data object. In the previous article, we showed how you can use the mediation flow component (further referenced as MFC) mapping for this purpose.

However, if you wanted to make it easier to distribute and reuse this transformation logic without replicating MFC mapping, it makes sense to encapsulate it into the Java class. Once this Java class is on the class path of the module, you can set it can as a data format handler on the HTTP SCA binding.

There are two interfaces supported in Integration Developer 6.2 to create data format transformation Java classes. The first one is the data binding (commonj.connector.runtime.DataBinding). The second is the data handler (commonj.connector.runtime.DataHandler). The difference between the two is that the data bindings are typically transport/binding specific (for example, HTTP, JMS, and so on), while data handlers are meant to be reusable across different types of SCA bindings.

In this scenario, we do not expect any payload in the HTTP request. All the data you need is contained in the URL query. Therefore, it is a transport specific transformation. The custom class text.db.URLExportDataBinding (CustomersLib/gen/src/text/db/URLExportDataBinding.java) will implement a HTTPStreamDataBinding and BindingContext interfaces. It is designed to extract query parameters from the HTTP URL and to create a data object based on the URL parameters' values. It will be used only to process incoming data. The outgoing data will be processed by the out-of-the-box XML data handler. Therefore, in addition to the primitive getters and setters, we only need to implement three methods: setBindingContext(Map m), convertFromNativeData(), and getDataObject(). Method setBindingContext(Map m) reads the context and detects the data object type that needs to be created (Listing 1).

Listing 1. Sample implementation of setBindingContext() method
publicvoid setBindingContext(Map arg0) {
   bindingContext = arg0;
   QName qname = (QName)bindingContext.get("ExpectedType");
   if(qname != null)
   {
      targetNamespace = qname.getNamespaceURI();
      localName = qname.getLocalPart();
   }

Method convertFromNativeData() is called to transform the native HTTP request into the data object. It reads the URL from the HTTP control and extracts query parameters from it (Listing 2). Then it calls the method getDataObject() (Listing 3) to get an instance of the data object based on the value discovered from the binding context. Once the data object is returned, the value of the query parameter is set on the data object.

Listing 2. Sample implementation of convertFromNativeData() method
public void convertFromNativeData(HTTPInputStream arg0) throws DataBindingException, 
 IOException 
{
   String url = fieldControl.getURL();
   String query = url.substring(url.indexOf("?")+1);
		
    if (query.indexOf('&') == -1)
   {
      //In the sample application we only expect one parameter which is  
      //enough for demonstrating functionality.
	//If there are more than one query parameters in the URL we would   
      //have to go to the ELSE and loop through all of them
	String nvpName = query.substring(0, query.indexOf("="));
	String nvpValue = query.substring(query.indexOf("=")+1);

      //Create data object
	getDataObject();
	//We assume that the name of the query parameter must match the //name of the 
      Data Object field
	if (fieldDataObject.getInstanceProperty(nvpName) != null)
	{
	   //If the property with the given name exists then set it
	   fieldDataObject.setString(nvpName, nvpValue);
	}
   }
   else
   {
	//If we had more than query parameters then we would have to loop 
      //through all of them and try to set the fields in the DataObject
   }
}
Listing 3. Sample implementation of getDataObject() method
public DataObject getDataObject() throws DataBindingException {
   if (fieldDataObject == null)
   {
      ServiceManager serviceManager = ServiceManager.INSTANCE;
	BOFactory bofactory = (BOFactory)  
        serviceManager.locateService("com/ibm/websphere/bo/BOFactory");
   	fieldDataObject = bofactory.create(targetNamespace, localName);
   }
   return fieldDataObject;
}

Once this class is implemented, you need to put in the library module (CustomersLib), which is on the dependency list of the integration module (Customers). In this way, this class is on the class path of the module. You can use it to configure the HTTP export component GetCustomersWithLocations. As we mentioned earlier, this data binding class is only designed to process incoming requests. You need to navigate to the Method Bindings panel on the Properties view and select the Data Serialization tab for the operation getCustomers(). To set the incoming data binding class, click the Select button for the Input data format field (Figure 8).

Figure 8. Operation input data format selection panel
Operation input data format selection panel

On the data transformation selection wizard, select the radio button that enables selection of the custom data binding class (Figure 9). Then select the URLExportDataBinding class on the class selection dialog.

Figure 9. Selecting custom data binding
Selecting custom data binding

Once the data binding is set on the HTTP export component, it will be used by the runtime to process data format transformation for the incoming requests (Figure 10). Now the binding is configured to map URL query parameters to the business object fields.

Figure 10. Binding configured with the custom data binding
Binding configured with the custom data binding

Note that for the response, you use the out-of-the-box XML data handler configuration. As a result, when the HTTP export component is invoked using the following URL:

http://localhost:9081/CustomersWeb/GetCustomersWithLocationsExport/getCustomers?type=*

The value of the type query parameter from the URL will be mapped to the field type of the business object CustomerType.


Scenario 2. Selecting the target interface function to invoke using the HTTP URL query parameter

The HTTP export binding component AddCustomerExportText in the module Customers is configured to receive HTTP POST requests in the plain text format over HTTP. The request is submitted from the simple HTML form built by the ProcessCustomer.jsp. There are two operations (addCustomer and updateCustomer) on the interface bound to the HTTP export component. SCA uses function selectors to select an interface operation to invoke at runtime.

The question is what function selector to use in our scenario. There is an existing out-of-the-box function selector that uses a combination of the method binding context path and HTTP method to select an operation. If the client uses different URLs or different HTTP methods to invoke different operations, then you can use the above mentioned out-of-the-box function selector.

In this scenario, the client JSP will append to the URL a query parameter action that can have two different values (Create or Update). When the URL contains the query action=Create, then the operation addCustomer must be invoked. Otherwise, you need to invoke operation updateCustomer.

Since the full URL including the query part is not the same for each operation, then you can use the out-of-the-box function selector. In this case, configure each method binding to use its own context path, by hard coding the query part of the URL (for example, ?action=Add) and specifying the native method according to the function selector rule (<context path>@<http method>).

However, what if you do not want to hardcode the query part of the URL on the method binding of the HTTP export component? In this case, both operations are configured to use the same HTTP method (POST) and URL context path. Therefore, the only option is to develop a custom function selector. Our custom function selector uses the value of the URL query parameter action to match with the native method defined on the method binding.

While designing the new function selector for this specific use case, we also want to show how to make the name of the query parameter configurable. You create a new custom function selector class text.fs.URLQueryParameterFunctionSelector with a configuration properties class text.fs.URLQueryParameterFunctionSelectorProperties. The properties class follows a naming convention, where it matches the name of its function selector class with the suffix "Properties" appended at the end.

Our function selector class must extend class HTTPFunctionSelector and implement methods setBindingContext(Map map) and generateEISFunctionName(). Method setBindingContext() allows the HTTP export binding to pass information to the function selector for discovering the configured function selector properties. It reads configuration parameter functionParameter value and stores it in the instance variable (Listing 4).

Listing 4. Sample implementation of setBindingContext() method in the configurable function selector
publicvoid setBindingContext(Map map)
{
   
   URLFunctionSelectorProperties properties=
      (URLFunctionSelectorProperties)map.  
         get(BindingContext.BINDING_CONFIGURATION);
   if(datahandlerproperties != null)
   {
      functionParameter = properties.getFunctionParameter();
   }
}

Method generateEISFunctionName() parses the URL query and extracts the value for the configured query parameter (Listing 5). This value is returned as a name that must match the native name configured on the method binding (Figure 11). In our scenario, the native name is Create for the operation addCustomer, and Update for the method updateCustomer

Listing 5. Sample implementation of generateEISFunctionName() method
publicfinal String generateEISFunctionName(HTTPControl httpcontrol, 
 HTTPHeaders httpheaders, HTTPInputStream httpinputstream)
    throws SelectorException
{
   String queryString = httpcontrol.getURL();
   queryString = queryString.substring(queryString.indexOf("?")+1);
   //In our sample application the assumption is that our URL query parameter at 
     the end of the URL.
   queryString = queryString.substring(queryString. 
      indexOf(functionParameter)).split("=")[1];
   return queryString;
}
Figure 11. Method binding native method configuration
Method binding native method configuration

Configuration bean class defines the single configuration property functionParameter. The function selector uses the value of this configuration parameter to find the name of the target method from the URL query. Now you can create a new function selector configuration that will be used later for configuring the HTTP export binding. You can create the configuration using the File > New > Binding Resource Configuration menu option on the Business Integration view. The HTTP binding is selected as a binding that can use this function selector configuration (Figure 12).

Figure 12. Function selector configuration
Function selector configuration

Now configure the HTTP binding with this new custom function selector configuration. At this point, the function selection algorithm is defined. However, this use case also includes Scenario 3 because the data is passed to the HTTP export binding in plain text format. Therefore, additional data transformation configuration needs to be done.


Scenario 3. Transforming HTTP POST plain text requests into the business object

The HTTP export binding described in Scenario 2 processes POST requests by updating or adding a new customer. The request is submitted from the simple HTML form in plain text format. The sample request looks like this:

name=Customer+D&type=Research&address=8300+Warden+Avenue%2C+Markham%2C+
Ontario%2C+L6G+1C7&user=eugene

As mentioned in Scenario 2, Integration Developer does not provide a data handler that can process such requests. In this case, compared to the Scenario 1, the handler does not need to access transport specific data. Therefore, the best fit for this occasion is a new custom data handler. To be even more flexible, make the custom data handler configurable.

Our custom data handler class text.handler.PlainTextDataHandler implements the base interface commonj.connector.runtime.DataHandler. In the first method, you need to implement setBindingContext(). This method detects and stores the data object name and namespace. Then it reads the configuration specified on the binding and stores all the configuration values that define the rules for request parsing.

Listing 6. Sample implementation of setBindingContext() method
publicvoid setBindingContext(Map map){

   QName qname = (QName)map.get(BindingContext.EXPECTED_TYPE);
   if(qname != null){
      targetNamespace = qname.getNamespaceURI();
      localName = qname.getLocalPart();
   }    	
   PlainTextHandlerProperties properties = 
      (PlainTextHandlerProperties)map.   
         get(BindingContext.BINDING_CONFIGURATION);
   if(datahandlerproperties != null){
      encoding = datahandlerproperties.getEncoding();
      exlusionList = datahandlerproperties.getExlusionList();
      caseSensitive = datahandlerproperties.isCaseSensitive();
      listSeparator = datahandlerproperties.getListSeparator();
    }
}

The next method to implement is transform(). This method is called when the binding attempts to transform the incoming request body into the business object. It reads the input stream into the bytes, creates a business object, and populates it with the values extracted from the request. See the WebSphere Integration Developer Information Center for details about the data handler interface implementation.

Listing 7. Sample implementation of transform() method
public Object transform(Object source, Class target, Object options)
   throws DataHandlerException
{
   System.out.println("Transforming incoming message");
    	
   if ((source == null) || (target == null))
      returnnull;
	
   // native data format to DataObject transformations
   if (target == DataObject.class) 
   {
     if (source instanceof InputStream) 
     {
       // TODO: Transform InputStream to DataObject
     	 InputStream inputstream = (InputStream)source;

	 byte[] bytes = readBytes(inputstream);
	 try 
	 {
	   if (bytes.length > 0)
	   {
	     System.out.println("Parsing input parameters");
	     String parms = new String(bytes, 0, bytes.length, 
             encoding);
	     System.out.println("Parameters: " + parms);
	         			
	     return createBusinessObject(parms);
	    }
	 } 
	 catch (UnsupportedEncodingException e) {
	   e.printStackTrace();
	 }
     }
     elseif (source instanceof Reader) {
       // TODO: Transform Reader to DataObject
     }
     else {
       // TODO: Transform Object to DataObject
     }
  }
	
  // DataObject to native data format transformations
  if (source instanceof DataObject) {
    if (target == InputStream.class) {
       // TODO: Transform DataObject to InputStream
    }
    else {
       // TODO: Transform DataObject to Object
    }
  }
  thrownew DataHandlerException("Transformation not supported");
 }

Method readBytes() is the private utility method that reads the input stream and stores it into the bytes array. Method includeParameter() is another utility method that implements the filtering rules defined by the configuration parameters. These rules define which parameter name is excluded from being promoted to the business object. The most important utility method in this class is createBusinessObject() (see Listing 8). It creates the business object using the namespace and name from the context, parses text content of the message and detects all the names-value pairs. Then for each pair, it invokes method includeParameters() to check if the parameter with this name needs to be mapped to the business object field. If the parameter needs to be set on the business object, then the parameter value is extracted, decoded, and set on the business object.

Listing 8. Sample implementation of createBusinessObject() method
private DataObject createBusinessObject(String s) throws DataHandlerException
{
    //First try to create a data object based on the type 
   DataObject dataobject = boFactory.create(targetNamespace, 
      localName);
   if(dataobject == null)
   {
      //If the data object is still not initialized then try to create 
      it by element. Business objects may be defined by the XSD type or  
      by XSD element. So we need to make sure that we cover both 
      scenarios.
      dataobject = boFactory.createByElement(targetNamespace, 
         localName);
   }
    	
   //Split the incoming parameters into individual tokens 
   String[] parms = s.trim().split("&");
    	
   for (int i=0; i < parms.length; i ++)
   {
      //Find next parameter name
    	String parmName = parms[i].substring(0, parms[i].indexOf("="));
    		
    	if (parms[i].indexOf(parmName) != -1)
    	{
    	   String updatedName = includeParameter(dataobject, parmName);
    	   if (updatedName != null)
    	   {
    	      //If parameter needs to be included then get the value
    		String value = parms[i].substring(parms[i].indexOf("=") + 
               1);
    		value = URLDecoder.decode(value, encoding);
		dataobject.setString(updatedName, value);
	   }
    	}
   }
   return dataobject;
}

Scenario 2 described the process of creating a custom function selector configuration. You can create a data handler configuration in the same fashion. Once the new custom data handler configuration is created, you can edit it using the Binding Configuration editor (Figure 13). The editor allows you to modify the following configuration properties supported by the class PlainTextDataHandlerProperties:

  • caseSensitive: Boolean flag to specify if the parameter name from the HTTP request must match the field on the business object ignoring case of the characters or not.
  • encoding: Text encoding.
  • exclusionList: Exclusion list that defines request properties that do not need to be mapped to the business object.
  • listSeparator: The separator character used by the exclusion list.

In our case, there are two request parameters to ignore, operation and user.

Figure 13. Custom data handler configuration
Custom data handler configuration

This data handler is designed only to process incoming plain text requests. However, the HTTP export binding component AddCustomerExportText is bound to the interface that has only one-way operations. Since there is no need to handle responses, you can set this data handler configuration as a default format handler, which will apply to all the method bindings (Figure 14).

Figure 14. Setting the default format handler
Setting the default format handler

Once the default format handler is configured, you can invoke this HTTP export binding from the HTML form to add or update the customer.


Scenario 4. Using and configuring the JSON data handler

This scenario demonstrates using the new configurable JSON data handler. This data handler is easy to use and quite flexible. In our example, the JSP, GetLocationCoordinatesJSON.jsp, generates JSON stream with random numbers as coordinates:

{"currentLatitude":"42.92777859562721",
"currentLongtitude":"-99.50927214867059"}

The JSON message needs to be transformed into the Coordinates business object (Figure 15).

Figure 15. Coordinates business object
Coordinates business object

By default, the names of the JSON object fields must match the business object field names. Note that the top level business object name is not specified in the JSON message. In our example, the names of the business object fields and the JSON response variable names do not match. To resolve the mismatch, the JSON data handler has a feature that helps in performing the mapping in these circumstances. It uses application specific metadata element serializedName stored inside the business object.

To configure business object metadata, you need to select the field (latitude or longitude) on the business object editor, and then select the Application info tab on the Properties view. Add the serializedName node to the tree and type the text value from the JSON object (currentLatitude or currentLongtitude) as shown in Figure 16.

Figure 16. Application info for the latitude field of the business object
Application info for the latitude field of the business object

Once serializedName is added to the business object, you can set the JSON data handler configuration on the HTTP import method binding as an output data format handler element to process the service JSON response (Figure 17).

Figure 17. JSON data handler configuration is set for processing the service response
JSON data handler configuration is set for processing the service response

This completes the JSON example. The HTTP import binding GetCurrentCoordinates is now configured to invoke a remote JSON service, supporting custom field mapping between the JSON message and the Coordinates business object.


Scenario 5. Handling ATOM feed data with out-of-the-box artifacts

Our previous article described how to use XML data binding and third party XML schema to enable ATOM feed support for the HTTP export binding.

Integration Developer 6.2 now provides the following artifacts:

  • Predefined set of ATOM feed business objects (XML schema)
  • Configurable data handler that transforms Atom feed business object into the Atom feed native message

This section describes how to use the provided artifacts to configure the HTTP export binding.

First, you need to add the Atom feed schema to the module Customers using the Dependencies editor. In the editor, open the Predefined resources section and select the ATOM schemas check box (Figure 18).

Figure 18. Import ATOM schemas to the module
Import ATOM schemas to the module

Save the change. The provided XML schemas for the Atom feed business objects are imported into the module. Then you need to create an interface using these business objects. Interface GetCustomersAtomFeed uses the feed business object for the output (Figure 19).

Figure 19. Interface using Atom feed business object
Interface using Atom feed business object

Then add this interface to the GetCustomersAtomFeed export component and to generate the HTTP binding. Now connect the export with the BPEL component. However, the interfaces on BPEL (GetCustomers) and the HTTP export binding component (GetCustomersAtomFeed) are different as they use different business objects for the response. Therefore, you need to implement a mediation flow component AtomFeedMappingComponent to map the interfaces and business objects (Figure 20).

Figure 20. HTTP export binding and Mediation flow components
HTTP export binding and Mediation flow components

The mediation flow component performs custom XSLT mapping for the request by storing the URL in the transient context by extracting the value for the type query parameter from the URL and setting it on the getCustomers operation input of the GetCustomers interface (Figures 21 and 22). This part of the mediation component is borrowed from the sample application described in the previous article.

Figure 21. Request mediation
Request mediation
Figure 22. XSLT map for the request mediation
XSLT map for the request mediation

Another custom XSLT map is used for response handling. The purpose of this map is to populate feed business object with the URL stored in the transient context and map each Customer business object to the entry element of the feed business object (Figures 23 to 25).

Figure 23. Response mediation
Response mediation
Figure 24. XSLT map for the response mediation
XSLT map for the response mediation
Figure 25. XSLT map for mapping individual Customer to the Atom feed entry
XSLT map for mapping individual Customer to the Atom feed entry

Once the mediation flow is complete, navigate to the Properties view of the Assembly editor when the HTTP export binding component GetCustomersAtomFeed is selected.

Select operation getFeed on the "Method bindings" panel. On the Data Serialization tab, make sure that the default Atom feed data handler configuration (UTF8AtomDataHander) is specified for the output (Figure 26).

Figure 26. Atom feed data handler specified on the HTTP export method binding
Atom feed data handler specified on the HTTP export method binding

Now the scenario is complete and you can invoke the application through the HTTP export binding GetAtomFeedCustomers from the client supporting Atom feeds using this URL:

http://localhost:9081/CustomersWeb/GetAtomFeedCustomers?type=*

Scenario 6. Configuring SSL on the HTTP import binding

This scenario describes how to configure the SCA HTTP import binding to invoke a URL using Secure Socket Layer (SSL) protocol. The SCA HTTP import binding supports configuring security settings on the binding or method binding levels. The difference is that when defined on the binding level, the security settings will apply to all the URLs configured on the selected HTTP import component. Whereas security settings defined for the individual method binding only apply to this method. So in this scenario, for simplicity, we assume that all the URLs defined by an HTTP import binding require SSL configuration.

This section does not have any sample application artifacts. It just outlines the steps to complete the configuration.

SSL requires a URL to have the https prefix. If a URL with such a prefix is specified on the HTTP import binding, but the SSL settings are not set, then Integration Developer will mark this import component with an error (Figure 27).

Figure 27. SSL error message for the HTTP import binding
SSL error message for the HTTP import binding

This indicates that you have to configure some SSL settings on the HTTP import component.

The SSL settings mentioned in the error message is found on the Security panel. You can find this panel nested within the Binding tab of the Properties view when the SCA HTTP import is selected on the Assembly editor. Navigate to the Advanced configuration tab and select the Security horizontal tab (Figure 28).

Figure 28. Binding the Security tab
Binding the Security tab

Note that the Security tab is found when the specific method is selected on the Method bindings panel (Figure 29).

Figure 29. Method binding Security tab
Method binding Security tab

On the Security panel, there is an attribute called SSL configuration name. This is the SSL settings attribute that is missing on the HTTP import binding, triggering the error message. To find the value of this attribute, start the server and open the server admin console. On the Admin console, expand the Security section and select SSL certificate and key management (Figure 30).

Figure 30. Admin console "Security" section expanded
Admin console Security section expanded

On the page that opens on the right side, select the SSL configurations link (Figure 31).

Figure 31. SSL configuration link on the main SSL page of the admin console
SSL configuration link on the main SSL page of the admin console

The SSL configurations page lists all existing server SSL configurations. At a minimum, there is the default one, NodeDefaultSSLSettings (Figure 32). Now you have a choice of either creating your own new configuration or updating the default one.

Figure 32. List of the existing SSL configurations
List of the existing SSL configurations

The name of the selected SSL configuration is the value that will be used to configure the HTTP import binding to enable SSL.

One more thing needs to be done on the server before you complete the scenario. You need to make sure that the selected SSL configuration has access to the target server certificate. To add the certificate to the default SSL configuration, navigate from the "SSL configurations" page following the path to the "Signer certificates" page (Figure 33): SSL configurations > NodeDefaultSSLSettings > Key stores and certificates > NodeDefaultTrustStore > Signer certificates.

Figure 33. List of the existing certificates
List of the existing certificates

If there is no certificate already imported for the target server, then you can add the certificate following the steps provided by the admin console. Or, use a helpful utility feature called "Retrieve from port". This function allows you to specify the host name, port, and get the target server certificate at the same time adding it to the SSL configuration (Figure 34).

Figure 34. Retrieve from port feature
Retrieve from port feature

Once the SSL configuration on the server is updated with the target server certificate, you can add the name of the selected SSL configuration to the HTTP import binding. On the Security panel of the selected HTTP import binding component, enter the value of the SSL configuration name defined on the server (Figure 35).

Figure 35. SSL configuration complete
SSL configuration complete

This concludes the task of configuring SSL for the HTTP import binding component. The HTTP import binding can now to communicate with the target server via SSL.


Application execution instructions

Note that most of the URLs used in the sample application use port 9081. This port is used by the TCP/IP monitor tool. The TCP/IP monitor must be configured and started using this port to enable the application. You can create a new instance of the monitor by using a Window > Preferences dialog. Navigate to the Run/Debug > TCP/IP Monitor entry on the left panel. Then use the Add button to create a new monitor, setting your host name and local port 9081 to be monitored. Then start the monitor instance (Figure 36). If you do not want to use the TCP/IP monitor, then you need to modify the port according to your local server settings for all the URLs used by the JSPs, HTTP import bindings, and sample URL from the article.

Figure 36. TCP IP Monitor
TCP IP Monitor

This tool is useful, allowing you to watch what is being sent on the wire by different HTTP invocations.

Once the configuration for all the scenarios is complete you can deploy and run the client JSP page in the Web browser using the following URL:

http://localhost:9081/HTTPExportToGoogleMap/SimpleListCustomers.jsp

The page displays the list of customers.

To add a new or modify existing customer, you need to copy the Customers.xml file from the CustomersLib library module to the C:\Temp directory. Otherwise, you need to open the GetCustomers Java component implementation and modify the value of the private variable xmlLocation.

Once the XML file is available at the specified location, you can use this URL to add a new customer:

http://localhost:9081/HTTPExportToGoogleMap/ProcessCustomer.jsp

Another option is to use the link from SimpleListCustomers.jsp.

If you click on the displayed customer's name, then you can update the existing customer's information using ProcessCustomer.jsp.

If you click the Add a new customer link, then you can add a new customer also using ProcessCustomer.jsp.

If you click the Map link for the selected customer, you will see the customer's home and current locations pinned to the Google map.

The required Web projects HTTPExportToGoogleMap and GenerateCustomerLocationService are always deployed automatically along with CustomersApp, as it was specified in the list of that module's dependencies (Figure 37).

Figure 37. Customer module dependencies
Customer module dependencies

Download the Project Interchange archive file, PIapplication.zip. It contains the above described application which is fully configured, ready to be deployed and run. You can import it to your workspace using the attached Project Interchange archive file, explore the application, deploy and run it on the WebSphere Process Server 6.2 test environment.


Conclusion

In this article, we demonstrated six common scenarios of the SCA HTTP bindings. Each scenario is implemented in a straight forward fashion, including the custom Java components that some scenarios require.

As a result, you have built and configured a SCA application that is capable of:

  • Handling dynamic target function selection based on the HTTP URL
  • Transforming plain text POST requests into the business objects
  • Mapping simple URL query parameters to a business object's fields
  • Processing Atom feed requests and JSON formatted responses using provided data handlers

We also demonstrated how to:

  • Create and use custom configurable data transformation components (data binding and data handler)
  • Create and use a custom configurable function selector
  • Enable SSL protocol for the HTTP import binding

The sample application demonstrated the use of the custom data binding, data handler, and function selector as a useful and powerful option that is easily re-usable and distributable.

This article highlighted the fact that you can use existing Integration Developer and Process Server tooling and runtime features, augmented by some limited customization, to easily enable HTTP bindings for some of the most common real-life scenarios.


Download

DescriptionNameSize
Code samplePIapplication.zip133KB

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=379382
ArticleTitle=Using SCA HTTP binding in typical real-life scenarios with WebSphere Integration Developer
publish-date=04012009