jcifs.util
Class Log

java.lang.Object
  |
  +--jcifs.util.Log

public class Log
extends java.lang.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 worki (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.

Three example log entries follow:

 Jul 7 19:17:40.999 - smb tree connect warning 
  path=\\140.240.194.37\IPC$
 Jul 7 19:17:41.069 - datagram packet sent to: cranes.campus.foo.br/140.240.194.37
 00000: 00 06 01 10 00 01 00 00 00 00 00 00 20 43 4B 41  |............ CKA|
 00010: 41 41 41 41 41 41 41 41 41 41 41 41 41 41 41 41  |AAAAAAAAAAAAAAAA|
 00020: 41 41 41 41 41 41 41 41 41 41 41 41 41 00 00 21  |AAAAAAAAAAAAA..!|
 00030: 00 01                                            |..              |
 Jul 7 19:17:47.087 - SmbFile exception
 java.net.UnknownHostException: no name with type 0x20 with no scope for host 140.240.194.37
     at jcifs.netbios.NbtAddress.getAllByAddress(NbtAddress.java:618)
     at jcifs.smb.SmbFile.list(SmbFile.java:700)
     at List.main(List.java:30)
 
To use this logging facility simply add any Log.println, Log.printHexDump, Log.printStackTrace, or derived methods throughout your code and set a suitable mask with Log.setMask. For example the following mask might be set at the very beginning of your program:

 Log.setMask(( Log.EXCEPTIONS | foo.Log.ALL ) & ~foo.Log.LOGINS );
 
This would write the stack traces from Log.printStackTrace calls and all logging for package foo with the exception of logging associated with the LOGINS mask. The following is an example of using the Log.println method:

 Log.println( Log.WARNINGS, "smb tree connect warning", " path=" + path );
 

Masks can be combined and subtracted with one another using bitwise operators. To combine two masks use the bitwise OR operator |. The bitwise AND operator & together with bitwise NOT ~ can be used to turn off masks.

If bit manipulation is not familiar, use the addMask and subtractMask methods. The equivalent of the first code sample would be:

 Log.addMask( Log.EXCEPTIONS );
 Log.addMask( foo.Log.ALL );
 Log.subtractMask( foo.Log.LOGINS );
 

Note: When defining a new mask, one must take care not to use bits that are already being used by another package. In the future, masks may be statically assigned during class initialization.

See Also:
LogWriter, jcifs.netbios.Log, jcifs.smb.Log

Field Summary
static int ALL
          Log all messages.
static int CRITICAL_EXCEPTIONS
          Depricated The jCIFS package no longer uses the CRITICAL_EXCEPTIONS mask.
static int DEBUGGING
          Use this mask while actively debugging your code.
static int EXCEPTIONS
          This is the default mask.
static int HEX_DUMPS
          This controls wheather or not printHexDump(java.lang.String, byte[]) messages are logged.
protected static int mask
          This is the integer mask that controls what is logged.
static java.lang.String NL
          The systems line separator.
static int NL_LENGTH
          The systems line separator length.
static int NON_CRITICAL_EXCEPTIONS
          Depricated The jCIFS package no longer uses the NON_CRITICAL_EXCEPTIONS mask.
static int NONE
          Mask to indicate that no messages should be logged(not even exceptions).
protected static jcifs.util.LogWriter out
          The shared output stream of all Log classes.
static int WARNINGS
          Log warning messages.
 
Constructor Summary
protected Log()
           
 
Method Summary
static void addMask(int mask)
           
static java.lang.String getHexString(byte[] src, int srcIndex, int size)
           
static java.lang.String getHexString(int val, int size)
          This is an alternative to the java.lang.Integer.toHexString method.
static java.lang.String getHexString(long val, int size)
           
static boolean isSet(int mask)
           
static void printHexDump(java.io.PrintStream ps, byte[] src, int srcIndex, int length)
           
static void printHexDump(java.lang.String desc, byte[] src)
          Hex dumps are ubiquitous enough to provide a standard and easy-to-use method for logging them.
static void printHexDump(java.lang.String desc, byte[] src, int srcIndex, int length)
           
static void println(int type, java.lang.String desc, char[] x)
          Print a char[] array.
static void println(int type, java.lang.String desc, int x)
          Print an int.
static void println(int type, java.lang.String desc, java.lang.Object x)
          Print an Object.
static void println(int type, java.lang.String desc, java.lang.String x)
          Print a String.
static void printProperties(int type, java.lang.String desc, java.util.Properties p)
          Print the contents of a Properties object to the log stream using the store method.
static void printStackTrace(int type, java.lang.String desc, java.lang.Throwable t)
           
static void printStackTrace(java.lang.String desc, java.lang.Throwable t)
          Provides standard way to log any Throwable object like an Exception.
static void setDateFormat(java.lang.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(java.io.OutputStream out)
          Specify an OutputStream to be used as the underlying stream.
static void subtractMask(int mask)
           
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 java.lang.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. Of course only exceptions that go through the printStackTrace(String desc, Throwable t ) facility can be filtered out.

CRITICAL_EXCEPTIONS

public static final int CRITICAL_EXCEPTIONS
Depricated The jCIFS package no longer uses the CRITICAL_EXCEPTIONS mask. It was invented to compensate for a deficiency in jCIFS that has since been resolved. It will be removed in the next release.

Log only critical exceptions. All exceptions logged with printStackTrace are considered critical. Exceptions are not critical if they are logged with the NON_CRITICAL_EXCEPTIONS mask.


NON_CRITICAL_EXCEPTIONS

public static final int NON_CRITICAL_EXCEPTIONS
Depricated The jCIFS package no longer uses the NON_CRITICAL_EXCEPTIONS mask. It was invented to compensate for a deficiency in jCIFS that has since been resolved. It will be removed in the next release.

Log non-critical exceptions. The EXCEPTIONS mask consists of both critical and non-critical exceptions.


WARNINGS

public static final int WARNINGS
Log warning messages.

DEBUGGING

public static final int DEBUGGING
Use this mask while actively debugging your code. It is an alternative for the popular System.out.println( "MADE IT!" ) statement but can be supressed.

HEX_DUMPS

public static final int HEX_DUMPS
This controls wheather or not printHexDump(java.lang.String, byte[]) messages are logged.

out

protected static jcifs.util.LogWriter out
The shared output stream of all Log classes. The defualt is System.err.

This was changed from System.out in jcifs-0.7.0b


mask

protected static int mask
This is the integer mask that controls what is logged. It is shared by all Log classes. The default mask is EXCEPTIONS which consists of CRITICAL_EXCEPTIONS and NON_CRITICAL_EXCEPTIONS.
Constructor Detail

Log

protected Log()
Method Detail

setPrintWriter

public static void setPrintWriter(java.io.OutputStream out)
Specify an OutputStream to be used as the underlying stream. The default OutputStream is System.out. Specify a different stream such as a FileOutputStream perhaps to divert all logging output to a different stream.
Parameters:
out - the stream to which logging messages are written

setDateFormat

public static void setDateFormat(java.lang.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
See Also:
java.util.SimpleDateFormat

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 provide a crude but effective syslog style way to dictate what is 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)

subtractMask

public static void subtractMask(int mask)

printStackTrace

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

printStackTrace

public static void printStackTrace(int type,
                                   java.lang.String desc,
                                   java.lang.Throwable t)

printHexDump

public static void printHexDump(java.lang.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(java.io.PrintStream ps,
                                byte[] src,
                                int srcIndex,
                                int length)

printHexDump

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

getHexString

public static java.lang.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 java.lang.String getHexString(long val,
                                            int size)

getHexString

public static java.lang.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,
                           java.lang.String desc,
                           int x)
Print an int. The bits of the integer type must match the mask.

println

public static void println(int type,
                           java.lang.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,
                           java.lang.String desc,
                           java.lang.String x)
Print a String. The bits of the integer type must match the mask.

println

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

printProperties

public static void printProperties(int type,
                                   java.lang.String desc,
                                   java.util.Properties p)
Print the contents of a Properties object to the log stream using the store method.