Level: Intermediate Anh-Khoa Phan (anhkhoa@us.ibm.com), Software Engineer, IBM
Eric Herness (herness@us.ibm.com), WebSphere Business Integration Chief Architect, IBM
06 Jun 2006 This article offers an overview of Java usage within the Service Component Architecture's (SCA) Plain Old Java Object (POJO) component and the data flow in and out of POJO components. You will see the effects of different invocation styles when they are used within a POJO component.
Introduction
Although every step has been taken to lessen the need for users of IBM WebSphere Integration Developer to program in Java, there are times when it's necessary to use Java and POJO components.
A prime example of when you need a POJO component is when you are integrating components that only understand WSDL-described components with components that can only be exposed with Java interfaces. Additionally, data that can't be manipulated within the WebSphere Integration Developer wizards, such as anyType types, can be handled manually within the confines of a POJO component using the Service Data Object (SDO) APIs. These scenarios give meaningful use cases that demonstrate the need for POJO components.
This article provides a base-level of understanding for coding Java in POJO components with respect to invocation styles and expectations of data coming in and out. It is not intended to describe all the scenarios around SCA POJO usage.
This article assumes you are familiar with the basics of SCA, including the concepts of modules and references.
An example: hello world
To illustrate the concepts introduced here, we start by describing a simple Hello World example. Our example is a single SCA module, named HWModule, which contains two POJO components named HelloWorld and MessageLogger. MessageLogger simply prints to the console the message from HelloWorld and returns if it was successful. Figure 1 illustrates the WSDL describing the interface for MessageLogger:
Figure 1. MessageLogger WSDL interface
Figure 2 shows the WSDL describing the interface for HelloWorld:
Figure 2. HelloWorld WSDL interface
Figure 3 shows the Assembly diagram for the example:
Figure 3. HWModule Assembly diagram
 |
