Using tcpmon to interactively debug calls to the Services Layer

You can use the tcpmon utility to interactively debug calls to the Services Layer. This will allow you to see the actual HTTP headers and entity bodies being sent in requests, and the headers and entity bodies being received in responses.

For instance, you can use tcpmon to debug calls made to the Services Layer by:

• CollectionSpace's Application layer.
• Code written using the CollectionSpace Services Java Client Library, including the automated client tests of the services layer.
• Web browers, cURL, and any other arbitrary HTTP client software.

Set up tcpmon as a proxy for the CollectionSpace Services layer

1. Download tcpmon.
2. Start tcpmon.
   The exact method of doing this may vary by operating system. On Linux, for instance, you might right-click on the tcpmon-1.1.jar or tcpmon.jar icon and select "Open with "Java"" from the menu which appears. On Mac OS X, you might double-click the icon instead.

   Tip

   If you encounter an error when trying to open tcpmon, see the Comment(s) at the end of this wiki page for suggestions.

3. Edit the values in the "Create a New TCP Monitor Connection" section, at left, in the tcpmon window:
   • Set Local Port to some unused local port number, such as 8200 (for example).
   • Set Server Name to the IP address of the server on which the CollectionSpace Services layer is running. If the Services layer is running on your own host, leave that value at its default of 127.0.0.1 (localhost).
   • Set Server Port to 8180, the port at which the CollectionSpace Services layer will be listening by default, on that server.
4. Click "Add Monitor".

Example of tcpmon's main window. (This is an imported image, and the port numbers do not match those listed above.)

Change your client configuration to connect to tcpmon, rather than to the Services layer

If you are using the Application layer

If you are debugging calls sent by CollectionSpace's Application layer to its Services layer:

For the tenant (museum) to which you'll be connecting, edit the $CSPACE_JEESERVER_HOME/lib/tenants/{tenantname}/local-{tenantname}-settings.xml file, to change the port number for the services layer to which the app layer will be connecting, to the Local Port number you set up when configuring tcpmon, above. (In the above file path, {tenantname} is a placeholder for the name of your museum ("tenant").)

If you are using the Java Client Library

If you are debugging calls sent by many of CollectionSpace Services layer's client tests, or other code written using the Java Client Library in which those tests are written:

1. Save a backup copy of your current collectionspace-client.properties file. (In trunk of the services source code tree, this file can be found at services/client/src/main/resources/collectionspace-client.properties.)
2. Edit the url property in your collectionspace-client.properties file, to connect to localhost at the Local Port number you set up when configuring tcpmon, above.
   
   For example, if you set the Local Port to 8200, edit this property as follows:

   cspace.url=http://localhost:8200/cspace-services/
   

The following additional steps appear also to be necessary, at least when running client tests using the full Services layer source code tree:

1. Change to the services/client directory.
2. Run mvn clean install -DskipTests. (This will install your edited collectionspace-client.properties file into a JAR in your local Maven repository.)

If you are using another HTTP client, like cURL

Connect to the Services layer via localhost at the Local Port number you set up when configuring tcpmon, above.

Example:

curl -u username:password http://localhost:8200/cspace-services/...

Interactively debug your calls to the Services layer

At this point, when you make calls to the Services layer, each request / response pair will appear as a row in the scrolling list, near the top of the tcpmon window.

Click any row to view the HTTP headers and entity body of the request and the response, which will appear in the two sections of the window below.

Example of tcpmon's traffic monitoring window, showing the contents of a GET request to the Services layer in the middle pane and the response to that request in the lower pane:

Revert to your previous configuration

When you are done debugging, you may return to your previous configuration.

Quit tcpmon

1. In the tcpmon window, click "Stop Monitor".
2. Quit the tcpmon application.

Revert your changes to your client configuration

If you are using the Java Client Library

Switch to your backup copy of your collectionspace-client.properties file, or else revert your recent changes to that file.

If you are using another HTTP client, like cURL

Change the port number at which you are accessing the CollectionSpace services back to its default of 8180, instead of 8200 or whatever other local port you were using with tcpmon.