Websphere MQ Everyplace

com.ibm.mqe
Class MQeTrace

java.lang.Object
  |
  +--com.ibm.mqe.MQeTrace

public class MQeTrace
extends java.lang.Object

Provides methods to set and invoke the trace handler.

The various trace methods available in this class all provide information to the trace handler set using setHandler(com.ibm.mqe.MQeTraceHandler).

A trace point is a location in code where a call to the MQeTrace mechanism has been made. Each trace point has a unique number, a java short primitive type. This number can be used to map from a numeric (which has a small footprint in the code) to a readable string (which has a relatively large footprint in the code).

The separation of the string, from the trace point number can be used by trace handlers to log the binary numeric information only. The mapping to a readable string can be done later when the trace is being analysed, in less footprint constrained environments.

For example : The MQeTraceFromBinaryFile class can collect binary information, and the the MQeTraceFromBinaryFile class can be used to convert the binary information to readable form.

All calls to the trace methods pass a group value. This is a bit-mask indicating some classification information to logically group similar trace points. Groups are defined by the GROUP_* constants defined in this class. These may be bitwise-ORed together, allowing a trace point to exist symultaneously in more than one group.

For example, if you are tracing an error, using a group of GROUP_ERROR is recommended so that trace handlers can filter the data, to collect or discard that piece of trace information depending on the filtering criteria in place at the time.

We recommend that any trace point be classified using one of the GROUP_ERROR, GROUP_WARNING or GROUP_INFO pre-defined logical groupings.

The group bitmask has some fields reserved for use by IBM, defined by bits set in the GROUP_MASK_IBM_DEFINED constant and the remaining bits, defined by bits set in the GROUP_MASK_USER_DEFINED constant, are allocated a meaning by user code.

Setting the filter mask using the setFilter(long) method can cause trace information to be filtered, such that some or all trace information is discarded before being passed on to the trace handler. This mechanism can be used to turn trace off (setting the filter mask to GROUP_MASK_NONE) or turn fully on (setting the filter mask to GROUP_MASK_ALL) or filter out everything except warnings and errors (by setting the filter mask to GROUP_ERROR | GROUP_WARNING) or any combination of groups.

So, if you wish to distinguish between an information trace point (one belonging to the GROUP_INFO group) originating from within MQe product code, and one coming from user code, you would use GROUP_INFO logically-ORed with GROUP_USER_DEFINED_1 , and set the filter mask to GROUP_USER_DEFINED_1. Alternatively, set the filter mask to ALL, and implement more complex filtering in a trace handler class, by implementing the MQeTraceHandler interface.

Note that the methods in this class are static, and the class holds information in static variables. Care should be taken to prevent the last existing instance of this class from being garbage collected. For this reason, the MQe class holds a static reference to an MQeTrace object.

Example:
 //
 // Method which logs a generic error.
 //
 // The trace handler will capture the value of thingToLog.toString().
 //
 // The trace will only be captured if the filter mask is set to unclude
 // MQeTrace.GROUP_ERROR or MQeTrace.GROUP_USER_DEFINED_1
 //
 // Facets of the calling thread (name and hash table) may be collected by
 // the trace handler.
 //
 // The hash table of the thingToLog object may also be captured.
 //
 // The hash table of the "this" object may be captured, with the value
 // returned by the this.toString() method.
 //
 public void logError(Object thingToLog) {
     MQeTrace.trace(this, (short) (MQeTrace.TRACE_NUMBER_USER_DEFINED_MIN + 1), MQeTrace.GROUP_ERROR | MQeTrace.GROUP_USER_DEFINED_1, thingToLog
     );
 }
 
 
,
 // static variable to make sure the MQeTrace object is long-lived, and not garbage collected.
 MQeTraceHandler handler = null;
 
 //
 // Sets a trace handler up.
 //
 public void traceInit() {
     MQeTraceHandler handler = (MQeTraceHandler) new com.ibm.mqe.trace.MQeTraceToBinaryFile();
 
     MQeTrace.setHandler(handler);
 }
 
 
 
,
 //
 // Demonstrates how the trace filter can be set to prevent filtering of any trace information.
 //
 void traceOn() {
     MQeTrace.setFilter(MQeTrace.GROUP_MASK_ALL);
 }
 
 
 
