Class Failure

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

    public final class Failure
    extends Object
    implements org.joda.beans.ImmutableBean, Serializable
    Description of a failed result.

    If calculation of a result fails this class provides details of the failure. There is a single reason and message and a set of detailed failure items. Each FailureItem has details of the actual cause.

    In most cases, instances of Failure should be created using one of the failure methods on Result.

    See Also:
    Serialized Form
    • Method Detail

      • of

        public static Failure 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 "{}" 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.format(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 Failure of​(FailureReason reason,
                                 Throwable cause,
                                 String message,
                                 Object... messageArgs)
        Obtains a failure from a reason, message and throwable.

        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.format(String, Object...) for more details.

        Parameters:
        reason - the reason
        cause - the cause
        message - the failure message, possibly containing placeholders, formatted using Messages.format(java.lang.String, java.lang.Object)
        messageArgs - arguments used to create the failure message
        Returns:
        the failure
      • of

        public static Failure of​(FailureReason reason,
                                 Exception cause,
                                 String message,
                                 Object... messageArgs)
        Obtains a failure from a reason, message and exception.

        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.format(String, Object...) for more details.

        Parameters:
        reason - the reason
        cause - the cause
        message - the failure message, possibly containing placeholders, formatted using Messages.format(java.lang.String, java.lang.Object)
        messageArgs - arguments used to create the failure message
        Returns:
        the failure
      • of

        public static Failure of​(FailureReason reason,
                                 Throwable cause)
        Obtains a failure from a reason and throwable.
        Parameters:
        reason - the reason
        cause - the cause
        Returns:
        the failure
      • of

        public static Failure of​(FailureReason reason,
                                 Exception cause)
        Obtains a failure from a reason and exception.
        Parameters:
        reason - the reason
        cause - the cause
        Returns:
        the failure
      • of

        public static Failure of​(FailureItem item)
        Obtains a failure for a single failure item.
        Parameters:
        item - the failure item
        Returns:
        the failure
      • of

        public static Failure of​(FailureItem item,
                                 FailureItem... additionalItems)
        Obtains a failure for multiple failure items.
        Parameters:
        item - the first failure item
        additionalItems - additional failure items
        Returns:
        the failure
      • of

        public static Failure of​(Collection<FailureItem> items)
        Obtains a failure for a non-empty collection of failure items.
        Parameters:
        items - the failures, not empty
        Returns:
        the failure
      • getFirstItem

        public FailureItem getFirstItem()
        Gets the first failure item.

        There will be at least one failure item, so this always succeeds.

        Returns:
        the failure item
      • mapItems

        public Failure mapItems​(Function<FailureItem,​FailureItem> function)
        Processes the failure by applying a function that alters the items.

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

        Parameters:
        function - the function to transform the failure items with
        Returns:
        the transformed instance
      • meta

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

        public Failure.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
      • getItems

        public ImmutableSet<FailureItem> getItems()
        Gets the set of failure items. There will be at least one failure item.
        Returns:
        the value of the property, not empty
      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object