Package com.composum.sling.core.logging

Class Message

  • All Implemented Interfaces:
    Cloneable
    public class Message
extends Object
implements Cloneable
    A container for a message, e.g. about internal processes, that can be presented to the user. It could be localized, and there might be details which can be suppressed, depending on the user / user settings or choices.

    For proper i18n in JSON serialization you need to register MessageTypeAdapterFactory(SlingHttpServletRequest) with GsonBuilder.registerTypeAdapterFactory(TypeAdapterFactory). The default JsonAdapter is just a fallback that uses no i18n. CAUTION: careful when extending this class - the MessageTypeAdapterFactory might not work for derived classes.

    • Field Detail

      • logLevel

        @Nullable
protected @Nullable Message.Level logLevel
        The level at which this message is logged, if different from level. This might be transient, but we make it non-transient because messages might be transmitted to a remote system and logged there again.
        See Also:
        getLogLevel()

      • text

        protected String text
        If set, an i18n-ed version of rawText with all placeholders replaced. This is modified during JSON-serialization.

      • rawText

        protected String rawText
        The raw version of the text which can contain {}-placeholders and is used as i18n-key.

      • path

        @Nullable
protected @Nullable String path
        Optional resource path this message is about.

    • Constructor Detail

      • Message

        @Deprecated
public Message()
        Deprecated.
        only for JSON deserialization.

      • Message

        public Message​(@Nullable
               @Nullable Message.Level level,
               @NotNull
               @NotNull String rawText,
               Object... arguments)
        Creates a message.
        Parameters:
        level - the level of the message, default info(java.lang.String, java.lang.Object...)
        rawText - the untranslated text of message, possibly with placeholders {} for arguments
        arguments - optional arguments placed in placeholders. Caution: must be primitive types if this is to be transmitted with JSON!

    • Method Detail

      • error

        @NotNull
public static @NotNull Message error​(@NotNull
                                     @NotNull String text,
                                     Object... arguments)
        Convenience-method - constructs with error(java.lang.String, java.lang.Object...).
        Parameters:
        text - the untranslated text of message, possibly with placeholders {} for arguments
        arguments - optional arguments placed in placeholders. Caution: must be primitive types if this is to be transmitted with JSON!

      • validationError

        public static Message validationError​(@Nullable
                                      @Nullable String context,
                                      @Nullable
                                      @Nullable String label,
                                      @NotNull
                                      @NotNull String text,
                                      Object... args)
        Convenience-method - constructs a validation message (which is logged only at level debug) with error(java.lang.String, java.lang.Object...).
        Parameters:
        context - an optional context of the message, such as the dialog tab in a validation message.
        label - an optional: label of the field which the message is about, primarily in validation messages.
        text - the untranslated text of message, possibly with placeholders {} for arguments
        arguments - optional arguments placed in placeholders. Caution: must be primitive types if this is to be transmitted with JSON!

      • warn

        @NotNull
public static @NotNull Message warn​(@NotNull
                                    @NotNull String text,
                                    Object... arguments)
        Convenience-method - constructs with warn(java.lang.String, java.lang.Object...).
        Parameters:
        text - the untranslated text of message, possibly with placeholders {} for arguments
        arguments - optional arguments placed in placeholders. Caution: must be primitive types if this is to be transmitted with JSON!

      • validationWarn

        public static Message validationWarn​(@Nullable
                                     @Nullable String context,
                                     @Nullable
                                     @Nullable String label,
                                     @NotNull
                                     @NotNull String text,
                                     Object... args)
        Convenience-method - constructs a validation message (which is logged only at level debug) with warn(java.lang.String, java.lang.Object...).
        Parameters:
        context - an optional context of the message, such as the dialog tab in a validation message.
        label - an optional: label of the field which the message is about, primarily in validation messages.
        text - the untranslated text of message, possibly with placeholders {} for arguments
        arguments - optional arguments placed in placeholders. Caution: must be primitive types if this is to be transmitted with JSON!

      • info

        @NotNull
public static @NotNull Message info​(@NotNull
                                    @NotNull String text,
                                    Object... arguments)
        Convenience-method - constructs with info(java.lang.String, java.lang.Object...).
        Parameters:
        text - the untranslated text of message, possibly with placeholders {} for arguments
        arguments - optional arguments placed in placeholders. Caution: must be primitive types if this is to be transmitted with JSON!

      • validationInfo

        public static Message validationInfo​(@Nullable
                                     @Nullable String context,
                                     @Nullable
                                     @Nullable String label,
                                     @NotNull
                                     @NotNull String text,
                                     Object... args)
        Convenience-method - constructs a validation message (which is logged only at level debug) with info(java.lang.String, java.lang.Object...).
        Parameters:
        context - an optional context of the message, such as the dialog tab in a validation message.
        label - an optional: label of the field which the message is about, primarily in validation messages.
        text - the untranslated text of message, possibly with placeholders {} for arguments
        arguments - optional arguments placed in placeholders. Caution: must be primitive types if this is to be transmitted with JSON!

      • debug

        @NotNull
public static @NotNull Message debug​(@NotNull
                                     @NotNull String text,
                                     Object... arguments)
        Convenience-method - constructs with debug(java.lang.String, java.lang.Object...).
        Parameters:
        text - the untranslated text of message, possibly with placeholders {} for arguments
        arguments - optional arguments placed in placeholders. Caution: must be primitive types if this is to be transmitted with JSON!

      • addDetail

        @NotNull
