Page Tree:

Child pages
  • Service Catalog Service Description and Assumptions - v0.9-alpha

This wiki space contains archival documentation of Project Bamboo, April 2008 - March 2013.

Skip to end of metadata
Go to start of metadata


Summary Description:

The Service Catalog service provides information about the services offered by the Bamboo Service Platform. Based on this information, service consumers can see what functionality a service provides and how, select which service provider best meets their needs, and invoke the service.

Full Description

The Service Catalog service provides a service consumer (e.g. end user, application developer) with access to information about available services developed for use in, and deployed through, the Bamboo Service Platform (BSP). This information includes both a reference to description of the service's RESTful API ( i.e. a contract that specifies how the service will perform Internet-based HTTP GET, POST, PUT, and DELETE calls) as well as a profile of the service listing all service providers and any supporting services that are potentially involved in implementing the functionality specified by the service. Using the Service Catalog service, a service consumer interested in some set of functionality can:

  • Obtain information about what services are currently available
  • What functionality a service provides and how
  • How to invoke a service over the Internet
  • Select from among multiple candidate service providers for a service; service providers are differentiated by the organization that developed the service provider, and by the version of the service a service provider supports.

Key Concepts

Information Provided by the Service Catalog Service
  • If a service consumer wishes to know what functionality a service provides and how, the Service Catalog service will return a Service Profile.
  • If a service consumer wishes to obtain information about what services are currently availablethe Service Catalog service will return a Service Profiles list. For each available service, the Service Profiles list (an XML document) includes both a link to the service's Service Description as well as a summary version of its Service Profile.
BSP Architecture

BSP follows a layered architecture:

  • REST Oriented Architecture (ROA) tier functions as an HTTP adapter for BSP services
  • Service Oriented Architecture (SOA) tier facilitates inter-service communication, including access to BSP core services (e.g. Result Set Cache, Notification)
  • Object Oriented Architecture (OOA) tier implements the functional domain

There are two types of services in BSP:

  • ROA tier services exposing a Java interface that implements a RESTful API. ROA services are dependent on corresponding SOA tier services for the actual implementation of service functionality
  • SOA tier services exposing a Java interface API that provide the essential service functionality by wrapping the components in the OOA tier, which itself may be either a set of components (e.g. Java classes) or a proxy for some set of components implemented outside of the BSP architecture

To illustrate this architecture, consider The Places-Text service which provides a RESTful API for obtaining geo-parser data from a text. In the diagram at right:

  • PlacesInTexts is a Java interface that specifies a RESTFul API
  • PlacesInTextResource is a Java class that implements PlacesInTexts and handles the HTTP method calls made to the service by invoking the PlacesInTextService service
  • PlacesInTextService is a Java interface that exposes an API for obtaining geo-parser data from a text which can be called from within BSP by Java classes in the ROA or SOA tier
  • PlacesInTextServiceProvider is a Java class that implements PlacesInTextService service functionality by combining calls to BSP core services (e.g. Notification, Result Set Cache)  with calls to GeoParserService
  • GeoParserService is a Java interface that specifies the behavior that must be exhibited by a geo-parser in BSP
  • CalaisGeoParserProxy and UnlockGeoParserProxy are Java classes that implement GeoParserService and that provide HTTP-based access to the 3rd-party geo-parser engines that perform the actual geoparsing

BSP Architecture Example

BSP Services vs. OSGi Services

One of the benefits obtained by basing BSP on FuseESB (i.e. Servicemix) is that it includes a service registry (specifically, an implementation of the OSGi Service Framework) that facilitates the publishing, finding, and binding of services. In the OSGi Services Framework, a service is a pair consisting of a Java interface and some Java class that implements the interface. There can be multiple "services" in the framework for the same interface, with each Java class potentially implementing more than one interface. It can be said that the framework does not as such have a concept of a service (as it is understood in the SOA literature) per se, and that which the framework calls a service is in an abstract sense really a service provider.

Conversely, in BSP a service is an abstraction composed of a contract (eponymously the service) and a service provider. For ROA (i.e. RESTful ) tier services, this means a service is a Service Description plus the set of components (e.g. Java classes, SOA tier services) that together form the service provider. For SOA tier services, this means a Java interface and some Java class that implements the interface plus any other SOA tier services that are required to completely fit the functional footprint.

Clearly there is a semantic disconnect between these two approaches to "services" that must be reconciled if the Service Catalog is to provide the information required by service consumers while leveraging the flexibility, portability, and scalability provided by the OSGi Service Framework.

Service Catalog Service Design

