Frequently Asked Questions

General Questions

How Often Do You Release a New SAP Cloud SDK Version?

We release a minor version every two weeks. All the features that are Generally Available or Beta get into the next release. You can find the latest SAP Cloud SDK version and the list of previous releases here or on Maven Central. Find more details in our release policy.

Should I Update With Every Release?

The general recommendation is YES. This way you'll reduce the effort to keep up with the fast pace of cloud development. We try to keep stable functionality consistent and explicitly notify about breaking changes. Be cautious about using features annotated as Beta because their API can change with every release.

Which Java Versions Are Supported by the SAP Cloud SDK?

The SAP Cloud SDK itself is compatible with Java 8, 11 and 17. Other Java versions may work as well, depending on your setup, but are not yet tested by us. Note that the SAP Business Technology Platform Cloud Foundry environment only supports Java 8 out of the box, but can be configured to also run with Java 11 or 17. SAP Business Technology Platform Neo only supports Java 8.

Spring Boot 3 and Java 17 support

SAP Cloud SDK can be used with JakartaEE (e.g. via Spring Boot 3, Spring 6, and Java 17) thanks to the experimental module servlet-jakarta.

In case you are migrating your application from Spring Boot 2, the below steps make sure the Cloud SDK continues to work smoothly:

1. Set Spring Boot version to 3 and Java version to 17:

<properties>
    <java.version>17</java.version>
    <maven.compiler.source>${java.version}</maven.compiler.source>
    <maven.compiler.target>${java.version}</maven.compiler.target>
    <maven.compiler.testSource>${java.version}</maven.compiler.testSource>
    <maven.compiler.testTarget>${java.version}</maven.compiler.testTarget>
</properties>

2. Place the Spring Boot dependency management before the SDK BOM:

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-dependencies</artifactId>
            <version>3.0.2</version> <!-- TODO: replace this with the most recent version -->
            <type>pom</type>
            <scope>import</scope>
        </dependency>
        <dependency>
            <groupId>com.sap.cloud.security</groupId>
            <artifactId>java-bom</artifactId>
            <version>3.1.3</version> <!-- TODO: replace this with the most recent version -->
            <scope>import</scope>
            <type>pom</type>
        </dependency>
        <dependency>
            <groupId>com.sap.cloud.sdk</groupId>
            <artifactId>sdk-bom</artifactId>
            <version>4.20.0</version> <!-- TODO: replace this with the most recent version -->
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

3. Replace any javax dependency with the respective jakarta dependency:

-<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>

Don't forget to replace javax imports in Java files with jakarta imports.

Also remember to migrate all your dependencies to their respective jakarta versions if applicable.

For example, if you were previously 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>

4. Add the new servlet-jakarta module:

<dependencies>
    <dependency>
        <groupId>com.sap.cloud.sdk.cloudplatform</groupId>
        <artifactId>servlet-jakarta</artifactId>
    </dependency>
</dependencies>

5. When using the @ServletComponentScan annotation as suggested, please update the namespace:

