Package org.pipservices3.commons.errors

Class ApplicationException

java.lang.Object
java.lang.Throwable
java.lang.Exception
org.pipservices3.commons.errors.ApplicationException
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
BadRequestException, ConfigException, ConflictException, ConnectionException, FileException, InternalException, InvalidStateException, InvocationException, NotFoundException, UnauthorizedException, UnknownException, UnsupportedException
public class ApplicationException extends Exception
Defines a base class to defive various application exceptions.

Most languages have own definition of base exception (error) types. However, this class is implemented symmetrically in all languages supported by PipServices toolkit. It allows to create portable implementations and support proper error propagation in microservices calls.

Error propagation means that when microservice implemented in one language calls microservice(s) implemented in a different language(s), errors are returned throught the entire call chain and restored in their original (or close) type.

Since number of potential exception types is endless, PipServices toolkit supports only 12 standard categories of exceptions defined in ErrorCategory. This ApplicationException class acts as a basis for all other 12 standard exception types.

Most exceptions have just free-form message that describes occured error. That may not be sufficient to create meaninful error descriptions. The ApplicationException class proposes an extended error definition that has more standard fields:

  • message: is a humand readable error description
  • category: one of 12 standard error categories of errors
  • status: numeric HTTP status code for REST invocations
  • code: a unique error code, usually defined as "MY_ERROR_CODE"
  • correlation_id: a unique transaction id to trace execution through a call chain
  • details: map with error parameters that can help to recreate meaningful error description in other languages
  • stack_trace: a stack trace
  • cause: original error that is wrapped by this exception

ApplicationException class is not serializable. To pass errors through the wire it is converted into ErrorDescription object and restored on receiving end into identical exception type.

See Also:

  • Constructor Details

    • ApplicationException

      public ApplicationException()
      Creates a new instance of application exception with unknown error category and assigns its values.

    • ApplicationException

      public ApplicationException(String category, String correlationId, String code, String message)
      Creates a new instance of application exception and assigns its values.
      Parameters:
      category - (optional) a standard error category. Default: Unknown
      correlationId - (optional) a unique transaction id to trace execution through call chain.
      code - (optional) a unique error code. Default: "UNKNOWN"
      message - (optional) a human-readable description of the error.

  • Method Details

    • getMessage

      public String getMessage()
      Overrides:
      getMessage in class Throwable

    • setMessage

      public void setMessage(String value)

    • getCategory

      public String getCategory()

    • setCategory

      public void setCategory(String value)

    • getCode

      public String getCode()

    • setCode

      public void setCode(String value)

    • getStatus

      public int getStatus()

    • setStatus

      public void setStatus(int value)

    • getDetails

      public StringValueMap getDetails()

    • setDetails

      public void setDetails(StringValueMap value)

    • getCorrelationId

      public String getCorrelationId()

    • setCorrelationId

      public void setCorrelationId(String value)

    • getCauseString

      public String getCauseString()
      Gets original error wrapped by this exception as a string message.
      Returns:
      an original error message.

    • setCauseString

      public void setCauseString(String value)
      Sets original error wrapped by this exception as a string message.
      Parameters:
      value - an original error message.

    • getStackTraceString

      public String getStackTraceString()
      Gets a stack trace where this exception occured.
      Returns:
      a stack trace as a string.

    • setStackTraceString

      public void setStackTraceString(String value)
      Sets a stack trace where this exception occured.
      Parameters:
      value - a stack trace as a string

    • withCode

      public ApplicationException withCode(String code)
      Sets a unique error code.

      This method returns reference to this exception to implement Builder pattern to chain additional calls.

      Parameters:
      code - a unique error code
      Returns:
      this exception object

    • withStatus

      public ApplicationException withStatus(int status)
      Sets a HTTP status code which shall be returned by REST calls.

      This method returns reference to this exception to implement Builder pattern to chain additional calls.

      Parameters:
      status - an HTTP error code.
      Returns:
      this exception object

    • withDetails

      public ApplicationException withDetails(String key, Object value)
      Sets a parameter for additional error details. This details can be used to restore error description in other languages.

      This method returns reference to this exception to implement Builder pattern to chain additional calls.

      Parameters:
      key - a details parameter name
      value - a details parameter name
      Returns:
      this exception object

    • withCause

      public ApplicationException withCause(Throwable cause)
      Sets a original error wrapped by this exception

      This method returns reference to this exception to implement Builder pattern to chain additional calls.

      Parameters:
      cause - original error object
      Returns:
      this exception object

    • withCorrelationId

      public ApplicationException withCorrelationId(String correlationId)
      Sets a correlation id which can be used to trace this error through a call chain.

      This method returns reference to this exception to implement Builder pattern to chain additional calls.

      Parameters:
      correlationId - a unique transaction id to trace error through call chain
      Returns:
      this exception object

    • withStackTrace

      public ApplicationException withStackTrace(String stackTrace)
      Sets a stack trace for this error.

      This method returns reference to this exception to implement Builder pattern to chain additional calls.

      Parameters:
      stackTrace - a stack trace where this error occured
      Returns:
      this exception object

    • wrap

      public ApplicationException wrap(Throwable cause)
      Wraps another exception into an application exception object.

      If original exception is of ApplicationException type it is returned without changes. Otherwise a new ApplicationException is created and original error is set as its cause.

      Parameters:
      cause - an original error object
      Returns:
      an original or newly created ApplicationException

    • wrapException

      public static ApplicationException wrapException(ApplicationException error, Throwable cause)
      Wraps another exception into specified application exception object.

      If original exception is of ApplicationException type it is returned without changes. Otherwise the original error is set as a cause to specified ApplicationException object.

      Parameters:
      error - an ApplicationException object to wrap the cause
      cause - an original error object
      Returns:
      an original or newly created ApplicationException