Migration Guide for CAP Java 3.0

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.).
 :::
 

java/migration.md

@@ -23,8 +23,91 @@ 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}
+::: warning
+This is a **preview** of the changes planned for CAP Java 3.0 (planned to be released July 2024)
+:::
+
+### Minimum Versions
+
+CAP Java 3.0 increased some minimum required versions:
+
+| Dependency | Minimum Version |
+| --- | --- |
+| Maven | 3.6.3 |
+| Cloud SDK | 5.9.0 |
+
+### 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.
+
+[Learn more about the Production Profile.](developing-applications/configuring#production-profile){.learn-more}
+
+### 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. |
+
+
+### Replaced Properies
+
+  - `cds.data-source.csvInitializationMode` -> `cds.data-source.csv.initializationMode`
+  - `cds.data-source.csvFileSuffix` -> `cds.data-source.csv.fileSuffix`
+  - `cds.data-source.csvPaths` -> `cds.data-source.csv.paths`
+  - `cds.data-source.csvSingleChangeset` -> `cds.data-source.csv.singleChangeset`
+  - `cds.remote.remoteServiceConfig.destination.type` -> `cds.remote.services.<key>.type`
+  - `cds.remote.remoteServiceConfig.destination.suffix` -> `cds.remote.services.<key>.http.suffix`
+  - `cds.remote.remoteServiceConfig.destination.service` -> `cds.remote.services.<key>.http.service`
+  - `cds.remote.remoteServiceConfig.destination.headers` -> `cds.remote.services.<key>.http.headers`
+  - `cds.remote.remoteServiceConfig.destination.queries` -> `cds.remote.services.<key>.http.queries`
+  - `cds.sql.search.useLocalizedView` -> `cds.sql.search.model`
+  - `cds.identity.authConfig.enabled` -> `cds.security.authentication.authConfig.enabled`
+  - `cds.xsuaa.authConfig.enabled` -> `cds.security.authentication.authConfig.enabled`
+  - `cds.odataV4.apply.inCqn.enabled` -> `cds.odataV4.apply.transformations.enabled`
+  - `cds.multiTenancy.healthCheck.intervalMillis` -> `cds.multiTenancy.healthCheck.interval`
+  - `cds.messaging.services.<key>.outbox.persistent.enabled` -> `cds.messaging.services.<key>.outbox.name`
+  - `cds.auditlog.outbox.persistent.enabled` -> `cds.auditlog.outbox.name`
+
+### Removed Properties
+
+- `cds.sql.supportedLocales`
+- `cds.security.mock.users.<key>.unrestricted`
+
+### Removed Java APIs
+
+- Removed deprecated classes:
+  - `com.sap.cds.services.environment.ServiceBinding`
+  - `com.sap.cds.services.environment.ServiceBindingAdapter`
+
+- Removed deprecated methods:
+  - `com.sap.cds.services.request.ModifiableUserInfo.setUnrestrictedAttributes`
+  - `com.sap.cds.services.request.ModifiableUserInfo.addUnrestrictedAttribute`
+  - `com.sap.cds.services.request.ModifiableUserInfo.removeUnrestrictedAttribute`
+  - `com.sap.cds.services.request.UserInfo.isUnrestrictedAttribute`
+  - `com.sap.cds.services.request.UserInfo.getUnrestrictedAttributes`
+
+### Changes in `cds-maven-plugin`
+
+The goal `addSample` is removed from the `cds-maven-plugin` and replaced with the goal `add` and property `-Dfeature=TINY_SAMPLE`.
+
+## 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.7.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>
+```
+
+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.
 
@@ -1040,16 +1123,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>
-```
-
-