oracle.ifs.common

Class TraceLogger

java.lang.Object

oracle.ifs.common.TraceLogger

Deprecated.

9.0.4.6: use oracle.ifs.common.logging.IfsLogger.

public class TraceLogger
extends Object

TraceLogger is the obsolete tracing class.

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:

• DT: the date and time
• CH: the channel number
• LV: the trace level
• SV: the service id of the traced object
• SS: the session id of the traced object
• ID: the id of the traced object
• CN: the classname of the traced object
• MS: the payload message

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:

• only trace the channels of interest
• don't set channels' trace levels unnecessarily high
• use local trace logs rather than remote trace logs where possible
• if you turn on tracing to troubleshoot a problem, turn it off when you're finished

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.

Version:

1.0

Author:

David Pitfield

(Published)

Field Summary

Fields

Modifier and Type	Field and Description
static int	CHANNEL_ACL_INDEXING Deprecated. The ACL Indexing channel.
static int	CHANNEL_AUDIT Deprecated. The Audit channel.
static int	CHANNEL_CACHING Deprecated. The Caching channel.
static int	CHANNEL_CONNECTION_POOL Deprecated. The Connection Pool channel.
static int	CHANNEL_DIRECTORY_SERVICES Deprecated. The Directory Services channel.
static int	CHANNEL_EVENT Deprecated. The Event channel.
static int	CHANNEL_EXCEPTION Deprecated. The Exception Management channel.
static int	CHANNEL_FOLDER_INDEXING Deprecated. The Folder indexing channel.
static int	CHANNEL_GENERAL Deprecated. The general-purpose trace channel.
static int	CHANNEL_MAIL_SERVER Deprecated. Mail server channel.
static int	CHANNEL_METHOD_INVOCATION Deprecated. The Method Invocation channel.
static int	CHANNEL_OAS Deprecated. The CORBA channel.
static int	HIGHEST_VALID_LEVEL Deprecated. The highest valid level.
static int	LAST_RESERVED_CHANNEL Deprecated. The last channel reserved for internal iFS use.
static int	LEVEL_DISABLED Deprecated. The value of level which represents disabling tracing.
static int	LEVEL_GREEN Deprecated. The value of level for status.
static int	LEVEL_PRIVATE Deprecated. The value of level for entry/exit of private scope methods on the CHANNEL_METHOD_INVOCATION channel.
static int	LEVEL_PROTECTED Deprecated. The value of level for entry/exit of protected and package scope methods on the CHANNEL_METHOD_INVOCATION channel.
static int	LEVEL_PUBLIC Deprecated. The value of level for entry/exit of public methods on the CHANNEL_METHOD_INVOCATION channel.
static int	LEVEL_RED Deprecated. The value of level for errors.
static int	LEVEL_YELLOW Deprecated. The value of level for warnings.
protected boolean	m_AutoFlushed Deprecated. Whether the stream to which the local trace log is written is automatically flushed each time a trace is written to it.
protected String	m_ChannelLabel Deprecated. The label for the trace log Channel field.
protected int[]	m_ChannelLevels Deprecated. The channels' levels.
protected String	m_ClassnameLabel Deprecated. The label for the trace log Classname field.
protected String	m_DateLabel Deprecated. The label for the trace log Date field.
protected File	m_File Deprecated. The file to which the local trace log is written.
protected String	m_IdLabel Deprecated. The label for the trace log Id field.
protected String	m_LevelLabel Deprecated. The label for the trace log Level field.
protected Localizer	m_Localizer Deprecated. The Localizer used by this TraceLogger.
protected PrintWriter	m_LocalStream Deprecated. The stream to which the local trace log is written.
protected String	m_PayloadLabel Deprecated. The label for the trace log Payload field.
protected String	m_ServiceIdLabel Deprecated. The label for the trace log Service Id field.
protected String	m_SessionIdLabel Deprecated. The label for the trace log Session Id field.
protected int	m_TraceType Deprecated. The type of tracing.
static int	TRACETYPE_BOTH Deprecated. Trace logs are sent to both a local stream and a remote TraceLogger.
static int	TRACETYPE_LOCAL Deprecated. Trace logs are sent to a local stream.
static int	TRACETYPE_NONE Deprecated. Tracing is disabled.
static int	TRACETYPE_REMOTE Deprecated. Trace logs are sent to to a remote TraceLogger.

Constructor Summary

Constructors

Constructor and Description
TraceLogger(Localizer localizer) Deprecated. Constructs a new TraceLogger.

Method Summary

Modifier and Type	Method and Description
void	finalize() Deprecated. Finalizes this TraceLogger.
void	flush() Deprecated. Flushes the stream to which the local trace log is written.
int	getChannelCount() Deprecated. Gets the number of channels.
int	getLevel(int channel) Deprecated. Gets the level of the specified channel.
int[]	getLevels() Deprecated. Gets the levels of all channels.
Localizer	getLocalizer() Deprecated. Gets the Localizer of this TraceLogger.
int	getTraceType() Deprecated. Gets the trace type.
protected void	initialize(int channelCount) Deprecated. Initializes this TraceLogger.
boolean	isAutoFlushed() Deprecated. 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) Deprecated. Gets whether tracing is enabled for the specified channel and level.
protected void	sendToStream(int channel, int level, Long serviceId, Long sessionId, Long id, String classname, String payload) Deprecated. Writes the trace request to the local trace log.
void	setAutoFlushed(boolean autoFlushed) Deprecated. 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) Deprecated. Sets the level of the specified channel.
void	setLevels(int level) Deprecated. Sets the level of each channel.
void	setLevels(int[] levels) Deprecated. Sets the levels of all channels.
void	setLocalStream(File file) Deprecated. Sets the stream to which the local trace log is written.
void	setLocalStream(PrintWriter writer) Deprecated. Sets the stream to which the local trace log is written.
void	setTraceType(int traceType) Deprecated. Sets the trace type.
void	trace(int channel, int level, Long serviceId, Long sessionId, Long id, String classname, String payload) Deprecated. Processes a trace request.

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

TRACETYPE_NONE

public static final int TRACETYPE_NONE

Deprecated.

Tracing is disabled.

See Also:

Constant Field Values

(Published)

TRACETYPE_LOCAL

public static final int TRACETYPE_LOCAL

Deprecated.

Trace logs are sent to a local stream.

See Also:

Constant Field Values

(Published)

TRACETYPE_REMOTE

public static final int TRACETYPE_REMOTE

Deprecated.

Trace logs are sent to to a remote TraceLogger.

See Also:

Constant Field Values

(Published)

TRACETYPE_BOTH

public static final int TRACETYPE_BOTH

Deprecated.

Trace logs are sent to both a local stream and a remote TraceLogger.

See Also:

Constant Field Values

(Published)

CHANNEL_GENERAL

public static final int CHANNEL_GENERAL

Deprecated.

The general-purpose trace channel.

See Also:

Constant Field Values

(Published)

CHANNEL_METHOD_INVOCATION

public static final int CHANNEL_METHOD_INVOCATION

Deprecated.

The Method Invocation channel.

See Also:

Constant Field Values

(Published)

CHANNEL_OAS

public static final int CHANNEL_OAS

Deprecated.

The CORBA channel.

This channel is used for tracing the CORBA infrastructure.

See Also:

Constant Field Values

(Published)

CHANNEL_DIRECTORY_SERVICES

public static final int CHANNEL_DIRECTORY_SERVICES

Deprecated.

The Directory Services channel.

This channel is used for tracing the Directory Services infrastructure.

See Also:

Constant Field Values

(Published)

CHANNEL_CONNECTION_POOL

public static final int CHANNEL_CONNECTION_POOL

Deprecated.

The Connection Pool channel.

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

See Also:

Constant Field Values

(Published)

CHANNEL_EXCEPTION

public static final int CHANNEL_EXCEPTION

Deprecated.

The Exception Management channel.

See Also:

Constant Field Values

(Published)

CHANNEL_EVENT

public static final int CHANNEL_EVENT

Deprecated.

The Event channel.

See Also:

Constant Field Values

(Published)

CHANNEL_AUDIT

public static final int CHANNEL_AUDIT

Deprecated.

The Audit channel.

See Also:

Constant Field Values

(Published)

CHANNEL_CACHING

public static final int CHANNEL_CACHING

Deprecated.

The Caching channel.

See Also:

Constant Field Values

(Published)

CHANNEL_FOLDER_INDEXING

public static final int CHANNEL_FOLDER_INDEXING

Deprecated.

The Folder indexing channel.

See Also:

Constant Field Values

(Published)

CHANNEL_ACL_INDEXING

public static final int CHANNEL_ACL_INDEXING

Deprecated.

The ACL Indexing channel.

See Also:

Constant Field Values

(Published)

CHANNEL_MAIL_SERVER

public static final int CHANNEL_MAIL_SERVER

Deprecated.

Mail server channel.

See Also:

Constant Field Values

(Published)

LAST_RESERVED_CHANNEL

public static final int LAST_RESERVED_CHANNEL

Deprecated.

The last channel reserved for internal iFS use.

See Also:

Constant Field Values

(Published)

LEVEL_DISABLED

public static final int LEVEL_DISABLED

Deprecated.

The value of level which represents disabling tracing.

See Also:

Constant Field Values

(Published)

LEVEL_RED

public static final int LEVEL_RED

Deprecated.

The value of level for errors.

See Also:

Constant Field Values

(Unpublished)

LEVEL_YELLOW

public static final int LEVEL_YELLOW

Deprecated.

The value of level for warnings.

See Also:

Constant Field Values

(Unpublished)

LEVEL_GREEN

public static final int LEVEL_GREEN

Deprecated.

The value of level for status.

See Also:

Constant Field Values

(Unpublished)

LEVEL_PUBLIC

public static final int LEVEL_PUBLIC

Deprecated.

The value of level for entry/exit of public methods on the CHANNEL_METHOD_INVOCATION channel.

See Also:

Constant Field Values

(Unpublished)

LEVEL_PROTECTED

public static final int LEVEL_PROTECTED

Deprecated.

The value of level for entry/exit of protected and package scope methods on the CHANNEL_METHOD_INVOCATION channel.

See Also:

Constant Field Values

(Unpublished)

LEVEL_PRIVATE

public static final int LEVEL_PRIVATE

Deprecated.

The value of level for entry/exit of private scope methods on the CHANNEL_METHOD_INVOCATION channel.

See Also:

Constant Field Values

(Unpublished)

HIGHEST_VALID_LEVEL

public static final int HIGHEST_VALID_LEVEL

Deprecated.

The highest valid level.

See Also:

Constant Field Values

(Published)

m_ChannelLevels

protected int[] m_ChannelLevels

Deprecated.

The channels' levels.

(Unpublished)

m_TraceType

protected int m_TraceType

Deprecated.

The type of tracing.

Must be TRACETYPE_NONE, TRACETYPE_LOCAL, TRACETYPE_REMOTE, or TRACETYPE_BOTH.

(Unpublished)

m_Localizer

protected Localizer m_Localizer

Deprecated.

The Localizer used by this TraceLogger.

(Unpublished)

m_LocalStream

protected PrintWriter m_LocalStream

Deprecated.

The stream to which the local trace log is written.

(Unpublished)

m_File

protected File m_File

Deprecated.

The file to which the local trace log is written.

(Unpublished)

m_AutoFlushed

protected boolean m_AutoFlushed

Deprecated.

Whether the stream to which the local trace log is written is automatically flushed each time a trace is written to it.

(Unpublished)

m_DateLabel

protected String m_DateLabel

Deprecated.

The label for the trace log Date field.

(Unpublished)

m_ChannelLabel

protected String m_ChannelLabel

Deprecated.

The label for the trace log Channel field.

(Unpublished)

m_LevelLabel

protected String m_LevelLabel

Deprecated.

The label for the trace log Level field.

(Unpublished)

m_ServiceIdLabel

protected String m_ServiceIdLabel

Deprecated.

The label for the trace log Service Id field.

(Unpublished)

m_SessionIdLabel

protected String m_SessionIdLabel

Deprecated.

The label for the trace log Session Id field.

(Unpublished)

m_IdLabel

protected String m_IdLabel

Deprecated.

The label for the trace log Id field.

(Unpublished)

m_ClassnameLabel

protected String m_ClassnameLabel

Deprecated.

The label for the trace log Classname field.

(Unpublished)

m_PayloadLabel

protected String m_PayloadLabel

Deprecated.

The label for the trace log Payload field.

(Unpublished)

Constructor Detail

TraceLogger

public TraceLogger(Localizer localizer)
            throws IfsException

Deprecated.

Constructs a new TraceLogger.

The TraceLogger initially has LAST_REVERVED_CHANNEL + 1 channels. Each channel's level is DISABLED. Local tracing is sent to the standard error stream and is flushed after each trace request.

Parameters:

