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.
Difference between revisions of "COSMOS Design 208584"
(→'''Change History''') |
(→'''Spec Change Impacts''') |
||
(21 intermediate revisions by 2 users not shown) | |||
Line 33: | Line 33: | ||
| align="left" | Code | | align="left" | Code | ||
| 1 | | 1 | ||
− | | David | + | | David/Ali |
|- | |- | ||
| align="left" | Test | | align="left" | Test | ||
| 0.4 | | 0.4 | ||
− | | David | + | | David/Ali |
|- | |- | ||
| align="left" | Documentation | | align="left" | Documentation | ||
Line 58: | Line 58: | ||
== Terminologies/Acronyms == | == Terminologies/Acronyms == | ||
− | The terminologies/acronyms below can be used throughout this document. | + | 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. |
{|{{BMTableStyle}} | {|{{BMTableStyle}} | ||
Line 65: | Line 65: | ||
! Definition | ! Definition | ||
|- | |- | ||
− | | | + | |CMDB |
− | |Management | + | |Configuration Management Database as defined by ITIL |
|- | |- | ||
|CMDBf | |CMDBf | ||
− | |[http://www.cmdbf.org Specification] | + | |[http://www.cmdbf.org 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 | |SML | ||
− | |Service Modeling Language - An XML-based language used for modeling | + | |Service Modeling Language - An XML-based language used for modeling |
|- | |- | ||
|SML Model | |SML Model | ||
Line 81: | Line 84: | ||
|- | |- | ||
|SML Repository | |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. | + | |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 | |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. | |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 | + | |CMDBf modules |
− | |The | + | |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 | |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 | ||
|} | |} | ||
Line 98: | Line 98: | ||
== ''' Purpose ''' == | == ''' Purpose ''' == | ||
This enhancement is associated with [https://bugs.eclipse.org/bugs/show_bug.cgi?id=208584 bugzilla 208584]. | This enhancement is associated with [https://bugs.eclipse.org/bugs/show_bug.cgi?id=208584 bugzilla 208584]. | ||
− | < | + | |
− | The purpose of this | + | As part of a previous enhancement<sup>[[#References|1]]</sup>, 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''' == | == '''Spec Change Impacts''' == | ||
− | The following spec changes impact the implementation of the CMDBf | + | The following spec changes impact the implementation of the CMDBf framework in COSMOS. The affected modules are noted as follows: |
− | + | {|{{BMTableStyle}} | |
− | + | |<span style="color:green;"><b>C</b></span> | |
− | + | |Common module | |
− | + | |- | |
− | + | |<span style="color:blue;"><b>Q</b></span> | |
− | + | |Query module | |
− | + | |- | |
− | + | |<span style="color:red;"><b>R</b></span> | |
− | + | |Registration module | |
− | + | |} | |
− | + | ||
− | + | # [http://cmdbf.org/schema/1-0-0/CMDBf%20v1.0.pdf CMDBf 1.0] introduces the concept of a <code>recordMetadata</code> element to the query response that contains "common information about the record itself". There is also a new <code>recordMetadata</code> attribute on the <code>propertyValue</code> element that "indicates the property to be evaluated is in the <code><recordMetadata></code> element of the record". <span style="color:blue;"><b>Q</b></span> | |
− | + | # <code>recordTypeSelector</code> and <code>propertyValueSelector</code> are renamed and aggregated under a common parent element, <code>recordConstraint</code>. The new names are listed in the [[#Spec changes summary table|spec changes summary table]]. <span style="color:blue;"><b>Q</b></span> | |
+ | # <code>xpath1Selector</code> is renamed <code>xpathExpression</code>, and is now mutually exclusive of all other subelements commonly shared between <code>itemTemplate</code> and <code>relationshipTemplate</code> elements. Further, a <code>dialect</code> attribute has been added so that XPath content is not restricted to the 1.0 version of XPath. The subelement formerly named <code>xpathExpression</code> that contains the raw XPath content is now named <code>expression</code>. <span style="color:blue;"><b>Q</b></span> | ||
+ | # 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. <span style="color:blue;"><b>Q</b></span> | ||
+ | # <code>depthLimit</code> is a new subelement of <code>relationshipTemplate</code> that defines whether multiple edges or nodes should be traversed when conducting the query <span style="color:blue;"><b>Q</b></span> | ||
+ | # <code>propertySubsetDirective</code> is now <code>contentSelector</code> and has a <code>matchedRecords</code> attribute that controls whether returned record content must match the selected type. Also, the <code>selectedRecordType</code> element has been introduced to control whether entire records or selected properties (through use of <code>selectedProperty</code> child elements) are returned. <span style="color:blue;"><b>Q</b></span> | ||
+ | # the <code>mdrId</code> element of the <code><registerRequest></code> element has been corrected to be defined as ''anyURI'' instead of <code>MdrScopedType</code> in the schema <span style="color:blue;"><b>Q</b></span> | ||
+ | # 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. <span style="color:blue;"><b>Q</b></span> <span style="color:red;"><b>R</b></span> | ||
+ | # Section 6 of the 1.0 spec describes new constructs called <code>queryServiceMetadata</code> and <code>registrationServiceMetadata</code>. These are provided so that a federating CMDB can determine which capabilities and data models are supported by a given MDR. Since this service metadata is considered optional by the spec, and since it can be implemented in parallel, the work has been spun off to a separate enhancement: [https://bugs.eclipse.org/bugs/show_bug.cgi?id=212185 bugzilla 212185]. | ||
+ | # <code>instanceIdSelector</code> has expanded to allow a collection of instanceIds to be referenced, instead of just one. Now the element is <code>instanceIdConstraint</code> and it contains one or more <code>instanceId</code> elements. <span style="color:blue;"><b>Q</b></span> | ||
=== '''Spec changes summary table''' === | === '''Spec changes summary table''' === | ||
Line 127: | Line 136: | ||
!align="left"|CMDBf 0.95 keyword | !align="left"|CMDBf 0.95 keyword | ||
!align="left"|CMDBf 1.0 keyword | !align="left"|CMDBf 1.0 keyword | ||
+ | !align="left"|Module | ||
|- | |- | ||
|N/A | |N/A | ||
|recordMetadata | |recordMetadata | ||
+ | |<span style="color:blue;"><b>Q</b></span> | ||
|- | |- | ||
|N/A | |N/A | ||
|recordConstraint | |recordConstraint | ||
+ | |<span style="color:blue;"><b>Q</b></span> | ||
|- | |- | ||
|recordTypeSelector | |recordTypeSelector | ||
|recordType | |recordType | ||
+ | |<span style="color:blue;"><b>Q</b></span> | ||
|- | |- | ||
|propertyValueSelector | |propertyValueSelector | ||
|propertyValue | |propertyValue | ||
+ | |<span style="color:blue;"><b>Q</b></span> | ||
|- | |- | ||
|instanceIdSelector | |instanceIdSelector | ||
|instanceIdConstraint | |instanceIdConstraint | ||
+ | |<span style="color:blue;"><b>Q</b></span> | ||
|- | |- | ||
|xpath1Selector | |xpath1Selector | ||
|xpathExpression | |xpathExpression | ||
+ | |<span style="color:blue;"><b>Q</b></span> | ||
|- | |- | ||
|xpathExpression | |xpathExpression | ||
|expression | |expression | ||
+ | |<span style="color:blue;"><b>Q</b></span> | ||
|- | |- | ||
|propertySubsetDirective | |propertySubsetDirective | ||
|contentSelector | |contentSelector | ||
+ | |<span style="color:blue;"><b>Q</b></span> | ||
|- | |- | ||
|dropDirective | |dropDirective | ||
|suppressFromResult | |suppressFromResult | ||
+ | |<span style="color:blue;"><b>Q</b></span> | ||
|- | |- | ||
|source | |source | ||
|sourceTemplate | |sourceTemplate | ||
+ | |<span style="color:blue;"><b>Q</b></span> | ||
|- | |- | ||
|target | |target | ||
|targetTemplate | |targetTemplate | ||
+ | |<span style="color:blue;"><b>Q</b></span> | ||
|- | |- | ||
|N/A | |N/A | ||
|depthLimit | |depthLimit | ||
+ | |<span style="color:blue;"><b>Q</b></span> | ||
|- | |- | ||
|sourceItem | |sourceItem | ||
|source | |source | ||
+ | |<span style="color:blue;"><b>Q</b></span> | ||
|- | |- | ||
|targetItem | |targetItem | ||
|target | |target | ||
+ | |<span style="color:blue;"><b>Q</b></span> | ||
|} | |} | ||
− | == '''Service | + | == '''Service Metadata''' == |
− | Service | + | 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 and data models. The design for this will be covered in [[COSMOS Design 212185]] and implemented under the associated enhancement. |
− | + | ||
− | + | ||
== ''' Task Breakdown ''' == | == ''' Task Breakdown ''' == | ||
Line 191: | Line 213: | ||
# Update the rest of the common query and registration service code | # Update the rest of the common query and registration service code | ||
# Update the SML repository code that uses the query service | # Update the SML repository code that uses the query service | ||
− | # Update the example query & registration service code | + | # Update the example query & registration service code, and the user documentation that accompanies it<sup>[[#References|2]]</sup> |
# 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 | # 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 | ||
Line 197: | Line 219: | ||
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 == | ||
+ | # [[COSMOS Design 204959]] | ||
+ | # [[Providing a CMDBf Query and Registration Service]] | ||
+ | |||
---- | ---- | ||
[[Category:COSMOS_Bugzilla_Designs]] | [[Category:COSMOS_Bugzilla_Designs]] |
Latest revision as of 18:49, 12 December 2007
Contents
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 |
|
Ali Mehregani | 12/05/2007 |
|
Workload Estimation
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 enhancement1, 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 framework in COSMOS. The affected modules are noted as follows:
C | Common module |
Q | Query module |
R | Registration module |
- 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 newrecordMetadata
attribute on thepropertyValue
element that "indicates the property to be evaluated is in the<recordMetadata>
element of the record". Q -
recordTypeSelector
andpropertyValueSelector
are renamed and aggregated under a common parent element,recordConstraint
. The new names are listed in the spec changes summary table. Q -
xpath1Selector
is renamedxpathExpression
, and is now mutually exclusive of all other subelements commonly shared betweenitemTemplate
andrelationshipTemplate
elements. Further, adialect
attribute has been added so that XPath content is not restricted to the 1.0 version of XPath. The subelement formerly namedxpathExpression
that contains the raw XPath content is now namedexpression
. Q - 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. Q
-
depthLimit
is a new subelement ofrelationshipTemplate
that defines whether multiple edges or nodes should be traversed when conducting the query Q -
propertySubsetDirective
is nowcontentSelector
and has amatchedRecords
attribute that controls whether returned record content must match the selected type. Also, theselectedRecordType
element has been introduced to control whether entire records or selected properties (through use ofselectedProperty
child elements) are returned. Q - the
mdrId
element of the<registerRequest>
element has been corrected to be defined as anyURI instead ofMdrScopedType
in the schema Q - 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. Q R
- Section 6 of the 1.0 spec describes new constructs called
queryServiceMetadata
andregistrationServiceMetadata
. These are provided so that a federating CMDB can determine which capabilities and data models are supported by a given MDR. Since this service metadata is considered optional by the spec, and since it can be implemented in parallel, the work has been spun off to a separate enhancement: bugzilla 212185. -
instanceIdSelector
has expanded to allow a collection of instanceIds to be referenced, instead of just one. Now the element isinstanceIdConstraint
and it contains one or moreinstanceId
elements. Q
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 | Module |
---|---|---|
N/A | recordMetadata | Q |
N/A | recordConstraint | Q |
recordTypeSelector | recordType | Q |
propertyValueSelector | propertyValue | Q |
instanceIdSelector | instanceIdConstraint | Q |
xpath1Selector | xpathExpression | Q |
xpathExpression | expression | Q |
propertySubsetDirective | contentSelector | Q |
dropDirective | suppressFromResult | Q |
source | sourceTemplate | Q |
target | targetTemplate | Q |
N/A | depthLimit | Q |
sourceItem | source | Q |
targetItem | target | Q |
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 and data models. The design for this will be covered in COSMOS Design 212185 and implemented under the associated enhancement.
Task Breakdown
The following section includes the tasks required to complete this enhancement.
- Copy the new data model schema to the COSMOS code base
- Update the XML in the JUnit testcases to reflect the changed data model
- Update the interfaces representing data model artifacts
- Update the concrete implementations of those interfaces found in the cmdbf.query plug-in to match the new API changes
- Update SAX parser code that transforms XML to artifacts
- Update the toXML() methods that convert artifacts to XML representation
- Update the code snippets in the JUnit testcases that make use of factory classes to instantiate artifacts for testing
- Update the rest of the common query and registration service code
- Update the SML repository code that uses the query service
- Update the example query & registration service code, and the user documentation that accompanies it2
- 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.