BSP Services Architecture Overview for Developers

Created by SM
Last updated: Apr 18, 2013 by Former user (Deleted)Version comment

In an early blog post I linked to the BSP Reference Service, an early – and now deprecated – proof-of-concept service used to describe the architecture in which web services to be hosted on the Bamboo Services Platform (BSP) would be implemented. In this post I will describe that architecture with reference to examples in the current code base.

This post is meant to help developers understand how to design services for deployment on the BSP.

Most of the content in this post originates in architecture designed and described by Fernando Alvarez, IT Architect at Berkeley and the chief designer and developer of core BSP services; some of the content is taken directly from his prior posts on this wiki, or from discussions between Fernando and other BTP developers.

High level architectural description

Click for larger image.

The high-level descriptions of the BSP's three-layered service architecture are:

  • The Resource-oriented Architecture (ROA) layer functions as an HTTP adapter for RESTful (Representational State Transfer) service invocation.
  • The Service-oriented Architecture (SOA) layer functions as the central point for service invocation and inter-service integration.
  • The Object-oriented Architecture (OOA) layer functions as the domain for the service. As such it contains all of the model logic. In cases where the service is a proxy, the functionality is performed by an external provider; while the components in this layer are responsible for bridging the gap between the features, syntax, and content of the 3rd-party provider and the BSP service.

Looking at each of these in somewhat greater detail, I'll augment general descriptions with references to the functionality of the Person Service and links to the code that implements that service's architectural layers.

The layers in greater detail

A service is generally composed from three OSGi bundles, corresponding to the three layers of the architecture listed above (more on implementation below).

ROA Layer (Resource)

The Resource classes at the ROA layer of the architecture accept HTTP requests, handle parameters, and handle any payload in the body of the request, e.g., an XML document in an HTTP POST.

The characteristics of the components resident in the ROA layer are:

  • Functions as the JAX-RS endpoint for the service
  • Configured as an Apache CXF jaxrs:server
  • Encapsulates both JAX-RS annotations and JAXB bindings
  • Handles HTTP API requests based on content type; currently supports text/html and application/xml
  • Includes minimal business logic
  • Communicates with SOA layer via OSGi service calls

Using the the Person Service as an example, the ROA layer handles HTTP calls documented in the Person Service Contract Description. These calls facilitate the creation, reading/listing, update, deletion of a "Bamboo Person Identifier" (BPId), which is the core data element in the principal resource associated with the Person Service (see Entity Diagram).

ROA layer code is organized under a /resource directory in the codebase.

SOA Layer (Service)

Resource classes make an OSGi service call to the SOA layer. This is the service provider to the ROA layer; it takes responsibility for doing the processing in the BSP's OSGi environment to fulfill the request. It is also the integration point to other services on the BSP. Services integrate with each other at the SOA layer, rather than having to make intra-container HTTP calls.

The characteristics of the components resident in the SOA layer are:

  • Provides an interface-based API accessible to all services resident in the same FuseESB instance (container)
  • Includes minimal business logic
  • Communicates with OOA layer via package dependencies

For the Person Service, the SOA layer responds to calls from the Person Service's ROA layer, and to calls initiated by other BSP-hosted services. It fulfills those calls by calling in turn on the OOA layer of the service, described below.

SOA layer code is organized under a /service directory in the codebase.

OOA Layer (Object/Domain)

The OOA layer is where we expect the majority of domain logic to reside.

The most likely expected scenario is that developers are likely not building services from scratch; this is a corollary of our emphasis on Project Bamboo's technology role as software integration over software innovation.

In many cases the service developer is wrapping extant code, which might be lightly modified for deployment on the BSP or elsewhere on the net. (For example, the Morphology Service, implemented at Tufts University as Groovy code, has been wrapped for deployment in the BSP's OSGi environment.)

The characteristics of the components resident in the OOA layer are:

  • Provides an Java API accessible to all bundles that import it's exported package
  • Implements any necessary interface to a backing service provider

For the Person Service, the OOA layer handles calls from the service's SOA layer. It fulfills those calls by implementing appropriate business logic, including persistence of the Person Service model, i.e., the association of a Bamboo Person Identifier with one or more "SourcedID" objects, as depicted in the Entity Diagram included in the Person Service developer documentation on this wiki.

OOA layer code is organized under a /domain directory in the codebase.

Implementing the architectural layers as OSGi bundles

As mentioned above, a service is generally composed from three OSGi bundles, corresponding to the three layers of the architecture listed above. It's possible that additional bundles must be implemented and deployed to support a complex service.

The degree to which there is complexity within the bundles depends wholly on the service's point of departure. In the common case in which extant code comprises the bulk of the OOA layer, an extant WAR file may become the OOA layer bundle. In these cases, the SOA and ROA are simply integration layers.

Some high level build and deploy orientation may be helpful:

  • Maven: There's a project POM with dependencies identified. The project POM specifies how the code will be deployed, i.e., as a "bundle" --- the core component of an OSGi deployment. A bundle is, basically, a JAR with additional metadata included in the manifest.
  • Bundles: are deployed into OSGi environment, either singly or grouped as "features"
  • Spring Framework wiring specifies a path to the service's endpoint, what singletons need to be instantiated, and which services are dependencies that need to be called across the BSP's OSGi layer. Spring configuration is in a beans.xml file, usually one per bundle/project.
  • Common dependencies (such as database names and configuration) are specified in a common POM (the BSP POM).

Service developers are encouraged to employ a combination of multi-module and parent POMs (Maven Project Object Model) to define the overall structure of the service project and manage its dependencies:

  • A project POM owns the layers (ROA, SOA, and OOA) as modules
  • Separate "type" POMs determine the actual characteristics of each layer POM. For example, a Resource POM might inherit all of the JAX-RS, JAXB, CXF, etc. dependencies and plugins required to function as a RESTful service from a RESTWS POM; but its build is driven by the overall module-owning project POM.

Code examples at the three architectural layers

For a more complex example, the Person Profile Service represents a more complex implementation. Its code may be located in the person-service hierarchy of the codebase as follows:

Conclusion

While this post gives a brief overview of BSP service architecture, developers are invited to contact the BSP Platform team with questions or for additional detail. We can be reached at platform@lists.projectbamboo.org.

(To subscribe to the Platform list or any other public list maintained by Project Bamboo, please visit the Project Bamboo Technology E-mail Lists page of our wiki.)