ca.idms.io
Class TraceObject

java.lang.Object
  ca.idms.io.TraceObject

All Implemented Interfaces:

Trace

Direct Known Subclasses:

IdmsJdbcObject, IdmsXAResource, NativeCodePage, NativeFormat, NativeObject, ProxyOptions

public class TraceObject
extends java.lang.Object
implements Trace

This serves as a general base class and provides some basic debugging routines to print trace information and display the contents of class variables.

Static trace methods are no longer supported as of Server 5.0, in order to enable tracing to separate log writers for each JDBC data source.

Version:

2.00, 09/23/02

Author:

Dave Ross

Field Summary

protected static java.lang.Class<?>[]	exclude Trace all but these classes if not null.
static java.lang.String	EXCLUDE Property name to exclude the specified classes from the trace.
static java.lang.String	FALSE
protected static java.lang.Class<?>[]	include Trace only these classes if not null.
static java.lang.String	INCLUDE Property name to include only the specified classes in the the trace.
protected TraceOutput	logWriter Instance specific log writer.
static java.lang.String	PREFIX System property name prefix.
static java.lang.String	PROPERTIES_FILE Default CA IDMS properties file name.
static java.lang.String	PROPERTIES_KEY System properties key name to specify the CA IDMS properties file.
static boolean	snap Can be used as a general snap option.
static java.lang.String	SNAP The "snap" property can be used as a general snap option.
static java.lang.String	SNAP_BYTES The "snap.bytes" property can be use to snap buffers in the trace.
static java.lang.String	SNAP_NATIVE The "snap.native" property can be used to trace display write native data buffers in the trace as it is read or written.
static java.lang.String	SNAP_OBJECT The "snap.object" property can be use to display object fields in the trace.
static java.lang.String	SNAP_SQL The "snap.sql" property can be use to display SQL control blocks, SQL syntax and buffers in the trace.
static boolean	snapBytes Enables display of byte array data in trace stream.
static boolean	snapNative Enables display of objects read and written by readNative and writeNative methods.
static boolean	snapObject Enables formatted display of objects in trace stream.
static boolean	snapSql Enables formatted display of SQL objects in trace stream.
static boolean	stub Enables calls to stub routines for local testing.
static boolean	trace Global trace option flag.
static java.lang.String	TRACE The property name to enable global tracing is "trace".
static java.lang.String	TRACE_FILE The "trace.file" property can be used to specify the global trace file.
static java.lang.String	TRACE_LIFE The "trace.life" property can be used to trace when an object is created and finalized.
static java.lang.String	TRACE_NATIVE The "trace.native" property can be used to trace when native data is read or written.
static java.lang.String	TRACE_PRODUCT The "trace.product" property can be used to set a product name in the trace.
static boolean	traceLife Enables printing of trace messages when a TraceObject is initialized and finalized.
static boolean	traceNative Enables printing of readNative and writeNative trace messages.
static TraceOutput	traceStream Global trace output stream.
static java.lang.String	TRUE

Constructor Summary

TraceObject()
The 0 argument constructor sets the log and traces object creation.

Method Summary

