Package org.glassfish.admin.amx.util

Class 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(org.glassfish.admin.amx.util.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.

    • 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

    • 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.

      • 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'.

      • 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.