Hema Sagar Reddy Kandati's Weblog: April 2010

Tuesday, April 27, 2010

Invoke Business Object Maps Using WebSphere Business Integration API

Summary:
Use “com.ibm.wbiserver.map.MapService” interface to invoke Business Object Maps from your Java Classes.

Using the MapService interface is pretty straight forward.

Use com.ibm.websphere.sca.ServiceManager class to lookup the MapService.
Use appropriate methods on the MapService to invoke the Business Object Maps.

Let’s see a small example of how this is done. I have created a sample interface with one operation, an input BO (Business Object) (FromBO) and an Output BO (ToBO). I have also created a business object map to map from FromBO to ToBO. The picture below shows the details.

In the code sample below, the input to the operation is an instance of FromBO. We create an instance of ToBO and use the ‘simpleTranformation’ method on the MapService to invoke the ‘FromBO_ToBO_Map’ business object map.

public DataObject mapInputtoOutput(DataObject input1) {
//create an instance of the output data object.
BOFactory boFactory = (BOFactory)ServiceManager.INSTANCE.
locateService("com/ibm/websphere/bo/BOFactory");
  DataObject output1 = boFactory.create("http://SampleLib/com/test/bo", "ToBO");
  //locate the map service
MapService serviceOne = (MapService)ServiceManager.INSTANCE.
locateService("com/ibm/wbiserver/map/MapService");
// invoke the business object map to do the transformation.
try {
  serviceOne.simpleTransform("http://SampleLib/com/test/maps",
"FromBO_ToBO_Map",input1, output1);
} catch (WBIMapServiceException e) {
// TODO Auto-generated catch block
e.printStackTrace();
  } catch (WBIMapNotFoundException e) {
// TODO Auto-generated catch block
  e.printStackTrace();
} catch (WBIMapFailureException e) {
// TODO Auto-generated catch block
  e.printStackTrace();
  }
return output1;
}

You can also use ‘transform’ method on the MapService interface if you would like to invoke business object maps that deal with transformations from multiple BOs to multiple BOs

Please check Must-Have bookmarks for IBM WebSphere Integration Developers for WAS API and other useful references.

Wednesday, April 21, 2010

WebsiteBaker: Customizing Multiflex-5 theme to add new blocks

Summary:
Customize Multiflex-5 to add new blocks, display icons and add content.

Recently, I was looking for website themes for my personal website, to use with websitebaker and found Multiflex-5 which I really liked for its features and its simple looks.

You will get all the info that you need to customize your template @ Multiflex:5.0. All you need to do is to find something that you like on the above site, right click on the webpage and select “View Page Source / View Source”. You basically browse down to the section that you are looking for, and use that in your template.

I wanted to add a new block and add content to it as shown in the picture below

Thought it might be useful for others who want to do the same, if I post this information. So, here you go!

In-order to add new menus or new blocks, you need to modify “info.php” under <installation dir>/templates/Multiflex-5/

The default template comes with two blocks named “News” and “Sidebar”. If you want an additional block or want to change the name of the existing blocks, “info.php” is the place to do it.

Once you have added a new block to “info.php”, it will be reflected in your (websitebaker) admin screen (Manage sections of a page) as shown below.

Note that “MyBlock” was added to info and it shows up in the drop down box in the Manage Sections page.

To add content to a block:

Add a section to your page and place it under one of the block names in the drop down box.
Modify “index.php” under <installation dir>/templates/Multiflex-5/, to pull the content into that block. The picture below shows a sample of how the “index.php” was modified to show the blocks.

Add Block - index.php

Additionally you can use different classes with your headings to display cool icons as shown below.

NOTE: When you modify the template "index.php" to display the content of the blocks, this will be done on all pages. If you do not add sections to other pages to provide content, empty blocks will be displayed.

References:

[1] WebsiteBaker-Designer Guide

[2] Multiflex-5.0

Friday, April 16, 2010

Web Services: A HOWTO on SOAP headers using JAX-RPC and JAX-WS

Summary:

This article tries to address the following questions

How to define SOAP headers in a WSDL?
How to deal with SOAP headers when following the top-down and bottom-up development approaches?
How to make the SOAP headers available to the implementation when the headers are defined using explicit or implicit styles using a top-down or a bottom-up approach?

Development Environment: WebSphere Integration Developer (WID) 6.2

Defining SOAP headers in WSDL (Implicit and Explicit Styles):

“An implicit SOAP header is a SOAP header that fits one of the following descriptions:

A message part that is declared as a SOAP header in the binding in the Web Services Description Language (WSDL) file, but the message definition is not referenced by a portType element within a WSDL file.
An element that is not contained in the WSDL file.” – [4]

The author of the wonderful article named “Implement implicit and explicit SOAP headers” has described both styles in great detail.

Two cases when using SOAP headers:

The data in the SOAP header is either used or populated in the implementation of the operation.
The data in the SOAP header is neither used nor populated in the implementation of the operation.

In particular, the rest of this article focuses on case 1 with both Implicit and Explicit styles.

Development Approach (Top-Down and Bottom-Up):

In a Top-Down development approach of a web service, the WSDL is first defined from which the java artifacts that are necessary to implement the service are generated.

For a top-down approach, you could use

WSDL2Java command in case of JAX-RPC
wsimport command in case of JAX-WS

In a Bottom-Up approach of a web service, the WSDL is generated from the java artifacts that are associated with the implementation of a particular service.

