WebObjects 5.4.2

com.webobjects.foundation
Class NSLog

java.lang.Object
  extended by com.webobjects.foundation.NSLog

public final class NSLog
extends Object

NSLog is a static class that is used to access the WebObjects Foundation logging system. It allows you to log debugging messages and provides functionality for controlling the level and focus of debugging output. Logging with NSLog offers greater flexibility and integration with the WebObjects runtime and debugging system than does logging with System.out, System.err, or java.rmi.server.LogStream.

By specifying debug groups and the debug level using NSLog's methods, you can control the scope and granularity of debugging output. Perhaps you are only interested in seeing debugging output that relates to the Enterprise Objects Framework, or more specifically, debugging output that relates to database fetches. NSLog is designed to allow you to specify the output based on predefined debug groups and levels.

Although NSLog provides functionality for advanced debugging, it is also as simple to use as System.out:

NSLog.out.appendln("WebObjects");

The above code outputs "WebObjects" in the console by default, but output can be directed to custom NSLog.Logger classes.

The logging system is made up of three classes: NSLog and NSLog.Logger, and NSLog.PrintStreamLogger. NSLog provides methods for controlling the level (amount of information sent to the logger) and focus (scope of the information sent to the logger) of debugging output. NSLog.Logger is an abstract class that provides the basic functionality for NSLog.

NSLog also provides two concrete subclasses of NSLog.Logger: NSLog.PrintStreamLogger and NSLog.Log4JLogger. NSLog.PrintStreamLogger appends information to a java.io.PrintStream pointing to System.out or System.err, or to a custom java.io.PrintStream. NSLog.Log4JLogger appends information to an org.apache.log4j.Logger.

The NSLog class cannot be instantiated.

Redirecting the Output of NSLog

NSLog offers the ability to redirect output to custom java.io.PrintStreams, such as local files. Note that setting the WOOutputPath property in WOApplication will automatically redirect output from NSLog to the specified file. This example illustrates manually appending error output to the local file "/Local/Users/log.txt":

// New print stream based on path.
PrintStream aStream = NSLog.printStreamForPath("/Local/Users/log.txt");

if (aStream != null) {
  // Direct output to the custom PrintStream.
  ( (NSLog.PrintStreamLogger) NSLog.err).setPrintStream(aStream);
}

// Enable verbose logging.
NSLog.err.setIsVerbose(true);

// Outputs "[2000-10-18 09:01:00 GMT] <main> WebObjects"
NSLog.err.appendln("WebObjects");

// Disables logging.
NSLog.err.setIsEnabled(false);

// Outputs nothing, since logging is disabled.
NSLog.err.appendln("Enterprise Objects");

NSLog also allows developer to use their own custom subclasses of NSLog.Logger or NSLog.PrintStreamLogger to implement custom behavior. By subclassing NSLog.Logger instead of NSLog.PrintStreamLogger, you can provide custom logging implementations that are not based on java.io.PrintStreams, such as outputting to email, Swing windows, etc. In the following example, a custom Logger is used to capture error messages:

// The developer has created a custom subclass of NSLog.Logger called MyMailLogger
MyMailLogger aLogger = new MyMailLogger("admin@mac.com", "smtp.mac.com");

// Use the custom logger for all error messages
// NSLog.out and NSLog.debug still use the default NSLog.PrintStreamLogger implementation
NSLog.setErr(aLogger);

Debug Groups

To control the scope of the debug information that is sent to the logger, NSLog declares a number of debug groups. By default, logging is enabled for all the debug groups declared by NSLog, except DebugGroupParsing. All the WebObjects frameworks, including Foundation and EOF, use NSLog for debugging, and rely on debug groups to control the scope of their debug logging.

As an example, this code uses debug groups to disable logging for debug information related to the Enterprise Objects Framework:

NSLog.refuseDebugLoggingForGroups(NSLog.DebugGroupEnterpriseObjects)

Before sending debug information to the logger, all classes that log EOF-related debug information check to see if debug logging is allowed for EOF-related issues using one of the debugLoggingAllowedFor... methods. Since the above code removed the DebugGroupEnterpriseObjects bit from the bit mask, EOF-related issues won't be sent to the logger.

Debug Levels

To control the granularity of debug information that is sent to the logger, NSLog declares a number of debug levels. A debug level specifies the importance of the information displayed in a message. These messages may be the result of exceptions or errors, but may also just be informational, such as printing variable values.

