Jump to: navigation, search

Difference between revisions of "COSMOS Programming Model"

(Preparing Development Environment)
 
(42 intermediate revisions by 3 users not shown)
Line 2: Line 2:
  
 
== Creating a Data Manager ==
 
== Creating a Data Manager ==
=== Getting Code from CVS ===
+
=== Preparing Development Environment ===
  
The code for data manager (both the framework and examples for using the framework) is checked into the sandbox directory of the COSMOS CVS.
+
Please find instructions for setting up development environment for i8 [[COSMOS Development Environment Setup i8|here]].
  
Host: dev.eclipse.org
+
=== Examples ===
Repository: /cvsroot/technology
+
The COSMOS demo and SDK provided on the download page include some examples for creating data managers or management data repositories (MDR). Developers are encouraged to run the demo program to get familiar with the functions provided by COSMOS, and use the examples as guidance.
Path: org.eclipse.cosmos/sandbox
+
  
Here is the list of bundles and their purposes:
+
=== Class Diagram ===
 +
The following diagram depicts the class hierarchy of the COSMOS data manager framework. <br/>
 +
[[image:DataManagerClassDiagram.jpg‎]]
  
'''Framework code for data manager:'''
+
Note the symmetry of the diagram. Classes on the left are implementation classes of the server logic. APIs are exposed through the Java interfaces in the middle of the diagram. The same set of interfaces are used by remote client classes on the right side.
*org.eclipse.cosmos.dc.sandbox.datamanager
+
*org.eclipse.cosmos.dc.sandbox.datamanager.common
+
*org.eclipse.cosmos.dc.sandbox.datamanager.client
+
  
'''Framework code for MDR''' (only required if data manager has to be CMDBf compliant):
+
The AbstractDataManager class provides basic functionality for registering with COSMOS brokers and handles various resource management and configuration capabilities.  AbstractMdr class provides a framework for providing logic for interpreting a CMDBf query, and translating the CMDBf query to a language that the application understands.
*org.eclipse.cosmos.dc.sandbox.mdr
+
*org.eclipse.cosmos.dc.sandbox.mdr.common
+
*org.eclipse.cosmos.dc.sandbox.mdr.client
+
  
'''MDR for SML repository''' (an example of an MDR, and can also be used to work with the SML repository provided by the *resource modeling subproject)
+
To create a data manager that does not support CMDBf query, you will need to subclass from the AbstractDataManager class, and provide custom APIs to expose application functions as web services.  For example, the logging data manager provided in the SDK has the following class hierarchy.
*org.eclipse.cosmos.rm.sandbox.dataManager.sml
+
  
'''Example MDR that provides custom capabilities and operations:'''
+
[[Image:LoggingMdrClassDiagram.jpg]]
*org.eclipse.cosmos.dc.sandbox.datamanager.example
+
*org.eclipse.cosmos.dc.sandbox.datamanager.example.common
+
*org.eclipse.cosmos.dc.sandbox.datamanager.example.client
+
  
'''Test programs:'''
+
To create an MDR, subclass from the AbstractMdr class, and provide the necessary implementations to extend the CMDBf query interpretation framework. More details about how to extend the framework will be provided in the next section. The SML repository MDR provided in the example has the following class hierachy.
*org.eclipse.cosmos.dc.sandbox.datamanager.test
+
  
=== Class Diagrams ===
+
[[Image:ExampleMdrClassDiagram.jpg]]
 
+
=== WSDM and Annotiations ===
+
  
 
=== Creating an MDR ===
 
=== Creating an MDR ===
Prerequisite: Import the framework bundles into workspace or install them in the target plaform. 
+
This section has step-by-step instructions for creating an MDR.   
Note: org.eclipse.cosmos.rm.sandbox.dataManager.sml bundle is an implementation of an MDR that uses an SML repository as the backend datastore.  Please refer to it as an example for creating an MDR.  The following steps show how to create an MDR.   
+
* Create a plug-in project: In the "Target Platform" section, select "an OSGi framework", and select "standard" from the dropdown box.  Click next to provide plugin ID, name, etc, and click Finish.
* Create a plugin projectIn the "Target Platform" section, select "an OSGi framework", and select "standard" from the dropdown box.  Click next to provide plugin ID, name, etc, and click Finish.
+
 
* Edit the MANIFEST.MF file in the Plug-in Manifest Editor.  On the Dependencies tab, add the following dependencies and save the file:
 
* Edit the MANIFEST.MF file in the Plug-in Manifest Editor.  On the Dependencies tab, add the following dependencies and save the file:
 
**org.apache.muse.complete
 
