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

Difference between revisions of "COSMOS Design 208584"

Line 201: Line 201:
  
 
All reviewer feedback should go in the [[Talk:COSMOS_Design_208584|Talk page for 208584]].
 
All reviewer feedback should go in the [[Talk:COSMOS_Design_208584|Talk page for 208584]].
 +
 +
==References==
 +
{{reflist}}
  
 
----
 
----
 
[[Category:COSMOS_Bugzilla_Designs]]
 
[[Category:COSMOS_Bugzilla_Designs]]

Revision as of 20:17, 5 December 2007

Update CMDBf query and registration service implementations to 1.0 spec level

This is the design document for bugzilla 208584. This documents the approach we are taking to update the query and registration service implementations from the CMDBf 0.95 spec to CMDBf 1.0.

Change History

Name: Date: Revised Sections:
David Whiteman 11/21/2007
  • Initial version
Ali Mehregani 12/05/2007
  • Added section 'Service Metadata'

Workload Estimation

Rough workload estimate in person weeks
Process Sizing Names of people doing the work
Design 1 David
Code 1 David/Ali
Test 0.4 David/Ali
Documentation 0.2
Build and infrastructure 0.2
Code review, etc.* 0.2
TOTAL 3.0

Terminologies/Acronyms

The terminologies/acronyms below can be used throughout this document. Note: These definitions are not meant to be general definitions of these terms, but rather refer to how the terms are used within this design document as applied to COSMOS.

Term Definition
CMDB Configuration Management Database as defined by ITIL
CMDBf CMDB Federation Specification
MDR Management Data Repository as defined by CMDBf
Federating CMDB As defined by the CMDBf spec, a CMDB that federates data from multiple MDRs
SML Service Modeling Language - An XML-based language used for modeling
SML Model A set of SML compliant resources
SML Repository The SML Repository describes any SML model together with a set of COSMOS API used to add new SML resources to the SML model and to query the SML model. In COSMOS, the SML repository has been implemented as an MDR.
CMDBf query MDRs make data available via a query service defined in the CMDBf specification. The input and output of a CMDBf query is a structured XML document described in the specification.
CMDBf modules The modules provided by COSMOS' CMDBf framework that adopters can directly extend to implement a query and/or registration service for their data source
CMDBf toolkit The code provided by COSMOS that interacts with the query and registration service framework, and provides the WSDM endpoints needed to communicate with the federating CMDB

Purpose

This enhancement is associated with bugzilla 208584.

As part of a previous enhancement[1], the COSMOS team provided a CMDBf framework that allowed adopters to implement a CMDBf query and registration service. That enhancement was implemented per the CMDBf spec, version 0.95. Since that time, the CMDBf spec has been updated to version 1.0.

The purpose of this design is to describe the approach we are taking to update the query and registration service implementations from the CMDBf 0.95 spec to CMDBf 1.0.

Spec Change Impacts

The following spec changes impact the implementation of the CMDBf toolkit in COSMOS. Here are the major highlights:

  • CMDBf 1.0 introduces the concept of a recordMetadata element to the query response that contains "common information about the record itself". There is also a new recordMetadata attribute on the propertyValue element that "indicates the property to be evaluated is in the <recordMetadata> element of the record".
  • recordTypeSelector and propertyValueSelector are renamed and aggregated under a common parent element, recordConstraint. The new names are listed in the spec changes summary table.
  • xpath1Selector is renamed xpathExpression, and is now mutually exclusive of all other subelements commonly shared between itemTemplate and relationshipTemplate elements. Further, a dialect attribute has been added so that XPath content is not restricted to the 1.0 version of XPath. The subelement formerly named xpathExpression that contains the raw XPath content is now named expression.
  • The semantics of the XPath expression in a CMDBf query have changed. In CMDBf 0.95, the XPath expression was used as a selector that evaluated to either true or false. In 1.0, the content of the record element contained by an item template is determined by the evaluation of the XPath expression. See line #1181 of the CMDBf 1.0 spec for more details.
  • depthLimit is a new subelement of relationshipTemplate that defines whether multiple edges or nodes should be traversed when conducting the query
  • propertySubsetDirective is now contentSelector and has a matchedRecords attribute that controls whether returned record content must match the selected type. Also, the selectedRecordType element has been introduced to control whether entire records or selected properties (through use of selectedProperty child elements) are returned.
  • the mdrId element of the <registerRequest> element has been corrected to be defined as anyURI instead of MdrScopedType in the schema
  • The specification now indicates a set of graph query faults and register operation faults that should be issued in certain failure conditions are met when processing a query, registration, or deregistration request. These are enumerated in sections 4.3.3, 5.2.3, and 5.2.6 of the spec. The query and registration services will need to define and throw special exception types containing the code, subcode, reason, and detail data. The MDR code will need to handle these exceptions and envelop them in a SOAP fault as part of the web service failure.
  • Section 6 of the 1.0 spec describes new constructs called queryServiceMetadata and registrationServiceMetadata. These are provided so that a federating CMDB can determine which capabilities and data models are supported by a given MDR.
NOTE TO REVIEWERS: This metadata is a new addition to the CMDBf schema 
that is optional to be implemented, but seems to be a key future 
component to the reconciliation taxonomy.  Does this implementation 
need to be done near term, and does it belong in the CMDBf framework, 
or in the CMDBf toolkit code?  If this is to be done as part of this
enhancement, a design overview is provided in the Service Metadata
section.

Spec changes summary table

Here is a summary in table form of some of the direct high-level changes in the CMDBf spec for version 1.0.

CMDBf 0.95 keyword CMDBf 1.0 keyword
N/A recordMetadata
N/A recordConstraint
recordTypeSelector recordType
propertyValueSelector propertyValue
instanceIdSelector instanceIdConstraint
xpath1Selector xpathExpression
xpathExpression expression
propertySubsetDirective contentSelector
dropDirective suppressFromResult
source sourceTemplate
target targetTemplate
N/A depthLimit
sourceItem source
targetItem target

Service Metadata

Service metadata is a new concept introduced in CMDBf1.0 specification. It's an optional mechanism for an MDR to advertise the query and registration service capabilities. There will be a new module added to the CMDBf project to allow consumers to add this support. The new module will be called CMDBfMetadata.jar and will have a very similar structure to CMDBfQueryTransformation.jar and CMDBfRegistrationTransformation.jar.

The library will include a POJO representation with a mirror transformation operation. How an MDR exposes the service metadata is left to the COSMOS code base that morphs a data store to a data manager. The library will simply provide a POJO representation that can be converted/generated to/from an XML document.

Task Breakdown

The following section includes the tasks required to complete this enhancement.

208584-pert.jpg

  1. Copy the new data model schema to the COSMOS code base
  2. Update the XML in the JUnit testcases to reflect the changed data model
  3. Update the interfaces representing data model artifacts
  4. Update the concrete implementations of those interfaces found in the cmdbf.query plug-in to match the new API changes
  5. Update SAX parser code that transforms XML to artifacts
  6. Update the toXML() methods that convert artifacts to XML representation
  7. Update the code snippets in the JUnit testcases that make use of factory classes to instantiate artifacts for testing
  8. Update the rest of the common query and registration service code
  9. Update the SML repository code that uses the query service
  10. Update the example query & registration service code, and the user documentation that accompanies it[2]
  11. Notify early adopters (e.g. the CMDBf toolkit, also found in the data collection subproject) of previous implementation of changed COSMOS code, so they can change their implementations

Open Issues/Questions

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

References


Back to the top