ariba.util.core
Class ThreadDebugState

java.lang.Object
  ariba.util.core.ThreadDebugState

public class ThreadDebugState
extends java.lang.Object

This class maintains debug state for the current thread. The class is intended to allow callers to add and remove arbitrary debug information as processing of a transation continues. This way when there is an error or a hang this information can be retrieved. It is very cheap to add and remove items as there is no synchronization. All static methods are safe to call.

Non static calls should be made with extreme caution - as that code will have to be able to handle all types of exceptions due to possible synchronization issues.

The only non static methods are for reading data exclusivly. This way a thread trying to look at the debug state of another thread will not be able to, under any circumstances, damage the thread it is looking at. Although it certainly may trigger exceptions in its own thread if race conditions are hit.

Nested Class Summary

static class

ThreadDebugState.StateMap

Field Summary

static boolean

threadStateEnabled

Method Summary

static void	clear() Remove all values that are currently stored.
static java.lang.Object	get(ThreadDebugKey key) Retrieve a value for a specified key.
static ThreadDebugState	getUnsafeThreadDebugState() This method is thread safe, but is the first step towards getting non safe data.
static java.lang.String	makeString() Return a string representing the contents of the state.
static java.lang.Object	nullSafeObject(java.lang.Object o) This is just a convinence for callers who wish to create Hashtables or Lists that contain objects that may be null.
static java.lang.Object	remove(ThreadDebugKey key) Remove a value for a specified key.
static void	set(ThreadDebugKey key, java.lang.Object value) The key specified will overwrite any other date stored with a pointer equal key.
java.lang.String	toString() This is the method to call to print state from a different thread.
java.lang.Object	unsafeGet(ThreadDebugKey key) This is an unsafe method.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

threadStateEnabled

public static boolean threadStateEnabled

Method Detail

set

public static void set(ThreadDebugKey key,
                       java.lang.Object value)

The key specified will overwrite any other date stored with a pointer equal key. The value reference will be saved, but not used, until needed. This is to allow operations to be significantly faster. Callers of this method should not do much computation or memory allocation to create the value object. It is ok if the value object's toString() is expensive as that will be called rarely. It is also ok if the value object changes internal contents during operation.

If value implements DebugState the debugState() method will be called instead of toString() on value when it is needed. This should happen rarely, so this method implementation may also be expensive without hurting performance of the overall application.

The toString() method of the value object must be be made safe for other threads to call, even if the value is being modified at the time. Throwing exceptions from the toString if the thread gets unlucky is acceptable, but data corruption is not.

Parameters:

key - the ThreadDebugKey to use for this object when printed. key may not be null.

value - the object to print out as part of the state. value may be null.

See Also:

DebugState

get

public static java.lang.Object get(ThreadDebugKey key)

Retrieve a value for a specified key. The key must be pointer equal to the key used to set the value.

remove

public static java.lang.Object remove(ThreadDebugKey key)

Remove a value for a specified key. The key must be pointer equal to the key used to set the value. The old value will be returned.

Parameters:

key - the ThreadDebugKey to delete from the current application state.

Returns:

the old value that was saved.

clear

public static void clear()

Remove all values that are currently stored.

makeString

public static java.lang.String makeString()

Return a string representing the contents of the state.

Returns:

The current state of this thread as a string. If there are errors in creating the string, the returned string will contain the text of the exception.

toString

public java.lang.String toString()

This is the method to call to print state from a different thread. To print your own thread's state, call the static makeString() method instead. This method will catch any exceptions that are thrown during processing and return them as the string.

Overrides:

toString in class java.lang.Object

unsafeGet

public java.lang.Object unsafeGet(ThreadDebugKey key)

This is an unsafe method. The caller is required to protect against exceptions that occur as a result of synchronization issues. It will attempt to perform an equivilent of a get.

getUnsafeThreadDebugState

public static ThreadDebugState getUnsafeThreadDebugState()

This method is thread safe, but is the first step towards getting non safe data. It will return a new ThreadDebugState object that will allow unsafe calls on it from a different thread. That object will, from then on, be able to see state that is set on this thread - even state set after this call.

nullSafeObject

public static java.lang.Object nullSafeObject(java.lang.Object o)

This is just a convinence for callers who wish to create Hashtables or Lists that contain objects that may be null. ThreadDebugState itself can handle null values