public @NotNull Message addDetail​(@NotNull
                                  @NotNull Message detailMessage)
        Adds a detailmessage.
        Returns:
        this for builder style operation chaining.

      • getTimestampAsDate

        @Nullable
public @Nullable Date getTimestampAsDate()
        Time the message was created.

      • getLogLevel

        @Nullable
public @Nullable Message.Level getLogLevel()
        The level with which we will log the message if MessageContainer has a logger. Transient attribute - will not be transmitted in JSON. This can be different from the getLevel(), e.g. in the case of validation messages which should only be logged as debug. Message.Level.none means it will not be logged; null means that getLevel() is used.

      • setLogLevel

        @NotNull
public @NotNull Message setLogLevel​(@Nullable
                                    @Nullable Message.Level logLevel)
        Sets the level with which we will log the message if MessageContainer has a logger. Transient attribute - will not be transmitted in JSON. This can be different from the getLevel(), e.g. in the case of validation messages which should only be logged as debug. Message.Level.none means it will not be logged; null means that getLevel() is used.
        Returns:
        {this} for chaining calls in builder-style

      • getRawText

        @NotNull
public @NotNull String getRawText()
        The raw, un-i18n-ed, human readable message text, possibly with argument placeholders {}. If i18n is wanted, this is the key for the i18n - all variable parts should be put into the arguments. Mandatory part of a message.

      • getMessage

        public String getMessage​(@Nullable
                         @Nullable org.apache.sling.api.SlingHttpServletRequest request)
        Like getText(), but returns the text i18n-ed for the request and parameters replaced.

      • getPath

        @Nullable
public @Nullable String getPath()
        Optional resource path this message is about.

      • setPath

        @NotNull
public @NotNull Message setPath​(@Nullable
                                @Nullable String path)
        Sets the optional resource path this message is about, and returns this message for builder style construction.
        Returns:
        this

      • getArguments

        @NotNull
public @NotNull List<Object> getArguments()
        Optional arguments used in placeholders of the getText(). If transmission over JSON is needed, these must be serializable with GSON.

      • getCategory

        @Nullable
public @Nullable String getCategory()
        Can optionally be used to categorize messages for filtering / sorting. This is not meant to be shown directly to the user.

      • setCategory

        @NotNull
public @NotNull Message setCategory​(@Nullable
                                    @Nullable String category)
        Sets the optional category: can optionally be used to categorize messages for filtering / sorting. This is not meant to be shown directly to the user.
        Returns:
        this for builder style operation chaining.

      • getLabel

        @Nullable
public @Nullable String getLabel()
        Optional: label of the field which the message is about, primarily in validation messages. (Not the human-readable but the programmatical id is meant.)

      • setLabel

        @NotNull
public @NotNull Message setLabel​(@Nullable
                                 @Nullable String label)
        Sets the optional context: a label of the field which the message is about, primarily in validation messages. (Not the human-readable but the programmatical id is meant.)
        Returns:
        this for builder style operation chaining.

      • getContext

        @Nullable
public @Nullable String getContext()
        Optional: a context of the message, such as the dialog tab in a validation message. (Not the human-readable but the programmatical id is meant.)

      • setContext

        @NotNull
public @NotNull Message setContext​(@Nullable
                                   @Nullable String context)
        Sets a context: a context of the message, such as the dialog tab in a validation message. (Not the human-readable but the programmatical id is meant.)
        Returns:
        this for builder style operation chaining.

      • prepareForJsonSerialization

        protected Message prepareForJsonSerialization​(org.apache.sling.api.SlingHttpServletRequest request)
                                       throws CloneNotSupportedException
        Clones the Message and sets its text to a properly i18n-ed version, and also makes Strings out of non-String and non-Numeric arguments to avoid problems with not JSON serializable arguments.

        Tradeoff: keeping numbers is more efficient but GSON turns numbers into doubles on deserialization which sometimes creates differences when formatting is repeated on a serialized and deserialized Message.

        Throws:
        CloneNotSupportedException

      • logInto

        @NotNull
public @NotNull Message logInto​(@Nullable
                                @Nullable org.slf4j.Logger log)
        Logs the message into the specified logger. Can be done automatically by a MessageContainer if MessageContainer(Logger) is used.
        Parameters:
        log - the log to write the message into
        Returns:
        this message for builder-style operation-chaining.
        See Also:
        MessageContainer(Logger)

      • logInto

        @NotNull
public @NotNull Message logInto​(@Nullable
                                @Nullable org.slf4j.Logger log,
                                @Nullable
                                @Nullable Throwable cause)
        Logs the message into the specified logger, including the {cause}'s stacktrace. Can be done automatically by a MessageContainer if MessageContainer(Logger) is used.
        Parameters:
        log - the log to write the message into
        cause - optionally, an exception that is logged as a cause of the message
        Returns:
        this message for builder-style operation-chaining.

      • getThrowableArgument

        @Nullable
protected @Nullable Throwable getThrowableArgument()
        Return the last argument if it is a Throwable. This is the stacktrace logged if there was not given one with logInto(Logger, Throwable) explicitly. Compatible with slf4j: use last argument if it is an exception http://slf4j.org/faq.html#paramException

      • toFormattedMessage

        public String toFormattedMessage()
        Return a full text representation of the message with replaced arguments and appended details. Mainly for logging / debugging purposes. Not i18n-ed.