We're happy to announce: SAP Cloud SDK Version 3 is finally here!
Note: For a quick tutorial on how to migrate, please visit our step-by-step guide.
Note: In case your Java project uses the CAP stack, please alter your project structure to use SAP Cloud SDK 3 beforehand as per the related blog post.
Note: For a complete overview of our blog post series visit the SAP Cloud SDK Overview.
As the new version of the SAP Cloud SDK for Java was announced many software projects may face the same migration scenario. This major update brings numerous improvements in code style, destination handling, test tools and much more. Some of the changes require a code adaptation on the consumer side of the API. That's why we highly recommend to read this document and follow the suggested steps whenever necessary.
So before starting to blindly resolve dependency issues, missing classes or type conflicts, please notice the changes done to...
In addition we suggest to read up on the updated behavior with...
As part of our renaming from SAP S/4HANA Cloud SDK to SAP Cloud SDK we now also adjusted the group id of all our modules to no longer contain the
When migrating your existing application to use version 3 of SAP Cloud SDK, please manually update the Maven groupId and artifactId of any referenced dependency entry in your
While all of them need to be checked, we advice to start with the project root
When iterating over the other dependencies, please check for the moved Maven group ids:
As you can see, with the library re-branding to SAP Cloud SDK, we were able to extract the S/4HANA related classes into their dedicated artifacts. While doing so, we slightly changed the name of some artifactIds to make them nonambiguous. You can find the full list of changed names in the table of the release notes.
Some modules of the SAP Cloud SDK have been discontinued. They have been used mostly internally and thus it is highly unlikely your application has used any of them directly.
If you have not yet generated a Maven project from one of the SAP Cloud SDK archetypes, you don't have to change anything. Just make sure to follow the tutorials accordingly and keep in mind the new archetype ids:
To better reflect the actual use of a class we also renamed all
The entity
The capabilities of the OData VDM provided by the SAP Cloud SDK 3 have not changed over the version. However, we introduce a completely new concept to handle destinations.
A quick overview of how we handled destinations prior to version 3:
A call to the OData VDM looked like this:
The downsides of this approach are:
The new concept now represents all destinations via interfaces (
The example call above can now look like this
This, for itself, doesn't look like an improvement at all. But consider the following example:
This means you no longer need to mock any Destination for the
Removal of the
With the new destination concept we also removed the
will look this in the future (if you want to stay with the default destination name):
This makes it clearer which destination actually gets loaded and consequently used by your OData VDM call.
The
Under the hood this just wraps the returned Destination of the
In the past Hystrix has been used as a library to ensure latency and fault tolerance conditions for the application runtime. But since Hystrix is not longer in active development but in maintenance mode, a migration happened to the spiritual successor: Resilience4j. The consuming API has seen some drastic changes.
When migrating to version 3, some adjustments need to be made for any application classes inheriting directly or indirectly from the class
Function decoration describes the practice of altering a provided lambda with the help of a utility class. This provides some advantages compared to the old inheritance model:
Example: A resilient call to an OData service endpoint.
The
With version 3 the following options are available to customize the instance of
Since the default resilience isolation mode is
As a result of the migration, the
When using the
With version 3, the internal framework to manage cache instances has changed from Guava Cache to the widely used JCache(JSR 107). Since this framework acts as Service Provider Interface, any adapter for JCache can be attached to your application. We highly recommend Caffeine to provide superior caching capabilities. The required dependency can be quickly added to the application
However if the consumer decides to use their own JCache provider, it's possible to exchange the respective dependency in the application Maven project setup. Consequently, the caching strategy only works, when a service provider for JCache is accessible at runtime.
Example: A cached resilient call to an exemplary service, which considers additional parameters for the cache key.
With version 3, the actual resilience framework can be customized. The application developer can implement their own implementation of
The API for
Under the hood of the
The default way the
This is now represented in a more flexible way by using the
In a provider/subscriber setup of your application you might have the possibility to retrieve a destination from either the provider or the subscriber. Before version 3 this looked like the following:
The change in version 3 removed this from the
This allows you to set the retrieval strategy on a per-call basis.
To follow the latest state-of-the-art paradigms with the SDK we decided to embrace the vavr library. This allows the consumer of the SDK to use different methods in a more functional way.
This new dependency introduces, besides many other classes, the
All of our APIs now use the vavr
with
as well as any usage of
If you want to fall back to the Java provided
For more information have a look into the great overview of the vavr library: https://www.vavr.io/vavr-docs/
In version 3, the following accessor classes and their corresponding facades have been restructured, simplifying their structure and leveraging functional concepts from
This affects the following classes:
As mentioned earlier,
For example, before version 3, the
Given that this class had five methods that needed to be implemented, providing a custom facade or mocking a facade in a test was rather cumbersome. In contrast, in version 3, the interface is now simplified and only consists of one method, wrapping possible error conditions in a
Accordingly, the
As you can see, on one hand, the
In addition to the existing accessors above, the following accessors have been added in version 3:
In addition to these changes, the following accessors now offer additional methods:
These methods allow to run code on behalf of another tenant, principal, request, and authorization token, either overriding a possibly existing value, offering a fallback in case of a missing existing value, and providing a global fallback on the accessor in case no other value exists. This allows to adjust the behavior of these accessors as needed, for example, to simplify testing.
Please note that the previously existing
For example, in order to run code on behalf of another tenant, you can use the following code now:
In order to use an existing tenant and only fallback to another tenant if no other tenant is available, you can use:
Finally, in order to define a global fallback, you can use:
Before version 3, the SAP Cloud SDK offered a so-called
One major functional change of the
Similar to the
In addition to this change, the
Furthermore, version 3 introduces
In order to wrap some piece of code into a specific context, you can use the
So, the following code:
will now look like this:
As you can see, no specific
If you want to make sure that a specific
This will ignore any existing contexts and simply use the
With version 3, the following global variables have been removed and are no longer considered at runtime:
This is the result of making the Cloud SDK more lenient towards versatile application scopes. The runtime no longer requires the context to provide correct values for tenant and principal (user). Instead tenant and principal are taken into account only when available. This is reflected in the default resilience isolation mode
If the API consumer insists on the tenant or principal separation, they need to specify the respective isolation mode in the
The test utility class
In addition, version 3 removes all methods from
Note: For a quick tutorial on how to migrate, please visit our step-by-step guide.
Note: In case your Java project uses the CAP stack, please alter your project structure to use SAP Cloud SDK 3 beforehand as per the related blog post.
Note: For a complete overview of our blog post series visit the SAP Cloud SDK Overview.
Introduction
As the new version of the SAP Cloud SDK for Java was announced many software projects may face the same migration scenario. This major update brings numerous improvements in code style, destination handling, test tools and much more. Some of the changes require a code adaptation on the consumer side of the API. That's why we highly recommend to read this document and follow the suggested steps whenever necessary.
So before starting to blindly resolve dependency issues, missing classes or type conflicts, please notice the changes done to...
- Dependency Identifiers
- VDM Usage
In addition we suggest to read up on the updated behavior with...
- Resilience and Caching
- Destination Handling
- VAVR Usage
- Accessors Handling
- ThreadContext
- Environment Variables
- MockUtil
Changed dependency identifiers and class names
As part of our renaming from SAP S/4HANA Cloud SDK to SAP Cloud SDK we now also adjusted the group id of all our modules to no longer contain the
s4hana section by default, but only when the module actually is S/4HANA specific. The artifact ids are now also unique, so that build tools like Gradle can easily import our modules just be using the artifact id. The concrete changes can be found in our release notes.Migrating the Maven project setup for an existing application
When migrating your existing application to use version 3 of SAP Cloud SDK, please manually update the Maven groupId and artifactId of any referenced dependency entry in your
pom.xml file. Please note, in a multi project setup you will find multiple pom.xml files.While all of them need to be checked, we advice to start with the project root
pom.xml. Find the dependencyManagemententry and replace the sdk-bom entry with the following:<dependency>
<groupId>com.sap.cloud.sdk</groupId>
<artifactId>sdk-bom</artifactId>
<version>3.0.0</version>
<type>pom</type>
<scope>import</scope>
</dependency>When iterating over the other dependencies, please check for the moved Maven group ids:
| Old GroupId | New GroupId | Context |
|---|---|---|
| com.sap.cloud.s4hana.archetypes | com.sap.cloud.sdk.archetypes | Maven archetypes |
| com.sap.cloud.s4hana.cloudplatform | com.sap.cloud.sdk.cloudplatform | SCP specific API |
| com.sap.cloud.s4hana.datamodel | com.sap.cloud.sdk.datamodel | API for virtual datamodel |
| com.sap.cloud.sdk.s4hana | S/4HANA specific API | |
| com.sap.cloud.s4hana.frameworks | com.sap.cloud.sdk.frameworks | Selection of frameworks |
| com.sap.cloud.s4hana.plugins | com.sap.cloud.sdk.plugins | Maven plugins |
| com.sap.cloud.s4hana.quality | com.sap.cloud.sdk.quality | Code quality ensuring classes |
| com.sap.cloud.s4hana.services | com.sap.cloud.sdk.services | Contributed serivce classes |
| com.sap.cloud.s4hana | com.sap.cloud.sdk.s4hana | S/4HANA specific API |
| com.sap.cloud.sdk.datamodel | API for virtual datamodel | |
| com.sap.cloud.sdk | Commonly used library core classes | |
| com.sap.cloud.sdk.testutil | Unit and integration tests |
As you can see, with the library re-branding to SAP Cloud SDK, we were able to extract the S/4HANA related classes into their dedicated artifacts. While doing so, we slightly changed the name of some artifactIds to make them nonambiguous. You can find the full list of changed names in the table of the release notes.
Some modules of the SAP Cloud SDK have been discontinued. They have been used mostly internally and thus it is highly unlikely your application has used any of them directly.
Migrating a new application
If you have not yet generated a Maven project from one of the SAP Cloud SDK archetypes, you don't have to change anything. Just make sure to follow the tutorials accordingly and keep in mind the new archetype ids:
com.sap.cloud.sdk.archetypes:scp-cf-springcom.sap.cloud.sdk.archetypes:scp-cf-tomeecom.sap.cloud.sdk.archetypes:scp-neo-javaee7
Renamed type names
To better reflect the actual use of a class we also renamed all
*Query classes into *Request as long as their main purpose was to request/read data from another system. This is especially relevant for the SoapQuery which is now called SoapRequestbut behaves completely the same.The entity
User has been replaced with the more generic entity Principal. It still fulfills the same functionality but now the updated name correctly reflects the meaning in the context of the application.Using the VDM
The capabilities of the OData VDM provided by the SAP Cloud SDK 3 have not changed over the version. However, we introduce a completely new concept to handle destinations.
Quick overview
A quick overview of how we handled destinations prior to version 3:
- A Destination was always identified by its name
- To retrieve the actual information of a destination we used the
DestinationAccessorwith the provided name - Class hierarchy representing the different types of destinations (HTTP, RFC)
A call to the OData VDM looked like this:
new DefaultBusinessPartnerService()
.getAllBusinessPartner()
.execute(new ErpConfigContext("some-destination-name"));The downsides of this approach are:
- With the tight coupling between the OData execution logic to the
DestinationAccessorit was necessary to mock a whole lot of code to execute a call inside a unit test - Having the different types as part of a strict class hierarchy means that adding new types in the future (or on-demand by a consumer) was rather complex and in some cases not possible at all.
The new concept now represents all destinations via interfaces (
DestinationProperties, HttpDestinationProperties, RfcDestinationProperties) that specify what properties a destinations exposes. Those properties are handled internally by an immutable Map, making the new destinations immutable themselves.The example call above can now look like this
Destination destination = DestinationAccessor.getDestination("some-destination-name");
new DefaultBusinessPartnerService()
.getAllBusinessPartner()
.execute(destination.asHttp());This, for itself, doesn't look like an improvement at all. But consider the following example:
HttpDestination httpDestination = DefaultHttpDestination.builder("uri.to.your.system").build()
new DefaultBusinessPartnerService()
.getAllBusinessPartner()
.execute(httpDestination);This means you no longer need to mock any Destination for the
DestinationAccessor just to execute a call via the OData VDM, e.g. in a test.Removal of the ErpQueryEndpoint and ErpConfigContext
With the new destination concept we also removed the
ErpConfigContext and the hidden default destination name ErpQueryEndpoint. This means your call like thisnew DefaultBusinessPartnerService()
.getAllBusinessPartner()
.execute(new ErpConfigContext());will look this in the future (if you want to stay with the default destination name):
Destination destination = DestinationAccessor.getDestination("ErpQueryEndpoint").decorate(DefaultErpHttpDestination::new);
new DefaultBusinessPartnerService()
.getAllBusinessPartner()
.execute(destination.asHttp());This makes it clearer which destination actually gets loaded and consequently used by your OData VDM call.
The
ErpConfigContext prior to version 3 handles the resolution of the sap-client and sap-locale properties of a Destination. This is now handled by the DefaultErpHttpDestination by decorating an already existing HttpDestination, as can be seen above. An alternative way to retrieve an ErpHttpDestination directly is provided by the ErpHttDestinationUtilsclass like this:ErpHttpDestination erpHttpDestination = ErpHttpDestinationUtils.getErpHttpDestination("some-destination-name");Under the hood this just wraps the returned Destination of the
DestinationAccessor and wraps it as an ErpHttpDestination. This is basically a drop-in replacement of the old ErpConfigContext.Resilience and Caching
In the past Hystrix has been used as a library to ensure latency and fault tolerance conditions for the application runtime. But since Hystrix is not longer in active development but in maintenance mode, a migration happened to the spiritual successor: Resilience4j. The consuming API has seen some drastic changes.
Lambda instead of Inheritance
When migrating to version 3, some adjustments need to be made for any application classes inheriting directly or indirectly from the class
HystrixCommand (or Command, ErpCommand, CachingErpCommand, CachingCommand). This Command model was used to implement child classes dedicated to a resilient operation. It has been discontinued in favor of function decoration.Function decoration describes the practice of altering a provided lambda with the help of a utility class. This provides some advantages compared to the old inheritance model:
- Modern API style, less boiler-plate code, fewer classes
- Optional decoration options can customize the lambda modification
- Interchangeable dependencies enables easy switching of involved frameworks
Example: A resilient call to an OData service endpoint.
- Before:
public class GetBusinessPartnerCommand extends ErpCommand<List<BusinessPartner>>
{
private final BusinessPartnerService businessPartnerService;
public GetBusinessPartnerCommand( BusinessPartnerService businessPartnerService, ErpConfigContext configContext )
{
super(GetBusinessPartnerCommand.class, configContext);
this.businessPartnerService = businessPartnerService;
}
@Override
protected List<BusinessPartner> run()
throws ODataException
{
return businessPartnerService.getAllBusinessPartner().top(10).execute(getConfigContext());
}
}
...
final BusinessPartnerService service = new DefaultBusinessPartnerService();
final ErpConfigContext configContext = new ErpConfigContext("MyDestination");
final List<BusinessPartner> businessPartners = new GetBusinessPartnerCommand(service, configContext).execute();
Characteristics:
- Class inheritance is required, therefore also an implementation of
run()and the super constructor invocation. - Requires a reference of
ErpConfigContext. - No easy way to declare the operation's dependency to tenant or principal.
- No easy way to customize resilience options.
- (Required) external dependency to Hystrix.
- Class inheritance is required, therefore also an implementation of
- After (with minimal application change):
public class GetBusinessPartnerCommand
{
private final BusinessPartnerService businessPartnerService;
private final Destination destination;
public GetBusinessPartnerCommand( BusinessPartnerService businessPartnerService, Destination destination )
{
this.businessPartnerService = businessPartnerService;
this.destination = destination;
}
public List<BusinessPartner> execute()
{
return ResilienceDecorator.executeSupplier(this::run, ResilienceConfiguration.of(GetBusinessPartnerCommand.class));
}
private List<BusinessPartner> run() {
try {
return businessPartnerService.getAllBusinessPartner().top(10).execute(destination.asHttp());
}
catch( ODataException e ) {
throw new ResilienceRuntimeException(e);
}
}
}
...
final BusinessPartnerService service = new DefaultBusinessPartnerService();
final Destination destination = DestinationAccessor.getDestination("MyDestination");
final List<BusinessPartner> businessPartners = new GetBusinessPartnerCommand(service, destination).execute();
Characteristics:
- No inheritance, no implementation requirements.
ResilienceConfigurationrequires a key, that can be either a String or a class reference.ResilienceConfigurationis customizable, featuring many different settings.- Direct exception handling.
- (Optional) external dependency to Resilience4j.
- Best practice:
final BusinessPartnerService service = new DefaultBusinessPartnerService();
final Destination destination = DestinationAccessor.getDestination("MyDestination");
final List<BusinessPartner> businessPartners = ResilienceDecorator.executeCallable(
() -> service.getAllBusinessPartner().top(10).execute(destination.asHttp()),
ResilienceConfiguration.of(BusinessPartnerService.class)
);
Characteristics:
- No extra class definition required. Short inline code.
- If exception handling needs to be adjusted, we recommend the
Tryconstruct from VAVR.
ResilienceDecorator
The
ResilienceDecorator class allows the API consumer to wrap a lambda of type Supplier (without checked exceptions) or Callable (with checked exceptions). Besides wrapping, it can also execute the lambda right away, even with optional fallback strategy - in case something goes wrong.With version 3 the following options are available to customize the instance of
ResilienceConfiguration:ResilienceIsolationMode
- Enum: NO_ISOLATION, TENANT_REQUIRED, TENANT_OPTIONAL, PRINCIPAL_REQUIRED, PRINCIPAL_OPTIONAL, TENANT_AND_USER_REQUIRED, TENANT_AND_USER_OPTIONAL (default)
BulkheadConfiguration
- MaxConcurrentCalls (int, default: 50)
- MaxWaitDuration (Duration, default: 60s)
CacheConfiguration
- ExpirationDuration (Duration, default: instant)
- Parameters (Serializable[] or Object[], default: empty)
CircuitBreakerConfiguration
- FailureRateThreshold (float, default: 50%)
- WaitDuration (Duration, default: 10s)
TimeLimiterConfiguration
- TimeoutDuration (Duration, default: 30s)
- ShouldCancelRunningFuture (boolean, default: true)
Since the default resilience isolation mode is
TENANT_AND_USER_OPTIONAL the resilience decorator decides at runtime, whether or not to include the tenant and principal data, depending on their existence in the current thread context. If the consumer wants to enforce principal or tenant separation, the isolation mode must be declared in the decorator options.As a result of the migration, the
asResilientCommand() methods were removed from all VDM fluent helpers. Now the API consumer is required to wrap their invocation of execute() from VDM fluent helpers using ResilienceDecorator instead.Caching with JCache
When using the
ResilienceDecorator, the caching feature is not enabled by default. It is activated once a CacheConfiguration is provided. Additional parameters can be passed along to customize the internal cache key. If these parameters are serializable, the cache key will be serializable as well.With version 3, the internal framework to manage cache instances has changed from Guava Cache to the widely used JCache(JSR 107). Since this framework acts as Service Provider Interface, any adapter for JCache can be attached to your application. We highly recommend Caffeine to provide superior caching capabilities. The required dependency can be quickly added to the application
pom.xml:<dependency>
<groupId>com.github.ben-manes.caffeine</groupId>
<artifactId>jcache</artifactId>
<version>2.7.0</version>
</dependency>However if the consumer decides to use their own JCache provider, it's possible to exchange the respective dependency in the application Maven project setup. Consequently, the caching strategy only works, when a service provider for JCache is accessible at runtime.
Example: A cached resilient call to an exemplary service, which considers additional parameters for the cache key.
- Before:
public class AddressBookLookupCommand extends CachingErpCommand<Address> {
private static final Cache<CacheKey, Address> cache = CacheBuilder.newBuilder().build();
private final AddressBookService addressBookService;
public AddressBookLookupCommand( AddressBookService addressBookService, ErpConfigContext configContext )
{
super(GetBusinessPartnerCommand.class, configContext);
this.addressBookService = addressBookService;
}
@Override
protected CacheKey getCacheKey() {
return super.getCacheKey().append(lastName, firstName);
}
@Override
protected Cache<CacheKey, Address> getCache() {
return cache;
}
@Override
protected final Address run() {
return addressBookService.lookup(lastName, firstName);
}
}
...
AddressBookService service;
String lastName;
String firstName;
Address address = new AddressBookLookupCommand(service, lastName, firstName).execute();
Characteristics:
- Enabling caching requires
CachingCommandorCachingErpCommandas super class. - Inheritance model requires overriding several methods.
- Manually manage static cache instance.
- Customization of CacheKey can easily be missed.
- Enabling caching requires
- After:
AddressBookService service;
String lastName;
String firstName;
ResilienceConfiguration resilienceConfiguration = ResilienceConfiguration.of(AddressBookService.class)
.cacheConfiguration(CacheConfiguration.of(Duration.ofDays(1)).withParameters(lastName, firstName)); // <--
Address address = ResilienceDecorator.executeSupplier(
() -> service.lookup(lastName, firstName),
resilienceConfiguration
);
Characteristics:
- Enabling caching only requires the attachment of
CacheConfigurationto the instance ofResilienceConfiguration. - API requires the consumer to specify the additional cache key parameters. Alternatively there is
withoutParameters()when no customization of cache key is required.
- Enabling caching only requires the attachment of
Resilience4j
With version 3, the actual resilience framework can be customized. The application developer can implement their own implementation of
ResilienceDecorationStrategy. But by default the resilience implementation of Cloud SDK is used, which is based on Resilience4j. However the strategy can be changed on the static methods of ResilienceDecorator.Destinations
The API for
DestinationAccessor and the related DestinationLoader provide a powerful set of tools to leverage the integration process to external services.Deeper look into the DestinationAccessor
Under the hood of the
DestinationAccessor no longer a single DestinationFacade handles the retrieval of destinations, but a chain of so called DestinationLoader.The default way the
DestinationAccessor searches for Destinations is the same with version 3 as before:- Search for a destination with the given name in the
destinationsenvironment variable. - Look into any additional loader provided by the libraries you have on your class path (e.g. the Destination Service on SAP Cloud Foundry).
This is now represented in a more flexible way by using the
DestinationLoaderChain. This now represents a chain of DestinationLoader implementations that are used one after another until a Destination is found. For an example, lets assume you want to retrieve your destinations first from the destinations environment variable, then from the Destination Service on SAP Cloud Foundry, and last from the Environment variable provided by the Extension Factory. Your custom loader chain would be instantiated the following way:DestinationLoader customLoaderChain =
DestinationLoaderChain
.builder(new EnvVarDestinationLoader())
.append(new ScpCfDestinationLoader())
.append(new ScpXfDestinationLoader())
.build();
DestinationAccessor.setLoader(customLoaderChain);How to use a different instances of RetrievalStrategy
In a provider/subscriber setup of your application you might have the possibility to retrieve a destination from either the provider or the subscriber. Before version 3 this looked like the following:
DestinationAccessor.setRetrievalStrategy("some-destination-name", DestinationRetrievalStrategy.ALWAYS_SUBSCRIBER);
Destination destination = DestinationAccessor.getDestination("some-destination-name");The change in version 3 removed this from the
DestinationAccessor and moved it to the actual DestinationLoaderimplementation. This makes it clearer that this is very platform specific knowledge.DestinationOptions customOptions =
DestinationOptions
.builder()
.augmentBuilder(
ScpCfDestinationOptionsAugmenter
.augmenter()
.retrievalStrategy(ScpCfDestinationRetrievalStrategy.ALWAYS_SUBSCRIBER))
.build();
Destination destination =
new ScpCfDestinationLoader()
.tryGetDestination("some-destination-name", customOptions)
.get();This allows you to set the retrieval strategy on a per-call basis.
Usage of VAVR in the API
To follow the latest state-of-the-art paradigms with the SDK we decided to embrace the vavr library. This allows the consumer of the SDK to use different methods in a more functional way.
Try<Tenant> maybeTenant = TenantAccessor.tryGetCurrentTenant();
String tenantId = maybeTenant.onFailure(this::recoverFromException).map(Tenant::getTenantId).get();This new dependency introduces, besides many other classes, the
Try mentioned above containing either an Throwable or an actual value, as well as an Option. This Option is a more powerful replacement of the Java provided Optional class.All of our APIs now use the vavr
Option instead of the Java Optional, so that a migration on the consumer side would replaceimport java.util.Optional;with
import io.vavr.control.Option;as well as any usage of
Option with Optional in the corresponding places.If you want to fall back to the Java provided
Optional you can easily do so by calling the toJavaOptional method:Option<BasicCredentials> vavrCredentials = httpDestination.getBasicCredentials();
Optional<BasicCredentials> javaCredentials = vavrCredentials.toJavaOptional();For more information have a look into the great overview of the vavr library: https://www.vavr.io/vavr-docs/
Accessors
Simplified Facade Structure and New Accessors
In version 3, the following accessor classes and their corresponding facades have been restructured, simplifying their structure and leveraging functional concepts from
io.vavr.control.Try.This affects the following classes:
TenantAccessorPrincipalAccessorDestinationAccessorHttpClientAccessorCloudPlatformAccessorSecretStoreAccessorAuthTokenAccessorLocaleAccessorJndiLookupAccessor
As mentioned earlier,
User has been migrated to Principal. Accordingly the original UserAccessor is no longer available but has been merged with the more generic PrincipalAccessor.For example, before version 3, the
TenantFacade looked like this:public interface TenantFacade
{
Class<? extends Tenant> getTenantClass();
Optional<Tenant> resolveCurrentTenant()
throws TenantAccessException;
Tenant getCurrentTenant()
throws TenantNotAvailableException, TenantAccessException;
Optional<Tenant> getCurrentTenantIfAvailable()
throws TenantAccessException;
Try<Tenant> tryGetCurrentTenant();
}Given that this class had five methods that needed to be implemented, providing a custom facade or mocking a facade in a test was rather cumbersome. In contrast, in version 3, the interface is now simplified and only consists of one method, wrapping possible error conditions in a
Try.public interface TenantFacade
{
Try<Tenant> tryGetCurrentTenant();
}Accordingly, the
TenantAccessor only relies on this one method to provide the following methods on its API:public final class TenantAccessor {
private static Try<TenantFacade> tenantFacade = FacadeLocator.getFacade(TenantFacade.class);
public static TenantFacade getTenantFacade() {
...
}
public static Try<TenantFacade> tryGetTenantFacade() {
...
}
public static void setTenantFacade( @Nullable final TenantFacade tenantFacade ) {
...
}
public static Tenant getCurrentTenant() throws TenantAccessException {
return tryGetCurrentTenant().getOrElseThrow(failure -> {
if( failure instanceof TenantAccessException ) {
throw (TenantAccessException) failure;
} else {
throw new TenantAccessException("Failed to get current tenant.", failure);
}
});
}
public static Try<Tenant> tryGetCurrentTenant() {
final Try<Tenant> tenantTry = tenantFacade.flatMap(TenantFacade::tryGetCurrentTenant);
...
return tenantTry;
}
...
}As you can see, on one hand, the
FacadeLocator now returns a Try when looking up an implementation, allowing the SDK to more leniently handle errors and only yield them if an accessor is really used. On the other hand, you may notice that the getCurrentTenant method simply delegates to the tryGetCurrentTenant method now, simplifying the implementation efforts for a facade.In addition to the existing accessors above, the following accessors have been added in version 3:
ThreadContextAccessorRequestAccessor
New Methods for "on-behalf" Execution
In addition to these changes, the following accessors now offer additional methods:
TenantAccessornow offers:
T executeWithTenant( Tenant tenant, Callable<T> callable )T executeWithFallbackTenant( Supplier<Tenant> fallbackTenant, Callable<T> callable )void executeWithTenant( Tenant tenant, Executable executable )void executeWithFallbackTenant( Supplier<Tenant> fallbackTenant, Callable<T> callable )Supplier<Tenant> getFallbackTenant()void setFallbackTenant(Supplier<Tenant> fallbackTenant)
PrincipalAccessornow offers:
T executeWithPrincipal( Principal principal, Callable<T> callable )T executeWithFallbackPrincipal( Supplier<Principal> fallbackPrincipal, Callable<T> callable )void executeWithPrincipal( Principal principal, Executable executable )void executeWithFallbackPrincipal( Supplier<Principal> fallbackPrincipal, Callable<T> callable )Supplier<Principal> getFallbackPrincipal()void setFallbackPrincipal(Supplier<Principal> fallbackPrincipal)
RequestAccessornow offers:
T executeWithRequest( HttpServletRequest request, Callable<T> callable )T executeWithFallbackRequest( Supplier<HttpServletRequest> fallbackRequest, Callable<T> callable )void executeWithRequest( HttpServletRequest request, Executable executable )void executeWithFallbackRequest( Supplier<HttpServletRequest> fallbackRequest, Callable<T> callable )Supplier<HttpServletRequest> getFallbackRequest()void setFallbackRequest(Supplier<HttpServletRequest> fallbackRequest)
AuthTokenAccessornow offers:
T executeWithAuthToken( AuthToken authToken, Callable<T> callable )T executeWithFallbackAuthToken( Supplier<AuthToken> fallbackAuthToken, Callable<T> callable )void executeWithAuthToken( AuthToken authToken, Executable executable )void executeWithFallbackAuthToken( Supplier<AuthToken> fallbackAuthToken, Callable<T> callable )Supplier<AuthToken> getFallbackToken()void setFallbackToken(Supplier<AuthToken> fallbackToken)
These methods allow to run code on behalf of another tenant, principal, request, and authorization token, either overriding a possibly existing value, offering a fallback in case of a missing existing value, and providing a global fallback on the accessor in case no other value exists. This allows to adjust the behavior of these accessors as needed, for example, to simplify testing.
Please note that the previously existing
JwtBasedRequestContextExecutor has been removed, being replaced with the respective executeWithAuthToken method of AuthTokenAccessor. You will also now find the new class AuthTokenBuilder, offering you convenient ways to construct an AuthToken instance to pass as an argument.For example, in order to run code on behalf of another tenant, you can use the following code now:
TenantAccessor.executeWithTenant(new ScpCfTenant("some-tenant", "some-subdomain"), () -> {
// TenantAccessor.getCurrentTenant() will return the tenant "some-tenant".
});In order to use an existing tenant and only fallback to another tenant if no other tenant is available, you can use:
TenantAccessor.executeWithFallbackTenant(new ScpCfTenant("fallback-tenant", "some-subdomain"), () -> {
// TenantAccessor.getCurrentTenant() will return the tenant that is already defined,
// or the tenant "fallback-tenant" if no tenant is otherwise available.
});Finally, in order to define a global fallback, you can use:
// define a global fallback for TenantAccessor
TenantAccessor.setFallbackTenant(() -> new ScpCfTenant("global-fallback-tenant", "some-subdomain"));
// remove the global fallback
TenantAccessor.setFallbackTenant(null);ThreadContext
Move from RequestContext to ThreadContext
Before version 3, the SAP Cloud SDK offered a so-called
RequestContext for storing the current request across different threads. In order to better decouple this concept from the servlet standard, version 3 introduces ThreadContext to replace this concept. A ThreadContext no longer holds a reference to the current request, but instead only provides a generic map of properties to store across threads.One major functional change of the
ThreadContext is that it is now possible to nest such contexts transparently, whereas before you had received an exception that indicated that this was not possible without a specific call to withParentRequestContext in the RequestContextExecutor.Similar to the
RequestContextAccessor in previous versions, ThreadContextAccessor offers the tryGetCurrentContext and getCurrentContext methods to access the current ThreadContext, and RequestAccessor which allows to access the current request. Internally, the RequestAccessor uses a ThreadContextListener to store the current request as a property of the current ThreadContext.In addition to this change, the
ThreadContextListeners, which are used to manage the properties in a ThreadContext, are extended in version 3 of the SDK to allow not only to hook into the initialization and destruction of the ThreadContext, but also get notified with a beforeInitialize, afterInitialize, beforeDestroy, and afterDestroy methods.Furthermore, version 3 introduces
ThreadContextDecorator, which offers the possibility to also wrap the callable that is passed to the ThreadContextExecutor, which replaces the previously existing RequestContextExecutor, allowing to wrap a piece of code into a specific context. This is used, for example, for the SAP CP Neo environment, which requires to manage some thread-specific state when switching to threads outside of container-managed threads.Running Code with a Specific ThreadContext
In order to wrap some piece of code into a specific context, you can use the
ThreadContextExecutor, similar to the RequestContextExecutor before.So, the following code:
new RequestContextExecutor().execute(() -> {
// compute some value
return someValue;
});will now look like this:
new ThreadContextExecutor().execute(() -> {
// compute some value
return someValue;
});As you can see, no specific
ThreadContext is provided here. This means that the call will either inherit and use an existing parent ThreadContext, if one is present. Otherwise, a new ThreadContext will be created.If you want to make sure that a specific
ThreadContext is used, you can provided it as follows:new ThreadContextExecutor().withThreadContext(customThreadContext).execute(() -> {
// compute some value
return someValue;
});This will ignore any existing contexts and simply use the
ThreadContext that is provided in withThreadContext.Environment Variables
With version 3, the following global variables have been removed and are no longer considered at runtime:
- USE_MOCKED_TENANT
- USE_MOCKED_USER
- ALLOW_MOCKED_AUTH_HEADER
This is the result of making the Cloud SDK more lenient towards versatile application scopes. The runtime no longer requires the context to provide correct values for tenant and principal (user). Instead tenant and principal are taken into account only when available. This is reflected in the default resilience isolation mode
TENANT_AND_USER_OPTIONAL.If the API consumer insists on the tenant or principal separation, they need to specify the respective isolation mode in the
ResilienceConfiguration for each resilient call. For example, the application will throw an exception when TENANT_AND_USER_REQUIRED is chosen but one of them is not resolvable from the thread context during runtime.Remove Unwanted Methods and Behavior from MockUtil
The test utility class
MockUtil no longer mocks the platform-dependent instance of the respective interface. For instance, in version 2.x, mockTenant() would have mocked an instance of either ScpCfTenant or ScpNeoTenant, depending on the used environment. While the intention here was to simplify testing, we noticed that this actually complicated the usage and facades such as TenantFacade. Therefore, version 3 again only mocks an instance of the interface, in our example, Tenant.In addition, version 3 removes all methods from
MockUtil that relied on the implicit destination name "ErpQueryEndpoint", for example the method mockDestination() which has no additional parameters. Now, the corresponding remaining methods require that you specify a destination name. Within existing tests, you can therefore safely add the missing argument by specifying "ErpQueryEndpoint" as destination name, or adjust your test to use another name of your choice.
- SAP Managed Tags:
17 Comments
| User | Count |
|---|---|
| 14 | |
| 11 | |
| 11 | |
| 10 | |
| 10 | |
| 8 | |
| 7 | |
| 7 | |
| 7 | |
| 7 |
