Diagnostic (CleanCode Java Libraries API)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

com.cleancode.data
Class Diagnostic

java.lang.Object
  com.cleancode.data.Diagnostic

public class Diagnostic
extends Object
extends Object

Provides configurable diagnostic logging of several message types to several output channels.

        // initialize
        import ...Data.Diagnostic;
        Diagnostic.init(...);
        diag = new Diagnostic(myClassName);
        VERSION = Version.getVersion(myClassName, "$Revision: 9 $");

        // for specific trails
        diag.enter(); // at top of a method
        diag.leave(); // at bottom of a method
        diag.create(); // in a constructor

        // for general information
        diag.print("me", "checking " + itemName);
        diag.print("me", PARAM_LIST);
        diag.warnPrint("field '" + itemName + "' not in library");
        diag.errPrint("fatal error: " + errCode);

        // for wrap-up
        diag.print("me", Diagnostic.getWarnCount() + " warning(s)");
        diag.print("me", Diagnostic.getErrCount() + " error(s)");
        Diagnostic.exit();

In a nutshell:

use print, warnPrint, or errPrint for general messages
use create, enter, leave, and getVersion for specific tracing
select stdout, stderr, or log files as destination channels.

Instrumenting Your Code

Each class that you wish to use diagnostics must have one or more Diagnostic objects-- each with its own diagnostic level--and be instrumented appropriately. What gets output and where it goes (that is, which specific diagnostics and which channels) is configurable from either the command-line or from a configuration file (or both), using an InputOptions object.

Quick Setup

This section discusses how to quickly convert an existing module to use diagnostics; the following sections provide much more detail.

Create one or more diagnostic objects per module:

         diag = new Diagnostic();

Change your System.err.println statements to errPrint or warnPrint method calls...

         System.err.println(msg) => diag.errPrint(msg);

...and your regular print statements to print method calls...

         if (DEBUG) print msg (or similar) => diag.print($msg);

Initialize the Diagnostic package in your main program (more detail on how to construct a parameter list follows the step-by-step section):

      Diagnostic.init(); // for errors and warnings only
      --OR--
      Diagnostic.init(this); // for diags for this package
      --OR--
      Diagnostic.init("pkg1","pkg2",...); // for diags for listed packages
      --OR--
      Diagnostic.init("pkg1",["v1",...]); // for variants of pkg1 diag
      --OR--
      Diagnostic.init($settings); // for more advanced uses

Finally, to avoid a warning from the diagnostic object itself, always define your package's VERSION variable.

Details on Quick Setup

1. Create a Diagnostic object

                diag = new Diagnostic(className);
                -- OR --
                diag = new Diagnostic(this);

The latter version is perhaps slightly preferable in that it does not need a hard-coded string. But note that you only need one Diagnostic object per class (not per instance), so it is recommended to assign it to a class variable. You may actually want more than one Diagnostic object, but even so, they should still all be class objects. Use the variant constructors for to create more than one:

                diag = new Diagnostic(className, variant);
                -- OR --
                diag = new Diagnostic(this, variant);

2. Hook up code tracing

Instrument your code by placing enter and leave method calls near the top and bottom, respectively, of the methods (and constructors) to be traced. Typically, use the no-argument form in constructors (since they do not have a method name). These methods will output ENTER---> and LEAVE---> labels to the currently selected output channels. In addition, they will indent (positively or negatively) subsequent messages to show the call sequence nested. The nesting prefix is configurable via the TRACE_INDENT property.

3. Hook up object creation diagnostics

Instrument your code by placing create method calls near the top of each constructor (or bottom--just be consistent). This method will output a message indicating creating an instance of the owning class to the currently selected output channels.

4. Hook up general diagnostics

Instrument your code by placing print method calls as needed to display static messages, variable values, etc. This method will output an arbitrary message to the currently selected output channels. You may pass a string or an arbitrary object (whose toString method will be invoked).

5. Instrument warnings and errors

Use warnPrint and errPrint where appropriate. This is an invaluable tool for locating system problems. Say, for example, a program serves web pages. It is not always appropriate to indicate file system errors to the user nor to use System.err.print, but using errPrint can also capture the message to a log file. These methods will output an arbitrary message preceded with either a WARNING: or ERROR: label.

6. Register a version for your module

Call the class method Version.getVersion(Object) to extract a version number from a version-control string, and to display it to the currently selected output channels.

7. Create or modify configuration file

You are not required to use a configuration file--for simple situations it is not necessary; see discussion further on about this. If you're interested in diagnostics from multiple modules, or multiple diagnostics within a single module, then you'll probably want a configuration file.

