|
Websphere MQ Everyplace | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--com.ibm.mqe.MQeTrace
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.
// // 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 |
public static final short TRACE_NUMBER_USER_DEFINED_MIN
IBM reserves the right to define of all trace point numbers below this value.
public static final short TRACE_NUMBER_USER_DEFINED_MAX
IBM reserves the right to define of all trace point numbers below this value.
public static final long GROUP_MASK_NONE
Useful when using the setFilter(long)
method, so that all
tracing is filtered-out at run time.
// // 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); }
public static final long GROUP_ERROR
// // 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 ); }
public static final long GROUP_WARNING
public static final long GROUP_ENTRY
public static final long GROUP_EXIT
public static final long GROUP_ADAPTER_CALLING
public static final long GROUP_ADAPTER_RETURNED
public static final long GROUP_RULE_CALLING
public static final long GROUP_RULE_RETURNED
public static final long GROUP_BRIDGE
public static final long GROUP_COMMS_OUTGOING
public static final long GROUP_CHANNEL_MANAGEMENT
public static final long GROUP_MESSAGE_STATE
public static final long GROUP_THREAD_CONTROL
public static final long GROUP_MESSAGE_STORE
public static final long GROUP_ADMINISTRATION
public static final long GROUP_EXCEPTION
// // 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 ); }
public static final long GROUP_JMS
public static final long GROUP_SECURITY
public static final long GROUP_COMMS_INCOMING
public static final long GROUP_TRANSACTION
public static final long GROUP_API
Will often be used in conjunction with the GROUP_ENTRY
and GROUP_EXIT
// // 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); }
public static final long GROUP_INFO
public static final long GROUP_QUEUE_MANAGER
public static final long GROUP_MQSERIES
public static final long GROUP_MASK_USER_DEFINED
IBM will not define any groups which clash with these bits.
public static final long GROUP_USER_DEFINED_1
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.
// // 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 ); }
public static final long GROUP_USER_DEFINED_2
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.
public static final long GROUP_USER_DEFINED_3
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.
public static final long GROUP_USER_DEFINED_4
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.
public static final long GROUP_MASK_IBM_DEFINED
User code should not trace information using these bits.
public static final long GROUP_MASK_ALL
Useful when using the setFilter(long)
method, so that no tracing
is filtered out at run time.
// // Demonstrates how the trace filter can be set to prevent filtering of any trace information. // void traceOn() { MQeTrace.setFilter(MQeTrace.GROUP_MASK_ALL); }
public static final long GROUP_MASK_DEFAULT
The default is all trace groups are turned on, except the MQSERIES trace group.
Use the setFilter(long)
to over-ride the default.
Constructor Detail |
public MQeTrace()
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 |
public static MQeTraceHandler setHandler(MQeTraceHandler newTraceHandler)
A reference to the trace handler previously set can be obtained using the
getHandler()
method.
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.
getHandler()
,
trace(java.lang.Object, short, long)
// // 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); }
public static MQeTraceHandler getHandler()
The trace handler was previously set using the setHandler(com.ibm.mqe.MQeTraceHandler)
method.
setHandler(com.ibm.mqe.MQeTraceHandler)
// // 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; }
public static void setFilter(long mask)
mask
- A bit mask against which all trace information is compared, to see whether that
trace information is suppressed or not.getFilter()
// // 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); }
public static long getFilter()
MQeTraceHandler
// // 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); }
public static void trace(java.lang.Object selfReference, short tracePointNumber, long groups)
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.
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.setHandler(com.ibm.mqe.MQeTraceHandler)
,
getHandler()
public static void trace(java.lang.Object selfReference, short tracePointNumber, long groups, java.lang.Object p1)
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.
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()
setHandler(com.ibm.mqe.MQeTraceHandler)
,
getHandler()
// // 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 ); }
public static void trace(java.lang.Object selfReference, short tracePointNumber, long groups, java.lang.Object p1, java.lang.Object p2)
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.
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()
setHandler(com.ibm.mqe.MQeTraceHandler)
,
getHandler()
public static void trace(java.lang.Object selfReference, short tracePointNumber, long groups, java.lang.Object p1, java.lang.Object p2, java.lang.Object p3)
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.
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()
setHandler(com.ibm.mqe.MQeTraceHandler)
,
getHandler()
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)
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.
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()
setHandler(com.ibm.mqe.MQeTraceHandler)
,
getHandler()
public static boolean passesFilter(long groups)
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.
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.// // 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 | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |