Mapping fields of incoming objects

Below are details of how mappers work, including how Sentinel selects them at runtime.

What is a mapper?

A mapper is a software component in Sentinel that builds an output object by “mapping” fields of an incoming object. You use mappers at the egress point for protocol messages, for example immediately before sending a CreditControlRequest. You can also use them in any features and other components that require protocol mapping. Sentinel comes with a standard set of mappers; and you can add new ones using the Sentinel SDK.

mapper

Mappers have access to session state, resource adaptor providers, and the from object to achieve their task. For example, a mapper that generates Diameter messages will use a Diameter provider to get a message factory for creating Diameter messages. It might read values from session state and the input from message to create Diameter AVPs; and once complete, return the newly created Diameter message as its result (the to object).

Sentinel uses the mapper concept to decouple Sentinel core from the details of how output messages are generated. Sentinel will select a mapper to apply at runtime, and apply it to generate output messages. The Sentinel SDK user can add new mappers and totally change the way Sentinel creates output messages.

How does Sentinel select mappers at runtime?

The Sentinel SDK generates a MapperRegistry that Sentinel uses at runtime to resolve which mapper to use. The interface to the Sentinel runtime is a MapperLibrary:

mappers-at-runtime

At runtime, Sentinel…​

  • uses mapper lookup configuration data to resolve which mapping to use

  • uses the “mapping name”, get a concrete mapper from the registry

  • returns the mapper to Sentinel core to use.

The mapper library implements dynamic lookup of mappers based on the SentinelSelectionKey, the from class, and the to class (as well as an optional MapperExecutionPoint). The library ultimately resolves the request for a mapper to a mapping name. The mapper registry that the Sentinel SDK generates provides a lookup table of mapping name → mapper implementation.

Dynamic mapper fallback selection

In the event that no exact match is found during a mapper lookup for the ‘from’ and ‘to’ classes, a more general MapperRegistry search is performed for mappers which partially fulfill the ‘from’ and ‘to’ classes via extension.

For example, if the Sentinel core requests a mapper from CAP2InitialDPArg to CreditControlRequest, but only a mapper from CCInitialDPArg to CreditControlRequest exists in the MapperRegistry, then this second mapper will be returned (as CAP2InitialDPArg extends CCInitialDPArg). This allows the creation of mappers which will work even when the exact ‘from’ class is not known at compile time, but is known to be a subclass of another class (such as CCInitialDPArg).

The order of mapper matching logic with dynamic fallback is as follows:

  1. Exact match of from class, to class, respecting mapping point.

  2. Generic match for from class, to class, respecting mapping point.

  3. Exact match of from class, to class, ignoring mapping point.

  4. Generic match for from class, to class, ignoring mapping point.

  5. If no mapper was found, throw a MapperException.

Tip Mappers are configured using the Mappers REST API or Managing Mappers web interface.
Previous page Next page