com.ibm.etill.framework.log
Class Trace

java.lang.Object
  |
  +--com.ibm.etill.framework.log.Trace

public final class Trace
extends Object

Holds data and methods to be used to trace execution of an application.

All tracing will be done using the WebSphere tracing facility. Although this class contains methods for getting and setting trace settings, they are no longer functional and users should instead use WebSphere to control trace settings and the location of the output trace file.

In WebSphere Studio, trace files are written to .metadata/.plugins/com.ibm.etools.websphere.tools/logs in the workspace directory. In WebSphere Application Server, trace records are either written to a "ring buffer" and can be dumped on request, or they are written to standard output or a user-specified file and grow indefinitely.


Field Summary
static int API_COMMAND
          API Command called trace setting
static int CASSETTE_FLAG_1
          Cassette level 1 trace setting
static int CASSETTE_FLAG_2
          Cassette level 2 trace setting
static int CASSETTE_FLAG_3
          Cassette level 3 trace setting
static int CASSETTE_FLAG_4
          Cassette level 4 trace setting
static int COMM_WITH_DATA
          Communication trace setting.
static int COMMUNICATION
          Communication trace setting.
static int DB_ACCESS
          Database access trace setting.
static int DB_COMMIT
          Database commit trace setting
static int DB_READ
          Database read access trace setting
static int DB_WRITE
          Database write access trace setting
static int DEBUG
          Generic "catch-all" trace setting
static int ERROR_OCCURRED
          Error (general) trace setting
static String FRAMEWORK
          identifies the Payments Framework component when making a trace call
static int FUNC_ENTRY
          Function entry trace setting
static int FUNC_ENTRY_EXIT
          Function entry/exit trace setting.
static int FUNC_EXIT
          Function exit trace setting
static int OBJ_BATCH
          Flag indicating a batch object.
static int OBJ_CREDIT
          Flag indicating a credit object.
static int OBJ_ORDER
          Flag indicating an order object.
static int OBJ_PAYMENT
          Flag indicating a payment object.
static int OBJECT_STATE
          Object state trace setting
static int PERFORMANCE
          Performance Information trace setting
static int REALM
          Realm trace setting
static int START_WORK_ITEM
          Work item has been started trace setting
static int SYSTEM_INFO
          System Information trace setting
static int TCP_CONN_DROP
          Connection dropped/lost trace setting
static int TCP_CONN_EST
          Connection established trace setting
static int TCP_READ
          TCP Read activity trace setting
static int TCP_READ_DATA
          TCP Read activity (including data) trace setting
static int TCP_WRITE
          TCP Write activity trace setting
static int TCP_WRITE_DATA
          TCP Write activity (including data) trace setting
static int TRACE_ALL
          All trace enabled trace setting.
static int TRACE_INFO
          Trace Information trace setting
static int TRACE_NONE
          All trace disabled trace setting.
static String USER_INTERFACE
          identifies the Payments Framework UI component when making a trace call
static String V1R2_COMPATABILITY_TRACE_NAME
          identifies trace calls made using the Payment Server 1.2 trace APIs
 
Constructor Summary
Trace()
           
 
Method Summary
static int getTraceSettings(String strComponentID)
          Deprecated. Cassettes should not call this method. Trace is now enabled and disabled using the WebSphere Application Server trace facility and cannot be set at runtime by cassettes. This method always returns zero.
static boolean isAnyoneTracing()
          Returns true if there is any logger that currently has trace enabled.
static boolean isTracing(String component)
          Indicates when the trace logger for the specified component is current enabled to trace records.
static void setTraceSettings(String strComponentID)
          Registers the component to the trace facility.
static void setTraceSettings(String strComponentID, int nTraceSettings)
          Deprecated. Use setTraceSettings(String)
static void setTraceSettings(String strComponentID, int nTraceSettings, String strTraceString)
          Deprecated. Use setTraceSettings(String)
static void trace(String strMessageText)
          Deprecated. Use trace(String, long, String, String, String) This method is only provided for compatibility with 1.2 cassettes and will be removed in the future.
static void traceApiCommand(String strComponentID, String strCommandName, String strParameters)
          Outputs an "API Command" trace record to the log file.
static void traceCassetteMessage1(String strComponentID, String strDebugMessage)
          Outputs a cassette-specific debug message to the log file.
static void traceCassetteMessage2(String strComponentID, String strDebugMessage)
          Outputs a cassette-specific debug message to the log file.
