Services are one of the core concepts of CAP. This section describes how services are represented in the CAP Java SDK and how their event-based APIs can be used. One of the key APIs provided by services is the uniform query API based on CQN statements.
Services dispatch events to Event Handlers, which implement the behaviour of the service. A service can process synchronous as well as asynchronous events and offers a user-friendly API layer around these events.
Every service implements the Service interface, which offers generic event processing capabilities through its emit(EventContext) method. The Event Context contains information about the event and its parameters. The emit method takes care of dispatching an Event Context to all event handlers registered on the respective event and is the central API to process asynchronous and synchronous events.
Often times your Java code needs to interact with other services. The ServiceCatalog provides programmatic access to all available services. The Service Catalog can be accessed from the Event Context or from the CdsRuntime.
As of version 2.4.0, the CAP Java SDK Maven Plugin is capable of generating specific interfaces for services in the CDS model. These service interfaces also provide Java methods for actions and functions, which allows easily calling actions and functions with their parameters. These specific interfaces can also be used to get access to the service:
The most used services in CAP are the CQN-based services. The most prominent of these are the Application Service, Persistence Service, and Remote Service. Those services can handle CRUD events by accepting CQN statements. They all implement the common interface CqnService, which defines the CQN-based APIs.
Application Services define the APIs that are exposed by a CAP application to its clients. They're backed by a CDS Service definition in the CDS model, which defines the structure of the API. Consequently, they only accept CQN statements targeting entities that are defined as part of their service definition. Typically these services are served by protocol adapters, such as OData V4, which use their CQN-based APIs.
Application Services are automatically augmented with generic providers (built-in event handlers), which handle common aspects such as authorization, input validation, implicit pagination and many more. Their default ON event handler delegates CQN statements to the Persistence Service.
The creation of Application Services can be customized through configuration. By default an Application Service is created for every service that is defined in the CDS model. Through configuration, it's also possible to create multiple Application Services based on the same model definition.
If an Application Service is created based on a service definition, that contains a draft-enabled entity, it also implements the DraftService interface. This interface provides an API layer around the draft-specific events, and allows to create new draft entities, patch, cancel or save them, and put active entities back into edit mode.
Persistence Services are CQN-based database clients. CAP applications most commonly use SQL databases like SAP HANA in production. For test and development, it's also possible to use a light-weight, in-memory database such as H2. The CAP Java SDK therefore provides a JDBC-based Persistence Service implementation out of the box. However, also other Persistence Service implementations based on NoSQL databases, such as MongoDB, are possible, even if not provided by the CAP Java SDK ready to use.
A Persistence Service isn't bound to a specific service definition in the CDS model. It's capable of accepting CQN statements targeting any entity or view that is stored in the corresponding database.
Transaction management is built in to Persistence Services. They take care of lazily initializing and maintaining database transactions as part of the active changeset context.
Some generic providers are registered on Persistence Services instead of on Application Services, like the ones for managed data. This ensures that the functionality is also triggered, when directly interacting with a Persistence Service.
The Persistence Service is used when implementing event handlers for Application Services, for example when additional data needs to be read when performing custom validations. Additionally, the default ON event handler of Application Services delegates CQN statements to the default Persistence Service.
Remote Services are CQN-based clients for remote APIs, for example OData. They're backed by a CDS Service definition, that reflects the structure of the remote API. The CDS service definition is usually imported, for example from an EDMX specification.
They can be used when integrating APIs provided by the application with APIs provided by other applications or micro-services. This integration can happen synchronously by delegating CQN statements from Application Services to Remote Services or asynchronously by using Remote Services to replicate data into the applications own persistence.
Remote Services need to be explicitly configured and are never created automatically. The configuration of a Remote Service specifies the destination where the remote API is available and its protocol type. It's also possible to create multiple Remote Services with different destinations based on the same model definition. If a Remote Service is created for a service definition in the CDS model, no Application Service is automatically created for that definition.
The Application Lifecycle Service emits events when the CdsRuntime is fully initialized, but the application is not started yet, or when the application is stopped. Its API and events are defined in the ApplicationLifecycleService interface. You can use these events to register an event handler which performs custom initialization or shutdown logic. In addition the Application Lifecycle Service provides an event to globally adapt the error response handling.