protected void	finalize() The finalizer traces object destruction.
protected java.lang.Object	get(java.lang.reflect.Field f) Provides a default get(Field) method that will attempt to retrieve the value of a declared variable of the class, and will work for the public variables variables of a derived class.
static boolean	getBoolean(java.lang.String key, boolean val) Gets a boolean value from the System or CA IDMS properties.
protected static java.lang.Class<?>[]	getClasses(java.util.Vector<java.lang.String> v) Gets classes to be included or excluded from trace.
static int	getInteger(java.lang.String key, int val) Gets a integer value from the System or CA IDMS properties.
static java.lang.String	getProperty(java.lang.String key, java.lang.String val) Gets a string value from the System or CA IDMS properties.
static void	listProperties(java.io.PrintStream out) Lists CA IDMS properties, loading them if necessary.
void	message(java.lang.String s) Writes a message to the trace file.
static java.util.Vector<java.lang.String>	parseList(java.lang.String s) Parses a list of arguments.
protected void	print(char c) Appends a character to the trace line buffer.
protected void	print(java.lang.Object o) Appends an object's value to the trace line buffer.
protected void	print(java.lang.String s) Appends a string to the trace line buffer.
protected void	println(java.lang.Object o) Writes the value of object to the trace stream.
protected void	println(java.lang.String s) Writes a line to the trace stream and log writer.
void	snap() Displays object member variables.
void	snap(java.lang.Object o, byte[] b) Displays a byte array in memory dump format.
void	snap(java.lang.Object o, byte[] b, int l) Displays a byte array in memory dump format.
void	snap(java.lang.String t, byte[] b) Displays a byte array in memory dump format.
void	snap(java.lang.String t, byte[] b, int l) Displays a byte array in memory dump format.
void	snap(java.lang.String t, byte[] b, int s, int l) Displays a byte array in memory dump format.
void	snap(java.lang.String t, java.lang.String s) Displays a "long" String.
static java.lang.String	toHex(byte v) Converts a byte to a hex string.
static java.lang.String	toHex(byte[] v) Converts a byte array to a hex string.
static java.lang.String	toHex(int v) Converts an int to a hex string.
static java.lang.String	toHex(long v) Converts a long to a hex string.
static java.lang.String	toHex(short v) Converts a short to a hex string.
static java.lang.String	toString(java.lang.Object o) Gets the string repesentation of an object.
boolean	trace() Checks if tracing is enabled.
boolean	trace(boolean f) Checks if tracing is enabled.
void	trace(java.lang.Object o, java.lang.String s) Writes a line to the trace file.
void	trace(java.lang.String s) Writes a line to the trace file.
static boolean	trace(TraceObject t) Checks if tracing is enabled.
static boolean	trace(TraceObject t, boolean f) Checks if tracing is enabled.
boolean	traceEntry() Checks if trace enabled and sets the log writer for the current thread.
protected static void	unloadProperties() Clears the IDMS properties.

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

PROPERTIES_FILE

public static final java.lang.String PROPERTIES_FILE

Default CA IDMS properties file name.

See Also:

Constant Field Values

PROPERTIES_KEY

public static final java.lang.String PROPERTIES_KEY

System properties key name to specify the CA IDMS properties file.

See Also:

Constant Field Values

PREFIX

public static final java.lang.String PREFIX

System property name prefix. Properties are normally specified in the IDMS properties file, but can also be specified as system properties when prefixed with "ca.idms.". Note that this has changed from "ca.jdbc." in Server 5.0, to avoid any possible collisions with other CA products.

See Also:

Constant Field Values

TRACE

public static final java.lang.String TRACE

The property name to enable global tracing is "trace". Additional properties can be set to provide more detailed control over the types of information reported in the trace.

See Also:

PREFIX, getProperty(String, String), Constant Field Values

TRACE_FILE

public static final java.lang.String TRACE_FILE

The "trace.file" property can be used to specify the global trace file. The default trace destination is the standard output file.

See Also:

Constant Field Values

TRACE_PRODUCT

public static final java.lang.String TRACE_PRODUCT

The "trace.product" property can be used to set a product name in the trace. This is useful when the trace output is be mixed in with that of other applications. For example: "trace.product"="IDMS ".

See Also:

Constant Field Values

TRACE_LIFE

public static final java.lang.String TRACE_LIFE

The "trace.life" property can be used to trace when an object is created and finalized.

See Also:

Constant Field Values

TRACE_NATIVE

public static final java.lang.String TRACE_NATIVE

The "trace.native" property can be used to trace when native data is read or written.

See Also:

Constant Field Values

SNAP_NATIVE

public static final java.lang.String SNAP_NATIVE

The "snap.native" property can be used to trace display write native data buffers in the trace as it is read or written.

See Also:

Constant Field Values

SNAP

public static final java.lang.String SNAP

The "snap" property can be used as a general snap option.

See Also:

Constant Field Values

SNAP_BYTES

public static final java.lang.String SNAP_BYTES

The "snap.bytes" property can be use to snap buffers in the trace. The snap occurs after data conversion and therefore will be displayed in the format of the server machine.

See Also:

Constant Field Values

SNAP_OBJECT

public static final java.lang.String SNAP_OBJECT

The "snap.object" property can be use to display object fields in the trace.

See Also:

Constant Field Values

SNAP_SQL