localizer - the Localizer for the TraceLogger. This is used to localize numbers and dates in the trace log, and to generate localized labels for trace log fields.

Throws:

IfsException - (IFS-19001) if localizer is null

(Unpublished)

Method Detail

initialize

protected final void initialize(int channelCount)
                         throws IfsException

Deprecated.

Initializes this TraceLogger.

Used by the constructor of TraceLogger and its subclasses.

Parameters:

channelCount - the desired number of trace channels

Throws:

IfsException - (IFS-11203) if channelCount is too small

(Unpublished)

getLocalizer

public final Localizer getLocalizer()
                             throws IfsException

Deprecated.

Gets the Localizer of this TraceLogger.

Returns:

the Localizer

Throws:

IfsException - if the operation fails

(Published)

getChannelCount

public final int getChannelCount()
                          throws IfsException

Deprecated.

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

(Published)

setLevel

public final void setLevel(int channel,
                           int level)
                    throws IfsException

Deprecated.

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

(Published)

setLevels

public final void setLevels(int level)
                     throws IfsException

Deprecated.

Sets the level of each channel.

Parameters:

level - the level

Throws:

IfsException - (IFS-11200) if the level is invalid

(Published)

setLevels

public final void setLevels(int[] levels)
                     throws IfsException

Deprecated.

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

(Published)

getLevel

public final int getLevel(int channel)
                   throws IfsException

Deprecated.

Gets the level of the specified channel.

Parameters:

channel - the channel number

Returns:

the level

Throws:

IfsException - (IFS-11201) if the channel is invalid

(Published)

getLevels

public final int[] getLevels()
                      throws IfsException

Deprecated.

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

(Published)

setTraceType

public final void setTraceType(int traceType)
                        throws IfsException

Deprecated.

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

(Published)

getTraceType

public final int getTraceType()
                       throws IfsException

Deprecated.

Gets the trace type.

Returns:

the trace type value

Throws:

IfsException - if the operation fails

(Published)

setLocalStream

public final void setLocalStream(PrintWriter writer)
                          throws IfsException

Deprecated.

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

(Published)

setLocalStream

public final void setLocalStream(File file)
                          throws IfsException

Deprecated.

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

(Published)

setAutoFlushed

public final void setAutoFlushed(boolean autoFlushed)
                          throws IfsException

Deprecated.

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

(Published)

isAutoFlushed

public final boolean isAutoFlushed()
                            throws IfsException

Deprecated.

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

(Published)

flush

public final void flush()
                 throws IfsException

Deprecated.

Flushes the stream to which the local trace log is written.

Throws:

IfsException - (IFS-11206) if the operation fails

(Published)

isTraced

public final boolean isTraced(int channel,
                              int level)
                       throws IfsException

Deprecated.

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

(Published)

trace

public void trace(int channel,
                  int level,
                  Long serviceId,
                  Long sessionId,
                  Long id,
                  String classname,
                  String payload)
           throws IfsException

Deprecated.

Processes a trace request.

The trace request is only written to the trace log if tracing is enabled for the specified channel and level.

Parameters:

channel - the channel number

level - the level

serviceId - the service id of the object performing the trace

sessionId - the session id of the object performing the trace, or 0 if the trace is requested by a service

id - the id of the object performing the trace, or 0 if the trace is requested by a service or session

classname - the classname of the object performing the trace

payload - a string containing any additional information to be placed in the trace log

Throws:

IfsException - (IFS-11201) if the channel is invalid

IfsException - (IFS-11207) if the operation otherwise fails

(Unpublished)

sendToStream

protected final void sendToStream(int channel,
                                  int level,
                                  Long serviceId,
                                  Long sessionId,
                                  Long id,
                                  String classname,
                                  String payload)
                           throws IfsException

Deprecated.

Writes the trace request to the local trace log.

Parameters:

channel - the channel number

level - the level

serviceId - the service id of the object performing the trace

sessionId - the session id of the object performing the trace, or 0 if the trace is requested by a service

id - the id of the object performing the trace, or 0 if the trace is requested by a service or session

classname - the classname of the object performing the trace

payload - a string containing any additional information to be placed in the trace log

Throws:

IfsException - (IFS-11205) if the operation fails

(Unpublished)

finalize

public void finalize()
              throws IfsException

Deprecated.

Finalizes this TraceLogger.

Overrides:

finalize in class Object

Throws:

IfsException - if the operation fails

(Unpublished)