Disclaimer: This blog post is only applicable for the SAP Cloud SDK version of at most 2.19.2. We plan to continuously migrate these blog posts into our List of Tutorials. Feel free to check out our updated Tutorials on the SAP Cloud SDK.

With the release of version 2.0.0 of the SAP S/4HANA Cloud SDK, along with dropping support for Java 7, we were able to incorporate several improvements and add some great new features to the Java libraries of the SDK based on your feedback! Along with the modernization of the technology stack, we took the chance to clean up our code base and remove obsolete and unwanted functionality that – in a few cases – required breaking changes to our API.

In order to provide you a smooth transition to our latest release, this migration guide aims to help you in moving your project to version 2.0.0 of the SAP S/4HANA Cloud SDK. In particular, this blog post will outline the relevant changes in detail and offer code examples that demonstrate the steps that are necessary for a successful and seamless migration.

For a general overview of the latest changes, please refer to our release notes.

Leverage Java 8

Move from Guava’s to Java’s Functional Primitives

In addition Replace Guava’s functional primitives like FluentIterable, Optional, Function, Predicate and Supplier with corresponding native Java 8 types. This usually means that you have to adjust the existing Guava imports and replace them with their Java 8 counterparts. For instance, differences between Guava’s and Java’s Optional are described in the Guava Javadoc. An example for the required changes is depicted below.

Previously

import com.google.common.base.Optional;
...

ProxyConfiguration proxyConfiguration = 
    DestinationAccessor.getDestination("dest")
        .getProxyConfiguration()
        .orNull();

Now

import java.util.Optional;
...

ProxyConfiguration proxyConfiguration = 
    DestinationAccessor.getDestination("dest")
        .getProxyConfiguration()
        .orElse(null);

The interface Executable no longer inherits from Callable and is now annotated with @FunctionalInterface. RequestContextExecutor has been adjusted accordingly to accept both Callable and Executable as Lambda expressions. This enables a simpler use of this class:

Previously

