Constructing a Data Manager

From Eclipsepedia

Revision as of 18:53, 20 April 2009 by Dlwhiteman.us.ibm.com (Talk | contribs)
(diff) ←Older revision | Current revision (diff) | Newer revision→ (diff)
Jump to: navigation, search
Image:edit-clear.png This page has been marked for deletion by the administrators. If this request is rescinded, please explain in Discussion.

[IMPORTANT: This document is out of date. Please instead find this documentation in the "Creating a Data Manager" section of the COSMOS Developer's Guide, which is linked from the COSMOS driver download pages]

COSMOS provides a framework for collecting and visualizing data for system management 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.

Contents

Introduction

The overall vision of the COSMOS project is to use industry standards to provide building blocks for integrating multiple system management products. This section walks through a summary of the COSMOS framework. It gives an overview of each component using the figure displayed below:

Image:cosmos-components.png

Each component, numerically labeled from 1 to 4 is described in order under the subsections below. Keep in mind that each component can reside on a different host.

Management Domain

The management domain is the entry point to communicate with the components available in the COSMOS framework. All clients desiring to establish a communication link with a component residing in COSMOS will first have to contact the management domain. This component can contain one or more brokers that keep track of registered data managers. Although it is technically possible to include multiple brokers in a management domain, COSMOS by default includes only one instance of a broker.

COSMOS Broker

The broker acts as a registry for a set of data managers. It simply accepts a registration request from a data manager by maintaining its end-point-reference (EPR). A client interested in establishing communication with a data manager will need to retrieve the data manager's EPR via the broker.

COSMOS Client

COSMOS provides a web-based user interface that provides visualizations for the registered data managers. The capabilities of the user interface is outside the scope of this document. Please refer to Visualizing Data from a Registered Data Manager for more details about the user interface available in COSMOS

Data Manager

A data manager is a framework around a system management application that has access to a set of data. The type of system management application, the data, or the mechanism used to collect the data is irrelevant to the framework. Wrapping a system management application around a data manager framework provides a standard mechanism for discovering the capabilities that an adopter exposes. This article primarily focuses on constructing a data manager. In an effort to better illustrate how this can be done, an example is provided based on a sample originally developed in the following article: Providing a CMDBf Query and Registration Service.

A data manager that provides a CMDBf query capability is referred to as a Management Data Repository (MDR). Please refer to the CMDBf specification for more details about MDRs and the query service. An MDR can therefore be thought of as a classification of a data manager. It is of course not required for adopters to provide a CMDBf query service as part of constructing a data manager.

The figure below gives a pictorial overview of all components that a data manager is composed of. The components that belong to the COSMOS framework is shaded in blue and the extensions are shaded in yellow. Subsequent sections delve into more detail about the subcomponents.

Image:data-manager-components.png

How long does it to build a Data Manager?

COSMOS 1.0 will ship with reference implementations for a number of Data Managers. For example, there will be a Data Manager for an RDBMS and another one for File-based stores. Additionally, based on the experience of the team, it takes about 3-6 weeks to code a Data Manager.

[Subject to revision / review]

Data Control and Assembly

[Hubert: Please add detail here]

CMDBf/Custom Query

[Hubert: Please add detail here]

Data Manager Example

The following example constructs an MDR (a classification of a data manager) based on the sample that was originally developed in Providing a CMDBf Query and Registration Service. This example requires an instance of Eclipse to be installed. Once successfully completed, the user will be able to discover the MDR using an EPR and execute CMDBf queries.

Retrieving the Required Code

  1. MUSE is a prerequisite for the project. Please obtain a copy of MUSE 2.2 from Apache's website. Once the archive file is extracted, copy the following into the plugin directory of the Eclipse workbench beings used for development:
    1. <MUSE_HOME>/modules/osgi/complete/muse-complete-2.2.0.jar
    2. <MUSE_HOME>/modules/osgi/mini/muse-osgi-soa-mini-2.2.0.jar
    3. <MUSE_HOME>/lib/eclipse-osgi/org.apache.wsdl4j_1.6.1 (copy the directory)
      Once the required files are copied, restart eclipse using the clean flag: <ECLIPSE_HOME>/eclipse -clean
  2. Use the following CVS information to extract the listed plug-ins from COSMOS CVS:

    Host: dev.eclipse.org
    Repository Path: cvsroot/technology
    User: anonymous
    Password: [Leave empty]
    Connection type: pserver

    Plug-ins:
    Extract the following plug-ins from HEAD/org.eclipse.cosmos/data-collection:
    • org.eclipse.cosmos.dc.broker.client
    • org.eclipse.cosmos.dc.cmdbf.services
    • org.eclipse.cosmos.dc.dataManager
    • org.eclipse.cosmos.dc.dataManager.client
    • org.eclipse.cosmos.dc.dataManager.common
    • org.eclipse.cosmos.dc.management.domain.client
    • org.eclipse.cosmos.dc.mdr
    • org.eclipse.cosmos.dc.mdr.client
    • org.eclipse.cosmos.dc.mdr.common
    • org.eclipse.cosmos.dc.common
    • org.eclipse.cosmos.dc.spec
    • org.eclipse.cosmos.management.common
    • org.eclipse.cosmos.management.wsdm
    • org.eclipse.cosmos.tptp.dependencies

    and the following plug-ins from HEAD/org.eclipse.cosmos/examples:
    • org.eclipse.cosmos.samples.cmdbf.services
    • org.eclipse.cosmos.example.mdr
  3. There will be a number of compile errors in org.eclipse.cosmos.management.wsdm because of unnecessary dependencies. Apply the following patch to remove the errors. This will later be corrected under the following defect: https://bugs.eclipse.org/bugs/show_bug.cgi?id=209575.

Code Overview

The primary plug-ins related to the construction of a data manager are

  • org.eclipse.cosmos.dc.dataManager
  • org.eclipse.cosmos.dc.dataManager.client
  • org.eclipse.cosmos.dc.dataManager.common

The common plug-in is required for the server and the client environment. The plug-in org.eclipse.cosmos.dc.dataManager is used for the server side and org.eclipse.cosmos.dc.dataManager.client is used for the client environment. A similar structure is used to provide the MDR classification of data managers. The MDR plug-ins extend the data manager plug-ins to provide this classification:

  • org.eclipse.cosmos.dc.mdr
  • org.eclipse.cosmos.dc.mdr.client
  • org.eclipse.cosmos.dc.mdr.common

The class diagram below displays the relationship between the classes of the data manager and the MDR plug-ins:

Image:datamanager.png

[Hubert: Please add a paragraph to describe the classes displayed in the class diagram]

The example is composed of the following two plug-ins:

  • org.eclipse.cosmos.samples.cmdbf.services
  • org.eclipse.cosmos.example.mdr

The first plug-in is described in Providing a CMDBf Query and Registration Service and will not be covered in this article. Only the second plug-in is relevant here. When creating an MDR data manager, the following steps have to be followed:

  1. 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.
  2. Edit the MANIFEST.MF file to include the following dependencies:
    • org.apache.muse.complete
    • org.eclipse.cosmos.dc.mdr

Once the plug-in is created, a class must be created to provide the implementation of the MDR. This class corresponds to org.eclipse.cosmos.example.mdr.ExampleMdr in the example plug-in. Notice the class is:

  • Annotated as a ManagedResource
  • Extends AbstractMDR class, and
  • Implements 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 returns an implementation of org.eclipse.cosmos.dc.cmdbf.services.provisional.query.service.IQueryHandlerFactory which was developed as part of implementing the first example: org.eclipse.cosmos.samples.cmdbf.services. Also notice that the activator of the plug-in has been modified by extending AbstractDataManagerActivator and providing a getDataManagerInstance() method.

Finally, a data manager plug-in is expected to provide a configuration file in the META-INF directory. The file is expected to be called "config.properties". See the example's configuration file by retrieving org.eclipse.cosmos.example.mdr/META-INF/config.properties. 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 retrieve from the data manager implementation class using the getConfigProperty method inherited from AbstractDataManager. The following is a general template that can be used for a configuration file: 

#
# URI of the management domain
#
MGMT_DOMAIN_URI=http://localhost:80/cosmos/services/org.eclipse.cosmos.dc.domain.impl.ManagementDomain

#
# Resource ID of the management domain
#
MGMT_DOMAIN_RESOURCEID=DOMAIN

#
# URI of the data manager EPR
#
ENDPOINTADDRESS=http://localhost:80/cosmos/services/org.eclipse.cosmos.rm.dataManager.sml.impl.SmlRepositoryDataManager

#
# Resource ID of the data manager
#
ENDPOINTRESOURCEID=EXAMPLE

#
# Display name of the data manager
#
NAME=Data Manager EXAMPLE

#
# Classification of the data manager
#
CLASSIFICATION=example

#
# Dialect of the data manager
#
DIALECT=my dialect

See the next section on how to run the sample.

Running the Sample

[Hubert: Can you include the content for how the user can run the sample? Please include any configuration required before running the sample]

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: (e.g. org.eclipse.cosmos.dc.sandbox.example.common) This "common" bundle is used by both the server and the client.
  2. Implementation bundle: Server code that provides implementation of the custom capability.
  3. Client proxy: remote API for the data manager.

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.

Visualizing the Example MDR

COSMOS user interface can be used to visualize the example MDR. Please see Visualizing Data from a Registered Data Manager for more details.

Retrieved from "http://wiki.eclipse.org/Constructing_a_Data_Manager"