This wiki space contains archival documentation of Project Bamboo, April 2008 - March 2013.
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.
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:
BSP follows a layered architecture:
There are two types of services in BSP:
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:
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.
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:
This design approach:
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:
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:
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:
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.
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 service.id, which is assigned by the framework) when publishing a service provider:
Interface name the service provider implements; a fully qualified Java reference type name e.g. "org.projectbamboo.bsp.services.core.person.service.Persons".
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.
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 service.pid 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 firstname.lastname@example.org.
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.
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.
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 email@example.com.
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: