New Versions of SAP Cloud SDK: 3.7.0 for Java and 1.12.0 for JavaScript

[HenningH]

We have released new versions of the SAP Cloud SDK. In detail, the following components are now available in new versions:

• Java libraries in version 3.7.0


• JavaScript libraries in version 1.12.0

In this blog post, we will walk you through the highlights of these releases. For a complete overview, visit our release notes for the Java libraries and for the JavaScript 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 versions.

Java Libraries: Release Highlights 3.7.0

You can update your dependencies of the SAP Cloud SDK for Java to version 3.7.0 and consume the new version from Maven Central.

Improvements to resilience API

Version 3.7.0 brings several improvements to the API for executing code in a resilient manner (for which ResilienceDecorator is the main entry point).

The CircuitBreakerConfiguration now allows to explicitly specify buffer sizes for the circuit breaker. The buffer sizes control how many sample executions the circuit breaker monitors before calculating the failure rate and potentially opening the circuit breaker because of too many failures. Use CircuitBreakerConfiguration.closedBufferSize and CircuitBreakerConfiguration.halfOpenBufferSize to provide custom values for the respective buffer size.

At the same time, we have also adjusted the default buffer sizes for circuit breakers in CircuitBreakerConfiguration from 100 to 10 for transitioning from CLOSED to OPEN state and from 10 to 5 for transitioning from HALF-OPEN back to CLOSED state.

A bit of additional background: the circuit breaker state transitions from CLOSED to OPEN when a threshold on the failure rate is exceeded (after collecting as many samples as specified by closedBufferSize), from OPEN to HALF-OPEN after a wait duration has passed, and from HALF-OPEN to CLOSED when a small number of consecutive attempts (halfOpenBufferSize) succeed.

As an additional improvement to the resilience API, version 3.7.0 allows to disable individual resilience properties (such as bulkhead or circuit breaker) when initializing a resilience configuration. To this end, the invididual configuration classes provide methods for instantiating a disabled configuration. In detail, we have introduced the following factory methods, in addition to the previously existing ones that instantiate an enabled configuration: CircuitBreakerConfiguration.disabled(), TimeLimiterConfiguration.disabled(), BulkheadConfiguration.disabled(), RetryConfiguration.disabled(), and CacheConfiguration.disabled().

Furthermore, we provide a new method ResilienceConfiguration.empty to initialize a new resilience configuration with all properties being disabled by default, so that you can adapt all properties to your needs without relying on defaults.

Improvements to caching API

The caching API provided as a configuration option in conjunction with the resilience API now allows clearing the cache for future requests when using a ResilienceConfiguration with a CacheConfiguration in place. Use ResilienceDecorator.invalidateCache(configuration) to clear the cache associated with a specific resilience configuration.

You can now explicitly specify the cache expiration strategy for a CacheConfiguration. The expiration strategy determines the point in the lifecycle of a cache entry that is used as basis for the expiration duration, for example, starting from when a cache entry has been created. Use withExpirationStrategy(strategy) on the builder for a CacheConfiguration with the enum constants available from CacheExpirationStrategy. WHEN_LAST_MODIFIED remains the default value for the expiration strategy.

Further improvements

The OData VDM generator now allows to specify a copyright header for generated files by supplying the parameter --copyright-header your-custom-header (or the corresponding Maven plugin parameter). By default, no header is generated.

Several further improvements are listed in the full release notes.

JavaScript Libraries: Release Highlights 1.12.0

The JavaScript libraries of the SAP Cloud SDK are now available in version 1.12.0.

Open source Command Line Interface (CLI)

We have released a preview version of the all-new open source SAP Cloud SDK Command Line Interface (CLI) @Sap-cloud-sdk/cli on the central registry npmjs.com. The CLI makes it easy to add the SAP Cloud SDK for JavaScript to an existing project and simplifies several other tasks when building applications on SAP Cloud Platform. Install the CLI via npm (npm install @Sap-cloud-sdk/cli). For more information on how to use the CLI, take a look at the Readme or call sap-cloud-sdk --help after installing.

The CLI is available as open source under Apache License 2.0 from the github.com repository. Contributions are welcome as pull requests.

Improved and configurable logging

To make filtering logs in Kibana and on SAP Cloud Platform easier, version 1.12.0 adds an SDK-specific logger based on winston. The logger issues the SDK module as an additional field suitable for filtering. You can configure the log level per module of the SDK also from outside by getting a logger for a specific module and adapting the returned winston logger. For example, the following code snippet changes the log level of the destination accessor of the SDK:

import { createLogger } from '@sap/cloud-sdk-util';

const logger = createLogger('destination');

logger.level = 'error';

The SDK now also produces better formatted logs locally. The new logger is used consistently throughout the SDK. Additionally, you can use it for application code as well.

Further improvements

Version 1.12.0 supports the handling of destinations with OAuth2SAMLBearerAssertion authentication type that include a property SystemUser. The system user will be used instead of the currently logged in user to retrieve an access token to the destination. That is, no principal propagation takes place. As a consequence, no user JWT is required.

As another improvement, the SDK now uses correct type DestinationOptions in execute method of OData VDM request builders. The type used previously was overly restrictive, which prevented passing of valid objects like a selectionStrategy, even though the code actually handles it.

As usual, the full release notes contain a list of all improvements in this release.

How to Update

Java libraries

To update the version of the SAP 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 3.7.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.sdk</groupId>

            <artifactId>sdk-bom</artifactId>

            <version>3.7.0</version>

            <type>pom</type>

            <scope>import</scope>

        </dependency>

    </dependencies>

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

</dependencyManagement>

If you update from a version prior to 3.0.0, have a look at our migration guide.

If you are using the SAP 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 Cloud SDK in version 3.7.0.

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

JavaScript libraries

To update the version of the SAP Cloud SDK JavaScript libraries used in an existing project, use the command npm update in the root folder of your module. Note that this will also update other modules, unless you explicitly specify which packages to update. If you want to check beforehand what will change, use npm outdated.