com.sap.cds.services

Interface Service

All Known Subinterfaces:

AuthorizationService, CdsService, DraftService, MessagingService, PersistenceService

public interface Service

The Service is the root consumption API that every Service instance offers. It offers the generic emit(EventContext) method, which is also the basis of more specialized consumption API methods.
To enable the Provider API the Service interface also offers programmatic registration of handlers to handle events. Handlers can be registered for the three phases BEFORE, ON and AFTER using EventPredicate as filter to select events and entities, which should be handled.

Method Summary

Modifier and Type	Method and Description
void	after(EventPredicate matcher, Handler handler) Registers a Handler on this Service for the AFTER phase of the processing of an EventContext.
void	before(EventPredicate matcher, Handler handler) Registers a Handler on this Service for the BEFORE phase of the processing of an EventContext.
void	emit(EventContext context) The generic consumption API to emit arbitrary events, represented by EventContext objects.
String	getName() Returns the name of the Service.
void	on(EventPredicate matcher, Handler handler) Registers a Handler on this Service for the ON phase of the processing of an EventContext.

Method Detail

before

void before(EventPredicate matcher,
            Handler handler)

Registers a Handler on this Service for the BEFORE phase of the processing of an EventContext. Using the EventPredicate the relevant events and entities, for which the Handler should become active can be selected.
The BEFORE phase is useful for doing filtering, validation and other types of pre-processing of the input parameters of an event. Handler are called one after the other and can abort the complete processing of the event at any time by throwing an exception. If during the BEFORE phase the EventContext.setCompleted() method is called, the event processing directly jumps to the AFTER phase. If no Handler completes the EventContext during the BEFORE phase, or does not abort the event processing by throwing an exception, the ON phase is started.

Parameters:

matcher - the EventPredicate, defining for which events and entities the Handler becomes active.

handler - the Handler implementing the business-logic, which should become active during the BEFORE phase.

on

void on(EventPredicate matcher,
        Handler handler)

Registers a Handler on this Service for the ON phase of the processing of an EventContext. Using the EventPredicate the relevant events and entities, for which the Handler should become active can be selected.
The ON phase is meant to implement the core processing of the event. It's Handler should compute the output parameters based in the input parameters of the event. Handler are called one after the other. If a Handler performs any action during the ON phase, it should call EventContext.setCompleted() to indicate that the event was successfully processed. As soon as the EventContext is completed, the ON phase is finished and the event processing jumps to the AFTER phase. In case a Handler throws an exception the event processing is aborted. If no Handler completes the EventContext during the ON phase, it is treated as an error and an exception with ErrorStatuses.NO_ON_HANDLER is thrown.

Parameters:

matcher - the EventPredicate, defining for which events and entities the Handler becomes active.

handler - the Handler implementing the business-logic, which should become active during the ON phase.

after

void after(EventPredicate matcher,
           Handler handler)

Registers a Handler on this Service for the AFTER phase of the processing of an EventContext. Using the EventPredicate the relevant events and entities, for which the Handler should become active can be selected.
The AFTER phase is useful for doing post-processing of the output parameters of an event. Handler are called one after the other. A Handler in this phase can still abort the event processing by throwing an exception. No further Handler are called in this case. Alternatively it can also call ChangeSetContext.markForCancel(), which cancels the active ChangeSetContext and causes a rollback of transactions. However it does not abort the event processing itself.

Parameters:

matcher - the EventPredicate, defining for which events and entities the Handler becomes active.

handler - the Handler implementing the business-logic, which should become active during the AFTER phase.

emit

void emit(EventContext context)

The generic consumption API to emit arbitrary events, represented by EventContext objects. More specialized consumption APIs (for example CdsService) are implemented as a wrapper around this method.
Emitting an EventContext will start the processing of the event and calls the registered Handler instances. If emit(EventContext) is called outside of an active ChangeSetContext, an internal ChangeSetContext is opened and properly closed. Handler can therefore rely on an active ChangeSetContext.
The EventContext passed to this method, should be propagated with the required input parameters of the event. After the method finished, the respective output parameters can be read from the passed in EventContext.

Parameters:

context - the EventContext to be emitted

getName

String getName()

Returns the name of the Service. The name might be the fully qualified name of a service, which is also present in the CdsModel. If the service is a technical service, the name is an arbitrary name, which is not reflected in the CdsModel.

Returns:

the name of the Service