Package com.sap.cds.services

Interface Service

All Known Subinterfaces:
ApplicationLifecycleService, ApplicationService, AsyncCqnService, AuditLogService, AuthorizationService, CqnService, DeploymentService, DraftService, ExtensibilityService, MessagingService, OutboxService, PdfService, 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 Details

    • create

      static Service create(String name)
      Creates a new Service
      Parameters:
      name - the name of the service
      Returns:
      the Service

    • 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

      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

      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