traceJ 1.0 README
=================

traceJ Overview
---------------

Debuggers are great while you're developing your code, but they don't 
do much good when a customer has a problem in the field.  It is also 
difficult, if not impossible, to recreate the exact circumstances under
which a customer is encountering a given problem.

If you've tried using the java.lang.Runtime traces to debug problems 
then you know the output is not uniform from one JVM to another.  You 
also know that you have virtually no control over what gets traced; no 
way to select the trace detail.  Worst of all, not all JVMs even support them.

If you need a commercial-scale, dynamic trace facility which will let
you (the developer) define what information is relevant; one with
which the trace granularity (or detail level) can be specified at
execution time; a facility which is hardware and JVM independent, then
you need traceJ.

traceJ is a set of Java classes which allow developers to enable 
tracing of their applications.  Features include:
 - YOU specify which constructors/methods are trace-eligible
 - YOU decide which items of information are useful for debugging
 - YOU which trace conditions warrant tracing of each constructor/method
 - trace granularity is specified at runtime
 - supports the following trace features:
	- constructors and methods
	- member fields
	- hex dump of String and char[] types
	- print any developer-defined messages
	- output to file stream or internal GUI display

Try it, see if it will meet your needs.  If it does then register it 
and gain the right to distribute the classes with your application.  It
can sure save time trying to determine just what's going on inside your
code.


Thread support
--------------

traceJ 1.2 is not thread-safe!  It is designed for single-threaded
applications.  Errors can occur when attempting to use it in more
than one thread of a multi-threaded application.  However, traceJ
version 2 (currently in development) will have full support for 
multi-threaded applications along with other expanded features.  It 
will allow your application to combine multi-threaded traces into a 
single output stream in such a way that it is easy to see how your 
code is executing.


System Requirement
------------------

Virtually any JVM (JDK 1.1)


Installation
------------

The traceJ archive file (tracJxx.zip) contains a zip file with the 
traceJ class files, a doc directory and an examples directory.  The
internal zip file (trace.zip) can be used in its zipped form or
unzipped into your class directory structure.

Extract the traceJ archive file (traceJxx.ZIP) to the desired directory.
Add trace.zip in your CLASSPATH environment variable, or unzip it into
a class directory.  If your CLASSPATH looks like this:

CLASSPATH=.;c:\java\classes;c:\java\lib\classes.zip 

then you could unzip trace.zip to the c:\java\classes directory.


Removal
-------

Simply delete the components of traceJ and remove trace.zip from 
your CLASSPATH (if necessary).  There are no registry entries or 
other modifications to be corrected.


Registration
------------

traceJ is provided as shareware.  For information about license, 
distribution, and registration, please see LICENSE.TXT and ORDER.TXT.


List of Files
-------------

 Length    Date    Name
 ------    ----    ----
   2453  11-22-97  docs/images/GridBagEx.gif
   2241  11-22-97  docs/images/OpenBookIcon.gif
    255  11-22-97  docs/images/blue-ball-small.gif
    925  11-22-97  docs/images/blue-ball.gif
   1497  11-22-97  docs/images/class-index.gif
   1711  11-22-97  docs/images/constructor-index.gif
   1565  11-22-97  docs/images/constructors.gif
    255  11-22-97  docs/images/cyan-ball-small.gif
    925  11-22-97  docs/images/cyan-ball.gif
   1438  11-22-97  docs/images/error-index.gif
   1707  11-22-97  docs/images/exception-index.gif
    102  11-22-97  docs/images/green-ball-small.gif
    886  11-22-97  docs/images/green-ball.gif
   1648  11-22-97  docs/images/interface-index.gif
    896  11-22-97  docs/images/magenta-ball.gif
   1588  11-22-97  docs/images/method-index.gif
   1403  11-22-97  docs/images/methods.gif
    104  11-22-97  docs/images/magenta-ball-small.gif
   1607  11-22-97  docs/images/package-index.gif
    255  11-22-97  docs/images/red-ball-small.gif
    527  11-22-97  docs/images/red-ball.gif
   1576  11-22-97  docs/images/variable-index.gif
   1380  11-22-97  docs/images/variables.gif
    255  11-22-97  docs/images/yellow-ball-small.gif
    925  11-22-97  docs/images/yellow-ball.gif
  24400  04-15-98  docs/phil.util.traceJ.Trace.html
  10001  04-15-98  docs/phil.util.traceJ.Traceable.html
   4814  04-15-98  docs/phil.util.traceJ.TraceToken.html
  18980  04-15-98  docs/AllNames.html
    801  04-15-98  docs/tree.html
   1612  04-15-98  examples/TestTrace.java
   9828  04-15-98  trace.zip
   2594  04-14-98  Vendor.txt
   5276  04-15-98  Readme.txt
   3107  04-14-98  Order.txt
   2611  04-14-98  License.txt
    345  04-14-98  History.txt

Feedback
--------

Feedback, questions and any comments :
E-mail    philreed@ticnet.com
Homepage  http://www.ticnet.com/philreed/
