Cisco CallManager 3.0 JTAPI Developer Guide
Cisco JTAPI Trace Logging
Downloads: This chapterpdf (PDF - 405.0KB) The complete bookPDF (PDF - 2.06MB) | Feedback

Cisco JTAPI Trace Logging

Table Of Contents

Cisco JTAPI Trace Logging

Introduction

Cisco Services Tracing API Hierarchy

Class Hierarchy

Interface Hierarchy

Class com.cisco.services.tracing

Cisco JTAPI Trace Logging Classes

BaseTraceWriter

Class Declaration

Description

Constructor Index

Method Index

Constructor Detail

Method Detail

ConsoleTraceWriter

Class Declaration

Description

Constructor Index

Method Index

Constructor Detail

Method Detail

LogFileTraceWriter

Class Declaration

Description

Field Index

Constructor Index

Method Index

Field Detail

Constructor Detail

Method Detail

OutputStreamTraceWriter

Class Declaration

Description

Constructor Index

Method Index

Constructor Detail

Method Detail

SyslogTraceWriter

Class Declaration

Description

Constructor Index

Method Index

Constructor Detail

Method Detail

TraceManagerFactory

Class Declaration

Description

Method Index

Method Detail

Interface com.cisco.services.tracing

Cisco JTAPI Trace Logging Interfaces

Conditional Trace

Interface Declaration

Description

Method Index

Method Detail

Trace

Interface Declaration

Description

Field Index

Method Index

Field Detail

Method Detail

TraceManager

Interface Declaration

Description

Method Index

Method Detail

TraceModule

Interface Declaration

Description

Method Index

Method Detail

UnconditionalTrace

Interface Declaration

Description

TraceWriter

Interface Declaration

Description

Method Index

Method Detail

TraceWriterManager

Interface Declaration

Description

Method Index

Method Detail


Cisco JTAPI Trace Logging


Introduction

The Cisco JTAPI implementation provides an exception tracing facility for use both in debugging your applications and in logging exceptions in the released application. Three main levels of trace are defined: WARNING, INFORMATIONAL and DEBUGGING. DEBUGGING represents the high level tracing. In addition, the DEBUGGING levels from specific JTAPI subareas can be selectively turned on or off. (Trace flags can be enabled or disabled using the jtprefs application or by editing the jtapi.ini file in the jdk 1.2 environments.) The message format is:

yyyy mmm dd hh:mm:ss TimeZone <-/+>hh:mm : 
%FACILITY-[SUBFACILITY-]SEVERITY-MNEMONIC:
Message-text

Use the trace logging classes and interfaces in conjunction with the JTAPI standard classes and the JTAPI extension interfaces and classes described in Chapter 2, "Cisco JTAPI Extensions" to create new applications for Cisco IP Telephony applications.

This chapter contains the following sections:

Cisco Services Tracing API Hierarchy

Class com.cisco.services.tracing

Interface com.cisco.services.tracing

Cisco Services Tracing API Hierarchy

Class Hierarchy

class java.lang.Object

class com.cisco.services.tracing.BaseTraceWriter

(implements com.cisco.services.tracing.TraceWriter)

class com.cisco.services.tracing.ConsoleTraceWriter

class com.cisco.services.tracing.LogFileTraceWriter

class com.cisco.services.tracing.OutputStreamTraceWriter
class com.cisco.services.tracing.SyslogTraceWriter
class com.cisco.services.tracing.TraceManagerFactory

Interface Hierarchy

interface com.cisco.services.tracing.Trace

interface com.cisco.services.tracing.ConditionalTrace

interface com.cisco.services.tracing.UnconditionalTrace

interface com.cisco.services.tracing.TraceManager

interface com.cisco.services.tracing.TraceModule

interface com.cisco.services.tracing.TraceWriter

interface com.cisco.services.tracing.TraceWriterManager

Class com.cisco.services.tracing

Cisco JTAPI Trace Logging Classes

Table 3-1 Cisco JTAPI Trace Logging Classes and Their Methods 

Cisco Trace Logging Classes
Method Names

BaseTraceWriter

close()

doClose()

doFlush()

doPrintln(java.lang.String)

flush()

getDescription()

getEnabled()

getName()

getTraceLevels()

println (java.lang.String, int)

setTraceLevels(int [])

toString()

ConsoleTraceWriter

doFlush()

doPrintln(java.lang.String, int)

main(java.lang.String[])

LogFileTraceWriter

doClose()

doFlush()

doPrintln(java.lang.String, int)

getCurrentFile()

getFileExtension()

getFileNameBase()

getMaxFiles()

getMaxFileSize()

OutputStreamTraceWriter

doClose()

doFlush()

doPrintln(java.lang.String, int)

getOutputStream()

SyslogTraceWriter

doClose()

doPrintln(java.lang.String, int)

main(java.lang.String[])

TraceManagerFactory

getModules()

registerModule(TraceModule)

registerModule(TraceModule, java.lang.String[], TraceWriterManager)

registerModule(TraceModule, TraceWriterManager)


BaseTraceWriter

java.lang.Object
  |
  +--com.cisco.services.tracing.BaseTraceWriter
        |
        +--com.cisco.services.tracing.BaseTraceWriter

public abstract class BaseTraceWriter
extends java.lang.Object
implements TraceWriter

Class Declaration

BaseTraceWriter

Description

This abstract class is useful for supplying a default, non-printing TraceWriter to a TraceWriterManager. This class must be extended to provide the functionality to trace to different streams. The doPrintln () method must be implemented by the extending class.

Constructor Index

BaseTraceWriter(int[], java.lang.String, java.lang.String) 

BaseTraceWriter with trace levels as passed in traceLevels in the array falling outside the range Trace. LOWEST_LEVEL and Trace.HIGHEST_LEVEL are ignored.


BaseTraceWriter(int, java.lang.String, java.lang.String)

BaseTraceWriter that traces all levels up to the maxTraceLevel. The trace level is maintained in the range [Trace.HIGHEST_LEVEL, Trace.LOWEST_LEVEL]

