BPEL Knowledge Base - Technical Note #001
TCP Tunneling
"TCP tunneling" is a generally useful technique whereby you can view the messages that are exchanged between programs/services. It is particularly useful in
the Web services/BPEL world where you may want to see the exact SOAP messages that are sent to, or received from, services with which a flow communicates.
To accomplish this, you insert a software listener in between your flow and the service. Your flow will communicate with the listener (called a "TCP Tunnel") and the listener will forward your messages to the service - as well as displaying them. Likewise, responses from the service will be returned to the tunnel which will display them and then forward them back to the flow.

To see all the messages exchanged between the BPEL Server and a Web service, you will need only a single TCP tunnel for synchronous services since all the pertinent messages are communicated in a single request/reply interaction with the service. For asynchronous services, you will need to set up 2 tunnels, one for the invocation of the service and another for the callback port of the flow.

  
 To set up a TCP listener for synchronous services that an Oracle BPEL Process
    Manager process initiates:
    

      


        a) Start your TCP listener, listening on a port like 1234 and sending
        on port

        9700 (or whatever port you installed Oracle BPEL PM to listen on - 9700
        is the

        default). You can use the TCP Tunnel included with Apache Axis which is

        bundled with BPEL PM by executing the following from a command line:
    
    
prompt> obsetenv
prompt> java -classpath %OB_CLASSPATH% orabpel.apache.axis.utils.tcpmon 1234
localhost 9700
      
   b) In the deployment descriptor for your flow (bpel.xml), add a "location"
    property to override the endpoint of the service. For example, to see the
    messages exchanged between the LoanFlow demo sample and the CreditRatingService
    that it calls, you should change the definition of the CreditRatingService
    location as shown below in the LoanFlow deployment descriptor, C:\orabpel\samples\demos\LoanDemo\LoanFlow\bpel.xml:

          
<partnerLinkBinding name="creditRatingService">
    <property name="wsdlLocation">
        http://localhost:9700/orabpel/default/CreditRatingService/CreditRatingService?wsdl
    </property>
    <property name="location">
        http://localhost:1234/orabpel/default/CreditRatingService
    </property>
</partnerLinkBinding>
    
    c) Compile and deploy the LoanDemo with the following command-line commands:

    
prompt> cd C:\orabpel\samples\demos\LoanDemo
prompt> obant
    
    d) Note that while the CreditRatingService happens to also be itself a BPEL
    process, the same technique can be used to see the SOAP messages that are
    passed to invoke a BPEL process as a Web service from another toolkit like
    Axis, .NET, etc.

    

  
  
To set up a TCP listener to display the SOAP messages for callbacks from
    asynchronous services:

    

     a) Start [another] TCP listener, listening on a port like 9710 and sending
    on port 9700.

    

    b) To see the effect of changing the callback port, you will also need to
    turn off the optimization of local SOAP calls which the BPEL PM server does.
    To do this, click the "Manage BPEL Domain" link in the upper-right
    of the BPEL Console and scroll down to the "opt-soap-shortcut" property.
    Change its value from true to false.

    

    c) Next, bring up the BPEL Admin console at http://localhost:9700/BPELAdmin
    and log in (the default admin password is: oracle). Scroll down on the initial
    Server / Config tab to the soap-server-url property. Change this to http://localhost:9710
    and click the Apply button.

    

    d) Re-start your BPEL server to pick up this change and initiate any flow
    that invokes asychronous Web services (for example the LoanFlow demo). You
    will see in your second TCP listener the callbacks from the asychronous services,
    like the UnitedLoan service callback. Of course, you can combine this with
    part 1 above to also send the UnitedLoan service initiation request through
    your first TCP Tunnel.

    
Note that if you are a JDeveloper user, you can also use the built in Packet
    Monitor in JDeveloper to see SOAP messages for both synchronous and asynchronous
    services.