Sunday, April 23, 2006

Oracle BPEL: Debugging "internal" SOAP Messages

When you develop applications that use SOAP based Web Services you very often use an HTTP proxy to capture the request and response that are exchanged between the clients and servers. For this you can use the Oracle HTTP Analyzer that is part of the toolset of Oracle JDeveloper, Axis TCP Monitor, or a packaged version of it that you have with Oracle BPEL Process Manager. BPELs are making extensive usage of SOAP messages, and it could be interesting to debug the different call to the partnerlinks. Oracle BPEL PM, to avoid HTTP calls and make optimized SOAP message when the partnerlink that you are invoking is deployed as a BPEL. So in the default configuration you do not see the different calls. In this article I explain how you can configure the server to be able to do it. For this I will be using:

  • Oracle BPEL Process Manager developer install running in an OC4J 10g Stand Alone (10.1.2.0.2)
  • obtunnel, that is a package version of Axis TCP Monitor located in <BPEL_HOME>\bin\obtunnel.bat
  • LoanFlow demo that you can install in 2 steps:
    • In a shell, go to <BPEL_HOME>\samples\demos\LoanDemo
    • Run the following command to deploy the LoadFlow BPEL and associated Web Services: > ..\..\..\bin\obant

Starting the Oralce BPEL Tunneling tool:

  • Just run the command <BPEL_HOME>\bin\obtunnel.bat You will see the following application:
By default the TCPMonitor launched from BPEL listens on the port 1234 and proxies for the default Oracle BPEL port 9700. So in this context you will capture all the requests is you access the server on the port 1234. It is not sufficiant here since the different partnerlinks endpoint are not dynamique and are set to the port 9700. So in this case you wont's see the request coming from the BPEL to a local partner link (and I am not talking about the SOAP Optimization yet). One way that I use to work around this issue in development --may be we have more simple solutions, but this is the one that I use-- is to change the port of the OC4J and make the proxy listening on the port 9700. In this case you will be able to capture the requests made from BPEL to its partnerlinks.

Changing the Port of OC4J and the TCP Monitor

I. Change the HTTP port of OC4J used by BPEL
  1. Open <BPEL_HOME>\system\appserver\oc4j\j2ee\home\config\http-web-site.xml
  2. Edit the port attribute of the root element web-site to enter a different value eg: <web-site port="9701"...
  3. Stop your BPEL Process Manager
II. Start a new TCPMonitor on port 9700
  1. In the TCPMonitor sceen click on the Admin Tab
  2. Enter 9700 for the "Listen Port #" field (since we want to be sure the partnerlinks are called correctly)
  3. Enter 9701 (or the value you entered for the HTTP port) for "Target Port #".
  4. Click Add
  5. Click on the new tab "Port 9700". If you have an error message like "java.net.BindException: Address Already in use: JVM_Bind" this is simply because your BPEL process manager is not stopped. In this case stop the BPEL server, and start the TCPMonitor by clicking the Start button.
III. Restart you BPEL Server Nothing special here you just need to start your server, and check that the BPEL PM is now listening on the HTTP port that you have entered, in my case 9701:
  • http://localhost:9701/BPELConsole
You can now go on the test page of the LoanFlow process (either on the port 9700 or 9701) and invoke the process. I am using 9701 since I want to capture the calls make by the Business Process to its partnerlinks. You can see some HTTP activities in your TCPMonitor, but if you look in details you only see request to the different WSDLs used by the LoanFlow... I was like you expecting to be able to see the different SOAP requests and response, but BPEL does some optimization around local SOAP calls. So to be able to capture these requests you just need to turn of this optimization.

Turning Off the SOAP Shortcut

  1. In the BPEL console, click on the "Manage BPEL Domain" link (top right)
  2. You arrive in the configuration tab, look for the optSoapShortcut property and set it to false.
  3. Click Apply
You can now go on the test page of the LoanFlow process (either on the port 9700 or 9701) and invoke the process. I am using 9701 since I want to capture the calls make by the Business Process to its partnerlinks. Now you can see all the SOAP requests and responses between the LoanFlow BPEL and its partnerlinks.
Click to Enlarge
Update on 08/02/2007 For people that are currently using Oracle BPEL 10.1.3.1 the optSoapShortcut is not visible anymore in the console, but it is still possible to configure this by adding it manually in the domain configuration file available at: $BPEL_HOME/domains//config/domain.xml

5 comments:

Arvind Jain said...

Tug, Good posting. I had a quick question. optSoapShortcut property is not visible in the Config tab of "Manage BPEL Domain". Is this deprecated in BPEL 10.1.3 ?

Tug Grall said...

Hello Arvind,

No the "optSoapShortcut" is not deprecated; it is true that this value is not visible anymore in the console and you need to configure it manually in the domain.xml.

This file is available here:
$BPEL_HOME/domains/[domain name]/config/domain.xml

Anonymous said...

We are interested in tracing an external webservice with obtunnel. However, I am not sure how to get this to work as obtunnel seems to expect the target to be the same box. I tried the proxy setting but this did not work either. My test case was a simple BPEL flow that invoked the validate zip external webservice from xmethods.

Think you can point me in the right direction?

Thanks,

Brett

Vidya said...

I am not able to find the "optSoapShortcut" property in
BPEL_HOMe\domains\default\config\domain.xml file.

I am running Oracle BPEL Process Manager 10.1.3 on OC4J container. If there any other file I need to look up.

Thanks,
-Vidya

Tug Grall said...

Hello Vidya

If the entry is not present in the domain.xml file you just need to create it; it should work this way.

Tug