Note:
Usually, it's not practical to have multiple references to the same component but we have done it here for illustration purposes. |
|
HelloWorld interacts with MessageLogger using two references. One is typed by Java (j-typed) and the other is typed by WSDL (w-typed), as you can see in figure 4.
Figure 4. HelloWorld references
Figure 5 illustrates the HWMessage Business Object (BO) that is used between HelloWorld and MessageLogger:
Figure 5. HWMessage BO
Further details of this example will be discussed where appropriate within each section.
Client-side Java programming model
This article focuses on two styles of invocation: dynamic invocation interface (DII) and strongly typed. DII is a generic dynamic invocation model that always ends in an 'invoke' type of call passing in the operation name and the input parameters for that operation. Strongly typed invocation does not end in an 'invoke', but ends in a strongly typed invocation.
Strongly typed style invocation
|
Note:
"j-typed" refers to the interface of the reference is defined by Java. |
|
Strongly typed invocations can only be done on a j-typed reference. In our example, we have a reference, named MessageLoggerPartner, defined on HelloWorld that is j-typed, as you can see in Figure 6.
Figure 6. HelloWorld references
Listing 1 shows the code in HelloWorld’s sayHello() method that invokes the j-typed MessageLoggerPartner reference in a strongly typed way:
Listing 1. Sample code for HelloWorld's
sayHello() using a j-type reference with
strongly typed invocation
// j-type reference strong-typed usage
MessageLogger service = locateService_MessageLoggerPartner();
Boolean isSuc = service.logMessage(inMsg);
if (isSuc.booleanValue()) { // reuse the inMsg for our response since it's the same type
inMsg.setString("message", "Success");
} else inMsg.setString("message", "Problem consuming message sent");
inMsg.setString("sourceEmail", "service@hw.org");
return inMsg;
|
In the above code, you'll see that the method locateService_MessageLoggerPartner() is used to return a proxy to the MessageLogger. This method is generated for each reference defined by a POJO component. In our case we have two references, MessageLoggerPartner and MessageLoggerPartner1, so two methods are generated in HelloWorld, locateService_MessageLoggerPartner() and locateService_MessageLoggerPartner1().
DII (weakly typed) style invocation
|
Note:
"w-typed" refers to the interface for the reference is defined by WSDL.
|
|
Weakly typed invocations can be done irrespective of the type defined for the reference; however, if the reference is w-typed then the client needs to use DII.
J-typed reference with DII
We could have used the MessageLoggerPartner reference in a weakly typed fashion. Listing 2 shows the code in HelloWorld's sayHello() method that invokes the j-typed MessageLoggerPartner reference in a weakly typed way:
Listing 2. Sample code for HelloWorld's sayHello() using a j-type reference with DII
invocation
// j-type reference DII usage
Service service = (Service) locateService_MessageLoggerPartner();
Boolean isSuc = (Boolean) service.invoke("logMessage", inMsg);
if (isSuc.booleanValue()) { // reuse the inMsg for our response since it's the same type
inMsg.setString("message", "Success"); } else
inMsg.setString("message", "Problem consuming message sent");
inMsg.setString("sourceEmail", "service@hw.org");
return inMsg;
|
Everything is similar to the strongly typed invocation, except the operation name passes into an 'invoke' call along with the input parameter.
W-typed reference with DII
If the reference is w-typed then the only invocation style available to the user is DII. In our example, we have defined another reference in addition to the j-typed reference – MessageLoggerPartner -- that is w-typed named MessageLoggerPartner1, as shown in figure 7.
Figure 7. HelloWorld references
Listing 3 shows the code in HelloWorld's sayHello() method to use this the w-typed HWMessageLoggerPartner1 reference in a DII way:
Listing 3. Sample code for Hello World's sayHello() using a w-type reference with DII
invocation
// w-type reference DII usage
Service service = (Service) locateService_MessageLoggerPartner1();
BOFactory bof
(BOFactory) new ServiceManager().locateService("com/ibm/websphere/bo/BOFactory");
DataObject inputWrapper =
bof.createByType(service.getReference().getOperationType("logMessage").getInputType());
inputWrapper.setDataObject("inMsg", inMsg);
DataObject outputWrapper = (DataObject) service.invoke("logMessage", inputWrapper);
boolean isSuc = outputWrapper.getBoolean("isSuccessful");
if (isSuc) { // reuse the inMsg for our response since it's the same type
inMsg.setString("message", "Success");
} else inMsg.setString("message", "Problem consuming message sent");
inMsg.setString("sourceEmail", "service@hw.org");
return inMsg;
|
This scenario is much more interesting, as you can tell from the code snippet in Listing 3. The interesting part is the input types that are sent in/out of the invocation.
|
Note:
Doc-literal wrapped (DLW) is the default pattern for WSDLs generated in WebSphere® Integration Developer.
|
|
In this last scenario we're using DataObjects -- inputWrapper and outputWrapper -- that correspond to the "wrapper" elements in a doc-literal wrapped (DLW) WSDL.
So, to understand what types to send -- strongly or weakly -- you'll need two tidbits of information. First you'll need to know style of WSDL -- DLW or any other -- and then you'll need the reference type, j-type or w-type.
Table 1. Input/Ouput type decision matrix
| Reference of j-type | Reference of w-type (DLW) | Reference of w-type (any other) |
|---|
| Weakly typed (DII) |
Java primitives for simple types; DataObject for
complex types
|
Wrapper elements specified for message in WSDL,
which encapsulates the payload object:
HWMessage or Boolean, and the like. The message element
is always a DataObject.
|
The type specified for the payload –
there's no wrapper thought here. If the
payload is of complex type then it's a
DataObject, and if it's a simple type then
it's Java primitive.
| | Strongly typed |
Java primitives for simple types; DataObject for
complex types
|
Wrapper elements specified for message in WSDL,
which encapsulates the payload object, HWMessage or Boolean, and the like.
The message element is always a DataObject.
|
The type specified for the payload –
there's no wrapper thought here. If the
payload is of complex type then it's a
DataObject, and if it's a simple type then
it's Java primitive.
|
Common problems
Since there can be multiple ways to invoke any given reference one can hit several known problems. The common ones will be presented here.
ClassCastException problems
This common error message indicates that the data being received or sent is not what is expected. For example, if the user does not understand that wrappers are needed for some scenarios then this will be sent on the return object cast. The remedy is to change the code to cast correctly to the right object.
IllegalArgumentException: Class 'x' does
not have a feature named 'y' problems
This error message also indicates that the data being received or sent is not what is expected, but instead of happening on the cast it occurs later when data is being accessed. For example, a user receiving a DataObject may think that it is not a wrapper DataObject and try to access the data attributes directly. Accessing it directly will cause an error. The remedy is to change the code to access the correct attributes.
Conclusion
This brief article offers a basic overview of selecting strong or weak invocation styles within a POJO component, and the common potential pitfalls of ClassCastException and IllegalArgumentException.
Download | Description | Name | Size | Download method |
|---|
| Hello World sample project interchange | ws-soa-sca-java-inv-pi.zip | 13KB | HTTP |
|---|
Resources
About the authors | | | Anh-Khoa Phan is a software engineer at IBM, in the Rochester Development lab. He currently works on WebSphere Business Integration. |
| | | Eric Herness is the chief architect for Websphere Business Integration IBM's Rochester Development lab. He is senior member of the WebSphere Foundation Architecture Board and a core member of the Software Group Architecture Board. Eric has been involved product architecture and product development in object technology and distributed computing for over 15 years. |
Rate this page
| 
