Today, we have released version 3.0.0 of the SAP Cloud SDK for Java. As you can see from the version number, this is a new major version, corresponding with many changes, improvements, and new functions. In this blog post, I want to walk you through the motivation for the new major version, elaborate on what has changed, and answer any further questions you may have. We have published a separate technical guide on how to migrate. I also will not go into the details on new functionality, which you can find in the usual relase blog post.
Before I dive deeper into version 3 for Java, a brief recap of what the SAP Cloud SDK is about.
The SAP Cloud SDK, launched in May 2019 as an evolution of the SAP S/4HANA Cloud SDK, is a consistent toolset for interacting with SAP solutions when developing cloud-native extension applications. It allows you to leverage SAP solutions, not limited to, but including SAP S/4HANA Cloud, SAP SuccessFactors, SAP C/4HANA, and others, in your Cloud-native application and quickly fulfil business requirements. It consists of libraries for Java, for JavaScript, and for continuous delivery.
At the time of the launch of the SAP Cloud SDK, the Java SDK had already been available as SAP S/4HANA Cloud SDK for more than one-and-a-half years. We deliberately did not rename any technical artifacts at launch to ensure smooth adoption.
So why a new major version now. Over the years, any artifact like the SDK evolves, because decisions of the past no longer apply (like names specific to SAP S/4HANA), because the environment has changed (new approaches to connect to downstream systems like SAP Cloud Platform Extension Factory), or because - let's face it - decisions you would take different in hindsight. A new major version is an opportunity to tackle those changes - changing things which a strict semantic versioning of the Java API that we apply only permits when increasing the major version, in this case, from 2 to 3.
When setting out to develop version 3, we agreed on one major vision: improving the experience of a developer when using the SDK towards "it just works". And that means it works out-of-the-box and in any scenario. For example, also in situations without an HTTP request a developer should not be obliged to jump through hoops to get the SDK working. This north star guided the major improvements outlined below.
In addition, we also took the opportunity to remove deprecated parts and change smaller things that should be done differently. We renamed our Maven artifacts, putting them under a common namespace
From the full list of changes listed in the release notes, here are the highlights.
The concept of destinations has been revamped significantly to evolve destinations towards a general, lightweight concept for dealing with target systems and make it less dependent on a concrete platform. All destinations can now be instantiated explicitly, making tests much easier, and have to be passed explicitly to decouple the resolving of a destination from the actual call, for example, in the OData VDM.
The new concept is based on several basic interfaces (such as
Resilience with
Before version 3, the SAP Cloud SDK for Java used the Hystrix library for implementing important resilient capabilities such as circuit breakers, bulkheads, and time limiters, to which the SDK added multi-tenant capabilities. Hystrix is now in maintenance mode, so it was time to look for a new, modern resilience framework, which we found with resilience4j.
At the same time, drawing from past experiences, we decided to introduce a layer of abstraction into the SDK, by decoupling the tenant-aware implementation of resilient behavior from a concrete framework. To this end, version 3 introduces generic functional-style adapters in the package
To make any code resilient, use
In this context, we also switched from Guava to allowing the use of any JSR-107 (JCache) compliant library for caching.
As mentioned, one key design goal of version 3 was making the use of the SDK outside of standard request-response scenarios easier. Before, the SDK often relied on the assumption of running in a Servlet container and being triggered by a request. You had to use specific mechanisms to instantiate a context. This cannot be avoided at all places to be able to set up a context to operate in, but now got much easier with version 3.
For one, the SDK is now more lenient and considers the case that now request is available as more of the norm than out of the ordinary. When required, it got much easier to set up a
This is just a high-level overview, much more can be learned from the migration guide, release blog, and release notes. Please note that we are in the process of updating existing tutorials and deep dives.
Our migration guide has you covered. Most of the steps are rather of a technical nature and can be applied by following the guide carefully.
Assuming a well-tested application and when following our migration guide, a couple of hours should be sufficient for a moderately sized application like our business partner address manager from the book Extending SAP S/4HANA. This may vary depending on size and complexity of the application, but you do not need to expect a large scale migration.
Update (2020): version 2.x no longer receives any updates, you should switch to version 3.x if you want to continue using the SDK.
Yes, for the immediate future, we plan to still make critical bug fixes and updates to the VDM for SAP S/4HANA Cloud available in maintenance releases of version 2.x. We will communicate a definite end-of-maintenance for version 2.x in the future. Please be aware that this is no commitment beyond what the SAP Developer License states.
Before I dive deeper into version 3 for Java, a brief recap of what the SAP Cloud SDK is about.
SAP Cloud SDK
The SAP Cloud SDK, launched in May 2019 as an evolution of the SAP S/4HANA Cloud SDK, is a consistent toolset for interacting with SAP solutions when developing cloud-native extension applications. It allows you to leverage SAP solutions, not limited to, but including SAP S/4HANA Cloud, SAP SuccessFactors, SAP C/4HANA, and others, in your Cloud-native application and quickly fulfil business requirements. It consists of libraries for Java, for JavaScript, and for continuous delivery.
At the time of the launch of the SAP Cloud SDK, the Java SDK had already been available as SAP S/4HANA Cloud SDK for more than one-and-a-half years. We deliberately did not rename any technical artifacts at launch to ensure smooth adoption.
Why a New Major Version?
So why a new major version now. Over the years, any artifact like the SDK evolves, because decisions of the past no longer apply (like names specific to SAP S/4HANA), because the environment has changed (new approaches to connect to downstream systems like SAP Cloud Platform Extension Factory), or because - let's face it - decisions you would take different in hindsight. A new major version is an opportunity to tackle those changes - changing things which a strict semantic versioning of the Java API that we apply only permits when increasing the major version, in this case, from 2 to 3.
When setting out to develop version 3, we agreed on one major vision: improving the experience of a developer when using the SDK towards "it just works". And that means it works out-of-the-box and in any scenario. For example, also in situations without an HTTP request a developer should not be obliged to jump through hoops to get the SDK working. This north star guided the major improvements outlined below.
In addition, we also took the opportunity to remove deprecated parts and change smaller things that should be done differently. We renamed our Maven artifacts, putting them under a common namespace
com.sap.cloud.sdk. This makes the naming clearer, as the term s4hana is going forward only used for functionality specific to SAP S/4HANA. In the same spirit, we removed ERP-specific terminology like the ErpConfigContext and ErpQueryEndpoint. We unified the API at several places and now use the functional Vavr library throughout the API.What did change?
From the full list of changes listed in the release notes, here are the highlights.
New destination concept
The concept of destinations has been revamped significantly to evolve destinations towards a general, lightweight concept for dealing with target systems and make it less dependent on a concrete platform. All destinations can now be instantiated explicitly, making tests much easier, and have to be passed explicitly to decouple the resolving of a destination from the actual call, for example, in the OData VDM.
The new concept is based on several basic interfaces (such as
Destination, HttpDestination and RfcDestination), default and platform-specific implementations (such as DefaultHttpDestination, ScpCfHttpDestination, or ScpNeoHttpDestination), and decorators for dynamically translating between the different types.Resilience with resilience4j
Before version 3, the SAP Cloud SDK for Java used the Hystrix library for implementing important resilient capabilities such as circuit breakers, bulkheads, and time limiters, to which the SDK added multi-tenant capabilities. Hystrix is now in maintenance mode, so it was time to look for a new, modern resilience framework, which we found with resilience4j.
At the same time, drawing from past experiences, we decided to introduce a layer of abstraction into the SDK, by decoupling the tenant-aware implementation of resilient behavior from a concrete framework. To this end, version 3 introduces generic functional-style adapters in the package
com.sap.cloud.sdk.cloudplatform.resilience and provides a default implementation of resilience using resilience4j as underlying library.To make any code resilient, use
ResilienceDecorator as the entry point for wrapping the code (callabe or supplier) with resilient behavior. The configuration of circuit breakers etc. happens with an instance of ResilienceConfiguration.In this context, we also switched from Guava to allowing the use of any JSR-107 (JCache) compliant library for caching.
Leveraging the SDK outside of requests
As mentioned, one key design goal of version 3 was making the use of the SDK outside of standard request-response scenarios easier. Before, the SDK often relied on the assumption of running in a Servlet container and being triggered by a request. You had to use specific mechanisms to instantiate a context. This cannot be avoided at all places to be able to set up a context to operate in, but now got much easier with version 3.
For one, the SDK is now more lenient and considers the case that now request is available as more of the norm than out of the ordinary. When required, it got much easier to set up a
ThreadContext and running code on-behalf-of a given tenant or principal, as explained in the release blog.This is just a high-level overview, much more can be learned from the migration guide, release blog, and release notes. Please note that we are in the process of updating existing tutorials and deep dives.
Q & A
How can I migrate?
Our migration guide has you covered. Most of the steps are rather of a technical nature and can be applied by following the guide carefully.
Which migration effort should I expect?
Assuming a well-tested application and when following our migration guide, a couple of hours should be sufficient for a moderately sized application like our business partner address manager from the book Extending SAP S/4HANA. This may vary depending on size and complexity of the application, but you do not need to expect a large scale migration.
Will you still provide support for version 2.x?
Update (2020): version 2.x no longer receives any updates, you should switch to version 3.x if you want to continue using the SDK.
- SAP Managed Tags:
