Class 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(...)
    Untranslated diagnosic trace generation is provided through the following set of static final convenience methods. See the documentation for the individual methods for usage detail.
    • 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 a TraceComponent object in return. The component registers by supplying a Class. The caller may use the returned TraceComponent object to emit trace and messages from an individual class or from a logical component that spans multiple classes. The package qualified name of the Class is obtained from the Class 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 the register() 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. The TraceComponent 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 specified TraceComponent, 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 specified TraceComponent, 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)
      Like formatMessage(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)
      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[] groups, java.lang.String bundle, java.lang.String name)
      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.
      • Methods inherited from class java.lang.Object

        equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • 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 the TraceOptions 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.

        This method should be used statically as a private final global element in the target class
        For example:
        public class Example {
        private final static TraceComponent tc = Tr.register( ... );
        ...
        }
        Parameters:
        aClass - a valid Class 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.

        This method should be used statically as a private final global element in the target class
        For example:
        public class Example {
        private final static TraceComponent tc = Tr.register( ... );
        ...
        }
        Parameters:
        name - a String to register a component for with the trace manager. The name is used in the registration process.
        aClass - a valid Class 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.

        This method should be used statically as a private final global element in the target class
        For example:
        public class Example {
        private final static TraceComponent tc = Tr.register( ... );
        ...
        }
        Parameters:
        name - a String to register a component for with the trace manager. The name is used in the registration process.
        aClass - a valid Class 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.

        This method should be used statically as a private final global element in the target class
        For example:
        public class Example {
        private final static TraceComponent tc = Tr.register( ... );
        ...
        }
        Parameters:
        aClass - a valid Class 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.

        This method should be used statically as a private final global element in the target class
        For example:
        public class Example {
        private final static TraceComponent tc = Tr.register( ... );
        ...
        }
        Parameters:
        aClass - a valid Class 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.Class<?> aClass,
                                              java.lang.String[] groups,
                                              java.lang.String bundle,
                                              java.lang.String name)
        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.

        This method should be used statically as a private final global element in the target class
        For example:
        public class Example {
        private final static TraceComponent tc = Tr.register( ... );
        ...
        }
        Parameters:
        aClass - a valid Class 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.
        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 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.

        This method should be used statically as a private final global element in the target class
        For example:
        public class Example {
        private final static TraceComponent tc = Tr.register( ... );
        ...
        }
        Parameters:
        name - a String to register a component for with the trace manager. The name is used in the registration process.
        aClass - a valid Class 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.

        This method should be used statically as a private final global element in the target class
        For example:
        public class Example {
        private final static TraceComponent tc = Tr.register( ... );
        ...
        }
        Parameters:
        name - a String to register a component for with the trace manager. The name is used in the registration process.
        aClass - a valid Class 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-null TraceComponent 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 the TraceComponent.
        objs - a number of Objects 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 specified TraceComponent, log the provided trace point.
        Parameters:
        tc - the non-null TraceComponent 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) of Objects. 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 specified TraceComponent, log the provided trace point.
        Parameters:
        id - The object writing the trace point; this will be output into the trace
        tc - the non-null TraceComponent the event is associated with. as the identity hashcode of the object encoded into Hex
        msg - text to include in the event. No translation or conversion is performed.
        objs - a variable number (zero to n) of Objects. 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-null TraceComponent 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) of Objects. 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-null TraceComponent the event is associated with.
        methodName -
        objs - a variable number (zero to n) of Objects. 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 trace
        tc - the non-null TraceComponent the event is associated with. as the identity hashcode of the object encoded into Hex
        methodName -
        objs - a variable number (zero to n) of Objects. 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-null TraceComponent 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 the TraceComponent.
        objs - a number of Objects 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-null TraceComponent 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) of Objects. 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 trace
        tc - the non-null TraceComponent the event is associated with. as the identity hashcode of the object encoded into Hex
        msg - text to include in the event. No translation or conversion is performed.
        objs - a variable number (zero to n) of Objects. 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-null TraceComponent 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 trace
        tc - the non-null TraceComponent the event is associated with. as the identity hashcode of the object encoded into Hex
        methodName -
        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-null TraceComponent 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 trace
        tc - the non-null TraceComponent the event is associated with. as the identity hashcode of the object encoded into Hex
        methodName -
        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-null TraceComponent 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 the TraceComponent.
        objs - a number of Objects 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-null TraceComponent 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 the TraceComponent.
        objs - a number of Objects 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-null TraceComponent 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 the TraceComponent.
        objs - a number of Objects 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-null TraceComponent of the message
        msgKey - the message key identifying an NLS message for this event. This message must be in the resource bundle currently associated with the TraceComponent.
        objs - a number of Objects 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 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-null TraceComponent of the message
        locales - 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 the TraceComponent.
        objs - a number of Objects 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