com.sun.appserv.management.base
Class AMXDebug

java.lang.Object
  com.sun.appserv.management.base.AMXDebug

public final class AMXDebug
extends Object

Internal debug facility. For development use only. Do not use this class; it is subject to arbitrary change.

AMX has some unique issues that make a separate debug facility highly useful. These include:

• The Logging MBean cannot use System.out/err or logging mechanisms to emit debugging information because it can potentially cause infinite recursion (and thus stack overflow). Without anothermechanism, debugging the Logging MBean would be very difficult
• AMX code has both client and server aspects, and the client code runs in both environments. The client code in particular can't necessarily assume there is any logging infrastructure in place
• Debugging complex interactions of MBean invocations over a remote connection which may also involve asynchronous Notifications is complicated. This logging facility makes it possible to selectively view specific entities in the interactions that are occuring, on a fine-grained level, something not possible with the server logging mechanism
• There is reason and justification for considering debugging code a separate issue than the log file that customers are expected to use. Comingling the two has already led to the log file becoming useless when logging is set to FINE[R][EST]. This issue becomes a serious problem when trying to diagnose an issue; one is either stuck with inserting INFO or higher logging messages, or using FINE and dealing with the vast quantify of log messages emitted at that level. It simply is unproductive, and discourages thorough testing.

Usage notes AMXDebug associates a file with each identifier (typically a classname). These files are located within the AMX_DEBUG_SUBDIR subdirectory within the directory specified by System.getProperty( "user.home" ) unless the system property AMX_DEBUG_DIR_SPROP is specified. All resulting AMXDebug output files end in the suffix AMX_DEBUG_SUFFIX.

This fine-grained approach makes it possible to "tail" just the output from just the classes of interest, something that is difficult or impossible otherwise.

AMXDebug is designed as a singleton. However, arbitrary identifiers may be used to associate debugging output with a particular output file. This allows fine-grained and selective debugging of just the items of interest.

When debugging is off, overhead is minimal, because all debugging calls are routed to "dev/null". The caller can also wrap such calls such that they don't make it to AMXDebug at all.

The debug flag may be set via the system property AMX_DEBUG_ENABLED_SPROP. Debugging will be enabled if that property has value "true". Otherwise, it is disabled. Debugging may also be programmatically enabled, on a per-ID basis.

The expected usage is per-class and the classname can generally be used as the identifier. However, usage include other patterns; anything that the emitting code can agree on, regardless of whether it is in the same class, or spread across many. One possibility would be to place the Output into the thread context. There are other possibilities.

Output may be marked using the mark(com.sun.appserv.management.util.misc.Output, java.lang.String) and markAll(java.lang.String) routines. This aids in visually organizing the output.

For more information, see the javadoc on individual routines.

Nested Class Summary

class

AMXDebug.WrapOutput Internal class which wraps the Output so that debug may be dynamically enabled or disable without any users of the Output having to be aware of it.

Field Summary

static String	AMX_DEBUG_APPEND_SPROP the key for the system property to append to debug files.
static String	AMX_DEBUG_DIR_SPROP The key for the system property to specify a different AMX_DEBUG_DIR.
static String	AMX_DEBUG_ENABLED_SPROP the key for the system property to enable AMX debug facility
static String	AMX_DEBUG_SUBDIR The name of the default subdirectory which contains the ".debug" files created by AMXDebug.
static String	AMX_DEBUG_SUFFIX Suffix used on all Output files.

Method Summary

void	cleanup() Turn off all debugging and close all files.
boolean	getDebug(String id) Get the debug state of a particular Output for the specified ID.
boolean	getDefaultDebug() Get the current default debug state used when any new Outputs are created.
static AMXDebug	getInstance() Get the Singletone AMXDebug instance.
Output	getOutput(String id) ID is typically a classname, but may be anything which can be used for a filename.
File	getOutputFile(String id) Get the File associated with 'id'.
String[]	getOutputIDs()
Output	getShared()
String	getStdMarker() The standard marker line emitted by mark(com.sun.appserv.management.util.misc.Output, java.lang.String).
String	getStdMarker(String msg) The standard marker line emitted by mark(com.sun.appserv.management.util.misc.Output, java.lang.String) with a message inserted.
void	mark(Output output, String marker) Output a marker into the Output.
void	mark(String id) Output a standard marker into the Output.
void	mark(String id, String marker) Output a marker into the Output associated with 'id'.
void	markAll() Output a standard marker into the Output.
void	markAll(String marker) Output a standard marker into the Output.
static String	methodString(String name, Object... args)
void	reset(String id) Turn off debugging any close the associated file (if any) for the Output specified by 'id'.
void	setAll(boolean debug) Set the debug state of all Outputs.
void	setDebug(String id, boolean debug) Set the debug state of a particular Output for the specified ID.
void	setDefaultDebug(boolean debug) Set the current default debug state.

