com.ibm.ws.ffdc

Class DiagnosticModule

  • java.lang.Object
    • com.ibm.ws.ffdc.DiagnosticModule


  • public class DiagnosticModule
    extends java.lang.Object
    Extend this class to create a diagnostic module to help FFDC capture and dump data for your component. Example usage:
     DiagnosticModuleForComponent dm = new DiagnosticModuleForComponent();
     if (FFDC.registerDiagnosticModule(dm, "com.ibm.ws.mycomponent.packagename") != 0)
     {
     // Diagnostic module failed to meet the criteria described above
     // Return codes :
     // 0 - DM was registered
     // 1 - A DM has already been registered with the package name
     // 2 - The DM did not meet the criteria to contain a single dump method
     // 3 - An unknown failure occured during the registration
     }
     
    Any methods beginning with "ffdcDump" will be recognized by the ffdc runtime, and used for data collection. These methods should expect the following parameters:
    1. Throwable th. The encountered exception.
    2. IncidentStream is. Write captured data to this stream.
    3. Object[] others. The value of the array may be null. If not null, it contains an array of objects which the caller to the FFDC filter passed.
    4. Object callerThis. The callerThis value may be null, if the method which invoked the filter was a static method. Or if the current point of execution for the filter, does not correspond to the DM being invoked.
    5. String sourceId. The sourceId passed to the filter.
    *

    Method names that start with "ffdcDumpDefault" will always be called when this component is involved in an exception or error situation. These methods will be responsible for performing the default data capture for their component.

    Method names that simply start with "ffdcDump" [not ffdcDumpDefault] are only called under certain conditions and are not considered part of the default data capture.

    Methods that don't start with "ffdcDump", or that don't conform to the expected signature will be ignored. Setting the com.ibm.ws.ffdc.debugDiagnosticModule system property to true will cause exceptions to be thrown for malformed diagnostic module signatures.

    • Field Summary

      Fields 
      Modifier and Type Field and Description
      static java.lang.String DEBUG_DM_PROPERTY
      Name of property used to enable noise-making when badly formed methods are encountered when initializing a new module.
      static java.lang.String FFDC_DUMP_DEFAULT_PREFIX
      The prefix of ffdcdumpdefault methods (compared using toLowerCase)
      static java.lang.String FFDC_DUMP_PREFIX
      The prefix of ffdcdump methods (compared using toLowerCase)
    • Constructor Summary

      Constructors 
      Constructor and Description
      DiagnosticModule() 
    • Method Summary

      Methods 
      Modifier and Type Method and Description
      boolean dumpComponentData(java.lang.String[] input_directives, java.lang.Throwable ex, IncidentStream ffdcis, java.lang.Object callerThis, java.lang.Object[] catcherObjects, java.lang.String sourceId, java.lang.String[] callStack)
      This method is invoked to instruct the diagnostic module to capture all relevant information that it has about a particular incident
      void getDataForDirectives(java.lang.String[] directives, java.lang.Throwable ex, IncidentStream ffdcis, java.lang.Object callerThis, java.lang.Object[] catcherObjects, java.lang.String sourceId)
      Invoke all the ffdcdump methods for a set of directives
      java.lang.String[] getDirectives()
      Return the list of directives returned by this diagnostic module.
      void stopProcessingException()
      Inform this base class (and the diagnostic engine) that no more diagnosis information is required for this incident
      boolean validate()
      Validate whether the diagnostic module is correctly coded.
      • Methods inherited from class java.lang.Object

        equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • DEBUG_DM_PROPERTY

        public static final java.lang.String DEBUG_DM_PROPERTY
        Name of property used to enable noise-making when badly formed methods are encountered when initializing a new module.
        See Also:
        Constant Field Values
      • FFDC_DUMP_PREFIX

        public static final java.lang.String FFDC_DUMP_PREFIX
        The prefix of ffdcdump methods (compared using toLowerCase)
        See Also:
        Constant Field Values
      • FFDC_DUMP_DEFAULT_PREFIX

        public static final java.lang.String FFDC_DUMP_DEFAULT_PREFIX
        The prefix of ffdcdumpdefault methods (compared using toLowerCase)
        See Also:
        Constant Field Values
    • Constructor Detail

      • DiagnosticModule

        public DiagnosticModule()
    • Method Detail

      • getDirectives

        public java.lang.String[] getDirectives()
        Return the list of directives returned by this diagnostic module.
        Returns:
        String[]
      • dumpComponentData

        public final boolean dumpComponentData(java.lang.String[] input_directives,
                                java.lang.Throwable ex,
                                IncidentStream ffdcis,
                                java.lang.Object callerThis,
                                java.lang.Object[] catcherObjects,
                                java.lang.String sourceId,
                                java.lang.String[] callStack)
        This method is invoked to instruct the diagnostic module to capture all relevant information that it has about a particular incident
        Parameters:
        input_directives - The directives to be processed for this incident
        ex - The exception that caused this incident
        ffdcis - The incident stream to be used to record the relevant information
        callerThis - The object reporting the incident
        catcherObjects - Additional objects that might be involved
        sourceId - The source id of the class reporting the incident
        callStack - The list of classes on the stack
        Returns:
        true if more diagnostic modules should be invoked after this one
      • getDataForDirectives

        public final void getDataForDirectives(java.lang.String[] directives,
                                java.lang.Throwable ex,
                                IncidentStream ffdcis,
                                java.lang.Object callerThis,
                                java.lang.Object[] catcherObjects,
                                java.lang.String sourceId)
        Invoke all the ffdcdump methods for a set of directives
        Parameters:
        directives - The list of directives to be invoked
        ex - The exception causing the incident
        ffdcis - The incident stream on which to report
        callerThis - The object reporting the incident
        catcherObjects - Any additional interesting objects
        sourceId - The sourceid of the class reporting the problem
      • validate

        public final boolean validate()
        Validate whether the diagnostic module is correctly coded. Method can be used as a simple validation of a components diagnostic module. The information printed can be used during the development of the DM.
        Returns:
        true; if the system property "com.ibm.ws.ffdc.debugDiagnosticModule" is set, then some validation will be performed on the diagnostic module.
      • stopProcessingException

        public final void stopProcessingException()
        Inform this base class (and the diagnostic engine) that no more diagnosis information is required for this incident