BaseTraceWriter(java.lang.String, java.lang.String) 

BaseTraceWriter that only traces the lowest level (i.e., severity level, Trace.LOWEST_LEVEL messages)

Method Index

close() 

Releases any resources associated by this TraceWriter

doClose() 

doFlush()

doPrintln(java.lang.String) 

Must be implemented by the various TraceWriters extending BaseTraceWriter to provide the specific tracing functionality

flush()

Forces output of any messages that have been printed using the println method

getDescription()

getEnabled()

Returns whether the println method will print anything or not

getName()

getTraceLevels()

println (java.lang.String, int)

This method prints the specified string followed by a carriage return. The concrete TraceWriter class will use the severity to block out messages from a particular stream.

setTraceLevels(int [])

Set the trace levels that will be traced by this TraceWriter

toString() 

Methods inherited from class java.lang.Object

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

Constructor Detail

BaseTraceWriter

protected BaseTraceWriter(int[] traceLevels,java.lang.String name,java.lang.String
description)

BaseTraceWriter that traces all levels up to the maxTraceLevel. The trace level is maintained in the range [Trace.HIGHEST_LEVEL, Trace.LOWEST_LEVEL].

Parameters

maxTraceLevel -

name -

description -

See Also

Trace

BaseTraceWriter

protected BaseTraceWriter(int maxTraceLevel,java.lang.String name,java.lang.String
description)

BaseTraceWriter that traces all levels up to the maxTraceLevel. The trace level is maintained in the range [Trace.HIGHEST_LEVEL, Trace.LOWEST_LEVEL]OutputStreamTraceWriter.

Parameters

name -

description -

See Also

Trace

BaseTraceWriter

protected BaseTraceWriter(java.lang.String name,java.lang.String description)

BaseTraceWriter which only traces the lowest level (i.e., severity level, Trace.LOWEST_LEVEL messages)

Parameters

name -

description -

See Also

Trace

Method Detail

close

public final void close()
Description copied from interface TraceWriter

Releases any resources associated by this TraceWriter

Specified by

The method close in interface TraceWriter

doClose

protected void doClose()

doFlush

protected void doFlush()

doPrintln

(java.lang.String message, int messageNumber) 

Must be implemented by the various TraceWriters extending BaseTraceWriter to provide the specific tracing functionality

flush

public final void flush()
Description copied from interface

TraceWriter

Forces output of any messages that have been printed using the println method

Specified by

The method flush in interface TraceWriter

getDescription

public final java.lang.String getDescription()
Specified by

The method getDescription in interface TraceWriter

Tags copied from interface

TraceWriter

Returns

a short description of this TraceWriter

getEnabled

public boolean getEnabled()
Description copied from interface TraceWriter

Returns whether or not the println method prints. A closed TraceWriter will always return false from this method.

Specified by

The method getEnabled in interface TraceWriter

Tags copied from interface

TraceWriter

Returns

true if this TraceWriter is enabled, false if not

getName

public final java.lang.String getName()
Specified by

The method getName in interface TraceWriter

Tags copied from interface

TraceWriter

Returns

the name of this TraceWriter

getTraceLevels

public final int[] getTraceLevels()
Specified by

The method getTraceLevels in interface TraceWriter

Tags copied from interface

TraceWriter

Returns

the array of trace levels that will be traced by this TraceWriter

println

public final void println(java.lang.String message, int severity)
Description copied from interface

TraceWriter

Prints the specified string followed by a carriage return. The concrete TraceWriter class will use the severity to block out messages from a particular stream. Each trace writer has a notion of the highest level trace it traces.

Specified by

The method println in interface TraceWriter

Tags copied from interface

TraceWriter

Parameters

message - the string to print

severity - of the trace

See Also

Trace

setTraceLevels

public final void setTraceLevels(int[] levels)
Description copied from interface

TraceWriter

Sets the trace levels that will be traced by this TraceWriter

Specified by

The method setTraceLevels in interface TraceWriter

Tags copied from interface

TraceWriter

Parameters

int[] - levels

See Also

Trace

toString

public final java.lang.String toString()
Overrides

The method toString in class java.lang.Object

ConsoleTraceWriter

java.lang.Object
  |
  +--com.cisco.services.tracing.BaseTraceWriter
        |
        +--com.cisco.services.tracing.ConsoleTraceWriter
public final class ConsoleTraceWriter
extends BaseTraceWriter

Class Declaration

ConsoleTraceWriter

Description

Supplies a console TraceWriter for tracing to System.out.

See Also

Trace

Constructor Index

ConsoleTraceWriter() 

Default constructor, traces all severity levels

ConsoleTraceWriter(int) 

Constructor that sets the maximum level to be traced

ConsoleTraceWriter(int[]) 

This constructs a ConsoleTraceWriter with an array of trace levels. It only traces with the severity included by the trace level array.

Method Index

doFlush() 

doPrintln(java.lang.String, int) 

Must be implemented by the various TraceWriters extending BaseTraceWriter to provide the specific tracing functionality

main(java.lang.String[]) 

Methods inherited from class com.cisco.services.tracing.BaseTraceWriter

close, doClose, flush, getDescription, getEnabled, getName, getTraceLevels, println,
setTraceLevels,toString

Methods inherited from class java.lang.Object

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

Constructor Detail

ConsoleTraceWriter

public ConsoleTraceWriter()

Default constructor, traces all severity levels

ConsoleTraceWriter

public ConsoleTraceWriter(int maxTraceLevel)

Constructor that sets the maximum level to be traced

Parameters

maxTraceLevel -

See Also

Trace

ConsoleTraceWriter

public ConsoleTraceWriter(int[] traceLevels)

This constructs a ConsoleTraceWriter with an array of trace levels. It only traces with the severity in the trace level array are traced.

Parameters

int - [] traceLevels

See Also

Trace

Method Detail

doFlush

protected final void doFlush()
Overrides