,
 //
 // To demonstrate using the trace mechanism from a static method.
 //
 public void myStaticMethod1() {
 
     // Create an instance of the trace subsystem, to prevent values within it being
     // garbage-collected.
     MQeTrace myTrace = new MQeTrace();
 
     // This example is slightly odd in that the conversion of the trace point number
     // into a readable string is being performed by the same code which is issueing the
     // trace information.
     //
     // Define the trace point we are going to use later.
     // It's number is user-defined, so must be within the user-defined range.
     // It has one parameter ('#' is substituted for this parameter).
     //
     short myTracePointNumber = MQeTrace.TRACE_NUMBER_USER_DEFINED_MIN + 345;
 
     MQeTracePoint myTracePoint = new MQeTracePoint(myTracePointNumber, "This is my trace point. Param=#", "examples.api.com.ibm.mqe.MQeTraceExample", "void myStaticMethod1()", (short) 15
         );
 
     // Create a renderer to map from the trace point number to all the information about the
     // trace point.
     MQeTraceRenderer myRenderer = new MQeTraceRenderer();
 
     // Create a group to which the trace point belongs.
     try {
         MQeTracePointGroup myGroup = new MQeTracePointGroup("MyGroup", 'm');
 
         myGroup.addTracePoint(myTracePoint);
         myRenderer.addGroup(myGroup);
     } catch (Exception e) {
         System.out.println("Group can not be created due to error" + e.toString());
     }
 
     // Create a trace handler.
     MQeTraceHandler myTraceHandler = (MQeTraceHandler) new com.ibm.mqe.trace.MQeTraceToReadable(
             System.out // Logs to the standard output stream.
             , myRenderer // Use the renderer containing our trace point
         );
 
     // Now that we have the trace handler set up. It's time to start using it.
 
     // Plug the trace handler into the trace mechanism
     MQeTrace.setHandler(myTraceHandler);
 
     // Log a trace entry the trace mechanism.
     MQeTrace.trace(null    // This code is within a static. There is no 'this' self-reference to pass.
         , (short) myTracePointNumber, (long) MQeTrace.GROUP_INFO | MQeTrace.GROUP_USER_DEFINED_1, "hello"
     );
 
     // System.out will now contain readable text containing "This is my trace point. Param=hello"
     // A reference to the group information, line number, class, method name and trace point number.
 
 }
 
 
 
,
 //
 // An error has been found, a throwable object is passed to a method
 // to trace the failure.
 //
 void traceError(Throwable t) {
 
     MQeTrace.trace(this                    // This instance is doing the tracing.
         // Details of the tracing object can be logged.
         , (short) 1234        // Our trace number mapped to a string
         // "Error=#" later in a trace point.
         , MQeTrace.GROUP_EXCEPTION | MQeTrace.GROUP_ERROR | MQeTrace.GROUP_USER_DEFINED_1, t
     );
 }
 
 
 

Field Summary
static long GROUP_ADAPTER_CALLING
          Indicates that MQe will shortly call out to an MQeAdapter method.
static long GROUP_ADAPTER_RETURNED
          Indicates that MQe has recently returned from a call to an MQeAdapter method.
static long GROUP_ADMINISTRATION
          Indicates that the trace point refers to an administration action.
static long GROUP_API
          Indicates that the trace point refers to a published MQe method.
static long GROUP_BRIDGE
          Indicates that the trace point concerns MQ Bridge functionality.
static long GROUP_CHANNEL_MANAGEMENT
          Indicates that the trace point concerns channel management.
static long GROUP_COMMS_INCOMING
          Indicates that the trace point refers to in-bound communications events.
static long GROUP_COMMS_OUTGOING
          Indicates that the trace point concerns out-bound communications.
static long GROUP_ENTRY
          Indicates that a trace point is at the point of entry into a method.
static long GROUP_ERROR
          Indicates that a trace point is logging details of an error.
static long GROUP_EXCEPTION
          Indicates that the trace point refers to an exception event.
static long GROUP_EXIT
          Indicates that a trace point is at the point of exit from a method.
static long GROUP_INFO
          Indicates that a trace point is neither a warning or error, but an extra piece of information.
static long GROUP_JMS
          Indicates that the trace point refers to a JMS operation.
static long GROUP_MASK_ALL
          A bit mask indicating that a trace point is a member of all groups.
static long GROUP_MASK_DEFAULT
          A bit mask used as the default filter.
static long GROUP_MASK_IBM_DEFINED
          A bit mask indicating which bits IBM code case use for IBM-defined groups.
