README.md

Java Open Service Broker

The Java Open Service Broker is Java library for developing an Open Service Broker.

It supports all features of the OSBAPI v2.14 specifications, including asynchronous Service Bindings and fetching Service Instances and Service Bindings.

This project is an early state and has not been extensively tested. Please report issues!

Goals

• Compliant with the Open Service Broker specification
• Lightweight
• Works with almost no external dependencies
• Can be used for stand-alone and embedded Service Brokers

Download

Download the latest JAR or grab via Maven:

<dependency>
  <groupId>de.fmui.osb.broker</groupId>
  <artifactId>java-osb-lib</artifactId>
  <version>0.0.2</version>
</dependency>

Usage

Implementing a broker handler

The business logic of your Service Broker resides in an object that implements the OpenServiceBrokerHandler interface. It is recommended to extend the class AbstractOpenServiceBrokerHandler instead of implementing the the interface directly.

The interface contains a method for each operation defined in the OSBAPI specification. All methods follow the same pattern:

OperationResponse operation(OperationRequest request) throws OpenServiceBrokerException

• The request object contains all input parameters and the request body.
• There is builder for each response object (OperationResponse.builder()), setting the HTTP status code and the response body.
• The request and response bodies and all objects defined in the OSBAPI specification are glorified Map<String, Object> objects, which allow setting and getting vendor extension fields.
• To return an error response, throw one of the exceptions derived from OpenServiceBrokerException.

See the example project for code samples.

Authentication

Authentication can be handled inside or outside the handler. If it is handled outside, the authenticate() method should be empty. If it is handled inside, the credentials check should happen in this method. This method is called before each operation method called. If the credentials are incorrect, throw an UnauthorizedException.

public void authenticate(RequestCredentials credentials) throws OpenServiceBrokerException {

  if (!credentials.isBasicAuthentication()) {
    throw new UnauthorizedException();
  }

  BasicAuthCredentials basicAuth = (BasicAuthCredentials) credentials;
  String username = basicAuth.getUsername();
  String password = basicAuth.getPassword();

  if (!check(username, password)) {
    throw new UnauthorizedException();
  }
}

Creating a stand-alone broker

The easiest way to build a stand-alone broker is to extend the OpenServiceBrokerServlet class.

@WebServlet("/my-broker/*")
public class MyBrokerServlet extends OpenServiceBrokerServlet {
  @Override
  public void init(ServletConfig config) throws ServletException {
    setOpenServiceBrokerHandler(new MyOSBHandler());
  }
}

Creating an embedded broker

To embed a broker into an existing servlet, use an OpenServiceBroker object. The processRequest() method parses the request, calls the broker handler, and sends the response.

@WebServlet("/my-service/*")
public class MyServiceServlet extends HttpServlet {

  private OpenServiceBroker broker = new OpenServiceBroker();
  private OpenServiceBrokerHandler handler = new MyOSBHandler();

  @Override
  protected void service(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {

    if (request.getPathInfo().startsWith("/broker/")) {
      // http://<host>/<context>/my-service/broker/...
      broker.processRequest(request, response, handler);
      return;
    } 
    
    // ... other code here ...
  }
}

Logging errors

The library writes error messages to stderr. This behavior can be changed by passing an object that implements the ErrorLogHandler interface to the setErrorLogHandler() method.

Converting contexts

The OSBAPI specification defines a context object, which contains platform specfic data. The default implementation converts Cloud Foundry context objects and Kubernetes context objects into the respective Java objects.

This conversion can be changed and extended to other platform by providing a custom ContextHandler object to the setContextHandler() method.

Example Service Broker

The example project contains code examples for a synchronous and an asynchronous Service Broker.