Create a configuration file as described in the API for the InputOptions class. Add properties used by Diagnostic objects as listed below. Also, add className_DIAG properties for each class you have instrumented. See the discussion on Diagnostic Selection for further details.

8. Initialize diagnostics and settings

In your program initialization, invoke the init method with a variety of parameter choices, as shown in the introduction to this section above.

Output Channels

All of the possible messages can go to any, all, or none of:

the STDERR stream (the console) typically used when trying to investigate system behavior or anomalies.
log files, one for regular messages and one for error/warning messages.
the STDOUT stream, formatted as plain text, for command-line use.
the STDOUT stream, formatted as XHTML, used as a web server response.

The selection of channels is made by the OUTPUT_DIAG and OUTPUT_ERR properties from the InputOptions object. See the table of InputOptions for this class.

Message Types

Each message type is shown in the table below along with the method used to generate it. The remaining two columns are explained following the table.

Message type	Method	Switch
warning	`warnPrint`	WARNINGS_ON
error	`errPrint`	always output
general	`print`	className_DIAG
object creation	`create`	CREATE_DIAG or className_DIAG
method trace	`enter` and `leave`	TRACE_DIAG or className_DIAG
class version	`Version.getVersion`	VERSION_DIAG or className_DIAG
server environment	`--`	ENV_DIAG

Messages will print only when one of the switches shown is active in the system diagnostic level mask. Note that several messages have more than one switch; those messages will print when either switch is active. Thus, one has the option of seeing, for example, create messages for all classes by activating the CREATE_DIAG switch, or of seeing all messages for one class by activating its class switch. The selection of active diagnostic switches is the DIAG_LEVEL property as explained below.

Diagnostic Selection

The key to seeing just what you want to see in the diagnostic output is the diagnostic selection mask. First, in the configuration file (or from the command-line) specify a InputOptions property for DIAG_LEVEL. Each bit of DIAG_LEVEL is an on/off switch. Therefore, it is best to use a hexadecimal, rather than decimal, representation where it is clear which bits are active. Example:

   DIAG_LEVEL = 0x04000fff

Next, define the diagnostic levels for the predefined Diagnostic switches. Example:

   VERSION_DIAG    = 0x40000000
   CREATE_DIAG     = 0x20000000
   TRACE_DIAG      = 0x10000000

Then, define the diagnostic levels for any library classes you are using. These will be named className_DIAG. Of course, you only need to do this if you care about seeing diagnostics for them. Any classes you do not explicitly define will get a default level of 1. Therefore, it is best not to use the 1 bit for anything else, as you will then get a lot of "noise". Example:

   INPUTOPTIONS_DIAG     = 0x08000000 // for InputOptions class
   DIAGNOSTIC_DIAG       = 0x04000000 // for Diagnostic class
   URLCONNECTIONMGR_DIAG = 0x00800000 // for UrlConnectionMgr class

Finally, define the diagnostic levels for any of your classes you have instrumented. As shown above, the diagnostic level properties are named with all capitals and a _DIAG suffix. So, if you have a class named SomeClass its corresponding diagnostic level in the configuration file will be labelled SOMECLASS_DIAG. Generally, each level should be a single bit, but this is not mandated. You could, for example, overlap bits to create a shorthand for seeing a group of certain diagnostics.

If you have more than one Diagnostic object in your module (created with one of the variant constructors), you need to define a diagnostic level for each one using the form className_variant_DIAG. So if you created one with a variant "A" in module SomeClass, then you'll also define SOMECLASS_A_DIAG.

InputOptions properties used by this class

Property	Type	Default	Specifies...
`InputOptions` properties used by this class
OUTPUT_DIAG	int	`OUTPUT_DIAG_LOGFILE`	output channels for regular (non-error and non-warning) messages
OUTPUT_ERR	int	`OUTPUT_DIAG_LOGFILE` and `OUTPUT_DIAG_STDERR`	output channels for error and warning messages
DIAG_LEVEL	int	0	active diag levels for regular messages
WARNINGS_ON	boolean	`true`	display or suppress warning messages
SHOW_THREAD	boolean	`true`	show or hide thread name with each message
TRACE_INDENT	String	2 spaces	characters to indent at `enter` or `leave` calls
LOG_DIR	String	log	directory in which to create log files
LOG_DIAG_NAME	String	errors	base name of the error (and warning) log file
LOG_ERR_NAME	String	diagnostics	base name of the diagnostic (non-error, non-warning) log file
CREATE_DIAG	int	1	diag used to show all object creations
TRACE_DIAG	int	1	diag used to show all trace messages
VERSION_DIAG	int	1	diag used to show all class versions
ENV_DIAG	int	1	diag used to show all system environment variables

