Recipes are community-created content. They are neither monitored nor endorsed by IBM. If you find inappropriate content, please useReport Abuseto let us know. For more information on community content, please refer to ourTerms of Use.

Cloud foundry concepts, knowledge of Java and Spring is required.

The recipe describes, creation of a service broker using spring framework, registration of a service broker on cloud platform and usage of the broker to expose a search service over cloud platform.

It also demonstrates the consumption of search service.

A machine with cloud foundry installed is a prerequisite.

This tutorial is exhibited on a Windows machine with a mini cloud foundry test environment and Bosh-Lite implementation.

For assistance with bosh-lite based cloud foundry installation, please refer to the Reference section.

Cloud Foundry is an open source cloud platform-as-a-service (PaaS), on which a developer can build, deploy and run applications on public or private cloud model. For more information on cloud foundry, please refer to

Cloud foundry provides a marketplace for services for example database as a service. Cloud foundry Service Broker is a medium which helps client to bind his application (say a Java application) to the cloud foundry managed services and use those services. For example, an application might not need to install and manage its own database but can bind to one of the database services available on cloud platform. The binding/unbinding of these services can be performed via Service brokers.

Service broker performs following activities for platform manage services

Publish catalog/details of service and its plans, costs and other metadata information.

Provision, deprovision service instances while client needs to bind/unbind those services.

Publish details of these services such as URL, credentials etc., for the application to bind with those.

Service broker implements APIs, for which cloud platform is a client. Service broker is responsible for advertising service and to make binding between service and application which consumes the service.

We will use spring-boot framework to develop Service broker. Spring-boot helps in easy bootstrapping rapid application development of spring applications.

Refer the following link for Spring-boot details

Spring boot details and quick start to write application

Spring has come up with framework for building a Spring boot project to implement Service broker APIs.

Spring-cloud-cloudfoundry-service-broker framework

This tutorial is built on top of this framework.

Lets start with developing/configuring a Service broker!

User can take help of any IDE to form a gradle project or can create maven project and convert it to a gradle project.

Being a gradle project, gradle is a compilation unit used for this Service broker.

One needs the following dependencies in build.gradle

Spring framework dependencies compatible with service broker APIs

Others dependencies like commons-lang for string manipulation and doing other stuff

The code for this entire exercise is available at

We will discuss the important concepts here, and show a part of code which is relevant for discussion.

The name of the application is search-service-broker.

Following is a snippet of dependencies we just mentioned, from build.gradle file.

Please refer tosearch-service-broker/build.gradlefor complete details.


<monscommons-lang33.4)< p=””></monscommons-lang33.4)<>








To start with, Spring boot framework requires a main application class, with main method, to bootstrap the application. Snippet is shown below.

Please refer for more details., args);

@EnableAutoConfigurationannotation auto-configure beans available in classpath.  Spring documentation can be referred to get more details on this.

@EnableJpaRepositoriesannotation, to enable jpa repositories. We would require some kind of repository to store/retrieve information about service instances and bindings.

For our Service broker, we have used hsqldb (hyper sql database). No need to install this database, though disk based installation is also available.

The dependency for the same is mentioned (inbuild.gradle) as

Spring boot starter data jpa, as highlighted above, provides functionality to store and retrieve data.

Now coming to broker implementation, the spring framework what we are using is compatible with Service Broker APIs.

The Spring framework already eased down a lot of the broker implementation part. We would require to extend/implement few classes there-in to get the the broker functionality in place.

The tutorial henceforth will discuss on using those core classes/interfaces to create a Service broker for search service.

Service instances are created by Cloud foundry platform for applications to use.

Lets discuss on instance creation implementation, which will be called by cloud foundry platform. framework lists the required methods to provision and deprovision service instances.

Following snippet shows class implementing this interface.

public class SearchInstanceController implements ServiceInstanceService

We will discuss this in details but meanwhile,

The service instances are required to be stored and retrieved from a repository.

For that we created following class

CrudRepositorySearchInstance, String

Extending CrudRepository provides default implementations for basic methods to store/retrieve objects from repository. For this demonstration, default basic methods are sufficient. User is free to provide implementations for specific methods, if required.

Repository class mentioned above has instance of SearchInstance which is nothing, but service instance to store and retrieve upon creation.

Coming back to creating class/methods to provision deprovision instances,, it is mandatory to implement method createServiceInstance as shown below

