Java client library

The java client library in scope/clients/clientlib provides useful functionality to tool clients written in Java: command line parsing, network handling, XML parsing, logging and error reporting, and other utility tasks.

The clientlib is a work in progress. Most classes are reasonably well documented; this document provides an overview of what's available.

(FIXME: This document should probably be the "@mainpage" in the clientlib package.)

Command line parsing

The Params class performs command line parsing for standalone clients. It recognizes many common options (like "--output" to set the output file and "--help" to print a help message); it's configurable to an extent.

The command line parser saves its results as properties on the Params object. The Util class has a method configure that accepts a Params object and uses the settings to configure the utilities, notably the output streams.

XML support

The clientlib provides a simple XML parser for an XML subset in the class XMLParser. (This parser is based on the SAX parser distributed with Java 5.) The library also provides a simple XML data structure through the classes XMLDocument, XMLElement, and XMLattribute. The XML parser always returns an XMLDocument instance.

Since numerous clients are similar in their needs to send and receive XML data, a number of utility classes exist to simplify this task. These are part of the data logger framework.

Network handling

The class ProxyConnection abstracts a TCP/IP connection from the client to the debugging proxy: it handles connecting to and disconnecting from the proxy, the initial handshake with the proxy, and data encoding and decoding for the transmission protocol. Clients of this class handle only Java String data.

Logging and error reporting

The Util class exports several logging functions: log, warn, and err. The latter two use the error output stream, whereas log uses the standard output stream. The streams can be controlled through Util.configure.

Other utilities

The data logger framework

The classes DataLoggerXML, DataLoggerClientXML, and DefaultDataLoggerClientXML act in concerts to make very simple data loggers possible:

The simplest client to study as an example is probably the Script Logger.