jcifs.util
Class Log

java.lang.Object
  |
  +--jcifs.util.Log
Direct Known Subclasses:
Log, Log

public class Log
extends Object

This log utility uses a combination of bit mask control and io stream functionality. All methods check the mask with the mask passed as a parameter to see if any further work(logging) should be performed. This provides explicit control at runtime over what is logged. The io stream model allows the PrintWriter to be set and provides many of the common PrintWriter methods that are usefull for streams. A little overkill but it is easy to use, implement, understand, and better than the plain Singlton style utilities.

Generally you need only be concerned with setting the mask with the desired class members of this Log class or any other class that extend this one like so:

 Log.setMask( jcifs.util.Log.EXCEPTIONS +
     jcifs.util.Log.WARNINGS +
     any.other.package.Log.DEBUGGING );
 

I guess the convention is to provide a class for each package called Log that extends this one and handles package specific messages. The only problem with this technique is that new Log classes must be carefull to use bits of the mask that are not already in use.

Since:
jcifs-0.1
Version:
0.1, 00/03/13
Author:
Michael B. Allen
See Also:
Log

Field Summary
static int ALL
          Log all messages.
static int DEBUGGING
          Use this when your just trying to log information while coding.
static int EXCEPTIONS
          This is the default mask.
static int HEX_DUMPS
          This is used by the printHexDump(java.lang.String, byte[]) function provided by this class.
protected static int mask
          This is the integer mask shared by all Log classes.
static String NL
          The systems line separator.
static int NL_LENGTH
          The systems line separator length.
static int NONE
          Mask to indicate that no messages should be logged(not even exceptions).
protected static LogWriter out
          The shared output stream shared by all Log classes.
static int WARNINGS
          This is just a standard convention for warning messages.
 
Constructor Summary
protected Log()
           
 
Method Summary
static void addMask(int mask)
           
static String getHexString(byte[] src, int srcIndex, int size)
           
static String getHexString(int val, int size)
          This is an alternative to the java.lang.Integer.toHexString method.
static String getHexString(long val, int size)
           
static boolean isSet(int mask)
           
static void printHexDump(String desc, byte[] src)
          Hex dumps are ubiquitous enough to provide a standard and easy-to-use method for logging them.
static void printHexDump(String desc, byte[] src, int srcIndex, int length)
           
static void println(int type, String desc, char[] x)
          Print a char[] array.
static void println(int type, String desc, int x)
          Print an int.
static void println(int type, String desc, Object x)
          Print an Object.
static void println(int type, String desc, String x)
          Print a String.
static void printStackTrace(String desc, Throwable t)
          Provides standard way to log any Throwable object like an Exception.
static void setDateFormat(String format)
          This controls what is passed to SimpleDateFormat to control what the timestamp looks like in the log stream.
static void setMask(int mask)
          Set the mask used to screen all calls to logging methods.
static void setPrintWriter(OutputStream out)
          Specify an OutputStream to be used as the underlying stream.
static void setPrintWriter(Writer out)
          Set the Writer used as the underlying stream.
static void toHexChars(int val, char[] dst, int dstIndex, int size)
          This is the same as getHexString(int val, int size) but provides a more practical form when trying to avoid String concatenation and StringBuffer.
static void toHexChars(long val, char[] dst, int dstIndex, int size)
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

NL

public static final String NL
The systems line separator.

NL_LENGTH

public static final int NL_LENGTH
The systems line separator length.

NONE

public static final int NONE
Mask to indicate that no messages should be logged(not even exceptions).

ALL

public static final int ALL
Log all messages.

EXCEPTIONS

public static final int EXCEPTIONS
This is the default mask. However, be aware that specifying a mask without adding this mask will result in exceptions not being logged. One should always add this EXCEPTIONS mask to the setMask(int mask) expression unless you are explicitly trying to suppress them. Ofcourse only exceptions that go through the printStackTrace(String desc, Throwable t ) facility can be filtered out.

WARNINGS

public static final int WARNINGS
This is just a standard convention for warning messages.

DEBUGGING

