Troubleshooting SOAP requests and responses

ColdFusion MX provides the following facilities for troubleshooting SOAP requests and responses:

The getSOAPRequest and getSOAPResponse functions.
The TCP monitor.

This section describes the following topics:

Viewing SOAP requests and responses

You can use the getSOAPRequest and getSOAPResponse functions to retrieve and display the XML passed to and from a web service. Although advanced users may use this information for custom functionality, you typically use these functions for debugging.

Use these functions in the following places:

GetSOAPRequest Clients call this function after the web service request; web service CFCs call this function in the web service CFC method.
GetSOAPResponse Clients call this function after the web service request completes; web service CFCs cannot use this method.

The following example uses the GetSOAPRequest and GetSOAPResponse functions in a web service client:

<cfscript>
 ws = CreateObject("webservice", "http://localhost:8500/soapexamples/tester.cfc?WSDL");
 addSOAPRequestHeader(ws, "http://mynamespace/", "username", "randy");
 ret = ws.echo_me("value");
</cfscript>

<cfset soapreq = GetSOAPRequest(ws)> 
<h2>SOAP Request</h2>
<cfdump var="#soapreq#">

<cfset soapresp = GetSOAPResponse(ws)>
<h2>SOAP Response</h2>
<cfdump var="#soapresp#">
...

The following example uses the GetSOAPRequest function in a web service CFC method:

<cfcomponent displayName="testerdebug" hint="Test for underscores">

<cffunction access="remote" name="echo_me" output="false" returntype="string" 
  displayname="Echo Test" hint="Header test">
  <cfargument name="in_here" required="true" type="string">
  <cfset var soapreq = "">

  <cfif IsSOAPRequest()>
    <cfset soapreq = GetSOAPRequest()>
   <cflog text="#soapreq#"
           log="APPLICATION"
           type="Information"> 
...

Using the TCP monitor

TCPMonitor is a swing-based application that lets you watch the request and response flow of HTTP traffic. You can also watch the request and response flow of SOAP traffic. TCPMonitor replaces the Sniffer service formerly used in Macromedia JRun.

To run TCPMonitor:

On Windows and Unix platforms, you can execute the TCPMonitor by launching the sniffer utility in the jrun_root/bin directory.
The TCP Monitor main window appears.

TCPMonitor is a swing-based application that lets you watch the request and response flow of HTTP traffic. However, you can also use it to watch the request and response flow of SOAP traffic.

To run TCPMonitor:

On Windows and Unix platforms, you can execute the TCPMonitor by launching the sniffer utility in the cf_root/bin (server configuration) or jrun_root/bin (multiserver configuration) directory.
The TCP Monitor main window appears.

Note: In the J2EE configuration, run the utility directly out of the JAR file by using the following command:
```
java -cp cf_webapp_root/WEB-INF/cfusion/lib/axis.jar java 
org.apache.axis.utils.tcpmon [listening_port] [target_host] [target_port]
```

Enter the values in the main window as described in the following table:

Field	Description
Listen Port#	Enter a local port number, such as 8123, to monitor for incoming connections. Instead of requesting the usual port on which your server runs, you request this port. TCPMonitor intercepts the request and forwards it to the Target Port.
Listener	Select Listener to use TCPMonitor as a sniffer service in JRun.
Proxy	Select Proxy to enable proxy support for TCPMonitor.
Target Hostname	Enter the target host to which incoming connections are forwarded. For example, if you are monitoring a service running on a local server, the hostname is localhost.
Target Port#	Enter the port number on the target machine to which TCPMonitor connects. For example, if you are monitoring a service running on your local ColdFusion server in the server configuration, the default port number is 8500.
HTTP Proxy Support	Select this check box only to configure proxy support for TCPMonitor.

You can optionally specify the Listen Port#, Target Hostname and Target Port# values when invoking TCPMonitor on the command line. The following is the syntax for TCPMonitor:

java org.apache.axis.utils.tcpmon [listening_port] [target_host] 
[target_port]

To add this profile to your TCPMonitor session, click Add.
A tab appears for your new tunneled connection.
Select the new tab. If there are port conflicts, TCPMonitor alerts you in the Request panel.
Request a page using the Listen Port defined in this TCPMonitor session. For example, if you entered 8123 for the Listen Port, enter the following URL in your browser:
```
http://localhost:8123/
```
TCPMonitor displays the current request and response information:

For each connection, the request appears in the Request panel and the response appears in the Response panel. TCPMonitor keeps a log of all request-response pairs and lets you view any particular pair by selecting an entry in the top panel.
To save results to a file for later viewing, click Save. To clear the top panel of older requests that you do not want to save, click Remove Selected and Remove All.
To resend the request that you are currently viewing and view a new response, click Resend. You can edit the request in the Request panel before resending, and test the effects of different requests.
To change the ports, click Stop, change the port numbers, and click Start.
To add another listener, click the Admin tab and enter the values as described previously.
To end this TCPMonitor session, click Close.

View comments in LiveDocs