Websphere MQ Everyplace

com.ibm.mqe.trace
Class MQeTracePoint

java.lang.Object
  |
  +--com.ibm.mqe.trace.MQeTracePoint

public class MQeTracePoint
extends java.lang.Object

A collection of information which describes a particular trace point.

A trace point can belong to zero or more groups of trace points. The MQeTracePointGroup class is used to represent a group of these trace points.

A trace point can be added to a group, and groups can be added to a MQeTraceRenderer in order to convert a numeric trace point number and a collection of parameters into a readable text representation.

A single trace point is a mapping from a message number to a number of properties.

Tools can use this interface to convert trace information from MQe into readable text in a format of their choice.

Note that trace points can be warnings, errors, debug statements, jms trace statements, or all of them at the same time !

If you don't want to render MQeTraceHandler data to readable formats immediately, do not include this class in the application package you distribute, as it will not be required.

See Also:
MQeTracePointGroup, MQeTraceRenderer

Field Summary
static int MESSAGE_NUMBER_USER_DEFINED_MAXIMUM
          User-defined trace point numbers must be less than or equal to this number.
static int MESSAGE_NUMBER_USER_DEFINED_MINIMUM
          User-defined trace point numbers must be equal to or greater than this number.
static java.lang.String SUBSTITUTION_MARKER
          A sub-string in the template string which is used to indicate that a parameter can be substituted in place of this marker.
static java.lang.String UNKNOWN_SOURCE_CLASS_NAME
          The default source class name, used unless the source class name has been set explicitly.
static short UNKNOWN_SOURCE_LINE_NUMBER
          Default value if the source line number is not set explicitly.
static java.lang.String UNKNOWN_SOURCE_METHOD
          The default value for the source method name if it is not set explicitly.
static java.lang.String UNKNOWN_TEMPLATE
          The default value used for the trace template unless it is specifically set using the setTemplate(java.lang.String) method.
 
Constructor Summary
  MQeTracePoint(MQeTracePoint existingTracePoint)
          Clones an existing trace point object.
  MQeTracePoint(short messageNumber, java.lang.String template, java.lang.String sourceClassName, java.lang.String sourceMethod, short sourceLineNumber)
          Defines all the information in a trace point in a single command.
protected MQeTracePoint(short messageNumber, java.lang.String template, java.lang.String sourceClassName, java.lang.String sourceMethod, short sourceLineNumber, long groupsMask)
          Defines all the information in a trace point in a single command.
 
Method Summary
 java.lang.String getMessage(java.lang.Object[] args)
          Gets a readable message which has had parameters substituted into the trace template.
 short getMessageNumber()
          Gets the message number of this trace point.
 java.lang.String getSourceClassName()
          Gets the class name from which this trace point is issued.
 short getSourceLineNumber()
          Gets the line number in the source file from which this trace point was issued.
 java.lang.String getSourceMethod()
          Provides the method name in the java file where the trace point was issued from.
 java.lang.String getTemplate()
          Gets the trace template of this trace point.
 void setMessageNumber(short messageNumber)
          Sets the number of this trace point.
 void setSourceClassName(java.lang.String className)
          Sets the name of the class from which this trace point is issued.
 void setSourceLineNumber(short lineNumber)
          Sets the line number in the source file from which this trace point is issued.
 void setSourceMethod(java.lang.String methodName)
          Sets the method associated with this trace point.
 void setTemplate(java.lang.String template)
          Sets the message template of this trace point
 java.lang.String toString()
          Gets a readable form of all data contained in the MQeTracePoint
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

MESSAGE_NUMBER_USER_DEFINED_MINIMUM

public static final int MESSAGE_NUMBER_USER_DEFINED_MINIMUM
User-defined trace point numbers must be equal to or greater than this number.

IBM reserves the right to define any trace point below this number.

See Also:
Constant Field Values

MESSAGE_NUMBER_USER_DEFINED_MAXIMUM

public static final int MESSAGE_NUMBER_USER_DEFINED_MAXIMUM
User-defined trace point numbers must be less than or equal to this number.

IBM reserves the right to define any trace point above this number.

See Also:
Constant Field Values

SUBSTITUTION_MARKER

public static final java.lang.String SUBSTITUTION_MARKER
A sub-string in the template string which is used to indicate that a parameter can be substituted in place of this marker.

See Also:
Constant Field Values

UNKNOWN_SOURCE_CLASS_NAME

public static final java.lang.String UNKNOWN_SOURCE_CLASS_NAME
The default source class name, used unless the source class name has been set explicitly.

See Also:
Constant Field Values

UNKNOWN_SOURCE_LINE_NUMBER

public static final short UNKNOWN_SOURCE_LINE_NUMBER
Default value if the source line number is not set explicitly.

See Also:
Constant Field Values

UNKNOWN_SOURCE_METHOD

public static final java.lang.String UNKNOWN_SOURCE_METHOD
The default value for the source method name if it is not set explicitly.

See Also:
Constant Field Values

UNKNOWN_TEMPLATE

public static final java.lang.String UNKNOWN_TEMPLATE
The default value used for the trace template unless it is specifically set using the setTemplate(java.lang.String) method.

See Also:
Constant Field Values
Constructor Detail

MQeTracePoint

public MQeTracePoint(MQeTracePoint existingTracePoint)
              throws java.lang.NullPointerException
Clones an existing trace point object.

Parameters:
existingTracePoint - A reference to a trace point object which has already been constructed. A value of null will result in an exception.
Throws:
java.lang.NullPointerException - if the passed existingTracePoint parameter is null.