static long GROUP_MASK_NONE
          A bit mask indicating that a trace point is a not a member of any groups.
static long GROUP_MASK_USER_DEFINED
          A bit mask indicating which bits MQe user code can use for used-defined groups.
static long GROUP_MESSAGE_STATE
          Indicates that the trace point concerns state changes of messages.
static long GROUP_MESSAGE_STORE
          Indicates that the trace point concerns the storage of messages.
static long GROUP_MQSERIES
          Indicates that a trace point was generated by the MQSeries java classes.
static long GROUP_QUEUE_MANAGER
          Indicates that a trace point refers to trace in the Queue Manager
static long GROUP_RULE_CALLING
          Indicates that MQe will shortly call out to a rule method.
static long GROUP_RULE_RETURNED
          Indicates that MQe has recently returned form a call to a rule method.
static long GROUP_SECURITY
          Indicates that the trace point refers to a security operation.
static long GROUP_THREAD_CONTROL
          Indicates that the trace point concerns the control of threads.
static long GROUP_TRANSACTION
          Indicates that the trace point refers to a message transaction.
static long GROUP_USER_DEFINED_1
          One of the bits taken from the GROUP_MASK_USER_DEFINED bit mask, for use by user code.
static long GROUP_USER_DEFINED_2
          One of the bits taken from the GROUP_MASK_USER_DEFINED bit mask, for use by user code.
static long GROUP_USER_DEFINED_3
          One of the bits taken from the GROUP_MASK_USER_DEFINED bit mask, for use by user code.
static long GROUP_USER_DEFINED_4
          One of the bits taken from the GROUP_MASK_USER_DEFINED bit mask, for use by user code.
static long GROUP_WARNING
          Indicates that a trace point is logging details of a warning.
static short TRACE_NUMBER_USER_DEFINED_MAX
          Defines the maximum allowable value a user-defined trace point number can be.
static short TRACE_NUMBER_USER_DEFINED_MIN
          Defines the minimum allowable value a user-defined trace point number can be.
 
Constructor Summary
MQeTrace()
          The constructor for such an object.
 
Method Summary
static long getFilter()
          Gets the current trace filter mask.
static MQeTraceHandler getHandler()
          Gets a reference to the trace handler currently used by MQe.
static boolean passesFilter(long groups)
          To check to see if a trace group would pass the trace filtering or not.
static void setFilter(long mask)
          Sets the current trace filter mask.
static MQeTraceHandler setHandler(MQeTraceHandler newTraceHandler)
          Sets the trace handler to be used by MQe.
static void trace(java.lang.Object selfReference, short tracePointNumber, long groups)
          Sends a trace entry to the current trace handler if it has been set.
static void trace(java.lang.Object selfReference, short tracePointNumber, long groups, java.lang.Object p1)
          Sends a trace entry to the current trace handler if it has been set.
static void trace(java.lang.Object selfReference, short tracePointNumber, long groups, java.lang.Object p1, java.lang.Object p2)
          Sends a trace entry to the current trace handler if it has been set.
static void trace(java.lang.Object selfReference, short tracePointNumber, long groups, java.lang.Object p1, java.lang.Object p2, java.lang.Object p3)
          Sends a trace entry to the current trace handler if it has been set.
static void trace(java.lang.Object selfReference, short tracePointNumber, long groups, java.lang.Object p1, java.lang.Object p2, java.lang.Object p3, java.lang.Object p4)
          Sends a trace entry to the current trace handler if it has been set.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

TRACE_NUMBER_USER_DEFINED_MIN

public static final short TRACE_NUMBER_USER_DEFINED_MIN
Defines the minimum allowable value a user-defined trace point number can be.

IBM reserves the right to define of all trace point numbers below this value.

See Also:
Constant Field Values

TRACE_NUMBER_USER_DEFINED_MAX

public static final short TRACE_NUMBER_USER_DEFINED_MAX
Defines the maximum allowable value a user-defined trace point number can be.

IBM reserves the right to define of all trace point numbers below this value.

See Also:
Constant Field Values

GROUP_MASK_NONE

public static final long GROUP_MASK_NONE
A bit mask indicating that a trace point is a not a member of any groups.

Useful when using the setFilter(long) method, so that all tracing is filtered-out at run time.

See Also:
Constant Field Values
Example:
 //
 // Demonstrates how the trace filter can be cleared, to filter out all trace information.
 // This effectively turns trace collection "off" without removal of the trace handler.
 //
 void collectNoTrace() {
     MQeTrace.setFilter(MQeTrace.GROUP_MASK_NONE);
 }
 
 
 

GROUP_ERROR

public static final long GROUP_ERROR
Indicates that a trace point is logging details of an error.

See Also:
Constant Field Values
Example:
 //
 // An error has been found, a throwable object is passed to a method
 // to trace the failure.
 //
 void traceError(Throwable t) {
 
     MQeTrace.trace(this                    // This instance is doing the tracing.
         // Details of the tracing object can be logged.
         , (short) 1234        // Our trace number mapped to a string
         // "Error=#" later in a trace point.
         , MQeTrace.GROUP_EXCEPTION | MQeTrace.GROUP_ERROR | MQeTrace.GROUP_USER_DEFINED_1, t
     );
 }
 
 
 

GROUP_WARNING

public static final long GROUP_WARNING
Indicates that a trace point is logging details of a warning.

See Also:
Constant Field Values

GROUP_ENTRY

public static final long GROUP_ENTRY
Indicates that a trace point is at the point of entry into a method.

See Also:
Constant Field Values

GROUP_EXIT

public static final long GROUP_EXIT
Indicates that a trace point is at the point of exit from a method.

See Also:
Constant Field Values

GROUP_ADAPTER_CALLING

public static final long GROUP_ADAPTER_CALLING
Indicates that MQe will shortly call out to an MQeAdapter method.

See Also:
Constant Field Values

GROUP_ADAPTER_RETURNED

public static final long GROUP_ADAPTER_RETURNED
Indicates that MQe has recently returned from a call to an MQeAdapter method.

See Also:
Constant Field Values

GROUP_RULE_CALLING

public static final long GROUP_RULE_CALLING
Indicates that MQe will shortly call out to a rule method.

See Also:
Constant Field Values

GROUP_RULE_RETURNED

public static final long GROUP_RULE_RETURNED
Indicates that MQe has recently returned form a call to a rule method.

See Also:
Constant Field Values

GROUP_BRIDGE

public static final long GROUP_BRIDGE
Indicates that the trace point concerns MQ Bridge functionality.

See Also:
Constant Field Values

GROUP_COMMS_OUTGOING

public static final long GROUP_COMMS_OUTGOING
Indicates that the trace point concerns out-bound communications.

See Also:
Constant Field Values

GROUP_CHANNEL_MANAGEMENT

public static final long GROUP_CHANNEL_MANAGEMENT
Indicates that the trace point concerns channel management.

See Also:
Constant Field Values

GROUP_MESSAGE_STATE

public static final long GROUP_MESSAGE_STATE
Indicates that the trace point concerns state changes of messages.

See Also:
Constant Field Values

GROUP_THREAD_CONTROL

public static final long GROUP_THREAD_CONTROL
Indicates that the trace point concerns the control of threads.

See Also:
Constant Field Values

GROUP_MESSAGE_STORE

public static final long GROUP_MESSAGE_STORE
Indicates that the trace point concerns the storage of messages.

See Also:
Constant Field Values

GROUP_ADMINISTRATION

public static final long GROUP_ADMINISTRATION
Indicates that the trace point refers to an administration action.

See Also:
Constant Field Values

GROUP_EXCEPTION

public static final long GROUP_EXCEPTION
Indicates that the trace point refers to an exception event.

See Also:
Constant Field Values
Example:
 //
 // An error has been found, a throwable object is passed to a method
 // to trace the failure.
 //
 void traceError(Throwable t) {
 
     MQeTrace.trace(this                    // This instance is doing the tracing.
         // Details of the tracing object can be logged.
         , (short) 1234        // Our trace number mapped to a string
         // "Error=#" later in a trace point.
         , MQeTrace.GROUP_EXCEPTION | MQeTrace.GROUP_ERROR | MQeTrace.GROUP_USER_DEFINED_1, t
     );
 }
 
 
 

GROUP_JMS

public static final long GROUP_JMS
Indicates that the trace point refers to a JMS operation.

See Also:
Constant Field Values

GROUP_SECURITY

public static final long GROUP_SECURITY
Indicates that the trace point refers to a security operation.

See Also:
Constant Field Values

GROUP_COMMS_INCOMING

public static final long GROUP_COMMS_INCOMING
Indicates that the trace point refers to in-bound communications events.

