com.sap.cds.services

Interface Service

All Known Subinterfaces:

ApplicationLifecycleService, ApplicationService, AuditLogService, AuthorizationService, CdsService, CqnService, DraftService, ExtensibilityService, MessagingService, OutboxService, PersistenceService, RemoteService, TenantProviderService

All Known Implementing Classes:

ServiceDelegator

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 events and entities, which should be handled.
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.
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 is thrown.
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.

Method Summary

Modifier and Type	Method and Description
void	after(EventPredicate matcher, Handler handler) Deprecated. Use after(String[], String[], int, Handler) instead.
default void	after(String[] events, String[] entities, Handler handler) Registers a Handler on this Service for the AFTER phase of the processing of an EventContext.
void	after(String[] events, String[] entities, int order, Handler handler) Registers a Handler on this Service for the AFTER phase of the processing of an EventContext.
default void	after(String event, String entity, Handler handler) Registers a Handler on this Service for the AFTER phase of the processing of an EventContext.
default void	after(String event, String entity, int order, Handler handler) Registers a Handler on this Service for the AFTER phase of the processing of an EventContext.
void	before(EventPredicate matcher, Handler handler) Deprecated. Use before(String[], String[], int, Handler) instead.
default void	before(String[] events, String[] entities, Handler handler) Registers a Handler on this Service for the BEFORE phase of the processing of an EventContext.
void	before(String[] events, String[] entities, int order, Handler handler) Registers a Handler on this Service for the BEFORE phase of the processing of an EventContext.
default void	before(String event, String entity, Handler handler) Registers a Handler on this Service for the BEFORE phase of the processing of an EventContext.
default void	before(String event, String entity, int order, Handler handler) Registers a Handler on this Service for the BEFORE phase of the processing of an EventContext.
static Service	create(String name) Creates a new Service
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) Deprecated. Use on(String[], String[], int, Handler) instead.
default void	on(String[] events, String[] entities, Handler handler) Registers a Handler on this Service for the ON phase of the processing of an EventContext.
void	on(String[] events, String[] entities, int order, Handler handler) Registers a Handler on this Service for the ON phase of the processing of an EventContext.
default void	on(String event, String entity, Handler handler) Registers a Handler on this Service for the ON phase of the processing of an EventContext.
default void	on(String event, String entity, int order, Handler handler) Registers a Handler on this Service for the ON phase of the processing of an EventContext.

Method Detail

create

static Service create(String name)

Creates a new Service

Parameters:

name - the name of the service

Returns:

the Service

before

@Deprecated
void before(EventPredicate matcher,
                        Handler handler)

Deprecated. Use before(String[], String[], int, Handler) instead.

Registers a Handler on this Service for the BEFORE phase of the processing of an EventContext.

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.

before

void before(String[] events,
            String[] entities,
            int order,
            Handler handler)

Registers a Handler on this Service for the BEFORE phase of the processing of an EventContext.

Parameters:

events - the events the custom handler is registered for

entities - the entities the custom handler is registered for

order - the order of the handler. the lower the order the earlier the handler gets called. if two handlers have the same order they get ordered in their registration order

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

before

default void before(String[] events,
                    String[] entities,
                    Handler handler)

Registers a Handler on this Service for the BEFORE phase of the processing of an EventContext.

Parameters:

events - the events the custom handler is registered for

entities - the entities the custom handler is registered for

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

before

default void before(String event,
                    String entity,
                    int order,
                    Handler handler)

Registers a Handler on this Service for the BEFORE phase of the processing of an EventContext.

Parameters:

event - the event the custom handler is registered for

entity - the entity the custom handler is registered for

order - the order of the handler. the lower the order the earlier the handler gets called. if two handlers have the same order they get ordered in their registration order

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

before

default void before(String event,
                    String entity,
                    Handler handler)

Registers a Handler on this Service for the BEFORE phase of the processing of an EventContext.

Parameters:

event - the event the custom handler is registered for

entity - the entity the custom handler is registered for

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

on

@Deprecated
void on(EventPredicate matcher,
                    Handler handler)

Deprecated. Use on(String[], String[], int, Handler) instead.

Registers a Handler on this Service for the ON phase of the processing of an EventContext.

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.

on

void on(String[] events,
        String[] entities,
        int order,
        Handler handler)

Registers a Handler on this Service for the ON phase of the processing of an EventContext.

Parameters:

events - the events the custom handler is registered for

entities - the entities the custom handler is registered for

order - the order of the handler. the lower the order the earlier the handler gets called. if two handlers have the same order they get ordered in their registration order

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

on

default void on(String[] events,
                String[] entities,
                Handler handler)

Registers a Handler on this Service for the ON phase of the processing of an EventContext.

Parameters:

events - the events the custom handler is registered for

entities - the entities the custom handler is registered for

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

on

default void on(String event,
                String entity,
                int order,
                Handler handler)

Registers a Handler on this Service for the ON phase of the processing of an EventContext.

Parameters:

event - the event the custom handler is registered for

entity - the entity the custom handler is registered for

order - the order of the handler. the lower the order the earlier the handler gets called. if two handlers have the same order they get ordered in their registration order

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

on

default void on(String event,
                String entity,
                Handler handler)

Registers a Handler on this Service for the ON phase of the processing of an EventContext.

Parameters:

event - the event the custom handler is registered for

entity - the entity the custom handler is registered for

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

after

@Deprecated
void after(EventPredicate matcher,
                       Handler handler)

Deprecated. Use after(String[], String[], int, Handler) instead.

Registers a Handler on this Service for the AFTER phase of the processing of an EventContext.

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.

after

void after(String[] events,
           String[] entities,
           int order,
           Handler handler)

Registers a Handler on this Service for the AFTER phase of the processing of an EventContext.

Parameters:

events - the events the custom handler is registered for

entities - the entities the custom handler is registered for

order - the order of the handler. the lower the order the earlier the handler gets called. if two handlers have the same order they get ordered in their registration order

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

after

default void after(String[] events,
                   String[] entities,
                   Handler handler)

Registers a Handler on this Service for the AFTER phase of the processing of an EventContext.

Parameters:

events - the events the custom handler is registered for

entities - the entities the custom handler is registered for

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

after

default void after(String event,
                   String entity,
                   int order,
                   Handler handler)

Registers a Handler on this Service for the AFTER phase of the processing of an EventContext.

Parameters:

event - the event the custom handler is registered for

entity - the entity the custom handler is registered for

order - the order of the handler. the lower the order the earlier the handler gets called. if two handlers have the same order they get ordered in their registration order

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

after

default void after(String event,
                   String entity,
                   Handler handler)

Registers a Handler on this Service for the AFTER phase of the processing of an EventContext.

Parameters:

event - the event the custom handler is registered for

entity - the entity the custom handler is registered for

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 CqnService) 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