com.sun.appserv.management.base
Class AMXDebug

java.lang.Object
  extended by 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:

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)