Options
All
  • Public
  • Public/Protected
  • All
Menu

Class ApplicationException

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 human-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

ErrorCategory

see

ErrorDescription

Hierarchy

Index

Constructors

constructor

  • new ApplicationException(category?: string, correlation_id?: string, code?: string, message?: string): ApplicationException
  • Creates a new instance of application exception and assigns its values.

    Parameters

    • Default value category: string = null

      (optional) a standard error category. Default: Unknown

    • Default value correlation_id: string = null

      (optional) a unique transaction id to trace execution through call chain.

    • Default value code: string = null

      (optional) a unique error code. Default: "UNKNOWN"

    • Default value message: string = null

      (optional) a human-readable description of the error.

    Returns ApplicationException

Properties

category

category: string

Standard error category

cause

cause: string

Original error wrapped by this exception

code

code: string = "UNKNOWN"

A unique error code

correlation_id

correlation_id: string

A unique transaction id to trace execution throug call chain

details

A map with additional details that can be used to restore error description in other languages

message

message: string

A human-readable error description (usually written in English)

stack_trace

stack_trace: string

Stack trace of the exception

status

status: number = 500

HTTP status code associated with this error type

Static Error

Error: ErrorConstructor

Static message

message: string

Static name

name: string

Static Optional stack

stack: string

Methods

getCauseString

  • getCauseString(): string

getStackTraceString

  • getStackTraceString(): string

setCauseString

  • setCauseString(value: string): void
  • Sets original error wrapped by this exception as a string message.

    Parameters

    • value: string

      an original error message.

    Returns void

setStackTraceString

  • setStackTraceString(value: string): void

withCause

  • 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: Error

      original error object

    Returns ApplicationException

    this exception object

withCode

  • Sets a unique error code.

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

    Parameters

    • code: string

      a unique error code

    Returns ApplicationException

    this exception object

withCorrelationId

  • 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: string

      a unique transaction id to trace error through call chain

    Returns ApplicationException

    this exception object

withDetails

  • 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: string

      a details parameter name

    • value: any

      a details parameter name

    Returns ApplicationException

    this exception object

withStackTrace

  • Sets a stack trace for this error.

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

    Parameters

    • stackTrace: string

      a stack trace where this error occured

    Returns ApplicationException

    this exception object

withStatus

  • 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: number

      an HTTP error code.

    Returns ApplicationException

    this exception object

wrap

  • 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: any

      an original error object

    Returns ApplicationException

    an original or newly created ApplicationException

Static unwrapError

  • unwrapError(error: any): any
  • Unwraps original exception through wrapped exception objects.

    Many frameworks like Seneca or restify wrap original exception. That may result in propagating less specific errors and can hide causes of the errors.

    Parameters

    • error: any

      an error object

    Returns any

    an original error object

Static wrapError

  • 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.

    see

    wrap

    Parameters

    • error: ApplicationException

      an ApplicationException object to wrap the cause

    • cause: any

      an original error object

    Returns ApplicationException

    an original or newly created ApplicationException

Generated using TypeDoc