static void traceCassetteMessage3(String strComponentID, String strDebugMessage)
          Outputs a cassette-specific debug message to the log file.
static void traceCassetteMessage4(String strComponentID, String strDebugMessage)
          Outputs a cassette-specific debug message to the log file.
static void traceDatabaseCommit(String strComponentID)
          Outputs an "Database Commit" trace record to the log file.
static void traceDatabaseRead(String strComponentID, String strSqlStatement)
          Outputs an "Database Read" trace record to the log file.
static void traceDatabaseWrite(String strComponentID, String strSqlStatement)
          Outputs an "Database Write" trace record to the log file.
static void traceDebug(String strComponentID, String strDebugMessage)
          Outputs a "Debug record" trace record to the log file.
static void traceErrorOccurred(String strComponentID, String strMessage)
          Outputs an "Error Occurred" trace record to the log file.
static void traceFunctionEntry(String strComponentID, String strFunctionName)
          Outputs a "Function Entry" trace record to the log file.
static void traceFunctionExit(String strComponentID, String strFunctionName)
          Outputs a "Function Exit" trace record to the log file.
static void traceObjectState(String strComponentID, int nObjectType, int nObjectID, String strObjectState)
          Outputs an "Object State" trace record to the log file.
static void tracePerformance(String strComponentID, String strPerformanceMessage)
          Outputs a "Performance table" trace record to the log file.
static void traceRealm(String strComponentID, String strRealmMessage)
          Outputs a "Realm record" trace record to the log file.
static void traceStartWorkItem(String strComponentID, String strWorkItemID)
          Outputs a "Start Work Item" trace record to the log file.
static void traceSystemInfo(String strComponentID, String strSystemInfo)
          Outputs an "System Info" trace record to the log file.
static void traceTcpConnectionDropped(String strComponentID, InetAddress sourceAddress, int nSourcePort, InetAddress destAddress, int nDestPort, int nConnectionID)
          Outputs a "TCP Connection Dropped/Lost" trace record to the log file.
static void traceTcpConnectionEstablished(String strComponentID, InetAddress sourceAddress, int nSourcePort, InetAddress destAddress, int nDestPort, int nConnectionID)
          Outputs a "TCP Connection Established" trace record to the log file.
static void traceTcpRead(String strComponentID, int nConnectionID, int nDataLength, String strData)
          Outputs a "TCP Read" trace record to the log file.
static void traceTcpWrite(String strComponentID, int nConnectionID, int nDataLength, String strData)
          Outputs a "TCP Write" trace record to the log file.
static boolean tracing()
          Deprecated. Use isTracing(loggerName). This method is only provided for compatibility with 1.2 cassettes and will be removed in the future.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

FRAMEWORK

public static final String FRAMEWORK
identifies the Payments Framework component when making a trace call

V1R2_COMPATABILITY_TRACE_NAME

public static final String V1R2_COMPATABILITY_TRACE_NAME
identifies trace calls made using the Payment Server 1.2 trace APIs

USER_INTERFACE

public static final String USER_INTERFACE
identifies the Payments Framework UI component when making a trace call

TCP_CONN_EST

public static final int TCP_CONN_EST
Connection established trace setting

TCP_CONN_DROP

public static final int TCP_CONN_DROP
Connection dropped/lost trace setting

TCP_READ

public static final int TCP_READ
TCP Read activity trace setting

TCP_READ_DATA

public static final int TCP_READ_DATA
TCP Read activity (including data) trace setting

TCP_WRITE

public static final int TCP_WRITE
TCP Write activity trace setting

TCP_WRITE_DATA

public static final int TCP_WRITE_DATA
TCP Write activity (including data) trace setting

FUNC_ENTRY

public static final int FUNC_ENTRY
Function entry trace setting

FUNC_EXIT

public static final int FUNC_EXIT
Function exit trace setting

API_COMMAND

public static final int API_COMMAND
API Command called trace setting

DB_READ

public static final int DB_READ
Database read access trace setting

DB_WRITE

public static final int DB_WRITE
Database write access trace setting

DB_COMMIT

public static final int DB_COMMIT
Database commit trace setting

DEBUG

public static final int DEBUG
Generic "catch-all" trace setting

OBJECT_STATE

public static final int OBJECT_STATE
Object state trace setting

ERROR_OCCURRED

public static final int ERROR_OCCURRED
Error (general) trace setting

