Fundamentals

Service Binding

A Service Binding is a set of (secret) key-value properties that can be used by applications to establish communication with external systems, such as a Database, an event bus, or a RESTful service.

The ServiceBinding interface is an immutable representation of the above mentioned concept. It allows accessing arbitrary properties using a String key. Additionally, it provides convenience getters for commonly used properties, such as the name of the service, tags associated with the Service Binding, and the credentials needed for accessing the remote service.

Service Binding Accessor

The ServiceBindingAccessor interface defines how applications can get a specific set of Service Bindings available to the application. Each ServiceBindingAccessor implementation should hereby focus on providing access to exactly one type of Service Binding.

For example, the SapVcapServicesServiceBindingAccessor is capable of parsing Cloud Foundrys VCAP_SERVICES structure for Service Bindings, but nothing else.

Instances of ServiceBindingAccessor that enable parsing different types of Service Bindings can then be combined using the built-in ServiceBindingMerger, which is a ServiceBindingAccessor itself. That way, different environments can be supported with one "top level" ServiceBindingAccessor.

Example: Combining ServiceBindingAccessors

ServiceBindingAccessor getCustomizedAccessor()
{
    ServiceBindingAccessor vcapServicesAccessor = new SapVcapServicesServiceBindingAccessor();
    ServiceBindingAccessor localEnvironmentAccessor = new MyLocalEnvironmentServiceBindingAccessor();

    return new ServiceBindingMerger(Arrays.asList(vcapServicesAccessor, localEnvironmentAccessor), ServiceBindingMerger.KEEP_EVERYTHING);
}

private static class MyLocalEnvironmentServiceBindingAccessor implements ServiceBindingAccessor
{
    ...
}

Typed Map / List View

The ServiceBinding interface is a very low-level abstraction. As such, it is not meant for extensive data parsing. Instead, applications usually just pass ServiceBinding instances to more high-level APIs of libraries and frameworks without further inspecting the contained data - if they ever come into contact with the ServiceBinding at all.

Sometimes, however, more complex or customized data extraction is actually needed.

This is where the TypedMapView and the TypedListView come into play. These two classes provide a type-safe, immutable abstraction over the ServiceBinding. They do offer APIs for retrieving both primitive values (e.g. getString(key)) as well as complex, nested structures (e.g. getMapView(key)).

Usage Example

ServiceBinding binding;

TypedMapView typedMapView = TypedMapView.of(binding);

String myStringValue = typedMapView.getString("my-string-property");
TypedListView myListValue = typedMapView.getListView("my-list-property");
TypedMapView myMapValue = typedMapView.getMapView("my-map-property");

// read credential properties
TypedMapView credentialView = TypedMapView.ofCredentials(binding);
String username = credentialView.getString("username");
String password = credentialView.getString("password");