Initialization Buffering

In order to provide the most robust and flexible diagnostic facility, the Diagnostic class was designed so that objects may be created and used before the class initialization -- and even the object initialization(!) -- has been performed. The initialization is typically performed by passing an InputOptions object to init (see below). But you may not have the arguments for these methods available without running some other code first. So until the initialization is done, the Diagnostic module quietly collects all messages in a queue, retaining all parameters of a message so that the diagnostic filters can be processed later.

The initialization process sets a variety of parameters from the system configuration, including specifying the diagnostic mask, the diagnostic levels for each module, and so forth. It also finishes initializing each Diagnostic object that has been created since the program started. Once initialization has completed, the message queue is processed, sending each message to the appropriate channel for the appropriate levels (or to the bit bucket if the message is not selected). The initialization buffering is then disabled; any subsequent Diagnostic method calls are passed through immediately. (Note that the secondary buffering controlled by setWebChannelBuffer is completely independent; it may or may not buffer depending on your setting.)

In the interests of reasonable behavior, this initialization buffering has some additional flexibility. First, if you do not call init, and a library module prints a diagnostic warning or error message, reasonable behavior dictates that the message should appear on STDERR, as described in the next section. So by the time your program ends, if you have not called init, any collected error/warning messages will be output to STDERR automatically. Second, if there is a lot of diagnostic traffic, it would not be nice to collect megabytes of messages which are never used. So after 100 messages have been collected, init is automatically invoked in the "casual user" mode, displays any collected errors/warnings, empties the buffer, and thus any subsequent errors/warnings are displayed immediately.

Using Diagnostics Without a Configuration File

Normal program sequence suggests that init be called, passing it an InputOptions object, before creating any Diagnostic objects, since configuration file settings are used by Diagnostic objects. But the casual user of my libraries, and perhaps of your libraries, will create objects which do create Diagnostic objects without any notion of a configuration file or of using InputOptions. That's okay; it's fine if init is never called, or is called with an InputOptions object which uses command-line parameters but no configuration file.

If a configuration file is not used, the following properties are adjusted for more sensible use:
OUTPUT_DIAG is initialized to OUTPUT_DIAG_STDOUT
OUTPUT_ERR is initialized to OUTPUT_DIAG_STDERR

That is, log file output is disabled, and if there are any errors or warnings to be printed along the way, they will simply be output to STDERR, rather than quietly go into a log file which the user/developer is not even aware of. Other diagnostic messages may or may not be displayed, depending upon your invocation of init.

SHOW_THREAD is initialized to false
For any messages which are displayed, they will not show the thread, just the plain message, again to keep things straightforward for the user.

Working With InputOptions Objects

To get started with creating your own InputOptions object, define a level for each Diagnostic object you're interested in, and set the diagnostic mask (DIAG_LEVEL) to that level. In the example, "2" is used. Any level will do as long as it is not the default level for unassigned diagnostics (the value 1). For a class named SomeClass, you would need only this:

                private static final String[] diagOutputOn = {
                        "SOMECLASS_DIAG=2",
                        "DIAG_LEVEL=2"
                };
                InputOptions settings = new InputOptions(diagOutputOn);
                Diagnostic.init(settings);

Note that if that is all you wish to do, it can be done more simply with
Diagnostic.init("SomeClass");

But let's explore further. Which output channels are selected? That is, what are the settings of the OUTPUT_DIAG and OUTPUT_ERR properties? Recall that normally the former would be just to the log file, while the latter would be STDERR and the log file. But, as described in the discussion above of running without a configuration file, these will be automatically adjusted to point only to STDOUT and STDERR, respectively. Hence, you get to see the output just as if you'd used System.out.println and System.err.println.

To tailor where the output goes, let's add to the InputOptions object. Here we show regular and error output explicitly set (note that for clarity I have left out package names on the variables in the Diagnostic namespace).

                private static final String[] diagOutputOn = {
                        "OUTPUT_DIAG="+Diagnostic.OUTPUT_DIAG_STDOUT,
                        "OUTPUT_ERR="+
                           (Diagnostic.OUTPUT_DIAG_STDERR|Diagnostic.OUTPUT_DIAG_LOGFILE),
                        "SOMECLASS_DIAG=2",
                        "VERSION_DIAG=4",
                        "DIAG_LEVEL=6"
                };

