Best Kept Secret

I'm used to discovering some new feature of an Oracle product and in my enthusiasm rushing up to someone to say "did you know ..." to which their answer is invariably "everybody knows that".  So when a colleague pointed out that Oracle BPEL PM ships with a handy HTTP spy facility I expected that I was the last person on the planet to have discovered it.  However it seems that this facility is unknown even to some seasoned BPEL hackers that I know.

Obtunnel Unveiled

If you look in the "$ORACLE_HOME/integration/orabpel/bin" you will find a shell script/batch file called obtunnel.  Run this and you get a proxy that will display in a window HTTP requests and responses.

obtunnel in action (click image to enlarge)

Incredibly useful when debugging SOAP based applications because you can see the whole message, both request and response with the HTTP headers.  It can also be useful to snoop on the headers of regular HTML requests or examine the input message to an HTML servlet or jsp.

JDeveloper also ships with a utility like this, but more powerful.  However the TCP Packet Monitor requires the client to be configured to use the monitor as an HTTP proxy and not all clients support proxies.  By contrast obtunnel sits in front of a single endpoint address (hostname and port number) and so is transparent to the client and the server.  Of course if you are unsure what endpoint the client is going to call then you can't use obtunnel.

An example

I was recently doing some work for a customer who wanted to use a third party visualisation tool with Oracle's Customer Data Hub.  The visualisation tool spoke to a web service so I took the WSDL for that web service and generated a JAX-RPC web service that implemented that interface.  The client code was an old C++ application that used old Microsoft SOAP libraries and hand parsed the XML responses.  Some of the problems that obtunnel helped us to identify were

• Unquoted SOAPAction HTTP header


• Syntactic differences in XML that caused client to break


• Chunked HTTP responses

Setting it Up

Obtunnel acts as a proxy for a backend service.  When you start it up you can set the listening port number (default is 1234) and the target hostname and port number (default is local hostname and 9700 to point at BPEL PM server default installation).  On the client side you just need to change the client endpoint port number and away you go.  Great if you want to see what messages actually look like on the wire.

It keeps a log of all the requests/responses that go through it, and there is a handy setting of "most recent" that keeps the most recent response in view.

It is possible to have it sit in front of multiple servers, but each one needs a different listening port within the obtunnel instance.  It is also possible to sit in front a server that is accessed via a proxy by specifying a proxy server that will be used to forward requests to the backend server.

Alternatives

Obtunnel is not the only tool I use for this.  I also use the Microsoft SOAP toolkit trace Utility.  This doesn't give such a good view of the raw message data, the HTTP header is not displayed in its original format and so some problems can be missed.  However it does do a better job of correlating requests and responses when using HTTP 1.1.

Use It

A google search for "obtunnel" returned 7 hits, none of them relevant, so I don't feel so bad for not knowing about it a while ago.  Although it ships with BPEL Process Manager I just got a huge amount of value from it whilst debugging a JAX-RPC web service and a C++ .Net client, so it is definately not a BPEL only thing.

Share and Enjoy ;-)