**org.apache.muse.complete
**org.eclipse.cosmos.dc.sandbox.dataManager
+
**org.eclipse.cosmos.dc.mdr
**org.eclipse.cosmos.dc.sandbox.mdr
+
* Create a class in this bundle that provides the implementation of the MDR.  This class corresponds to org.eclipse.cosmos.example.mdr.ExampleMdr in the Example MDR in the SDK. 
* Create a class in this bundle that provides the implementation of the  
+
 
**Annotate the class as a ManagedResource
 
**Annotate the class as a ManagedResource
 
**Extend AbstractMDR class
 
**Extend AbstractMDR class
Line 53: Line 39:
 
public class MyMDR extends AbstractMdr implements IDataManager, IMdrQuery
 
public class MyMDR extends AbstractMdr implements IDataManager, IMdrQuery
 
</pre>
 
</pre>
*Implemnet methods declared in interfaces and abstract methods from super class.  For example, the query method takes a CMDBf query as inputProvide adapter code here to parse the query, talk to the data source, and return the response in CMDBf response formatThe logic for parsing the query, invocation of APIs of data source and transforming the query output to CMDBf query response can take place in another class or OSGi bundle.
+
*Implement the getQueryHandlerFactory method, which is an abstract method from the super class.  This method should return an instance of org.eclipse.cosmos.dc.cmdbf.services.query.service.IQueryHandlerFactoryA query handler factory is a factory class that creates handlers for CMDBf queryRead more about the CMDBf query processing framework from the [[Providing_a_CMDBf_Query_and_Registration_Service | Providing a CMDBf Query and Registration Service]] wiki page.  
* An activator class is generated when the OSGi bundle created.  Open the Activator java file in the editor.  COSMOS framework comes with an abstract activator that contains code required by the activators of all data managers.  Make the following updates in the activator java class:
+
* An activator class is generated when the OSGi bundle is created.  Open the Activator java file in the editor.  COSMOS framework comes with an abstract activator that contains code required by the activators of all data managers.  Make the following updates in the activator java class:
 
** Remove the "start" and "stop" method stubs generated by the eclipse.   
 
** Remove the "start" and "stop" method stubs generated by the eclipse.   
 
** Make the Activator class extend AbstractDataManagerActivator
 
** Make the Activator class extend AbstractDataManagerActivator
** Implement the getDataManagerInstance abract method. The method will return an instance of the class that implements the capabilities.  The activator will look like the following.   
+
** Implement the getDataManagerInstance abstract method. The method will return an instance of the class that implements the capabilities.  The activator will look like the following.   
 
<pre>
 
<pre>
 
public class Activator extends AbstractDataManagerActivator {
 
public class Activator extends AbstractDataManagerActivator {
Line 66: Line 52:
  
 
}
 
}
 +
</pre>
 +
* Provide data manager configuration file: add a file call config.properties in the META-INF directory.  This file contains configurable parameters for the data manager.  The keys in the properties files are defined as constants in the IDataManager interface.  The config values can be retrieved from the data manager implementation class using the getConfigProperty method inherited from AbstractDataManager.  Here is a template of the config file:
 +
<pre>
 +
#
 +
# Resource ID of the Data Manager
 +
#
 +
RESOURCE_ID=Example
 +
 +
#
 +
# Display name of the Data Manager
 +
#
 +
DISPLAY_NAME=MDR Example
 +
 +
#
 +
# Description of the Data Manager
 +
#
 +
DESCRIPTION=An example of an MDR
 +
 +
#
 +
# Path to a file that store the EPR of the management domain
 +
#
 +
MGMT_DOMAIN_EPR_FILE=META-INF/domainEPR.xml
 +
 
</pre>
 
</pre>
  
 
=== Providing Custom Capabilities ===
 
=== Providing Custom Capabilities ===
A data manager can expose operations that are not part of the CMDBf specification by providing a custom capability and implementation. The org.eclipse.cosmos.dc.sandbox.example.* bundles provide an example on how to create a data manager with custom APIs. 
+
A data manager can expose operations that are not part of the CMDBf specification by providing a custom capability and implementation.  
  
 
The convention is to put code for the data manager in three bundles:
 
The convention is to put code for the data manager in three bundles:
# API bundle: (e.g. org.eclipse.cosmos.dc.sandbox.example.common) This "common" bundle is used by both the server and the client.  
+
# API bundle: This "common" bundle is used by both the server and the client.  (e.g. org.eclipse.cosmos.dc.stat.datamgr.common)   
# Implementation bundle: Server code that provides implementation of the custom capability.   
+
# Implementation bundle: Server code that provides implementation of the custom capability.  (e.g. org.eclipse.cosmos.dc.stat.datamgr)
# Client proxy: remote API for the data manager.
+
# Client proxy: remote API for the data manager. (e.g. org.eclipse.cosmos.dc.stat.datamgr.client)
  