See Also:
Constant Field Values

GROUP_TRANSACTION

public static final long GROUP_TRANSACTION
Indicates that the trace point refers to a message transaction.

See Also:
Constant Field Values

GROUP_API

public static final long GROUP_API
Indicates that the trace point refers to a published MQe method.

Will often be used in conjunction with the GROUP_ENTRY and GROUP_EXIT

See Also:
Constant Field Values
Example:
 //
 // Switch on the collection of MQe interface call tracing, without effecting any other
 // trace filtering which is already set.
 //
 void collectMQeAPITraceOn() {
     long currentFilter = MQeTrace.getFilter();
     long newFilter = currentFilter | MQeTrace.GROUP_API;
 
     MQeTrace.setFilter(newFilter);
 }
 
 
 

GROUP_INFO

public static final long GROUP_INFO
Indicates that a trace point is neither a warning or error, but an extra piece of information.

See Also:
Constant Field Values

GROUP_QUEUE_MANAGER

public static final long GROUP_QUEUE_MANAGER
Indicates that a trace point refers to trace in the Queue Manager

See Also:
Constant Field Values

GROUP_MQSERIES

public static final long GROUP_MQSERIES
Indicates that a trace point was generated by the MQSeries java classes.

See Also:
Constant Field Values

GROUP_MASK_USER_DEFINED

public static final long GROUP_MASK_USER_DEFINED
A bit mask indicating which bits MQe user code can use for used-defined groups.

IBM will not define any groups which clash with these bits.

See Also:
Constant Field Values

GROUP_USER_DEFINED_1

public static final long GROUP_USER_DEFINED_1
One of the bits taken from the GROUP_MASK_USER_DEFINED bit mask, for use by user code.

Here for convenience. There are potentially 16 such groups available for user code. Only one such group is defined to preserve footprint.

See Also:
Constant Field Values
Example:
 //
 // An error has been found, a throwable object is passed to a method
 // to trace the failure.
 //
 void traceError(Throwable t) {
 
     MQeTrace.trace(this                    // This instance is doing the tracing.
         // Details of the tracing object can be logged.
         , (short) 1234        // Our trace number mapped to a string
         // "Error=#" later in a trace point.
         , MQeTrace.GROUP_EXCEPTION | MQeTrace.GROUP_ERROR | MQeTrace.GROUP_USER_DEFINED_1, t
     );
 }
 
 
 

GROUP_USER_DEFINED_2

public static final long GROUP_USER_DEFINED_2
One of the bits taken from the GROUP_MASK_USER_DEFINED bit mask, for use by user code.

Here for convenience. There are potentially 16 such groups available for user code. Only one such group is defined to preserve footprint.

See Also:
Constant Field Values

GROUP_USER_DEFINED_3

public static final long GROUP_USER_DEFINED_3
One of the bits taken from the GROUP_MASK_USER_DEFINED bit mask, for use by user code.

Here for convenience. There are potentially 16 such groups available for user code. Only one such group is defined to preserve footprint.

See Also:
Constant Field Values

GROUP_USER_DEFINED_4

public static final long GROUP_USER_DEFINED_4
One of the bits taken from the GROUP_MASK_USER_DEFINED bit mask, for use by user code.

Here for convenience. There are potentially 16 such groups available for user code. Only one such group is defined to preserve footprint.

See Also:
Constant Field Values

GROUP_MASK_IBM_DEFINED

public static final long GROUP_MASK_IBM_DEFINED
A bit mask indicating which bits IBM code case use for IBM-defined groups.

User code should not trace information using these bits.

See Also:
Constant Field Values

GROUP_MASK_ALL

public static final long GROUP_MASK_ALL
A bit mask indicating that a trace point is a member of all groups.

Useful when using the setFilter(long) method, so that no tracing is filtered out at run time.

See Also:
Constant Field Values
Example:
 //
 // Demonstrates how the trace filter can be set to prevent filtering of any trace information.
 //
 void traceOn() {
     MQeTrace.setFilter(MQeTrace.GROUP_MASK_ALL);
 }
 
 
 

GROUP_MASK_DEFAULT

public static final long GROUP_MASK_DEFAULT
A bit mask used as the default filter.

The default is all trace groups are turned on, except the MQSERIES trace group.

Use the setFilter(long) to over-ride the default.

See Also:
Constant Field Values
Constructor Detail

MQeTrace

public MQeTrace()
The constructor for such an object.

