diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json new file mode 100644 index 0000000000..9929d05df0 --- /dev/null +++ b/.devcontainer/devcontainer.json @@ -0,0 +1,11 @@ +{ + "image":"mcr.microsoft.com/devcontainers/universal:2", + "customizations": { + "vscode": { + "extensions": [ + "fcrespo82.markdown-table-formatter", + "vue.volar" + ] + } + } +} \ No newline at end of file diff --git a/.vscode/extensions.json b/.vscode/extensions.json new file mode 100644 index 0000000000..4b89ee0096 --- /dev/null +++ b/.vscode/extensions.json @@ -0,0 +1,7 @@ +{ + // List of extensions which should be recommended for users of this workspace. + "recommendations": [ + "fcrespo82.markdown-table-formatter", + "vue.volar" + ] +} \ No newline at end of file diff --git a/advanced/publishing-apis/assets/openapi-diagram.png b/advanced/publishing-apis/assets/openapi-diagram.png new file mode 100644 index 0000000000..3aef5c45e1 Binary files /dev/null and b/advanced/publishing-apis/assets/openapi-diagram.png differ diff --git a/advanced/publishing-apis/assets/swagger-link.png b/advanced/publishing-apis/assets/swagger-link.png new file mode 100644 index 0000000000..3686c6acbb Binary files /dev/null and b/advanced/publishing-apis/assets/swagger-link.png differ diff --git a/advanced/publishing-apis/asyncapi.md b/advanced/publishing-apis/asyncapi.md new file mode 100644 index 0000000000..1f835eda1e --- /dev/null +++ b/advanced/publishing-apis/asyncapi.md @@ -0,0 +1,134 @@ +--- +shorty: AsyncAPI +synopsis: > + About how to convert events in CDS models to AsyncAPI documentation. +redirect_from: advanced/asyncapi +status: released +--- + + + + +# Publishing to AsyncAPI + +You can convert events in CDS models to the [AsyncAPI specification](https://www.asyncapi.com), a widely adopted standard used to describe and document message-driven asynchronous APIs. + + +## Usage from CLI { #cli} + +Use the following command to convert all services in `srv/` and store the generated AsyncAPI documents in the `docs/` folder: + +```sh +cds compile srv --service all -o docs --to asyncapi +``` + +For each service that is available in the `srv/` files, an AsyncAPI document with the service name is generated in the output folder. +If you want to generate one AsyncAPI document for all the services, you can use `--asyncapi:merged` flag: + +```sh +cds compile srv --service all -o docs --to asyncapi --asyncapi:merged +``` + +[Learn how to programmatically convert the CSN file into an AsyncAPI Document](/node.js/cds-compile#to-asyncapi){.learn-more} + +## Presets { #presets} + +Use presets to add configuration for the AsyncAPI export tooling. + +::: code-group +```json [.cdsrc.json] +{ + "export": { + "asyncapi": { + "application_namespace": "sap.example" + ... + } + } +} +``` +::: + +| Term | Preset Target | AsyncAPI field | Remarks | +|-------------------------|---------------|-------------------------------|--------------------------------------------------------------------------------------------------------------------------| +| `merged.title` | Service | info.title | Mandatory when `--asyncapi:merged` flag is given.
`title` from here is used in the generated AsyncAPI document. | +| `merged.version` | Service | info.version | Mandatory when `--asyncapi:merged` flag is given.
`version` from here is used in the generated AsyncAPI document | +| `merged.description` | Service | info.description | Optional when `--asyncapi:merged` flag is given.
`description` from here is used in the generated AsyncAPI document. | +| `merged.short_text` | Service | x-sap-shortText | Optional when `--asyncapi:merged` flag is given.
The value from here is used in the generated AsyncAPI document. | +| `application_namespace` | Document | x-sap-application-namespace | Mandatory | +| `event_spec_version` | Event | x-sap-event-spec-version | | +| `event_source` | Event | x-sap-event-source | | +| `event_source_params` | Event | x-sap-event-source-parameters | | +| `event_characteristics` | Event | x-sap-event-characteristics | | + +## Annotations { #annotations} + +Use annotations to add configuration for the AsyncAPI export tooling. + +::: tip +Annotations will take precedence over [presets](#presets). +::: + +| Term (`@AsyncAPI.`) | Annotation Target | AsyncAPI field | Remarks | +|------------------------|-------------------|-------------------------------|-------------------------------------------------------------------------------------------------------------------------| +| `Title` | Service | info.title | Mandatory | +| `SchemaVersion` | Service | info.version | Mandatory | +| `Description` | Service | info.description | | +| `StateInfo` | Service | x-sap-stateInfo | | +| `ShortText` | Service | x-sap-shortText | | +| `EventSpecVersion` | Event | x-sap-event-spec-version | | +| `EventSource` | Event | x-sap-event-source | | +| `EventSourceParams` | Event | x-sap-event-source-parameters | | +| `EventCharacteristics` | Event | x-sap-event-characteristics | | +| `EventStateInfo` | Event | x-sap-stateInfo | | +| `EventSchemaVersion` | Event | x-sap-event-version | | +| `EventType` | Event | | Optional; The value from this annotation will be used to
overwrite the default event type in the AsyncAPI document. | + +For example: + +```cds +@AsyncAPI.Title : 'CatalogService Events' +@AsyncAPI.SchemaVersion: '1.0.0' +@AsyncAPI.Description : 'Events emitted by the CatalogService.' + +service CatalogService { + @AsyncAPI.EventSpecVersion : '2.0' + @AsyncAPI.EventCharacteristics: { + ![state-transfer]: 'full-after-image' + } + @AsyncAPI.EventSchemaVersion : '1.0.0' + + event SampleEntity.Changed.v1 : projection on CatalogService.SampleEntity; +} +``` + +## Type Mapping { #mapping} + +CDS Type to AsyncAPI Mapping + +| CDS Type | AsyncAPI Supported Types | +|----------------------------------------|-----------------------------------------------------------------------------------------------------| +| `UUID` | `{ "type": "string", "format": "uuid" }` | +| `Boolean` | `{ "type": "boolean" }` | +| `Integer` | `{ "type": "integer" }` | +| `Integer64` | `{ "type": "string", "format": "int64" }` | +| `Decimal`, `{precision, scale}` | `{ "type": "string", "format": "decimal", "formatPrecision": , "formatScale": }` | +| `Decimal`, without scale | `{ "type": "string", "format": "decimal", "formatPrecision": }` | +| `Decimal`, without precision and scale | `{ "type": "string", "format": "decimal" }` | +| `Double` | `{ "type": "number" }` | +| `Date` | `{ "type": "string", "format": "date" }` | +| `Time` | `{ "type": "string", "format": "partial-time" }` | +| `DateTime` | `{ "type": "string", "format": "date-time" }` | +| `Timestamp` | `{ "type": "string", "format": "date-time" }` | +| `String` | `{ "type": "string", "maxLength": length }` | +| `Binary` | `{ "type": "string", "maxLength": length }` | +| `LargeBinary` | `{ "type": "string" }` | +| `LargeString` | `{ "type": "string" }` | diff --git a/advanced/publishing-apis/index.data.ts b/advanced/publishing-apis/index.data.ts new file mode 100644 index 0000000000..44b5878e2e --- /dev/null +++ b/advanced/publishing-apis/index.data.ts @@ -0,0 +1,10 @@ +import { basename } from 'node:path' +import { createContentLoader } from 'vitepress' +import filter from '../../.vitepress/theme/components/indexFilter.ts' + +const basePath = basename(__dirname) +export default createContentLoader([`**/${basePath}/*.md`], { + transform(rawData) { + return filter(rawData, `/${basePath}/`) + } +}) diff --git a/advanced/publishing-apis/index.md b/advanced/publishing-apis/index.md new file mode 100644 index 0000000000..8d1b36d2c4 --- /dev/null +++ b/advanced/publishing-apis/index.md @@ -0,0 +1,16 @@ +--- +status: released +synopsis: How to publish APIs in different formats +--- + +# Publishing APIs + +{{ $frontmatter.synopsis }} + + + + +
+ diff --git a/advanced/publishing-apis/openapi.md b/advanced/publishing-apis/openapi.md new file mode 100644 index 0000000000..ba3aeb2bf8 --- /dev/null +++ b/advanced/publishing-apis/openapi.md @@ -0,0 +1,191 @@ +--- +shorty: OpenAPI +synopsis: > + About how to publish service APIs in OpenAPI format. +redirect_from: advanced/openapi +status: released +--- + +# Publishing to OpenAPI + +You can convert CDS models to the [OpenAPI Specification](https://www.openapis.org), a widely adopted API description standard. + +## Usage from CLI { #cli} + +For example, this is how you convert all services in `srv/` and store the API files in the `docs/` folder: + +```sh +cds compile srv --service all -o docs --to openapi +``` + +With the `--openapi:diagram` parameter, you can also include a [yuml](https://yuml.me/) entity-relationship diagram of the service entities in the Open API file. + +![A screenshot of the entity-relationship diagram.](assets/openapi-diagram.png){ .adapt } + +The default value of the server URL is the service base path as declared in the CDS source. + +If you have a **single server** and you want to set the server URL, use `--openapi:url ` option. Include the service path in the URL. For that, you can use the `${service-path}` variable. + +If you want to configure **multiple servers**, you can use `--openapi:servers ` which accepts stringified JSON of the server object. +Here, you can pass multiple server objects by passing the stringified JSON objects as an array. + +```sh +cds compile srv service.cds --to openapi --openapi:servers "\"'[{\\\"url\\\":\\\"api.sandbox.com\\\",\\\"description\\\":\\\"Test URL\\\"},{\\\"url\\\":\\\"api.prod.com\\\",\\\"description\\\":\\\"Production URL\\\"}]'\"" +``` + +_Note:_ `--openapi:url` is ignored when this option is specified. + +## Swagger UI { #swagger-ui} + +#### Embedded in Node.js + +In Node.js apps, the standard Swagger UI can be served with the help of the [`cds-swagger-ui-express`](https://www.npmjs.com/package/cds-swagger-ui-express) package: + +```sh +npm add --save-dev cds-swagger-ui-express +``` + +Swagger UI is then served at `$api-docs/...`. Just follow the _Open API preview_ links on the index page: +![A screenshot showing the link to the Swagger UI.](assets/swagger-link.png){style="margin:5px auto;width:50%" .adapt} + + +#### Embedded in Java + +Swagger UI is not available out of the box for CAP Java. However, check out this [commit in our CAP Java sample application](https://github.com/SAP-samples/cloud-cap-samples-java/commit/67f0ba618fc7da131d1a104f7a23e8b836e14d93) that demonstrates how to integrate a Swagger UI into your Spring Boot application. + +#### Online Swagger Editor + +Alternatively, you can use the [online Swagger editor](https://editor.swagger.io/) with the OpenAPI files produced with the [CLI](#cli). +In this case, you likely need to enable [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing) because the `swagger.io` site needs to call `localhost`. You can use the [`cors` middleware](https://www.npmjs.com/package/cors), for example. + +## Annotations + +The OData to OpenAPI Mapping can be fine-tuned via annotations in the CSDL (`$metadata`) documents. + +See [Frequently Asked Questions](#faq) for examples on how to use these annotations. + + +## [Core Annotations](https://github.com/oasis-tcs/odata-vocabularies/blob/master/vocabularies/Org.OData.Core.V1.md) + +| Term | Annotation Target | OpenAPI field | +|--------------------|-------------------------------------------------------------------------------|-------------------------------------------------------------------| +| `Computed` | Property | omit from Create and Update structures | +| `DefaultNamespace` | Schema | path templates for actions and functions without namespace prefix | +| `Description` | Action, ActionImport, Function, FunctionImport | `summary` of Operation Object | +| `Description` | EntitySet, Singleton | `description` of Tag Object | +| `Description` | EntityType | `description` of Request Body Object | +| `Description` | ComplexType, EntityType, EnumerationType, Parameter, Property, TypeDefinition | `description` of Schema Object | +| `Description` | Schema, EntityContainer | `info.title` | +| `Example` | Property | `example` of Schema Object | +| `Immutable` | Property | omit from Update structure | +| `LongDescription` | Action, ActionImport, Function, FunctionImport | `description` of Operation Object | +| `LongDescription` | Schema, EntityContainer | `info.description` | +| `Permissions:Read` | Property | omit read-only properties from Create and Update structures | +| `SchemaVersion` | Schema | `info.version` | + + +## [Capabilities](https://github.com/oasis-tcs/odata-vocabularies/blob/master/vocabularies/Org.OData.Capabilities.V1.md) + +| Term | Annotation Target | OpenAPI field | +|-------------------------------------------------------------|----------------------|-------------------------------------------------------------------------------------------------------| +| `CountRestrictions`
 `/Countable` | EntitySet | `$count` system query option for `GET` operation | +| `DeleteRestrictions`
 `/Deletable` | EntitySet, Singleton | `DELETE` operation for deleting an existing entity | +|  `/Description` | EntitySet, Singleton | `summary` of Operation Object | +|  `/LongDescription` | EntitySet, Singleton | `description` of Operation Object | +| `ExpandRestrictions`
 `/Expandable` | EntitySet, Singleton | `$expand` system query option for `GET` operations | +| `FilterRestrictions`
 `/Filterable` | EntitySet | `$filter` system query option for `GET` operation | +|  `/RequiredProperties` | EntitySet | required properties in `$filter` system query option for `GET` operation (parameter description only) | +|  `/RequiresFilter` | EntitySet | `$filter` system query option for `GET` operation is `required` | +| `IndexableByKey` | EntitySet | `GET`, `PATCH`, and `DELETE` operations for a single entity within an entity set | +| `InsertRestrictions`
 `/Insertable` | EntitySet | `POST` operation for inserting a new entity | +|  `/Description` | EntitySet | `summary` of Operation Object | +|  `/LongDescription` | EntitySet | `description` of Operation Object | +| `KeyAsSegmentSupported` | EntityContainer | `paths` URL templates use key-as-segment style instead of parenthesis style | +| `NavigationRestrictions`
 `/RestrictedProperties` | EntitySet, Singleton | operations via a navigation path | +|   `/DeleteRestrictions/...` | EntitySet, Singleton | `DELETE` operation for deleting a contained entity via a navigation path | +|   `/FilterRestrictions/...` | EntitySet, Singleton | `$filter` system query option for reading related entities via a navigation path | +|   `/InsertRestrictions/...` | EntitySet, Singleton | `POST` operation for inserting a new related entity via a navigation path | +|   `/ReadByKeyRestrictions/...` | EntitySet, Singleton | `GET` operation for reading a contained entity by key via a navigation path | +|   `/ReadRestrictions/...` | EntitySet, Singleton | `GET` operation for reading related entities via a navigation path | +|   `/SearchRestrictions/...` | EntitySet, Singleton | `$search` system query option for reading related entities via a navigation path | +|   `/SelectSupport/...` | EntitySet, Singleton | `$select` system query option for reading related entities via a navigation path | +|   `/SkipSupported` | EntitySet, Singleton | `$skip` system query option for reading contained entities via a navigation path | +|   `/SortRestrictions/...` | EntitySet, Singleton | `$orderby` system query option for reading related entities via a navigation path | +|   `/TopSupported` | EntitySet, Singleton | `$top` system query option for reading contained entities via a navigation path | +|   `/UpdateRestrictions/...` | EntitySet, Singleton | `PATCH` operation for modifying a contained entity via a navigation path | +| `ReadByKeyRestrictions`
 `/Readable` | EntitySet | `GET` operation for reading a single entity by key | +|  `/Description` | EntitySet | `summary` of Operation Object | +|  `/LongDescription` | EntitySet | `description` of Operation Object | +| `ReadRestrictions`
 `/Readable` | EntitySet, Singleton | `GET` operation for reading an entity set or singleton | +|  `/Description` | EntitySet, Singleton | `summary` of Operation Object | +|  `/LongDescription` | EntitySet, Singleton | `description` of Operation Object | +| `SearchRestrictions`
 `/Searchable` | EntitySet | `$search` system query option for `GET` operation | +| `SelectSupport`
 `/Supported` | EntitySet, Singleton | `$select` system query option for `GET` operation | +| `SkipSupported` | EntitySet | `$skip` system query option for `GET` operation | +| `SortRestrictions`
 `/NonSortableProperties` | EntitySet | properties not listed in `$orderby` system query option for `GET` operation | +|  `/Sortable` | EntitySet | `$orderby` system query option for `GET` operation | +| `TopSupported` | EntitySet | `$top` system query option for `GET` operation | +| `UpdateRestrictions`
 `/Updatable` | EntitySet, Singleton | `PATCH` operation for modifying an existing entity | +|  `/Description` | EntitySet, Singleton | `summary` of Operation Object | +|  `/LongDescription` | EntitySet, Singleton | `description` of Operation Object | +| `BatchSupport`
 `/Supported` | EntityContainer | `Batch` Support for the service | + + +## [Validation](https://github.com/oasis-tcs/odata-vocabularies/blob/master/vocabularies/Org.OData.Validation.V1.md) + +| Term | Annotation Target | OpenAPI field | +|-----------------|-------------------|-----------------------------------------------------------| +| `AllowedValues` | Property | `enum` of Schema Object - list of allowed (string) values | +| `Exclusive` | Property | `exclusiveMinimum`/`exclusiveMaximum` of Schema Object | +| `Maximum` | Property | `maximum` of Schema Object | +| `Minimum` | Property | `minimum` of Schema Object | +| `Pattern` | Property | `pattern` of Schema Object | + + +## [Authorization](https://github.com/oasis-tcs/odata-vocabularies/blob/master/vocabularies/Org.OData.Authorization.V1.md) + +| Term | Annotation Target | OpenAPI field | +|-------------------|-------------------|--------------------------------------------------------------------------------| +| `Authorizations` | EntityContainer | `securitySchemes` of Components Object/`securityDefinitions` of Swagger Object | +| `SecuritySchemes` | EntityContainer | `security` of OpenAPI/Swagger Object | + + +## Frequently Asked Questions { #faq label='FAQs'} + +Examples for typical questions on how to fine-tune the generated OpenAPI descriptions. + +### Suppress GET (list and by-key) on an entity set? + +To suppress both types of GET requests to an entity set, annotate it with + +```json +"@Capabilities.ReadRestrictions": { + "Readable": false +} +``` + +### Suppress GET (list) on an entity set? + +To suppress only GET list requests to an entity set and still allow GET by-key, annotate it with + +```json +"@Capabilities.ReadRestrictions": { + "Readable": false, + "ReadByKeyRestrictions": { + "Readable": true + } +} +``` + + +### Suppress GET (by-key) on an entity set? + +To suppress only GET by-key requests to an entity set and still allow GET list, annotate it with + +```json +"@Capabilities.ReadRestrictions": { + "ReadByKeyRestrictions": { + "Readable": false + } +} +``` diff --git a/java/architecture.md b/java/architecture.md new file mode 100644 index 0000000000..58b687935c --- /dev/null +++ b/java/architecture.md @@ -0,0 +1,254 @@ +--- +synopsis: > + One of the key CAP design principles is to be an opinionated but yet open framework. Giving a clear guidance for cutting-edge technologies on the one hand and still keeping the door wide open for custom choice on the other hand, demands a highly flexible CAP Java SDK. + The modular architecture reflects this requirement, allowing fine-grained stack configuration and custom extensions. +status: released +uacp: Used as link target from Help Portal at https://help.sap.com/products/BTP/65de2977205c403bbc107264b8eccf4b/9186ed9ab00842e1a31309ff1be38792.html +--- + +# Open Architecture + + +One of the key [CAP design principles](../about/#open-and-opinionated) is to be an opinionated but yet open framework. Giving a clear guidance for cutting-edge technologies on the one hand and still keeping the door wide open for custom choice on the other hand, demands a highly flexible CAP Java SDK. +Section [Architecture Overview](#modular_architecture) explains how the basic architecture of CAP Java meets this requirement, allowing a fine-grained stack [Configuration](#stack_configuration) and extensions with custom modules. + + +## Architecture Overview { #modular_architecture} + +One of the basic design principle of the CAP Java SDK is to keep orthogonal functionality separated in independent components. The obvious advantage of this decoupling is that it makes concrete components exchangeable independently. +Hence, it reduces the risk of expensive adaptions in custom code, which can be necessary due to new requirements with regards to the platform environment or used version of platform services. Hence, the application is [platform **and** service agnostic](../about/#agnostic-approach). + +For instance, custom code doesn't need to be written against the chosen type of persistence service, but can use the generic persistence service based on [CQL](./query-api). Likewise, the application isn't aware of the concrete (cloud) platform environment in which it gets embedded. Consequently, preparing an application to be deployable in different platform contexts is rather a matter of configuration than of code adaption. + +Consequently, CAP Java SDK doesn't determine the technology the application is built on. +But it comes with a chosen set of industry-proven frameworks that can be consumed easily. Nevertheless, you can override the defaults separately depending on the demands in your scenario. + +Moreover, the fine-grained modularization allows you to assemble a minimum set of components, which is necessary to fulfill the application-specific requirements. This reduces resource consumption at runtime as well as maintenance costs significantly. + +Another helpful result of the described architecture is that it simplifies local testing massively. Firstly, as components are coupled weakly, you can define the actual test scope precisely and concentrate on the parts that need a high test coverage. Components outside of the test scope are replaceable with mocks, which ideally simulate all the possible corner cases. +Alternatively, you can even configure test on integration level to be executed locally if you replace all dependencies to remote services by local service providers. A common example for this is to run the application locally on SQLite instead of SAP HANA. + +The following diagram illustrates the modular stack architecture and highlights the generic components: + +The graphic is explained in the accompanying text. + +You can recognize five different areas of the stack, which comprise components according to different tasks: + +* The [application framework](#application-framework) defines the runtime basis of your application typically inclusing a web server. +* [Protocol adapters](#protocol-adapters) map protocol-specific web events into [CQN](../cds/cqn) events for further processing. +* The resulting CQN-events are passed to [service providers](#service-providers), which drive the processing of the event. +* The [CQN execution engine](#cqn-execution-engine) is capable of translating [CQN](../cds/cqn) statements into native statements of a data sink such as a persistence service. +* [Application features](#application-features) are optional extensions that add additional functionality to your application, for instance to add multitenancy capabilities or a platform service integration. + + +### Application Framework { #application-framework} + +Before starting the development of a new CAP-based application, an appropriate application framework to build on needs to be chosen. The architecture of the chosen framework not only has a strong impact on the structure of your project, but it also affects efforts for maintenance as well as support capabilities. +The framework provides the basis of your web application in terms of a runtime container in which your business code can be embedded and executed. This helps to separate your business logic from common tasks like processing HTTP/REST endpoints including basic web request handling. +Typically, a framework also provides you with a rich set of generic tools for recurring tasks like configuration, localization, or logging. In addition, some frameworks come with higher-level concepts like dependency injection or sophisticated testing infrastructure. + +CAP Java SDK positions [Spring](https://spring.io) or more precisely [Spring Boot](https://spring.io/projects/spring-boot) as the first choice application framework, which is seamlessly integrated. Spring comes as a rich set of industry-proven frameworks, libraries, and tools that greatly simplify custom development. Spring Boot also allows the creation of self-contained applications that are easy to configure and run. + +As all other components in the different layers of the CAP Java SDK are decoupled from the concrete application framework, thus you aren't obligated to build on Spring. In some scenarios, it might be even preferable to run the (web) service with minimal resource consumption or with smallest possible usage of open source dependencies. In this case, a solution based on plain Java Servlets could be favorable. Lastly, in case you want to run your application on a 3rd party application framework, you're free to bundle it with CAP modules and provide the glue code, which is necessary for integration. + + +### Protocol Adapters { #protocol-adapters} + +The CAP runtime is based on an [event](../about/#events) driven approach. Generally, [Service](../about/#services) providers are the consumers of events, that means, they do the actual processing of events in [handlers](../guides/providing-services#event-handlers). During execution, services can send events to other service providers and consume the results. The native query language in CAP is [CQN](../cds/cqn), which is accepted by all services that deal with data query and manipulation. Inbound requests therefore need to be mapped to corresponding CQN events, which are sent to an accepting Application Service (see concept [details](../about/#querying)) afterwards. Mapping the ingress protocol to CQN essentially summarizes the task of protocol adapters depicted in the diagram. Most prominent example is the [OData V4](https://www.odata.org/documentation/) protocol adapter, which is fully supported by the CAP Java SDK. Further HTTP-based protocols can be added in future, but often applications require specific protocols, most notably [RESTful](https://en.wikipedia.org/wiki/Representational_state_transfer) ones. Such application-specific protocols can easily be implemented by means of Spring RestControllers. + +The modular architecture allows to add custom protocol adapters in a convenient manner, which can be plugged into the stack at runtime. Note that different endpoints can be served by different protocol adapters at the same time. + + +### Service Providers { #service-providers} + +Services have different purposes. For instance, CDS model services provide an interface to work with persisted data of your [domain model](../about/#domain-modeling). Other services are rather technical, for example, hiding the consumption API of external services behind a generic interface. As described in CAPs [core concepts](../about/#services), services share the same generic provider interface and are implemented by event handlers. The service provider layer contains all generic services, which are auto-exposed by the CAP Java SDK according to the appropriate CDS model. In addition, technical services are offered such as the [Persistence Service](consumption-api#persistenceservice) or [Auditlog Service](auditlog#auditlog-service), which can be consumed in custom service handlers. + +In case the generic handler implementation of a specific service doesn't match the requirements, you can extend or replace it with custom handler logic that fits your business needs. See section [Event Handlers](provisioning-api) for more details. + + +### CQN Execution Engine { #cqn-execution-engine} + +The CQN execution engine is responsible for processing the passed CQN events and translating them to native statements that get executed in a target persistence service like SAP HANA or SQLite. CQN statements can be built conveniently in a [fluent API](./query-api). In the future, additional targets can be added to the list of supported outbound sources. + + +### Application Features { #application-features} + +The overall architecture of the CAP Java SDK allows additional components to be plugged in at runtime. This plugin mechanism makes the architecture open for future extensions and allows context-based configuration. It also enables you to override standard behavior with custom-defined logic in all different layers. Customer components or [extension modules](https://blogs.sap.com/2023/05/16/how-to-build-reusable-plugin-components-for-cap-java-applications/comment-page-1/#comment-674200) that are registered by the runtime can bring custom adapters, custom services or just custom handlers for existing services. + +CAP Java makes use of [features](#standard-modules) itself to provide optional functionality, examples are [SAP Event Mesh](./messaging-foundation) and [Audit logging](./auditlog) integration. + +## Configuration { #stack_configuration} + + As outlined in section [Architecture Overview](#modular_architecture), the CAP Java SDK is highly flexible. You can choose among modules prepared for different environments and in addition also include optional or custom extensions. + Which set of modules is active at runtime is a matter of compile time and runtime configuration. + + At compile time, you can assemble modules from the different layers: + * The [application framework](#application-framework) + * One or more [protocol adapters](#protocol-adapters) + * The core [service providers](#service-providers) + * [Application features](#application-features) to optionally extend the application or adapt to a specific environment + +### Wiring Modules { #module-configuration } + +All CAP Java SDK modules are built as [Maven](https://maven.apache.org/) artifacts and are available on [Apache Maven Central Repository](https://search.maven.org/search?q=com.sap.cds). They've `groupId` `com.sap.cds`. +Beside the Java libraries (Jars) reflecting the modularized functionality, the group also contains a "bill of materials" (BOM) pom named `cds-services-bom`, which is recommended especially for multi-project builds. It basically helps to control the dependency versions of the artifacts and should be declared in dependency management of the parent `pom`: + +```xml + + 2.0.2 + + + + + + com.sap.cds + cds-services-bom + ${cds.services.version} + pom + import + + + +``` + +::: tip Keep Versions in Sync +Importing `cds-services-bom` into the DependencyManagement of your project ensures that versions of all CAP modules are in sync. +::: + +The actual Maven dependencies specified in your `pom` need to cover all libraries that are necessary to run the web application: An application framework, a protocol adapter, and the CAP Java SDK. + +The dependencies of a Spring Boot application with OData V4 endpoints could look like in the following example: + +```xml + + + + com.sap.cds + cds-framework-spring-boot + runtime + + + + + com.sap.cds + cds-adapter-odata-v4 + runtime + + + + + com.sap.cds + cds-services-api + + + com.sap.cds + cds-services-impl + runtime + + +``` + +::: tip API Modules w/o scope `dependency` +Only API modules without dependency scope should be added (they gain `compile` scope by default) such as `cds-services-api` or `cds4j-api`. +All other dependencies should have a dedicated scope, like `runtime` or `test` to prevent misuse. +::: + +You are not obliged to choose one of the prepared application frameworks (identifiable by `artifactId` prefix `cds-framework`), +instead you can define your own application context if required. +Similarly, you're free to configure multiple adapters including custom implementations that map any specific web service protocol. + +::: tip Recommended Application Framework +We highly recommended to configure `cds-framework-spring-boot` as application framework. +It provides you with a lot of [integration with CAP](./development/#spring-boot-integration) out of the box, +as well as enhanced features, such as dependency injection and auto configuration. +::: + +Additional application features you want to use are added as additional dependencies. The following is required to make your application multitenancy aware. + +```xml + + + + com.sap.cds + cds-feature-mt + runtime + + +``` + +Choosing a feature by adding the Maven dependency *at compile time* enables the application to make use of the feature *at runtime*. If a chosen feature misses the required environment at runtime, the feature won't be activated. Together with the fact that all features have a built-in default implementation ready for local usage, you can run the application locally with the same set of dependencies as for productive mode. +For instance, the authentication feature `cds-feature-hana` requires a valid `hana` binding in the environment. Hence, during local development without this binding, this feature gets deactivated and the stack falls back to default feature adapted for SQLite. + +### Standard Modules { #standard-modules } + +CAP Java comes with a rich set of prepared modules in all different layers of the stack: + +**Application Frameworks**: +* `cds-framework-spring`: Makes your application a Spring Boot application. +* `cds-framework-plain`: Adds support to run as plain Java Servlet-based application. + +**Protocol adapters**: +* `cds-adapter-odata-v4`: Auto-exposes Application Services as OData V4 endpoints. +* `cds-adapter-odata-v2`: Auto-exposes Application Services as OData V2 endpoints. +* `cds-adapter-api`: Generic protocol adapter interface to be implemented by customer adapters. + +**Runtime (mandatory)**: +* `cds-services-api`: Interface of the CAP Java SDK. Custom handler or adapter code needs to compile against. +* `cds-services-impl`: Implementation of the CAP Java SDK. + +**Application features**: +* `cds-feature-cloudfoundry`: Makes your application aware of SAP BTP, Cloud Foundry environment. +* `cds-feature-k8s`: [Service binding support for SAP BTP, Kyma Runtime](./development/#kubernetes-service-bindings). +* `cds-feature-hana`: Makes your application aware of SAP HANA data sources. +* `cds-feature-xsuaa`: Adds [XSUAA](https://github.com/SAP/cloud-security-xsuaa-integration)-based authentication to your application. +* `cds-feature-identity`: Adds [Identity Services](https://github.com/SAP/cloud-security-xsuaa-integration) integration covering IAS to your application. +* `cds-feature-mt`: Makes your application multitenant aware. +* `cds-feature-enterprise-messaging`: Connects your application to SAP Event Mesh. +* `cds-feature-remote-odata`: Adds [Remote Service](remote-services#remote-services) support. + +::: tip +`cds-feature-cloudfoundry` and `cds-feature-k8s` can be combined to create binaries that support both environments. +::: + +### Starter Bundles + +To simplify the configuration on basis of Maven dependencies, the CAP Java SDK comes with several starter bundles that help to set up your configuration for most common use cases quickly: + +* `cds-starter-cloudfoundry`: Bundles features to make your application production-ready for SAP BTP, Cloud Foundry environment. It comprises XSUAA authentication, SAP HANA persistence, Cloud Foundry environment for SAP BTP, and multitenancy support. +* `cds-starter-k8s`: Bundles features to make your application production-ready for SAP BTP, Kyma/K8s environment. It comprises XSUAA authentication, SAP HANA persistence, Kyma/K8s environment for SAP BTP, and multitenancy support. +* `cds-starter-spring-boot`: Bundles all dependencies necessary to set up a web-application based on Spring Boot. No protocol adapter is chosen. + +Starter bundle `cds-starter-spring-boot` can be combined with any of the other bundles. + +An example of a CAP application with OData V4 on Cloud Foundry environment: +```xml + + + com.sap.cds + cds-starter-spring-boot + + + + com.sap.cds + cds-adapter-odata-v4 + runtime + + + + com.sap.cds + cds-starter-cloudfoundry + runtime + + +``` + +### Custom Modules { #custom-modules } + +The plugin technique for the [standard modules](#standard-modules) can be used for custom modules in the same way. +By adding an additional dependency in the application project to the custom Maven module, the loaded module automatically adds functionality (usually handlers or providers) or extensions to the CDS model. + +[Learn more about the CAP Java plugin technique.](../java/plugins){ .learn-more} diff --git a/node.js/assets/schema-usage_compressed.mp4 b/node.js/assets/schema-usage_compressed.mp4 new file mode 100644 index 0000000000..22c8a9afea Binary files /dev/null and b/node.js/assets/schema-usage_compressed.mp4 differ