Thursday, July 31, 2014

Error Messages using the WEF JAXB Plugin

I just resolved an issue related to my plugin for WEF which generates JAXB code for easy conversion to/from IXML and I thought I'd write it up before I forget.

The error message looks something like this:

java.lang.ClassCastException: javax.xml.bind.JAXBElement incompatible with com.dsixe.jaxbgen....

This seems to be caused by a variance in the schema generated by the SQL Call builder where the topmost wrapper element is not annotated as root element by JAXB. The problem is solved by using code which looks like this:


javax.xml.bind.JAXBElement jaxbElement = (javax.xml.bind.JAXBElement)Transform.convertToObject(available, "http://com/dsixe/Roles", com.dsixe.jaxbgen.rolesTransformSchema.RowSetType.class);

com.dsixe.jaxbgen.rolesTransformSchema.RowSetType iAvailable = (com.dsixe.jaxbgen.rolesTransformSchema.RowSetType) jaxbElement.getValue(); 
We need to initially cast to JAXBElement and then use getValue() to retrieve the object. One more line of code fixes the problem.

Friday, April 18, 2014

Defaulting WEF Builder Input Groups as Expanded

A little used WEF feature is the comments builder input which appears on all builder editors. The input always displays at the very top under the collapsed group header "Properties" along with the builder enable/disable input. The primary reason it is little used is because the "Properties" group is collapsed by default and therefore not immediately visible. This can be easily changed through these steps:

1) Extract the Base.bdef file from \WebContent\WEB-INF\builders\corebuilders.zip
2) Copy the file to \WebContent\WEB-INF\builders\com\bowstreet\core
3) Edit the highlighted element from true to false



Restart your eclipse workspace and the comments builder input should now be visible by default.


Remember to restart this process when you upgrade to a new version of WEF since this effectively overrides the designer's defaults.

Tuesday, March 4, 2014

REST vs SOAP

For some reason people who work in technology seem to have well defined opinions about matters and will often go to great lengths to defend those opinions. Think about the unix vi editor (I dislike), windows vs unix, windows vs apple. These topics will often lead to flame wars. Today I'm going to weigh in on web service transports and hope I don't light up a wildfire.

Early Binding vs Late Binding

I'm a supporter of the SOAP protocol for most cases unless the service is to be consumed by a javascript application. I've been thinking about why it is that I have this preference and I think I know exactly why. It comes down to early (or design time) binding of an external component vs late (or runtime) binding. This concept has been around since the early days of computer science, the idea being that a sub component can declare ahead of time what kind of operation signatures it supports so that these can be confirmed by the compiler. If a piece of code which has been bound at compile time fails at run time then we immediately know there is a conflict in versions. A similar concept is found in strongly typed languages. I can think of a few examples of this:
  • java interfaces
  • C/C++ header files
  • WSDL - web service definition language
The bad part of using SOAP is that it requires additional overhead, but in simple cases this is little more that a message envelope.

The other side of the argument is run time binding where we find out about the operation signatures when the code is actually executed. Now this isn't as bad as one thinks because the component owner will always provide details about the shape of the data and what is expected so the consumer that write appropriate code. The bad part of this is that the service provider can change anything at any time without notifying the consumers, resulting in an error when the consumer attempts to invoke an operation. There is a similar concept in weakly typed languages:
  • javascript
  • visual basic
  • assembly language

How to Choose?

The short answer is that this whole argument is moot if the software is well designed and written. All the valuable business logic should reside in java bean POJOs and then combined with a runtime container such as an enterprise service bus (ESB) or a service component architecture (SCA). The container manages exposing the POJO business logic using any number of transport protocols and can be configured at time of deployment. If an ESB or SCA is not available, then a similar result can be attained by coding a thin delegate using JAX-RS or JAX-WS.

Why do I prefer early binding? I don't like doing emergency production troubleshooting and with early binding I can eliminate one more point of failure.

Tuesday, January 21, 2014

Transform IXml with JAXB


This posting simply redirects to an article I've added to IBM's community.

http://www-10.lotus.com/ldd/pfwiki.nsf/dx/Transform_IXml_with_JAXB

Saturday, November 2, 2013

Building Reusable Web Services