public static final java.lang.String SNAP_SQL

The "snap.sql" property can be use to display SQL control blocks, SQL syntax and buffers in the trace. The snap occurs before data conversion and therefore will be displayed in the format of the local machine.

See Also:

Constant Field Values

INCLUDE

public static final java.lang.String INCLUDE

Property name to include only the specified classes in the the trace. When the "include" property is set to a comma separated list of fully qualified class names, only messages from those classes will be included in the trace.

See Also:

Constant Field Values

EXCLUDE

public static final java.lang.String EXCLUDE

Property name to exclude the specified classes from the trace. When the "exclude" property is set to a comma separated list of fully qualified class names, messages from those classes will be excluded from the trace.

See Also:

Constant Field Values

TRUE

public static final java.lang.String TRUE

See Also:

Constant Field Values

FALSE

public static final java.lang.String FALSE

See Also:

Constant Field Values

trace

public static boolean trace

Global trace option flag. When true this indicates that global tracing is enabled, and trace messages will be written to the output stream specified by traceStream. The global trace is independent of any JDBC log writer that might be set.

Classes should generally use the trace() method to determine if tracing is enabled to either the global trace or a log writer to avoid the overhead of building trace message when disabled.

See Also:

TRACE

traceLife

public static boolean traceLife

Enables printing of trace messages when a TraceObject is initialized and finalized.

See Also:

TRACE_LIFE

traceNative

public static boolean traceNative

Enables printing of readNative and writeNative trace messages. These are methods implemented by classes that implement the Native interface. This allows more specific control over the types of tacing information displayed.

See Also:

TRACE_NATIVE, Native

snap

public static boolean snap

Can be used as a general snap option.

See Also:

SNAP

snapNative

public static boolean snapNative

Enables display of objects read and written by readNative and writeNative methods.

See Also:

SNAP_NATIVE, snap(String,byte[],int,int), Native

snapBytes

public static boolean snapBytes

Enables display of byte array data in trace stream.

See Also:

SNAP_BYTES, snap(String,byte[],int,int)

snapObject

public static boolean snapObject

Enables formatted display of objects in trace stream.

See Also:

SNAP_OBJECT, snap()

snapSql

public static boolean snapSql

Enables formatted display of SQL objects in trace stream.

See Also:

SNAP_SQL, snap()

stub

public static boolean stub

Enables calls to stub routines for local testing. This is only useful for internal development testing.

include

protected static java.lang.Class<?>[] include

Trace only these classes if not null.

See Also:

INCLUDE

exclude

protected static java.lang.Class<?>[] exclude

Trace all but these classes if not null.

See Also:

EXCLUDE

traceStream

public static TraceOutput traceStream

