Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

COSMOS Design 200222

Revision as of 15:41, 28 August 2007 by Amehrega.ca.ibm.com (Talk | contribs) (''' Implementation Detail ''')

Adding support for the CMDBf query service on top of the SML repository

Change History

Name: Date: Revised Sections:
David Whiteman 8/21/2007
  • Initial version
David Whiteman 8/27/2007
  • Added use cases
Ali Mehregani 8/28/2007
  • Modified purpose & requirements
  • Added implementation details & task breakdown
David Whiteman 8/28/2007
  • Expanded use cases
  • Added test coverage

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
  • - includes other committer work (e.g. check-in, contribution tracking)

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

According to the CMDBf specification, a repository will need to provide two services for it to be considered as an MDR:

  1. Registration
  2. Query

The implementation of these services is the minimum requirement for a repository to be integrated with a federating CMDB. During the i6 time-frame a query service will be implemented for the SML repository. The service will allow clients to query the available data with the XML query language described in the CMDBf specification. The output of the query will also be in XML format, which the client is expected to understand.

Currently clients are expected to interact with the SML repository via a set of convenience APIs. This enhancement does not imply the removal of such APIs. They may need to slightly be modified to accompany the new changes but they can still be reused by clients who have no intentions of leveraging the new query service.

There will likely be common set of code between the COSMOS client and the SML repository. It's expected that this common set will reside under the data collection subproject. One of the primary objectives of this document is to identify this reusable set of common code.

Requirements

This section lists the requirements of this enhancement:

  1. Querying the SML repository using the XML query format specified in the CMDBf specification
  2. Producing query results to clients using the XML response format specified in the CMDBf specification

Use Cases

For the following use cases, the SML repository acting as an MDR will contain the data described in the org.eclipse.cosmos.rm.example.datacenter COSMOS plug-in:

Use Case 1: Retrieve All Computers Using Red Hat Linux 8

  1. Client connects to the SML repository
  2. Client submits request for the CMDBf query service operation
  3. Client sets the argument of the operation to a query that will retrieve: all computers with an installed OS with a brand name of "Red Hat 8"
  4. Client runs the operation
  5. Client retrieves the response from the operation's output

Use Case 2: Retrieve All Computers With At Least 2000 MB RAM

  1. Client connects to the SML repository
  2. Client submits client request for the CMDBf query service operation
  3. Client sets the argument of the operation to a query that will retrieve: all computers with a RAM value greater than or equal to 2000 MB.
  4. Client runs the operation
  5. Client retrieves the response from the operation's output

Use Case 3: Retrieve All Server Software

  1. Client connects to the SML repository
  2. Client submits client request for the CMDBf query service operation
  3. Client sets the argument of the operation to a query that will retrieve: all server software.
  4. Client runs the operation
  5. Client retrieves the response from the operation's output

Use Case 4: Retrieve Serial Numbers and Disk Drive Capacities

  1. Client connects to the SML repository
  2. Client submits client request for the CMDBf query service operation
  3. Client sets the argument of the operation to a query that will retrieve: the serial numbers and disk drive capacities of all computers.
  4. Client runs the operation
  5. Client retrieves the response from the operation's output

Use Case 5: Retrieve All Non-database Software on Linux Machines

  1. Client connects to the SML repository
  2. Client submits client request for the CMDBf query service operation
  3. Client sets the argument of the operation to a query that will retrieve: all software installed on Linux machines that is not a relational database.
  4. Client runs the operation
  5. Client retrieves the response from the operation's output

Implementation Detail

The following section details out the implementation of the CMDBf query service for the SML repository. As mentioned before, the SML repository has defined a set of convenience APIs that it is currently leveraged by clients. The implementation of this enhancement will need to understand queries based on the CMDBf specification and make use of the convenience APIs to fetch the required data.

Scope

Using the instanceIdSelector under the itemTemplate is equivalent to fetching documents with an org.eclipse.cosmos.rm.repository.provisional.resource.ISMLMetadata that has a specific ID. The property, xpath, and the record type selectors will all be supported under the itemTemplate element. Clients will also be able to use the propertySubsetDirective to only return a set of desired properties.

The only valid relationship between items stored in an SML repository is the 'references' relationship. Item i1 references i2 if and only if there exists an inter-document reference of i2 in the SML document representation of i1. All relationshipTemplate elements should have a record type selector with:

No other selectors should be used in conjunction with this relationship.

Architecture

The flow diagram below depicts how the query service will process an input. The service will apply the selectors in the following order:

  1. instanceIdSelector
  2. recordTypeSelector
  3. propertyValueSelector
  4. xpath1Selector

The instance and record selectors are faster and effective mechanisms of narrowing the result set for a query, whereas the property and xpath selectors are more processor intensive operations that are applied in the end.

QueryService-FlowDiagram.png

The CMDBf query service will be implemented as an operation of the SML repository. Similar to the validation, import, and export operations, a client will first need to establish a connection to the repository to obtain the CMDBf query operation. The operation will take an input stream as argument and will produce an input stream as output. The argument is expected to be set to the XML query and the output will be the query response.

There will be a reusable component under the data collection subproject that will need to transform an XML query into a graph that is understandable by the query service. There also needs to be a common component to convert a graph representing a query response into an XML document that conforms to the CMDBf standard. The image below depicts the interaction between the client, the SML repository, and the query service. The input and output transformers are reusable components that will reside under the data collection subproject.

QueryService-Interactions.png

Test Coverage

Unit tests will need to perform the following tests:

  • Complex tests outlined in the Use Cases section of this document
  • Tests using an identity selector, one with 0 results and one with exactly 1 result. More than one result will be logged as a failure.
  • Tests using a property value selector, one for each of the following operators:
    • equal (caseSensitive attribute set to true, set to false, and omitted; negate set to true, false, or omitted; string, boolean, time, and integer types used)
    • less (negate set to true, false, or omitted; string, time, and integer types used)
    • lessOrEqual (negate set to true, false, or omitted; string, time, and integer types used)
    • greater (negate set to true, false, or omitted; string, time, and integer types used)
    • greaterOrEqual (negate set to true, false, or omitted; string, time, and integer types used)
    • contains (caseSensitive attribute set to true, set to false, and omitted; negate set to true, false, or omitted)
    • like (caseSensitive attribute set to true, set to false, and omitted; negate set to true, false, or omitted)
    • isNull (negate set to true, false, or omitted)
  • Tests using a record type selector:
    • type is exact type match
    • type requested is supertype of existing record
  • Tests using an XPath selector:
    • using correct syntax for expression, with and without results
    • using incorrect syntax for expression
  • Tests combining 2 item templates and a relationship template, that use a drop selector to exclude the relationship template and the 2nd item template
  • Tests using a property subset directive
    • with two properties listed
    • with no properties listed
  • Tests using relationship cardinality, using minimum, maximum, and both attributes

Task Breakdown

  1. Create graph representation of query input and response
  2. Create the input transformer
  3. Create the output transformer
  4. Add in the query service as an SML repository operation
  5. Create a generic framework for implementing selectors
  6. Add in the instance id selector
  7. Create JUnit tests for the instance id selector
  8. Add in the record type selector
  9. Create JUnit tests for the record type selector
  10. Add in the property value selector
  11. Create JUnit tests for the property value selector
  12. Add in the xpath selector
  13. Create JUnit tests for the xpath selector
  14. Implement the property subset directive
  15. Ensure that all selectors work with itemTemplate elements
  16. Implement the relationship template constraint
  17. Add Junit tests for querying items and relationships

Open Issues/Questions

All feedback should go in the Talk page for 200222.


Back to the top