Skip to content

Commit

Permalink
Merge remote-tracking branch 'origin/main' into andre/cdl
Browse files Browse the repository at this point in the history
  • Loading branch information
@bugwelle
bugwelle committed Jan 31, 2025
2 parents 4dbbe41 + a7f9b45 commit 7f36479
Show file tree
Hide file tree
Showing 4 changed files with 53 additions and 43 deletions.
2 changes: 1 addition & 1 deletion .vitepress/config.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -101,7 +101,7 @@ config.rewrites = rewrites
// Add custom capire info to the theme config
config.themeConfig.capire = {
versions: {
java_services: '3.7.0',
java_services: '3.7.1',
java_cds4j: '3.7.0'
},
gotoLinks: [],
Expand Down
85 changes: 44 additions & 41 deletions guides/multitenancy/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,7 @@ cds add multitenancy --for production
```jsonc
{
"dependencies": {
"@sap/cds-mtxs": "^1.17"
"@sap/cds-mtxs": "^2"
},
}
```
Expand All @@ -91,14 +91,14 @@ cds add multitenancy --for production
{
"name": "bookshop-mtx",
"dependencies": {
"@sap/cds": "^7",
"@sap/cds-hana": "^2",
"@sap/cds-mtxs": "^1.17",
"@cap-js/hana": "^2",
"@sap/cds": "^8",
"@sap/cds-mtxs": "^2",
"@sap/xssec": "^4",
"express": "^4"
},
"devDependencies": {
"@cap-js/sqlite": ">=1"
"@cap-js/sqlite": "^1"
},
"scripts": {
"start": "cds-serve"
Expand Down Expand Up @@ -163,8 +163,8 @@ cds add multitenancy --for production
{
"name": "bookshop-mtx",
"dependencies": {
"@sap/cds": ">=7",
"@sap/cds-hana": "^2",
"@cap-js/hana": "^2",
"@sap/cds": "^8",
"@sap/cds-mtxs": "^2",
"@sap/xssec": "^4",
"express": "^4"
Expand Down Expand Up @@ -878,7 +878,7 @@ You should now see the route mapped to your application.

<div class="impl java">

See [Java Guide](../../java/multitenancy#database-update)
[Learn best practices for schema updates in the Java Guide](../../java/multitenancy#database-update){.learn-more style="margin-top: 20px"}

</div>

Expand Down Expand Up @@ -1115,33 +1115,14 @@ cds.on('served', () => {
```
<!-- TODO: Learn more about the available events to plug in to{.learn-more}-->

## Appendix

### Behind the Scenes { #behind-the-scenes}

With adding the MTX services, your project configuration is adapted at all relevant places.

Configuration and dependencies are added to your _package.json_ and an _xs-security.json_ containing MTX-specific scopes and roles is created. {.node}

Configuration and dependencies are added to your _.cdsrc.json_ and an _xs-security.json_ containing MTX-specific scopes and roles is created. {.java}
## Configuring the Java Service { #binding-it-together .java}

For the MTA deployment service dependencies are added to the _mta.yaml_ file. Each SaaS application will have bindings to at least three SAP BTP service instances.

| Service | Description |
| ------------------------------------------------------------ | ------------------------------------------------------------ |
| [Service Manager](https://help.sap.com/docs/SERVICEMANAGEMENT/09cc82baadc542a688176dce601398de/4e19b11211fe4ca2a266d3fdd4a72188.html) (`service-manager`) | CAP uses this service for creating a new SAP HANA Deployment Infrastructure (HDI) container for each tenant and for retrieving tenant-specific database connections. |
| [SaaS Provisioning Service](https://help.sap.com/products/BTP/65de2977205c403bbc107264b8eccf4b/3971151ba22e4faa9b245943feecea54.html) (`saas-registry`) | To make a SaaS application available for subscription to SaaS consumer tenants, the application provider must register the application in the SAP BTP Cloud Foundry environment through the SaaS Provisioning Service. |
| [User Account and Authentication Service](https://help.sap.com/docs/CP_AUTHORIZ_TRUST_MNG) (`xsuaa`) | Binding information contains the OAuth client ID and client credentials. The XSUAA service can be used to validate the JSON Web Token (JWT) from requests and to retrieve the tenant context from the JWT.|

> If you're interested, use version control to spot the exact changes. {.node}

#### Configuring the Java Service { #binding-it-together .java}

This how the services have been configured for the `srv` module in the _mta.yaml_ / _values.yaml_ file:
`cds add multitenancy` added configuration similar to this:

::: code-group

```yaml [mta.yaml]
```yaml [mta.yaml (Cloud Foundry)]
modules:
- name: bookshop-srv
type: java
Expand All @@ -1165,7 +1146,7 @@ modules:
- name: bookshop-registry
```

```yaml [values.yaml]
```yaml [values.yaml (Kyma)]
...
srv:
bindings:
Expand All @@ -1176,23 +1157,24 @@ srv:
SPRING_PROFILES_ACTIVE: cloud
CDS_MULTITENANCY_APPUI_TENANTSEPARATOR: "-"
CDS_MULTITENANCY_APPUI_URL: https://{{ .Release.Name }}-srv-{{ .Release.Namespace }}.{{ .Values.global.domain }}
CDS_MULTITENANCY_SIDECAR_URL: https://{{ .Release.Name }}-sidecar-{{ .Release.Namespace }}.{{ .Values.global.domain }} #cds.noOverwrite
CDS_MULTITENANCY_SIDECAR_URL: https://{{ .Release.Name }}-sidecar-{{ .Release.Namespace }}.{{ .Values.global.domain }}
...
```
:::

> These environment variables in `values.yaml` may be overwritten by `cds add` commands. If you want to provide your own value and don't want `cds add` commands to overwrite the value of any particular variable, add `#cds.noOverwrite` comment next to that value (as shown in above example).

- `CDS_MULTITENANCY_SIDECAR_URL` sets the application property <Config java>cds.multitenancy.sidecar.url</Config>. This URL is required by the CAP Java runtime to connect to the MTX Sidecar application and is derived from the property `url` of the mtx-sidecar module.
- Similarly, `CDS_MULTITENANCY_APPUI_URL` configures the URL that is shown in the SAP BTP Cockpit. Usually it points to the app providing the UI, which is the module `app` in this example.
- `CDS_MULTITENANCY_SIDECAR_URL` sets the application property <Config java>cds.multitenancy.sidecar.url</Config>. This URL is required by the CAP Java runtime to connect to the MTX Sidecar application and is derived from the property `mtx-url` of the mtx-sidecar module.
- `CDS_MULTITENANCY_APPUI_URL` sets the entry point URL that is shown in the SAP BTP Cockpit.
- `CDS_MULTITENANCY_APPUI_TENANTSEPARATOR` is the separator in generated tenant-specific URL.

The tenant application requests are separated by the tenant specific app URLs. The tenant specific URL is made up of:
The tenant application requests are separated by the tenant-specific app URL:

```http
https://<subaccount subdomain><CDS_MULTITENANCY_APPUI_TENANTSEPARATOR><CDS_MULTITENANCY_APPUI_URL>
```

You can also define the environment variable `CDS_MULTITENANCY_APPUI_TENANTSEPARATOR` in the extension descriptor. The extension descriptor file could look like this:
::: tip Use MTA extensions for landscape-specific configuration

You can define the environment variable `CDS_MULTITENANCY_APPUI_TENANTSEPARATOR` in an MTA extension descriptor:

::: code-group

Expand All @@ -1209,9 +1191,10 @@ modules:
TENANT_HOST_PATTERN: ^(.*)-${default-uri}
```

:::
[Learn more about _Defining MTA Extension Descriptors_](https://help.sap.com/docs/btp/sap-business-technology-platform/defining-mta-extension-descriptors?q=The%20MTA%20Deployment%20Extension%20Descriptor){.learn-more style="margin-top: 10px;"}

[Learn more about _Defining MTA Extension Descriptors_](https://help.sap.com/docs/btp/sap-business-technology-platform/defining-mta-extension-descriptors?q=The%20MTA%20Deployment%20Extension%20Descriptor){.learn-more}

:::

#### Option: Provisioning Only { #provisioning-only-mtx-sidecar .java}

Expand Down Expand Up @@ -1255,6 +1238,10 @@ You can also selectively use these properties to enable only extensibility or fe

:::

<div id="subscriptionmanager" />

## Appendix

### About SaaS Applications

Software-as-a-Service (SaaS) solutions are deployed once by a SaaS provider, and then used by multiple SaaS customers subscribing to the software.
Expand Down Expand Up @@ -1296,7 +1283,23 @@ The main task for the MTX sidecar is to serve `subscribe` and `upgrade` requests

The CAP services runtime requests models from the sidecar only when you apply tenant-specific extensions. For Node.js projects, you have the option to run the MTX services embedded in the main app, instead of in a sidecar.

<div id="subscriptionmanager" />
<!-- Who cares? Also outdated with IAS -> busywork keeping that in sync -->
### Behind the Scenes { #behind-the-scenes}

With adding the MTX services, your project configuration is adapted at all relevant places.

Configuration and dependencies are added to your _package.json_ and an _xs-security.json_ containing MTX-specific scopes and roles is created. {.node}

Configuration and dependencies are added to your _.cdsrc.json_ and an _xs-security.json_ containing MTX-specific scopes and roles is created. {.java}

For the MTA deployment service dependencies are added to the _mta.yaml_ file. Each SaaS application will have bindings to at least three SAP BTP service instances.

| Service | Description |
| ------------------------------------------------------------ | ------------------------------------------------------------ |
| [Service Manager](https://help.sap.com/docs/SERVICEMANAGEMENT/09cc82baadc542a688176dce601398de/4e19b11211fe4ca2a266d3fdd4a72188.html) (`service-manager`) | CAP uses this service for creating a new SAP HANA Deployment Infrastructure (HDI) container for each tenant and for retrieving tenant-specific database connections. |
| [SaaS Provisioning Service](https://help.sap.com/products/BTP/65de2977205c403bbc107264b8eccf4b/3971151ba22e4faa9b245943feecea54.html) (`saas-registry`) | To make a SaaS application available for subscription to SaaS consumer tenants, the application provider must register the application in the SAP BTP Cloud Foundry environment through the SaaS Provisioning Service. |
| [User Account and Authentication Service](https://help.sap.com/docs/CP_AUTHORIZ_TRUST_MNG) (`xsuaa`) | Binding information contains the OAuth client ID and client credentials. The XSUAA service can be used to validate the JSON Web Token (JWT) from requests and to retrieve the tenant context from the JWT.|


<!--

Expand Down
7 changes: 7 additions & 0 deletions java/event-handlers/indicating-errors.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -122,6 +122,13 @@ messages.warn("my.message.key", paramNumber);
throw new ServiceException(ErrorStatuses.BAD_REQUEST, "my.message.key", paramNumber, originalException);
```

### Translations for Validation Error Messages { #ootb-translated-messages }

CAP Java provides out-of-the-box translation for error messages that originate from input validation annotations such as `@assert...` or `@mandatory` and security annotations `@requires` and `@restrict`.

The error messages are optimized for UI scenarios and avoid any technical references to entity names or element names. Message targets are used where appropriate to allow the UI to show the error message next to the affected UI element.
You can enable these translated error messages by setting [<Config java>cds.errors.defaultTranslations.enabled: true</Config>](../developing-applications/properties#cds-errors-defaultTranslations-enabled).

### Exporting the Default Messages

As of CAP Java 1.10.0, you can extract the available default messages as a resource bundle file for further processing (for example, translation). Therefore, the delivery artifact [cds-services-utils](https://search.maven.org/artifact/com.sap.cds/cds-services-utils) contains a resource bundle `cds-messages-template.properties` with all available error codes and default messages. Application developers can use this template to customize error messages thrown by the CAP Java SDK in the application.
Expand Down
2 changes: 1 addition & 1 deletion java/working-with-cql/query-api.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -774,7 +774,7 @@ There are few notable examples of such restrictions:

* You cannot use the `lock()` together with a `distinct()` or a `groupBy()`.
* You cannot use the `lock()` in a statement with the subquery as a source.
* Localized entities can be locked only if your query is executed without a locale, as described in the chapter [Modifying Request Context](../event-handlers/request-contexts#modifying-requestcontext).
* Localized entities can be locked only if your query is run without a locale, as described in the chapter: [Modifying Request Context](../event-handlers/request-contexts#modifying-requestcontext). Alternatively, they can be locked by removing the localized element from the select list (columns).
* Entities that contain "on-read" calculated elements can't be locked when the statement references them in the select list or a filter.

As a general rule, prefer the statements that select primary keys with a simple condition, such as `byId` or `matching`, to select the target entity set that is locked.
Expand Down

0 comments on commit 7f36479

Please sign in to comment.