The Service Binding Access library is a utility for easily reading application configurations for bound services in the Cloud Foundry and Kubernetes environment of SAP Business Technology Platform. It combines best practices with extended compatibility and low maintenance for library developers.

A service binding is a set of properties that describe how an application shall establish communication with an external service, such as a REST API, a database, or an event bus. Although the project primarily targets library developers, some web application projects may also profit from using this tool directly for specific use-cases. Please find the examples below.

Motivation

Java web application developers heavily rely on their frameworks and libraries to properly load any platform provided information that is necessary for service communication. Independent from the environment characteristics the service binding data for an application shall be automatically read and considered at runtime.

Until recently, library engineers wrote their own logic, potentially struggling with platform specific challenges. As a result, incompatibilities may occur over time with other application frameworks or even with the BTP environment itself. Therefore, we found three SAP projects to join forces and align on a unified API to address this common problem.

If you are using one of the following libraries, then your application already today is profiting from the improvements:

• SAP Cloud SDK 4.0.0+
• SAP Cloud Application Programming Model (CAP) 1.27.1+
• SAP XSUAA Cloud Security 2.13.0+

Usage

At application runtime the service bindings can be conveniently retrieved. It’s considered best-practice to expect an accessor object by parameter or class attribute, and use DefaultServiceBindingAccessor for fallback. The resulting list of service bindings can be filtered comfortably.

Optional<ServiceBinding> getXsuaaServiceBinding() {
  return getXsuaaServiceBinding(DefaultServiceBindingAccessor.getInstance());
}

Optional<ServiceBinding> getXsuaaServiceBinding( ServiceBindingAccessor accessor ) {
  return accessor.getServiceBindings()
    .stream()
    .filter(binding -> "xsuaa".equalsIgnoreCase(binding.getServiceName().orElse(null)))
    .filter(binding -> "lite".equalsIgnoreCase(binding.getServicePlan().orElse(null)))
    .filter(binding -> binding.getTags().contains("tag"))
    .findFirst();
}

Several default properties can be read from a single service binding object:

ServiceBinding binding;

Optional<String> name = binding.getName();
Optional<String> serviceName = binding.getServiceName();
Optional<String> servicePlan = binding.getServicePlan();
List<String> tags = binding.getTags();
Map<String, Object> credentials = binding.getCredentials();

The ServiceBinding instance represents an immutable collection of key-value properties. These properties can be used, for example, to establish an outbound connection to the specific service. Since the existence of service binding properties may depend on environment, plan or tenant, most fields are marked as optional.

Property access

In addition to the predefined property accessors, all available data can be read by using the generic methods:

ServiceBinding binding;

Set<String> keys = binding.getKeys();
boolean propExists = binding.containsKey("prop");
Optional<Object> propValue = binding.get("prop");

The library also provides optional helper classes to conveniently enable type-safe property access:

ServiceBinding binding;

TypedMapView bindingMap = TypedMapView.of(binding);
TypedMapView bindingCredentialsMap = TypedMapView.ofCredentials(binding);

The TypedMapView implements type-safe property accessors for reading values of type Boolean, String, Number, Map and List.

And more!

If you are interested in learning more about advanced features, please find the online repository: https://github.com/SAP/btp-environment-variable-access

You can use it to report issues, ask questions, request features and commit code. The documentation explains how to integrate and customize it in your own library. And once it works for you, please let us know in the comments! Then we will add it to our supporters list above.

Share Your Feedback

Do you have any questions on the new features? Or are you struggling with the upgrade? Don’t hesitate to share your feedback in the comments below, ask a question or to create a dedicated issue on the GitHub repository.