A constructor must be used if static data held within this class is to be protected from garbage collection. For example, the reference to the trace handler set up by the setHandler(com.ibm.mqe.MQeTraceHandler) method.

Method Detail

setHandler

public static MQeTraceHandler setHandler(MQeTraceHandler newTraceHandler)
Sets the trace handler to be used by MQe.

A reference to the trace handler previously set can be obtained using the getHandler() method.

Parameters:
newTraceHandler - A reference to code which implements the MQeTraceHandler. This object will be used to log trace information from all MQe classes from this point onwards, and any user-code which calls MQeTrace methods. Pass null if tracing is no longer required.
Returns:
The previous trace handler used by MQe. null if there was no trace handler previously set.
See Also:
getHandler(), trace(java.lang.Object, short, long)
Example:
 //
 // Demonstrates the construction of a trace handler, and setting that handler up
 // to accept trace information from the MQeTrace class.
 //
 void startCollectingTrace() throws Exception {
 
     // Create a trace handler which puts trace to the System.out output stream.
     MQeTraceHandler myTraceHandler = (MQeTraceHandler) new com.ibm.mqe.trace.MQeTraceToReadable();
 
     // Plug the trace handler in so it starts collecting trace information.
     MQeTrace.setHandler(myTraceHandler);
 }
 
 
 

getHandler

public static MQeTraceHandler getHandler()
Gets a reference to the trace handler currently used by MQe.

The trace handler was previously set using the setHandler(com.ibm.mqe.MQeTraceHandler) method.

Returns:
A reference to the current trace handler. null will be returned if there is no current trace handler set.
See Also:
setHandler(com.ibm.mqe.MQeTraceHandler)
Example:
 //
 // Demonstrates how to find out which trace handler is set or not.
 //
 boolean isTraceHandlerSet() {
     boolean isSet;
     MQeTraceHandler currentHandler = MQeTrace.getHandler();
 
     if (null == currentHandler) {
         isSet = false;
     } else {
         isSet = true;
     }
     return isSet;
 }
 
 
 

setFilter

public static void setFilter(long mask)
Sets the current trace filter mask.

Parameters:
mask - A bit mask against which all trace information is compared, to see whether that trace information is suppressed or not.
See Also:
getFilter()
Example:
 //
 // Starts the collection of all errors, warnings, and anything relating to JMS.
 //
 void collectJMSAndErrorsAndWarnings() {
     MQeTrace.setFilter(MQeTrace.GROUP_ERROR | MQeTrace.GROUP_WARNING | MQeTrace.GROUP_JMS);
 }
 
 
 

getFilter

public static long getFilter()
Gets the current trace filter mask.

Returns:
A bit-mask of trace point groups, which is used to filter all trace activity in the system. Expressed as a collection of the GROUP_* constants in the MQeTraceHandler.
See Also:
MQeTraceHandler
Example:
 //
 // Switch on the collection of MQe interface call tracing, without effecting any other
 // trace filtering which is already set.
 //
 void collectMQeAPITraceOn() {
     long currentFilter = MQeTrace.getFilter();
     long newFilter = currentFilter | MQeTrace.GROUP_API;
 
     MQeTrace.setFilter(newFilter);
 }
 
 
 

trace

public static void trace(java.lang.Object selfReference,
                         short tracePointNumber,
                         long groups)
Sends a trace entry to the current trace handler if it has been set.

This variant of the call passes no additional parameters with the number of the trace point.

The current trace handler is set using the setHandler(com.ibm.mqe.MQeTraceHandler) method, and a reference to it obtained using the getHandler() method.

Depending on the value of the groups parameter, and the trace filter mask set by the setFilter(long) method, the trace information may be supressed at run-time before it is passed to the trace handler.

Parameters:
selfReference - A reference to the "this" object if it is available at the point the call is made. Object class name and hash code can be extracted from this object reference. If invoking this method from a static method, or you do not wish to have such properties traced, use a null value.
tracePointNumber - The number associated with the trace point to be logged. User values must be in the range TRACE_NUMBER_USER_DEFINED_MIN to TRACE_NUMBER_USER_DEFINED_MAX inclusive. IBM reserves the trace points outside of this range for its' own use.
groups - A bitmasked field comprised of one or more GROUP_* constants bit-ORed together. This information can be used to dynamically filter out these course groupings in a simple way, without having to load the MQeTraceRenderer and associated classes. It is recommended that a value OR-ed with GROUP_INFO, GROUP_WARNING or GROUP_ERROR is used.
See Also:
setHandler(com.ibm.mqe.MQeTraceHandler), getHandler()

