Add Exception Mapper - SchwarzIT/sap-usi-logging-api GitHub Wiki

Exception mappers are used to extract the relevant data from an exception while logging it. They are based on the interface /USI/IF_BAL_EXCEPTION_MAPPER, that offers two methods.

When to implement

Chances are you will never need your own exception mapper.

You would only need one, if you had an exception class, that contained additional data (such as e.g. an internal table), that is NOT encapsulated in a data container.

Before writing a custom exception mapper, you should consider the following procedure, since this is more straigthforward:

  • Encapsulate the additional data in a data container.
    • Check for an existing data container before implementing your own - they all implement interface /USI/IF_BAL_DATA_CONTAINER.
    • If you can't find a suitable data container, feel free to start a discussion about that.
  • Add a public read-only attribute TYPE REF TO /USI/IF_BAL_MESSAGE_DETAILS to your exception class (Name does not matter).

This allows you to attach a single data container (Interface /USI/IF_BAL_DATA_CONTAINER) or a collection of data containers (Interface /USI/IF_BAL_DATA_CONTAINER_COL / Class /USI/CL_BAL_DC_COLLECTION) to your exception. The logger will recognize and log them them automatically.

Method GET_T100_MESSAGE

All implementations should delegate the call to the text getter of the Exception API.

If the text getter should not work, as expected a new plugin class for the text getter might be needed. Please refer to the documentation to find out, how to create it.

The interface method exists "for historic reasons", as the text extraction was originally "invented" for the logging API before it was moved to the exception API. As the interface had already been rolled out and custom implementations of that interface might exist, deleting the method declaration was no longer feasible.

Method GET_DATA_CONTAINERS

Extracts additional data from the exception (if found) and returns them as a data container collection (TYPE REF TO /USI/IF_BAL_DATA_CONTAINER_COL).

The API is shipped with the default mapper /USI/CL_BAL_EM_BASE, that will already recognize all public instance attributes of an exception having the following types:

  • TYPE REF TO /USI/IF_BAL_DATA_CONTAINER (Single data container)
  • TYPE REF TO /USI/IF_BAL_DATA_CONTAINER_COL (Data container collection)

How to implement an exception mapper

If you should ever need a custom exception mapper, I would recommend to copy the class /USI/CL_BAL_EM_BASE. After that, just enhance the method /USI/IF_BAL_EXCEPTION_MAPPER~GET_DATA_CONTAINERS as needed.

Integration

Once created a new mapper has to be maintained in the customizing (see: Customizing -> Exception Mappers).