The new version of the SAP S/4HANA Cloud SDK Java libraries is available since last week. You can update your dependencies to version 2.4.1 and consume the new version from Maven Central.
In this blog post, we will walk you through the highlights of the 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.

SAP TechEd 2018 is approaching quickly! The conference in Las Vegas is only two weeks away, and Barcelona and Bangalore will follow soon after. The SAP S/4HANA Cloud SDK will be well-represented at all three locations with numerous sessions, including hands-on workshops and CodeJams.

Check out the agenda for SDK-related sessions in Las Vegas and Barcelona. Especially make sure to register for hands-on sessions now, as capacity is limited.

Stay tuned for a blog post with more details on the SDK sessions!

Java Libraries: Release Highlights

Consume SOAP APIs Conveniently

The SAP S/4HANA Cloud SDK strives to make consuming APIs of SAP S/4HANA Cloud easy and delightful, most importantly with the Java Virtual Data Model (VDM) for OData services. In addition to OData services, some APIs of SAP S/4HANA Cloud are exposed as SOAP services. There are already open source libraries for consuming SOAP services from Java available. What was missing so far is an easy integration of SOAP service consumption with the capabilities of the SDK, which transparently handles low-level tasks such as retrieving destination configuration for the SAP S/4HANA system to connect to, establishing the connection, possibly via a Cloud Connector to the on-premise network, applying required authentication, and many more.

With version 2.4.1, the SAP S/4HANA Cloud SDK simplifies consuming a SOAP service when using the Apache Axis2 framework. To this end, we introduce the SoapQuery class. With this, you can easily generate a Java representation for the SOAP service in question using Axis2 and couple it with the SAP S/4HANA Cloud SDK to handle the infrastructure tasks of destination retrieval, connectivity, and authentication. That is, your code to call an operation of a SOAP service can be as simple as follows (using Java 8 lambda expressions) and benefit from the capabilities of the SAP S/4HANA Cloud SDK:

new SoapQuery<>(YourAxis2SoapServiceStub.class)
    .execute(soapService -> soapService.callOperation(...))

We have published a separate deep dive on the convenient consumption of SOAP APIs that explains end-to-end the use of the new feature in more detail. Make sure to check out this blog post if you want to consume SOAP APIs of SAP S/4HANA Cloud in your application on SAP Cloud Platform.

Create New OData Entity as Child of Another Entity

The Java VDM for OData services makes it easy, besides other features, to create new entities via OData requests. Some OData services may require that you create an entity as a child of another entity via a navigation property of the parent entity. In other cases, it may be more natural to create an entity by addressing the naviation property of a parententity, for example, when adding an address to an existing business partner.

The Java VDM now allows creating an OData entity as the child of another entity. To leverage this feature, first call the method of the service with the entity to create, then use the method asChildOf on the corresponding fluent helper for the create request. You need to supply the parent entity to asChildOf, as well as the navigation property of the parent entity type to specify the relationship between parent entity and the child entity to be created.

As an example, consider the following code which will create an address as a child of a business partner via the TO_BUSINESS_PARTNER_ADDRESS navigation property of the business partner:

new DefaultBusinessPartnerService()
    .createBusinessPartnerAddress(addressToCreate)
    .asChildOf(parentBusinessPartner, BusinessPartner.TO_BUSINESS_PARTNER_ADDRESS)
    .execute();

As usual with the Java VDM, this approach is type-safe thanks to the Java representation of the OData service. It requires that the OData service in question supports creating the child entity via the navigation property of another entity.

Retrieve Destinations from Subscriber and/or Provider Account

The SAP S/4HANA Cloud SDK relieves developers from menial tasks otherwise required to retrieve the configuration of destinations. You can define destinations that point to downstream services or systems using the SAP Cloud Platform cockpit and easily reference them by name from your code. The SAP S/4HANA Cloud SDK takes care of everything else, from retrieving the configuration to executing necessary authentication flows as defined by the configuration.

In a multi-tenant software-as-a-service (SaaS) application, there may be different kinds of downstream destinations, some of which are tenant-specific and defined by customers subscribed to the application, and others defined by the application provider. For example, each customer will define his own destination configuration to connect to his SAP S/4HANA system, while a microservice may use the destination service to define a common destination to connect to another microservice. In the latter case, it may be highly undesired if customers could overwrite the application-internal destination, while this is necessary in the first case.

With version 2.4.1, the SDK gives consumers more fine-granular control over where to look for destinations. One differentiates between the provider account, which hosts the application, and subscriber accounts for each tenant (customer) of the application. The SDK now allows developers to specify per destination whether the configuration shall be retrieved always and exclusively from the provider account or from the subscriber account. It is also possible to choose to fallback to the provider in case the current subscriber tenant does not define (that is, overrides) the destination.

To this end, we have enhanced the DestinationAccessor class by the static method setRetrievalStrategy. For a given destination name, you can set the strategy for loading the destination to any of the above mentioned strategies, which are reflected by DestinationRetrievalStrategy. For example, to prevent subscribers from overriding a destination you would set its strategy to DestinationRetrievalStrategy.ALWAYS_PROVIDER.

The strategy is not being persisted. You need to ensure that you set the strategy prior to any attempt to resolve the destination, for example, during application startup. If no specific strategy has been defined for a destination, the default of the current environment of SAP Cloud Platform will be used. On the Neo environment, this means subscriber then provider (fallback), and on Cloud Foundry always subscriber. Use getRetrievalStrategy to determine the currently defined strategy for a destination.

Further Improvements

The Java VDM for OData services now handles optimistic concurrency control also for delete requests and queries. Previously (since version 1.10.0), the ETag version identifier used for concurrency control in OData services was handled automatically only in case of retrieving an entity by key and during update requests. Now, when retrieving many entities with a OData query request that returns the ETag value for each entity, the version identifier will be stored for all retrieved entities. Delete requests will automatically include the ETag value from the entity to be deleted, if available, in the If-Match header of the request.

Version 2.4.1 introduces the DestinationHeaderProvider interface that allows to pass additional Header objects to any call of the respective destination. Interface implementations are automatically discovered by the Java service loader.

We have enhanced all Cloud Foundry archetypes to use the timeout attribute in manifest.yml. The default values for newly generated projects is a deployment timeout of 5 minutes in order to avoid issues with larger deployments that may take longer starting, especially if available CPU is restricted.

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.4.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.4.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.4.1.

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