Talk:COSMOS Design 204959

This page includes all the discussion for COSMOS Design 204959.

[Sheldon's comment] I assume the apis will throw some sort of exception. For example if a user specifies a data provider that is not supported by the handler it should throw some sort of unsupported exception.

Yes, there are a few exceptions that are included:

• SelectorHandleException
• UnsupportedDataProvider
• UnsupportedSelectorHandler

[Valentina's comment] I still have a hard time mapping the SML repository notion used here to its real meaning. Reading the document content it seems that SML repository in this context is the set of java API’s implemented in COSMOS which allows generic interaction with any repository containing SML compliant data ( or generic SML model ). In this context, SML repository is NOT the COSMOS SML repository we also call Data Center repository. If I got it right I suggest changing the name to 'API for generic SML models' or something similar.

The APIs defined for the SML repository are very generic. The interfaces will allow any generic SML document to be processed. It's only our implementation that extends the set of APIs to include convenience classes for processing facet-based models. I will update the terminologies section of the document but I don't agree with introducing a new term.

Ali, if you introduce or not new terms is irrelevant and less important, my point here is that I don't understand your current SML repository definition and I want you to clarify this.

Please refer to the terminologies section

[Hubert's comment] I am interested in the part of the enhancement that deals with providing custom handlers for processing CMDBf queries. I don't get information from the design page to understand how the framework and handlers work. For example, I have a database (with an arbitrary schema) that contains information about items and relationships. How do I write handlers to process the query? What do the APIs of the handlers look like? Using an example may help with the explanation.

There are two types of handlers available:

org.eclipse.cosmos.dc.cmdbf.services.provisional.query.service.IItemSelectorHandler.java
org.eclipse.cosmos.dc.cmdbf.services.provisional.query.service.IRelationshipSelectorHandler.java

As the name suggests, the first handler is used for selectors of an item template and the second handler is used to process the selectors of a relationship template. An adopter can for example provide a handler for the instance id selector of an item template by providing an implementation of the first interface. See the following classes as examples of handlers that have been created for the SML repository:

org.eclipse.cosmos.rm.repository.internal.operations.cmdbf.ItemInstanceHandler.java
org.eclipse.cosmos.rm.repository.internal.operations.cmdbf.ItemPropertyHandler.java
org.eclipse.cosmos.rm.repository.internal.operations.cmdbf.ItemRecordHandler.java
org.eclipse.cosmos.rm.repository.internal.operations.cmdbf.ItemXPathHandler.java
org.eclipse.cosmos.rm.repository.internal.operations.cmdbf.RelationshipRecordHandler.java

Once the handler classes are complete, a factory class is created to construct instances of the handlers. The factory class is expected to be of type: org.eclipse.cosmos.dc.cmdbf.services.provisional.query.service.ISelectorHandlerFactory.java. See the SML repository factory class as an example:

org.eclipse.cosmos.rm.repository.internal.operations.cmdbf.SMLSelectorHandlerFactory.java

The final step is to have the factory class registered with the framework using: org.eclipse.cosmos.dc.cmdbf.services.provisional.query.service.SelectorHandlerFactoryRegistration.java. A factory class is registered with an MDR ID. For example:

SelectorHandlerFactoryRegistration.registerHandlerFactory(CMDBfConstants.REPOSITORY_MDRID_URI, SMLSelectorHandlerFactory.getInstance());

[More comments from Hubert]

Here is more feedback on the CMDBf service implementation:

1. The SelectorHandlerfactoryRegistration class is a factory of handler factories. It returns a factory class based on a "mdrId" key. The mdrId as implemented in the code is not the instance ID of an MDR, but a namespace hardcoded to indicate a certain type of MDR. I don't see a usecase for having a factory of factories for registering selector handlers from different MDR types. The architecture can be simplified by removing SelectorHandlerfactoryRegistration, and register a factory with the operation directly. This will maintain a 1:1 relationship between the operation instance and the handler factory instance. This simplification eliminates the need to pass in an mdrId to the execute method of the ICMDBfQueryOperation interface.
2. Implementation of org.eclipse.cosmos.rm.repository.internal.operations.cmdbf.ItemInstanceHandler: This class is an implementation of the InstanceIdSelector. This selector provides 2 values - mdrId and localId. The implementation of the itemInstanceHandler for SML repository first compares the mdrId with a constant defined in an interface. I think this implementation may not be sufficient. The mdrId should be an unique identifier of an MDR instance. This selector is most useful in the federating CMDB, which can provide identifier unique in individual MDRs. If I have two SML repository in my system, they should have different mdrIds. If this selector is for use in an MDR, and if the MDR has a unique instance identified exposed, the mdrId should be compared to the unique instance ID value.
3. Data Provider: The AbstractSelectorHandler class has an abstract method isDataProviderSupported and requires implementation of handler classes to provide the implementation of this method. The idea is to have the selector handlers validate whether it is being called to serve the correct data provider type. I think this checking mechanism can be removed, for 2 reasons:
   • Custom handlers are contributed by registering a handler factory with the MDR. The factory is responsible for providing the relevant custom handlers. Since there is a 1 to 1 relationship between the MDR and the factory, there is no chance to have a wrong handler returned, unless it is a development time bug.
   • This checking mechanism requires the application that needs to be exposed as an MDR to have a class that implements IDataProvider. This requirement is hard to meet because we should not ask the application code (e.g. TADDM) to depend on COSMOS code. The dependency should be in the reverse direction. That is, we create an MDR to connect an application through CMDBf query service, and this MDR requires the application API.
4. serialization of request object: The payload of the response is in the Record element. This element has an "any" type, so the child of the "Record" element can be anything. The current requires the content of "Record" be pre-serialized into String, so that the getter and setter of the Record object can treat the content as a String. The object model can be improved by handling objects that implement a serializer API. So the getter and setter can handle any objects, and the serialization and deserialization are done with the rest of the object model. Also, another thing that need to take note regarding the Record element is that the Record object has a addNamespace method for setting the namespace of the record content. The object model needs to somehow validate or ensure the content of Record indeed has the same namespace. Alternatively, the namespace value is set automatically by the object model by retrieving the namespace from the Record content.

1. A very good suggestion. I will remove SelectorHandlerFactoryRegistration and move the logic of the caching mechanism to AbstractSelectorHandlerFactory as discussed.
2. The CMDBf standard doesn’t really indicate that an MDR ID is independent of a session. Although I understand your case here, I would prefer not to make any changes to the SML repository implementation. There is nothing in the framework that would prevent adopters from using MDR IDs that are session/instance dependent.
3. We flushed this one in person. Here’s a summary of the changes:
   1. The parameter type of the initialize method will be changed from IDataProvider to a Map. IDataProvider will be removed.
   2. isDataProviderSupported(…) will be removed and the exception name of the initialize method will change to something more generic
   3. CMDBfQueryOperation will do the initialization of the individual selector handlers
4. This has already been addressed by David. The record objects have been modified to take any object that implements IXMLWritable as their value. Adopters can use a serializer to transform a query response to objects that correspond to the records embedded in an XML response.