SAP S/4HANA Cloud SDK: Version 1.10.0 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 1.10.0 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.

Please note: version 1.10.0 is planned to be the last version of the SAP S/4HANA Cloud SDK Java libraries that supports Java 7. Future releases will only support Java 8.

Java Libraries: Release Highlights

Release of Virtual Data Model (VDM) generator

This version releases the VDM generator for OData services for productive use. The VDM generator is thus no longer considered experimental.

The VDM generator gives you the option to quickly generate your own VDM for your custom OData services. As you may know from the corresponding blog post, the SAP S/4HANA Cloud SDK provides a Java virtual data model for OData services of SAP S/4HANA Cloud. The VDM allows to easily access SAP S/4HANA Cloud APIs in a fluent and type-safe manner. The VDM delivered with the SAP S/4HANA Cloud SDK gives easy, fluent, and type-safe access to the public API of SAP S/4HANA Cloud (and SAP S/4HANA) published in the SAP API Business Hub. With the VDM generator, you can leverage these benefits also for any other OData v2 service. These custom services can, for example, be based on custom business objects or custom CDS views, created with the in-app extensibility capabilities of an SAP S/4HANA Cloud system. See this blog post for a detailed walk-through of using the generator.

The productive release of the VDM generator requires only the metadata document for each OData services for which to generate a VDM. You can simply download the metadata document as an EDMX file from your OData service by appending /$metadata to the URL. In contrast to the experimental release, Swagger files are now optional and can be used to describe the service further, but are not required. Store the EDMX files with file extension .edmx in one folder that we will use as input for the generator.

Afterwards, to run the generator, follow these simple steps:

1. Download the command line interface of the generator, rename it to odata-generator-cli.jar, and put it in a folder of your choice. Note: please check for the latest version of the generator on Maven Central.


2. Run java -jar odata-generator-cli.jar -h on the command line within that folder to see the available options of the command line interface.


3. Run the generator as follows: java -jar odata-generator.jar -i /path/to/input/folder -o /path/to/output/folder.
   You can also specify the parameter -p my.package.name to choose the package name.


4. Wait for the generator to finish with a success message. This will only take one or two seconds.


5. Put the generated Java source files from the output folder into your project that is using the SAP S/4HANA Cloud SDK so that they are picked up by Java. For example, move them to the application/src/main/java folder.


6. Finally, you need to add Lombok to the dependencies of your project (and, if needed, to your IDE). Add the following to the dependencies section of your application/pom.xml file:
   

   <dependency>
   
       <groupId>org.projectlombok</groupId>
   
       <artifactId>lombok</artifactId>
   
       <scope>provided</scope>
   
   </dependency>​

   
   

Now, you can use the generated classes in your Java code to access your custom OData service with the same simplicity, type-safety, and ease-of-use that you know from the VDM for the public API of SAP S/4HANA Cloud.

The above is just one possible option to use the generator. There is also a Maven plugin com.sap.cloud.s4hana.datamodel:odata-generator-maven-plugin available to generate the VDM as part of the Maven lifecycle. Furthermore, you can call the generator from any Java application via the DataModelGenerator builder class.

In comparison to the experimental release of the VDM generator, the productive release in this version 1.10.0 brings many improvements. The previously required Swagger JSON file that describes an OData service in more detail is now optional.
The generator will by default use the label from the OData metadata (sap:label attribute) to derive the VDM name of entities and their properties for more speaking names. You can use the old strategy to use the name instead with the corresponding command line interface (CLI) option --use-odata-names (if you are using the Maven plugin, add the following parameter to the plugin configuration: <nameSource>NAME</nameSource>). This may be required, for example, when labels would lead to duplicate names.
You can finetune the names of generated Java classes and properties by supplying a custom NamingStrategy to define the mapping of metadata names and labels to Java identifiers. Supply the fully qualified name of your class implementing this interface via the parameter --name-strategy-class (CLI) or namingStrategy (Maven plugin) and supply the class on the classpath when running the generator.

Improvements to Update Requests with the VDM

The VDM makes it easy to call any operation of an OData service. This version of the SAP S/4HANA Cloud SDK brings several improvements for update requests made with the VDM.

Update using PATCH Requests

All update requests with the VDM are now made using the HTTP PATCH request method. Patch requests in principle only require sending changed fields. In version 1.10.0, the VDM for this purpose sends all fields of the entity that are not null (i.e., have not been initialized). This strategy allows developers to control the fields that are being sent by constructing an entity that only contains those fields. We plan to improve the update handling in the future to make it easier to send update requests.

Optimistic Concurrency Control

The VDM now supports optimistic concurrency control for update requests. The OData v2 specification uses ETags for optimistic concurrency control. The VDM transparently retrieves the ETag version identifier during read-by-key requests such as getting a physical inventory item and supplies it as If-Match header during update requests such as update physical inventory item. The OData service will only execute the update request if the version identifier is still the same as given in the header.
You can force overwrites (if the OData service supports it) by telling the update request to ignore the version identifier. You can manually get and set the ETag version identifier manually on all entities.

Further Improvements

Similarly to other Cloud Platform abstractions provided by the SAP S/4HANA Cloud SDK, we introduced an AuthTokenAcccessor to transparently access the current authorization token on SAP Cloud Platform Cloud Foundry.

We fixed an issue where destinations on SAP Cloud Platform Cloud Foundry were not retrieved correctly in a multi-tenant setup.

Several further improvements are listed in the full release notes.

How to Update: 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 1.10.0.

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>1.10.0</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 1.10.0.

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