I've worked on many projects for various organizations, both large and small, during my career in IT, and it's sad to say that reusability of web services is something that is very difficult to attain. We all learn about good design and coding practices, and agree that reusability is cornerstone to building great applications, so why do so many organizations get it wrong?

Qualities of a Good Web Service

Let's start by identifying what can be considered to be traits of a good web service
  • encapsulation of knowledge
  • fine and coarse grained operations
  • self documenting
  • application agnostic
  • ease of use
There are other traits such as security, but these are more technical aspects that are well described through the WS-* specifications. Most concepts are easier explained through an example, and in the context of this article I'll use an automobile's construction process as a guide. If we consider a web service that provides operations to assemble a car, what would that service look like?

Fine and Coarse Grained Operations

Every good developer understands the advantage of breaking up their code into reusable parts that can be invoked from different sources. Somehow this approach never translates itself into web services. It seems that developers are so focused on reaching the next milestone that they don't take the time to ask a very basic question.

Can this operation be broken up into useful parts?

Agile methodology involves delivering functionality with short development cycles, and this makes it easy to forget about the larger context. Developers may be focused on writing a service operation to deliver a car's door, that they don't think how a door is composed of many pieces. What happens if in the next development cycle there's a need for an operation to deliver a door mirror or a window control switch (these are parts of a car's door)? Instead of writing a coarse grained operation that looks like this:

CarDoor getCarDoor(){
}

it can be broken up into several fine grained operations

DoorMirror getMirror(){
}

DoorSwitch[] getSwitches(){
}

CarDoor getCarDoor(){
   CarDoor = getMirror() + getSwitches();
}


With little additional work, the service is now much more useful and can handle future requests that may not have been anticipated.

 

Encapsulation of Knowledge

A big reason organizations decide to develop web services is not only to expose back end systems, but also to encapsulate/hide the complexity of those systems. Software applications have a way of far outliving their original lifespan due to embedded business logic or the cost of rewriting them. A web service can be written that leaks the internal workings of the system it is exposing.

This is bad. How do these leaks happen?

Let's take the car example which is manufactured by the fictitious Acme car company. As is the case for most industries, Acme uses an internal vocabulary to describe parts of their cars (I'm making these up):
  • windows are called "clear silica substrate" (or CSS)
  • door switches are called by their product codes such as D39's
Everybody working at Acme knows what that a car door has two D39's and a CSS, but these terms should not be exposed in a service operation. What's more, if the manufacturer of the D39's goes out of business (or the underlying software system is replaced) any references to these terms suddenly don't make sense. Instead of exposing this object:

CarDoor {
    CSS cssItemNumber;
    D39[] switches;
}

use something that is agnostic of the underlying system but supports the business objects:

CarDoor{
    Window windowID;
    Switch[] doorSwitchID; 
}

This approach makes the operations easy to understand, and cuts down on the need to document.


Self Documenting

The bane of all software development is documentation. Nobody likes to do it, and when done, it gets misplaced or quickly falls out of date with the implementation. I can write about how developers need to get their act together, but the truth is that it just doesn't happen that way. They can be coaxed into writing a few lines to describe their functions but formal documentation is not realistic. An alternative way to handle this situation is to write a service interface that uses business terms instead of technical ones and exposes explicit, fine grained operations. The following is an example of a poor interface to handle seats in a car:

handleSeat(String operation, Seat newSeat, Seat oldSeat, String seatID){
    if operation = "add" then ....
    if operation = "remove" then ...
    if operation = "replace" then ...
}

The above operation requires documentation that describes the options for "add", "remove" and "replace". It is impossible that a consumer of the service will be able to guess the values without referring to some documentation (which is probably non existent or out of date). What's more is that because the operation requires a "Seat" object for "add", the consumer also needs to pass one for "remove", even though it is not necessary for that particular operation. A better interface looks like this:

addSeat(Seat seat){
}

removeSeat(String seatID){
}

replaceSeat(Seat newSeat, Seat oldSeat){
}

Again, just a little more effort makes the service infinitely more usable. A business subject matter expert (SME) should be able to understand the interface.

Application Agnostic

