Package com.almworks.jira.structure.api.error

Class StructureException

Object
Throwable
Exception
StructureException
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
ForestMergeStructureException, StructureInteractionException
@PublicApi public class StructureException extends Exception

StructureException can be thrown for different causes that involve Structure plugin. It usually means that the operation that is traced back to the user's action cannot be performed and should be reported as an error.

Each exception is associated with a specific value from enumeration StructureError. Exception may also carry additional message and information about affected structure, view, item or row. The general method Throwable.getMessage(), returns all information included with the exception, except for the stack trace and cause.

Displaying User-Friendly Errors

To display an error on the user interface: use getLocalizedMessage() or getLocalizedMessage(ApplicationUser) to get a human-friendly error in the user's locale. However, in many cases the error message will not be localized and the result of getLocalizedMessage() will contain the problem description in English.

So for the best result, you should check isLocalized() method and if exception is not localized, use some wrapper text to display the error to the user in a good way: 

 Java code:
   try {
     ...
   } catch (StructureException e) {
     if (e.isLocalized()) {
       setDisplayedError(e.getLocalizedMessage());
     } else {
       setDisplayedError(getText("my.errors.structure-error", e.getLocalizedMessage()));
     }
   }

Throwing StructureException

An instance of StructureException may be created by using one of the available constructors, but it might be more convenient to start from StructureError and use chained builder commands, ending with message specification:

   throw StructureErrors.GENERIC_ERROR.withMessage("cannot foo bar");
   ...
   throw StructureErrors.INVALID_JQL.causedBy(caughtException).forStructure(id).withoutMessage();
   ...
   throw StructureErrors.VIEW_EDIT_DENIED.forView(id).withLocalizedMessage("error.view.edit.denied", id, name);
See Also:

  • Constructor Details

    • StructureException

      public StructureException(@Nullable StructureError error)
      Constructs an instance of exception.
      Parameters:
      error - structure error code

    • StructureException

      public StructureException(@Nullable StructureError error, @Nullable String message)
      Constructs an instance of exception.
      Parameters:
      error - structure error code
      message - additional message text

    • StructureException

      public StructureException(@Nullable StructureError error, @Nullable Long structure)
      Constructs an instance of exception.
      Parameters:
      error - structure error code
      structure - structure in question

    • StructureException

      public StructureException(@Nullable StructureError error, @Nullable Long structure, @Nullable Long row)
      Constructs an instance of exception.
      Parameters:
      error - structure error code
      structure - structure in question
      row - related row ID

    • StructureException

      public StructureException(@Nullable StructureError error, @Nullable Long structure, @Nullable Long row, @Nullable String message)
      Constructs an instance of exception.
      Parameters:
      error - structure error code
      structure - structure in question
      row - related row ID
      message - additional message text

    • StructureException

      public StructureException(@Nullable StructureError error, @Nullable Long structure, @Nullable Long row, @Nullable String message, @Nullable Throwable cause)
      Constructs an instance of exception. For convenience, use one of the overloaded constructors.
      Parameters:
      error - structure error code
      structure - structure in question
      row - related row ID
      message - additional message text
      cause - throwable cause

    • StructureException

      public StructureException(@Nullable StructureError error, @Nullable Long structure, @Nullable Long row, @Nullable Long view)
      Constructs an instance of exception. For convenience, use one of the overloaded constructors.
      Parameters:
      error - structure error code
      structure - structure in question
      row - related row ID
      view - related view ID

    • StructureException

      public StructureException(@Nullable StructureError error, @Nullable Long structure, @Nullable Long row, @Nullable Long view, @Nullable String message)
      Constructs an instance of exception. For convenience, use one of the overloaded constructors.
      Parameters:
      error - structure error code
      structure - structure in question
      row - related row ID
      view - related view ID
      message - additional message text

    • StructureException

      protected StructureException(StructureError error, @Nullable Throwable cause, @Nullable Long structure, @Nullable Long view, @Nullable Long row, @Nullable ItemIdentity item, @Nullable String message, @Nullable String messageKey, @Nullable Object... messageParameters)
      Constructs an instance of this exception. Not intended to be called directly.
      Parameters:
      error - structure error code
      cause - throwable cause
      structure - related structure ID
      view - related view ID
      row - related row ID
      item - related item ID
      message - additional message text
      messageKey - i18n message text
      messageParameters - i18n message parameters

  • Method Details

    • toString

      public String toString()
      Provides string representation of the exception. Overrides default toString(), which uses getLocalizedMessage().
      Overrides:
      toString in class Throwable

    • getError

      @NotNull public StructureError getError()
      Returns the error value associated with the exception.
      Returns:
      StructureError enum value

    • getProblemDetails

      @NotNull public String getProblemDetails()

      Returns the part of Throwable.getMessage() that corresponds to the original description of the problem. Does not contain structure ID, error code, and related item information, so is more user-friendly than Throwable.getMessage() in case when that information can be more suitably described by the caller.

      Normally you shouldn't use this method, use getLocalizedMessage() instead. You may want to use this method if you don't need a potentially localized message, but still need a more user-friendly English message about the problem.

      Returns:
      a more user-friendly error description than Throwable.getMessage() would return.

    • getStructure

      public long getStructure()
      Returns related structure, or 0 if no structure is related.
      Returns:
      related structure ID

    • getView

      public long getView()
      Returns related view, or 0 if no view is related.
      Returns:
      related view ID

    • getRow

      public long getRow()
      Returns related row, or 0 if no row is related.
      Returns:
      related row ID

    • getItem

      @Nullable public ItemIdentity getItem()
      Returns related item, or null if no item is related.
      Returns:
      related item ID

    • isLocalized

      public boolean isLocalized()
      Checks if there's a i18n message.
      Returns:
      true if there's a localized message
      See Also:

    • getLocalizedMessage

      @NotNull public String getLocalizedMessage()
      Gets the localized message about the problem in the current user's locale. If there's no i18n message available, returns some friendly message, provided by getProblemDetails().
      Overrides:
      getLocalizedMessage in class Throwable
      Returns:
      i18n-ized error message in current user's locale
      See Also:

    • getLocalizedMessage

      @NotNull public String getLocalizedMessage(@Nullable ApplicationUser user)
      Gets the localized message about the problem in the given user's locale. If there's no i18n message available, returns some friendly message, provided by getProblemDetails().
      Parameters:
      user - target user
      Returns:
      i18n-ized error message in current user's locale
      See Also:

    • asI18nText

      @NotNull public I18nText asI18nText()