Several points to note:

We have included a line for VERSION_DIAG above, which specifies that the version of each instrumented and loaded class will be shown as a diagnostic message.
The DIAG_LEVEL is a bit-wise combination of the xxx_DIAG bit flags.
The OUTPUT_DIAG and OUTPUT_ERR properties are bitwise combinations of the valid output channel values.

Web Channel Buffering

Diagnostic output to the STDERR channel and to the log file channel is sent to these destinations as encountered. The STDOUT channel, however, may either be used for command line processing or for CGI output for a web server. Diagnostic therefore provides web channel buffering which you must enable if you are generating CGI output. Otherwise, you may have diagnostic output even before your HTTP headers, which will generate a server error. Almost as bad, you might get diagnostic output interspersed with your regular generated output. Use the setWebChannelBuffer method with a true value to enable it. From that point on, all output destined for the web channel will be queued until such time you explicitly ask for it via the output method. This allows you to insert the diagnostic output wherever you'd like in your generated web page. The output method provides some convenience features which depend on the input you feed it; see the method description for more detail. Once you call this method, the message queue is emptied, and will then start collecting subsequent Diagnostic output, if any, from scratch.

Since:: CleanCode 0.9
Version:: $Revision: 9 $
Author:: Michael Sorens

Nested Class Summary
`static class`	`Diagnostic.Test` A standalone test class to exercise the `Diagnostic` class.

Field Summary
`static String`	`CONSTRUCTOR` A label which specifies a constructor method, used as an argument to the `print` method.
`static String`	`DEFAULT_LOG_DIAG_NAME` Default standard logging file prefix name.
`static String`	`DEFAULT_LOG_DIR` Default directory for log output of diagnostics.
`static String`	`DEFAULT_LOG_ERR_NAME` Default error/warning logging file prefix name.
`static String`	`ERROR_LABEL` Constant label prefixing all error messages.
`static int`	`OUTPUT_DIAG_LOGFILE` A bit switch directing output to a log file as plain text.
`static int`	`OUTPUT_DIAG_STDERR` A bit switch directing output to STDERR as plain text.
`static int`	`OUTPUT_DIAG_STDOUT` A bit switch directing output to STDOUT formatted as plain text.
`static int`	`OUTPUT_DIAG_WEBPAGE` A bit switch directing output to STDOUT formatted as HTML.
`static ParamMap`	`paramMap` The diagnostic parameters for the Diagnostic class itself.
`static String`	`VERSION` Current version of this class.
`static String`	`WARNING_LABEL` Constant label prefixing all warning messages.

Constructor Summary
`Diagnostic(Object anObject)` Creates a `Diagnostic` object with the standard level for the specified class.
`Diagnostic(Object anObject, String variant)` Creates a `Diagnostic` object with a variation of the standard level for the specified class.
`Diagnostic(String className)` Creates a `Diagnostic` object with the standard level for the specified class.
`Diagnostic(String className, String variant)` Creates a `Diagnostic` object with a variation of the standard level for the specified class.