START_WORK_ITEM

public static final int START_WORK_ITEM
Work item has been started trace setting

TRACE_INFO

public static final int TRACE_INFO
Trace Information trace setting

SYSTEM_INFO

public static final int SYSTEM_INFO
System Information trace setting

PERFORMANCE

public static final int PERFORMANCE
Performance Information trace setting

REALM

public static final int REALM
Realm trace setting

CASSETTE_FLAG_1

public static final int CASSETTE_FLAG_1
Cassette level 1 trace setting

CASSETTE_FLAG_2

public static final int CASSETTE_FLAG_2
Cassette level 2 trace setting

CASSETTE_FLAG_3

public static final int CASSETTE_FLAG_3
Cassette level 3 trace setting

CASSETTE_FLAG_4

public static final int CASSETTE_FLAG_4
Cassette level 4 trace setting

COMMUNICATION

public static final int COMMUNICATION
Communication trace setting. This is a combination of TCP_CONN_EST, TCP_CONN_DROP, TCP_READ and TCP_WRITE trace settings.

COMM_WITH_DATA

public static final int COMM_WITH_DATA
Communication trace setting. This is a combination of TCP_CONN_EST, TCP_CONN_DROP, TCP_READ_DATA and TCP_WRITE_DATA trace settings. TCP write (including data) trace settings.

DB_ACCESS

public static final int DB_ACCESS
Database access trace setting. This is a combination of DB_READ, DB_WRITE and DB_COMMIT trace settings.

FUNC_ENTRY_EXIT

public static final int FUNC_ENTRY_EXIT
Function entry/exit trace setting. This is a combination of FUNC_ENTRY and FUNC_EXIT trace settings.

TRACE_ALL

public static final int TRACE_ALL
All trace enabled trace setting.

TRACE_NONE

public static final int TRACE_NONE
All trace disabled trace setting.

OBJ_ORDER

public static final int OBJ_ORDER
Flag indicating an order object.

OBJ_BATCH

public static final int OBJ_BATCH
Flag indicating a batch object.

OBJ_PAYMENT

public static final int OBJ_PAYMENT
Flag indicating a payment object.

OBJ_CREDIT

public static final int OBJ_CREDIT
Flag indicating a credit object.
Constructor Detail

Trace

public Trace()
Method Detail

getTraceSettings

public static int getTraceSettings(String strComponentID)
Deprecated. Cassettes should not call this method. Trace is now enabled and disabled using the WebSphere Application Server trace facility and cannot be set at runtime by cassettes. This method always returns zero.

Returns the trace settings for the given component id. Since we are now using WebSphere to control the trace settings for each component and the trace settings have different values than before. This method will now always return 0.
Parameters:
strComponentID - The ID of the component making this function call.
Returns:
always zero.

setTraceSettings

public static void setTraceSettings(String strComponentID,
                                    int nTraceSettings,
                                    String strTraceString)
Deprecated. Use setTraceSettings(String)

Registers the component to the trace facility. The actual trace setting is ignored since the WebSphere Application Server trace facility is now used to control trace settings.
Parameters:
strComponentID - the component ID to register to the trace facility. This will usually be the name of the cassette.
nTraceSettings - this value is ignored.
strTraceString - this value is ignored.

setTraceSettings

public static void setTraceSettings(String strComponentID,
                                    int nTraceSettings)
Deprecated. Use setTraceSettings(String)

Registers the component to the trace facility. The actual trace setting is ignored since the WebSphere Application Server trace facility is now used to control trace settings.
Parameters:
strComponentID - the component ID to register to the trace facility. This will usually be the name of the cassette.
nTraceSettings - this value is ignored.

setTraceSettings

public static void setTraceSettings(String strComponentID)
Registers the component to the trace facility.
Parameters:
strComponentID - the component ID to register to the trace facility. This will usually be the name of the cassette.

isAnyoneTracing

public static final boolean isAnyoneTracing()
Returns true if there is any logger that currently has trace enabled.

This method should be called before any tracing invocation to determine if we even need to bother making the call to begin with. Example:

 if (Trace.isAnyoneTracing()) 
   Trace.traceFunctionEntry(strCompId, "MyFunction");
 

It is recommended that for performance reasons, users make use of the isTracing() method instead of this one.

Returns:
a boolean value that is true if at least one component is tracing something (and thus the tracing call should be made), or false if nothing is being traced (and thus the tracing call should not be made.)