For a bottom-up approach, you could use

Java2WSDL command in case of JAX-RPC
wsgen command in case of JAX-WS

Combining the two options of the development approach with the two options of SOAP header definition styles, we end up with 4 combinations.

Top-Down – Explicit
Top-Down – Implicit
Bottom-Up – Explicit
Bottom-Up – Implicit

JAX-RPC

Top-Down – Explicit

If you have defined your SOAP header using the explicit style in the WSDL, JAX-RPC maps the explicit headers to the Service Endpoint Interface (SEI) of the web service. Both request and response headers if any will be available for the implementation code.

With an explicit header definition style, after the java artifacts are generated, the SEI looks like the following for one operation named “returnInput” that has both request and response headers defined

public interface TestTopDownHeaders extends java.rmi.Remote {

public void returnInput(com.test.TestInput parameters, com.test.BaseRequest_Type

request_header, com.test.holders.TestOutputHolder parameters2,

com.test.holders.BaseResponse_TypeHolder response_header) throws

java.rmi.RemoteException;

}

Note that the headers are passed in as parameters.

Top-Down – Implicit

JAX-RPC does not provide any mapping for the implicit header definitions.

One could use JAX-RPC handlers to access the headers for cases where the implementation of the service does not deal with the header information.

For cases where the SOAP header is either used or populated in the implementation of the operation, you could use one of the two options

Use the ServiceLifecycle interface as described in [2] in the references section.
Use JAX-RPC handler and use ThreadLocal class to store/retrieve the header information. On the Server side, when the request comes in, the handler basically populates the values in the request header that the implementation needs on the thread-local variable. The information stored is available to the operation implementation. For the response headers, the operation implementation can pass the information along to the handler in a similar fashion. This is not an elegant approach but sure works!

Bottom-Up – Explicit

For the Bottom-Up – Explicit header approach, a lot of manual changes need to be made. This is particularly for cases where the operation implementation needs to have access to SOAP headers.

Here is what I have done.

Create holder classes
Modify the SEI to pass headers as parameters mimicking the generated classes in the top-down approach.
Generate the WSDL
Modify the WSDL
Modify the mapping xml

Seems to work fine, but I would not recommend this approach since there is a lot of manual work involved.

Bottom-Up – Implicit

Some amount of manual changes to the WSDL is required (adding the SOAP header to the bindings sections). Also, in-order to generate the mappings for the header objects, they will have to be added to the interface and then removed at a later point, not to mention the changes to the mappings xml file.

One of the two approaches described in Top-Down – Implicit can be used to make the SOAP header information available to the implementation of the operation.

JAX-WS (2.1)

Using annotations in JAX-WS, you can mark a parameter as a header.

Eg:

@WebParam(name = "RequestHeader", targetNamespace = "http://www.test.com", header = true, partName = "request_header")

If you are looking for JAX-WS annotations reference, please use [5] in the references section.

Top-Down – Explicit

JAX-WS supports explicit headers and provides the header objects as parameters to the operation. It generates the annotations, marking the SOAP header parameters as headers.

Top-Down – Implicit

JAX-WS has no support for implicit headers but after generating the java artifacts. For cases where the implementation deals with the headers

Simply add header parameters with annotations to the interface/implementation classes and the mapping is taken care of. Don’t forget to use the Holder class for OUT and IN/OUT parameters.
The other approach would be to use JAX-WS handlers and MessageContext object to make the headers accessible to the implementation. Please refer [3] to see how you can work with JAX-WS handlers to do the same.

Bottom-Up – Explicit

JAX-WS supports explicit headers even in the bottom-up approach. Add the annotations marking the header parameters as headers.

E.g.:

@WebService(name = "TestBottomupHeaders", targetNamespace = "http://www.test.com")

@SOAPBinding(parameterStyle = SOAPBinding.ParameterStyle.BARE)

public interface TestBottomupHeadersIntf extends java.rmi.Remote{

@WebMethod(action = "returnInput")

public void returnInput(

@WebParam(name = "TestInput", targetNamespace =

"http://www.test.com", partName = "input") TestInput input,

@WebParam(name = "BaseRequest", targetNamespace = "http://www.test.com",

header = true, partName = "request_header") BaseRequest_Type requestHeader,

@WebParam(name = "TestOutput", targetNamespace = "http://www.test.com", mode

= WebParam.Mode.OUT, partName = "output") Holder<TestOutput> output,

@WebParam(name = "BaseResponse", targetNamespace = "http://www.test.com",

header = true, mode = WebParam.Mode.OUT, partName = "response_header")

Holder<BaseResponse_Type> responseHeader);

}

NOTE: For OUT and IN/OUT parameters, you must use the Holder class as shown above.

Bottom-Up – Implicit

Two approaches here:

Define the POJO interface passing the headers as parameters and with annotations marking header=”true” where appropriate
Generate the WSDL
Change the WSDL manually to have implicit headers definitions rather than explicit.

2. Use JAX-WS handlers to make the headers available to the implementation. Please refer [3] to see how you can work with JAX-WS handlers and MessageContext to do the same.

References:

[1]        Implement implicit and explicit SOAP headers

[2]        Web services programming tips and tricks: Using SOAP headers with JAX-RPC

[3]        Get a handle on the JAX-WS API's handler framework

[4]        IBM WebSphere Application V 7.0 Information Center

[5]        JAX-WS annotations reference