Method Summary
`void`	`create()` Prints a message indicating creation of an object of the owning class.
`void`	`create(Object obj)` Prints a message indicating creation of an object of the specified class.
`void`	`create(String supplementalMsg)` Prints a message indicating creation of an object of the owning class with a supplemental message.
`void`	`enter()` Prints a message indicating entering a constructor of the owning class.
`void`	`enter(String methodName)` Prints a message indicating entering a method of the owning class with a supplemental message.
`void`	`enter(String methodName, String supplementalMsg)` Prints a message indicating entering a method of the owning class.
`void`	`errPrint(String msg)` Output an error message prefixed with the class name of the owning class.
`void`	`errPrint(String methodName, String msg)` Output an error message prefixed with a method name.
`static void`	`exit()` Cleanup routine to close all active log streams.
`static void`	`flush()` Flush all active log streams.
`static String`	`formatTable(Object msgObj)` Formats a one- or two-dimensional table for display.
`String`	`getClassName()` Returns the name of the owning class.
`String`	`getDiagName()` Returns the name of the diagnostic for the class which created it.
`int`	`getErrCount()` Return number of errors observed.
`int`	`getWarnCount()` Returns number of warnings observed.
`boolean`	`getWebPageEnabled()` Indicates whether either the standard or the error channels have specified the web page channel for output from the configuration settings.
`static void`	`init()` Initializes the diagnostic system enabling only warnings and errors to STDERR.
`static void`	`init(boolean enableAll)` Initializes the diagnostic system enabling all diagnostics for all classes.
`static void`	`init(InputOptions mySettings)` Initializes the diagnostic system with custom settings.
`static void`	`init(String className)` Initializes the diagnostic system enabling all diagnostics for the specified class.
`static void`	`init(String[] classNames)` Initializes the diagnostic system enabling all diagnostics for all the specified classes.
`static void`	`init(String className, String variantChars)` Initializes the diagnostic system enabling selected diagnostics for the specified class.
`static void`	`init(String className, String[] variant)` Initializes the diagnostic system enabling selected diagnostics for the specified class.
`boolean`	`isActive()` Indicates whether the `Diagnostic` is selected by the current diagnostic level.
`void`	`leave()` Prints a message indicating leaving a constructor of the owning class.
`void`	`leave(String methodName)` Prints a message indicating leaving a method of the owning class with a supplemental message.
`void`	`leave(String methodName, String supplementalMsg)` Prints a message indicating leaving a method of the owning class.
`String`	`output()` Retrieves the collected web channel output when web channel buffering is enabled.
`static String`	`output(String webPage)` Retrieves the collected web channel output when web channel buffering is enabled.
`void`	`print(Object msg)` Output an arbitrary message with no prefix.
`void`	`print(String methodName, Object msg)` Output an arbitrary message prefixed with the method name.
`void`	`printVersion(String targetClassName, String verString)` Prints the version number of the specified class.
`static void`	`reset()` Resets diagnostics to initial conditions, allowing init() to be called again.
`static void`	`setPendingLimit(int limit)` Changes the pending limit of messages before the Diagnostic system is auto-initialized.
`void`	`setTerse(boolean terse)` Selects whether Map objects should be output in a terse or verbose format.
`static void`	`setWebChannelBuffer(boolean boolValue)` Activates or deactivates the web channel buffer.
`void`	`warnPrint(String msg)` Output a warning message prefixed with the class name of the owning class.
`void`	`warnPrint(String methodName, String msg)` Output a warning message prefixed with a method name.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

OUTPUT_DIAG_STDOUT

public static final int OUTPUT_DIAG_STDOUT

A bit switch directing output to STDOUT formatted as plain text. This is a possible value for the OUTPUT_DIAG and OUTPUT_ERR properties. Included in the default OUTPUT_DIAG mask if a configuration file is not used.

See Also:: Constant Field Values

OUTPUT_DIAG_STDERR

public static final int OUTPUT_DIAG_STDERR

A bit switch directing output to STDERR as plain text. This is a possible value for the OUTPUT_DIAG and OUTPUT_ERR properties. Included in the default OUTPUT_ERR mask.

See Also:: Constant Field Values

OUTPUT_DIAG_WEBPAGE

public static final int OUTPUT_DIAG_WEBPAGE

A bit switch directing output to STDOUT formatted as HTML. This is a possible value for the OUTPUT_DIAG and OUTPUT_ERR properties.

See Also:: Constant Field Values

OUTPUT_DIAG_LOGFILE

public static final int OUTPUT_DIAG_LOGFILE

A bit switch directing output to a log file as plain text. This is a possible value for the OUTPUT_DIAG and OUTPUT_ERR properties. Included in the default OUTPUT_DIAG mask and OUTPUT_ERR mask if a configuration file is used.

See Also:: Constant Field Values

CONSTRUCTOR

public static final String CONSTRUCTOR

A label which specifies a constructor method, used as an argument to the print method. The print method displays the calling method along with its message. A constructor, though, is not a method, and thus doesn't have a method name. One may, of course, pass any string for the method name, but passing this constant provides consistency.

See Also:: Constant Field Values

VERSION

public static final String VERSION

Current version of this class.

paramMap

public static ParamMap paramMap

The diagnostic parameters for the Diagnostic class itself.

DEFAULT_LOG_DIR

public static final String DEFAULT_LOG_DIR

Default directory for log output of diagnostics.

See Also:: Constant Field Values

DEFAULT_LOG_DIAG_NAME

public static final String DEFAULT_LOG_DIAG_NAME

Default standard logging file prefix name.

See Also:: Constant Field Values

DEFAULT_LOG_ERR_NAME

public static final String DEFAULT_LOG_ERR_NAME

Default error/warning logging file prefix name.

See Also:: Constant Field Values

WARNING_LABEL

public static final String WARNING_LABEL

Constant label prefixing all warning messages.

See Also:: Constant Field Values

ERROR_LABEL