isTracing

public static final boolean isTracing(String component)
Indicates when the trace logger for the specified component is current enabled to trace records. All calls to one of the trace methods in this class should be conditioned using this method as follows:
   if (Trace.isTracing(comp)) Trace.traceDebug(comp,...);
 
This will improve the performance of the system since the arguments of the trace(...) method will not be evaluated when tracing is disabled.
Parameters:
component - The ID of the component making this function call.
Returns:
true if the trace logger has tracing enabled; false otherwise.

tracing

public static final boolean tracing()
Deprecated. Use isTracing(loggerName). This method is only provided for compatibility with 1.2 cassettes and will be removed in the future.

Returns true if there is any logger that currently has trace enabled.
Returns:
true if the any trace logger has tracing enabled; false otherwise.

trace

public static void trace(String strMessageText)
Deprecated. Use trace(String, long, String, String, String) This method is only provided for compatibility with 1.2 cassettes and will be removed in the future.

Outputs a debug trace record to the trace log containing the specified text.
Parameters:
strMessageText - the message text to trace.

traceTcpConnectionEstablished

public static void traceTcpConnectionEstablished(String strComponentID,
                                                 InetAddress sourceAddress,
                                                 int nSourcePort,
                                                 InetAddress destAddress,
                                                 int nDestPort,
                                                 int nConnectionID)
Outputs a "TCP Connection Established" trace record to the log file.
Parameters:
strComponentID - The ID of the component making this function call.
sourceAddress - The IP address of the source machine.
nSourcePort - The port number of the source machine.
destAddress - The IP address of the destination machine.
nDestPort - The port number of the destination machine.
nConnectionID - The connection ID assigned to this connection.

traceTcpConnectionDropped

public static void traceTcpConnectionDropped(String strComponentID,
                                             InetAddress sourceAddress,
                                             int nSourcePort,
                                             InetAddress destAddress,
                                             int nDestPort,
                                             int nConnectionID)
Outputs a "TCP Connection Dropped/Lost" trace record to the log file.
Parameters:
strComponentID - The ID of the component making this function call. (Should be a maximum of 6 characters)
sourceAddress - The IP address of the source machine.
nSourcePort - The port number of the source machine.
destAddress - The IP address of the destination machine.
nDestPort - The port number of the destination machine.
nConnectionID - The connection ID assigned to this connection.

traceTcpRead

public static void traceTcpRead(String strComponentID,
                                int nConnectionID,
                                int nDataLength,
                                String strData)
Outputs a "TCP Read" trace record to the log file.
Parameters:
strComponentID - The ID of the component making this function call. (Should be a maximum of 6 characters)
nConnectionID - The connection ID of the connection reading the data
nDataLength - The number of bytes read
strData - The actual data that was read

traceTcpWrite

public static void traceTcpWrite(String strComponentID,
                                 int nConnectionID,
                                 int nDataLength,
                                 String strData)
Outputs a "TCP Write" trace record to the log file.
Parameters:
strComponentID - The ID of the component making this function call. (Should be a maximum of 6 characters)
nConnectionID - The connection ID of the connection writing the data
nDataLength - The number of bytes written
strData - The actual data that was written

traceFunctionEntry

public static void traceFunctionEntry(String strComponentID,
                                      String strFunctionName)
Outputs a "Function Entry" trace record to the log file.
Parameters:
strComponentID - The ID of the component making this function call. (Should be a maximum of 6 characters)
strFunctionName - The name of the function that was just entered.

traceFunctionExit

public static void traceFunctionExit(String strComponentID,
                                     String strFunctionName)
Outputs a "Function Exit" trace record to the log file.
Parameters:
strComponentID - The ID of the component making this function call. (Should be a maximum of 6 characters)
strFunctionName - The name of the function about to be exited.

traceApiCommand

public static void traceApiCommand(String strComponentID,
                                   String strCommandName,
                                   String strParameters)
Outputs an "API Command" trace record to the log file.
Parameters:
strComponentID - The ID of the component making this function call. (Should be a maximum of 6 characters)
strCommandName - The name of the API command that is being called.
strParameters - The parameters passed to the API command.

traceDatabaseRead

public static void traceDatabaseRead(String strComponentID,
                                     String strSqlStatement)
Outputs an "Database Read" trace record to the log file.
Parameters:
strComponentID - The ID of the component making this function call. (Should be a maximum of 6 characters)
strSqlStatement - The SQL statement that was passed to the database

