SAP S/4HANA Cloud SDK: Version 2.3.1 is Available

[HenningH]

The new version of the SAP S/4HANA Cloud SDK Java libraries is available since today. You can update your dependencies to version 2.3.1 and consume the new version from Maven Central.
In this blog post, we will walk you through the highlights of this release. For a complete overview, visit our release notes for the Java libraries. The release notes also include the change log of all our releases so far.
At the end of the article, you will find a set of instructions on how to update to the new version.

Java Libraries: Release Highlights

Update of Java VDM to SAP S/4HANA Cloud 1808

Recently, SAP released SAP S/4HANA Cloud 1808.

With version 2.3.1, the SAP S/4HANA Cloud SDK updates the Java VDM (VDM) for OData services of SAP S/4HANA Cloud 1808 to support all newly released or updated OData services of an SAP S/4HANA Cloud 1808 system. As explained in the blog post about the VDM itself, the VDM greatly simplifies reading and writing data from an SAP S/4HANA system in your Java code.

You can use the SDK to connect to all OData services listed in the SAP API Business Hub for SAP S/4HANA Cloud. As usual, the Java representations of all OData services are available from the package com.sap.cloud.sdk.s4hana.datamodel.odata.services.
Furthermore, there are selected BAPIs available that can be accessed via the Java VDM for BAPIs, which we have also updated for SAP S/4HANA Cloud 1808.

Executing OData requests in a Resilient Manner

Applications that access SAP S/4HANA systems or other downstream services are by definition distributed systems. In a distributed system, developers need to take special precautions to guard against failures when accessing those dependencies to build a resilient, fault-tolerant applications.
Making it easy to build resilient applications has always been an important goal of the SAP S/4HANA Cloud SDK, for example, by providing the ErpCommand class and other classes which make constructing a Hystrix command easy. For more details about the concept of resilience and the support available in the SDK so far, consult this tutorial.

Now, with version 2.3.1, we make it even easier to execute OData requests using the Java VDM in a resilient manner, automatically wrapped in a Hystrix command. Simply use the new method asResilientCommand available from any fluent helper of the Java VDM. This method returns an instance of a pre-configured Hystrix command that you can use like any Hystrix command to perform a resilient call, for example, by executing the command synchronously or asynchronously. This is supported for any OData operation of SAP S/4HANA.

To execute an OData request in a resilient manner using the new method, instead of calling, for example, service.getAllBusinessPartner().execute(), call service.getAllBusinessPartner().asResilientCommand().execute(). That is, build up the OData request as you are used to with the Java VDM, and then transfer it into a command by calling asResilientCommand before executing it. A more complete example could look as follows. Note that we can supply a fallback as a lambda function (which receives the exception that occured during execution as parameter).

// construct OData request as usual

new DefaultBusinessPartnerService()

    .getAllBusinessPartner()

    .filter(...).select(...)

    // wrap in Hystrix command and specify a fallback

    .asResilientCommand()

    .withFallback( (e) -> Collections.emptyList() ) // ignoring execution exception "e"

    // execute the Hystrix command (or queue / observe it)

    .execute();

The convenient way to resilient execution of Java VDM requests uses under the hood the new class ODataRequestCommand, which represents a sensible-default implementation of ErpCommand for OData requests.

Further Improvements

We fixed the issue that .gitignore files had not been correctly generated by archetypes. Now, each project generated by one of our archetypes (see this tutorial for an example) includes a .gitignore file in the root folder with sensible defaults. Most importantly, credential files will be ignored to avoid accidentally committing them to Git. Please ensure that you have never committed those to your Git repository.

The application programming model for SAP Cloud Platform makes provisioning OData services easy, besides other features. Projects that want to use both, the OData consumption capabilities or other features of the SAP S/4HANA Cloud SDK and the libraries for the OData provisioning capabilities, will now find it easier to use both together with consistent versions. The SAP S/4HANA Cloud SDK manages the version of the OData v2 provisioning libraries of the application programming model in the BOM of the SAP S/4HANA Cloud SDK. This allows to quickly use the corresponding libraries for providing OData v2 services by simply adding required dependencies to the dependencies of a project; consistent versions will automatically be ensured thanks to the BOM of the SAP S/4HANA Cloud SDK. In particular, we manage the following dependencies required for provisioning OData v2 or v4 services: com.sap.cloud.servicesdk.prov:api (v2, v4), com.sap.cloud.servicesdk.prov:odata2.web, com.sap.cloud.servicesdk.prov:odata2.xsa, com.sap.cloud.servicesdk.prov:odatav2-hybrid, com.sap.cloud.servicesdk.prov:odatav2-prov, and com.sap.cloud.servicesdk.prov:odatav4.

At the same time, we have upgraded the dependencies relevant for the application programming model for SAP Cloud Platform from version 1.18.0 to 1.19.0.

When errors, for example, regarding null handling and type conversion, occur during the parsing of OData payloads in the VDM, we now throw unchecked exceptions. Previously, checked exceptions would be thrown. In cases where the errors cannot be recovered from, an ODataPayloadParsingFailedException will be thrown, which is a RuntimeException.

Several further improvements are listed in the full release notes.

How to Update the Java Libraries

To update the version of the SAP S/4HANA Cloud SDK Java libraries used in an existing project, proceed as follows:

• Open the pom.xml file in the root folder of your project.


• Locate the dependency management section and therein the sdk-bom dependency.


• Update the version of that dependency to 2.3.1.

With this, you are already done thanks to the "bill of material" (BOM) approach. Your dependency should look like this:

<dependencyManagement>

    <dependencies>

        <dependency>

            <groupId>com.sap.cloud.s4hana</groupId>

            <artifactId>sdk-bom</artifactId>

            <version>2.3.1</version>

            <type>pom</type>

            <scope>import</scope>

        </dependency>

    </dependencies>

    <!-- possibly further managed dependencies ... -->

</dependencyManagement>

You can now recompile your project (be aware of the compatibility notes, though) and leverage the new features of the SAP S/4HANA Cloud SDK in version 2.3.1.

Of course, you can also generate a new project that uses version 2.3.1 from the start by running the Maven archetypes for Neo or Cloud Foundry with -DarchetypeVersion=2.3.1 (or RELEASE).