Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES
SUMMARY:  INNER | FIELD | CONSTR | METHOD DETAIL:  FIELD | CONSTR | METHOD

oracle.ifs.common
Class TraceLogger


java.lang.Object

  |

  +--oracle.ifs.common.TraceLogger
public abstract class TraceLogger
extends java.lang.Object

TraceLogger is the abstract tracing superclass.

Tracing writes time-stamped status information, called traces, to disk files. These trace logs are useful in tracking down unusual application behavior.

The tracing function is carried out by TraceLogger and its subclasses. Each LibrarySession, S_LibrarySession, and S_LibraryService object instantiates a TraceLogger. Obtain a reference to this TraceLogger by invoking the getTraceLogger method of these classes.

The TraceLogger controls where the trace logs are created, the type of information they contain, and the detail of this information.

Use setTraceType to control where the trace logs are created. A TraceLogger can create local trace logs, remote trace logs, both, or neither.

Local trace logs are created on the file system of the computer on which the TraceLogger is running. For a LibrarySession's trace logger, this is the client-tier computer on which LibrarySession runs. For a S_LibrarySession or S_LibraryService trace logger, this is the middle-tier application server hosting the session and service. Use setLocalStream to set the stream to which the local trace log is written.

Remote trace logs allow aggregation of trace information from multiple sessions. For a LibrarySession's trace logger, remote tracing sends the traces to the trace logger of the corresponding S_LibrarySession. For a S_LibrarySession's trace logger, remote tracing sends the traces to the trace logger of the corresponding S_LibraryService. For a S_LibraryService's trace logger, remote tracing sends the traces to a single, realm-wide, trace logger which aggregates the traces from all services into a single trace log.

To issue a trace request, invoke trace on a LibraryObject, LibrarySession, S_LibraryObject, S_LibrarySession, or S_LibraryService. This method takes a channel number, trace level, and payload message as arguments. The channel describes the type of operation that led to the trace, such as event processing or transaction management. The level specifies how detailed is the information contained in the trace. Level 10 is very detailed information; level 1 is high-level information.

TraceLogger provides methods to allow the desired trace level to be specified on a channel-by-channel basis. Increasing channels' trace levels increases the amount of information written to the trace log. A TraceLogger writes a trace request to the trace log only if the request's trace level is less than or equal to the trace level of the channel. Setting a channel's trace level to DISABLED (level 0) disables all tracing for that channel.

iFS reserves channels numbered 0 to LAST_RESERVED_CHANNEL for internal use. An application may create and use additional channels.

The trace log contains one trace per line. Each trace consists of the following tab-delimited fields:

Sometimes it may be computationally expensive for your application to prepare the string containing the payload message. To minimize performance degradation, use the TraceLogger isTraced method (or the LibraryObject, LibrarySession, S_LibraryObject, S_LibrarySession, or S_LibraryService convenience method of the same name) as follows: 

 // Only invoke myExpensiveMethod() if necessary.
 if (session.isTraced(TraceLogger.CHANNEL_GENERAL, 2))
 {
     String payloadMessage = myExpensiveMethod();
     session.trace(TraceLogger.CHANNEL_GENERAL, 2, payloadMessage);
 }
Other tips to maximize trace performance are:

At the start of a session, the trace level for each channel of both the LibrarySession trace logger and S_LibrarySession trace logger is set to the trace level of the corresponding channel of the S_LibraryService trace logger. Use the getLevels, setLevels, LibrarySession.getSessionTraceLoggerLevels and LibrarySession.setSessionTraceLoggerLevels methods to subsequently synchronize the trace levels of the LibrarySession and S_LibrarySession trace loggers. The LibrarySession.getServiceTraceLoggerLevels and LibrarySession.setServiceServiceTraceLoggerLevels can be similarly used to synchronize the S_LibraryService trace logger.

Field Summary
static int CHANNEL_AUDIT
          The Audit channel.
static int CHANNEL_CACHING
          The Caching channel.
static int CHANNEL_CONNECTION_POOL
          The Connection Pool channel.
static int CHANNEL_DIRECTORY_SERVICES
          The Directory Services channel.
static int CHANNEL_EVENT
          The Event channel.
