COSMOS Design 204959

Provide reusable CMDBf APIs for adopters that intend to provide a CMDBf query/registration service

Change History

Name:	Date:	Revised Sections:
Ali Mehregani	10/04/2007	Initial version

Workload Estimation

Rough workload estimate in person weeks

Process	Sizing	Names of people doing the work
Design	1	David/Ali
Code	2	David/Ali
Test	1	David/Ali
Documentation	0.4
Build and infrastructure	0.2
Code review, etc.*	0.2
TOTAL	4.8

Terminologies/Acronyms

The terminologies/acronyms below are commonly used throughout this document. The list below defines each term regarding how it is used in this document:

Term	Definition
MDR	management data repository
CMDBf	specification for a CMDB that federates between multiple MDRs[1]
federating CMDB	the CMDB that federates between MDRs, offering a common access point to clients and correlating identifying record data
CMDB	configuration management database
SML Repository	repository of SML documents hosted in COSMOS with an established API (see bugzilla 179828)
Query service	MDRs make data available to Clients via a Query service. Queries may select and return items, relationships, and/or graphs containing items and relationships.

Purpose

This enhancement is associated with bugzilla 204959.

The purpose of this enhancement is to refactor the CMDBf query code to make it more reusable. The SML repository already defines a set of APIs related to the CMDBf query. This set needs to be migrated to org.eclipse.cosmos.dc.cmdbf.query so that it can be reused by contributors who intend to provide a query service for a data provider.

Another purpose of this enhancement is to implement the registration transformation code, and provide reusable APIs for the CMDBf registration service.

This document will detail out the structure of the code and the minimum API set required to be implemented by contributors. The document will include code snippets to illustrate the simplicity in leveraging the available APIs. As part of the implementation of this enhancement the SML repository will be modified based on the refactored code. The set of classes provided in org.eclipse.cosmos.dc.cmdbf.query will be divided into the following sets:

1. CMDBfCommon.jar
2. CMDBfQueryTransformation.jar
3. CMDBfQueryService.jar
4. CMDBfRegistrationTransformation.jar
5. CMDBfRegistrationService.jar

The CMDBfCommon module will include any code that will be required by two or more of the other modules. The dependency of the modules is discussed in more details under the 'Implementation Detail' section. The set included under CMDBfQueryTransformation.jar will contain any necessary code for clients who intend to build a CMDBf query and consume a query response. It performs the following transformations:

• CMDBf XML query document > POJO representation of the query
• POJO representation of the query > CMDBf XML query document
• CMDBf XML query response > POJO representation of the query response
• POJO representation of the query response > CMDBf XML query response

Adopters can choose to use CMDBfQueryTransformation.jar as is or have it tweaked based on their needs. What will be included in this jar file will be a concrete implementation of the transformations. Similarly, CMDBfRegistrationTransformation.jar will include a concrete implementation of the transformation required from an XML registration request to a POJO representation (and vice-versa).

CMDBfQueryService.jar will contain the necessary code for processing a query that conforms to CMDBf. This set will allow the user to provide implementation of selector handlers that are specific to a data provider. CMDBfQueryService.jar cannot be used as-is and will require a minimum API set to be implemented. Similarly, CMDBfRegistrationService.jar can be used by contributors to help in processing a registration request.

Requirements

The following is the list of requirements that this enhancement will address:

1. Checking the conformance of a CMDBf query against its schema
2. Checking the conformance of a CMDBf registration request against its schema
3. Transformation of CMDBf XML query from/to a POJO representation
4. Transformation of CMDBf XML registration from/to a POJO representation
5. A common method of processing a CMDBf query
6. A common method of processing a registration request

Transformations

Query

CMDBf specifies an XML-based syntax by which queries are submitted to the query service, which reports back a query result from the available MDRs, also using XML syntax. As part of our implementation of the query service, we internally accept POJOs to represent a graph of the query, and return the query result as a set of POJOs. The job of the transformers is to convert POJOs to and from the XML syntax detailed in the CMDBf specification.

As part of COSMOS Design 200222, a set of query transformations and an SML-repository-specific query service were designed and implemented. In an effort to make these components reusable, the query transformations will be refactored to share common components needed by other libraries in this design. The initial candidate classes to be moved to the common module are IXMLWritable, QueryServiceUtil (which will be renamed) and some of the fields in IQueryTransformerConstants.

In addition, the previously implemented packages will be renamed to include the word "provisional", which in the API contract specifications we are reusing from the TPTP project, indicates the behavior can change in the implementation, but the API signatures can't. Each class in these provisional APIs will include the annotation @provisional in the class comment.

Here is a simple example that illustrates the incoming query input transformation:

InputStream inputStream = new ByteArrayInputStream(example1().getBytes());
Query query = QueryInputTransformer.transform(inputStream);

Assume that example1() returns a String containing the XML syntax for a <query> as specified in the CMDBf spec.

Registration

CMDBf specifies a registration service by which MDRs register themselves with the federating CMDB. The process for registration involves an XML-based transaction, similar to how the query service works. This enhancement will provide a transformer to convert a registration request from XML to a POJO graph structure, and will also provide the reverse of that transformation. In addition, it will provide another transformer that will convert a registration response output by the MDR from a POJO graph structure to the XML-based syntax expected by the CMDBf spec, and will again provide a reverse of that transformation. The reverse transformations are needed by some clients of the registration service, and also are useful in unit testing of the implementation.

The following new classes and methods will provide these transformations:

static public RegisterRequest org.eclipse.cosmos.dc.cmdbf.registration.transform.provisional.RegistrationInputTransformer.transform(InputStream)
static public InputStream org.eclipse.cosmos.dc.cmdbf.registration.transform.provisional.RegistrationInputTransformer.transform(RegisterRequest)
static public RegisterResponse org.eclipse.cosmos.dc.cmdbf.registration.transform.provisional.RegistrationOutputTransformer.transform(InputStream)
static public InputStream org.eclipse.cosmos.dc.cmdbf.registration.transform.provisional.RegistrationOutputTransformer.transform(RegisterResponse)

RegisterRequest and RegisterResponse POJOs will consist of APIs and classes that match or closely mirror the corresponding element names in the CMDBf data model.

Here is a simple example that illustrates the incoming registration input transformation:

InputStream inputStream = new ByteArrayInputStream(example1().getBytes());
RegisterRequest registerRequest = RegistrationInputTransformer.transform(inputStream);

Assume that example1() returns a String containing the XML syntax for a <registerRequest> as specified in the CMDBf spec.

Open Issues/Questions

All reviewer feedback should go in the Talk page for 204959.

---