The goal of the BSP Service Catalog design is to reconcile the semantic differences between the OSGi Service Framework and BSP's definition of a service. Fundamentally, the Service Catalog service will wrap the OSGi Service Framework with an abstraction that encapsulates the framework while adding the necessary constructs to obtain the information to be provided by the Service Catalog service.

The approach taken is to follow a service provider framework pattern, a system in which multiple service providers implement a service, and the framework makes the implementations available to its clients, decoupling them from the implementations. There are three essential components of a service provider framework:

  1. A service interface, which providers implement. In the Service Catalog this API will be provided by the service developer.
  2. A provider registration API, which the system uses to register implementations, giving clients access to them. In the Service Catalog, this will be provided by the OSGI Service Framework; developers will employ a Spring Dynamic Modules (DM) approach for publishing services and their metadata.
  3. A service access API, which clients use to obtain an instance of the service. The service access API typically allows but does not require the client to specify some criteria for choosing a provider. In the absence of such a specification, the API returns an instance of a default implementation. In the Service Catalog, this will be provided by the Service Catalog service itself..

This design approach:

  • Reduces the amount of coding required to implement the solution by delegating service provider publish / find / bind to the OSGi Service Repository in FuseESB
  • Promotes consistency and minimizes the need for programming level knowledge of the OSGi Service Repository by employing Spring DM-based configuration to publish service providers
  • Extends the capabilities of the OSGi Service Repository to include intrinsic version support for service providers independent of bundle versioning
  • Ensures that the most appropriate service provider candidate is selected to service the client
Service Providers and SOA Tier Services

In many cases, there is a one-to-one relationship between the service and its service provider. In these cases, publishing the service, finding the service, and then binding to the service is straightforward and could be done through Spring DM configuration when the service and its consumers are built; essentially a static, development-time configuration approach.

However, there exists a set of cases where multiple service providers exist, for example when:

  • The BSP service is a proxy for third-party components (e.g. a GeoParser service provided by to two or more geo-parsers) the existence of which may only be known at run-time, and whose availability is not guaranteed
  • The service provider, or rather a subclass of a more general service provider, is dependent on parameters specific to a client invocation (e.g. a Document Handler service returning a typed document handler which extends a generic document handler )
  • A given service provider is itself available in multiple instances, i.e. as different versions

In these cases, a dynamic, run-time approach is required. It is in providing such a dynamic service find and bind function that the Service Catalog service provides its greatest value in that it:

  • Ensures that the finding and binding of / to multiple service providers implementing a service is decoupled from the client
  • Differentiates between candidate service providers in a well defined and consistent manner
  • Is responsive to client run-time needs and so provides the most appropriate service provider available

The Service Catalog Service considers two Service Provider entries in the OSGi Service Registry to be semantically equivalent for the purposes of returning a service provider for a service if the values for the keys in red below are all equal. Although the underlying OSGi Service Registry does not enforce uniqueness when publishing a Service / Service Provider, the Service Catalog Service guarantees that a single value will be returned when multiple Service Providers are semantically equal by:

  1. If only one of the duplicates has defaultServiceProvider set to true, then that Service Provider will be returned
  2. If none of the Service Providers is the default, or more than one has defaultServiceProvider set to true, then the first element resulting from the sorting of the duplicates by their ranking (highest first) and then by their (lowest first) will be returned.

Services and their service provider implementations will change over time. While the OSGi Service Registry's selection algorithm is adequate for choosing amongst service versions (assuming usage follows Service Metadata below and the employment of a Filter) it is less satisfactory when distinguishing amongst multiple service provider candidates whose distinctive characteristic is the version of the service API they support.

Service Metadata

Information about a service provider will be stored in the OSGi Service Framework.The framework maintains a Java Dictionary object for each service provider. At a minimum, BSP service developers are required to define the following set of metadata (except for, which is assigned by the framework) when publishing a service provider:



Developer Notes

SP List


objectClass *

Interface name the service provider implements; a fully qualified Java reference type name e.g. "".

Cf. description.


(tick) *

Unique identifier assigned sequentially by the OSGi Service Framework at bundle start time - cannot be changed by either the developer or the Service Catalog service. These values are NOT persistent across restarts of the Framework, and so cannot be used to persistently identify anything

Automatically assigned; developer does not supply a value for this metadata element.


(tick) *

Uniquely identifies the service / service provider and persists across multiple Framework invocations. It is assigned by Project Bamboo during an out of band process when requesting that a service provider be included in a given BSP release.Service providers that lack this value will be ignored by the Service Catalog Service. If the service provider is a Resource class, then the value will be considered the identifier for the RESTful service as well.