static int CHANNEL_EXCEPTION
          The Exception Management channel.
static int CHANNEL_GENERAL
          The general-purpose trace channel.
static int CHANNEL_MAIL_SERVER
          Mail server channel.
static int CHANNEL_METHOD_INVOCATION
          The Method Invocation channel.
static int CHANNEL_OAS
          The CORBA channel.
static int HIGHEST_VALID_LEVEL
          The highest valid level.
static int LAST_RESERVED_CHANNEL
          The last channel reserved for internal iFS use.
static int LEVEL_DISABLED
          The value of level which represents disabling tracing.
static int TRACETYPE_BOTH
          Trace logs are sent to both a local stream and a remote TraceLogger.
static int TRACETYPE_LOCAL
          Trace logs are sent to a local stream.
static int TRACETYPE_NONE
          Tracing is disabled.
static int TRACETYPE_REMOTE
          Trace logs are sent to to a remote TraceLogger.
 
Method Summary
 void flush()
          Flushes the stream to which the local trace log is written.
 int getChannelCount()
          Gets the number of channels.
 int getLevel(int channel)
          Gets the level of the specified channel.
 int[] getLevels()
          Gets the levels of all channels.
 Localizer getLocalizer()
          Gets the Localizer of this TraceLogger.
 int getTraceType()
          Gets the trace type.
 boolean isAutoFlushed()
          Gets whether the stream to which the local trace log is written is automatically flushed each time a trace is written to it.
 boolean isTraced(int channel, int level)
          Gets whether tracing is enabled for the specified channel and level.
 void setAutoFlushed(boolean autoFlushed)
          Sets whether the stream to which the local trace log is written is automatically flushed each time a trace is written to it.
 void setLevel(int channel, int level)
          Sets the level of the specified channel.
 void setLevels(int level)
          Sets the level of each channel.
 void setLevels(int[] levels)
          Sets the levels of all channels.
 void setLocalStream(java.io.File file)
          Sets the stream to which the local trace log is written.
 void setLocalStream(java.io.PrintWriter writer)
          Sets the stream to which the local trace log is written.
 void setTraceType(int traceType)
          Sets the trace type.
 

Field Detail

TRACETYPE_NONE


public static final int TRACETYPE_NONE
Tracing is disabled.

TRACETYPE_LOCAL


public static final int TRACETYPE_LOCAL
Trace logs are sent to a local stream.

TRACETYPE_REMOTE


public static final int TRACETYPE_REMOTE
Trace logs are sent to to a remote TraceLogger.

TRACETYPE_BOTH


public static final int TRACETYPE_BOTH
Trace logs are sent to both a local stream and a remote TraceLogger.

CHANNEL_GENERAL


public static final int CHANNEL_GENERAL
The general-purpose trace channel.

CHANNEL_METHOD_INVOCATION


public static final int CHANNEL_METHOD_INVOCATION
The Method Invocation channel.

CHANNEL_OAS


public static final int CHANNEL_OAS
The CORBA channel.

This channel is used for tracing the CORBA infrastructure.

CHANNEL_DIRECTORY_SERVICES


public static final int CHANNEL_DIRECTORY_SERVICES
The Directory Services channel.

This channel is used for tracing the Directory Services infrastructure.

CHANNEL_CONNECTION_POOL


public static final int CHANNEL_CONNECTION_POOL
The Connection Pool channel.

This channel is used for tracing the connection pool, cursor pool, and transaction management infrastructure.

CHANNEL_EXCEPTION


public static final int CHANNEL_EXCEPTION
The Exception Management channel.

CHANNEL_EVENT


public static final int CHANNEL_EVENT
The Event channel.

CHANNEL_AUDIT


public static final int CHANNEL_AUDIT
The Audit channel.

CHANNEL_CACHING


public static final int CHANNEL_CACHING
The Caching channel.

CHANNEL_MAIL_SERVER


public static final int CHANNEL_MAIL_SERVER
Mail server channel.

LAST_RESERVED_CHANNEL


public static final int LAST_RESERVED_CHANNEL
The last channel reserved for internal iFS use.

LEVEL_DISABLED


public static final int LEVEL_DISABLED
The value of level which represents disabling tracing.