public static final int DEBUGGING
Use this when your just trying to log information while coding. It's an alternative for the ever popular System.out.println( "MADE IT!" ).

HEX_DUMPS

public static final int HEX_DUMPS
This is used by the printHexDump(java.lang.String, byte[]) function provided by this class.

out

protected static LogWriter out
The shared output stream shared by all Log classes. The defualt is System.out.

mask

protected static int mask
This is the integer mask shared by all Log classes. By defualt it is set to EXCEPTIONS.
Constructor Detail

Log

protected Log()
Method Detail

setPrintWriter

public static void setPrintWriter(Writer out)
Set the Writer used as the underlying stream. To write the log to a file, simply do

  setPrintWriter( new FileWriter( "log.txt" ))
 
Parameters:
out - the Writer for the underlying stream

setPrintWriter

public static void setPrintWriter(OutputStream out)
Specify an OutputStream to be used as the underlying stream.
Parameters:
out - the output stream

setDateFormat

public static void setDateFormat(String format)
This controls what is passed to SimpleDateFormat to control what the timestamp looks like in the log stream. For example, a format of "EEE, MMM d, h:mm:ss a" would generate timestamps that read Tue, Mar 14, 4:57:02 PM. This is a whistle.
Parameters:
the - format string

setMask

public static void setMask(int mask)
Set the mask used to screen all calls to logging methods. The idea here is that the mask can be specified as an arithmetic expression to perovide a crude but effective syslog style way to dictate what it logged. For example:

  setMask( Log.EXCEPTIONS +
           Log.HEX_DUMPS +
           jcifs.netbios.Log.PACKET_DATA );

  setMask( Log.ALL - jcifs.netbios.Log.PACKET_DIAGRAMS );
 

isSet

public static boolean isSet(int mask)

addMask

public static void addMask(int mask)

printStackTrace

public static void printStackTrace(String desc,
                                   Throwable t)
Provides standard way to log any Throwable object like an Exception.

printHexDump

public static void printHexDump(String desc,
                                byte[] src)
Hex dumps are ubiquitous enough to provide a standard and easy-to-use method for logging them. All that is required to use this is setting the mask for HEX_DUMPS. The hex dump output is represended in the standard form and is quite efficient. Many mega bytes of source data could be dumped to a file without worry.

 00000: 04 d2 29 00 00 01 00 00 00 00 00 01 20 45 47 46  |..)......... EGF|
 00010: 43 45 46 45 45 43 41 43 41 43 41 43 41 43 41 43  |CEFEECACACACACAC|
 00020: 41 43 41 43 41 43 41 43 41 43 41 41 44 00 00 20  |ACACACACACAAD.. |
 00030: 00 01 c0 0c 00 20 00 01 00 00 00 00 00 06 20 00  |..... ........ .|
 00040: ac 22 22 e1                                      |."".            |
 

printHexDump

public static void printHexDump(String desc,
                                byte[] src,
                                int srcIndex,
                                int length)

getHexString

public static String getHexString(int val,
                                  int size)
This is an alternative to the java.lang.Integer.toHexString method. It is an efficient relative that also will pad the left side so that the result is size digits.

getHexString

public static String getHexString(long val,
                                  int size)

getHexString

public static String getHexString(byte[] src,
                                  int srcIndex,
                                  int size)

toHexChars

public static void toHexChars(int val,
                              char[] dst,
                              int dstIndex,
                              int size)
This is the same as getHexString(int val, int size) but provides a more practical form when trying to avoid String concatenation and StringBuffer.

toHexChars

public static void toHexChars(long val,
                              char[] dst,
                              int dstIndex,
                              int size)

println

public static void println(int type,
                           String desc,
                           int x)
Print an int. The bits of the integer type must match the mask.

println

public static void println(int type,
                           String desc,
                           char[] x)
Print a char[] array. The bits of the integer type must match the mask.

println

public static void println(int type,
                           String desc,
                           String x)
Print a String. The bits of the integer type must match the mask.

println

public static void println(int type,
                           String desc,
                           Object x)
Print an Object. The bits of the integer type must match the mask.