When an exception is encountered, the exception message should always be output, but the stack trace should only be output if a particular level of debugging is requested:

} catch (Exception e) {
  NSLog.err.appendln("Exception encountered: " + e.getMessage());
  if (NSLog.debugLoggingAllowedForLevel(DebugLevelCritical) {
    NSLog.debug.appendln(e);
  }
}

When you desire to see the value of a variable at particular points in the application, DebugLevelInformational can be used to control logging. Logging the values of variables can be expensive, so it is prudent to wrap this kind of logging in a debug level conditional. For instance, you should conditionalize the logging of values in an array like this:

// Assuming declaration of int[] anArray = new int[10];
if debugLoggingAllowedForLevel(DebugLevelInformational) {
  for (i = 0, i < 9, i++) {
    NSLog.debug.appendln(anArray[i]);
  }
}

DebugLevelDetailed should be used to conditionalize logging for computationally intensive tasks, such as JDBC function calls.

Note that if the allowed debug level is specified using the setAllowedDebugLevel method, messages of that level and lower will be logged. That is, DebugLevelDetailed will also log messages of level DebugLevelInformational and messages of level DebugLevelCritical. Likewise, DebugLevelInformational will also log messages of level DebugLevelCritical, but not messages of level DebugLevelDetailed.

Creating Custom Debug Group Sets

NSLog uses a bit mask to specify a set of debug groups, which means that you can easily create a custom debug groups mask for more flexible logging. For instance, if the requirement is logging debugging output only for EOF-related issues and EOModel-related issues, you can simply bitwise inclusive OR the groups together using the "|" operator in Java. That creates a debug groups mask which can be used to more flexibly monitor and log errors relating to those two issues. To do this:

    <blockquote>
         // Create a custom debug groups mask.
         NSLog.debug.setAllowedDebugGroups(NSLog.DebugGroupEnterpriseObjects | NSLog.DebugGroupModel);
         ...
         // Later, add NSLog.DebugGroupWebObjects
         NSLog.allowDebuggingForGroups(NSLog.DebugGroupWebObjects);
     </blockquote>
 

In addition to the debug groups provided by WebObjects, new debug groups can be added. The high 32 bits (i.e. bits 32 - 63) are available to developers. The low bits are reserved by WebObjects An example of declaring a new debug group:

public static final long DebugGroupCustomGroup = 1L << 45;

NSLog From the Command Line

Debug groups and levels can be enabled from the command line, or in Properties files by setting values for the properties NSDebugLevel and NSDebugGroups. You can enable multiple debug groups by name, by bit position, or both. A series of examples:

To start with the default set of debug groups, and the debug level set to "Informational":
% ./MyJavaWOApp -DNSDebugLevel=NSLog.DebugLevelInformational
To start with the default debug Level, and the debug groups set to DebugGroupResources:
% ./MyJavaWOApp -DNSDebugGroups=NSLog.DebugGroupResources
To start with the default debug level, and the debug groups set to all mask values from 10 to 63:
% ./MyJavaWOApp -DNSDebugGroups=10:
To start with the default debug level, and the debug groups set to all mask values from 0 to 23:
% ./MyJavaWOApp -DNSDebugGroups=:23
To start with the default debug level, and the debug groups set to all mask values between 10 and 23:
% ./MyJavaWOApp -DNSDebugGroups=10:23
To start with the default debug level, and the debug groups set to DebugGroupResources:
% ./MyJavaWOApp -DNSDebugGroups="(NSLog.DebugGroupResources, NSLog.DebugGroupWebObjects)"
To start with the default debug level, and the debug groups set to mask values 0 to 2, 10 to 14, 18, and 29 to 63, as well as DebugGroupJSPServlets:
% ./MyJavaWOApp -DNSDebugLevel=NSLog.DebugLevelInformational -DNSDebugGroups="(:2, 10:14, 18, NSLog.DebugGroupJSPServlets, 29:)"

Constants

The following tables display the values of different debug groups and debug levels:

Constant          Shift             Value   
DebugGroupApplicationGeneration 3 8
DebugGroupArchiving 6 64
DebugGroupAssociations 19 524288
DebugGroupComponentBindings 9 512
DebugGroupComponents 26 67108864
DebugGroupControllers 20 1048576
DebugGroupDatabaseAccess 16 65536
DebugGroupDeployment 22 4194304
DebugGroupEnterpriseObjects 1 2
DebugGroupFormatting 10 1024
DebugGroupIO 13 8192
DebugGroupJSPServlets 27 134217728
DebugGroupKeyValueCoding 8 256
DebugGroupModel 15 32768
DebugGroupMultithreading 4 16
DebugGroupParsing 23 8388608
DebugGroupQualifiers 11 2048
DebugGroupReflection 24 16777216
DebugGroupRequestHandling 25 33554432
DebugGroupResources 5 32
DebugGroupRules 21 2097152
DebugGroupSQLGeneration 17 131072
DebugGroupTiming 14 16384
DebugGroupUserInterface 18 262144
DebugGroupValidation 7 128
DebugGroupWebObjects 2 4
DebugGroupWebServices 28 268435456
and again, sorted by number:
Constant          Shift             Value   
DebugGroupEnterpriseObjects 1 2
DebugGroupWebObjects 2 4
DebugGroupApplicationGeneration 3 8
DebugGroupMultithreading 4 16
DebugGroupResources 5 32
DebugGroupArchiving 6 64
DebugGroupValidation 7 128
DebugGroupKeyValueCoding 8 256
DebugGroupComponentBindings 9 512
DebugGroupFormatting 10 1024
DebugGroupQualifiers 11 2048
DebugGroupIO 13 8192
DebugGroupTiming 14 16384
DebugGroupModel 15 32768
DebugGroupDatabaseAccess 16 65536
DebugGroupSQLGeneration 17 131072
DebugGroupUserInterface 18 262144
DebugGroupAssociations 19 524288
DebugGroupControllers 20 1048576
DebugGroupRules 21 2097152
DebugGroupDeployment 22 4194304
DebugGroupParsing 23 8388608
DebugGroupReflection 24 16777216
DebugGroupRequestHandling 25 33554432
DebugGroupComponents 26 67108864
DebugGroupJSPServlets 27 134217728
DebugGroupWebServices 28 268435456

See Also:
NSLog.Logger

Nested Class Summary
static class NSLog.Log4JLogger
          NSLog.Log4JLogger is a concrete subclass of NSLog.Logger.
static class NSLog.Logger
          NSLog.Logger is an abstract class that specifies the core functionality for NSLog.
static class NSLog.PrintStreamLogger
          NSLog.PrintStreamLogger is a concrete subclass of NSLog.Logger.
 
Field Summary
static NSLog.Logger debug
          Logger sending error to system error file.
static long DebugGroupApplicationGeneration
          The debug group for logging of general application generation issues.
static long DebugGroupArchiving
          The debug group for logging of encoding and decoding issues.
static long DebugGroupAssociations
          The debug group for logging of association exceptions and problems.
static long DebugGroupComponentBindings
          The debug group for logging of binding exceptions and problems.
static long DebugGroupComponents
          The debug group for logging issues related to components and component definitions.
static long DebugGroupControllers
          The debug group for logging of controller exceptions and problems.
static long DebugGroupDatabaseAccess
          The debug group for logging of database access exceptions and problems.
static long DebugGroupDeployment
          The debug group for logging of Monitor, wotaskd, and deployment related issues.
static long DebugGroupEnterpriseObjects
          The debug group for enabling logging of general EOF issues.
static long DebugGroupFormatting
          The debug group for logging of formatting exceptions and problems.
static long DebugGroupIO
          The debug group for logging of I/O exceptions and problems.
static long DebugGroupJSPServlets
          The debug group for logging issues related to JSP or Servlet integration.
static long DebugGroupKeyValueCoding
          The debug group for logging of key value coding exceptions and problems
static long DebugGroupModel
          The debug group for logging of EOModel exceptions, problems, and inconsistencies.
static long DebugGroupMultithreading
          The debug group for logging of threading issues.
static long DebugGroupParsing
          The debug group for logging of HTML parsing issues and other HTML-related issues.
static long DebugGroupQualifiers
          The debug group for logging of qualifier issues
static long DebugGroupReflection
          The debug group for logging of class introspection issues.
static long DebugGroupRequestHandling
          The debug group for logging of issues related to the request-response loop.
static long DebugGroupResources
          The debug group for logging of resource loading/lookup exceptions and problems.
static long DebugGroupRules
          The debug group for logging of dynamic rule system issues and logging issues
static long DebugGroupSQLGeneration
          The debug group for logging of SQL generation issues and logging.
static long DebugGroupTiming
          The debug group for logging of dynamic rule system issues.
static long DebugGroupUserInterface
          The debug mask for logging of widget set and view exceptions and problems.
static long DebugGroupValidation
          The debug group for logging of validation exceptions and problems.
static long DebugGroupWebObjects
          The debug group for enabling logging of general WebObjects framework issues.
static long DebugGroupWebServices
          The debug group for logging issues related to Web Services.
static int DebugLevelCritical
          Logs debug messages that should not be sent in non-debug mode, such as stack traces.
static int DebugLevelDetailed
          Logs debug messages that qualify as computationally intensive, such as JDBC function calls.
static int DebugLevelInformational
          Logs debug messages that don't qualify as computationally intensive.
static int DebugLevelOff
          Logs no messages.
static NSLog.Logger err
          Logger sending output to system error file.
static NSLog.Logger out
          Logger sending output to system output file.
 
Method Summary
static void allowDebugLoggingForGroups(long aDebugGroups)
          Enables logging for the debug group or the debug groups mask specified by aDebugGroups by adding it (via bitwise inclusive OR) to the debug groups mask.
static int allowedDebugLevel()
          Deprecated. Use NSLog.debug.allowedDebugLevel instead.
static boolean debugLoggingAllowedForGroups(long aDebugGroups)
          Allow debug logging if the groups specified by aDebugGroups are enabled (that is, the debug groups are part of the debug groups enabled by allowDebugLoggingForGroups or setAllowedDebugGroups).
static boolean debugLoggingAllowedForLevel(int aDebugLevel)
          Allow debug logging if aDebuglevel is less than or equal to the debug level provided by allowedDebugLevel.
static boolean debugLoggingAllowedForLevelAndGroups(int aDebugLevel, long aDebugGroups)
          Invokes debugLoggingAllowedForGroups and debugLoggingAllowedForLevel.
static PrintStream printStreamForPath(String aPath)
          Provides a java.io.PrintStream object representing the file specified by aPath.
static void refuseDebugLoggingForGroups(long aDebugGroups)
          Disables debug logging for the debug groups mask specified by aDebugGroups.
static void setAllowedDebugGroups(long aDebugGroups)
          Specifies the set (the bit mask) of allowed debug groups.
static void setAllowedDebugLevel(int aDebugLevel)
          Deprecated. Use NSLog.debug.setAllowedDebugLevel instead.
static void setDebug(NSLog.Logger instance)
          Sets the debugging logger NSLog.debug to instance.
static void setDebug(NSLog.Logger instance, int aDebugLevel)
          Sets the debugging logger NSLog.debug to instance.
static void setErr(NSLog.Logger instance)
          Sets the logger NSLog.err to instance.
static void setOut(NSLog.Logger instance)
          Sets the logger NSLog.out to instance.
static String throwableAsString(Throwable t)
          Provides the stack trace of t as a string.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DebugGroupEnterpriseObjects

public static final long DebugGroupEnterpriseObjects
The debug group for enabling logging of general EOF issues.

See Also:
Constant Field Values

DebugGroupWebObjects

public static final long DebugGroupWebObjects
The debug group for enabling logging of general WebObjects framework issues.

See Also:
Constant Field Values

DebugGroupApplicationGeneration

public static final long DebugGroupApplicationGeneration
The debug group for logging of general application generation issues.

See Also:
Constant Field Values

DebugGroupMultithreading

public static final long DebugGroupMultithreading
The debug group for logging of threading issues.

See Also:
Constant Field Values

DebugGroupResources

public static final long DebugGroupResources
The debug group for logging of resource loading/lookup exceptions and problems.

See Also:
Constant Field Values

DebugGroupArchiving

public static final long DebugGroupArchiving
The debug group for logging of encoding and decoding issues.

See Also:
Constant Field Values

DebugGroupValidation

public static final long DebugGroupValidation
The debug group for logging of validation exceptions and problems.

See Also:
Constant Field Values

DebugGroupKeyValueCoding

public static final long DebugGroupKeyValueCoding
The debug group for logging of key value coding exceptions and problems

See Also:
Constant Field Values

DebugGroupComponentBindings

public static final long DebugGroupComponentBindings
The debug group for logging of binding exceptions and problems.

See Also:
Constant Field Values

DebugGroupFormatting

public static final long DebugGroupFormatting
The debug group for logging of formatting exceptions and problems.

See Also:
Constant Field Values

DebugGroupQualifiers

public static final long DebugGroupQualifiers
The debug group for logging of qualifier issues

See Also:
Constant Field Values

DebugGroupIO

public static final long DebugGroupIO
The debug group for logging of I/O exceptions and problems.

See Also:
Constant Field Values

DebugGroupTiming

public static final long DebugGroupTiming
The debug group for logging of dynamic rule system issues.

See Also:
Constant Field Values

DebugGroupModel

public static final long DebugGroupModel
The debug group for logging of EOModel exceptions, problems, and inconsistencies.

See Also:
Constant Field Values

DebugGroupDatabaseAccess

public static final long DebugGroupDatabaseAccess
The debug group for logging of database access exceptions and problems.

See Also:
Constant Field Values

DebugGroupSQLGeneration

public static final long DebugGroupSQLGeneration
The debug group for logging of SQL generation issues and logging.

See Also:
Constant Field Values

DebugGroupUserInterface

public static final long DebugGroupUserInterface
The debug mask for logging of widget set and view exceptions and problems.

See Also:
Constant Field Values

DebugGroupAssociations

public static final long DebugGroupAssociations
The debug group for logging of association exceptions and problems.

See Also:
Constant Field Values

DebugGroupControllers

public static final long DebugGroupControllers
The debug group for logging of controller exceptions and problems.

See Also:
Constant Field Values

DebugGroupRules

public static final long DebugGroupRules
The debug group for logging of dynamic rule system issues and logging issues

See Also:
Constant Field Values

DebugGroupDeployment

public static final long DebugGroupDeployment
The debug group for logging of Monitor, wotaskd, and deployment related issues.

See Also:
Constant Field Values

DebugGroupParsing

public static final long DebugGroupParsing
The debug group for logging of HTML parsing issues and other HTML-related issues.

See Also:
Constant Field Values

DebugGroupReflection

public static final long DebugGroupReflection
The debug group for logging of class introspection issues.

See Also:
Constant Field Values

DebugGroupRequestHandling

public static final long DebugGroupRequestHandling
The debug group for logging of issues related to the request-response loop.

See Also:
Constant Field Values

DebugGroupComponents

public static final long DebugGroupComponents
The debug group for logging issues related to components and component definitions.

See Also:
Constant Field Values

DebugGroupJSPServlets

public static final long DebugGroupJSPServlets
The debug group for logging issues related to JSP or Servlet integration.

See Also:
Constant Field Values

DebugGroupWebServices

public static final long DebugGroupWebServices
The debug group for logging issues related to Web Services.

See Also:
Constant Field Values

DebugLevelOff

public static final int DebugLevelOff
Logs no messages. The default.

See Also:
Constant Field Values

DebugLevelCritical

public static final int DebugLevelCritical
Logs debug messages that should not be sent in non-debug mode, such as stack traces. Logging with this debug level is not likely to affect the performance of the application.

See Also:
Constant Field Values

DebugLevelInformational

public static final int DebugLevelInformational
Logs debug messages that don't qualify as computationally intensive. Logging with this debug level will slow the application only moderately.

See Also:
Constant Field Values

DebugLevelDetailed

public static final int DebugLevelDetailed
Logs debug messages that qualify as computationally intensive, such as JDBC function calls. Logging with this debug level will slow the application considerably.

See Also:
Constant Field Values

debug

public static volatile NSLog.Logger debug
Logger sending error to system error file.


err

public static volatile NSLog.Logger err
Logger sending output to system error file.


out

public static volatile NSLog.Logger out
Logger sending output to system output file.

Method Detail

allowDebugLoggingForGroups

public static void allowDebugLoggingForGroups(long aDebugGroups)
Enables logging for the debug group or the debug groups mask specified by aDebugGroups by adding it (via bitwise inclusive OR) to the debug groups mask. For instance, to allow debug logging for EOF-related issues, add the EOF debug group, DebugGroupEnterpriseObjects to the mask:
    <blockquote>
     NSLog.allowDebugLoggingForGroups(DebugGroupEnterpriseObjects);
     </blockquote>
 

This differs from setAllowedDebugGroups in that allowDebugLoggingForGroups adds debug groups and debug groups masks to the existing bit mask in NSLog. setAllowedDebugGroups, however, replaces the existing bit mask in NSLog with the debug group or debug groups mask it is passed. For example,

    <blockquote>
     // This will add the EOF debug group to the mask:
     NSLog.allowDebugLoggingForGroups(DebugGroupEnterpriseObjects);
     // This will replace all debug groups and masks in
     // the bit mask with the EOF debug group
     NSLog.setAllowedDebugGroups(DebugGroupEnterpriseObjects);
     </blockquote>
 

Use the refuseDebugLoggingForGroups method to disallow specific debug groups.

By default, logging is allowed for all debug groups. If you set the debug level to be high (for example, DebugLevelDetailed), the debugging output may be overwhelming.

Parameters:
aDebugGroups - a customized set of debug groups
See Also:
NSLog.debugLoggingAllowedForGroups(long), NSLog.setAllowedDebugGroups(long), NSLog.refuseDebugLoggingForGroups(long)

allowedDebugLevel

@Deprecated
public static int allowedDebugLevel()
Deprecated. Use NSLog.debug.allowedDebugLevel instead.

Invokes NSLog.debug.allowedDebugLevel().

Returns:
the debug level of the debug logger
See Also:
NSLog.debugLoggingAllowedForGroups(long), NSLog.debugLoggingAllowedForLevel(int), NSLog.debugLoggingAllowedForLevelAndGroups(int, long), NSLog.setAllowedDebugLevel(int), NSLog.Logger.allowedDebugLevel()

debugLoggingAllowedForGroups

public static boolean debugLoggingAllowedForGroups(long aDebugGroups)
Allow debug logging if the groups specified by aDebugGroups are enabled (that is, the debug groups are part of the debug groups enabled by allowDebugLoggingForGroups or setAllowedDebugGroups). This method will return false if allowedDebugLevel returns DebugLevelOff. See "Creating Custom Debug Groups" in the class concepts for examples of how to create a custom debug groups bit mask.

Parameters:
aDebugGroups - a customized set of debug groups
Returns:
true if the debug groups specified by aDebugGroups are enabled (that is, the debug groups are part of the debug groups bit mask)
See Also:
NSLog.allowedDebugLevel(), NSLog.allowDebugLoggingForGroups(long), NSLog.setAllowedDebugGroups(long)

debugLoggingAllowedForLevel

public static boolean debugLoggingAllowedForLevel(int aDebugLevel)
Allow debug logging if aDebuglevel is less than or equal to the debug level provided by allowedDebugLevel. This is because the highest debug level, DebugLevelDetailed, implies DebugLevelInformational which implies DebugLevelCritical. See "Debug Levels" in the class concepts for more information.

Parameters:
aDebugLevel - level of debug required
Returns:
true if debug logging is allowed for aDebugLevel
See Also:
NSLog.allowedDebugLevel()

debugLoggingAllowedForLevelAndGroups

public static boolean debugLoggingAllowedForLevelAndGroups(int aDebugLevel,
                                                           long aDebugGroups)
Invokes debugLoggingAllowedForGroups and debugLoggingAllowedForLevel. Returns true if both of these methods return true.

Parameters:
aDebugLevel - level of debug required
aDebugGroups - a customized set of debug groups
Returns:
true if both debugLoggingAllowedForGroups and debugLoggingAllowedForLevel return true.
See Also:
NSLog.debugLoggingAllowedForLevel(int), NSLog.debugLoggingAllowedForGroups(long)

printStreamForPath

public static PrintStream printStreamForPath(String aPath)
Provides a java.io.PrintStream object representing the file specified by aPath. If the stream cannot be created, returns null, but no exception will be thrown.

Parameters:
aPath - path of the file
Returns:
a java.io.PrintStream to a file at the specified path or null if there is any problem with the path (i.e. it doesn't exist), or with the file at that path (i.e. it's a path to a directory, so a stream can't be created for it)
See Also:
NSLog.PrintStreamLogger

refuseDebugLoggingForGroups

public static void refuseDebugLoggingForGroups(long aDebugGroups)
Disables debug logging for the debug groups mask specified by aDebugGroups.

By default, logging is allowed for all debug groups. If the debug level is set to be high (for example, DebugLevelDetailed), the debugging output may be overwhelming.

Parameters:
aDebugGroups - customized groups for debug
See Also:
NSLog.allowDebugLoggingForGroups(long), NSLog.debugLoggingAllowedForGroups(long), NSLog.setAllowedDebugGroups(long)

setAllowedDebugGroups

public static void setAllowedDebugGroups(long aDebugGroups)
Specifies the set (the bit mask) of allowed debug groups. Typically, this method is invoked at the beginning of the application execution, since it affects logging behavior in the entire application, and completely overrides the global debug groups mask. If it is required to turn logging on for a smaller scope and for a shorter period of execution, allowDebugLoggingForGroups and refuseDebugLoggingForGroups should be used.

Note: This method completely overrides the global debug groups mask, and affects logging behavior in the entire application. It is suggested that it is used once at the beginning of application execution.

By default, logging is allowed for all debug groups. If the debug level is set to be high (for example, DebugLevelDetailed), the debugging output may be overwhelming.

Parameters:
aDebugGroups - customized groups for debug
See Also:
NSLog.debugLoggingAllowedForGroups(long), NSLog.allowDebugLoggingForGroups(long), NSLog.refuseDebugLoggingForGroups(long)

setAllowedDebugLevel

@Deprecated
public static void setAllowedDebugLevel(int aDebugLevel)
Deprecated. Use NSLog.debug.setAllowedDebugLevel instead.

Invokes setAllowedDebugLevel on NSLog.debug.

NOTE: NSLog stores no state regarding debug level. If you replace NSLog.debug using setDebug(Logger), you must invoke NSLog.debug.setAllowedDebugLevel. Otherwise, use setDebug(Logger, int).

Parameters:
aDebugLevel - level of debug required
Throws:
IllegalArgumentException - if aDebugLevel is invalid
See Also:
NSLog.setDebug(NSLog.Logger), NSLog.setDebug(NSLog.Logger, int), NSLog.Logger.setAllowedDebugLevel(int)

setDebug

public static void setDebug(NSLog.Logger instance)
Sets the debugging logger NSLog.debug to instance. By default, NSLog.debug is an NSLog.PrintStreamLogger that sends its output to System.err. NSLog.debug is used for status and error messages that will conditionally be shown. If instance is null, no change will be made.

NOTE: NSLog itself stores no state regarding debug level. After calling this method, you must invoke NSLog.debug.setAllowedDebugLevel.

Parameters:
instance - instance of the logger to use as the debug logger
See Also:
NSLog.debugLoggingAllowedForGroups(long), NSLog.debugLoggingAllowedForLevel(int), NSLog.debugLoggingAllowedForLevelAndGroups(int, long), NSLog.setDebug(NSLog.Logger, int), NSLog.Logger, NSLog.Logger.setAllowedDebugLevel(int)

setDebug

public static void setDebug(NSLog.Logger instance,
                            int aDebugLevel)
Sets the debugging logger NSLog.debug to instance. By default, NSLog.debug is an NSLog.PrintStreamLogger that sends its output to System.err. NSLog.debug is used for status and error messages that will conditionally be shown. If instance is null, no change will be made.

NOTE: NSLog itself stores no state regarding debug level.

Parameters:
instance - instance of the logger to use as the debug logger
Since:
5.2.2
See Also:
NSLog.debugLoggingAllowedForGroups(long), NSLog.debugLoggingAllowedForLevel(int), NSLog.debugLoggingAllowedForLevelAndGroups(int, long), NSLog.setDebug(NSLog.Logger), NSLog.Logger, NSLog.Logger.setAllowedDebugLevel(int)

setErr

public static void setErr(NSLog.Logger instance)
Sets the logger NSLog.err to instance. By default, NSLog.err is an NSLog.PrintStreamLogger that sends its output to System.err. NSLog.err is used for error messages that will always be shown. If instance is null, no change will be made.

Parameters:
instance - instance of the logger to use as the error logger
See Also:
NSLog.Logger

setOut

public static void setOut(NSLog.Logger instance)
Sets the logger NSLog.out to instance. By default, NSLog.out is an NSLog.PrintStreamLogger that sends its output to System.out. NSLog.out is used for status messages that will always be shown. If instance is null, no change will be made.

Parameters:
instance - instance of the logger to use as the out logger
See Also:
NSLog.Logger

throwableAsString

public static String throwableAsString(Throwable t)
Provides the stack trace of t as a string.

Parameters:
t - the throwable message
Returns:
the output message as a string

Last updated June 2008

Copyright © 2000-2008 Apple Inc.