In summary, don't create services for a specific application, instead code generic operations that can be used by any application. Acme needs a service that supplies wheels for it's latest model, the XJ2000. The immediate thought is to create operation like so:

Wheel[] getXJ200Wheels(){
}

Six months later management decides that the web service has worked out so well, they want to leverage their investment to provide wheels for an older model, the FRT3000. The FRT3000 is a sport model which has two kinds of wheels, 18 inch alloys as well as 16 inch standard. Unfortunately the existing operation cannot be reused because it doesn't take into consideration that wheels come in different sizes and will have to be rewritten.

Operations should reflect the business knowledge domain (in this case, the auto industry), not the application's.

 

 Ease of Use

Here's a common scenario that unfolds when a developer begins to work on a new feature. They look at a document from the design team and are made aware of some existing service operations that should be leveraged to accelerate their work. They pull up the service with a testing tool and attempt to make use of it. If
  • they can't find the WSDL document 
  • the service is not well documented
  • they can't find the correct parameters to invoke the service operations
  • the operations are too difficult to understand or are perceived to be inadequate
  • they have an alternative way to get their work completed
they won't use it and will write their own code. The developer is on a tight deadline to deliver and will avoid something that's difficult to use.

So what's the answer?

A simple guiding principal I try to follow is this - write the service as if it was exposed to the real world instead of some internal team. Would Bob at Universal Motor Co understand my service? The great appeal of a service oriented architecture (SOA) is writing once and reusing throughout the organization, unfortunately the investment doesn't pay off it it is not done right.


Thursday, August 8, 2013

Logging SOAP Requests in WEF

Some of my projects make extensive use of the web service call builder and I often need to look at the outgoing SOAP requests when a problem crops up. This is easy by turning on logging in the advanced section of the builder, but doing this on every instance of the builder is tedious.


JAX-WS SOAP Handler
I stumbled on this article where Rob Flynn describes a technique to handle SOAP requests from a central point using the bowstreet.serviceCall.jaxwsHandler override. I used this approach to add some log4j logging statements, this way I don't have to go into each builder and tweak the input and redeploy, I can just change the log4j.properties. Unbelievably, a google search shows that there are no other references to this override - not even in IBM's documentation. I have to wonder how many other awesome WEF features lay undocumented (ask me about pageprocessors.properties).

public class SoapHandler extends BaseJaxWsHandler {

    static Logger logger = Logger.getLogger(SoapHandler.class);
    
    /* 
     * Populate the user's identity into the SOAP request.
     */
    public boolean handleOutboundMessage(SOAPMessageContext context) {
        // bail if logging not enabled  
        if (!logger.isInfoEnabled())
            return;
         logMessage(context);
        
        return true;
    }
    
    
    /**
     * Log the SOAP message.
     * @param context
     */
    private void logMessage(SOAPMessageContext context) {

        // bail if logging not enabled  
        if (!logger.isInfoEnabled())
            return;
        
        try {
            HashMap hm = (HashMap) context.get(com.ibm.websphere.webservices.Constants.REQUEST_TRANSPORT_PROPERTIES);
            Set keys = hm.keySet();
            
            logger.info(">> Start SOAP message log");
            logger.info("calling Model=" + getWebappAccess().getModelName());
            logger.info(this.getEndPointUrl(context));

            for (Object key : keys){
                logger.info("HTTP header -> " + key + "=" + hm.get(key));
            }
            
            logger.info(context.getMessage().getSOAPPart().getEnvelope());
            logger.info(">> End SOAP message log\n");
        } catch (SOAPException e) {
            // we're just logging, not sure we care that an exception is thrown
        }
    }


}

The parent class BaseJaxWsHandler can be found on Rob's entry mentioned above.

Friday, May 31, 2013

Product Codes for IBM Software

In many past instances I've been really confused by the download process for IBM Passport. Searching for the correct download package is like trying to find a needle in a haystack.

This week I stumbled on a page I had been looking for, here is a link to the product codes for WebSphere Portal 8:

http://www-10.lotus.com/ldd/portalwiki.nsf/xpDocViewer.xsp?lookupName=IBM WebSphere Portal 8 Product Documentation#action=openDocument&res_title=Electronic_images_wp8&content=pdcontent