- @ServletComponentScan({"com.sap.cloud.sdk", ...
+ @ServletComponentScan({"com.sap.cloud.sdk.cloudplatform.servletjakarta", ...

6. Configure Cloud Foundry for Java 17

• Configure SAP Java Buildpack to run with Java 17
  • Add the SAPMachine JRE version 17 in you manifest.yml:

    env:
  +   JBP_CONFIG_COMPONENTS: 'jres: [''com.sap.xs.java.buildpack.jre.SAPMachineJRE'']'
  +   JBP_CONFIG_SAP_MACHINE_JRE: '{ use_offline_repository: false, version: 17.0.5 }'

Can I Use Features Annotated as Beta in Production?

We do not recommend using the API that is marked unstable in the production code. We do not guarantee any API compatibility for future updates and the features might be experimental. You can use these features to test new functionality, provide us feedback, and plan migration steps when Beta features are released as General Availability.

I Think I Found a Bug in the SAP Cloud SDK, What Should I Do?

Please, report it to us via any available channel. The preferred support channel is Stack Overflow. You can also create an issue on the SAP Cloud SDK external GitHub repository or use the internal one if you're an SAP employee.

How Do I Remotely Debug My App on SAP BTP Cloud Foundry?

Use these CF CLI instructions to activate debugging for your App.

TomEE (when using SAP Java Buildpack)

cf ssh application -c "app/META-INF/.sap_java_buildpack/sapjvm/bin/jvmmon <<< 'start debugging'"
cf ssh application -N -T -L 8000:localhost:8000

Spring

cf set-env application JBP_CONFIG_DEBUG "{enabled: true}"
cf restage application
cf ssh -N -T -L 8000:localhost:8000 application

Check out this blog post for step-by-step remote debugging instructions. You'll also learn how to get debug information into IntelliJ IDEA.

warning

Do not forget to revert any changes you made to your mta.yml (and/or environment) after your debugging session. We strongly discourage users from running productive applications in debug mode!

I'm Observing a DefaultHttpClientFactory not a subtype Exception

Application that rely on the SAP Java Buildpack, which is always true for application that require JCo, may throw the following exception when trying to access a RFC destination:

java.util.ServiceConfigurationError: com.sap.cloud.security.client.HttpClientFactory: com.sap.cloud.security.client.DefaultHttpClientFactory not a subtype

This issue is caused by a dependency scope conflict and can be solved by following our guidance.

Incoming Requests Fail Because a Request Header is Too Large

In some cases you may need to configure your app/server to accept larger request headers. If your app is responding with 400 codes and you see a log entry Request header is too large make sure to increase the header size limit.

Refer to this guide on how to achieve this for Spring based applications. In case you are deploying a WAR file with the SAP Java Buildpack refer to this documentation.

OData Related Questions

What Versions of OData Protocol Do You Support?

We support OData v2 and OData v4 services. You can use the pregenerated client libraries supplied with the SAP Cloud SDK or generate your client from the SAP Cloud SDK specification. Find more details here.

Do You Support All OData Features?

We support most of the OData features that are exposed by SAP services. However, the OData specification is huge and contains many features that would see rare to no use. If you need a feature that is not yet supported by SAP Cloud SDK, please make a feature request via email cloudsdk@sap.com or create an issue towards one of our repositories.

I Receive an OData Error/Exception When Using SAP Cloud SDK for Java

You may see some errors while developing. These errors are not always caused by flaws in the SAP Cloud SDK as we often see inconsistent OData protocol handling by different services. Some of them even have known flaws for which we have workarounds. If you can't solve your issue via debugging and experimenting, please, report your incident via Stack Overflow or our GitHub repositories.

How To Use the OData Attachment Service?

You are trying to use the virtual data model for AttachmentService as provided by the SAP Cloud SDK. However, it's impossible to run the request successfully, the attachments will not be uploaded. This is caused by an outdated specification, for which the Java classes are automatically generated. As a consequence the generated AttachmentService interface and DefaultAttachmentService implementation cannot be used reliably.

We recommend running manual requests instead (click to expand).

1. Request CSRF token with HEAD request
2. Upload Attachment with POST request.

// Resolve HttpClient instance
HttpDestination destination;
HttpClient httpClient = HttpClientAccessor.getHttpClient(destination);

// Resolve CSRF token, internally runs HEAD request
String csrfToken = new DefaultCsrfTokenRetriever()
    .retrieveCsrfToken(httpClient, AttachmentService.DEFAULT_SERVICE_PATH)
    .getToken();

// Prepare attachment for HTTP request
InputStream inStream;
HttpEntity attachmentEntity = new InputStreamEntity(inStream); // alternatively, new FileEntity(File)

// Prepare attachment creation request
HttpPost create = new HttpPost(AttachmentService.DEFAULT_SERVICE_PATH + "/AttachmentContentSet");
create.setEntity(attachmentEntity);
create.setHeader(DefaultCsrfTokenRetriever.X_CSRF_TOKEN_HEADER_KEY, csrfToken);
create.setHeader("Content-Type", "image/jpeg");
create.setHeader("Slug", "'filename.jpg'");
create.setHeader("BusinessObjectTypeName", "'ObjectTypeName'");
create.setHeader("LinkedSAPObjectKey", "'ObjectKey'");

// Send attachment creation request
HttpResponse response = httpClient.execute(create);

// Parse response
String responseText = EntityUtils.toString(response.getEntity());

Once you've decided on InputStream or File as underlying data type for HttpEntity, you need to apply values for HTTP headers:

• x-csrf-token - value from previous HEAD request
• Content-Type - value depending on a file type, make sure it is correct
• Slug - value in single-quotes '
• BusinessObjectTypeName - value in single-quotes '
• LinkedSAPObjectKey - value in single-quotes '.

Please note, depending on the file size, a request may take several seconds to minutes. This suggested HTTP interaction is the officially documented approach. It's not considered a workaround.

In case you want to deserialize the JSON from responseTest variable, then run the following code:

// Deserialize the AttachmentContent object
TypeToken<Map<String, AttachmentContent>> responseType = new TypeToken<Map<String, AttachmentContent>>() {
};
Map<String, AttachmentContent> responseObject = new Gson().fromJson(responseText, responseType.getType());
AttachmentContent result = responseObject.get("d");

"Provide a correct Content-Type"

The Content-Type should correspond to the uploaded file or your upload might fail.

Open API Related Questions

Do You Support RESTful Services?

Yes, we do support OpenAPI 2.0 also known as Swagger, and OpenAPI 3.0 specifications. The latter is preferred. Find documentation how to generate a type-safe Open API client here. We also release pregenerated libraries in collaboration with service providers who release RESTful Open API services. For details check an overview. For feedback or questions about our Open API offering, please, create an issue here.

Questions About SAP Business Technology Platform

Do You Support SAP BTP, Cloud Foundry Environment?

The SAP Cloud SDK for Java has first-class support for SAP BTP, Cloud Foundry environment. We provide plenty of helpful abstractions for connectivity and authentication that make developing apps a pleasant and rewarding experience. Let us know if you miss functionality of the SAP BTP for the Cloud Foundry environment in the SAP Cloud SDK for Java.

Do You Support SAP Business Technology Platform - Neo?

warning

All the NEO specific classes and functions have been deprecated. We are planning to discontinue support of NEO with SAP Cloud SDK v5 by end of 2023.

We still provide full support for SAP Business Technology Platform Neo. However, we do not recommend starting new projects with SAP BTP for the Neo environment. The Cloud Foundry environment is better suited for apps and SAP S/4HANA extension development. Also, for Neo we provide out-of-the-box support with only servlet based applications and not spring based applications.

Do You Support Reactive Spring Technology, e.g. Webflux?

The SAP Cloud SDK for Java currently is not fully compatible with the Reactive Spring Technology Stack. Most importantly, the Multi Tenancy Features are not functional on that stack, because they were designed with servlet based applications in mind.

You can find more details on this Stack Overflow Question.

Is the SAP Cloud SDK for Java affected by the Log4Shell/CVE-2021-44228 Vulnerability?

The SAP Cloud SDK for Java uses SLF4J as its logging framework and actively excludes all other logging frameworks. This exclusion strategy also applies to transitive dependencies. That means you will not find any logging implementations provided or expected by the SAP Cloud SDK for Java. That is why the SAP Cloud SDK for Java itself does not render your application built on it vulnerable to the Log4Shell vulnerability.

However, you should still check that your application or one of its dependencies doesn't include log4j-core on the classpath.

Our SAP BTP CF Archetypes use logback as the logging implementation, the SAP BTP Neo archetype relies on the logger provided by the Neo Platform.

For further reading on this vulnerability have a look at the following (external) links:

• https://www.lunasec.io/docs/blog/log4j-zero-day-mitigation-guide/
• http://slf4j.org/log4shell.html
• https://support.sap.com/content/dam/support/en_us/library/ssp/my-support/trust-center/sap-tc-01-5025.pdf
• https://nvd.nist.gov/vuln/detail/CVE-2021-44228