MQeTracePoint

protected MQeTracePoint(short messageNumber,
                        java.lang.String template,
                        java.lang.String sourceClassName,
                        java.lang.String sourceMethod,
                        short sourceLineNumber,
                        long groupsMask)
Defines all the information in a trace point in a single command.

Pass null for any of the string parameters for which no information is available.

Parameters:
messageNumber - A value indicating the number of this message. Use the setMessageNumber(short) method to over-write this value later if required.
template - A String punctuated by sub-strings. The getMessage(java.lang.Object[]) method will substitute a parameter where these marker strings appear in the template.
sourceClassName - The name of the class from which the trace point was issued.
sourceMethod - The method within the class from which the trace point was issued.
sourceLineNumber - The line number within the source file from at which the trace point is defined.
groupsMask - A long containing bit masks of the groups this message belongs to.

MQeTracePoint

public MQeTracePoint(short messageNumber,
                     java.lang.String template,
                     java.lang.String sourceClassName,
                     java.lang.String sourceMethod,
                     short sourceLineNumber)
Defines all the information in a trace point in a single command.

Pass null for any of the string parameters for which no information is available.

Parameters:
messageNumber - A value indicating the number of this message. Use the setMessageNumber(short) method to overwrite this value later if required.
template - A String punctuated by SUBSTITUTION_MARKER sub-strings. The getMessage(java.lang.Object[]) method will substitute a parameter where these marker strings appear in the template.
sourceClassName - The name of the class from which the trace point was issued.
sourceMethod - The method within the class from which the trace point was issued.
sourceLineNumber - The line number within the source file from at which the trace point is defined.
Method Detail

getMessageNumber

public short getMessageNumber()
Gets the message number of this trace point.

Returns:
The message number of this trace point.

setMessageNumber

public void setMessageNumber(short messageNumber)
Sets the number of this trace point.

Parameters:
messageNumber - the number of this trace message. User code must be within the range from USER_DEFINED_MESSAGE_NUMBER_MINIMUM to USER_DEFINED_MESSAGE_NUMBER_MAXIMUM (inclusive).

IBM reserves the right to use any trace point numbers outside of this range.

Returns:
void

getTemplate

public java.lang.String getTemplate()
Gets the trace template of this trace point.

Returns:
A java.lang.String contains the text string relating to the specified trace point number. If no string for that number can be found, a null is returned.

setTemplate

public void setTemplate(java.lang.String template)
Sets the message template of this trace point

Parameters:
template - If a value of null is passed, the template will be set to the default value of UNKNOWN_TEMPLATE
Returns:
void

getSourceMethod

public java.lang.String getSourceMethod()
Provides the method name in the java file where the trace point was issued from.

For example, if the trace point were defined in the MQeQueueManager file, within the putMessage() method, then the returned string will be "putMessage".

Returns:
A java.lang.String Contains the name of the method in which the trace statement was defined. This relies provided the correct name of the method was put in the trace point definition. UNKNOWN_SOURCE_METHOD will be returned if the trace point did not contain any method information.

setSourceMethod

public void setSourceMethod(java.lang.String methodName)
Sets the method associated with this trace point.

Retrieve this value using the getSourceMethod() method.

Parameters:
methodName - The name of the method from which this trace point is issued. If null is specified, the UNKNOWN_SOURCE_METHOD value is used as a default.
Returns:
void
See Also:
getSourceMethod()

setSourceClassName

public void setSourceClassName(java.lang.String className)
Sets the name of the class from which this trace point is issued.

Parameters:
className - The name of the class is the fully-qualified package followed by the name of the class, excluding any ".class" file extension. A null value passed will set the value held to the default of UNKNOWN_SOURCE_CLASS_NAME.
Returns:
void

getSourceClassName

public java.lang.String getSourceClassName()
Gets the class name from which this trace point is issued.

Returns:
className The name of the class from which the trace point is issued. It consists of the fully-qualified package, followed by the name of the class, * excluding any ".class" file extension. This relies on the correct class name being put into the trace point definition. UNKNOWN_SOURCE_CLASS_NAME will be returned if the trace point did not contain any class information.

setSourceLineNumber

public void setSourceLineNumber(short lineNumber)
Sets the line number in the source file from which this trace point is issued.

Parameters:
lineNumber - The line number in the source file from which the trace point is issued in code.
Returns:
void

getSourceLineNumber

public short getSourceLineNumber()
Gets the line number in the source file from which this trace point was issued.

Returns:
A number indicating the line number at which the trace point is issued in a source code file. This relies on the correct line number being put into the trace point definition. UNKNOWN_SOURCE_LINE_NUMBER will be returned if the trace point did not contain a line number.

toString

public java.lang.String toString()
Gets a readable form of all data contained in the MQeTracePoint

Overrides:
toString in class java.lang.Object
Returns:
A text string containing all properties concerning this trace point.

getMessage

public java.lang.String getMessage(java.lang.Object[] args)
Gets a readable message which has had parameters substituted into the trace template.

Parameters:
args - An array of objects. Each object in the array will have its toString() method invoked. The result will be substituted for a SUBSTITUTION_MARKER
Returns:
The trace point template with any substitution markers replaced by the toString() value of the corresponding argument. If there are too many arguments, then this uses the first few arguments those which have matching #s and the rest is ignored. If there are too few arguments, then the excess #s are retained as they are.

Websphere MQ Everyplace