-### Migrating to New Database Services? {.node}
+### Migrating to the `@cap-js/` Database Services? {.node}
-With CDS 8, the new database services for SQLite, PostgreSQL, and SAP HANA are now generally available. It's highly recommended to migrate. You can find instructions in the [migration guide](databases-sqlite#migration). Although the guide is written in the context of the new SQLite Service, the same hints apply to PostgreSQL and SAP HANA.
+With CDS 8, the [`@cap-js`](https://github.com/cap-js/cds-dbs) database services for SQLite, PostgreSQL, and SAP HANA are generally available. It's highly recommended to migrate. You can find instructions in the [migration guide](databases-sqlite#migration). Although the guide is written in the context of the SQLite Service, the same hints apply to PostgreSQL and SAP HANA.
### Adding Database Packages {.node}
-Following are cds-plugin packages for CAP Node.js runtime that support respective databases:
+Following are cds-plugin packages for CAP Node.js runtime that support the respective databases:
| Database | Package | Remarks |
| ------------------------------ | ------------------------------------------------------------ | ---------------------------------- |
@@ -37,7 +37,7 @@ Following are cds-plugin packages for CAP Node.js runtime that support respectiv
| **[PostgreSQL](databases-postgres)** | [`@cap-js/postgres`](https://www.npmjs.com/package/@cap-js/postgres) | maintained by community + CAP team |
-> Follow the links above to find specific information for each.
+> Follow the preceding links to find specific information for each.
In general, all you need to do is to install one of the database packages, as follows:
@@ -345,7 +345,7 @@ Select.from(AUTHOR)
### Standard Operators {.node}
-The database services guarantee identical behavior of these operators:
+The database services guarantee the identical behavior of these operators:
* `==`, `=` — with `=` null being translated to `is null`
* `!=`, `<>` — with `!=` translated to `IS NOT` in SQLite, or to `IS DISTINCT FROM` in standard SQL, or to an equivalent polyfill in SAP HANA
@@ -353,72 +353,11 @@ The database services guarantee identical behavior of these operators:
In particular, the translation of `!=` to `IS NOT` in SQLite — or to `IS DISTINCT FROM` in standard SQL, or to an equivalent polyfill in SAP HANA — greatly improves the portability of your code.
-::: warning Runtime Only
-The operator mappings are available for runtime queries only, but not in CDS files.
-:::
-
-
-### Functions Mappings for Runtime Queries {.node}
-
-A specified set of standard functions is supported in a **database-agnostic**, hence portable way, and translated to database-specific variants or polyfills.
-Note that these functions are only supported within runtime queries, but not in CDS files.
-This set of functions are by large the same as specified in OData:
-
-* `concat(x,y,...)` — concatenates the given strings or numbers
-* `trim(x)` — removes leading and trailing whitespaces
-* `contains(x,y)` — checks whether `y` is contained in `x`, may be fuzzy
-* `startswith(x,y)` — checks whether `y` starts with `x`
-* `endswith(x,y)` — checks whether `y` ends with `x`
-* `matchespattern(x,y)` — checks whether `x` matches regex `y`
-* `substring(x,i,n?)` 1 —
- Extracts a substring from `x` starting at index `i` (0-based) with optional length `n`.
- * **`i`**: Positive starts at `i`, negative starts `i` before the end.
- * **`n`**: Positive extracts `n` items; omitted extracts to the end; negative is invalid.
-* `indexof(x,y)` 1 — returns the index of the first occurrence of `y` in `x`
-* `length(x)` — returns the length of string `x`
-* `tolower(x)` — returns all-lowercased `x`
-* `toupper(x)` — returns all-uppercased `x`
-* `ceiling(x)` — rounds the input numeric parameter up to the nearest numeric value
-* `floor(x)` — rounds the input numeric parameter down to the nearest numeric value
-* `round(x)` — rounds the input numeric parameter to the nearest numeric value.
- The mid-point between two integers is rounded away from zero, i.e. 0.5 is rounded to 1 and ‑0.5 is rounded to -1.
-* `year(x)` `month(x)`, `day(x)`, `hour(x)`, `minute(x)`, `second(x)` —
- returns parts of a datetime for a given `cds.DateTime` / `cds.Date` / `cds.Time`
-* `time(x)`, `date(x)` - returns a string representing the `time` / `date` for a given `cds.DateTime` / `cds.Date` / `cds.Time`
-* `fractionalseconds(x)` - returns a a `Decimal` representing the fractions of a second for a given `cds.Timestamp`
-* `maxdatetime()` - returns the latest possible point in time: `'9999-12-31T23:59:59.999Z'`
-* `mindatetime()` — returns the earliest possible point in time: `'0001-01-01T00:00:00.000Z'`
-* `totalseconds(x)` — returns the duration of the value in total seconds, including fractional seconds. The [OData spec](https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part2-url-conventions.html#sec_totalseconds) defines the input as EDM.Duration: `P12DT23H59M59.999999999999S`
-* `now()` — returns the current datetime
-* `min(x)` `max(x)` `sum(x)` `average(x)` `count(x)`, `countdistinct(x)` — aggregate functions
-* `search(xs,y)` — checks whether `y` is contained in any of `xs`, may be fuzzy → [see Searching Data](../guides/providing-services#searching-data)
-* `session_context(v)` — with standard variable names → [see Session Variables](#session-variables)
-> 1 These functions work zero-based. E.g., `substring('abcdef', 1, 3)` returns 'bcd'
-
-> You have to write these functions exactly as given; all-uppercase usages aren't supported.
-
-In addition to the standard functions, which all `@cap-js` database services support, `@cap-js/sqlite` and `@cap-js/postgres` also support these common SAP HANA functions, to further increase the scope for portable testing:
-
-* `years_between` — Computes the number of years between two specified dates.
-* `months_between` — Computes the number of months between two specified dates.
-* `days_between` — Computes the number of days between two specified dates.
-* `seconds_between` — Computes the number of seconds between two specified dates.
-* `nano100_between` — Computes the time difference between two dates to the precision of 0.1 microseconds.
-
-The database service implementation translates these to the best-possible native SQL functions, thus enhancing the extent of **portable** queries.
-With open source and the new database service architecture, we also have methods in place to enhance this list by custom implementation.
-
-> For the SAP HANA functions, both usages are allowed: all-lowercase as given above, as well as all-uppercase.
-
-::: warning Runtime Only
-The function mappings are available for runtime queries only, but not in CDS files.
-:::
-
### Session Variables {.node}
-The API shown below, which includes the function `session_context()` and specific pseudo variable names, is supported by **all** new database services, that is, *SQLite*, *PostgreSQL* and *SAP HANA*.
-This allows you to write respective code once and run it on all these databases:
+The API shown after this, which includes the function `session_context()` and specific pseudo variable names, is supported by **all** new database services, that is, *SQLite*, *PostgreSQL* and *SAP HANA*.
+This allows you to write the respective code once and run it on all these databases:
```sql
SELECT session_context('$user.id')
@@ -454,7 +393,7 @@ db.queryForList("SELECT from sqlite_schema where name like ?", name);
### Reading `LargeBinary` / BLOB {.node}
-Formerly, `LargeBinary` elements (or BLOBs) were always returned as any other data type. Now, they are skipped from `SELECT *` queries. Yet, you can still enforce reading BLOBs by explicitly selecting them. Then the BLOB properties are returned as readable streams.
+Formerly, `LargeBinary` elements (or BLOBs) were always returned as any other data type. Now, they're skipped from `SELECT *` queries. Yet, you can still enforce reading BLOBs by explicitly selecting them. Then the BLOB properties are returned as readable streams.
```js
SELECT.from(Books) //> [{ ID, title, ..., image1, image2 }] // [!code --]
@@ -481,7 +420,7 @@ You can also do this manually with the CLI command `cds compile --to `.
When you've created a CAP Java application with `cds init --java` or with CAP Java's [Maven archetype](../java/developing-applications/building#the-maven-archetype), the Maven build invokes the CDS compiler to generate a `schema.sql` file for your target database. In the `default` profile (development mode), an in-memory database is [initialized by Spring](https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#howto.data-initialization) and the schema is bootstrapped from the `schema.sql` file.
-[Learn more about adding an inital database schema.](../java/cqn-services/persistence-services#initial-database-schema){.learn-more}
+[Learn more about adding an initial database schema.](../java/cqn-services/persistence-services#initial-database-schema){.learn-more}
@@ -791,7 +730,7 @@ The following rules apply:
- If you refer to a column name in the annotation, you need to take care of
a potential name mapping yourself, for example, for structured elements.
-- Annotation `@sql.prepend` is only supported for entities translating to tables. It can't be used with views nor with elements.
+- Annotation `@sql.prepend` is only supported for entities translating to tables. It can't be used with views or with elements.
- For SAP HANA tables, there's an implicit `@sql.prepend: 'COLUMN'` that is overwritten by an explicitly provided `@sql.prepend`.
* Both `@sql.prepend` and `@sql.append` are disallowed in SaaS extension projects.
@@ -823,7 +762,7 @@ ROW TABLE E (
[Learn more about Columnar and Row-Based Data Storage](https://help.sap.com/docs/hana-cloud-database/sap-hana-cloud-sap-hana-database-administration-guide/columnar-and-row-based-data-storage){.learn-more}
### Reserved Words
-The CDS compiler and CAP runtimes provide smart quoting for reserved words in SQLite and in SAP HANA so that they can still be used in most situations. But in general reserved words cannot be used as identifiers. The list of reserved words varies per database.
+The CDS compiler and CAP runtimes provide smart quoting for reserved words in SQLite and in SAP HANA so that they can still be used in most situations. But in general reserved words can't be used as identifiers. The list of reserved words varies per database.
Find here a collection of resources on selected databases and their reference documentation:
@@ -841,6 +780,46 @@ Find here a collection of resources on selected databases and their reference do
## Database Constraints
+### Not Null
+
+You can specify that a column's value must not be `NULL` by adding the [`not null` constraint](../cds/cdl#null-values) to the element, for example:
+
+```cds
+entity Books {
+ key ID: Integer;
+ title: String not null;
+}
+```
+
+
+### Unique
+
+Annotate an entity with `@assert.unique.Java projects have to use a sidecar architecture. For Node.js this is optional, but allows for better scalability in multitenant scenarios. + [Learn more about **Multitenant Saas Application Deployment**](./to-cf){.learn-more} - `mtx-extension`: Creates a deployment layout (_extension.tgz_ file) for an MTX extension project, which is required for extension activation using `cds push`. Extension point restrictions defined by the SaaS app provider are validated by default. If any restriction is violated the build aborts and the errors are logged.
- The build task is created by default for projects that have `"cds": { "extends": "\
+ The build task is created by default for projects that have `"cds": { "extends": "\
+- Additional types may be supported by build plugin contributions. + [Learn more about **Running Build Plugins**](#run-the-plugin){.learn-more} Build tasks can be customized using the following properties: @@ -78,6 +105,7 @@ Build tasks can be customized using the following properties: - `dest`: Optional destination of the modules builds, relative to the enclosing project. The _src_ folder is used by default. - `options`: Sets the options according to the target technology.
- `model`: It has type _string_ or _array of string_. The given list of folders or individual _.cds_ file names is resolved based on the current working dir or the project folder passed to cds build. CDS built-in models (prefix _@sap/cds*_) are added by default to the user-defined list of models. + [Learn more about **Core Data Services (CDS)**](../../cds/){.learn-more} **Note:** @@ -85,18 +113,14 @@ Alternatively you can execute build tasks and pass the described arguments from ### Build Target Folder {#build-target-folder} -If you want to change the default target folder, use the `target` property in _.cdsrc.json_ or _package.json_. It is resolved based on the root folder of your project. +If you want to change the default target folder, use the
-Relevant source files from _db_ or _srv_ folders are copied into this folder, which makes it a self-contained folder that is ready for deployment. The default folder names can be changed with the _folders.db_, _folders.srv_, _folders.app_ configuration. Or you can go for individual build task configuration for full flexibility. +Relevant source files from _db_ or _srv_ folders are copied into this folder, which makes it self-contained and ready for deployment. The default folder names can be changed with the
-While we used SQLite as a low-cost stand-in during development, we're going to use an SAP HANA Cloud database for production:
+While we used SQLite as a low-cost stand-in during development, we're using an SAP HANA Cloud database for production:
@@ -147,7 +145,7 @@ While we used SQLite or H2 as a low-cost stand-in during development, we're goin
```sh
-cds add hana --for production
+cds add hana
```
[Learn more about using SAP HANA for production.](../databases-hana){.learn-more}
@@ -157,24 +155,13 @@ cds add hana --for production
Configure your app for XSUAA-based authentication:
```sh
-cds add xsuaa --for production
+cds add xsuaa
```
::: tip This will also generate an `xs-security.json` file
The roles/scopes are derived from authorization-related annotations in your CDS models. Ensure to rerun `cds compile --to xsuaa`, as documented in the [_Authorization_ guide](/guides/security/authorization#xsuaa-configuration) whenever there are changes to these annotations.
:::
-::: details For trial and extension landscapes, OAuth configuration is required
-Add the following snippet to your _xs-security.json_ and adapt it to the landscape you're deploying to:
-
-```json
-"oauth2-configuration": {
- "redirect-uris": ["https://*.cfapps.us10-001.hana.ondemand.com/**"]
-}
-```
-
-:::
-
[Learn more about SAP Authorization and Trust Management/XSUAA.](https://discovery-center.cloud.sap/serviceCatalog/authorization-and-trust-management-service?region=all){.learn-more}
### 3. MTA-Based Deployment { #add-mta-yaml}
@@ -221,12 +208,14 @@ For **single-tenant applications**, you can use [SAP Build Work Zone, Standard E
cds add workzone
```
+**Important:** This also requires you to set up SAP Build Work Zone, Standard Edition [according to the SAP Learning tutorial](https://developers.sap.com/tutorials/spa-configure-workzone.html).
+
### 6. Optional: Multitenancy { #add-multitenancy }
To enable multitenancy for production, run the following command:
```sh
-cds add multitenancy --for production
+cds add multitenancy
```
[Learn more about MTX services.](../multitenancy/#behind-the-scenes){.learn-more}
@@ -242,24 +231,23 @@ The previous steps are required _only once_ in a project's lifetime. With that d
## Build and Deploy
-You can now freeze dependencies, build, and deploy the application:
-
+Make sure you are logged in to Cloud Foundry and target the space you want to deploy to:
```sh
-cds up
+cf login --sso # to log on with SAP Universal ID
+cf target
```
+[Learn more about `cf login`](https://help.sap.com/products/BTP/65de2977205c403bbc107264b8eccf4b/7a37d66c2e7d401db4980db0cd74aa6b.html){.learn-more}
-[You need to be logged in to Cloud Foundry.](https://help.sap.com/products/BTP/65de2977205c403bbc107264b8eccf4b/7a37d66c2e7d401db4980db0cd74aa6b.html){.learn-more}
+::: tip Prevent outdated lock file issues
+If your project already includes a _package-lock.json_, run `npm update` to make sure it’s in sync with your _package.json_ before proceeding.
+:::
-
-
-
::: details Essentially, this automates the following steps...
```sh
@@ -267,8 +255,11 @@ ln -sf ../package-lock.json
npm i app/browse
npm i app/admin-books
+# If project is monorepo
+ln -sf ../package-lock.json
+
# If project is multitenant
-npm i --package-lock-only mtx/sidecar
+npm i --package-lock-only --prefix mtx/sidecar
# If package-lock.json doesn't exist
npm i --package-lock-only
@@ -308,7 +299,7 @@ You can use this URL to access the approuter as the entry point of your applicat
For **multitenant applications**, you have to subscribe a tenant first. The application is accessible via a tenant-specific URL after subscription.
::: tip No index page and SAP Fiori preview in the cloud
-The default index page and [SAP Fiori preview](../../advanced/fiori#sap-fiori-preview), that you are used to see from local development, are only available for the development profile and not available in the cloud. For productive applications, you should add a proper SAP Fiori Elements application through on of the [user interface options](#add-ui) outlined before.
+The default index page and [SAP Fiori preview](../../advanced/fiori#sap-fiori-preview), that you are used to seeing during local development, are only meant for the development profile and not available in the cloud. For productive applications, you should add a proper SAP Fiori elements application through on of the [user interface options](#add-ui) outlined before.
:::
### Inspect Apps in BTP Cockpit
diff --git a/guides/deployment/to-kyma.md b/guides/deployment/to-kyma.md
index e02c665201..c1d01c6965 100644
--- a/guides/deployment/to-kyma.md
+++ b/guides/deployment/to-kyma.md
@@ -85,9 +85,15 @@ The following diagram illustrates the deployment workflow:
+ Make sure your SAP HANA Cloud is [mapped to your namespace](https://community.sap.com/t5/technology-blogs-by-sap/consuming-sap-hana-cloud-from-the-kyma-environment/ba-p/13552718#toc-hId-569025164)
+ Ensure SAP HANA Cloud is accessible from your Kyma cluster by [configuring trusted source IPs](https://help.sap.com/docs/HANA_CLOUD/9ae9104a46f74a6583ce5182e7fb20cb/0610e4440c7643b48d869a6376ccaecd.html)
+#### Configure Kubernetes
+
+Download the Kubernetes configuration from SAP BTP and move it to _$HOME/.kube/config_.
+
+[Learn more in the SAP BTP Kyma documentation](https://help.sap.com/docs/btp/sap-business-technology-platform/access-kyma-instance-using-kubectl){.learn-more}
+
#### Get Access to a Container Registry
-SAP BTP doesn't provide a container registry, but you can choose from offerings of hosted open source and private container image registries, as well as solutions that can be run on premise or in your own cloud infrastructure.
+SAP BTP doesn't provide a container image registry (or container repository), but you can choose from offerings of hosted open source and private container image registries, as well as solutions that can be run on premise or in your own cloud infrastructure.
::: tip Ensure network access
@@ -102,26 +108,17 @@ To use a docker image from a private repository, you need to [create an image pu
::: details Use this script to create the docker pull secret...
```sh
-echo -n "Your repository: "; read YOUR_REPOSITORY
+echo -n "Your docker registry server: "; read YOUR_REGISTRY
echo -n "Your user: "; read YOUR_USER
echo -n "Your email: "; read YOUR_EMAIL
-echo -n "Your API key: "; read -s YOUR_API_KEY
+echo -n "Your API token: "; read -s YOUR_API_TOKEN
kubectl create secret docker-registry \
- "$YOUR_REPOSITORY" \
+ docker-registry \
"--docker-server=$YOUR_REGISTRY" \
"--docker-username=$YOUR_USER" \
- "--docker-password=$YOUR_API_KEY" \
+ "--docker-password=$YOUR_API_TOKEN" \
"--docker-email=$YOUR_EMAIL"
-```
-The `image` property needs to contain the full tag that was used to push the image to the repository:
-
-```yaml
-spec:
- imagePullSecrets:
- - name: $YOUR_REPOSITORY
- containers:
- - name: cap-srv
- image: $YOUR_REPOSITORY.docker.io/$YOUR_IMAGE:$YOUR_VERSION
+# The 2nd 'docker-registry' above is our default secret name.
```
:::
@@ -135,11 +132,24 @@ It is recommended to use a technical user for this secret that has only read per
Let's start with a new sample project and prepare it for production using an SAP HANA database and XSUAA for authentication:
+
+
+```sh
+cds init bookshop --java --add sample && cd bookshop
+cds add hana,xsuaa
+```
+
+
+
+
```sh
cds init bookshop --add sample && cd bookshop
-cds add hana,xsuaa --for production
+cds add hana,xsuaa
```
+
+
+
#### User Interfaces
@@ -274,6 +274,11 @@ After adding multitenancy, Maven build should be used to generate the model rela
mvn install
```
+:::warning Error message: 'Invalid MTX sidecar configuration'
+If you get the message 'Invalid MTX sidecar configuration', you need to add the dependency to `@sap/cds-mtxs` also to the `package.json` in your project root.
+This is a known issue in CDS 9.
+:::
+
## Test-Drive Locally {#test-locally}
@@ -715,7 +720,7 @@ In order to get your multitenant application deployed, follow this excerpt from
Once: Add SAP HANA Cloud, XSUAA, and [App Router](../deployment/to-cf#add-app-router) configuration. The App Router acts as a single point-of-entry gateway to route requests to. In particular, it ensures user login and authentication in combination with XSUAA.
```sh
-cds add hana,xsuaa --for production
+cds add hana,xsuaa
```
If you intend to serve UIs you can easily set up the SAP Cloud Portal service:
@@ -751,33 +756,15 @@ Add the following snippet to your _xs-security.json_ and adapt it to the landsca
[Learn more about configured BTP services for SaaS applications.](#behind-the-scenes){.learn-more}
-[Freeze the `npm` dependencies](../deployment/to-cf#freeze-dependencies) for server and MTX sidecar.
-
-```sh
-npm update --package-lock-only
-npm update --package-lock-only --prefix mtx/sidecar
-```
-
-In addition, you need install and freeze dependencies for your UI applications:
-```sh
-npm i --prefix app/browse
-npm i --prefix app/admin-books
-```
-
-**Build and deploy**:
::: code-group
```sh [Cloud Foundry]
-mbt build -t gen --mtar mta.tar
-cf deploy gen/mta.tar
+cds up
```
```sh [Kyma]
-# Omit `--push` flag for testing, otherwise `ctz`
-# will push images to the specified repository
-ctz containerize.yaml --push
-helm upgrade --install bookshop ./chart
+cds up --to k8s
```
:::
@@ -993,14 +980,14 @@ cds watch --profile dev
## SaaS Dependencies {#saas-dependencies}
Some of the xsuaa-based services your application consumes need to be registered as _reuse services_ to work in multitenant environments. This holds true for the usage of both the SaaS Registry service and the Subscription Manager Service (SMS).
-CAP Java as well as `@sap/cds-mtxs`, each offer an easy way to integrate these dependencies. They support some services out of the box and also provide a simple API for applications. Most notably, you need such dependencies for the following SAP BTP services: [Audit Log](https://discovery-center.cloud.sap/serviceCatalog/audit-log-service), [Event Mesh](https://discovery-center.cloud.sap/serviceCatalog/event-mesh), [Destination](https://discovery-center.cloud.sap/serviceCatalog/destination), [HTML5 Application Repository](https://discovery-center.cloud.sap/serviceCatalog/html5-application-repository-service), and [Cloud Portal](https://discovery-center.cloud.sap/serviceCatalog/cloud-portal-service).
+CAP Java as well as `@sap/cds-mtxs`, each offer an easy way to integrate these dependencies. They support some services out of the box and also provide a simple API for applications. Most notably, you need such dependencies for the following SAP BTP services: [Audit Log](https://discovery-center.cloud.sap/serviceCatalog/audit-log-service), [Event Mesh](https://discovery-center.cloud.sap/serviceCatalog/event-mesh), [Destination](https://discovery-center.cloud.sap/serviceCatalog/destination), [HTML5 Application Repository](https://discovery-center.cloud.sap/serviceCatalog/html5-application-repository-service), and [Cloud Portal](https://discovery-center.cloud.sap/serviceCatalog/cloud-portal-service).
For CAP Java, all these services are supported natively and SaaS dependencies are automatically created if such a service instance is bound to the CAP Java application, that is, the `srv` module.
:::tip Explicitly activate the Destination service
SaaS dependency for Destination service needs to be activated explicitly in the `application.yaml` due to security reasons. SaaS dependencies for some of the other services can be **de**activated by setting the corresponding property to `false` in the `application.yaml`.
-Refer to the `cds.multiTenancy.dependencies` section in the [CDS properties](/java/developing-applications/properties#cds-properties).
+Refer to the `cds.multiTenancy.dependencies` section in the [CDS properties](/java/developing-applications/properties#cds-properties).
:::
For CAP Node.js, all these services are supported natively and can be activated individually by providing configuration in `cds.requires`. In the most common case, you simply activate service dependencies like so:
@@ -1049,10 +1036,11 @@ The Boolean values in the _mtx/sidecar/package.json_ activate the default config
### Additional Services
-If your CAP Java application uses a service that isn't supported out of the box, you can add a custom dependency by providing a custom handler. Refer to [Define Dependent Services](../../java/multitenancy#define-dependent-services) for details.
+In **CAP Java**, if your application uses a service that isn't supported out of the box, you can define dependencies by providing a custom handler.
+[Learn more about defining dependent services](../../java/multitenancy#define-dependent-services){.learn-more}
-In Node.js, you can use the `subscriptionDependency` setting to provide a dependency configuration similar to the standard configuration shown before. Use your application's or CAP plugin's _package.json_:
+In **CAP Node.js**, you can use a custom `subscriptionDependency` entry in your application's or CAP plugin's _package.json_:
```json [package.json]
"cds": {
@@ -1068,7 +1056,6 @@ In Node.js, you can use the `subscriptionDependency` setting to provide a depend
Alternatively, overriding the [`dependencies`](./mtxs#get-dependencies) handler gives you full flexibility for any custom implementation.
-
## Add Custom Handlers
diff --git a/guides/multitenancy/mtxs.md b/guides/multitenancy/mtxs.md
index 1c96b8c0c9..178530494e 100644
--- a/guides/multitenancy/mtxs.md
+++ b/guides/multitenancy/mtxs.md
@@ -1140,7 +1140,6 @@ The _SaasProvisioningService_ is a façade for the _DeploymentService_ to adapt
- `workerSize` — max number of parallel asynchronous jobs per database
- `clusterSize` — max number of database clusters, running `workerSize` jobs each
- `queueSize` — max number of jobs waiting to run in the job queue
-- `dependencies` — SAP BTP SaaS Provisioning service dependencies
#### HTTP Request Options
diff --git a/guides/multitenancy/old-mtx-migration.md b/guides/multitenancy/old-mtx-migration.md
index 59d8042927..fdc81580db 100644
--- a/guides/multitenancy/old-mtx-migration.md
+++ b/guides/multitenancy/old-mtx-migration.md
@@ -20,8 +20,14 @@ Towards new multitenancy capabilities
-
-CAP Java offers the option to enable rejection conditions for `UPDATE`, `DELETE` and custom events. Enable it using the configuration option cds.security.authorization.instance-based.reject-selected-unauthorized-entity.enabled: true .
-
-
-
::: info Avoid enumerable keys
In case the filter condition is not met in an `UPDATE` or `DELETE` request, the runtime rejects the request (response code 403) even if the user is not even allowed to read the entity. To avoid to disclosure the existence of such entities to unauthorized users, make sure that the key is not efficiently enumerable.
:::
@@ -899,7 +892,7 @@ Information about roles and attributes has to be made available to the UAA platf
Derive scopes, attributes, and role templates from the CDS model:
```sh
-cds add xsuaa --for production
+cds add xsuaa
```
This generates an _xs-security.json_ file:
diff --git a/guides/using-services.md b/guides/using-services.md
index 37d5d7c5f8..847616b79a 100644
--- a/guides/using-services.md
+++ b/guides/using-services.md
@@ -92,7 +92,7 @@ If you want to learn about this topic based on the [Incident Management](https:/
## Install Dependencies { .node }
```sh
-npm add @sap-cloud-sdk/http-client@3.x @sap-cloud-sdk/connectivity@3.x @sap-cloud-sdk/resilience@3.x
+npm add @sap-cloud-sdk/http-client@4.x @sap-cloud-sdk/connectivity@4.x @sap-cloud-sdk/resilience@4.x
```
## Get and Import an External Service API { #external-service-api }
@@ -986,7 +986,7 @@ Since you don't want to use the destination for local testing, but only for prod
}
```
-Additionally, you can provide [destination options](https://sap.github.io/cloud-sdk/api/v3/interfaces/sap-cloud-sdk_connectivity.DestinationFetchOptions.html) inside a `destinationOptions` object:
+Additionally, you can provide [destination options](https://sap.github.io/cloud-sdk/api/v4/interfaces/sap-cloud-sdk_connectivity.DestinationFetchOptions.html) inside a `destinationOptions` object:
```jsonc
"cds": {
@@ -1394,7 +1394,7 @@ The MTA-based deployment is described in [the deployment guide](deployment/). Yo
```sh
-cds add xsuaa,destination,connectivity --for production
+cds add xsuaa,destination,connectivity
```
::: details Learn what this does in the background...
@@ -1661,7 +1661,7 @@ This list specifies the properties for application defined destinations.
| `queries` | Map of URL parameters |
| `forwardAuthToken` | [Forward auth token](#forward-auth-token) |
-[Destination Type in SAP Cloud SDK for JavaScript](https://sap.github.io/cloud-sdk/api/v3/interfaces/sap_cloud_sdk_connectivity.Destination.html){.learn-more .node}
+[Destination Type in SAP Cloud SDK for JavaScript](https://sap.github.io/cloud-sdk/api/v4/interfaces/sap-cloud-sdk_connectivity.Destination.html){.learn-more .node}
[HttpDestination Type in SAP Cloud SDK for Java](https://help.sap.com/doc/82a32040212742019ce79dda40f789b9/1.0/en-US/index.html){.learn-more .java}
#### Authentication Types
diff --git a/index.md b/index.md
index e3f23d0d7e..e14dee3470 100644
--- a/index.md
+++ b/index.md
@@ -36,7 +36,7 @@ features:
details:
• Capture intent ⇒ What, not how! • Minimized boilerplate coding
- • Developers + domain experts
+ • Minimized technical debt
link: about/ linkText: Read the Primer @@ -44,7 +44,7 @@ features: icon: 🌀 details: • Jumpstart with minimal setup
- • Rapid dev at minimized costs
+ • Fast inner loop dev & tests
• Grow as you go...
link: get-started/in-a-nutshell linkText: Get Started in a Nutshell diff --git a/java/_menu.md b/java/_menu.md index d69dd1f514..04e7b8b858 100644 --- a/java/_menu.md +++ b/java/_menu.md @@ -16,14 +16,14 @@ ## [Indicating Errors](event-handlers/indicating-errors) ## [Request Contexts](event-handlers/request-contexts) ## [ChangeSet Contexts](event-handlers/changeset-contexts) -# [Fiori Drafts](../../java/fiori-drafts) +# [Fiori Drafts](fiori-drafts) # [Messaging](messaging) # [Audit Logging](auditlog) -# [Change Tracking](../../java/change-tracking) +# [Change Tracking](change-tracking) # [State Transitions](../../java/flows) # [Transactional Outbox](outbox) -# [Multitenancy](../../java/multitenancy) - ## [Multitenancy (Classic)](../../java/multitenancy-classic) +# [Multitenancy](multitenancy) + ## [Multitenancy (Classic)](multitenancy-classic) # [Security](security) ## [IAS and AMS](../../java/ams) # [Spring Boot Integration](spring-boot-integration) @@ -37,5 +37,7 @@ ## [Optimizing](operating-applications/optimizing) ## [Observability](operating-applications/observability) ## [Developer Dashboard](../../java/operating-applications/dashboard) +# [Integrating Applications](../../java/integrating-applications/) + ## [Unified Customer Landscape](../../java/integrating-applications/ucl) # [Building Plugins](../../java/building-plugins) # [Migration Guides](migration) \ No newline at end of file diff --git a/java/cds-data.md b/java/cds-data.md index e24f4fa9e0..a897eea7ae 100644 --- a/java/cds-data.md +++ b/java/cds-data.md @@ -21,47 +21,49 @@ uacp: Used as link target from Help Portal at https://help.sap.com/products/BTP/ The [predefined CDS types](../cds/types) are mapped to Java types and as follows: -| CDS Type | Java Type | Remark | -|--------------------|------------------------|--------------------------------------------------------------------------| -| `cds.UUID` | `java.lang.String` | | -| `cds.Boolean` | `java.lang.Boolean` | | -| `cds.UInt8` | `java.lang.Short` | | -| `cds.Int16` | `java.lang.Short` | | -| `cds.Int32` | `java.lang.Integer` | | -| `cds.Integer` | `java.lang.Integer` | | -| `cds.Int64` | `java.lang.Long` | | -| `cds.Integer64` | `java.lang.Long` | | -| `cds.Decimal` | `java.math.BigDecimal` | | -| `cds.DecimalFloat` | `java.math.BigDecimal` | deprecated | -| `cds.Double` | `java.lang.Double` | | -| `cds.Date` | `java.time.LocalDate` | date without a time-zone (year-month-day) | -| `cds.Time` | `java.time.LocalTime` | time without a time-zone (hour-minute-second) | -| `cds.DateTime` | `java.time.Instant` | instant on the time-line with _sec_ precision | -| `cds.Timestamp` | `java.time.Instant` | instant on the time-line with _µs_ precision | -| `cds.String` | `java.lang.String` | | -| `cds.LargeString` | `java.lang.String` | `java.io.Reader` (1) if annotated with `@Core.MediaType` | -| `cds.Binary` | `byte[]` | | -| `cds.LargeBinary` | `byte[]` | `java.io.InputStream` (1) if annotated with `@Core.MediaType` | -| `cds.Vector` | `com.sap.cds.CdsVector`| for [vector embeddings](#vector-embeddings) | +| CDS Type | Java Type | Remark | +| ------------------ | ----------------------- | ------------------------------------------------------------------------ | +| `cds.UUID` | `java.lang.String` | | +| `cds.Boolean` | `java.lang.Boolean` | | +| `cds.UInt8` | `java.lang.Short` | | +| `cds.Int16` | `java.lang.Short` | | +| `cds.Int32` | `java.lang.Integer` | | +| `cds.Integer` | `java.lang.Integer` | | +| `cds.Int64` | `java.lang.Long` | | +| `cds.Integer64` | `java.lang.Long` | | +| `cds.Decimal` | `java.math.BigDecimal` | | +| `cds.DecimalFloat` | `java.math.BigDecimal` | deprecated | +| `cds.Double` | `java.lang.Double` | | +| `cds.Date` | `java.time.LocalDate` | date without a time-zone (year-month-day) | +| `cds.Time` | `java.time.LocalTime` | time without a time-zone (hour-minute-second) | +| `cds.DateTime` | `java.time.Instant` | instant on the time-line with _sec_ precision | +| `cds.Timestamp` | `java.time.Instant` | instant on the time-line with _µs_ precision | +| `cds.String` | `java.lang.String` | | +| `cds.LargeString` | `java.lang.String` | `java.io.Reader` (1) if annotated with `@Core.MediaType` | +| `cds.Binary` | `byte[]` | | +| `cds.LargeBinary` | `byte[]` | `java.io.InputStream` (1) if annotated with `@Core.MediaType` | +| `cds.Vector` | `com.sap.cds.CdsVector` | for [vector embeddings](#vector-embeddings) | +| `cds.Map` | `java.util.Map` | for arbitrary [structured data](#structured-data)(2) | ### SAP HANA-Specific Data Types To facilitate using legacy CDS models, the following [SAP HANA-specific data types](../advanced/hana#hana-types) are supported: -| CDS Type | Java Type | Remark | -| --- | --- | --- | -| `hana.TINYINT` | `java.lang.Short` | | -| `hana.SMALLINT` | `java.lang.Short` | | -| `hana.SMALLDECIMAL` | `java.math.BigDecimal` | | -| `hana.REAL` | `java.lang.Float` | | -| `hana.CHAR` | `java.lang.String` | | -| `hana.NCHAR` | `java.lang.String` | | -| `hana.VARCHAR` | `java.lang.String` | | -| `hana.CLOB` | `java.lang.String` | `java.io.Reader` (1) if annotated with `@Core.MediaType` | -| `hana.BINARY` | `byte[]` | | +| CDS Type | Java Type | Remark | +| ------------------- | ---------------------- | ------------------------------------------------------------------- | +| `hana.TINYINT` | `java.lang.Short` | | +| `hana.SMALLINT` | `java.lang.Short` | | +| `hana.SMALLDECIMAL` | `java.math.BigDecimal` | | +| `hana.REAL` | `java.lang.Float` | | +| `hana.CHAR` | `java.lang.String` | | +| `hana.NCHAR` | `java.lang.String` | | +| `hana.VARCHAR` | `java.lang.String` | | +| `hana.CLOB` | `java.lang.String` | `java.io.Reader` (1) if annotated with `@Core.MediaType` | +| `hana.BINARY` | `byte[]` | | > (1) Although the API to handle large objects is the same for every database, the streaming feature, however, is supported (and tested) in **SAP HANA**, **PostgreSQL**, and **H2**. See section [Database Support in Java](./cqn-services/persistence-services#database-support) for more details on database support and limitations. +> (2) Serialized as JSON to a CLOB column or JSONB column (on Postgres) ::: warning The framework isn't responsible for closing the stream when writing to the database. You decide when the stream is to be closed. If you forget to close the stream, the open stream can lead to a memory leak. @@ -275,6 +277,8 @@ person.toJson(); // { "salutation" : "Mr.", name : { "first" : "Frank" } } Avoid cyclic relationships between CdsData objects when using toJson. ::: + + ## Vector Embeddings
diff --git a/java/messaging.md b/java/messaging.md index 0893f3954b..ff064a2dd0 100644 --- a/java/messaging.md +++ b/java/messaging.md @@ -68,11 +68,11 @@ With the availability of a messaging service, you can now use it to send message MessagingService messagingService; // Sending via the technical API of the messaging service -messagingService.emit("My/Destination/Messaging/Topic", "raw message payload"); +messagingService.emit("My/Topic", Map.of("message", "hello world")); // Sending by emitting a context via CAP service API -TopicMessageEventContext context = TopicMessageEventContext.create("My/Destination/Messaging/Topic"); -context.setData("raw message payload"); +TopicMessageEventContext context = TopicMessageEventContext.create("My/Topic"); +context.setDataMap(Map.of("message", "hello world")); messagingService.emit(context); ``` @@ -99,11 +99,11 @@ To receive messages matching a desired topic from a message broker, you just nee Example: ```java -@On(service = "messaging-name", event = "My/Destination/Messaging/Topic") +@On(service = "messaging-name", event = "My/Topic") public void receiveMyTopic(TopicMessageEventContext context) { // get ID and payload of message String msgId = context.getMessageId(); - String payload = context.getData(); + Map
`
`emptyAttributeValuesAreRestricted` | [Use conditions with explicit checks for empty attributes.](../guides/security/authorization#user-attrs) | +| `cds.odataV4.serializer.buffered` | OData V4 responses are now always streamed while serialized. | +| `cds.environment.k8s` | Use service bindings from SAP BTP Operator on Kyma. | +| `cds.multiTenancy.subscriptionManager.`
`clientCertificateHeader` | `cds.security.authentication.`
`clientCertificateHeader` | +| `cds.multiTenancy.security.`
`internalUserAccess.enabled` | `cds.security.authentication.`
`internalUserAccess.enabled` | + +### Removed Java APIs + +- Removed deprecated classes: + - `com.sap.cds.ql.cqn.CqnSearchPredicate`, use `CqnSearchTermPredicate` instead + +- Removed deprecated methods: + - `com.sap.cds.ql.cqn.Modifier.search(String term)`, use `searchTerm(CqnSearchTermPredicate)` instead + - `com.sap.cds.ql.cqn.Modifier.selectListValue(Value value, String alias)`, use `selectListValue(SelectableValue value, String alias)` instead + - `com.sap.cds.ql.SelectableValue.withoutAlias()`, use `as(String alias)` instead + ## CAP Java 2.10 to CAP Java 3.0 { #two-to-three } ### Minimum Versions @@ -174,7 +284,7 @@ Some property defaults have been adjusted: | `cds.sql.hana.optimizationMode` | `legacy` | `hex` | SQL for SAP HANA is optimized for the HEX engine. | | `cds.odataV4.lazyI18n.enabled` | `null` | `true` | Lazy localization is now enabled by default in multitenant scenarios. | | `cds.auditLog.personalData.`
`throwOnMissingDataSubject` | `false` | `true` | Raise errors for incomplete personal data annotations by default. | -| `cds.messaging.services.
| Operator | + | |||
|---|---|---|---|---|
| + CAP Java + | - Predicate + CDL | Description @@ -1488,11 +1494,9 @@ These comparison operators are supported: | ||
| EQ | = | -EQ - | -- Test if this value equals a given value. NULL values might be treated as unknown resulting in a three-valued logic as in SQL. + Test if this value equals a given value. NULL values might be treated as unknown resulting in a three-valued logic as in SQL. |
Select.from("bookshop.Books")
@@ -1502,11 +1506,9 @@ EQ
|
| NE | <> | -NE - | -- Test if this value is NOT equal to a given value. NULL values might be treated as unknown resulting in a three-valued logic as in SQL. + Test if this value is NOT equal to a given value. NULL values might be treated as unknown resulting in a three-valued logic as in SQL. |
Select.from("bookshop.Books")
@@ -1516,11 +1518,9 @@ NE
|
| IS | == | -IS - | -- Test if this value equals a given value. NULL values are treated as any other value. + Test if this value equals a given value. NULL values are treated as any other value (Boolean logic). | @@ -1532,11 +1532,9 @@ IS |
| IS NOT | != | -IS NOT - | -- Test if this value is NOT equal to a given value. NULL values are treated as any other value. + Test if this value is NOT equal to a given value. NULL values are treated as any other value (Boolean logic). | @@ -1548,9 +1546,7 @@ IS NOT |
| -GT - | +GT | > | Test if this value is greater than a given value. | @@ -1564,9 +1560,21 @@ GT|
| GE | >= | -LT + Test if this value is greater than or equal to a given value. | +
+
+Select.from("bookshop.Books")
+ .where(b -> b.get("stock")
+ .ge(5));
+
+ |
+|
| LT | < | Test if this value is less than a given value. | @@ -1580,9 +1588,7 @@ LT||
| -LE - | +LE | <= | Test if this value is less than or equal to a given value. | @@ -1596,7 +1602,7 @@ LE|
| + | BETWEEN |
diff --git a/java/working-with-cql/query-execution.md b/java/working-with-cql/query-execution.md
index 8f206e1764..af60b19a27 100644
--- a/java/working-with-cql/query-execution.md
+++ b/java/working-with-cql/query-execution.md
@@ -400,11 +400,17 @@ The `lock()` method has an optional parameter `timeout` that indicates the maxim
The parameter `mode` allows to specify whether an `EXCLUSIVE` or a `SHARED` lock should be set.
-## Runtime Views { #runtimeviews}
+## Runtime Views { #runtimeviews }
-The CDS compiler generates [SQL DDL](../../guides/databases?impl-variant=java#generating-sql-ddl) statements based on your CDS model, which include SQL views for all CDS [views and projections](../../cds/cdl#views-projections). This means adding or changing CDS views requires a deployment of the database schema changes.
+The CDS compiler generates [SQL DDL](../../guides/databases?impl-variant=java#generating-sql-ddl) statements from your CDS model, including SQL views for all CDS [views and projections](../../cds/cdl#views-projections). As a result, adding or modifying CDS views typically requires redeploying the database schema.
-To avoid schema updates due to adding or updating CDS views, annotate them with [@cds.persistence.skip](../../guides/databases#cds-persistence-skip). In this case the CDS compiler won't generate corresponding static database views. Instead, the CDS views are dynamically resolved by the CAP Java runtime.
+To avoid schema redeployments when you add or update CDS views, annotate them with [@cds.persistence.skip](../../guides/databases#cds-persistence-skip). This annotation tells the CDS compiler to skip generating database views for these entities. Instead, the CAP Java runtime dynamically resolves such views at runtime.
+
+::: warning Limitations
+Runtime views support only simple [CDS projections](../../cds/cdl#as-projection-on). They do not support complex views that use aggregations, unions, joins, or subqueries in the `FROM` clause. To read [draft-enabled](../fiori-drafts#reading-drafts) entities, set `cds.drafts.persistence` to `split`. [Calculated elements](../../cds/cdl#calculated-elements) are not yet supported in runtime views.
+:::
+
+For example, consider the following CDS model and query:
```cds
entity Books {
@@ -413,33 +419,47 @@ entity Books {
stock : Integer;
author : Association to one Authors;
}
-@cds.persistence.skip // [!code focus]
-entity BooksWithLowStock as projection on Books { // [!code focus]
- id, title, author.name as author // [!code focus]
-} where stock < 10; // [!code focus]
+@cds.persistence.skip
+entity BooksWithLowStock as projection on Books {
+ id, title, author.name as author
+} where stock < 10;
```
-
-At runtime, CAP Java resolves queries against runtime views until an entity is reached that isn't annotated with *@cds.persistence.skip*. For example, the CQL query
-
```sql
Select BooksWithLowStock where author = 'Kafka'
```
-is executed against SQL databases as
-
-```SQL
-SELECT B.ID, B.TITLE, A.NAME as "author" FROM BOOKS AS B
- LEFT OUTER JOIN AUTHORS AS A ON B.AUTHOR_ID = A.ID
-WHERE B.STOCK < 10 AND A.NAME = ?
-```
+CAP Java provides two modes for resolving runtime views:
-::: warning Limitations
-Runtime views are supported for simple [CDS projections](../../cds/cdl#as-projection-on). Expands of [filtered associations](../../cds/cdl#publish-associations-with-filter) are only supported since `3.7.0`. Constant values and expressions in runtime views are supported since `3.8.0`.
+**`cte` mode**: The runtime translates the view definition into a _Common Table Expression_ (CTE) and sends it with the query to the database.
-Complex views using aggregations or union/join/subqueries in `FROM` are not supported and for reading [draft-enabled](../fiori-drafts#reading-drafts) entities, `cds.drafts.persistence` needs to be set to `split`.
+```sql
+WITH BOOKSWITHLOWSTOCK_CTE AS (
+ SELECT B.ID,
+ B.TITLE,
+ A.NAME AS "AUTHOR"
+ FROM BOOKS B
+ LEFT OUTER JOIN AUTHOR A ON B.AUTHOR_ID = A.ID
+ WHERE B.STOCK < 10
+)
+SELECT ID, TITLE, AUTHOR AS "author"
+ FROM BOOKSWITHLOWSTOCK_CTE
+ WHERE A.NAME = ?
+```
+
+::: tip
+CAP Java 4.x uses `cte` mode by default. In 3.10, enable it with **cds.sql.runtimeView.mode: cte**.
:::
-### Using I/O Streams in Queries
+**`resolve` mode**: The runtime _resolves_ the view definition to the underlying persistence entities and executes the query directly against them.
+
+```sql
+SELECT B.ID, B.TITLE, A.NAME AS "author"
+ FROM BOOKS AS B
+ LEFT OUTER JOIN AUTHORS AS A ON B.AUTHOR_ID = A.ID
+ WHERE B.STOCK < 10 AND A.NAME = ?
+```
+
+## Using I/O Streams in Queries
As described in section [Predefined Types](../cds-data#predefined-types) it's possible to stream the data, if the element is annotated with `@Core.MediaType`. The following example demonstrates how to allocate the stream for element `coverImage`, pass it through the API to an underlying database and close the stream.
@@ -473,7 +493,7 @@ try (InputStream resource = getResource("IMAGE.PNG")) {
// Transaction finished
```
-### Using Native SQL
+## Using Native SQL
CAP Java doesn't have a dedicated API to execute native SQL Statements. However, when using Spring as application framework you can leverage Spring's features to execute native SQL statements. See [Execute SQL statements with Spring's JdbcTemplate](../cqn-services/persistence-services#jdbctemplate) for more details.
diff --git a/menu.md b/menu.md
index e373bfe69b..716409ff24 100644
--- a/menu.md
+++ b/menu.md
@@ -46,6 +46,7 @@
### [SAP Event Mesh](guides/messaging/event-mesh)
### [Apache Kafka](../guides/messaging/apache-kafka)
### [Events from S/4](guides/messaging/s4)
+ ### [Task Queues](guides/messaging/task-queues)
## [Protocols/APIs](advanced/publishing-apis/)
@@ -91,7 +92,7 @@
### [Deploy to Cloud Foundry](../guides/deployment/to-cf)
### [Deploy to Kyma/K8s](../guides/deployment/to-kyma)
- ### [Deploy to Shared DB](../guides/deployment/shared-db)
+ ### [Microservices with CAP](../guides/deployment/microservices)
### [Deploy with Confidence](../guides/deployment/dwc)
### [Deploy with CI/CD](../guides/deployment/cicd)
### [Custom Builds](../guides/deployment/custom-builds)
@@ -165,3 +166,4 @@
## [Open Resource Discovery](plugins/#ord-open-resource-discovery)
## [CAP Operator for K8s](plugins/#cap-operator-plugin)
## [SAP Cloud Appl. Event Hub](plugins/#event-hub)
+## [Advanced Event Mesh](plugins/#advanced-event-mesh)
diff --git a/node.js/_menu.md b/node.js/_menu.md
index eec9275676..609d8aae34 100644
--- a/node.js/_menu.md
+++ b/node.js/_menu.md
@@ -57,7 +57,7 @@
# [cds. utils](cds-utils)
# [cds. test()](cds-test)
# [cds. plugins](cds-plugins)
-# [cds. outboxed()](outbox)
+# [cds. queued()](queue)
# [TypeScript](typescript)
# [Fiori Support](fiori)
# [Best Practices](best-practices)
diff --git a/node.js/authentication.md b/node.js/authentication.md
index 8d76c59113..2394829ea9 100644
--- a/node.js/authentication.md
+++ b/node.js/authentication.md
@@ -369,6 +369,28 @@ npm add @sap/xssec
```
:::
+#### Token Validation
+
+For tokens issued by SAP Cloud Identity Service, `@sap/xssec` offers two additional validations: (1) token ownership via x5t thumbprint and (2) proof-of-possession.
+These validations are enabled by default for requests to the app's `cert` route (`.cert` segment in the domain).
+
+The default behavior can be overwritten using additional configuration as follows:
+
+```json
+"requires": {
+ "auth": {
+ "kind": "ias",
+ "config": { // passed to @sap/xssec as is
+ "validation": {
+ "x5t": { "enabled": false },
+ "proofToken": { "enabled": false }
+ }
+ }
+ }
+}
+```
+
+Please see [`@sap/xssec` documentation](https://www.npmjs.com/package/@sap/xssec) for more details.
### Custom Authentication { #custom }
@@ -461,7 +483,7 @@ If you don't know the API endpoint, have a look at section [Regions and API Endp
```json
"oauth2-configuration": {
"redirect-uris": [
- "http://localhost:5000/"
+ "http://localhost:5000/login/callback"
]
}
```
diff --git a/node.js/cds-compile.md b/node.js/cds-compile.md
index db25936742..b28c6f36d9 100644
--- a/node.js/cds-compile.md
+++ b/node.js/cds-compile.md
@@ -183,15 +183,6 @@ for (let [edm,{file,suffix}] of all)
console.log (file,suffix,edm)
```
-
-### .hdbcds() {.method .deprecated}
-
-Generates `hdbcds` output.
-
-Current SAP HANA Cloud versions do no longer support `.hdbcds`. The command is supported for backward compatibility with older versions of [SAP HANA Service for SAP BTP](https://help.sap.com/docs/HANA_SERVICE).
-
-Use [`cds.compile.to.hana`](#hana) instead.
-
### .hdbtable() {.method .deprecated}
Use [`cds.compile.to.hana`](#hana) instead.
diff --git a/node.js/cds-connect.md b/node.js/cds-connect.md
index e1c3062e94..26b1147e09 100644
--- a/node.js/cds-connect.md
+++ b/node.js/cds-connect.md
@@ -13,15 +13,72 @@ The latter include **database** services. In all cases use `cds.connect` to conn
[[toc]]
+## Connecting to Required Services { #cds-connect-to }
+
+
+
+### cds. connect.to () {.method}
+
+Use `cds.connect.to()` to connect to services configured in a project's `cds.requires` configuration.
+
+```js
+const ReviewsService = await cds.connect.to('ReviewsService')
+```
+
+The method returns a _Promise_ resolving to a _[Service](../cds/cdl#services)_ instance which acts as a client proxy to the service's API, allowing you to call its methods and access its data using common [`cds.Service`](core-services#consuming-services) methods, e.g.:
+
+```js
+let reviews = await ReviewsService.read ('Reviews')
+```
+
+
+**Arguments** are as follows:
+
+```ts:no-line-numbers
+async function cds.connect.to (
+ name? : string, // reference to an entry in `cds.requires` config
+ options? : {
+ kind : string // reference to a preset in `cds.requires.kinds` config
+ impl : string // module name of the implementation
+ }
+) : Promise | ||
cds.import
+ Programmatically use cds.import.
---
# CDS Import API
diff --git a/tools/assets/help/cds-compile.out.md b/tools/assets/help/cds-compile.out.md
index 2479f58c0c..8de919a7d4 100644
--- a/tools/assets/help/cds-compile.out.md
+++ b/tools/assets/help/cds-compile.out.md
@@ -18,7 +18,7 @@
- json, yml
- edm, edmx, edmx-v2, edmx-v4, edmx-w4, edmx-x4
- - sql, hdbcds, hdbtable, hana
+ - sql, hana, hdbtable
- cdl
- xsuaa
- openapi
diff --git a/tools/assets/help/cds-debug.out.md b/tools/assets/help/cds-debug.out.md
index 1b861de222..17a16a6bbb 100644
--- a/tools/assets/help/cds-debug.out.md
+++ b/tools/assets/help/cds-debug.out.md
@@ -25,6 +25,10 @@
the debug port (default: '9229' for Node.js, '8000' for Java)
+ -f | --force
+
+ if necessary, automatically enable ssh for the app and restart it
+
EXAMPLES
cds debug
cds debug bookshop-srv --port 8001
diff --git a/tools/assets/help/cds-help.out.md b/tools/assets/help/cds-help.out.md
index 215581b595..e3c65240ac 100644
--- a/tools/assets/help/cds-help.out.md
+++ b/tools/assets/help/cds-help.out.md
@@ -22,6 +22,8 @@
e | env inspect effective configuration
b | build prepare for deployment
d | deploy deploy to databases or cloud
+ | up build and deploy your application
+ | debug debug your application
| subscribe subscribe a tenant to a multitenant SaaS app
| unsubscribe unsubscribe a tenant from a multitenant SaaS app
l | login login to extensible multitenant SaaS app
diff --git a/tools/assets/help/cds-init.out.md b/tools/assets/help/cds-init.out.md
index 6d9a1db73f..64538bdefd 100644
--- a/tools/assets/help/cds-init.out.md
+++ b/tools/assets/help/cds-init.out.md
@@ -84,7 +84,7 @@
cds init bookshop --java
cds init bookshop --add hana
cds init bookshop --add multitenancy,mta
- cds init --java --java:mvn groupId=myGroup,artifactId=newId,package=my.company
+ cds init --java --java:mvn DgroupId=myGroup,DartifactId=newId,Dpackage=my.company
SEE ALSO
cds add - to augment your projects later on
diff --git a/tools/assets/help/cds-typer.out.md b/tools/assets/help/cds-typer.out.md
index 3c1014543e..594fcf474f 100644
--- a/tools/assets/help/cds-typer.out.md
+++ b/tools/assets/help/cds-typer.out.md
@@ -20,6 +20,13 @@ OPTIONS
This value must be set in your project configuration.
Passing it as parameter to the cds-typer CLI has no effect.
+ --cache: <none | blake2s256>
+ (default: none)
+
+ How to cache typer runs.
+ none: fully run cds-typer whenever it is called
+ blake2s256: only run if the blake2s256-hash of the model has changed. Hash is stored in a file between runs.
+
--help
This text.
@@ -74,6 +81,7 @@ OPTIONS
If set to true, properties in entities are
always generated as optional (a?: T).
+ Setting it to false makes properties non-optional instead (a: T).
--targetModuleType
--target_module_type: <esm | cjs | auto>
@@ -85,7 +93,7 @@ OPTIONS
--useEntitiesProxy
--use_entities_proxy: <true | false>
- (default: false)
+ (default: true)
If set to true the 'cds.entities' exports in the generated 'index.js'
files will be wrapped in 'Proxy' objects
diff --git a/tools/assets/help/cds-version-md.out.md b/tools/assets/help/cds-version-md.out.md
index 5c0fb3d392..5a0c0b19a8 100644
--- a/tools/assets/help/cds-version-md.out.md
+++ b/tools/assets/help/cds-version-md.out.md
@@ -5,16 +5,14 @@
| your-project | <Add your repository here> |
| ---------------------- | --------------------------------------- |
| @cap-js/asyncapi | 1.0.3 |
-| @cap-js/cds-types | 0.9.0 |
-| @cap-js/db-service | 1.19.1 |
-| @cap-js/openapi | 1.2.1 |
-| @cap-js/sqlite | 1.10.0 |
-| @sap/cds | 8.9.0 |
-| @sap/cds-compiler | 5.9.0 |
-| @sap/cds-dk (global) | 8.9.0 |
-| @sap/cds-fiori | 1.4.0 |
-| @sap/cds-foss | 5.0.1 |
-| @sap/cds-mtxs | 2.7.0 |
-| @sap/eslint-plugin-cds | 3.2.0 |
-| Node.js | v20.19.0 |
+| @cap-js/cds-types | 0.10.0 |
+| @cap-js/db-service | 2.0.1 |
+| @cap-js/openapi | 1.2.3 |
+| @cap-js/sqlite | 2.0.1 |
+| @sap/cds | 9.0.2 |
+| @sap/cds-compiler | 6.0.10 |
+| @sap/cds-dk (global) | 9.0.4 |
+| @sap/cds-fiori | 2.0.1 |
+| @sap/cds-mtxs | 3.0.1 |
+| Node.js | v20.19.2 |
diff --git a/tools/assets/help/cds-version.out.md b/tools/assets/help/cds-version.out.md
index 6887a503b7..816f6d0f36 100644
--- a/tools/assets/help/cds-version.out.md
+++ b/tools/assets/help/cds-version.out.md
@@ -3,17 +3,15 @@
> cds version
@cap-js/asyncapi: 1.0.3
-@cap-js/cds-types: 0.9.0
-@cap-js/db-service: 1.19.1
-@cap-js/openapi: 1.2.1
-@cap-js/sqlite: 1.10.0
-@sap/cds: 8.9.0
-@sap/cds-compiler: 5.9.0
-@sap/cds-dk (global): 8.9.0
-@sap/cds-fiori: 1.4.0
-@sap/cds-foss: 5.0.1
-@sap/cds-mtxs: 2.7.0
-@sap/eslint-plugin-cds: 3.2.0
-Node.js: v20.19.0
+@cap-js/cds-types: 0.10.0
+@cap-js/db-service: 2.0.1
+@cap-js/openapi: 1.2.3
+@cap-js/sqlite: 2.0.1
+@sap/cds: 9.0.2
+@sap/cds-compiler: 6.0.10
+@sap/cds-dk (global): 9.0.4
+@sap/cds-fiori: 2.0.1
+@sap/cds-mtxs: 3.0.1
+Node.js: v20.19.2
your-project: 1.0.0
diff --git a/tools/cds-cli.md b/tools/cds-cli.md
index 884bf050c5..d4e986bd99 100644
--- a/tools/cds-cli.md
+++ b/tools/cds-cli.md
@@ -127,6 +127,8 @@ The facets built into `@sap/cds-dk` provide you with a large set of standard fea
| `toggles` | - -Adding feature 'lint'... - -Successfully added features to your project. - - -Almost done -- -If a _package.json_, _pom.xml_, or _.cdsrc.json_ file is found, you have the choice to install the ESLint dependencies directly. Once confirmed, this will install ESLint and the CDS plugin, as well as add the corresponding configuration for the recommended rules into your project. +You may be asked to install ESLint as additional dependency in case it is not available in your project yet. Just follow the instructions on screen. ### CDS Lint CLI {#usage-lint-cli} @@ -72,7 +54,7 @@ It follows standard ESLint behaviour. If there are no lint errors, there is no o Make sure you have ESLint and our ESLint plugin installed via [`cds add lint`](#cds-add-lint). ::: -To turn on Lint checking in your VS Code Editor simply download the [ESLint extension](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) for _Visual Studio Code_. +To turn on lint checking in your VS Code Editor simply download the [ESLint extension](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) for _Visual Studio Code_. CDS Lint seamlessly integrates with it. For _SAP Business Application Studio_ this comes preinstalled. Now you can see lint reports also in your editor. You can see all rules [marked as **Editor default** here](./rules/). Any other (project-based) rules are not turned on by diff --git a/tools/cds-lint/rules/index.md b/tools/cds-lint/rules/index.md index d6066f1767..226b7e11e8 100644 --- a/tools/cds-lint/rules/index.md +++ b/tools/cds-lint/rules/index.md @@ -12,7 +12,7 @@ status: released # Rules Reference -Below you can find all rules of the \`@sap/eslint-plugin-cds\` ESLint plugin. +Below you can find all rules of the `@sap/eslint-plugin-cds` ESLint plugin. They are grouped by categories [Model Validation](#model-validation) and [Environment](#environment) to help you understand their purpose.you are missing 2 npm dependencies : - -(1) ESLint v>=8.0.0 -(2) ESLint plugin for CDS - - -Install dependencies now ? [y/n] y - -Successfully added features to your project. -