HIGHEST_VALID_LEVEL


public static final int HIGHEST_VALID_LEVEL
The highest valid level.
Method Detail

getLocalizer


public final Localizer getLocalizer()
                             throws IfsException
Gets the Localizer of this TraceLogger.
Returns:
the Localizer
Throws:
IfsException - if the operation fails

getChannelCount


public final int getChannelCount()
                          throws IfsException
Gets the number of channels.
Returns:
the number of channels. Since channels are numbered starting at 0, the channel number of the highest channel is one less than this value.
Throws:
IfsException - if the operation fails

setLevel


public final void setLevel(int channel,
                           int level)
                    throws IfsException
Sets the level of the specified channel.
Parameters:
channel - the channel number
level - the level
Throws:
IfsException - (IFS-11201) if the channel is invalid
IfsException - (IFS-11200) if the level is invalid

setLevels


public final void setLevels(int level)
                     throws IfsException
Sets the level of each channel.
Parameters:
level - the level
Throws:
IfsException - (IFS-11200) if the level is invalid

setLevels


public final void setLevels(int[] levels)
                     throws IfsException
Sets the levels of all channels.
Parameters:
levels - an array of levels. The array index corresponds to the channel number.
Throws:
IfsException - (IFS-11204) if the size of the array does not equal the number of channels
IfsException - (IFS-11200) if a level is invalid

getLevel


public final int getLevel(int channel)
                   throws IfsException
Gets the level of the specified channel.
Parameters:
channel - the channel number
Returns:
the level
Throws:
IfsException - (IFS-11201) if the channel is invalid

getLevels


public final int[] getLevels()
                      throws IfsException
Gets the levels of all channels.
Returns:
an array of levels. The array index corresponds to the channel number.
Throws:
IfsException - if the operation fails

setTraceType


public final void setTraceType(int traceType)
                        throws IfsException
Sets the trace type.
Parameters:
traceType - the desired trace type. Must be TRACETYPE_NONE, TRACETYPE_LOCAL, TRACETYPE_REMOTE, TRACETYPE_BOTH.
Throws:
IfsException - (IFS-11202) if the trace type is invalid

getTraceType


public final int getTraceType()
                       throws IfsException
Gets the trace type.
Returns:
the trace type value
Throws:
IfsException - if the operation fails

setLocalStream


public final void setLocalStream(java.io.PrintWriter writer)
                          throws IfsException
Sets the stream to which the local trace log is written.
Parameters:
writer - the PrintWriter to which the local trace log is written. If null, the local trace log is written to the standard error stream.
Throws:
IfsException - if the operation fails

setLocalStream


public final void setLocalStream(java.io.File file)
                          throws IfsException
Sets the stream to which the local trace log is written.

If the file does not exist, it will be created when the first trace is written to the local stream. If this file already exists, its existing contents will be overwritten.

Parameters:
file - the file to which the local trace log is written. If null, the local trace log is written to the standard error stream.
Throws:
IfsException - if the operation fails

setAutoFlushed


public final void setAutoFlushed(boolean autoFlushed)
                          throws IfsException
Sets whether the stream to which the local trace log is written is automatically flushed each time a trace is written to it.

If false, flush should be invoked before examining the local trace log to ensure its completeness.

Parameters:
autoFlushed - whether the stream is automatically flushed
Throws:
IfsException - if the operation fails

isAutoFlushed


public final boolean isAutoFlushed()
                            throws IfsException
Gets whether the stream to which the local trace log is written is automatically flushed each time a trace is written to it.
Returns:
whether the stream is automatically flushed
Throws:
IfsException - if the operation fails

flush


public final void flush()
                 throws IfsException
Flushes the stream to which the local trace log is written.
Throws:
IfsException - (IFS-11206) if the operation fails

isTraced


public final boolean isTraced(int channel,
                              int level)
                       throws IfsException
Gets whether tracing is enabled for the specified channel and level.
Parameters:
channel - the channel number
level - the level
Returns:
whether tracing is enabled
Throws:
IfsException - (IFS-11201) if the channel is invalid
Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES
SUMMARY:  INNER | FIELD | CONSTR | METHOD DETAIL:  FIELD | CONSTR | METHOD