A capability is declared as a Java interface.  (See org.eclipse.cosmos.dc.dataManager.example.api.ICustomCapability as an example.  Please note the following components in the capability interface:
+
A capability is declared as a Java interface.  (See org.eclipse.cosmos.dc.datamanager.example.api.ICustomCapability as an example.  Please note the following components in the capability interface:
 
* The interface declaration is decorated by the following annotation.  Namespace is declared as a public constant in the interface class.
 
* The interface declaration is decorated by the following annotation.  Namespace is declared as a public constant in the interface class.
 
  @ManagedResourceCapability(namespace=____)
 
  @ManagedResourceCapability(namespace=____)
Line 82: Line 91:
 
* The URI and QName of each operation and their parameters are also declared in the interface.
 
* The URI and QName of each operation and their parameters are also declared in the interface.
  
The steps for creating the implemtation bundle is same as those used to create a basic MDR as described in the prvious section.  The difference is that the data manager implementation class will also implement the custom capability API in the class delaration, and provide the implementation in the class.
+
The steps for creating the implementation bundle is same as those used to create a basic MDR as described in the previous section.  The difference is that the data manager implementation class will also implement the custom capability API in the class declaration, and provide the implementation in the class.
  
=== Client proxy for MDR and Data Manager ===
+
=== Client proxy for the MDR and Data Manager ===
 +
The org.eclipse.cosmos.dc.sandbox.datamanager.client and org.eclipse.cosmos.dc.sandbox.mdr.client bundles provide the client proxies for the data manager and MDR.  If the client application is simply invoking the COSMOS data manager capabilities and the CMDBf query API remotely, this two client implementation is sufficient.  (For an example, see how the client application uses the proxies in the test code in org.eclipse.cosmos.dc.sandbox.datamanager.test.)
  
=== Writing a Custom Data Manager Proxy ===
+
Subclass from MDRClient or DataManagerClient when you need to provide a client proxy of a data manager that provides custom capabilities.
 +
 
 +
=== Running the MDR within Eclipse ===
 +
* Select Run > Open Run Dialog...
 +
* Create a new OSGi Framework profile.
 +
* Select all plug-ins in the workspace and deselect all plugins in the Target platform.  Then click on "Add Required Bundles" button. 
 +
* Select a few extra bundles from the target platform:
 +
<code>
 +
<pre>
 +
javax.mail.api
 +
javax.saaj.api
 +
muse.osgi.soa.mini
 +
org.apache.commons.httpclient
 +
org.apache.commons.logging(1.0.4)
 +
org.eclipse.equinox.ds
 +
org.eclipse.equinox.http.jetty
 +
org.eclipse.equinox.log
 +
</pre>
 +
</code>
 +
* Then click the "Add Required Bundles" button again.
 +
* Click "Run" button.
  
=== Deployment ===
+
[[Category:COSMOS]]

Latest revision as of 12:52, 4 February 2008

COSMOS provides a framework for collecting and visualizing data for system administration applications. By leveraging the COSMOS framework and providing the necessary extensions, programmers can quickly and easily create applications for collecting data from disparate data sources, and making data available through standard-based APIs or an easy-to-use user interface. This document explains the programming model used in extending the COSMOS framework.

Creating a Data Manager

Preparing Development Environment

Please find instructions for setting up development environment for i8 here.

Examples

The COSMOS demo and SDK provided on the download page include some examples for creating data managers or management data repositories (MDR). Developers are encouraged to run the demo program to get familiar with the functions provided by COSMOS, and use the examples as guidance.

Class Diagram

The following diagram depicts the class hierarchy of the COSMOS data manager framework.
DataManagerClassDiagram.jpg

Note the symmetry of the diagram. Classes on the left are implementation classes of the server logic. APIs are exposed through the Java interfaces in the middle of the diagram. The same set of interfaces are used by remote client classes on the right side.

The AbstractDataManager class provides basic functionality for registering with COSMOS brokers and handles various resource management and configuration capabilities. AbstractMdr class provides a framework for providing logic for interpreting a CMDBf query, and translating the CMDBf query to a language that the application understands.

To create a data manager that does not support CMDBf query, you will need to subclass from the AbstractDataManager class, and provide custom APIs to expose application functions as web services. For example, the logging data manager provided in the SDK has the following class hierarchy.

LoggingMdrClassDiagram.jpg

To create an MDR, subclass from the AbstractMdr class, and provide the necessary implementations to extend the CMDBf query interpretation framework. More details about how to extend the framework will be provided in the next section. The SML repository MDR provided in the example has the following class hierachy.

ExampleMdrClassDiagram.jpg

Creating an MDR

This section has step-by-step instructions for creating an MDR.

  • Create a plug-in project: In the "Target Platform" section, select "an OSGi framework", and select "standard" from the dropdown box. Click next to provide plugin ID, name, etc, and click Finish.
  • Edit the MANIFEST.MF file in the Plug-in Manifest Editor. On the Dependencies tab, add the following dependencies and save the file:
    • org.apache.muse.complete
    • org.eclipse.cosmos.dc.mdr
  • Create a class in this bundle that provides the implementation of the MDR. This class corresponds to org.eclipse.cosmos.example.mdr.ExampleMdr in the Example MDR in the SDK.
    • Annotate the class as a ManagedResource
    • Extend AbstractMDR class
    • Implement IDataManager and IMdrQuery (Although the superclass already implements these interfaces, we need this step as a temporary workaround for a bug in the management bundle.) The class signature looks something like this:
@ManagedResource
public class MyMDR extends AbstractMdr implements IDataManager, IMdrQuery
  • Implement the getQueryHandlerFactory method, which is an abstract method from the super class. This method should return an instance of org.eclipse.cosmos.dc.cmdbf.services.query.service.IQueryHandlerFactory. A query handler factory is a factory class that creates handlers for CMDBf query. Read more about the CMDBf query processing framework from the Providing a CMDBf Query and Registration Service wiki page.
  • An activator class is generated when the OSGi bundle is created. Open the Activator java file in the editor. COSMOS framework comes with an abstract activator that contains code required by the activators of all data managers. Make the following updates in the activator java class:
    • Remove the "start" and "stop" method stubs generated by the eclipse.
    • Make the Activator class extend AbstractDataManagerActivator
    • Implement the getDataManagerInstance abstract method. The method will return an instance of the class that implements the capabilities. The activator will look like the following.
public class Activator extends AbstractDataManagerActivator {

	protected IDataManager getDataManagerInstance() {
		return new MyDataManager();
	}

}
  • Provide data manager configuration file: add a file call config.properties in the META-INF directory. This file contains configurable parameters for the data manager. The keys in the properties files are defined as constants in the IDataManager interface. The config values can be retrieved from the data manager implementation class using the getConfigProperty method inherited from AbstractDataManager. Here is a template of the config file:
#
# Resource ID of the Data Manager
#
RESOURCE_ID=Example

#
# Display name of the Data Manager
#
DISPLAY_NAME=MDR Example

#
# Description of the Data Manager
#
DESCRIPTION=An example of an MDR

#
# Path to a file that store the EPR of the management domain
#
MGMT_DOMAIN_EPR_FILE=META-INF/domainEPR.xml

Providing Custom Capabilities

A data manager can expose operations that are not part of the CMDBf specification by providing a custom capability and implementation.

The convention is to put code for the data manager in three bundles:

  1. API bundle: This "common" bundle is used by both the server and the client. (e.g. org.eclipse.cosmos.dc.stat.datamgr.common)
  2. Implementation bundle: Server code that provides implementation of the custom capability. (e.g. org.eclipse.cosmos.dc.stat.datamgr)
  3. Client proxy: remote API for the data manager. (e.g. org.eclipse.cosmos.dc.stat.datamgr.client)

A capability is declared as a Java interface. (See org.eclipse.cosmos.dc.datamanager.example.api.ICustomCapability as an example. Please note the following components in the capability interface:

  • The interface declaration is decorated by the following annotation. Namespace is declared as a public constant in the interface class.
@ManagedResourceCapability(namespace=____)
  • Methods are decorated by the @ManagedOperation annotation.
  • The URI and QName of each operation and their parameters are also declared in the interface.

The steps for creating the implementation bundle is same as those used to create a basic MDR as described in the previous section. The difference is that the data manager implementation class will also implement the custom capability API in the class declaration, and provide the implementation in the class.

Client proxy for the MDR and Data Manager

The org.eclipse.cosmos.dc.sandbox.datamanager.client and org.eclipse.cosmos.dc.sandbox.mdr.client bundles provide the client proxies for the data manager and MDR. If the client application is simply invoking the COSMOS data manager capabilities and the CMDBf query API remotely, this two client implementation is sufficient. (For an example, see how the client application uses the proxies in the test code in org.eclipse.cosmos.dc.sandbox.datamanager.test.)

Subclass from MDRClient or DataManagerClient when you need to provide a client proxy of a data manager that provides custom capabilities.

Running the MDR within Eclipse

  • Select Run > Open Run Dialog...
  • Create a new OSGi Framework profile.
  • Select all plug-ins in the workspace and deselect all plugins in the Target platform. Then click on "Add Required Bundles" button.
  • Select a few extra bundles from the target platform:

javax.mail.api
javax.saaj.api
muse.osgi.soa.mini
org.apache.commons.httpclient
org.apache.commons.logging(1.0.4)
org.eclipse.equinox.ds
org.eclipse.equinox.http.jetty
org.eclipse.equinox.log

  • Then click the "Add Required Bundles" button again.
  • Click "Run" button.