traceDatabaseWrite

public static void traceDatabaseWrite(String strComponentID,
                                      String strSqlStatement)
Outputs an "Database Write" trace record to the log file.
Parameters:
strComponentID - The ID of the component making this function call. (Should be a maximum of 6 characters)
strSqlStatement - The SQL statement that was passed to the database

traceDatabaseCommit

public static void traceDatabaseCommit(String strComponentID)
Outputs an "Database Commit" trace record to the log file.
Parameters:
strComponentID - The ID of the component making this function call. (Should be a maximum of 6 characters)

traceDebug

public static void traceDebug(String strComponentID,
                              String strDebugMessage)
Outputs a "Debug record" trace record to the log file.
Parameters:
strComponentID - The ID of the component making this function call. (Should be a maximum of 6 characters)
strDebugMessage - The debug message to display. This is an arbitrary-length String...

traceRealm

public static void traceRealm(String strComponentID,
                              String strRealmMessage)
Outputs a "Realm record" trace record to the log file.
Parameters:
strComponentID - The ID of the component making this function call. (Should be a maximum of 6 characters)
strDebugMessage - The debug message to display. This is an arbitrary-length String...

tracePerformance

public static void tracePerformance(String strComponentID,
                                    String strPerformanceMessage)
Outputs a "Performance table" trace record to the log file.
Parameters:
strComponentID - The ID of the component making this function call. (Should be a maximum of 6 characters)
strDebugMessage - The debug message to display. This is an arbitrary-length String...

traceObjectState

public static void traceObjectState(String strComponentID,
                                    int nObjectType,
                                    int nObjectID,
                                    String strObjectState)
Outputs an "Object State" trace record to the log file.
Parameters:
strComponentID - The ID of the component making this function call. (Should be a maximum of 6 characters)
nObjectType - The type of object being traced. This can be any of the following values:
  • Trace.OBJ_ORDER
  • Trace.OBJ_BATCH
  • Trace.OBJ_PAYMENT
  • Trace.OBJ_CREDIT
nObjectID - A unique identifier for the object.
strObjectState - A string representation of the object's state.

traceErrorOccurred

public static void traceErrorOccurred(String strComponentID,
                                      String strMessage)
Outputs an "Error Occurred" trace record to the log file.
Parameters:
strComponentID - The ID of the component making this function call. (Should be a maximum of 6 characters)
strMessage - The message used to describe the error.

traceStartWorkItem

public static void traceStartWorkItem(String strComponentID,
                                      String strWorkItemID)
Outputs a "Start Work Item" trace record to the log file.
Parameters:
strComponentID - The ID of the component making this function call. (Should be a maximum of 6 characters)
strWorkItemID - An informational text that indicates work item status.

traceSystemInfo

public static void traceSystemInfo(String strComponentID,
                                   String strSystemInfo)
Outputs an "System Info" trace record to the log file.
Parameters:
strComponentID - The ID of the component making this function call. (Should be a maximum of 6 characters)
strSystemInfo - The message to display

traceCassetteMessage1

public static void traceCassetteMessage1(String strComponentID,
                                         String strDebugMessage)
Outputs a cassette-specific debug message to the log file.
Parameters:
strComponentID - The ID of the component making this function call. (Should be a maximum of 6 characters)
strDebugMessage - The debug message to display. This is an arbitrary-length String...

traceCassetteMessage2

public static void traceCassetteMessage2(String strComponentID,
                                         String strDebugMessage)
Outputs a cassette-specific debug message to the log file.
Parameters:
strComponentID - The ID of the component making this function call. (Should be a maximum of 6 characters)
strDebugMessage - The debug message to display. This is an arbitrary-length String...

traceCassetteMessage3

public static void traceCassetteMessage3(String strComponentID,
                                         String strDebugMessage)
Outputs a cassette-specific debug message to the log file.
Parameters:
strComponentID - The ID of the component making this function call. (Should be a maximum of 6 characters)
strDebugMessage - The debug message to display. This is an arbitrary-length String...

traceCassetteMessage4

public static void traceCassetteMessage4(String strComponentID,
                                         String strDebugMessage)
Outputs a cassette-specific debug message to the log file.
Parameters:
strComponentID - The ID of the component making this function call. (Should be a maximum of 6 characters)
strDebugMessage - The debug message to display. This is an arbitrary-length String...