public static final String ERROR_LABEL

Constant label prefixing all error messages.

See Also:: Constant Field Values

Constructor Detail

Diagnostic

public Diagnostic(Object anObject)

Creates a Diagnostic object with the standard level for the specified class. The level className_DIAG is retrieved from the InputOptions property list. If a property for this class is not defined, a default value of 1 is used. This constructor is typically used when assigning to an instance variable, passing this as the first argument.

Parameters:: anObject - the owning object

Diagnostic

public Diagnostic(String className)

Creates a Diagnostic object with the standard level for the specified class. The level className_DIAG is retrieved from the InputOptions property list. If a property for this class is not defined, a default value of 1 is used. This constructor is typically used in a class variable declaration, as there's no this object to pass.

Parameters:: className - name of the calling class

Diagnostic

public Diagnostic(Object anObject,
                  String variant)

Creates a Diagnostic object with a variation of the standard level for the specified class. The level className_variation_DIAG is retrieved from the InputOptions property list. If a property for this class is not defined, a default value of 1 is used. This constructor is typically used when assigning to an instance variable, passing this as the first argument.

Parameters:: anObject - the owning object; variant - a label variation for the class diagnostic

Diagnostic

public Diagnostic(String className,
                  String variant)

Creates a Diagnostic object with a variation of the standard level for the specified class. The level className_variation_DIAG is retrieved from the InputOptions property list. If a property for this class is not defined, a default value of 1 is used. This constructor is typically used in a class variable declaration, as there's no this object to pass.

Parameters:: className - name of the calling class; variant - a label variation for the class diagnostic

Method Detail

init

public static void init()

Initializes the diagnostic system enabling only warnings and errors to STDERR. Other messages are silently ignored. This simplest form of the init method is sufficient for casual use. You may even use diagnostics without initializing at all, but note that errors and warnings may be delayed until your program finishes execution. See the Description for further details.

init

public static void init(boolean enableAll)

Initializes the diagnostic system enabling all diagnostics for all classes. Warnings and errors go to STDERR; regular messages go to STDOUT as plain text if enableAll is true.

Parameters:: enableAll - flag indicating to enable all or none of the regular messages.

init

public static void init(String className)

Initializes the diagnostic system enabling all diagnostics for the specified class. Warnings and errors go to STDERR; regular messages to STDOUT as plain text. For finer resolution within a class use init(String,String[]).

Parameters:: className - name of class to enable Diagnostics for

init

public static void init(String className,
                        String[] variant)

Initializes the diagnostic system enabling selected diagnostics for the specified class. All warnings and errors go to STDERR; regular messages for each variant of the named class go to STDOUT as plain text. Each member of the variant array identifies a specific variant which you would have created with the Diagnostic constructor. See init(String,String) for a convenience method for the special case of one-character variants.

Parameters:: className - name of class to enable Diagnostics for; variant - array of variant specifiers for the named class

init

public static void init(String className,
                        String variantChars)

Initializes the diagnostic system enabling selected diagnostics for the specified class. All warnings and errors go to STDERR; regular messages for each variant of the named class go to STDOUT as plain text. This is a convenience method for a special case of the init(String,String[]) method where you are using single-letter variants. So each character in the variant string designates a variant created from the constructor. If you have a class "someClass" and you created variants "A", "B", and "C", you can use "A", "BC", "BAC", or other combinations for variant to enable the ones you are interested in.

Parameters:: className - name of class to enable Diagnostics for; variantChars - String of single-character variant specifiers for the named class

init

public static void init(String[] classNames)

Initializes the diagnostic system enabling all diagnostics for all the specified classes. Warnings and errors go to STDERR; regular messages to STDOUT as plain text.

Parameters:: classNames - array of class names to enable Diagnostics for

init

public static void init(InputOptions mySettings)

Initializes the diagnostic system with custom settings. Taking an InputOptions object, this variation of init provides the most flexibility. The InputOptions object handles a configuration file and/or command-line arguments.

Parameters:: mySettings - an InputOptions object with custom settings

reset

public static void reset()

Resets diagnostics to initial conditions, allowing init() to be called again. Note that this should only be called before an init() or after an exit().

setPendingLimit

public static void setPendingLimit(int limit)

Changes the pending limit of messages before the Diagnostic system is auto-initialized. The default value is 100. If the number of messages already buffered is larger than this new pending limit, the Diagnostic system is immediately initialized.

Parameters:: limit - limit of messages buffered before automatically initializing Diagnostic class.

getClassName

public String getClassName()

Returns the name of the owning class.

