Class FailureItem

  • All Implemented Interfaces:
    Serializable, org.joda.beans.Bean, org.joda.beans.ImmutableBean

    public final class FailureItem
    extends Object
    implements org.joda.beans.ImmutableBean, Serializable
    Details of a single failed item.

    This is used in Failure and FailureItems to capture details of a single failure. Details include the reason, message and stack trace.

    See Also:
    Serialized Form
    • Field Detail

      • EXCEPTION_MESSAGE_ATTRIBUTE

        public static final String EXCEPTION_MESSAGE_ATTRIBUTE
        Attribute used to store the exception message.
        See Also:
        Constant Field Values
    • Method Detail

      • of

        public static FailureItem of​(FailureReason reason,
                                     String message,
                                     Object... messageArgs)
        Obtains a failure from a reason and message.

        The message is produced using a template that contains zero to many "{}" or "{abc}" placeholders. Each placeholder is replaced by the next available argument. If the placeholder has a name, its value is added to the attributes map with the name as a key. If there are too few arguments, then the message will be left with placeholders. If there are too many arguments, then the excess arguments are appended to the end of the message. No attempt is made to format the arguments. See Messages.formatWithAttributes(String, Object...) for more details.

        An exception will be created internally to obtain a stack trace. The cause type will not be present in the resulting failure.

        Parameters:
        reason - the reason
        message - a message explaining the failure, not empty, uses "{}" for inserting messageArgs
        messageArgs - the arguments for the message
        Returns:
        the failure
      • of

        public static FailureItem of​(FailureReason reason,
                                     Throwable cause,
                                     String messageTemplate,
                                     Object... messageArgs)
        Obtains a failure from a reason, throwable and message.

        The message is produced using a template that contains zero to many "{}" placeholders. Each placeholder is replaced by the next available argument. If there are too few arguments, then the message will be left with placeholders. If there are too many arguments, then the excess arguments are appended to the end of the message. No attempt is made to format the arguments. See Messages.formatWithAttributes(String, Object...) for more details.

        It can be useful to capture the underlying exception message. This should be achieved by adding ': {exceptionMessage}' to the template and 'cause.toString()' or 'cause.getMessage()' to the arguments.

        This recognizes and handles FailureItemProvider exceptions.

        Parameters:
        reason - the reason
        cause - the cause
        messageTemplate - a message explaining the failure, not empty, uses "{}" for inserting messageArgs
        messageArgs - the arguments for the message
        Returns:
        the failure
      • from

        public static FailureItem from​(Throwable th)
        Creates a failure item from the throwable.

        This recognizes and handles FailureItemProvider exceptions.

        Parameters:
        th - the throwable to be processed
        Returns:
        the failure item
      • getMessageTemplate

        public String getMessageTemplate()
        Gets the message template that was used to create the message.

        This method derives the template from 'templateLocation' in the attributes. This only works if the template location correctly matches the message.

        Returns:
        the message template
      • withAttribute

        public FailureItem withAttribute​(String key,
                                         String value)
        Returns an instance with the specified attribute added.

        If the attribute map of this instance has the specified key, the value is replaced.

        Parameters:
        key - the key to add
        value - the value to add
        Returns:
        the new failure item
      • withAttributes

        public FailureItem withAttributes​(Map<String,​String> attributes)
        Returns an instance with the specified attributes added.

        If the attribute map of this instance has any of the new attribute keys, the values are replaced.

        Parameters:
        attributes - the new attributes to add
        Returns:
        the new failure item
      • mapMessage

        public FailureItem mapMessage​(Function<String,​String> function)
        Processes the failure item by applying a function that alters the message.

        This operation allows wrapping a failure message with additional information that may have not been available to the code that created the original failure.

        Parameters:
        function - the function to transform the message with
        Returns:
        the transformed instance
      • toString

        public String toString()
        Returns a string summary of the failure, as a single line excluding the stack trace.
        Overrides:
        toString in class Object
        Returns:
        the summary string
      • meta

        public static FailureItem.Meta meta()
        The meta-bean for FailureItem.
        Returns:
        the meta-bean, not null
      • metaBean

        public FailureItem.Meta metaBean()
        Specified by:
        metaBean in interface org.joda.beans.Bean
      • getReason

        public FailureReason getReason()
        Gets the reason associated with the failure.
        Returns:
        the value of the property, not null
      • getMessage

        public String getMessage()
        Gets the error message associated with the failure.
        Returns:
        the value of the property, not empty
      • getAttributes

        public ImmutableMap<String,​String> getAttributes()
        Gets the attributes associated with this failure. Attributes can contain additional information about the failure. For example, a line number in a file or the ID of a trade.
        Returns:
        the value of the property, not null
      • getStackTrace

        public String getStackTrace()
        Gets stack trace where the failure occurred. If the failure was caused by an Exception its stack trace is used, otherwise it's the location where the failure was created.
        Returns:
        the value of the property, not null
      • getCauseType

        public Optional<Class<? extends Throwable>> getCauseType()
        Gets the type of the throwable that caused the failure, not present if it wasn't caused by a throwable.
        Returns:
        the optional value of the property, not null
      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object