We have released the new version 2.14.0 of the SAP S/4HANA Cloud SDK for Java.

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.

SAPPHIRE NOW 2019 is drawing closer and will start in less than four weeks from now. You can meet us there from May 7 to 9 at the topic station SAP S/4HANA Cloud Integration and Extension.
Already one day earlier, Monday, May 6, the SAP Global Partner Summit 2019 takes place. There, we will have dedicated sessions at the booth Deploy and extend SAP S/4HANA Cloud. For more details on our presence at the summit, refer to this blog post.

Java Libraries: Release Highlights 2.14.0

You can update your dependencies of the SAP S/4HANA Cloud SDK for Java to version 2.14.0 and consume the new version from Maven Central.

Message VDM: standalone message converters

We have improved the experimental Message virtual data model (VDM) that was first released with version 2.11.1 to make it easier to leverage the functionality for converting plain messages into typed messages representing business events of SAP S/4HANA Cloud.

To this end, version 2.14.0 adds new standalone message converter classes that can convert payload strings or JMS messages to Message VDM messages. To convert JMS messages, instantiate a JmsMessagingVdmConverter and then call the fromMessage method.

new JmsMessagingVdmConverter().fromJmsMessage(jmsMessage)

The mapping of message types to corresponding message factory class names is done via the MessageFactoryMapper interface. With VdmMessages, we provide a default implementation of of this interface for currently supported message types of SAP S/4HANA Cloud, which is also used out-of-the-box by the above mentioned converter for JMS messages.
To convert plain string-typed message payloads, instantiate a MessagingVdmConverter with the desired MessageFactoryMappers and call the method fromMessage.

Access current principal

With the UserAccessor, we already gave straightforward access to the current user. On Cloud Foundry, this did not cover cases where your app was called via client credentials, as Cloud Foundry differentiates between users and clients depending on the grant_type used by the JWT authentication token.

To similarly access information about the current principal (which comprises both user or client), version 2.14.0 provides a PrincipalAccessor. The returned Principal object includes the identifier of the principal, which is either the user_name or client_id, depending on the current grant_type, as well as authorization information. In the Neo environment of SAP Cloud Platform, the principal is equivalent to the user.

For most use cases, we recommend to use the new PrincipalAccessor instead of the more restricted UserAccessor, which is only recommended if you need to ensure that your app was called by a proper user.

Further improvements

We now support using default values also for the audiences of the JWT created when running operations on behalf of specific tenants. The new method onBehalfOfTenant( @Nonnull String tenantId ) of JwtBasedRequestContextExecutor uses default values for issuerUrl and audiences, so that you only need to supply the tenant identifier. The list of audiences will be initialized with the own application name as taken from the XSUAA service binding context. At the same time, we replace the previously existing method with the more specific method onBehalfOfTenant(@Nonnull String tenantId, @Nonnull String issuerUrl, @Nonnull Collection audiences ) for full customization of these values.

Version 2.14.0 fixes an issue on Cloud Foundry and Neo where accessing a destination with a valid URL led to an URL parsing exception if at least one other destination returned by the destination service had an invalid URL.

We have also fixed an issue with incorrect serialization of negative numbers when using RFC queries via JCo.

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 2.14.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>2.14.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
    <!-- possibly further managed dependencies ... -->
</dependencyManagement>

If you are using the SAP S/4HANA Cloud SDK in a project of the SAP Cloud Application Programming Model, replace sdk-bom with sdk-modules-bom to only update the version of SDK modules, not further dependencies.
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.14.0.

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