trace

public static void trace(java.lang.Object selfReference,
                         short tracePointNumber,
                         long groups,
                         java.lang.Object p1)
Sends a trace entry to the current trace handler if it has been set.

The current trace handler is set using the setHandler(com.ibm.mqe.MQeTraceHandler) method, and a reference to it obtained using the getHandler() method.

Depending on the value of the groups parameter, and the trace filter mask set by the setFilter(long) method, the trace information may be supressed at run-time before it is passed to the trace handler.

Parameters:
selfReference - A reference to the "this" object if it is available at the point the call is made. Object class name and hash code can be extracted from this object reference. If invoking this method from a static method, or you do not wish to have such properties traced, use a null value.
tracePointNumber - The number associated with the trace point to be logged. User values must be in the range TRACE_NUMBER_USER_DEFINED_MIN to TRACE_NUMBER_USER_DEFINED_MAX inclusive. IBM reserves the trace points outside of this range for its' own use.
groups - A bitmasked field comprised of one or more GROUP_* constants bit-ORed together. This information can be used to dynamically filter out these course groupings in a simple way, without having to load the MQeTraceRenderer and associated classes. It is recommended that a value OR-ed with GROUP_INFO, GROUP_WARNING or GROUP_ERROR is used.
p1 - A parameter associated with the trace point. The trace handler is likely to use the Object.toString() method for this parameter. A null value is allowed. If this parameter is derived from a Throwable class then the trace handler may use Throwable.printStackTrace()
See Also:
setHandler(com.ibm.mqe.MQeTraceHandler), getHandler()
Example:
 //
 // An error has been found, a throwable object is passed to a method
 // to trace the failure.
 //
 void traceError(Throwable t) {
 
     MQeTrace.trace(this                    // This instance is doing the tracing.
         // Details of the tracing object can be logged.
         , (short) 1234        // Our trace number mapped to a string
         // "Error=#" later in a trace point.
         , MQeTrace.GROUP_EXCEPTION | MQeTrace.GROUP_ERROR | MQeTrace.GROUP_USER_DEFINED_1, t
     );
 }
 
 
 

trace

public static void trace(java.lang.Object selfReference,
                         short tracePointNumber,
                         long groups,
                         java.lang.Object p1,
                         java.lang.Object p2)
Sends a trace entry to the current trace handler if it has been set.

The current trace handler is set using the setHandler(com.ibm.mqe.MQeTraceHandler) method, and a reference to it obtained using the getHandler() method.

Depending on the value of the groups parameter, and the trace filter mask set by the setFilter(long) method, the trace information may be supressed at run-time before it is passed to the trace handler.

Parameters:
selfReference - A reference to the "this" object if it is available at the point the call is made. Object class name and hash code can be extracted from this object reference. If invoking this method from a static method, or you do not wish to have such properties traced, use a null value.
tracePointNumber - The number associated with the trace point to be logged. User values must be in the range TRACE_NUMBER_USER_DEFINED_MIN to TRACE_NUMBER_USER_DEFINED_MAX inclusive. IBM reserves the trace points outside of this range for its' own use.
groups - A bitmasked field comprised of one or more GROUP_* constants bit-ORed together. This information can be used to dynamically filter out these course groupings in a simple way, without having to load the MQeTraceRenderer and associated classes. It is recommended that a value OR-ed with GROUP_INFO, GROUP_WARNING or GROUP_ERROR is used.
p1 - A parameter associated with the trace point. The trace handler is likely to use the Object.toString() method for this parameter. A null value is allowed.
p2 - A parameter associated with the trace point. Similar to parameter p1. If this parameter is derived from a Throwable class then the trace handler may use Throwable.printStackTrace()
See Also:
setHandler(com.ibm.mqe.MQeTraceHandler), getHandler()

trace

public static void trace(java.lang.Object selfReference,
                         short tracePointNumber,
                         long groups,
                         java.lang.Object p1,
                         java.lang.Object p2,
                         java.lang.Object p3)
Sends a trace entry to the current trace handler if it has been set.

The current trace handler is set using the setHandler(com.ibm.mqe.MQeTraceHandler) method, and a reference to it obtained using the getHandler() method.

