pip_services3_commons.errors.ApplicationException module

pip_services3_commons.errors.ApplicationException

Application error type

copyright: Conceptual Vision Consulting LLC 2018-2019, see AUTHORS for more details.
license: MIT, see LICENSE for more details.

exception pip_services3_commons.errors.ApplicationException.ApplicationException(category: str = 'Unknown', correlation_id: Optional[str, None] = None, code: str = 'UNKNOWN', message: str = 'Unknown error')

Bases: Exception

Defines a base class to defive various application exceptions.

Most languages have own definition of base error (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 error types is endless, PipServices toolkit supports only 12 standard categories of exceptions defined in ErrorCategory. This ApplicationException class acts as a basis for all obj 12 standard error 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 obj languages - stack_trace: a stack trace - cause: original error that is wrapped by this error

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

get_cause_string() → str 

Gets original error wrapped by this error as a string message.

Returns: an original error message.

get_stack_trace_string() → Optional[str, None]

Gets a stack trace where this error occured.

Returns: a stack trace as a string.

set_cause_string(value: str)

Sets original error wrapped by this error as a string message.

Parameters: value – an original error message.

set_stack_trace_string(value: str)

Sets a stack trace where this error occured.

Parameters: value – a stack trace as a string

to_json()

with_cause(cause: Exception) → pip_services3_commons.errors.ApplicationException.ApplicationException 

Sets a original error wrapped by this error

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

Parameters: cause – original error object
Returns: this error object

with_code(code: str) → pip_services3_commons.errors.ApplicationException.ApplicationException 

Sets a unique error code. This method returns reference to this error to implement Builder pattern to chain additional calls.

Parameters: code – a unique error code
Returns: this error object

with_correlation_id(correlation_id: Optional[str, None]) → pip_services3_commons.errors.ApplicationException.ApplicationException 

Sets a correlation id which can be used to trace this error through a call chain.

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

Parameters: correlation_id – a unique transaction id to trace error through call chain
Returns: this error object

with_details(key: str, value: Any) → pip_services3_commons.errors.ApplicationException.ApplicationException 

Sets a parameter for additional error details. This details can be used to restore error description in obj languages.

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

Parameters

key – a details parameter name
value – a details parameter name

Returns

this error object

with_stack_trace(stack_trace: str) → pip_services3_commons.errors.ApplicationException.ApplicationException 

Sets a stack trace for this error.

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

Parameters: stack_trace – a stack trace where this error occured
Returns: this error object

with_status(status: int) → pip_services3_commons.errors.ApplicationException.ApplicationException 

Sets a HTTP status code which shall be returned by REST calls. This method returns reference to this error to implement Builder pattern to chain additional calls.

Parameters: status – an HTTP error code.
Returns: this error object

wrap(cause: Any) → pip_services3_commons.errors.ApplicationException.ApplicationException 

Wraps another error into an application error object.

If original error 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

static wrap_error(error: pip_services3_commons.errors.ApplicationException.ApplicationException, cause: Any) → pip_services3_commons.errors.ApplicationException.ApplicationException 

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