Migration Guide for CAP Java 3.0 (#892)

* Migration Guide for CAP Java 3.0 (#890) * Changes in cds-maven-plugin (#893) * Update migration.md * Update java/migration.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * Fix typo * Update migration.md * Fixed wrong property order (#935) * [CAP Java 3.0] Explain removal of classic MTX in migration guide (#942) * Added table for removed properties (#936) * Update migration.md * Update migration.md * Update migration.md * Update java/migration.md Co-authored-by: Marc Becker <[email protected]> * Update java/migration.md Co-authored-by: Marc Becker <[email protected]> * Update migration.md * Update java/migration.md * Update java/migration.md --------- Co-authored-by: Marc Becker <[email protected]> * Update migration.md * Update java/migration.md * describing new semantics of `cds.outbox.persistent.enabled` (#987) * Describe changes of goal generate (#993) * Update migration.md * Update migration.md * cds.sql.hana.optimizationMode: hex * Java 3 Migration: CqnSearchTermPredicate (#1015) * [3.0] Removal of `cds-feature-xsuaa` (#918) Co-authored-by: Marc Becker <[email protected]> * Add removed property * cqn(String) methods * $user.tenant * 3.0: Lazy localization by default (#1023) * $user.tenant deprecation * document cds.auditLog.personalData.throwOnMissingDataSubject change * Update migration.md * CqnSearchPredicate * Session Context Variables * Prohibit star-expand and inline-all (#1039) * Apply suggestions from code review Co-authored-by: Matthias Schur <[email protected]> * Remove warning * Update minimum versions in general docs * [3.0] IAS support in Remote Services and IAS migration guide (#1047) * ias scenarios * ias scenarios * ias scenarios * Apply suggestions from code review Co-authored-by: Marc Becker <[email protected]> * extract details to security.md * bullet point list * Update java/cqn-services/remote-services.md Co-authored-by: Marc Becker <[email protected]> * Update java/cqn-services/remote-services.md * Update java/cqn-services/remote-services.md * Update java/migration.md * Update java/security.md * Update java/security.md * Update java/security.md * Update java/security.md * Update java/security.md * fix syntax * added code block * fix formatting * cosmetics --------- Co-authored-by: Marc Becker <[email protected]> Co-authored-by: Mahati Shankar <[email protected]> Co-authored-by: Mahati Shankar <[email protected]> * Update java/migration.md Co-authored-by: Mahati Shankar <[email protected]> * added new default value of message service structured flag * changed default value in java messaging docs * fixed link * Update migration.md * Update java/migration.md * Update java/migration.md * Update java/migration.md * cosmetics --------- Co-authored-by: Markus Ofterdinger <[email protected]> Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Adrian Görler <[email protected]> Co-authored-by: René Jeglinsky <[email protected]> Co-authored-by: Thomas Bonk <[email protected]> Co-authored-by: Matthias Schur <[email protected]> Co-authored-by: Stefan Henke <[email protected]> Co-authored-by: Vladimir <[email protected]> Co-authored-by: Mahati Shankar <[email protected]> Co-authored-by: Mahati Shankar <[email protected]> Co-authored-by: BraunMatthias <[email protected]> Co-authored-by: Thomas Bonk <[email protected]>
cap-js · Jul 1, 2024 · f6f9336 · f6f9336
1 parent 136779b
commit f6f9336
Show file tree

Hide file tree

Showing 6 changed files with 232 additions and 64 deletions.
diff --git a/java/cqn-services/remote-services.md b/java/cqn-services/remote-services.md
@@ -147,8 +147,8 @@ The class `SomeReuseServiceOAuth2PropertySupplier` needs to be provided by you e
 
 #### Binding to a Service with Shared Identity
 
-If the remote API is available within the same SaaS application and using the same (shared) XSUAA service instance for authentication, no service broker-based reuse service is required.
-The _Remote Service_ can be configured using the shared XSUAA service instance as binding (here: `shared-xsuaa`):
+If the remote API is available within the same SaaS application and using the same (shared) service instance of XSUAA or Identity (IAS) for authentication, no service broker-based reuse service is required.
+The _Remote Service_ can be configured using the shared service instance as binding (here: `shared-xsuaa`):
 
 ::: code-group
 ```yaml [srv/src/main/resources/application.yaml]
@@ -162,9 +162,14 @@ cds:
 ```
 :::
 
-The plain XSUAA service binding does not contain the URL of the remote API. Therefore it needs to be explicitly configured in the `options` section.
+The plain service binding of XSUAA or IAS does not contain the URL of the remote API. Therefore it needs to be explicitly configured in the `options` section.
 As the URL is typically not known at development time, it can be alternatively defined as an environment variable `CDS_REMOTE_SERVICES_<name>_OPTIONS_URL`.
 
+:::tip
+Remote APIs which require IAS-based authentication might expect certificate based client authentication in addition to the IAS-based JWT token (ie. [proof-of-possession](https://github.com/SAP/cloud-security-services-integration-library/tree/main/java-security#proofofpossession-validation)). 
+CAP _Remote Services_ automatically takes care of this by initiating a mutual TLS handshake with the remote API.
+:::
+
 #### Configuring the Authentication Strategy
 
 While service bindings typically provide authentication details, they don't predetermine the user propagation and authentication strategy, for example, technical user or named user flow.
@@ -193,6 +198,20 @@ cds:
 ```
 :::
 
+If your CAP application is using IAS and you want to call a _remote API_ that is provided by another IAS-based application (ie. Application2Application scenario), you can utilize a simplified security configuration in the destination.
+As a pre-requisite, your CAP application and the called application need to trust the same IAS tenant and you need to define a dependency in IAS to consume the respective API provided by the _remote API_.
+
+Create a destination configuration with the following parameters:
+
+- _URL_: `<url-of-the-remote-api>`
+- _Authentication_: `NoAuthentication`
+- Additional Properties:
+  - _cloudsdk.ias-dependency-name_: `<name-of-the-ias-dependency>`
+
+At runtime, this destination configuration will use the bound `identity` service instance's credentials to request a token for the _remote API_.
+
+[Learn more about consuming APIs from Other IAS-Appications in the **SAP Cloud Identity Services documentation**.](https://help.sap.com/docs/cloud-identity-services/cloud-identity-services/consume-apis-from-other-applications){.learn-more}
+
 The CAP Java SDK obtains the destination for a _Remote Service_ from the `DestinationAccessor` using the name that is configured in the _Remote Service_'s destination configuration.
 
 If you're using the SAP BTP Destination Service, this is the name you used when you defined the destination there. To properly resolve the destination from SAP BTP Destination Service [additional Cloud SDK dependencies](#cloud-sdk-dependencies) are required.

diff --git a/java/developing-applications/configuring.md b/java/developing-applications/configuring.md
@@ -28,10 +28,10 @@ Now, that you're familiar with how to configure your application, start to creat
 
 When running your application in production, it makes sense to strictly disable some development-oriented features.
 The production profile configures a set of selected property defaults, recommended for production deployments, at once.
-To specify the production profile, set `cds.environment.production.profile` to a Spring profile used in production deployments.
+By default the production profile is set to `cloud`. To specify a custom production profile, set `cds.environment.production.profile` to a Spring profile used in your production deployments.
 
 ::: tip Production profile = `cloud`
-It is recommended to set `cds.environment.production.profile` to `cloud`. The Java Buildpacks set the `cloud` profile for applications by default.
+The Java Buildpacks set the `cloud` profile for applications by default.
 Other active profiles for production deployments are typically set using the environment variable `SPRING_PROFILES_ACTIVE` on your application in your deployment descriptors (`mta.yaml`, Helm charts, etc.).
 :::
 

diff --git a/java/messaging.md b/java/messaging.md
@@ -755,7 +755,7 @@ Besides these kinds of topic manipulations, additional topic manipulations might
 
 The configuration property `structured` determines if messages are represented as a plain String (`false`) or always structured as two separate maps, representing data and headers (`true`). Setting this property enables handling of message headers, like `cloudevents` headers, separately from the message itself. This works for all messaging brokers supported by CAP. If using a message broker that supports native headers, e.g. Kafka, the headers are separated from the business data. On incoming messages the flag determines the internal representation of the message either as a plain string or two maps of message data and message headers. Having header data separated, avoids adding extra information or metadata as part of the business data when sending them to the message broker. Additionally the header data is clearly separated on the consumer side, because they provided by different data and headers maps.
 
-The default value for the configuration property `structured` is `false`.
+The default value for the configuration property `structured` is `true`.
 
 Configuration example:
 ::: code-group

diff --git a/java/migration.md b/java/migration.md
@@ -23,8 +23,203 @@ uacp: Used as link target from Help Portal at https://help.sap.com/products/BTP/
 
 [[toc]]
 
+## CAP Java 2.10 to CAP Java 3.0 { #two-to-three }
 
-## CAP Java 1.34 to CAP Java 2.0 { #one-to-two}
+### Minimum Versions
+
+CAP Java 3.0 increased some minimum required versions:
+
+| Dependency | Minimum Version |
+| --- | --- |
+| @sap/cds-dk | ^7 |
+| Maven | 3.6.3 |
+| Cloud SDK | 5.9.0 |
+
+CAP Java 3.0 no longer supports @sap/cds-dk ^6.
+
+### Production Profile `cloud`
+
+The Production Profile now defaults to `cloud`. This ensures that various property defaults suited for local development are changed to recommended secure values for production.
+
+One of the effects of the production profile is that the index page is disabled by default.
+If you are using the root path `/` for readiness or liveness probing in Kyma you will need to adjustment them, in this case
+it is recommended to use Spring Boot actuator's `/actuator/health` endpoint instead.
+
+[Learn more about the Production Profile.](developing-applications/configuring#production-profile){.learn-more}
+
+### 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`.
+
+It utilizes [SAP´s `spring-security` library](https://github.com/SAP/cloud-security-services-integration-library/tree/main/spring-security) instead of the deprecated [`spring-xsuaa` library](https://github.com/SAP/cloud-security-services-integration-library/tree/main/spring-xsuaa).
+
+If your application relies on the standard security configuration by CAP Java and depend on one of the CAP starter bundles, it is expected that you won't need to adapt code.
+
+If you have customized the security configuration, you need to adapt it to the new library. If your application had a direct dependency to `cds-feature-xsuaa`, we recommend using one of our starter bundles `cds-starter-cloudfoundry` or `cds-starter-k8s`.
+
+[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
+
+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 (e.g. 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/<tenant>` (PUT)
+
+### Lazy Localization by default
+
+EDMX resources served by the OData V4 `/$metadata` endpoints are now localized lazily by default.
+This significantly reduces EDMX cache memory consumption when many languages are used.
+Note, that this requires at least `@sap/cds-mtxs` in version `1.12.0`.
+
+The cds build no longer generates localized EDMX files by default anymore, but instead generates templated EDMX files and a `i18n.json` containing text bundles.
+If you need localized EDMX files to be generated, set `--opts contentLocalizedEdmx=true` when calling `cds build`.
+
+### Star-expand and inline-all are no longer permitted
+
+Previously, you could not use expand or inline without explicit paths on draft-enabled entities. Now they are rejected for all entities on application service level.
+
+For example, following statement will not be executed when submitted to an instance of [`ApplicationService`](https://www.javadoc.io/doc/com.sap.cds/cds-services-api/latest/com/sap/cds/services/cds/ApplicationService.html).
+
+```java
+Select.from(BOOKS).columns(b -> b.expand());
+```
+
+This does not impact OData where `expand=*` is transformed into expands for all associations.
+
+### Adjusted POJO class generation
+
+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. |
+
+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.
+
+### Adjusted Property Defaults
+
+Some property defaults have been adjusted:
+
+| Property | Old Value | New Value | Explanation |
+| --- | --- | --- | --- |
+| `cds.remote.services.<key>.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.messaging.services.<key>.structured` | `false` | `true` | [Enhanced message representation](./messaging.md#enhanced-messages-representation) is now enabled by default. |
+
+### Adjusted Property Behavior
+
+| Property | New Behavior |
+| --- | --- |
+| `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:
+
+| 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.identity.authConfig.enabled` | `cds.security.authentication.authConfig.enabled` | |
+| `cds.messaging.services.<key>.outbox.persistent.enabled` | `cds.messaging.services.<key>.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.<key>.maxAttempts` | |
+| `cds.outbox.persistent.storeLastError` | `cds.outbox.services.<key>.storeLastError` | |
+| `cds.outbox.persistent.ordered` | `cds.outbox.services.<key>.ordered` | |
+| `cds.remote.<key>.destination.headers` | `cds.remote.services.<key>.http.headers` | |
+| `cds.remote.<key>.destination.queries` | `cds.remote.services.<key>.http.queries` | |
+| `cds.remote.<key>.destination.service` | `cds.remote.services.<key>.http.service` | |
+| `cds.remote.<key>.destination.suffix` | `cds.remote.services.<key>.http.suffix` | |
+| `cds.remote.<key>.destination.type` | `cds.remote.services.<key>.type` | |
+| `cds.security.mock.users.<key>.unrestricted` | | Special handling of unrestricted attributes has been removed, in favor of [explicit modelling](../guides/security/authorization#unrestricted-xsuaa-attributes). |
+| `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` | |
+
+### Removed Java APIs
+
+- Removed deprecated classes:
+  - `com.sap.cds.services.environment.ServiceBinding`
+  - `com.sap.cds.services.environment.ServiceBindingAdapter`
+  - `com.sap.cds.services.mt.MtAsyncDeployEventContext`
+  - `com.sap.cds.services.mt.MtAsyncDeployStatusEventContext`
+  - `com.sap.cds.services.mt.MtAsyncSubscribeEventContext`
+  - `com.sap.cds.services.mt.MtAsyncSubscribeFinishedEventContext`
+  - `com.sap.cds.services.mt.MtAsyncUnsubscribeEventContext`
+  - `com.sap.cds.services.mt.MtAsyncUnsubscribeFinishedEventContext`
+  - `com.sap.cds.services.mt.MtDeployEventContext`
+  - `com.sap.cds.services.mt.MtGetDependenciesEventContext`
+  - `com.sap.cds.services.mt.MtSubscribeEventContext`
+  - `com.sap.cds.services.mt.MtSubscriptionService`
+  - `com.sap.cds.services.mt.MtUnsubscribeEventContext`
+
+- Removed deprecated methods:
+  - `com.sap.cds.services.request.ModifiableUserInfo.addUnrestrictedAttribute`
+  - `com.sap.cds.services.request.ModifiableUserInfo.setUnrestrictedAttributes`
+  - `com.sap.cds.services.request.ModifiableUserInfo.removeUnrestrictedAttribute`
+  - `com.sap.cds.services.request.UserInfo.getUnrestrictedAttributes`
+  - `com.sap.cds.services.request.UserInfo.isUnrestrictedAttribute`
+  - `com.sap.cds.ql.Insert.cqn(String)`
+  - `com.sap.cds.ql.Update.cqn(String)`
+  - `com.sap.cds.ql.Upsert.cqn(String)`
+
+- Deprecations:
+  - `com.sap.cds.ql.cqn.CqnSearchPredicate`, instead use `CqnSearchTermPredicate`
+  - `com.sap.cds.ql.cqn.Modifier.search(String)`, instead use `searchTerm(CqnSearchTermPredicate)`
+
+### Removed goals in `cds-maven-plugin`
+
+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:
+
+```xml
+<dependency>
+	<groupId>com.sap.cloud.sdk.cloudplatform</groupId>
+	<artifactId>connectivity-apache-httpclient4</artifactId>
+</dependency>
+```
+
+If you are using Cloud SDK APIs explicitly in your code consider the migration guide for Cloud SDK 5 itself: https://sap.github.io/cloud-sdk/docs/java/guides/5.0-upgrade-steps
+
+## CAP Java 1.34 to CAP Java 2.0 { #one-to-two }
 
 This section describes the changes in CAP Java between the major versions 1.34 and 2.0. It provides also helpful information how to migrate a CAP Java application to the new major version 2.0.
 
@@ -1042,16 +1237,3 @@ After rebuilding and restarting your application, your Application Services are
 <!-- TODO: Move this to "Development" section -->
 
 <span id="afterenablingodata" />
-
-## 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 to use at least version `5.2.0` of Cloud SDK. To upgrade your CAP Java application to Cloud SDK 5, in most cases, you  don't need to adapt any code if you rely on the Cloud SDK integration package (`cds-integration-cloud-sdk`). In these cases, it's sufficient to add the following maven dependency to your CAP Java application:
-
-```xml
-<dependency>
-	<groupId>com.sap.cloud.sdk.cloudplatform</groupId>
-	<artifactId>connectivity-apache-httpclient4</artifactId>
-</dependency>
-```
-
-