Steps to update to Version 5 of the SAP Cloud SDK
Version 5 of the SAP Cloud SDK is here and we highly recommend updating to it as soon as possible. It brings various improvements, it is now Open Source and the Destination API has been unified.
For more information also check out our version 5 release blog post
Starting with version 5.0.0 the SAP Cloud SDK requires a Java version of at least 17.
If you are using the Cloud Application Programming model (CAP) to build your application, please note that the SAP Cloud SDK version 5 requires a minimum CAP/CDS version of at least 2.4.0.
If you are on an older CAP stack, please follow the CAP migration guide first.
Before You Update
Before you increase the SAP Cloud SDK version to 5, it is recommended to first update to the latest available version of the SAP Cloud SDK 4 and migrate any usage of deprecated API. Follow the deprecation notes in the Javadocs to find recommended replacements. All deprecated APIs are removed with version 5.
Also, make sure that you are using Java 17 or higher. To setup your build to use Java 17 you can use this guide. As Java EE modules have been removed from Java 11, you might also need to update your application to use the Jakarta EE modules instead. This JEP provides a good overview of the changes: JEP 320: Remove the Java EE and CORBA Modules.
If you are consuming SOAP APIs and are relying on the axis2-wsdl2code-maven-plugin to generate classes, please also additionally include javax.activation:activation artifact to your dependencies to avoid compilation errors.
We recommend to update your application in the following order:
- Make sure you use the latest SAP Cloud SDK v4 version available.
- Update your application to use Java 17.
- Update your application to use the latest SAP Cloud SDK v5 and Spring Boot/Spring version available.
Change Version of Your sdk-bom or sdk-modules-bom
The first step is to change the version of the SAP Cloud SDK dependency in your pom.xml file.
Depending on your project setup you might use one of our BOMs or the individual modules.
To find our BOMs, search for the following entries in your maven dependencyManagement section: com.sap.cloud.sdk:sdk-bom and com.sap.cloud.sdk:sdk-modules-bom.
Update them directly to version 5.0.0 or the latest version.
- Spring Boot
- SAP Java Buildpack
If you are using the SAP Java Buildpack and produce a war deployment (e.g. when you require JCo for your application),
please replace the sdk-sjb-bom with the cf-tomee7-bom and the sdk-bom instead:
<dependencyManagement>
<dependencies>
<!-- Cloud SDK + SAP Java Buildpack BOMs -->
<dependency>
<groupId>com.sap.cloud.sjb.cf</groupId>
<artifactId>cf-tomee7-bom</artifactId>
<version>use-latest-version-here</version>
<type>pom</type>
<scope>import</scope>
</dependency>
<dependency>
<groupId>com.sap.cloud.sdk</groupId>
<artifactId>sdk-bom</artifactId>
<version>use-latest-version-here</version>
<type>pom</type>
<scope>import</scope>
</dependency>
<!-- Work around for SOAP users only -->
<dependency>
<groupId>org.codehaus.woodstox</groupId>
<artifactId>stax2-api</artifactId>
<version>4.2.2</version>
<scope>compile</scope>
</dependency>
</dependencies>
</dependencyManagement>
Change the target runtime from tomee7 to tomcat, and the buildpack from sap_java_buildpack to sap_java_buildpack_jakarta:
buildpacks:
- - sap_java_buildpack
+ - sap_java_buildpack_jakarta
env:
- TARGET_RUNTIME: tomee7
+ TARGET_RUNTIME: tomcat
If you are building on Spring or Spring Boot you should also update to the latest version of the respective BOMs, so 6.1.0 (Spring) or 3.1.6 (Spring Boot) as of the time of writing.
These BOMs should be listed after any SAP Cloud SDK related BOM, so for Spring Boot your dependencyManagement section should look something like this:
<dependencyManagement>
<dependencies>
<dependency>
<groupId>com.sap.cloud.sdk</groupId>
<artifactId>sdk-bom</artifactId>
<version>5.0.0</version> <!-- TODO: replace this with the most recent version -->
<type>pom</type>
<scope>import</scope>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-dependencies</artifactId>
<version>3.1.6</version> <!-- TODO: replace this with the most recent version -->
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
At the same time you should also replace usages of javax dependencies with the respective jakarta dependency.
As we only provide a managed version for jakarta.servlet-api in our BOM, you will need to add the formerly managed version for the jakarta.inject-api dependency manually:
-<dependency>
- <groupId>javax.inject</groupId>
- <artifactId>javax.inject</artifactId>
-</dependency>
+<dependency>
+ <groupId>jakarta.inject</groupId>
+ <artifactId>jakarta.inject-api</artifactId>
+ <version>2.0.1</version>
+</dependency>
Also remember to migrate all your dependencies to their respective jakarta versions if applicable.
For example, if you were using com.sap.hcp.cf.logging:cf-java-logging-support-servlet for application logging you must instead switch to using com.sap.hcp.cf.logging:cf-java-logging-support-servlet-jakarta.
-<dependency>
- <groupId>com.sap.hcp.cf.logging</groupId>
- <artifactId>cf-java-logging-support-servlet</artifactId>
-</dependency>
+<dependency>
+ <groupId>com.sap.hcp.cf.logging</groupId>
+ <artifactId>cf-java-logging-support-servlet-jakarta</artifactId>
+ <version>latest-lib-version</version>
+</dependency>
For projects that were already upgraded to Java 17 and Spring Boot 3 in SAP Cloud SDK 4
Remove or Replace Modified SAP Cloud SDK Dependencies
The lists below contains all modules that have been renamed or removed from the SAP Cloud SDK. Therefore, you should also rename respectively remove those from your project setup.
Full list of renamed or replaced modules
Full list of removed modules
If you are using our BOMs to provide the module versions, a fast way to do identify those is to run any mvn command.
This will now lead to error messages like this:
'dependencies.dependency.version' for com.sap.cloud.sdk.cloudplatform:auditlog-scp-cf:jar is missing
This helps you to identify which modules you need to remove or replace in your project setup.
Steps to migrate Destination usages
Version 5 of the SAP Cloud SDK comes with a major cleanup of the APIs around the Destination concept.
This cleanup comes without a lot of breaking changes so that existing applications require only a minimum of adjustments.
To make the process of adjusting existing applications as easy as possible, please follow the below steps:
-
Remove any invocation of
Destination#decorate. This method was only used in conjunction with theDefaultErpHttpDestination, which has been removed in this major version update. The functionality has been moved internally, so that decorating existingDestinationinstances is no longer needed. -
(Optional) Remove any invocations of
Destination#asHttporDestination#asRfc. A big part of theDestinationcleanup was to straighten our public APIs that expected specific sub-types ofDestinationorDestinationProperties(e.g.HttpClientAccessor#getHttpClient(HttpDestinationProperties)). These APIs now all rely onDestination, which makes casting via#asHttpor#asRfcunnecessary. -
Replace any of the removed classes related to the
DestinationAPI as mentioned in the list of removed APIs.
DestinationAccessExceptionAn earlier version of the upgrade guide contained an additional instruction to move handling of DestinationAccessException from DestinationAccessor.getDestination() to destination.getHeaders().
This instruction was incorrect and has been removed.
In case you have followed this instruction, please revert the change.
Remove or Replace Modified SAP Cloud SDK APIs
Once the build doesn't complain about missing dependency versions anymore, you can start to fix the compilation errors.
Full list of removed API
Generate and Use Your Own OData Clients
Generate Your Own OData Clients
The SAP Cloud SDK no longer provides pre-generated OData Virtual Data Models. We made this decision to reduce the maintenance effort and to allow you to generate your own OData clients with the exact version of the OData service you are using. That way there is no need to wait for the next SAP Cloud SDK release to get the latest changes of an OData service you are consuming.
To generate your own OData VDM, you can use the OData Generator Maven Plugin directly. You can use the following configuration to generate an OData client that is compatible with the OData VDM the SAP Cloud SDK provided in version 4:
- OData v2
- OData v4
<inputDirectory>${project.basedir}/src/main/resources/odata/edmx</inputDirectory>
<outputDirectory>${project.build.directory}/vdm</outputDirectory>
<serviceNameMappingFile>${project.basedir}/src/main/resources/odata/serviceNameMappings.properties</serviceNameMappingFile>
<deleteOutputDirectory>true</deleteOutputDirectory>
<packageName>com.sap.cloud.sdk.s4hana.datamodel.odatav4</packageName>
<compileScope>COMPILE</compileScope>
The file specified under serviceNameMappingFile will be created and populated, if it doesn't exist yet. If you want to create an OData client that is compatible with the OData VDM the SAP Cloud SDK provided in version 4, you can use this serviceNameMappings.properties.
<inputDirectory>${project.basedir}/src/main/resources/odata/edmx</inputDirectory>
<outputDirectory>${project.build.directory}/vdm</outputDirectory>
<serviceNameMappingFile>${project.basedir}/src/main/resources/odata/serviceNameMappings.properties</serviceNameMappingFile>
<deleteOutputDirectory>true</deleteOutputDirectory>
<packageName>com.sap.cloud.sdk.s4hana.datamodel.odata</packageName>
<compileScope>COMPILE</compileScope>
The file specified under serviceNameMappingFile will be created and populated, if it doesn't exist yet. If you want to create an OData client that is compatible with the OData VDM the SAP Cloud SDK provided in version 4, you can use this serviceNameMappings.properties.
If you want to generate an OData client that is compatible with the On-Premise OData VDM the SAP Cloud SDK provided in version 4, take special care of the packageName and the contents of the serviceNameMappingFile to reflect what you are expecting.
Handle OData Virtual Data Model Instantiation
Depending on your project setup, you might have relied on the @Inject annotation in your OData VDM services.
As the OData generators don't generate the javax.inject.Named annotations anymore, you will need to instantiate your own services instead.
For that you can either use your own dependency injection framework, or instantiate the services manually.
The manual approach would look something like this:
- @Inject
- private BusinessPartnerService businessPartnerService;
+ private BusinessPartnerService businessPartnerService = new DefaultBusinessPartnerService();
Remove Discontinued ServletFilter from Your web.xml
We decided to remove all security related Filter implementations from the SAP Cloud SDK, to have a clearer separation between the SAP Security Libraries and the SAP Cloud SDK.
This means you need to remove all mentions of the following filters from your web.xml (mind the security in the package): com.sap.cloud.sdk.cloudplatform.security.servlet.*Filter
The com.sap.cloud.sdk.cloudplatform.servlet.RequestAccessorFilter is functionally replaced by com.sap.cloud.sdk.cloudplatform.servletjakarta.RequestAccessorFilter found in com.sap.cloud.sdk.cloudplatform:servlet-jakarta.
Audit Log usage
The Audit Log feature is no longer released with version 5 of the SAP Cloud SDK. If you want to continue using audit logging, you could still use version 4 of the audit logging artifact along with version 5 of the SAP Cloud SDK.
You would have to manually add all the following artifacts(only available internally) to your project:
<dependency>
<groupId>com.sap.cloud.sdk.cloudplatform</groupId>
<artifactId>auditlog-scp-cf</artifactId>
<version>4.28.0</version> <!-- Pay attention that this the old v4 artifact -->
</dependency>
<dependency>
<groupId>com.sap.xs.auditlog</groupId>
<artifactId>audit-java-client-api</artifactId>
<version>latest-available-version-in-artifactory</version>
</dependency>
<dependency>
<groupId>com.sap.xs.auditlog</groupId>
<artifactId>audit-java-client-impl</artifactId>
<version>latest-available-version-in-artifactory</version>
</dependency>
<dependency>
<groupId>com.sap.xs.java</groupId>
<artifactId>xs-env</artifactId>
<version>latest-available-version-in-artifactory</version>
</dependency>
You will then be able to log events using the AuditLogger API.