The method doFlush in class BaseTraceWriter

doPrintln

protected final void doPrintln(java.lang.String message, int messageNumber)
Description copied from class

BaseTraceWriter

Must be implemented by the various TraceWriters extending BaseTraceWriter to provide the specific tracing functionality

Overrides

The method doPrintln in class BaseTraceWriter

main

public static void main(java.lang.String[] args)

LogFileTraceWriter

java.lang.Object
  |
  +--com.cisco.services.tracing.BaseTraceWriter
        |
        +--com.cisco.services.tracing.LogFileTraceWriter

public final class LogFileTraceWriter
extends BaseTraceWriter

Class Declaration

LogFileOutputStream

Description

This class extends the BaseTraceWriter class to implement a TraceWriter that writes to a set of log files, rotating among them as each becomes filled to a specified capacity and stores them in a specified directory.

Each of the log files is named according to a pattern controlled by three properties, CurrentFile, FileNameBase, and FileExtension. The CurrentFile property determines which log file, by ordinal number, is being written at present, the FileNameBase property determines the prefix of each log file name, and the FileExtension property determines the suffix (e.g., ".txt").

From these properties, log files are named FileNameBase LeadingZeroPadding CurrentFile.FileExtension. The CurrentFile property takes on a value from 1 to the value of the MaxFiles property. Note that the CurrentFile property, when converted to a String, is padded with leading zeroes depending on the values of the MaxFiles and CurrentFile properties.

Where the log files are stored is determined by the path, dirNameBase, useSameDir. If a path is not specified, the current path is used as default. If a dirNameBase is not specified, it write log files in the path. Depending upon whether useSameDir is true or false, files are written to the same directory or a new directory, each time an instance of LogFileTraceWriter is created. In case new directories are being made each time, the directory name will consist of the dirNameBase and a number, separated by an '_'. The number is one more than the greatest number associated with directories with the same dirNameBame in the path. While specifying the path, you may use either a "/" or "\\", but not "\."

The LogFileTraceWriter keeps track of how many bytes have been written to the current log file. When that number grows within approximately LogFileTraceWriter.ROLLOVER_THRESHOLD bytes, tracing continues to the next file, which is either CurrentFile +1 if CurrentFile is not equal to MaxFiles, or 1 if CurrentFile is equal to MaxFiles.


Note All properties of this class are specified in the constructor; there is no way to change them dynamically. Caveat: If two instances of LogFileTraceWriter are created with the same path and dirNameBase, and useSameDir is true, they may write to the same file.


Example

The following code instantiates a LogFileTraceWriter that will create log files called "MyLog01.log" through "MyLog12.log." Each file will grow to approximately 100K bytes in size before the next file is created.

LogFileTraceWriter out = new LogFileTraceWriter ("MyLog", "log", 12, 100 * 1024); 

will create a log file TraceWriter which will rotate traces to 12 files from Mylog01.log and Mylog12.log with a file size of 100 KB. By default the tracing is set to the HIGHEST_LEVEL

Example

The following code constructs a LogFileTraceWriter which stores the log files in the path "c:/LogFiles" in a sub directory, "Run."

LogFileTraceWriter out = new LogFileTraceWriter ( "c:/logFiles", "Run", "MyLog", "log",
12, 100*1024, true ); 
See Also

Trace

Field Index

DEFAULT_FILE_NAME_BASE 

DEFAULT_FILE_NAME_EXTENSION 

DIR_BASE_NAME_NUM_SEPERATOR 

MIN_FILE_SIZE 

MIN_FILES 

ROLLOVER_THRESHOLD 

Constructor Index

LogFileTraceWriter(java.lang.String, java.lang.String, int, int)

Default constructor for LogFileTraceWriter that rotates among an arbitrary number of files with tracing for all levels

LogFileTraceWriter(java.lang.String, java.lang.String, java.lang.String,
java.lang.String, int, int, boolean)

Default constructor for LogFileTraceWriter that rotates among an arbitrary number of files with tracing for all levels

LogFileTraceWriter(java.lang.String, java.lang.String, java.lang.String,
 java.lang.String, int, int, int, boolean) 

Constructs a LogFileTraceWriter that rotates among an arbitrary number of files storing them in a specified directory

Method Index

doClose() 

Closes this OutputStream

doFlush() 

doPrintln(java.lang.String, int) 

Must be implemented by the various TraceWriters extending BaseTraceWriter to provide the specific tracing functionality

getCurrentFile() 

Returns the CurrentFile property

getFileExtension() 

Returns the FileExtension property

getFileNameBase() 

Returns the FileNameBase property

getMaxFiles() 

Returns the MaxFiles property

getMaxFileSize() 

Returns the MaxFileSize property

Methods inherited from class com.cisco.services.tracing.BaseTraceWriter

close, flush, getDescription, getEnabled, getName, getTraceLevels,
println,setTraceLevels, toString

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_FILE_NAME_BASE

public static final java.lang.String DEFAULT_FILE_NAME_BASE

DEFAULT_FILE_NAME_EXTENSION

public static final java.lang.String DEFAULT_FILE_NAME_EXTENSION

DIR_BASE_NAME_NUM_SEPERATOR

public static final char DIR_BASE_NAME_NUM_SEPERATOR

MIN_FILE_SIZE

public static final int MIN_FILE_SIZE

MIN_FILES

public static final int MIN_FILES

ROLLOVER_THRESHOLD

public static final int ROLLOVER_THRESHOLD

Constructor Detail

LogFileTraceWriter