Global trace output stream. This specifies the global output stream where trace messages from all IDMS objects in the Java VM are written. Global tracing is enabled be setting the (@link #TRACE} property, and is completely independent of any JDBC log writer that might be set.

By default trace information is written to System.out.

The IDMS JDBC Driver and JDBC Server override this and set the trace stream to use the native trace methods on platforms where they are available. This allows Java trace information to be integrated with the native client interface tracing.

On platforms where the native methods are not supported the TRACE_FILE property can be used to specify a trace file name. If this file cannot be opened for any reason the standard output will be used.

See Also:

TraceOutput, TraceStream

logWriter

protected TraceOutput logWriter

Instance specific log writer. This specifies the PrintWriter where trace messages for this and all "related" objects are written.

It is independent of the traceStream and is used to print messages to the log writer specified by the JDBC DriverManager or DataSource or equivalent class.

Constructor Detail

TraceObject

public TraceObject()

The 0 argument constructor sets the log and traces object creation.

Method Detail

finalize

protected void finalize()
                 throws java.lang.Throwable

The finalizer traces object destruction.

Overrides:

finalize in class java.lang.Object

Throws:

java.lang.Throwable - not really

getBoolean

public static boolean getBoolean(java.lang.String key,
                                 boolean val)

Gets a boolean value from the System or CA IDMS properties.

Parameters:

key - the name of the property.

val - the default value of the property.

Returns:

true if specified value is "true", false otherwise.

See Also:

getProperty(String, String)

getInteger

public static int getInteger(java.lang.String key,
                             int val)

Gets a integer value from the System or CA IDMS properties. The value can be specified in either decimal ("NNNNN") or hexdecimal ("0xNNNNNNNN") form.

Parameters:

key - the name of the property.

val - the default value of the property.

Returns:

the value if found, the default otherwise.

See Also:

getProperty(String, String)

getProperty

public static java.lang.String getProperty(java.lang.String key,
                                           java.lang.String val)

Gets a string value from the System or CA IDMS properties. This method first prefixes the key with PREFIX and searches the System properties for the value. It then uses the original key to search the CA IDMS properties. The last value found is returned.

Parameters:

key - the name of the property.

val - the default value of the property.

Returns:

the value if found, the default otherwise.

listProperties

public static final void listProperties(java.io.PrintStream out)

Lists CA IDMS properties, loading them if necessary. This method is provided for debugging.

Parameters:

out - the output print stream

unloadProperties

protected static void unloadProperties()

Clears the IDMS properties. They will be reloaded the next time they are accessed. This allows them to be refreshed without shutting down the Java VM.

traceEntry

public boolean traceEntry()

Checks if trace enabled and sets the log writer for the current thread. This method supports an instance specific log writer in addition to the global log stream. The constructor sets logWriter to the value in effect for the current thread.

This method should be invoked on entry by every public method exposed to the application to check if tracing is enabled and ensure that the connection specific log writer, if any, is set in the ThreadLocal variable for the current thread.

For example, the IDMS JDBC Driver uses this to support a separate log writer for each DataSource, and invokes this method first in every public method that can cause a TraceObject to be created.

Note: This method must be invoked every time the thread could change. Multi-threaded applications are responsible for ensuring that this is set correctly before creating any objects derived from this class.

Returns:

true if tracing is enabled, false otherwise

trace

public static final boolean trace(TraceObject t)

Checks if tracing is enabled. Methods in classes not derived from TraceObject can use this method to determine when to print trace information. It checks both the global trace option and the instance specific logWriter in the specified trace object. If t == null only the global flag is checked.

Parameters:

t - trace object to test or null

Returns:

true tracing is enabled, false otherwise

See Also:

trace()

trace

public static final boolean trace(TraceObject t,
                                  boolean f)

Checks if tracing is enabled. This convenience method is slightly more efficient than the equivalent:

f && TraceObject.trace(t)

Parameters:

t - trace object to test or null

f - additional trace flag

Returns:

true if tracing is enabled, false otherwise

See Also:

trace()

trace

public final boolean trace()

Checks if tracing is enabled. Methods in classes derived from this can use this method to determine when to print trace information. It checks both the global trace flag and the instance specific logWriter in this object.

Returns:

true if tracing is enabled, false otherwise

trace

public final boolean trace(boolean f)

Checks if tracing is enabled. This convenience method is slightly more efficient than the equivalent:

f && trace()

Parameters:

f - additional trace flag

Returns:

true if tracing is enabled, false otherwise

getClasses

protected static java.lang.Class<?>[] getClasses(java.util.Vector<java.lang.String> v)

Gets classes to be included or excluded from trace.

Parameters:

v - vector containing class names

Returns:

array of class objects or null if none found

parseList

public static java.util.Vector<java.lang.String> parseList(java.lang.String s)

Parses a list of arguments.

Parameters:

s - comma delimited argument string

Returns:

vector containing substrings

message

public void message(java.lang.String s)

Writes a message to the trace file. This method is unconditional, the message is printed unchanged if a trace file stream exists.

Parameters:

s - String to write.

trace

public void trace(java.lang.Object o,
                  java.lang.String s)

Writes a line to the trace file. The line is preceded by object identification.

Parameters:

o - the that will be identified in the trace

s - String to write.

See Also:

trace(String), include, exclude

trace

public void trace(java.lang.String s)

Writes a line to the trace file. The line is preceded by object identification.

The caller of this method can check the trace flags to selectively trace information. This method does not check these flags, however it does check the include and exclude Class arrays.

Specified by:

trace in interface Trace

Parameters:

s - String to write.

See Also:

trace(), include, exclude

snap

public void snap(java.lang.Object o,
                 byte[] b)

Displays a byte array in memory dump format.

Parameters:

o - the object for the title.

b - the array to snap.

snap

public void snap(java.lang.Object o,
                 byte[] b,
                 int l)

Displays a byte array in memory dump format.

Parameters:

o - the object for the title.

b - the array to snap.

l - length to snap.

snap

public void snap(java.lang.String t,
                 byte[] b)

Displays a byte array in memory dump format.

Parameters:

t - title for array in trace stream

b - the array to snap.

snap

public void snap(java.lang.String t,
                 byte[] b,
                 int l)

Displays a byte array in memory dump format.

Parameters:

t - title for array in trace stream

b - the array to snap.

l - length to snap.

snap

public void snap(java.lang.String t,
                 byte[] b,
                 int s,
                 int l)

Displays a byte array in memory dump format.

Parameters:

t - title for array in trace stream

b - the array to snap.

s - start offset.

l - length to snap, -1 means use b,length.

See Also:

snap(String,byte[],int), snap(String,byte[]), snap(Object,byte[],int), snap(Object,byte[])

snap

public void snap(java.lang.String t,
                 java.lang.String s)

Displays a "long" String.

Parameters:

t - title for string in trace stream

s - the string to snap.

get

protected java.lang.Object get(java.lang.reflect.Field f)
                        throws java.lang.IllegalAccessException

Provides a default get(Field) method that will attempt to retrieve the value of a declared variable of the class, and will work for the public variables variables of a derived class. Classes containing non-public variables should override this method to so that snap() can access the values of these variables (cloning it exactly is all that is needed).

Parameters:

f - a Field returned by GetDeclaredFields()

Returns:

the Object named by f

Throws:

java.lang.IllegalAccessException - if the variable is not declared as public in the derived class

See Also:

snap, snap()

snap

public void snap()

Displays object member variables. Provides a default snap method that will display all public variables of a derived class. If the derived class overrides get(java.lang.reflect.Field), this method will also display the values of private, protected, and package variables.

This method checks the include and exclude Class arrays.

Specified by:

snap in interface Trace

See Also:

get(java.lang.reflect.Field)

print

protected void print(char c)

Appends a character to the trace line buffer.

Parameters:

c - character to print.

See Also:

print(String), println(String)

print

protected void print(java.lang.Object o)

Appends an object's value to the trace line buffer.

Parameters:

o - object to print.

See Also:

print(String), println(String)

print

protected void print(java.lang.String s)

Appends a string to the trace line buffer. This buffer prevents trace output from other threads from getting mixed in the object's print line without requiring the other threads to wait on the output stream. The buffer is actually written by println.

Parameters:

s - partial line String.

See Also:

println(String)

println

protected void println(java.lang.Object o)

Writes the value of object to the trace stream.

Parameters:

o - Object to write.

See Also:

println(String)

println

protected void println(java.lang.String s)

Writes a line to the trace stream and log writer. The string passed is appended to the line buffer, and the entire buffer is then printed and reinitialized. No attempt is made break up a "long" line into multiple print lines, so strings should be kept reasonably short (which will also avoid reallocating the line buffer).

Note that the calling object is responsible for ensuring that output from other threads does not get mixed up in the trace output.

Parameters:

s - String to write.

toHex

public static java.lang.String toHex(byte v)

Converts a byte to a hex string.

Parameters:

v - byte to convert.

Returns:

String representation.

toHex

public static java.lang.String toHex(byte[] v)

Converts a byte array to a hex string.

Parameters:

v - byte array to convert.

Returns:

String representation.

toHex

public static java.lang.String toHex(short v)

Converts a short to a hex string.

Parameters:

v - short to convert

Returns:

String representation.

toHex

public static java.lang.String toHex(int v)

Converts an int to a hex string.

Parameters:

v - int to convert

Returns:

String representation.

toHex

public static java.lang.String toHex(long v)

Converts a long to a hex string.

Parameters:

v - long to convert

Returns:

String representation.

toString

public static java.lang.String toString(java.lang.Object o)

Gets the string repesentation of an object. This method is essentially the Object.toString() method. It is provided here so that the trace and snap methods can consistently display an object's string representation when the object overrides toString.

Parameters:

o - the object.

Returns:

the object's string representation.