Class AMXDebug
- java.lang.Object
-
- org.glassfish.admin.amx.util.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 propertyAMX_DEBUG_DIR_SPROP
is specified. All resulting AMXDebug output files end in the suffixAMX_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(org.glassfish.admin.amx.util.Output, java.lang.String)
andmarkAll(java.lang.String)
routines. This aids in visually organizing the output.For more information, see the javadoc on individual routines.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
AMXDebug.WrapOutput
Internal class which wraps the Output so that debug may be dynamically enabled or disabled without any users of the Output having to be aware of it.
-
Field Summary
Fields Modifier and Type Field Description 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 facilitystatic 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
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description 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 bymark(org.glassfish.admin.amx.util.Output, java.lang.String)
.String
getStdMarker(String msg)
The standard marker line emitted bymark(org.glassfish.admin.amx.util.Output, java.lang.String)
with a message inserted.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
mark(Output output, String marker)
Output a marker into the Output.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.
-
-
-
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 ifAMX_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 bymark(org.glassfish.admin.amx.util.Output, java.lang.String)
.
-
getStdMarker
public String getStdMarker(String msg)
The standard marker line emitted bymark(org.glassfish.admin.amx.util.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.
-
-