Revision History
Revision 1.0 10.04.2013 Admin TCPMon Tutorial
Revision 1.1 10.05.2013 Admin Add Tips, bug fixes and enhancements

When developing web services applications, it’s often on demand to be able to track the SOAP messages passed along in TCP based conversation, the TCPMon comes as the first option to capture the outgoing and incoming SOAP envelopes.

1. TCPMon Introduction

TCPMon is a open source utility debug tool, distributed under the Apache 2.0 license. It has originally being part of Axis1 and now stands as an independent project. The official web site is http://ws.apache.org/tcpmon/. It is based on a swing UI and works on almost all platforms that Java supports. It allows user record, monitor and resent the messages, This TCPMon tutorial is step-by-step guide to explain how TCPMon works and also to explain its features.

(There’s a same name TCPMon project in a Google Code, but that’s not the same one, and it only has less features).

2. Prerequisite

TCPMon was written by standard Java language,  it has absolutely no dependencies on third party libraries. to run TCPMon, only the JDK or JRE is required.

3. Download and Start TCPMon

Visit http://ws.apache.org/commons/tcpmon/download.cgi to download the 1.0 Source or binary distribution. Unzip the tcpmon-1.0-bin.zip(this latest 1.0 version was released on 27 – 03 – 2006), then navigate to the folder where you unzipped the download, there have two ways to start  TCPMon:

  • Double click the bat file tcpmon.bat
  • Open a terminal window and Change directory (cd) to the build folder, type: java -cp ./tcpmon-1.0.jar org.apache.ws.commons.tcpmon.TCPMon
org.apache.ws.commons.tcpmon.TCPMon is the main GUI class of the TCPMon. If you want to read TCPMon code, it’s where you can start with.

Once it is launched, you should see the below TCPMon UI interface.

tcpmon UI

4. Configure Admin TCPMon

The TCPMon usage pattern is as an intermediary. It is called explicit since the client has to point to the intermediary rather than the original endpoint in order to monitor the messages. TCPMon enables kinds of listing/proxy bridge between server and client, while client sends the soap message, it is made to connect to tcpmon, and tcpmon forwards the data/SOAP message to the real server along-with displaying it in its GUI. The following figure explains this concept.

concept
Click on Admin tab to configure the TCPMon. Thinking that we want retrieve the all cities in a country from http://www.webservicex.net. The webservice is already up and available on the port 80.

Steps (Please see the following screen shot)

  1. Set Listen Port # as 8080 (Assuming that port 8080 is free on your system)
  2. Set Target Hostname as www.webservicex.net
  3. Set Target Port # as 80
  4. Click add button to start listening

Admin config for TCPMon

We have instructed tcpmon to listen on port 8080 and forward any requests being received to www.webservicex.net. In the web service request, we should set the URL as localhost:8080. This will cause any requests to go through the tcpmon proxy, to capture the SOAP request and then forward to the target hostname value. The response from the web service will also be captured by tcpmon and then forwarded on to our application.

Note that the client needs to connect to the machine where tcpmon is running on the “Local Port”, not directly to the server.

4. Send a web service SOAP request

Once we finished the client program and send the soap request, the TCPMon will record the incoming and outgoing SOAP envelopes and lists on the below UI.
tcpmon_result

As displaying on the UI, the additional feature are that we can view the content in XML format, resend the request, switch layout and so on.

The following XML is the SOAP request we retrieve all cities in india.

SOAP Reqeust
POST /globalweather.asmx HTTP/1.1
SOAPAction: "http://www.webserviceX.NET/GetCitiesByCountry"
Content-Type: text/xml
User-Agent: Axis/2.0
Host: www.webservicex.net:8080
Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
Connection: keep-alive
Content-Length: 379<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<GetCitiesByCountry xmlns="http://www.webserviceX.NET">
<CountryName>India</CountryName>
</GetCitiesByCountry>
</soap:Body>
</soap:Envelope>

The following XML are the SOAP response from this web service server.

SOAP Response
HTTP/1.1 200 OK
Cache-Control: private, max-age=0
Content-Length: 8038
Content-Type: text/xml; charset=utf-8
Server: Microsoft-IIS/7.0
X-AspNet-Version: 4.0.30319
X-Powered-By: ASP.NET
Date: Fri, 04 Oct 2013 15:05:41 GMT<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<GetCitiesByCountryResponse xmlns="http://www.webserviceX.NET">
<GetCitiesByCountryResult><NewDataSet> <Table>
<Country>British Indian Ocean Territory</Country>
</NewDataSet>...</GetCitiesByCountryResult>
</GetCitiesByCountryResponse>
</soap:Body>
</soap:Envelope>