Depending on the value of the groups parameter, and the trace filter mask set by the setFilter(long) method, the trace information may be supressed at run-time before it is passed to the trace handler.

Parameters:
selfReference - A reference to the "this" object if it is available at the point the call is made. Object class name and hash code can be extracted from this object reference. If invoking this method from a static method, or you do not wish to have such properties traced, use a null value.
tracePointNumber - The number associated with the trace point to be logged. User values must be in the range TRACE_NUMBER_USER_DEFINED_MIN to TRACE_NUMBER_USER_DEFINED_MAX inclusive. IBM reserves the trace points outside of this range for its' own use.
groups - A bitmasked field comprised of one or more GROUP_* constants bit-ORed together. This information can be used to dynamically filter out these course groupings in a simple way, without having to load the MQeTraceRenderer and associated classes. It is recommended that a value OR-ed with GROUP_INFO, GROUP_WARNING or GROUP_ERROR is used.
p1 - A parameter associated with the trace point. The trace handler is likely to use the Object.toString() method for this parameter. A null value is allowed.
p2 - A parameter associated with the trace point. Similar to parameter p1.
p3 - A parameter associated with the trace point. Similar to parameter p1. If this parameter is derived from a Throwable class then the trace handler may use Throwable.printStackTrace()
See Also:
setHandler(com.ibm.mqe.MQeTraceHandler), getHandler()

trace

public static void trace(java.lang.Object selfReference,
                         short tracePointNumber,
                         long groups,
                         java.lang.Object p1,
                         java.lang.Object p2,
                         java.lang.Object p3,
                         java.lang.Object p4)
Sends a trace entry to the current trace handler if it has been set.

The current trace handler is set using the setHandler(com.ibm.mqe.MQeTraceHandler) method, and a reference to it obtained using the getHandler() method.

Depending on the value of the groups parameter, and the trace filter mask set by the setFilter(long) method, the trace information may be supressed at run-time before it is passed to the trace handler.

Parameters:
selfReference - A reference to the "this" object if it is available at the point the call is made. Object class name and hash code can be extracted from this object reference. If invoking this method from a static method, or you do not wish to have such properties traced, use a null value.
tracePointNumber - The number associated with the trace point to be logged. User values must be in the range TRACE_NUMBER_USER_DEFINED_MIN to TRACE_NUMBER_USER_DEFINED_MAX inclusive. IBM reserves the trace points outside of this range for its' own use.
groups - A bitmasked field comprised of one or more GROUP_* constants bit-ORed together. This information can be used to dynamically filter out these course groupings in a simple way, without having to load the MQeTraceRenderer and associated classes. It is recommended that a value OR-ed with GROUP_INFO, GROUP_WARNING or GROUP_ERROR is used.
p1 - A parameter associated with the trace point. The trace handler is likely to use the Object.toString() method for this parameter. A null value is allowed.
p2 - A parameter associated with the trace point. Similar to parameter p1.
p3 - A parameter associated with the trace point. Similar to parameter p1.
p4 - A parameter associated with the trace point. Similar to parameter p1. If this parameter is derived from a Throwable class then the trace handler may use Throwable.printStackTrace()
See Also:
setHandler(com.ibm.mqe.MQeTraceHandler), getHandler()

passesFilter

public static boolean passesFilter(long groups)
To check to see if a trace group would pass the trace filtering or not.

When calling a trace point requires building lots of complex data, the costs of doing this when the data will be filtered-out eventually are wasted. Sometimes it makes sence to determine whether a trace group will be filtered out or not to save on unnecessary work.

Parameters:
groups - A bitmasked field comprised of one or more GROUP_* constants bit-ORed together. This information can be used to dynamically filter out these course groupings in a simple way, without having to load the MQeTraceRenderer and associated classes. It is recommended that a value OR-ed with GROUP_INFO, GROUP_WARNING or GROUP_ERROR is used.
Example:
 //
 // An important event has occurred. Gather lots of data and report the results.
 // Only do this if trace is turned on, so unnecessary work is avoided.
 // The gathering of the data will take a long time otherwise, and will consume
 // memory.
 long traceGroups = MQeTrace.GROUP_USER_DEFINED_4;
 
 if (MQeTrace.passesFilter(traceGroups)) {
     String data = collectLotsOfDataToTrace();
 
     MQeTrace.trace(this, (short) 0, traceGroups, data);
 }        
 
 

Websphere MQ Everyplace