From 4a5d3d80cf45650c10d441fb8b0a00db0b015cb4 Mon Sep 17 00:00:00 2001 From: Marc Becker Date: Thu, 18 Jul 2024 14:45:41 +0200 Subject: [PATCH 1/5] Minor improvements of CAP Java 3.0 migration guide --- java/migration.md | 54 +++++++++++++++++++++++------------------------ 1 file changed, 27 insertions(+), 27 deletions(-) diff --git a/java/migration.md b/java/migration.md index 43f8f2e7b..3da58eda5 100644 --- a/java/migration.md +++ b/java/migration.md @@ -31,9 +31,9 @@ CAP Java 3.0 increased some minimum required versions: | Dependency | Minimum Version | | --- | --- | +| Cloud SDK | 5.9.0 | | @sap/cds-dk | ^7 | | Maven | 3.6.3 | -| Cloud SDK | 5.9.0 | CAP Java 3.0 no longer supports @sap/cds-dk ^6. @@ -46,6 +46,19 @@ If you are using the root path `/` for a readiness or liveness probe in Kyma you [Learn more about the Production Profile.](developing-applications/configuring#production-profile){.learn-more} +### Removed MTX Classic Support + +Support for classic MTX (@sap/cds-mtx) has been removed. Using streamlined MTX (@sap/cds-mtxs) is mandatory for multitenancy. +If you're still using MTX Classic refer to the [multitenancy migration guide](../guides/multitenancy/old-mtx-migration). + +In addition, the deprecated `MtSubscriptionService` API, has been removed. It has now been superseeded by the `DeploymentService` API. +As part of this change the compatibility mode for the `MtSubscriptionService` API has been removed. Besides the removal of the Java APIs this includes the following behavioural changes: + +- During unsubscribe, the tenant's content (like HDI container) is now deleted by default when using the new `DeploymentService` API. +- The HTTP-based tenant upgrade APIs provided by the CAP Java app have been removed, use the [`Deploy` main method](/java/multitenancy#deploy-main-method) instead. This includes the following endpoints: + - `/mt/v1.0/subscriptions/deploy/**` (GET & POST) + - `/messaging/v1.0/em/` (PUT) + ### Removed feature `cds-feature-xsuaa` The feature `cds-feature-xsuaa` has been removed. Support for XSUAA and IAS has been unified under the umbrella of `cds-feature-identity`. @@ -59,18 +72,13 @@ If you have customized the security configuration, you need to adapt it to the n [Learn more about the security configuration.](./security#xsuaa-ias){.learn-more} [Learn more about migration to SAP´s `spring-security` library.](https://github.com/SAP/cloud-security-services-integration-library/blob/main/spring-security/Migration_SpringXsuaaProjects.md) -### Removed MTX Classic Support +### Proof-Of-Possession enforced for IAS-based authentication -Support for classic MTX (@sap/cds-mtx) has been removed. Using streamlined MTX (@sap/cds-mtxs) is mandatory for multitenancy. -If you're still using MTX Classic refer to the [multitenancy migration guide](../guides/multitenancy/old-mtx-migration). +In IAS scenarios, the [Proof-Of-Possession](https://github.com/SAP/cloud-security-services-integration-library/tree/main/java-security#proofofpossession-validation) is now enforced by default for incoming requests for versions starting from `3.5.1` of the [SAP BTP Spring Security Client](https://github.com/SAP/cloud-security-services-integration-library/tree/main/spring-security). -In addition, the deprecated `MtSubscriptionService` API, has been removed. It has now been superseeded by the `DeploymentService` API. -As part of this change the compatibility mode for the `MtSubscriptionService` API has been removed. Besides the removal of the Java APIs this includes the following behavioural changes: +Because of this, applications calling a CAP Java application will need to send a valid client certificate in addition to the JWT token. In particular, applications using an Approuter have to set `forwardAuthCertificates: true` on the Approuter destination pointing to your CAP backend. -- During unsubscribe, the tenant's content (like HDI container) is now deleted by default when using the new `DeploymentService` API. -- The HTTP-based tenant upgrade APIs provided by the CAP Java app have been removed. This includes the following endpoints: - - `/mt/v1.0/subscriptions/deploy/**` (GET & POST) - - `/messaging/v1.0/em/` (PUT) +[Learn more about Proof-Of-Possession.](./security.md#proof-of-possession){.learn-more} ### Lazy Localization by default @@ -122,14 +130,6 @@ Some property defaults have been adjusted: | --- | --- | | `cds.outbox.persistent.enabled` | When set to `false`, all persistent outboxes are disabled regardless of their specific configuration. | -### Deprecated Session Context Variables - -| Old Variable | Replacement | -| --- | --- | -| `$user.tenant` | `$tenant` | -| `$at.from` | `$valid.from` | -| `$at.to` | `$valid.to` | - ### Removed Properties The following table gives an overview about the removed properties: @@ -162,6 +162,14 @@ The following table gives an overview about the removed properties: | `cds.sql.supportedLocales` | | All locales are supported by default for localized entities, as session variables can now be leveraged on all databases. | | `cds.xsuaa.authConfig.enabled` | `cds.security.authentication.authConfig.enabled` | | +### Deprecated Session Context Variables + +| Old Variable | Replacement | +| --- | --- | +| `$user.tenant` | `$tenant` | +| `$at.from` | `$valid.from` | +| `$at.to` | `$valid.to` | + ### Removed Java APIs - Removed deprecated classes: @@ -197,17 +205,9 @@ The following table gives an overview about the removed properties: The goal `addSample` from the `cds-maven-plugin` has been removed. Use the new goal `add` with the property `-Dfeature=TINY_SAMPLE` instead. -### Proof-Of-Possession enforced for IAS-based authentication - -In IAS scenarios, the [Proof-Of-Possession](https://github.com/SAP/cloud-security-services-integration-library/tree/main/java-security#proofofpossession-validation) is now enforced by default for incoming requests for versions starting from `3.5.1` of the [SAP BTP Spring Security Client](https://github.com/SAP/cloud-security-services-integration-library/tree/main/spring-security). - -Because of this, applications calling a CAP Java application will need to send a valid client certificate in addition to the JWT token. In particular, applications using an Approuter have to set `forwardAuthCertificates: true` on the Approuter destination pointing to your CAP backend. - -[Learn more about Proof-Of-Possession.](./security.md#proof-of-possession){.learn-more} - ## Cloud SDK 4 to 5 { #cloudsdk5 } -CAP Java `2.6.0` and higher is compatible with Cloud SDK in version 4 and 5. For reasons of backward compatibility, CAP Java assumes Cloud SDK 4 as the default. However, we highly recommend that you use at least version `5.7.0` of Cloud SDK. If you relied on the Cloud SDK integration package (`cds-integration-cloud-sdk`), you won't need to adapt any code to upgrade your CAP Java application to Cloud SDK 5. In these cases, it's sufficient to add the following maven dependency to your CAP Java application: +CAP Java `2.6.0` and higher is compatible with Cloud SDK in version 4 and 5. For reasons of backward compatibility, CAP Java assumes Cloud SDK 4 as the default. However, we highly recommend that you use at least version `5.9.0` of Cloud SDK. If you relied on the Cloud SDK integration package (`cds-integration-cloud-sdk`), you won't need to adapt any code to upgrade your CAP Java application to Cloud SDK 5. In these cases, it's sufficient to add the following maven dependency to your CAP Java application: ```xml From 25c41ea3b7a720b297163b6138935a05d08b38cd Mon Sep 17 00:00:00 2001 From: Marc Becker Date: Thu, 25 Jul 2024 14:11:19 +0200 Subject: [PATCH 2/5] Fix property names --- java/migration.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/java/migration.md b/java/migration.md index 3da58eda5..201ca3fb6 100644 --- a/java/migration.md +++ b/java/migration.md @@ -141,7 +141,9 @@ The following table gives an overview about the removed properties: | `cds.dataSource.csvInitializationMode` | `cds.dataSource.csv.initializationMode` | | | `cds.dataSource.csvPaths` | `cds.dataSource.csv.paths` | | | `cds.dataSource.csvSingleChangeset` | `cds.dataSource.csv.singleChangeset` | | -| `cds.identity.authConfig.enabled` | `cds.security.authentication.authConfig.enabled` | | +| `cds.security.identity.authConfig.enabled` | `cds.security.authentication.authConfig.enabled` | | +| `cds.security.xsuaa.authConfig.enabled` | `cds.security.authentication.authConfig.enabled` | | +| `cds.security.mock.users..unrestricted` | | Special handling of unrestricted attributes has been removed, in favor of [explicit modelling](../guides/security/authorization#unrestricted-xsuaa-attributes). | | `cds.messaging.services..outbox.persistent.enabled` | `cds.messaging.services..outbox.name` | | | `cds.multiTenancy.compatibility.enabled` | | MtSubscriptionService API [has been removed](#removed-mtx-classic-support) and compatibility mode is no longer available. | | `cds.multiTenancy.healthCheck.intervalMillis` | `cds.multiTenancy.healthCheck.interval` | | @@ -152,15 +154,13 @@ The following table gives an overview about the removed properties: | `cds.outbox.persistent.maxAttempts` | `cds.outbox.services..maxAttempts` | | | `cds.outbox.persistent.storeLastError` | `cds.outbox.services..storeLastError` | | | `cds.outbox.persistent.ordered` | `cds.outbox.services..ordered` | | -| `cds.remote..destination.headers` | `cds.remote.services..http.headers` | | -| `cds.remote..destination.queries` | `cds.remote.services..http.queries` | | -| `cds.remote..destination.service` | `cds.remote.services..http.service` | | -| `cds.remote..destination.suffix` | `cds.remote.services..http.suffix` | | -| `cds.remote..destination.type` | `cds.remote.services..type` | | -| `cds.security.mock.users..unrestricted` | | Special handling of unrestricted attributes has been removed, in favor of [explicit modelling](../guides/security/authorization#unrestricted-xsuaa-attributes). | +| `cds.remote.services..destination.headers` | `cds.remote.services..http.headers` | | +| `cds.remote.services..destination.queries` | `cds.remote.services..http.queries` | | +| `cds.remote.services..destination.service` | `cds.remote.services..http.service` | | +| `cds.remote.services..destination.suffix` | `cds.remote.services..http.suffix` | | +| `cds.remote.services..destination.type` | `cds.remote.services..type` | | | `cds.sql.search.useLocalizedView` | `cds.sql.search.model` | | | `cds.sql.supportedLocales` | | All locales are supported by default for localized entities, as session variables can now be leveraged on all databases. | -| `cds.xsuaa.authConfig.enabled` | `cds.security.authentication.authConfig.enabled` | | ### Deprecated Session Context Variables From c5265a02d51aad7142adb6d5b19c70ef9466da9e Mon Sep 17 00:00:00 2001 From: Marc Becker Date: Thu, 25 Jul 2024 15:46:09 +0200 Subject: [PATCH 3/5] Improve POJO generation examples --- java/migration.md | 52 ++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 51 insertions(+), 1 deletion(-) diff --git a/java/migration.md b/java/migration.md index 201ca3fb6..2669b691e 100644 --- a/java/migration.md +++ b/java/migration.md @@ -108,10 +108,60 @@ Some parameter defaults of the goal `generate` have been adjusted: | Parameter | Old Value | New Value | Explanation | | --- | --- | --- | --- | | `sharedInterfaces` | `false` | `true` | Interfaces for global arrayed types with inline anonymous type are now generated exactly once. `sharedInterfaces` ensures such types are not generated as inline interfaces again, if used in events, actions or functions. | -| `uniqueEventContexts` | `false` | `true` | Determines whether the event context interfaces should be unique for bound actions and functions. | +| `uniqueEventContexts` | `false` | `true` | Determines whether the event context interfaces should be unique for bound actions and functions, by prefixing the interfaces with the entity name. | Both these changes result in the generation of incompatible POJOs. To get the former POJOs, the new defaults can be overwritten by setting the parameters to the old values. +Consider the following example: + +```cds +service MyService { + entity MyEntity { + key ID: UUID + } actions { + // bound action + action doSomething(values: MyArray); + } +} + +// global arrayed type +type MyArray: many { + value: String; +} +``` + +With the new defaults the generated interface for the `doSomething` action looks like his: + +```java +// uniqueEventContexts: true => +// interface is prefixed with entity name "MyEntity" +public interface MyEntityDoSomethingContext extends EventContext { + + // sharedInterfaces: true => global MyArray type is used + Collection getValues(); + void setValues(Collection values); + +} +``` + +Formerly the generated interface looked like this: + +```java +// uniqueEventContexts: false => +// interface is not prefixed with entity name +public interface DoSomethingContext extends EventContext { + + // sharedInterfaces: false => global MyArray type is not used, + // instead an additional interface Values is generated inline + Collection getValues(); + void setValues(Collection values); + + interface Values extends CdsData { + // ... + } +} +``` + ### Adjusted Property Defaults Some property defaults have been adjusted: From f03fec4038fd9a4594b1dd193b4d970954a3f199 Mon Sep 17 00:00:00 2001 From: Marc Becker Date: Thu, 25 Jul 2024 16:18:23 +0200 Subject: [PATCH 4/5] Make tables smaller --- java/migration.md | 56 +++++++++++++++++++++++------------------------ 1 file changed, 28 insertions(+), 28 deletions(-) diff --git a/java/migration.md b/java/migration.md index 2669b691e..c1df0ea88 100644 --- a/java/migration.md +++ b/java/migration.md @@ -171,7 +171,7 @@ Some property defaults have been adjusted: | `cds.remote.services..http.csrf.enabled` | `true` | `false` | Most APIs don't require CSRF tokens. | | `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.auditLog.personalData.`
`throwOnMissingDataSubject` | `false` | `true` | Raise errors for incomplete personal data annotations by default. | | `cds.messaging.services..structured` | `false` | `true` | [Enhanced message representation](./messaging.md#enhanced-messages-representation) is now enabled by default. | ### Adjusted Property Behavior @@ -184,33 +184,33 @@ Some property defaults have been adjusted: The following table gives an overview about the removed properties: -| Removed Property | Replacement | Explanation | -| --- | --- | --- | -| `cds.auditlog.outbox.persistent.enabled` | `cds.auditlog.outbox.name` | | -| `cds.dataSource.csvFileSuffix` | `cds.dataSource.csv.fileSuffix` | | -| `cds.dataSource.csvInitializationMode` | `cds.dataSource.csv.initializationMode` | | -| `cds.dataSource.csvPaths` | `cds.dataSource.csv.paths` | | -| `cds.dataSource.csvSingleChangeset` | `cds.dataSource.csv.singleChangeset` | | -| `cds.security.identity.authConfig.enabled` | `cds.security.authentication.authConfig.enabled` | | -| `cds.security.xsuaa.authConfig.enabled` | `cds.security.authentication.authConfig.enabled` | | -| `cds.security.mock.users..unrestricted` | | Special handling of unrestricted attributes has been removed, in favor of [explicit modelling](../guides/security/authorization#unrestricted-xsuaa-attributes). | -| `cds.messaging.services..outbox.persistent.enabled` | `cds.messaging.services..outbox.name` | | -| `cds.multiTenancy.compatibility.enabled` | | MtSubscriptionService API [has been removed](#removed-mtx-classic-support) and compatibility mode is no longer available. | -| `cds.multiTenancy.healthCheck.intervalMillis` | `cds.multiTenancy.healthCheck.interval` | | -| `cds.multiTenancy.mtxs.enabled` | | MTXS is enabled [by default](#removed-mtx-classic-support). | -| `cds.multiTenancy.security.deploymentScope` | | HTTP-based tenant upgrade endpoints [have been removed](#removed-mtx-classic-support). | -| `cds.odataV4.apply.inCqn.enabled` | `cds.odataV4.apply.transformations.enabled` | | -| `cds.odataV4.serializer.enabled` | | The legacy serializer has been removed. | -| `cds.outbox.persistent.maxAttempts` | `cds.outbox.services..maxAttempts` | | -| `cds.outbox.persistent.storeLastError` | `cds.outbox.services..storeLastError` | | -| `cds.outbox.persistent.ordered` | `cds.outbox.services..ordered` | | -| `cds.remote.services..destination.headers` | `cds.remote.services..http.headers` | | -| `cds.remote.services..destination.queries` | `cds.remote.services..http.queries` | | -| `cds.remote.services..destination.service` | `cds.remote.services..http.service` | | -| `cds.remote.services..destination.suffix` | `cds.remote.services..http.suffix` | | -| `cds.remote.services..destination.type` | `cds.remote.services..type` | | -| `cds.sql.search.useLocalizedView` | `cds.sql.search.model` | | -| `cds.sql.supportedLocales` | | All locales are supported by default for localized entities, as session variables can now be leveraged on all databases. | +| Removed Property | Replacement / Explanation | +| --- | --- | +| `cds.auditlog.outbox.persistent.enabled` | `cds.auditlog.outbox.name` | +| `cds.dataSource.csvFileSuffix` | `cds.dataSource.csv.fileSuffix` | +| `cds.dataSource.csvInitializationMode` | `cds.dataSource.csv.initializationMode` | +| `cds.dataSource.csvPaths` | `cds.dataSource.csv.paths` | +| `cds.dataSource.csvSingleChangeset` | `cds.dataSource.csv.singleChangeset` | +| `cds.security.identity.authConfig.enabled` | `cds.security.authentication.`
`authConfig.enabled` | +| `cds.security.xsuaa.authConfig.enabled` | `cds.security.authentication.`
`authConfig.enabled` | +| `cds.security.mock.users..unrestricted` | Special handling of unrestricted attributes has been removed, in favor of [explicit modelling](../guides/security/authorization#unrestricted-xsuaa-attributes). | +| `cds.messaging.services..outbox.persistent.enabled` | `cds.messaging.services..outbox.name` | +| `cds.multiTenancy.compatibility.enabled` | MtSubscriptionService API [has been removed](#removed-mtx-classic-support) and compatibility mode is no longer available. | +| `cds.multiTenancy.healthCheck.intervalMillis` | `cds.multiTenancy.healthCheck.interval` | +| `cds.multiTenancy.mtxs.enabled` | MTXS is enabled [by default](#removed-mtx-classic-support). | +| `cds.multiTenancy.security.deploymentScope` | HTTP-based tenant upgrade endpoints [have been removed](#removed-mtx-classic-support). | +| `cds.odataV4.apply.inCqn.enabled` | `cds.odataV4.apply.transformations.enabled` | +| `cds.odataV4.serializer.enabled` | The legacy serializer has been removed. | +| `cds.outbox.persistent.maxAttempts` | `cds.outbox.services..maxAttempts` | +| `cds.outbox.persistent.storeLastError` | `cds.outbox.services..storeLastError` | +| `cds.outbox.persistent.ordered` | `cds.outbox.services..ordered` | +| `cds.remote.services..destination.headers` | `cds.remote.services..http.headers` | +| `cds.remote.services..destination.queries` | `cds.remote.services..http.queries` | +| `cds.remote.services..destination.service` | `cds.remote.services..http.service` | +| `cds.remote.services..destination.suffix` | `cds.remote.services..http.suffix` | +| `cds.remote.services..destination.type` | `cds.remote.services..type` | +| `cds.sql.search.useLocalizedView` | `cds.sql.search.model` | +| `cds.sql.supportedLocales` | All locales are supported by default for localized entities, as session variables can now be leveraged on all databases. | ### Deprecated Session Context Variables From 7c9870f46171ad7f92f74413dde176c698e9fd9b Mon Sep 17 00:00:00 2001 From: Mahati Shankar <93712176+smahati@users.noreply.github.com> Date: Fri, 26 Jul 2024 13:36:28 +0200 Subject: [PATCH 5/5] Update java/migration.md --- java/migration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/java/migration.md b/java/migration.md index c1df0ea88..f822069af 100644 --- a/java/migration.md +++ b/java/migration.md @@ -130,7 +130,7 @@ type MyArray: many { } ``` -With the new defaults the generated interface for the `doSomething` action looks like his: +With the new defaults the generated interface for the `doSomething` action looks like this: ```java // uniqueEventContexts: true =>