public LogFileOutputStream((java.lang.String path, java.lang.String dirNameBase,
java.lang.String fileNameBase, java.lang.String fileNameExtension, int maxFiles,
int maxFileSize, boolean useSameDir)
throws java.io.IOException

This is a default constructor for LogFileTraceWriter that rotates among an arbitrary number of files with tracing for all levels. Since a path and Directory Base name is not specified, it writes the files to the current directory without any sub directories.

Parameters

fileNameBase -

fileNameExtension -

maxFiles -

maxFileSize -

LogFileTraceWriter

public LogFileTraceWriter(java.lang.String path, java.lang.String dirNameBase,
java.lang.String fileNameBase, java.lang.String fileNameExtension, int maxFiles,
int maxFileSize, boolean useSameDir)
throws java.io.IOException

Default constructor for LogFileTraceWriter that rotates among an arbitrary number of files with tracing for all levels

Parameters

path -

dirNameBase -

fileNameBase -

fileNameExtension -

maxFiles -

maxFileSize -

useSameDir -

LogFileTraceWriter

public LogFileTraceWriter(java.lang.String path, java.lang.String dirNameBase,
java.lang.String fileNameBase, java.lang.String fileNameExtension, int maxFiles,
int maxFileSize, int maxTraceLevel, boolean useSameDir)
throws java.io.IOException

Constructs a LogFileTraceWriter that rotates among an arbitrary number of files storing them in a specified directory.

Parameters

path -

dirNameBase -

fileNameBase -

fileNameExtension -

maxFiles -

maxFileSize -

maxTraceLevel -

useSameDir -

Method Detail

doClose

protected void doClose()

Closes this OutputStream. Any log file that is currently open will be closed as well

Overrides

The method doClose in class BaseTraceWriter

doFlush

protected void doFlush()
Overrides

The method doFlush in class BaseTraceWriter

doPrintln

protected void doPrintln(java.lang.String message, int messageNumber)
Description copied from class

BaseTraceWriter

Must be implemented by the various TraceWriters extending BaseTraceWriter to provide the specific tracing functionality

Overrides

The method doPrintln in class BaseTraceWriter

getCurrentFile

public int getCurrentFile()

Returns the CurrentFile property

Returns

The CurrentFile property

getFileExtension

public java.lang.String getFileExtension()

Returns the FileExtension property

Returns

the FileExtension property

getFileNameBase

public java.lang.String getFileNameBase()

Returns the FileNameBase property

Returns

the FileNameBase property

getMaxFiles

public int getMaxFiles()

Returns the MaxFiles property

Returns

the MaxFiles property

getMaxFileSize

public int getMaxFileSize()

Returns the MaxFileSize property

Returns

the MaxFileSize property

OutputStreamTraceWriter

java.lang.Object
  |
  +--com.cisco.services.tracing.OutputStreamTraceWriter

public final class OutputStreamTraceWriter
extends BasicTraceWriter
implements TraceWriter

Class Declaration

OutputStreamTraceWriter

Description

OutputStreamTraceWriter wraps an output stream in a TraceWriter. This simplifies adding custom tracing classes that can co-exist with JTAPI TraceWriters.

Constructor Index

OutputStreamTraceWriter(int, java.io.OutputStream)

Default constructor which is autoflushing

OutputStreamTraceWriter(int, java.io.OutputStream, boolean)

Create an OutputStreamTraceWriter

Method Index

doClose() 

doFlush() 

doPrintln(java.lang.String, int) 

Must be implemented by the various TraceWriters extending BaseTraceWriter to provide the specific tracing functionality

getOutputStream() 

Methods inherited from class com.cisco.services.tracing.BaseTraceWriter

close, flush, getDescription, getEnabled, getName, getTraceLevels, println,
setTraceLevels, toString

Methods inherited from class java.lang.Object

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

Constructor Detail

OutputStreamTraceWriter

public OutputStreamTraceWriter(int maxTraceLevel,java.io.OutputStream outputStream, 
boolean autoFlush)

Create an OutputStreamTrace Writer

Parameters

maxTraceLevel -

See Also

Trace

OutputStreamTraceWriter

public OutputStreamTraceWriter(int maxTraceLevel,java.io.OutputStream outputStream,
boolean autoFlush)

Default constructor which is autoflushing

Method Detail

doClose

protected void doClose()
Overrides

The method doClose in class BaseTraceWriter

doFlush

protected void doFlush()
Overrides

The method doFlush in class BaseTraceWriter

doPrintln

public void println(java.lang.String message)
Description copied from class

BaseTraceWriter

Must be implemented by the various TraceWriters extending BaseTraceWriter to provide the specific tracing functionality

Overrides

The method doPrintln in class BaseTraceWriter

getOutputStream

public java.io.OutputStream getOutputStream()
Returns

the output stream associated with the TraceWriter

SyslogTraceWriter

java.lang.Object
  |
  +--com.cisco.services.tracing.BaseTraceWriter
        |
        +--com.cisco.services.tracing.SyslogTraceWriter

public final class SyslogTraceWriter
extends BaseTraceWriter

Class Declaration

SyslogTraceWriter

Description

SyslogTraceWriter refines the BaseTraceWriter to allow tracing to syslog. Cisco syslog specification calls for sending low level traces to a syslog collector in the form of UDP messages. No buffering is done in this TraceWriter. The SyslogTraceWriter makes an exception to the println() method in that it places a '\0' instead of a System specified line separator to terminate the message packet.

Constructor Index

SyslogTraceWriter(int, java.lang.String) 

Default SyslogTraceWriter with a max trace level of INFORMATIONAL

SyslogTraceWriter(int, java.lang.String, int) 

SyslogTraceWriter with max trace level specified

SyslogTraceWriter(int, java.lang.String, int[]) 

SyslogTraceWriter which takes an array of trace levels.

Method Index

doClose() 

Closes the socket

doPrintln(java.lang.String, int) 

The SyslogTraceWriter makes an exception to the println() method in that it places a '\0' instead of a System specified line separator to terminate the message packet.

main(java.lang.String[]) 

Methods inherited from class com.cisco.services.tracing.BaseTraceWriter

close, doFlush, flush, getDescription, getEnabled, getName, getTraceLevels, println,
setTraceLevels, toString

Methods inherited from class java.lang.Object

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

Constructor Detail

SyslogTraceWriter

public SyslogTraceWriter (int, java.lang.String collector)

Default SyslogTraceWriter with a max trace level of INFORMATIONAL

See Also

Trace

SyslogTraceWriter

public SyslogTraceWriter(int port, java.lang.String collector, int maxTraceLevel)

SyslogTraceWriter with max trace level specified

See Also

Trace

SyslogTraceWriter

public SyslogTraceWriter(int port, java.lang.String collector, int[] traceLevels)

SyslogTraceWriter which takes an array of trace levels

See Also

Trace

Method Detail

doClose

public void doClose()

Closes the socket

Overrides

The method doClose in class BaseTraceWriter

doPrintln

protected void doPrintln(java.lang.String message, int messageNumber)

The SyslogTraceWriter makes an exception to the println() method in that it places a '\0' instead of a System specified line separator to terminate the message packet. The portion of the message after a '\r' or '\n' is ignored.

Overrides

The method doPrintln in class BaseTraceWriter

main

public static void main(java.lang.String[] args)

TraceManagerFactory

java.lang.Object
   |
   +----com.cisco.services.tracing.TraceManagerFactory

public class TraceManagerFactory 
extends Object 

Class Declaration

TraceManagerFactory

Description

The TraceManagerFactory class is a class by which applications obtain a TraceManager object. The TraceModule passed in the constructor is registered in a list. The list can be enumerated using the getModules() method.

Method Index

getModules() 

Returns an enumeration of the TraceModules registered with this factory

registerModule(TraceModule) 

Returns an instance of a TraceManager object

registerModule(TraceModule, java.lang.String[], TraceWriterManager)

Returns an instance of a TraceManager object

registerModule(TraceModule, TraceWriterManager)

Returns an instance of a TraceManager object

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, to String, wait, wait
wait

Method Detail

getModules

public static java.util.Enumeration getModules()

This method returns an enumeration of the TraceModules registered with this factory.

registerModule

public static TraceManager registerModule(TraceModule module)

This method returns an instance of a TraceManager object. The contained TraceWriterManager will not have any default Trace Writers.

registerModule

public static TraceManager registerModule(TraceModule module, java.lang.String[]
subFacilities, TraceWriterManager traceWriterManager)

This method returns an instance of a TraceManager object. The trace output will be redirected to the TraceWriterManager object specified.

registerModule

public static TraceManager registerModule(TraceModule module, TraceWriterManager
traceWriterManager)

This method returns an instance of a TraceManager object. The trace output will be redirected to the TraceWriterManager object specified.

Interface com.cisco.services.tracing

Cisco JTAPI Trace Logging Interfaces

Table 3-2 Cisco JTAPI TraceLogging Interfaces and Their Methods 

Cisco Trace Logging Interfaces
Method Names

Trace

getName()

isEnabled()

print(Object)

print(String)

print(String, Object)

print(String, String)

println(Object)

println(String)

println(String, Object)

println(String, String)

setDefaultMnemonic(String)

TraceManager

disable()

enable()

TraceManager

 

TraceManager

addSubFacilities(java.lang.String[])

addSubFacility(java.lang.String)

disableAll()

disableTimeStamp()

enableAll()

enableTimeStamp()

getConditionalTrace(int)

getConditionalTrace(java.lang.String, int)

getName()

getSubFacilities()

getTraces()

getTraceWriterManager()

getUnconditionalTrace(int)

getUnconditionalTrace(java.lang.String, int)

removeTrace(Trace)

setSubFacilities(java.lang.String[])

setSubFacility(java.lang.String)

setTraceWriterManager(TraceWriterManager)

TraceModule

getTraceManager()

getTraceModuleName()

UnconditionalTrace

close()

flush()

getDescription()

getEnabled()

getName()

getTraceLevels()

println(java.lang.String, int)

setTraceLevels(int[])

TraceWriterManager

addTraceWriter(TraceWriter)

getTraceWriters()

removeTraceWriter(TraceWriter traceWriter)

setTraceWriters(TraceWriter[] traceWriters)


Conditional Trace

public interface ConditionalTrace
extends Trace

Interface Declaration

Conditional Trace

Description

The ConditionalTrace interface extends the Trace interface and defines the methods that allow enabling and disabling of tracing for this particular condition.

Typically, applications would obtain one ConditionalTrace object per each condition that they need to trace under certain circumstances but not always (e.g., AUDIT, INFO, etc.).

Fields inherited from interface com.cisco.services.tracing.Trace

ALERTS, ALERTS_TRACE_NAME, CRITICAL, CRITICAL_TRACE_NAME, DEBUGGING, DEBUGGING_TRACE_NAME, EMERGENCIES, EMERGENCIES_TRACE_NAME, ERROR, ERROR_TRACE_NAME, HIGHEST_LEVEL, INFORMATIONAL, INFORMATIONAL_TRACE_NAME, LOWEST_LEVEL, NOTIFICATION, NOTIFICATION_TRACE_NAME, WARNING, WARNING_TRACE_NAME

Method Index

disable() 

Disables this condition for tracing

enable() 

Enables this condition for tracing

Methods inherited from interface com.cisco.services.tracing.Trace

getName, getType, isEnabled, println, println, println, println, setDefaultMnemonic

Method Detail

disable

public void disable()

Disables this condition for tracing

enable

public void enable()

Enables this condition for tracing

Trace

public interface Trace 

Interface Declaration

Trace

Description

The Trace interface defines the methods that allow application tracing. Trace also defines the standard trace types as specified by SyslogTrace Logging.Syslog currently defines 8 levels of trace. The severity of the message is indicated in the trace as a number ranging between [0-7] (0 and 7 included). Currently 7 is HIGHEST_LEVEL and 0 is the LOWEST_LEVEL trace. All 8 levels are predefined here as static int types for reference in tracing sub-system implementations.

The severities traced are as follows:

0 = EMERGENCIES—System unusable

1 = ALERTS —Immediate action needed

2 = CRITICAL —Critical conditions

3 = ERROR —Error conditions

4 = WARNING —Warning conditions

5 = NOTIFICATION —Normal but significant condition

6 = INFORMATIONAL —Informational messages only

7 = DEBUGGING —Debugging messages

Field Index

ALERTS 

The application will continue working on the tasks but all functions may not be operational (one or more devices in the list are not accessible but others in the list can be accessed).

Syslog severity level = 1

ALERTS_TRACE_NAME 

String descriptor for ALERTS trace level

CRITICAL 

A critical failure, the application can not accomplish the tasks required due to this failure (e.g., the app can't open the database to read the device list).

Syslog severity level = 2

CRITICAL_TRACE_NAME 

String descriptor for CRITICAL trace level

DEBUGGING 

Very detailed information regarding errors or processing status that is only generated when DEBUG

mode has been enabled

Syslog severity level = 7

DEBUGGING_TRACE_NAME 

String descriptor for the DEBUGGING trace level

EMERGENCIES 

Emergency situation, a system shutdown is necessary

Syslog severity level = 0

EMERGENCIES_TRACE_NAME 

String descriptor for EMERGENCIES trace level

ERROR 

An error condition of some kind has occurred and the user needs to understand the nature of that failure

Syslog severity level = 3

ERROR_TRACE_NAME 

String descriptor for ERROR trace level

HIGHEST_LEVEL 

The highest trace level, currently this is DEBUGGING with a trace level of 7

INFORMATIONAL 

Information of some form not relating to errors, warnings, audit, or debug

Syslog severity level =6

INFORMATIONAL_TRACE_NAME 

String descriptor for INFORMATIONAL trace level

LOWEST_LEVEL 

The lowest trace level, currently this is EMERGENCIES with a trace level of 0

NOTIFICATION 

Notification denotes a normal but significant condition

Syslog severity level = 5

NOTIFICATION_TRACE_NAME 

String descriptor for NOTIFICATION trace level

WARNING 

Warning that a problem of some form exists but is not keeping the application from completing its tasks

Syslog severity level = 4

WARNING_TRACE_NAME 

String descriptor for WARNING trace level

Method Index

getName()

Returns the name of this Trace object

getType() 

Returns the type of trace

isEnabled() 

Returns the state of this Trace object

println(java.lang.Object) 

Prints the string returned by the Object.toString() method and terminates the line as defined by the system

println(java.lang.String) 

Prints a message in the same format as Trace.print() and terminates the line as defined by the system

println(java.lang.String, java.lang.Object) 

Prints the string returned by the Object.toString() method and terminates the line as defined by the system

println(java.lang.String, java.lang.String) 

Prints a message in the same format as Trace.print() and terminates the line as defined by the system

setDefaultMnemonic(java.lang.String) 

Sets a default mnemonic for all messages printed out to this trace

Field Detail

ALERTS

public static final int ALERTS

The application will continue working on the tasks but all functions may not be operational (one or more devices in the list are not accessible but others in the list can be accessed)

Syslog severity level = 1

ALERTS_TRACE_NAME

public static final java.lang.String ALERTS_TRACE_NAME

String descriptor for ALERTS trace level

CRITICAL

public static final int CRITICAL

A critical failure, the application can not accomplish the tasks required due to this failure (e.g., the app can't open the database to read the device list).

Syslog severity level = 2

CRITICAL_TRACE_NAME

public static final java.lang.String CRITICAL_TRACE_NAME

String descriptor for CRITICAL trace level

DEBUGGING

public static final int DEBUGGING

Very detailed information regarding errors or processing status that is only generated when DEBUG mode has been enabled

Syslog severity level = 7

DEBUGGING_TRACE_NAME

public static final java.lang.String DEBUGGING_TRACE_NAME

String descriptor for the DEBUGGING trace level

EMERGENCIES

public static final int EMERGENCIES

Emergency situation, a system shutdown is necessary

Syslog severity level = 0

EMERGENCIES_TRACE_NAME

public static final java.lang.String EMERGENCIES_TRACE_NAME

String descriptor for EMERGENCIES trace level

ERROR

public static final int ERROR

An error condition of some kind has occurred and the user needs to understand the nature of that failure

Syslog severity level = 3

ERROR_TRACE_NAME

public static final java.lang.String ERROR_TRACE_NAME

String descriptor for ERROR trace level

HIGHEST_LEVEL

public static final int HIGHEST_LEVEL

The highest trace level, currently this is DEBUGGING with a trace level of 7

INFORMATIONAL

public static final int INFORMATIONAL

Information of some form not relating to errors, warnings, audit, or debug

Syslog severity level =6

INFORMATIONAL_TRACE_NAME

public static final java.lang.String INFORMATIONAL_TRACE_NAME

String descriptor for INFORMATIONAL trace level

LOWEST_LEVEL

public static final int LOWEST_LEVEL

The lowest trace level, currently this is EMERGENCIES with a trace level of 0

NOTIFICATION

public static final int NOTIFICATION

Notification denotes a normal but significant condition

Syslog severity level = 5

NOTIFICATION_TRACE_NAME

public static final java.lang.String NOTIFICATION_TRACE_NAME

String descriptor for NOTIFICATION trace level

WARNING

public static final int WARNING

Warning that a problem of some form exists but is not keeping the application from completing its tasks

Syslog severity level = 4

WARNING_TRACE_NAME

public static final java.lang.String WARNING_TRACE_NAME

String descriptor for WARNING trace level

Method Detail

getName

public java.lang.String getName()

Returns the name of this Trace object

Returns

the name of this Trace object

getType

public int getType()

Returns the type of trace

Returns

the trace severity as specified in Syslog. DEBUGGING, INFORMATIONAL, WARNING, etc.

isEnabled

public boolean isEnabled()

This method returns the state of this Trace object. By default, Trace objects are enabled, that is, the print() and println() methods will always trace. The state may not be changed through this interface, however, this object may implement additional interfaces that allow the state to be changed.

See Also

ConditionalTrace

println

public void println(java.lang.Object object)

Prints the string returned by the Object.toString() method and terminates the line as defined by the system

Parameters

object - the object to be printed

println

public void println(java.lang.String message)

Prints a message in the same format as Trace.print() and terminates the line as defined by the system

Parameters

message - the message to be printed

println

public void println(java.lang.String mnemonic, java.lang.Object object)

Prints the string returned by the Object.toString() method and terminates the line as defined by the system

Parameters

object - the object to be printed

mnemonic - the mnemonic mapped to message to be printed

println

public void println(java.lang.String mnemonic, java.lang.String message)

Prints a message in the same format as Trace.print() and terminates the line as defined by the system

Parameters

message - the message to be printed

mnemonic - the mnemonic mapped to message to be printed

setDefaultMnemonic

public void setDefaultMnemonic(java.lang.String mnemonic)

Sets a default mnemonic for all messages printed out to this trace

Parameters

mnemonic, - a mnemonic string

TraceManager

public interface TraceManager 

Interface Declaration

TraceManager

Description

The TraceManager interface defines the methods that allow applications trace management.

Typically, an application obtains only one TraceManager object. All Trace objects are created by default: Predefined Trace in accordance with Syslog definitions are:

ContitionalTraces:

INFORMATIONAL, DEBUGGING, NOTIFICATION, WARNING

UnconditionalTraces:

ERROR, CRITICAL, ALERTS, EMERGENCIES

Facilities/Sub-Facilities

Facility

The code consists of two or more uppercase letters that indicate the facility to which the message refers. A facility can be a hardware device, a protocol, or a module of the system software.

SubFacility

A code consisting of two or more uppercase letters that indicate the sub-facility to which the message refers. A sub-facility can be a hardware device component, a protocol unit, or a sub-module of the system software.

By default all 8 Conditional and Unconditional Traces are created for the Facility and 8 for each of the subFacilities. In order to use the DEBUGGING trace for the parent FACILITY, for example, the application needs to use the getConditionalTrace("DEBUGGING") method of this object.

In order to use the DEBUGGING trace for the SUBFACILITY, for example, the application needs to use the getConditionalTrace(

SUBFACILITY + "_" + "DEBUGGING" ) method of this object or use the getConditionalTrace

( SUBFACILITY , "DEBUGGING" ) method.

System wide TraceWriterManager is set through the setTraceWriterManager method provided by this interface.

The Trace Manager object also allows the application to enable or disable tracing for all trace through the enableAll() and disableAll() methods.

Method Index

addSubFacilities(java.lang.String[]) 

Sets a set of subFacilities for this TraceManager/Facility

addSubFacility(java.lang.String) 

Adds a single subFacility for this TraceManager/Facility

disableAll() 

Disables tracing for all Trace objects managed by this TraceManager

disableTimeStamp() 

Disables prefixing a time stamp for every message printed by this TraceManager

enableAll()

Enables tracing for all Trace objects managed by this TraceManager

enableTimeStamp() 

Enables prefixing a time stamp for every message printed by this TraceManager

getConditionalTrace(int) 

Creates a new ConditionalTrace object or obtains an existing ConditionalTrace object for this condition

getConditionalTrace(java.lang.String, int) 

Creates a new ConditionalTrace object or obtains an existing ConditionalTrace object for this condition and subFacility

getName() 

Returns the Facility name for this TraceManager

getSubFacilities() 

Returns the subFacility names for this TraceManager/Facility

getTraces()

Returns an enumeration of the Trace objects managed by this TraceManager

getTraceWriterManager()

Returns the TraceWriter used by this TraceManager

getUnconditionalTrace(int) 

Creates a new UnconditionalTrace object or obtains an existing UnconditionalTrace object for this condition

getUnconditionalTrace(java.lang.String, int) 

Creates a new UnconditionalTrace object or obtains an existing UnconditionalTrace object for this condition and subFacility

removeTrace(Trace) 

Removes a Trace object given an object

setSubFacilities(java.lang.String[]) 

Deprecated and replaced with TraceManager.addSubFacilities method

setSubFacility(java.lang.String) 

Deprecated and replaced with TraceManager.addSubFacility method

setTraceWriterManager(TraceWriterManager) 

Sets the TraceWriter to be used by this TraceManager

Method Detail

addSubFacilities

public void addSubFacilities(java.lang.String[] names)

Sets a set of subFacilities for this TraceManager/Facility

addSubFacility

public void addSubFacility(java.lang.String name)

Adds a single subFacility for this TraceManager/Facility

disableAll

public void disableAll()

Disables tracing for all Trace objects managed by this TraceManager

disableTimeStamp

public void disableTimeStamp()

Disables prefixing a time stamp for every message printed by this TraceManager

enableAll

public void enableAll()

Enables tracing for all Trace objects managed by this TraceManager

enableTimeStamp

public void enableTimeStamp()

Enables prefixing a time stamp for every message printed by this TraceManager

getConditionalTrace

public ConditionalTrace getConditionalTrace(int severity)

Creates a new ConditionalTrace object or obtains an existing ConditionalTrace object for this condition

getConditionalTrace

public ConditionalTrace getConditionalTrace(java.lang.String subFacility, int severity)

Creates a new ConditionalTrace object or obtains an existing ConditionalTrace object for this condition and subFacility

getName

public java.lang.String getName()

Returns the Facility name for this TraceManager

getSubFacilities

public java.lang.String[] getSubFacilities()

Returns the subFacility names for this TraceManager/Facility

getTraces

public java.util.Enumeration getTraces()

Returns an enumeration of the Trace objects managed by this TraceManager

getTraceWriterManager

public TraceWriterManager getTraceWriterManager()

Returns the TraceWriter used by this TraceManager

getUnconditionalTrace

public UnconditionalTrace getUnconditionalTrace(int severity)

Creates a new UnconditionalTrace object or obtains an existing UnconditionalTrace object for this condition

getUnconditionalTrace

public UnconditionalTrace getUnconditionalTrace(java.lang.String subFacility,
int severity)

Creates a new UnconditionalTrace object or obtains an existing UnconditionalTrace object for this condition and subFacility

removeTrace

public void removeTrace(Trace tc)

Removes a Trace object given an object

setSubFacilities

public void setSubFacilities(java.lang.String[] names)

Deprecated and replaced with TraceManager.addSubFacilities method

Sets a set of subFacilities for this TraceManager/Facility

setSubFacility

public void setSubFacility(java.lang.String name)

Deprecated and replaced with TraceManager.addSubFacility method

Adds a single subFacility for this TraceManager/Facility

setTraceWriterManager

public void setTraceWriterManager(TraceWriterManager twm)

Sets the TraceWriter to be used by this TraceManager

TraceModule

public interface TraceModule 

All Known Subinterfaces

CiscoJtapiPeer

Interface Declaration

TraceModule

Description

The TraceModule interface serves two purposes. First, it allows applications to discover the TraceManager object used by other packages that they use. Second, applications that register with the TraceManagerFactory must identify themselves by implementing this interface.

Method Index

getTraceManager() 

Returns the TraceManager that an object is using for tracing

getTraceModuleName() 

Returns the module name

Method Detail

getTraceManager

public TraceManager getTraceManager()

Returns the TraceManager that an object is using for tracing

getTraceModuleName

public String getTraceModuleName()

Returns the module name

UnconditionalTrace

public interface UnconditionalTrace 
extends Trace 

Interface Declaration

UnconditionalTrace

Description

The UnconditionalTrace interface extends the Trace interface. Note that because this object extends Trace, its state is enabled by default and it may not be changed.

Typically, applications would obtain one UnconditionalTrace object per each condition that they need to trace always under any circumstances (e.g., ERROR, FATAL, etc.).

Fields inherited from interface com.cisco.services.tracing.Trace

ALERTS, ALERTS_TRACE_NAME, CRITICAL, CRITICAL_TRACE_NAME, DEBUGGING, 
DEBUGGING_TRACE_NAME, EMERGENCIES, EMERGENCIES_TRACE_NAME, ERROR, ERROR_TRACE_NAME, 
HIGHEST_LEVEL, INFORMATIONAL, INFORMATIONAL_TRACE_NAME, LOWEST_LEVEL, NOTIFICATION, 
NOTIFICATION_TRACE_NAME, WARNING, WARNING_TRACE_NAME

Methods inherited from interface com.cisco.services.tracing.Trace

getName, getType, isEnabled, println, println, println, println, setDefaultMnemonic

TraceWriter

public interface TraceWriter 

Interface Declaration

TraceWriter

Description

The TraceWriter interface abstracts the details of trace message output. The TraceWriter uses its enabled method to advertise whether or not the print and println methods will have any effect. Users of TraceWriter should use the value returned by the getEnabled method as an indication of whether they should invoke the print and println methods at all.

Method Index

close() 

Releases any resources associated by this TraceWriter

flush() 

Forces output of any messages that have been printed using the println method

getDescription() 
getEnabled() 

Returns whether the println method will print anything or not

getName() 
getTraceLevels() 

println(java.lang.String, int)

This method prints the specified string followed by a carriage return. The concrete TraceWriter class will use the severity to block out messages from a particular stream.

setTraceLevels(int[]) 

Set the trace levels that will be traced by this TraceWriter

Method Detail

close

public void close()

Releases any resources associated by this TraceWriter

flush

public void flush()

Forces output of any messages that have been printed using the println method

getDescription

public java.lang.String getDescription()
Returns

a short description of this TraceWriter

getEnabled

public boolean getEnabled()

This method returns whether the println method will print anything or not. A closed TraceWriter will always return false from this method.

Returns

true if this TraceWriter is enabled, false if not

getName

public java.lang.String getName()
Returns

the name of this TraceWriter

getTraceLevels

public int[] getTraceLevels()
Returns

the array of trace levels that will be traced by this TraceWriter

println

public void println(java.lang.String message, int severity)

This method prints the specified string followed by a carriage return. The concrete TraceWriter class will use the severity to block out messages from a particular stream. Each trace writer has a notion of the highest level trace it traces.

Parameters

message - the string to print

severity - of the trace

See Also

Trace

setTraceLevels

public void setTraceLevels(int[] levels)

set the trace levels that will be traced by this TraceWriter

Parameters

int[] - levels

See Also

Trace

TraceWriterManager

public interface TraceWriterManager 
extends TraceWriter 

Interface Declaration

TraceWriterManager

Description

TraceWriterManager contains the list of TraceWriter objects that JTAPI uses to implement the tracing. The list is populated at startup from the switches in jtapi.ini. A LogFileTraceWriter, a ConsoleTraceWriter, and a SyslogTraceWriter are available. Users can override the JTAPI TraceWriters by setting a user implemented TraceWriter[] or adding to the existing TraceWriters. This makes it possible to add other TraceWriters that can function along with existing JTAPI tracing.

Method Index

addTraceWriter(TraceWriter) 

Add another TraceWriter to the array

getTraceWriters()

removeTraceWriter(TraceWriter) 

Remove the TraceWriter from the array in the manager

setTraceWriters(TraceWriter[]) 

Implementations can use this method to override or enhance the JTAPI provided TraceWriters

Methods inherited from interface com.cisco.services.tracing.TraceWriter

close, flush, getDescription, getEnabled, getName, getTraceLevels, println,
setTraceLevels

Method Detail

addTraceWriter

public void addTraceWriter(TraceWriter traceWriter)

Add another TraceWriter to the array

Parameters

TraceWriter - to be added to the list

getTraceWriters

public TraceWriter[] getTraceWriters()
Returns

the array of TraceWriters in the manager

removeTraceWriter

public void removeTraceWriter(TraceWriter traceWriter)

Remove the TraceWriter from the array in the manager

setTraceWriters

public void setTraceWriters(TraceWriter[] traceWriters)

Implementations can use this method to override or enhance the JTAPI provided TraceWriters

Parameters

TraceWriters []- the array of TraceWriters