Class Tr
- java.lang.Object
-
- com.ibm.websphere.ras.Tr
-
public class Tr extends java.lang.Object
This class provides the public interface to the message and trace logging facility.A Message is an informational record that is output to the console. Messages must use localization (national language) support. The caller must supply a message key and appropriate substitution parameters when the request to log a message is made. The national language support of the runtime will find the message text corresponding to the message key in the appropriate message properties file and will format the message with the supplied substitution parameters before displaying the message to the end user.
A Trace entry is an informational record that is intended to be used by developers and service personnel. As such, a trace record may be more complex or verbose than its message counterpart and may contain information that is meaningful only to a developer. Neither localization support nor Java TextMessage formatting is provided for trace entries. The text passed by the caller is treated as raw text. Parameters passed by the caller are not treated as substitution parameters and are displayed in a manner that individual trace delegates deem appropriate (typically through use of toString()).
Translated message generation is provided through the following set of static final convenience methods. See the documentation for the individual methods for usage detail.
info(...)
audit(...)
warning(...)
error(...)
fatal(...)
entry(...)
exit(...)
debug(...)
dump(...)
event(...)
Before using these convenience methods, a component must register with this service via one of the
register()
methods and obtain aTraceComponent
object in return. The component registers by supplying aClass
. The caller may use the returnedTraceComponent
object to emit trace and messages from an individual class or from a logical component that spans multiple classes. The package qualified name of theClass
is obtained from theClass
object and used as the registration name. The registration name is used to determine whether messages and trace are enabled for that particular TraceComponent.This service also provides the ability to combine
TraceComponent
s into logical trace groups. These trace groups can be enabled or disabled (using configuration facilities) as a single entity, as can any singular component. Versions of theregister()
method are provided that allow the group name to be specified at register time.Once a
TraceComponent
is obtained by a caller, that caller can use the convenience methods provided by this service. TheTraceComponent
is a required parameter of the convenience methods.Here are two simple usage examples. The first demonstrates how to register a class with the trace manager and the second demonstrates how to generate a debug trace call.
private static TraceComponent tc = Tr.register(ComponentImpl.class, ComponentConstants.TRACE_GROUP, ComponentConstants.NLS_BUNDLE);
...if (tc.isDebugEnabled()) Tr.debug(tc, "Hello from the trace system.");
-
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static void
audit(TraceComponent tc, java.lang.String msgKey, java.lang.Object... objs)
Print the provided translated message if the input trace component allows audit level messages.static void
debug(TraceComponent tc, java.lang.String msg, java.lang.Object... objs)
If debug level diagnostic trace is enabled for the specifiedTraceComponent
, log the provided trace point.static void
debug(java.lang.Object id, TraceComponent tc, java.lang.String msg, java.lang.Object... objs)
If debug level diagnostic trace is enabled for the specifiedTraceComponent
, log the provided trace point.static void
dump(TraceComponent tc, java.lang.String msg, java.lang.Object... objs)
Print the provided trace point if the input trace component allows dump level messages.static void
entry(TraceComponent tc, java.lang.String methodName, java.lang.Object... objs)
Print the provided trace point if the input trace component allows entry level messages.static void
entry(java.lang.Object id, TraceComponent tc, java.lang.String methodName, java.lang.Object... objs)
Print the provided trace point if the input trace component allows entry level messages.static void
error(TraceComponent tc, java.lang.String msgKey, java.lang.Object... objs)
Print the provided translated message if the input trace component allows error level messages.static void
event(TraceComponent tc, java.lang.String msg, java.lang.Object... objs)
Print the provided trace point if the input trace component allows event level messages.static void
event(java.lang.Object id, TraceComponent tc, java.lang.String msg, java.lang.Object... objs)
Print the provided trace point if the input trace component allows event level messages.static void
exit(TraceComponent tc, java.lang.String methodName)
Print the provided trace point if the input trace component allows exit level messages.static void
exit(TraceComponent tc, java.lang.String methodName, java.lang.Object o)
Print the provided trace point if the input trace component allows exit level messages.static void
exit(java.lang.Object id, TraceComponent tc, java.lang.String methodName)
Print the provided trace point if the input trace component allows exit level messages.static void
exit(java.lang.Object id, TraceComponent tc, java.lang.String methodName, java.lang.Object o)
Print the provided trace point if the input trace component allows exit level messages.static void
fatal(TraceComponent tc, java.lang.String msgKey, java.lang.Object... objs)
Print the provided translated message if the input trace component allows fatal level messages.static java.lang.String
formatMessage(TraceComponent tc, java.lang.String msgKey, java.lang.Object... objs)
Translate a message in the context of the input trace component using the default locale.static java.lang.String
formatMessage(TraceComponent tc, java.util.Enumeration<java.util.Locale> locales, java.lang.String msgKey, java.lang.Object... objs)
LikeformatMessage(TraceComponent, List, String, Object...)
, but takes an Enumeration of Locales.static java.lang.String
formatMessage(TraceComponent tc, java.util.List<java.util.Locale> locales, java.lang.String msgKey, java.lang.Object... objs)
Translate a message in the context of the input trace component.static java.lang.String
formatMessage(TraceComponent tc, java.util.Locale locale, java.lang.String msgKey, java.lang.Object... objs)
LikeformatMessage(TraceComponent, List, String, Object...)
, but takes a single Locale.static void
info(TraceComponent tc, java.lang.String msgKey, java.lang.Object... objs)
Print the provided translated message if the input trace component allows info level messages.static TraceComponent
register(java.lang.Class<?> aClass)
Register the provided class with the trace service.static TraceComponent
register(java.lang.Class<?> aClass, java.lang.String group)
Register the provided class with the trace service and assign it to the provided group name.static TraceComponent
register(java.lang.Class<?> aClass, java.lang.String group, java.lang.String bundle)
Register the provided class with the trace service and assign it to the provided group name.static TraceComponent
register(java.lang.String name, java.lang.Class<?> aClass, java.lang.String group)
Register the provided name with the trace service and assign it to the provided group name.static TraceComponent
register(java.lang.String name, java.lang.Class<?> aClass, java.lang.String[] groups)
Register the provided name with the trace service and assign it to the provided groups.static TraceComponent
register(java.lang.String name, java.lang.Class<?> aClass, java.lang.String[] groups, java.lang.String bundle)
Register the provided name with the trace service and assign it to the provided groups.static TraceComponent
register(java.lang.String name, java.lang.Class<?> aClass, java.lang.String group, java.lang.String bundle)
Register the provided name with the trace service and assign it to the provided group name.static void
warning(TraceComponent tc, java.lang.String msgKey, java.lang.Object... objs)
Print the provided translated message if the input trace component allows warning level messages.
-
-
-
Method Detail
-
register
public static TraceComponent register(java.lang.Class<?> aClass)
Register the provided class with the trace service. This method will look for a trace group name, list of trace group names, and a message bundle name specified through theTraceOptions
annotation. The annotation can be specified at the class and/or the package level; the class-level annotation will be given priority. If both traceGroup and traceGroups are specified, traceGroups will be given priority.- Parameters:
aClass
- a validClass
to register a component for with the trace manager. The className is obtained from the Class and is used as the name in the registration process.- Returns:
- TraceComponent the
TraceComponent
corresponding to the name of the specified class.
-
register
public static TraceComponent register(java.lang.String name, java.lang.Class<?> aClass, java.lang.String group)
Register the provided name with the trace service and assign it to the provided group name.- Parameters:
name
- aString
to register a component for with the trace manager. The name is used in the registration process.aClass
- a validClass
to register a component for with the trace manager. The class is used for location of resource bundles.group
- the name of the group that the named component is a member of. Null is allowed. If null is passed, the name is not added to a group. Once added to a group, there is no corresponding mechanism to remove a component from a group.- Returns:
- TraceComponent the
TraceComponent
corresponding to the name of the specified name.
-
register
public static TraceComponent register(java.lang.String name, java.lang.Class<?> aClass, java.lang.String[] groups)
Register the provided name with the trace service and assign it to the provided groups.- Parameters:
name
- aString
to register a component for with the trace manager. The name is used in the registration process.aClass
- a validClass
to register a component for with the trace manager. The class is used for location of resource bundles.groups
- a list of the groups that the named component is a member of. Null is allowed. If null is passed, the name is not added to a group. Once added to a group, there is no corresponding mechanism to remove a component from a group.- Returns:
- TraceComponent the
TraceComponent
corresponding to the name of the specified name.
-
register
public static TraceComponent register(java.lang.Class<?> aClass, java.lang.String group)
Register the provided class with the trace service and assign it to the provided group name.- Parameters:
aClass
- a validClass
to register a component for with the trace manager. The className is obtained from the Class and is used as the name in the registration process.group
- the name of the group that the named component is a member of. Null is allowed. If null is passed, the name is not added to a group. Once added to a group, there is no corresponding mechanism to remove a component from a group.- Returns:
- TraceComponent the
TraceComponent
corresponding to the name of the specified class.
-
register
public static TraceComponent register(java.lang.Class<?> aClass, java.lang.String group, java.lang.String bundle)
Register the provided class with the trace service and assign it to the provided group name. Translated messages will attempt to use the input message bundle source.- Parameters:
aClass
- a validClass
to register a component for with the trace manager. The className is obtained from the Class and is used as the name in the registration process.group
- the name of the group that the named component is a member of. Null is allowed. If null is passed, the name is not added to a group. Once added to a group, there is no corresponding mechanism to remove a component from a group.bundle
- the name of the message properties file to use when providing national language support for messages logged by this component. All messages for this component must be found in this file.- Returns:
- TraceComponent the
TraceComponent
corresponding to the name of the specified class.
-
register
public static TraceComponent register(java.lang.String name, java.lang.Class<?> aClass, java.lang.String group, java.lang.String bundle)
Register the provided name with the trace service and assign it to the provided group name. Translated messages will attempt to use the input message bundle source.- Parameters:
name
- aString
to register a component for with the trace manager. The name is used in the registration process.aClass
- a validClass
to register a component for with the trace manager. The class is used for location of resource bundles.group
- the name of the group that the named component is a member of. Null is allowed. If null is passed, the name is not added to a group. Once added to a group, there is no corresponding mechanism to remove a component from a group.bundle
- the name of the message properties file to use when providing national language support for messages logged by this component. All messages for this component must be found in this file.- Returns:
- TraceComponent the
TraceComponent
corresponding to the name of the specified name.
-
register
public static TraceComponent register(java.lang.String name, java.lang.Class<?> aClass, java.lang.String[] groups, java.lang.String bundle)
Register the provided name with the trace service and assign it to the provided groups. Translated messages will attempt to use the input message bundle source.- Parameters:
name
- aString
to register a component for with the trace manager. The name is used in the registration process.aClass
- a validClass
to register a component for with the trace manager. The class is used for location of resource bundles.groups
- the name of the groups that the named component is a member of. Null is allowed. If null is passed, the name is not added to a group. Once added to a group, there is no corresponding mechanism to remove a component from a group.bundle
- the name of the message properties file to use when providing national language support for messages logged by this component. All messages for this component must be found in this file.- Returns:
- TraceComponent the
TraceComponent
corresponding to the name of the specified name.
-
audit
public static final void audit(TraceComponent tc, java.lang.String msgKey, java.lang.Object... objs)
Print the provided translated message if the input trace component allows audit level messages.- Parameters:
tc
- the non-nullTraceComponent
the event is associated with.msgKey
- the message key identifying an NLS message for this event. This message must be in the resource bundle currently associated with theTraceComponent
.objs
- a number ofObjects
to include as substitution text in the message. The number of objects passed must equal the number of substitution parameters the message expects. Null is tolerated.
-
debug
public static final void debug(TraceComponent tc, java.lang.String msg, java.lang.Object... objs)
If debug level diagnostic trace is enabled for the specifiedTraceComponent
, log the provided trace point.- Parameters:
tc
- the non-nullTraceComponent
the event is associated with.msg
- text to include in the event. No translation or conversion is performed.objs
- a variable number (zero to n) ofObjects
. toString() is called on each object and the results are appended to the message.
-
debug
public static final void debug(java.lang.Object id, TraceComponent tc, java.lang.String msg, java.lang.Object... objs)
If debug level diagnostic trace is enabled for the specifiedTraceComponent
, log the provided trace point.- Parameters:
id
- The object writing the trace point; this will be output into the tracetc
- the non-nullTraceComponent
the event is associated with. as the identity hashcode of the object encoded into Hexmsg
- text to include in the event. No translation or conversion is performed.objs
- a variable number (zero to n) ofObjects
. toString() is called on each object and the results are appended to the message.
-
dump
public static final void dump(TraceComponent tc, java.lang.String msg, java.lang.Object... objs)
Print the provided trace point if the input trace component allows dump level messages.- Parameters:
tc
- the non-nullTraceComponent
the event is associated with.msg
- text to include in the event. No translation or conversion is performed.objs
- a variable number (zero to n) ofObjects
. toString() is called on each object and the results are appended to the message.
-
entry
public static final void entry(TraceComponent tc, java.lang.String methodName, java.lang.Object... objs)
Print the provided trace point if the input trace component allows entry level messages.- Parameters:
tc
- the non-nullTraceComponent
the event is associated with.methodName
-objs
- a variable number (zero to n) ofObjects
. toString() is called on each object and the results are appended to the message.
-
entry
public static final void entry(java.lang.Object id, TraceComponent tc, java.lang.String methodName, java.lang.Object... objs)
Print the provided trace point if the input trace component allows entry level messages.- Parameters:
id
- The object writing the trace point; this will be output into the tracetc
- the non-nullTraceComponent
the event is associated with. as the identity hashcode of the object encoded into HexmethodName
-objs
- a variable number (zero to n) ofObjects
. toString() is called on each object and the results are appended to the message.
-
error
public static final void error(TraceComponent tc, java.lang.String msgKey, java.lang.Object... objs)
Print the provided translated message if the input trace component allows error level messages.- Parameters:
tc
- the non-nullTraceComponent
the event is associated with.msgKey
- the message key identifying an NLS message for this event. This message must be in the resource bundle currently associated with theTraceComponent
.objs
- a number ofObjects
to include as substitution text in the message. The number of objects passed must equal the number of substitution parameters the message expects. Null is tolerated.
-
event
public static final void event(TraceComponent tc, java.lang.String msg, java.lang.Object... objs)
Print the provided trace point if the input trace component allows event level messages.- Parameters:
tc
- the non-nullTraceComponent
the event is associated with.msg
- text to include in the event. No translation or conversion is performed.objs
- a variable number (zero to n) ofObjects
. toString() is called on each object and the results are appended to the message.
-
event
public static final void event(java.lang.Object id, TraceComponent tc, java.lang.String msg, java.lang.Object... objs)
Print the provided trace point if the input trace component allows event level messages.- Parameters:
id
- The object writing the trace point; this will be output into the tracetc
- the non-nullTraceComponent
the event is associated with. as the identity hashcode of the object encoded into Hexmsg
- text to include in the event. No translation or conversion is performed.objs
- a variable number (zero to n) ofObjects
. toString() is called on each object and the results are appended to the message.
-
exit
public static final void exit(TraceComponent tc, java.lang.String methodName)
Print the provided trace point if the input trace component allows exit level messages.- Parameters:
tc
- the non-nullTraceComponent
the event is associated with.methodName
-
-
exit
public static final void exit(java.lang.Object id, TraceComponent tc, java.lang.String methodName)
Print the provided trace point if the input trace component allows exit level messages.- Parameters:
id
- The object writing the trace point; this will be output into the tracetc
- the non-nullTraceComponent
the event is associated with. as the identity hashcode of the object encoded into HexmethodName
-objs
-
-
exit
public static final void exit(TraceComponent tc, java.lang.String methodName, java.lang.Object o)
Print the provided trace point if the input trace component allows exit level messages.- Parameters:
tc
- the non-nullTraceComponent
the event is associated with.methodName
-o
-
-
exit
public static final void exit(java.lang.Object id, TraceComponent tc, java.lang.String methodName, java.lang.Object o)
Print the provided trace point if the input trace component allows exit level messages.- Parameters:
id
- The object writing the trace point; this will be output into the tracetc
- the non-nullTraceComponent
the event is associated with. as the identity hashcode of the object encoded into HexmethodName
-o
-
-
fatal
public static final void fatal(TraceComponent tc, java.lang.String msgKey, java.lang.Object... objs)
Print the provided translated message if the input trace component allows fatal level messages.- Parameters:
tc
- the non-nullTraceComponent
the event is associated with.msgKey
- the message key identifying an NLS message for this event. This message must be in the resource bundle currently associated with theTraceComponent
.objs
- a number ofObjects
to include as substitution text in the message. The number of objects passed must equal the number of substitution parameters the message expects. Null is tolerated.
-
info
public static final void info(TraceComponent tc, java.lang.String msgKey, java.lang.Object... objs)
Print the provided translated message if the input trace component allows info level messages.- Parameters:
tc
- the non-nullTraceComponent
the event is associated with.msgKey
- the message key identifying an NLS message for this event. This message must be in the resource bundle currently associated with theTraceComponent
.objs
- a number ofObjects
to include as substitution text in the message. The number of objects passed must equal the number of substitution parameters the message expects. Null is tolerated.
-
warning
public static final void warning(TraceComponent tc, java.lang.String msgKey, java.lang.Object... objs)
Print the provided translated message if the input trace component allows warning level messages.- Parameters:
tc
- the non-nullTraceComponent
the event is associated with.msgKey
- the message key identifying an NLS message for this event. This message must be in the resource bundle currently associated with theTraceComponent
.objs
- a number ofObjects
to include as substitution text in the message. The number of objects passed must equal the number of substitution parameters the message expects. Null is tolerated.
-
formatMessage
public static final java.lang.String formatMessage(TraceComponent tc, java.lang.String msgKey, java.lang.Object... objs)
Translate a message in the context of the input trace component using the default locale. This method is typically used to provide translated messages that might help resolve an exception that is surfaced to a user.- Parameters:
tc
- the non-nullTraceComponent
of the messagemsgKey
- the message key identifying an NLS message for this event. This message must be in the resource bundle currently associated with theTraceComponent
.objs
- a number ofObjects
to include as substitution text in the message. The number of objects passed must equal the number of substitution parameters the message expects. Null is tolerated.- Returns:
- the translated message
-
formatMessage
public static java.lang.String formatMessage(TraceComponent tc, java.util.Locale locale, java.lang.String msgKey, java.lang.Object... objs)
LikeformatMessage(TraceComponent, List, String, Object...)
, but takes a single Locale.
-
formatMessage
public static java.lang.String formatMessage(TraceComponent tc, java.util.Enumeration<java.util.Locale> locales, java.lang.String msgKey, java.lang.Object... objs)
LikeformatMessage(TraceComponent, List, String, Object...)
, but takes an Enumeration of Locales.
-
formatMessage
public static final java.lang.String formatMessage(TraceComponent tc, java.util.List<java.util.Locale> locales, java.lang.String msgKey, java.lang.Object... objs)
Translate a message in the context of the input trace component. This method is typically used to provide translated messages that might help resolve an exception that is surfaced to a user.- Parameters:
tc
- the non-nullTraceComponent
of the messagelocales
- the possible locales to use for translation. Locales from the front of the list are preferred over Locales from the back of the list. If the list is null or empty, the default Locale will be used.msgKey
- the message key identifying an NLS message for this event. This message must be in the resource bundle currently associated with theTraceComponent
.objs
- a number ofObjects
to include as substitution text in the message. The number of objects passed must equal the number of substitution parameters the message expects. Null is tolerated.- Returns:
- the translated message
-
-