new RequestContextExecutor().execute(new Executable() {
    @Override
    public void execute() throws Exception {
        ...
    }
);

Now

new RequestContextExecutor().execute(() -> {
   ...
});

Move from Joda-Time to Java’s Date and Time

With version 2.0.0, the SDK replaces the use of Joda-Time as well as the legacy Java 7 date and time classes with the corresponding  java.time classes of Java 8. In particular, in the Java virtual data model (VDM), the deprecated Calendar type has been replaced with LocalDateTime, LocalTime, and ZonedDateTime. When adapting your code, you will be able to see the new expected type on the respective entity fields.

Change Obsolete or Unwanted Behavior

CacheKey

The potentially risky best-effort cache keys and HystrixUtil command key methods have been removed. The CachingCommand now uses CacheKey.ofTenantAndUserIsolation() by default. While the best-effort isolation allowed to generically construct a cache key with the highest possible level of isolation, it beared the potential risk of an unexpected cache isolation, for example due to a security configuration mistake. Therefore, we decided to require an explicit specification of the expected isolation instead. If the requested isolation level cannot be provided, an exception is thrown instead of silently reverting to a weaker isolation.

Previously

// weaker than expected isolation possible at runtime
CacheKey cacheKey = CacheKey.newBestEffortIsolatedKey();

Now

 // explicitly specify and enforce isolation at runtime
CacheKey cacheKey = CacheKey.ofTenantAndUserIsolation();

Note: As a consequence of removing the best-effort cache key, a tenant is already required when using the destination service on Cloud Foundry. If you are in an environment without security being configured, set the ALLOW_MOCKED_AUTH_HEADERenvironment variable to true to mock a tenant and still use the destination service (without principal propagation).

MockUtil

In previous versions, the SDK used to implicitly mock an audit log with calling MockUtil.mockDefaults(). Since this represented a deviation of behavior between tests, a local container, and code that runs on SAP Cloud Platform, the audit log is no longer mocked by this method. In contrast, if you need to mock an audit log, you now have to explicitly call MockUtil.mockAuditLog().

Previously

private static final MockUtil mockUtil = new MockUtil();

@Test
public void test()
{
    mockUtil.mockDefaults(); // implicitly mocked an audit log
}

Now

private static final MockUtil mockUtil = new MockUtil();

@Test
public void test()
{
    mockUtil.mockDefaults(); // no longer mocks an audit log
    mockUtil.mockAuditLog(); // mock the audit log explicitly now
}

Clean up API of SAP S/4HANA Cloud SDK

Cloud Platform Abstractions

Within version 2.0.0, the APIs of the Cloud Platform abstractions have been improved with accessor methods returning Optionals in TenantAccessor, UserAccessor, and SecretStoreAccessor. For example, in order to retrieve the current tenant, previous versions only offered a method getCurrentTenant() that could throw a TenantNotAvailableException. Since the flow of an application can depend on the availability of a tenant, the previous APIs required developers to rely on the anti-pattern of using exceptions for controlling the code flow. Therefore, the SDK now offers new methods such as getCurrentTenantIfAvailable() which avoid the use of an exception here.

Previously

Tenant getCurrentTenant()
    throws TenantNotAvailableException,
        TenantAccessException;

Now

Optional<Tenant> getCurrentTenantIfAvailable()
    throws TenantAccessException;
    
Tenant getCurrentTenant()
    throws TenantNotAvailableException,
        TenantAccessException;

ErpConfigContext and ErpEndpoint

For historic reasons, previous versions of the SDK offered the class ErpEndpoint as well ErpConfigContext. Since both classes eventually turned out to be very similar, the purpose and use of both classes became confusing for developers. In particular, since an ErpEndpoint always had to be constructed from a given ErpConfigContext, developers often had to wrap an ErpConfigContext into an ErpEndpoint without an obvious reason. Therefore, we decided to only offer ErpConfigContext to represent the context for transparently connecting to SAP S/4HANA systems via different protocols.

Previously

new DefaultBusinessPartnerService()
    .getAllBusinessPartner()
    .execute(new ErpEndpoint(new ErpConfigContext()));

Now

new DefaultBusinessPartnerService()
    .getAllBusinessPartner()
    .execute(new ErpConfigContext());

RequestContext Handling

In previous versions of the SAP S/4HANA Cloud SDK, SDK-internal RequestContextListeners were initialized using ServletContextListeners. The downside of this was that RequestContextListeners would not be initialized when being used within certain test setups or when using another ServletContextListener. Therefore, the SDK-internal RequestContextListener instances are now initialized using the ServiceLoader mechanism, allowing developers to more easily use SDK components within tests and during application startup.

Previously

@WebListener
public class MyServletContextListener implements ServletContextListener
{
    @Override
    public void contextInitialized( ServletContextEvent servletContextEvent )
    {
        // explicitly register RequestContextListeners
        new RequestContextExecutor().withListeners(
            new DestinationsRequestContextListener(),
            new ScpNeoDestinationsRequestContextListener(),
            new TenantRequestContextListener(),
            new UserRequestContextListener()
        ).execute(...);
    }

    ...
}

Now

@WebListener
public class MyServletContextListener implements ServletContextListener
{
    @Override
    public void contextInitialized( ServletContextEvent servletContextEvent )
    {
        new RequestContextExecutor().execute(...);
    }

    ...
}

Furthermore, the method requestContextExecutor() has been removed from the class MockUtil. It is now possible to simply use new RequestContextExecutor() instead.

Previously

private static final MockUtil mockUtil = new MockUtil();

@Test
public void test()
{
    mockUtil.requestContextExecutor().execute(...);
}

Now

@Test
public void test()
{
    new RequestContextExecutor().execute(...);
}

RequestContext now uses a custom class Property to represent a property with a certain value or exception if the value could not be determined.

Previously

Optional<Object> getProperty( String name )
    throws RequestContextPropertyException;

Now

Optional<Property<?>> getProperty( String name )
    throws RequestContextPropertyException;

Boostrap Hystrix on SAP Cloud Platform Neo

Previous versions of the SDK relied on a ServletContextListener to register a Neo-specific concurrency strategy for Hystrix in ScpNeoHystrixBootstrapListener. This is now obsolete since the SDK internally uses the standard Java ServiceLoader mechanism offered by Hystrix to register this strategy.

Previously

@WebListener
public class MyServletContextListener implements ServletContextListener
{
    @Override
    public void contextInitialized( ServletContextEvent servletContextEvent )
    {
        // ensure correct use of HystrixConcurrencyStrategy on Neo
        new ScpNeoHystrixBootstrapListener().bootstrap();

        ...
    }

    ...
}

Now

@WebListener
public class MyServletContextListener implements ServletContextListener
{
    @Override
    public void contextInitialized( ServletContextEvent servletContextEvent )
    {
        // nothing special required here anymore
        ...
    }

    ...
}

Apply Consistent Naming

Constructor Methods

In order to align the naming of constructor methods in the the SAP S/4HANA Cloud SDK with common terminology of Java 8, we simplified CacheKey with unified of constructor methods.

Previously

CacheKey.newGlobalKey();
CacheKey.newTenantIsolatedKey();
CacheKey.newUserIsolatedKey();
CacheKey.newUserOrTenantIsolatedKey();
CacheKey.newTenantIsolatedOrGlobalKey();
CacheKey.newBestEffortIsolatedKey();
// and many more

Now

CacheKey.ofNoIsolation();
CacheKey.ofTenantIsolation();
CacheKey.ofTenantAndUserIsolation();
CacheKey.of(nullableTenantId, nullableUserName);

Furthermore, unified namings have been applied to ConvertedObject with of constructor methods and fixing the misspelled term “convertable”, replacing it with the corrected term “convertible”.

Previously

ConvertedObject.fromConverted(nullableValue);
ConvertedObject.fromNull();
ConvertedObject.notConvertable();

Now

ConvertedObject.of(nullableValue);
ConvertedObject.ofNull();
ConvertedObject.ofNotConvertible();

Virtual Data Model

The methods for retrieving the value of association properties are no longer named getXOrNull. Instead, these methods are now called getXIfPresent to better reflect the return type Optional.

Previously

Optional<Customer> customer = 
    businessPartner.getCustomerOrNull(); // returns Optional, not null

Now

Optional<Customer> customer = businessPartner.getCustomerIfPresent();

Improvements

Mocking of Tenant and User

The SDK now offers the environment variables USE_MOCKED_TENANT and USE_MOCKED_USER for fine-granular control over mocking of the current tenant and user at runtime.

• When these environment variables are set to true, the application will use a mocked tenant (with an empty tenant identifier "") and/or mocked user (with an empty user name "") instead of an actual tenant or user, respectively.
• This should not be used in production, but only for testing purposes. As a consequence, security errors are logged when you use these environment variables.
• The behavior is similar to the ALLOW_MOCKED_AUTH_HEADER environment variable on Cloud Foundry, but in contrast to this variable it works on both Neo and Cloud Foundry and takes precedence over an actual tenant and user.

Mocking of Cloud Platform Abstractions

MockUtil now uses the AuditLog, CloudPlatform, GenericDestination, Destination, RfcDestination, Tenant, User, and SecretStore type of the respective Cloud platform for mocking based on the chosen dependency of Cloud Foundry or Neo. This makes it easier to run the same code within tests, a local container, and on SAP Cloud Platform and allows to more easily test application logic that relies on the environment-specific implementation of a platform abstraction.

Previously

private static final MockUtil mockUtil = new MockUtil();

@Test
public void test()
{
    final Tenant currentTenant = mockUtil.mockCurrentTenant();

    // currentTenant was mocked as an instance of Tenant
    assertTrue( currentTenant instanceof ScpCfTenant ); // would fail
}

Now

private static final MockUtil mockUtil = new MockUtil();

@Test
public void test()
{
    final Tenant currentTenant = mockUtil.mockCurrentTenant();

    // currentTenant is now mocked as an instance of ScpCfTenant
    assertTrue( currentTenant instanceof ScpCfTenant ); // works!
}

Conclusion

This concludes our migration guide for moving to version 2.0.0 of the SAP S/4HANA Cloud SDK. We will update the content of this blog post based on your feedback on migration challenges that we may have overlooked so far. Let us know if you run into issues, for example by commenting on this blog post or posting your question on StackOverflow using the s4sdk tag!