Returns:: the name of the owning class

getDiagName

public String getDiagName()

Returns the name of the diagnostic for the class which created it. The name has the form className_DIAG or className_variant_DIAG, depending on the constructor used.

Returns:: the name of the owning class diagnostic property

getWarnCount

public int getWarnCount()

Returns number of warnings observed. This is the number of warnings which occurred, whether or not warnings are displayed.

Returns:: number of warnings observed

getErrCount

public int getErrCount()

Return number of errors observed.

Returns:: number of errors observed

getWebPageEnabled

public boolean getWebPageEnabled()

Indicates whether either the standard or the error channels have specified the web page channel for output from the configuration settings. This may be used, for example, to conditionally provide a header and footer for diagnostic output in a generated web page. Note that this will not indicate whether any diagnostic output is actually generated; it simply indicates that output, if generated, will be sent to the web page channel.

Returns:: boolean indicating whether web page channel has been activated.

setWebChannelBuffer

public static void setWebChannelBuffer(boolean boolValue)

Activates or deactivates the web channel buffer. This allows you to control the output on the web channel, so you may insert the diagnostic output in your generated web page wherever you wish using the output method. See the Description for further details.

Parameters:: boolValue - selects on or off state.

output

public static String output(String webPage)

Retrieves the collected web channel output when web channel buffering is enabled. When using web channel output, you may choose to have it buffered or not. When not buffered, output occurs to the channel when it is generated. But that may not be desirable if, for example, you have not set up your HTTP headers. So when you do enable web channel buffering, this method is the way you access that stored output. There are two methods to retrieve the data; the output() signature simply returns it as a string for you to place where you please. This form, on the other hand, accepts your web page as an input parameter, inserts the stored web channel output, and returns the updated page. The diagnostic text is inserted at the spot where a place holder is found in your text (the string "<DIAG_OUTPUT>"). If no place holder is found, and the text is HTML, then the diagnostic text is inserted just before the /body tag. If it is not HTML, then the diagnostic text is just tacked onto the end of your output.

Parameters:: webPage - your fully-formed web page as a string with a placeholder
Returns:: updated webPage with the diagnostic text added

output

public String output()

Returns:: diagnostic text

flush

public static void flush()

Flush all active log streams.

exit

public static void exit()

Cleanup routine to close all active log streams.

isActive

public boolean isActive()

Indicates whether the Diagnostic is selected by the current diagnostic level. That is, the Diagnostic was created to respond to a particular diagnostic switch. The global DIAG_LEVEL property specifies all the switches which are active for this program invocation. If this Diagnostic's level is one of the active switches, true is returned.

Returns:: boolean indicating whether Diagnostic is selected

printVersion

public void printVersion(String targetClassName,
                         String verString)

Prints the version number of the specified class. This method is invoked automatically by the Version class so one does not normally need to call it.

Parameters:: targetClassName - name of calling class; verString - RCS version string

create

public void create(String supplementalMsg)

Prints a message indicating creation of an object of the owning class with a supplemental message. This method will output a message not only for the diagnostic level of the owning class but also for the CREATE_DIAG diagnostic level. Thus, one has the option of seeing all create messages for all classes by switching on the CREATE_DIAG diagnostic level, or of seeing all messages for one (or more) particular class by switching on its diagnostic level.

Parameters:: supplementalMsg - a supplemental message to tack on to the standard message

create

public void create()

Prints a message indicating creation of an object of the owning class.

See Also:: general create method

create

public void create(Object obj)

Prints a message indicating creation of an object of the specified class.

Parameters:: obj - Owning object to print diagnostic about.
See Also:: general create method

enter

public void enter(String methodName,
                  String supplementalMsg)

Prints a message indicating entering a method of the owning class. This method will output a message not only for the diagnostic level of the owning class but also for the TRACE_DIAG diagnostic level. Thus, one has the option of seeing all enter/leave messages for all classes by switching on the TRACE_DIAG diagnostic level, or of seeing all messages for one (or more) particular class by switching on its diagnostic level.

A side effect of this method is that the indentation of subsequent messages will be increased to indicate nested method calls. Calls to enter and leave should be balanced to properly show indentation.

Parameters:: methodName - name of calling method; supplementalMsg - a supplemental message to tack on to the standard message
See Also:: leave

enter

public void enter()

Prints a message indicating entering a constructor of the owning class.

See Also:: general enter method

enter

public void enter(String methodName)

Prints a message indicating entering a method of the owning class with a supplemental message.

Parameters:: methodName - name of calling method
See Also:: general enter method

leave

public void leave(String methodName,
                  String supplementalMsg)

Prints a message indicating leaving a method of the owning class. This method will output a message not only for the diagnostic level of the owning class but also for the TRACE_DIAG diagnostic level. Thus, one has the option of seeing all enter/leave messages for all classes by switching on the TRACE_DIAG diagnostic level, or of seeing all messages for one (or more) particular class by switching on its diagnostic level.

A side effect of this method is that the indentation of subsequent messages will be decreased to indicate nested method calls. Calls to enter and leave should be balanced to properly show indentation.

Parameters:: methodName - name of calling method; supplementalMsg - a supplemental message to tack on to the standard message
See Also:: enter

leave

public void leave()

Prints a message indicating leaving a constructor of the owning class.

See Also:: general leave method

leave

public void leave(String methodName)

Prints a message indicating leaving a method of the owning class with a supplemental message.

Parameters:: methodName - name of calling method
See Also:: general leave method

print

public void print(String methodName,
                  Object msg)

Output an arbitrary message prefixed with the method name. If this object's diagnostic level is active (per the DIAG_LEVEL property) the message will be output to the currently selected output channels.

Parameters:: methodName - name of calling method; msg - message to print

print

public void print(Object msg)

Output an arbitrary message with no prefix. If this object's diagnostic level is active (per the DIAG_LEVEL property) the message will be output to the currently selected output channels. NB: This version of the print method differs from the print(String,Object) form in that it will not prefix the message with any caller information; it just outputs the unadorned message.

Parameters:: msg - message to print

warnPrint

public void warnPrint(String methodName,
                      String msg)

Output a warning message prefixed with a method name. If warnings are enabled (via the WARNINGS_ON property), the message will be output to the currently selected output channels.

Parameters:: methodName - name of calling method; msg - message to print

warnPrint

public void warnPrint(String msg)

Output a warning message prefixed with the class name of the owning class. If warnings are enabled (via the WARNINGS_ON property), the message will be output to the currently selected output channels. Defaults to using the class name as the caller, rather than the method name which may be passed in via the alternate warnPrint(String,String) form.

Parameters:: msg - message to print

errPrint

public void errPrint(String methodName,
                     String msg)

Output an error message prefixed with a method name. The message will be output unconditionally to the currently selected output channels.

Parameters:: methodName - name of calling method; msg - message to print

errPrint

public void errPrint(String msg)

Output an error message prefixed with the class name of the owning class. The message will be output unconditionally to the currently selected output channels. Defaults to using the class name as the caller, rather than the method name which may be passed in via the alternate errPrint(String,String) form.

Parameters:: msg - message to print

setTerse

public void setTerse(boolean terse)

Selects whether Map objects should be output in a terse or verbose format.

Parameters:: terse - boolean indicating terse state.

formatTable

public static String formatTable(Object msgObj)

Formats a one- or two-dimensional table for display.

Parameters:: msgObj - table to format for display.
Returns:: string representing formatted table

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

CleanCode Java Libraries

com.cleancode.data Class Diagnostic

Instrumenting Your Code

Quick Setup

Details on Quick Setup

1. Create a Diagnostic object

2. Hook up code tracing

3. Hook up object creation diagnostics

4. Hook up general diagnostics

5. Instrument warnings and errors

6. Register a version for your module

7. Create or modify configuration file

8. Initialize diagnostics and settings

Output Channels

Message Types

Diagnostic Selection

InputOptions properties used by this class

Initialization Buffering

Using Diagnostics Without a Configuration File

Working With InputOptions Objects

Web Channel Buffering

OUTPUT_DIAG_STDOUT

OUTPUT_DIAG_STDERR

OUTPUT_DIAG_WEBPAGE

OUTPUT_DIAG_LOGFILE

CONSTRUCTOR

VERSION

paramMap

DEFAULT_LOG_DIR

DEFAULT_LOG_DIAG_NAME

DEFAULT_LOG_ERR_NAME

WARNING_LABEL

ERROR_LABEL

Diagnostic

Diagnostic

Diagnostic

Diagnostic

init

init

init

init

init

init

init

reset

setPendingLimit

getClassName

getDiagName

getWarnCount

getErrCount

getWebPageEnabled

setWebChannelBuffer

output

output

flush

exit

isActive

printVersion

create

create

create

enter

enter

enter

leave

leave

leave

print

print

warnPrint

warnPrint

errPrint

errPrint

setTerse

formatTable

com.cleancode.data
Class Diagnostic