public CreateServiceInstanceResponse createServiceInstance(

String instanceId = request.getServiceInstanceId();

System.out.println(createServiceInstance () Creating service instance + instanceId);

SearchInstance instance = repository.findOne(instanceId);

throw new ServiceInstanceExistsException(instanceId,

.println(createServiceInstance() service instance created


.println(createServiceInstance() search service instance created);

On request by user or application, above method will be called by cloud foundry platform with following path

The appropriate instance_id would be supplied by platform only.

create service instance (details to follow for service)

The class lists other methods like, update service instance, delete service instance, which will be called by cloud foundry platform in a similar fashion as that of creating a service instance.

Once a service instance is created, that instance should be bind to the requesting application. provides methods to create and delete binding.

The binding also requires binding details to be stored in a repository. Same is shown in following snippet.

CrudRepositorySearchInstanceBinding, String

The searchInstanceBinding parameter to the above class is the binding instance.

Coming back to implementing interface, its the implementers responsibility to save bindings to the repository, as shown in following snippet.

public CreateServiceInstanceBindingResponse createServiceInstanceBinding(

CreateServiceInstanceBindingRequest request)

String methodInfo = createServiceInstanceBinding () ;

String serviceInstanceId = request.getServiceInstanceId();

System.out.println(methodInfo + , bindingId = + bindingId

SearchInstanceBinding binding = bindingRepository.findOne(bindingId);

throw new ServiceInstanceBindingExistsException(serviceInstanceId,

MapString, Object credentials = new HashMap();



binding = new SearchInstanceBinding(bindingId, serviceInstanceId,

return new CreateServiceInstanceAppBindingResponse()

This method is called by cloud foundry platform with path


and platform will take care of passing appropriate instance_id and binding_id.

The method listed above also forms credentials & URL for the service, which, the service consuming application can use to communicate with service.

Similarly, this class also provides other functions like, delete service binding which is called when an application unbinds itself from a service.

Catalog provides details for the service as plans, cost etc.

Catalog functionality is provided by the class filling in and returning the instance from the framework.

In our case, for demonstration purpose, hardcoded details include as shown below

Collections.singletonList(new ServiceDefinition(

A search service broker implementation, true, false,

Collections.singletonList(new Plan(search-plan,

But one can also include detailed information about plans, costs & other things and can store/retrieve catalog information from the repository.

Our search service is based on Lucene search APIs. Service does indexing and storing content in memory, though one can choose to do it on disk. For more details on Lucene refer to

Text supplied to the service by the application, needs to be index/stored somewhere so that, it could be searched via keywords. Each application binding to search service would require its own memory area (RAMDirectory class in Lucene API), and other essentials Lucene components. The association between these components to each application is established when we created the service instance.

The SearchEntity class has all the required components as its members, while our broker application maintains a map for service-instance-id and SearchEntity class, for storing/retrieving and using same components for each of the applications.

Snippet below shows the mapping association between instance-id and SearchEntity.

private static final MapString, SearchEntity searchEntityInst = new HashMapString, SearchEntity();

And SearchEntity, with components as its members

public SearchEntity(IndexWriter writer, RAMDirectory ramDirectory,

The core search functionality includes, indexing/storing, searching and deleting content, which is passed by the service consuming application.

Refer to the following classes for these functionalities

The service indexes the text which is supplied in the form of plain String, JSONObject as String, and JSONArray as String. The content can be searched and deleted with keywords. This will be demonstrated.

Pictorial representation of the discussed concepts can be seen below.

The picture depicts that, as cloud foundry gets requests, it is responsible for service creation, service binding-unbinding and service deletion. The service is contacted via broker.

Cloud-foundry applications require users to operate in organizations and spaces there-in.

Cloud-foundry documentation can be referred for more details.

In my set-up, I created myorg and two spaces namely, demo-broker and demo-apps.

Upon login, I am presented with these options to choose a space

I chose demo-broker space to deploy and configure Service broker.

The broker application is named as search-service-broker. The application is compiled with

The broker application is named as search-service-broker. The application is compiled with

The application needs to be pushed to cloud foundry platform.

I will be using cloud foundry command line tool to execute cloud foundry command.

To push an application to cloud foundry, it needs to have a manifest.yml file for command line to read the content from.

A file with basic minimal details was created as below

path build/libs/search-service-broker.jar

The path in above the file mentions a jar to be pushed. So to push, run command

The image above shows the output after executing the cf push command.

Once application is uploaded, details are displayed as

For demonstration purpose, credentials for spring-security to access spring broker are hardcoded.

src/main/resources/application.propertieshas the credentials, one may use a good sign-in mechanism.

By calling the catalog API with the URL provided by cloud-foundry and with above credentials, we can verify if the broker is deployed and is functioning.

Now lets go to other space and create instance of broker.

Register broker in new space with command below

– sudo cf create-service-broker search-broker cfsvc

– sudo cf enable-service-access search-service

(search-service is the name of broker application, mentioned in catalog)

– sudo cf create-service search-service basic my-search-svc

Logs (shown in following fig) for create-service command shows, platform called  method

public CreateServiceInstanceResponse createServiceInstance(

This method was discussed in Creating and deleting service instances section above.

Lets discuss about a controller class which enables applications to call and consume search service.

The code is designed as REST APIs inside class

Snippet below show methods to index, search and delete content respectively. Consumer of search service calls this method to perform various search operations.

public ResponseEntityString putContent(

@RequestBody String content) @RequestMapping(/search/instanceId)

public ResponseEntityString getContent(

@RequestParam(value = key, required = false) String key,

@RequestParam String content) @RequestMapping(value = /search/instanceId, method = RequestMethod.DELETE)

public ResponseEntityString deleteContent(

@RequestParam(value = key, required = false) String key,

The application consuming service needs to take care of the passed instanceId (generated while creating service).

Lets elaborate on how applications would know instanceId.

A simple Servlet application is developed to demonstrate the consumption of a service.

To begin with, lets deploy this application and bind it to the service we created.

– sudo cf bind-service search-service-consumer my-search-svc

After binding, the application should be restaged on platform. Logs will show binding command triggered platform to call the following method (we discussed in Creating and deleting service instance binding section).

public CreateServiceInstanceBindingResponse createServiceInstanceBinding(

After the application is restaged, the environment information of consumer application shows URL and credentials of the service.

The environment variable will be used and parsed inside the search consumer application servlet and call various search service APIs, to carry out search service core functionality.

The URL in the above image also shows instanceId appended to it. This instanceId belongs to the service we created.

The VACP_SERVICES is available as environment variable and can be obtained with

Once we get that, we can parse to get the URL, user and password.

String VCAP_SERVICES = System.getenv(VCAP_SERVICES);

// When running in Bluemix, the VCAP_SERVICES env var will have

// credentials for all bound/connected services

JsonObject obj = (JsonObject) new JsonParser()

EntryString, JsonElement serviceEntry = null;

SetEntryString, JsonElement entries = obj.entrySet();

for (EntryString, JsonElement eachEntry entries)

if (eachEntry.getKey().toLowerCase()

<ntains(search-service)) p=”” <=””></ntains(search-service))>

Could not find search-service key in VCAP_SERVICES env variable);

obj = (JsonObject) ((JsonArray) serviceEntry.getValue()).get(0);

We discussed Search Controller, performing core search functions. Lets demonstrate now to store, search delete content.

sudo curl -X POST -H Content-Type application/json -d This is plain text content to demostrate search /search/consumer

Same way lets post some jsons with following command

sudo curl -X POST -H Content-Type application/json -d json_keyThis is sample json /search/consumer

sudo curl -X POST -H Content-Type application/json -d services[idsearch-service-broker,namesearch-service,descriptionA search service broker implementation,bindabletrue,plan_updateablefalse,plans[idsearch-plan,namedefault,descriptionThis is a default search plan.  All services are created equally.,metadatacosts[amountINR0,unitMONTHLY],freefalse],tags[search,document],metadatalongDescriptionSearch Service,documentationUrl,providerDisplayNamePivotal,displayNameSearch Service,imageUrl,supportUrl,requires[],dashboard_clientnull] m/search/consumer

sudo curl -X GET -H Content-Type application/json -d contenthttp//

sudo curl -X GET -H Content-Type application/json -d /search/consumer?key=name

The aim of this tutorial was to develop a Service broker, put a service which can be provisioned/de provisioned via broker and exhibit the service consumption through a service consumer application. It was demonstrated with Search Service based on Lucene APIs. The search service can be enhanced to provide advance APIs by Lucene.

Thank you! Comments and questions are welcome.

For assistance with bosh-lite based cloud foundry installation, please refer to the following link.

6 comments onCloud Foundry Service Broker and Service

A very useful and well described article! Thanks Chandrakant.

Thanks Chandrakant. This helped a lot in creating a service broker.

The demo section has all but I found the following points confusing

1. cf create-service is this service instantiation or broker ?

2. Can I invoke the url from any consumer (deployed on the same space) dynamically and bind to it at runtime ? My requirement is to create an on-demand service and delete that after use ?

sudo cf create-service search-service basic my-search-svc

This command will basically create service instance. I didnt try invoking this at runtime , but you can give a try. You should know the name of broker applications and plans ahead of creating service instance.

cf enable-service-access email-service -o ******

Enabling access to all plans of service email-service for the org ****** as suma

Server error, status code: 400, error code: 260001, message: Service Plan Visibi

lity is invalid: service_plan is from a private broker

It looks like the broker is not accessible in your space to enable. I am using Bosh. What platform are you using. You might want to read documentation of platform. The solution might be at point where you are creating broker.

I am using trial version of PWS and working on to find a solution. It seems a free service plan will work. Will confirm.