Methods inherited from class java.lang.Object

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

Field Detail

AMX_DEBUG_ENABLED_SPROP

public static final String AMX_DEBUG_ENABLED_SPROP

the key for the system property to enable AMX debug facility

See Also:

Constant Field Values

AMX_DEBUG_APPEND_SPROP

public static final String AMX_DEBUG_APPEND_SPROP

the key for the system property to append to debug files. Otherwise they are overwritten each time

See Also:

Constant Field Values

AMX_DEBUG_DIR_SPROP

public static final String AMX_DEBUG_DIR_SPROP

The key for the system property to specify a different AMX_DEBUG_DIR. This value is uninterpreted--the result from new File( System.getProperty( AMX_DEBUG_SUBDIR ) is used directly.

If the sytem property AMX_DEBUG_SUBDIR is not specified, then AMXDebug looks for the system property "com.sun.aas.instanceRoot". If that system property is not found, then "user.home" is used. The result of this is the "parent dir". The resulting output directory is then /AMX_DEBUG_SUBDIR.

See Also:

Constant Field Values

AMX_DEBUG_SUBDIR

public static final String AMX_DEBUG_SUBDIR

The name of the default subdirectory which contains the ".debug" files created by AMXDebug. This is the directory used if AMX_DEBUG_DIR_SPROP is not specified.

See Also:

Constant Field Values

AMX_DEBUG_SUFFIX

public static final String AMX_DEBUG_SUFFIX

Suffix used on all Output files.

See Also:

Constant Field Values

Method Detail

getOutputIDs

public String[] getOutputIDs()

getDefaultDebug

public boolean getDefaultDebug()

Get the current default debug state used when any new Outputs are created.

setDefaultDebug

public void setDefaultDebug(boolean debug)

Set the current default debug state. Existing outputs are not affected.

See Also:

setAll(boolean)

getDebug

public boolean getDebug(String id)

Get the debug state of a particular Output for the specified ID.

setDebug

public void setDebug(String id,
                     boolean debug)

Set the debug state of a particular Output for the specified ID. If the Output currently maintains an open file, and debug is false, the file is closed.

setAll

public void setAll(boolean debug)

Set the debug state of all Outputs.

See Also:

setDebug(java.lang.String, boolean)

cleanup

public void cleanup()

Turn off all debugging and close all files.

reset

public void reset(String id)

Turn off debugging any close the associated file (if any) for the Output specified by 'id'.

getStdMarker

public String getStdMarker()

The standard marker line emitted by mark(com.sun.appserv.management.util.misc.Output, java.lang.String).

getStdMarker

public String getStdMarker(String msg)

The standard marker line emitted by mark(com.sun.appserv.management.util.misc.Output, java.lang.String) with a message inserted.

mark

public void mark(Output output,
                 String marker)

Output a marker into the Output. If 'marker' is null, then the std marker is emitted.

mark

public void mark(String id,
                 String marker)

Output a marker into the Output associated with 'id'.

mark

public void mark(String id)

Output a standard marker into the Output.

markAll

public void markAll(String marker)

Output a standard marker into the Output.

markAll

public void markAll()

Output a standard marker into the Output.

getInstance

public static AMXDebug getInstance()

Get the Singletone AMXDebug instance.

getOutputFile

public File getOutputFile(String id)

Get the File associated with 'id'. The file may or may not exist, and may or may not be open, depending on whether debug is enabled and whether anything was written to the file.

getShared

public Output getShared()

getOutput

public Output getOutput(String id)

ID is typically a classname, but may be anything which can be used for a filename. The id will be used to create file .debug in the AMX_DEBUG_SUBDIR directory.

methodString

public static String methodString(String name,
                                  Object... args)