Contact a Berkeley-based member of Project Bamboo's Scholarly Services team to initiate the out-of-band process described in the description at left. If you are not already in direct contact with such a team member, inquire at



service.ranking *

Ranking used by framework algorithm when selecting from amongst multiple service providers.

Service ranking should be an integer value in the range 0-9. Higher numbers will be selected over lower numbers if the framework algorithm by which the catalog selects a service provider is invoked; however, existence of more finely-grained metadata, specifically serviceProviderSupportedVersionsRange, will keep the framework algorithm (and service.ranking value) from coming into play. That is, the value of this metadata is only utilized in choosing a service provider if the service catalog algorithm is unable to select a single service provider based on more finely-grained metadata.




URL to description of the RESTful service if the service provider is a Resource class; otherwise URL to a description of the service provider.

  • For a Resource class, provide a URL to the service contract documentation maintained by Project Bamboo
  • Otherwise, provide a URL to a 'parent' documentation page maintained by the vendor or supporter of the service provider. This documentation page might be a formal API description (e.g., Javadoc); or might be a web or wiki page, which may itself contain links to a formal API description, a version-controlled codebase, etc.



service.description *

Description of the RESTful service if the service provider is a Resource class otherwise a description of the service provider.

A brief, human-readable text description (abstract) of the service, similar to (and perhaps copied from) a summary description given at serviceDescriptionLocation.



service.vendor *

Entity responsible for the service.




Only required if the service provider is a Resource class. The value should be the same as it appears in the address attribute of the jaxrs:server element, e.g. if "<jaxrs:server id="persons" address="/persons>" then the value should be "persons"

Cf. description. Expected to be NULL if the service provider is not a Resource class.




For a Resource class, this value identifies the version of the RESTful API exposed by the service provider; otherwise, this value identifies the version of the service provider.

For Resource classes, the value (RESTful API version) is determined by developer in consultation with personnel responsible for service version governance. Currently, initiate an out-of-band process to determine an appropriate value by contacting a Berkeley-based member of Project Bamboo's Scholarly Services team. If you are not already in direct contact with such a team member, inquire at

If the service provider isnota Resource class, the value of this metadata is determined by the service.vendor.

In either case, the value of this metadata element conforms to the major.minor.micro.qualifier semantics described in theOSGI versioning approach to Semantic Versioning.




List of other services used by this service

A comma-delimited list of objectClass values (see above), where the fully-qualified Java reference types comprise the services used by this service.




Name of the service / service provider.

A human-friendly name of the service or service provider, e.g., "Notification"; "Unlock geoparser"




Specifies whether a service provider is functional ot system

A functional service provider will appear in the Service List




Whether or not this service provider is the default service provider for the service.

TRUE if this is the default service provider for a service; FALSE if it is not; NULL if the service provider is a Resource class. In any deployment, it is intended that only one Service Provider is declared to be the defaultServiceProvider for any given objectClass.




Range of service API versions supported by this service provider - see OSGi versioning approach for details.

Note that "service API versions" referenced in the description of this metadata element are the values of serviceVersion elements described in Service Catalog metadata for Resource classes; see above.




Email for use in contacting the resource responsible for supporting the service provider.

An e-mail address associated with a project or team (e.g., a mailing list address) is strongly preferred to an individual's e-mail address. This preference is meant to insulate Service Catalog metadata from personnel changes at owning serviceVendor institutions or organizations.



Key determined by service developer

Additional metadata about a service provider

At the service developers discretion, additional metadata can be included in the Service Profile



* Defined by OSGi


The ability to store and disseminate the information provided by the Service Catalog assumes that the following changes to service development practices will be applied. Failing to do so will preclude the service in question from being included in any information provided by the Service Catalog:

  1. All BSP service developers will now include a set of metadata when publishing a service. The required set of metadata will conform to the BSP standard as defined herein as of the release in which the Service Catalog service is deployed.
  2. All BSP services, whether they be ROA or SOA tier services, will now be published  to the OSGi Service Framework. This means that in addition to providing the metadata required to publish the service, all ROA services will be re-factored to include a Java interface (if one doesn't already exist) in the ROA tier and have the service's resource class implement it.
  3. While the OSGi Service Framework supports registering a service under multiple interfaces (a many-to-many relationship), service developers will establish a one-to-one relationship when publishing. That is, if a service provider implements multiple interfaces, it should be published multiple times, once for each interface.


  • FuseESB implementation of the OSGi Service Framework

Background Documentation