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 208274"

('''Use Cases''')
(''' Workload Estimation''')
Line 36: Line 36:
 
| align="left" | Design
 
| align="left" | Design
 
| 1
 
| 1
| David/Hubert/Martin
+
| David (initial work by Hubert/Martin/Mark)
 
|-
 
|-
 
| align="left" | Code
 
| align="left" | Code

Revision as of 17:50, 24 January 2008

Create a data manager toolkit that will allow adopters to easily register and use a data provider inside COSMOS framework

This is the design document for bugzilla 208274.

Change History

Name: Date: Revised Sections:
Mark Weitzel and Hubert Leung 11/7/2007
  • Initial version
Martin Simmonds 1/18/2008
  • Initial design details of project wizard
David Whiteman 1/22/2008
  • Added rest of design template
  • Added screen mockups

Workload Estimation

Rough workload estimate in person weeks
Process Sizing Names of people doing the work
Design 1 David (initial work by Hubert/Martin/Mark)
Code 2 David/Hubert
Test 1 David/Hubert/QA
Documentation 2 David/Rich
Build and infrastructure 0
Code review, etc.* 0
TOTAL 6.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
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

There are a number of manual steps that adopters are required to take when creating a data manager, MDR, or federating CMDB using the COSMOS framework. Much of these steps can be automated by an Eclipse-based toolkit that will greatly simplify the steps required for an adopter to use COSMOS framework. The toolkit should automatically generate code stubs, configuration files, and any other artifacts that will greatly simplify the procedure for adding a custom data manager to COSMOS.

Use Cases

The following have been identified as use cases related to this enhancement.

  1. Developer creates new data manager
    There are two variations on this use case:
    1. Data manager is being created from scratch.
      This is addressed in Creating a new Data Manager project.
    2. Data manager is being adapted to existing data source.
      This is the case where the user imports an MDR into Eclipse. Users will create a normal Eclipse project, and then based on the config.properties and domainEPR.xml files, new manifest editor pages will be displayed for editing these. See Updating Data Manager Project.
  2. Developer updates properties of data manager
    This is addressed in Updating Data Manager Project.

Development environment

  • Developer will install a set of plug-ins into the Eclipse workbench, and will download noted COSMOS prerequisites.
  • Developers will create extensions to the COSMOS framework in the Eclipse workbench environment.
  • Examples and documentation on how to extend the COSMOS framework will be provided, integrated with the Eclipse help system.
  • Developers can test toolkit implementation using WSDM Tooling, as it allows the launching of endpoints within Eclipse
  • Developer will export the end result into deployment environment:
    • J2EE, OSGi
    • Server component
    • Client component

Detailed Design

Creating a new Data Manager project

We will provide a new Eclipse menu option for creating a data manager project. As mentioned previously, this will greatly simplify the process and reduce the human error in configuring a data manager or MDR for use with COSMOS.

The menu option will be accessible from the Eclipse menu bar, as follows:

<mdw> Since CMDBf is a primary use case, I think it would be good to call this out directly in the design of the user interface. Here, we could have the "Systems Management Menu" and underneath it, add "CMDBf Management Data Repository" and "Custom Data Manager". This should be an extension point that people can register under. This would be consistent with the COSMOS programming model in that CMDBf APIs are simply "convenience" APIs on top of data managers. I may want to be able to register my own kind of APIs. </mdw>

<dlw> We do call this out, in the "project type" group on page 1 of the project creation wizard. We were thinking this would be more flexible than requiring that the choice be made in the tree where you select what kind of project to create. I'd be interested in hearing more specifics on your extension point thoughts. </dlw>

208274 eclipse file menu.jpg

208274 New project wizard.jpg

Create Data Manager Project Wizard

The wizard for creating a data manager project will have the following responsibilities:

  • Creates org.eclipse.cosmos.*mdrname.mdr project
  • Creates Activator.java
  • Creates *mdrnameMdr.java
  • Create config.proprties
  • Create domainEPR.xml
  • Create MANIFEST.MF
  • Creates Plug-in Dependencies
    • org.apache.xerces_2.8.0*
    • org.apache.xml.resolver*
    • muse-complete-2.2.0.jar
    • org.eclipse.osgi_3.3.2.R33x*
    • org.eclipse.cosmos.common
    • org.eclipse.dc.cmdbf.services
    • org.eclipse.dc.dataManager
    • org.eclipse.dc.mdr
    • org.eclipse.dc.mdr.common
    • org.eclipse.cosmos.management.common
    • org.eclipse.cosmos.samples.cmdbf.services


When the 'Create Data Manager' project wizard is launched, properties general to all data managers can be set:

  1. MdrName
  2. Resource_ID
  3. Display Name
  4. Description
  5. Deployment target (Tomcat/OSGI)
  6. Type of data manager (standard data manager / MDR (query service) / federating CMDB (query & reg service)

Here is a mockup of the appearance of the wizard:
208274 create data mgr wizard.jpg

<mdw> I think we should break this down into two parts and base this on the metadata that is defined in the CMDBf spec. For metadata that would apply to all data managers, we have something like this screen. When you are defining an MDR, we add a page for MDR specific metadata, e.g. depth level. Likewise, this should be an extension point that we register with. </mdw>

<dlw> OK, below is some text along those lines. Question: since this is an extension point, I'm guessing the project type choice will need to be a drop down list rather than a radio button? Should other project types be added per extension points? </dlw>

When the developer selects one of the types "MDR" or "federating CMDB" for the data manager project, there will be custom pages displayed based on registered extension points so that metadata specific to those project types can be input.

<mdw> I don't think "Tomcat" is an environment. I think we would have J2EE or OSGi. I'm not sure if we even have the OSGi requirement any longer and I'd be willing to simplify if we could. We should check with the SDD folks as they might be the ones that will need to use OSGi.


It't not clear what the "Create JUnit" stuff would do. I'd rather see a generic "test harness" for CMDBf if there was a way to swing it. The test harness should be a separate ER and tied to pluggable resource model.

</mdw>

<dlw> We call it a "deployment target" not an "environment". I guess your general comment is Tomcat is too specific of a term here. I updated the UI accordingly.

The "Create JUnit" option was just to specify whether "Creates org.eclipse.cosmos.*mdrname.mdr.test junit project" and "Creates Junit test *mdrnameTest.java" as described in the list of wizard responsibilities. It agree it's strange to have that though since other project wizards don't offer that an option, and JUnits are not specific to data manager projects. I removed it. </dlw>

Generating EPRs

Our initial thought was to generate an empty EPR file as part of the wizard. However, it would be really nice to provide a UI so users don't have to hand-code these as well. Here is a mockup for the input controls for generating an EPR, which will be on page 2 of the project creation wizard.

208274 create data mgr wizard page2.jpg


<mdw> The issue that I see here is that the EPRs will change when you move from dev -> test -> qa -> production. Specifying it here I think is not the right thing to do. </mdw>

<dlw> This is just to specify the initial content of the EPRs, since coding the XML by hand is tedious and error prone. Clearly you would need to tweak this as you go through development. We could provide a project property page, like the one described in the next section, for you to change those values and re-generate the EPRs. This is much like what is found in the WSDM toolkit. </dlw>

Updating Data Manager Project

A valid use case is for a developer to want to change some of the initial project settings after the project has been created. We will provide an extra page on the project manifest that will allow several of the project parameters to be changed. We will need to be sure to preserve user edits to the project artifacts that are made outside our editors.

208274 project editor.jpg

Data Manager Project Artifacts

The following examples illustrate the artifacts that would be generated if a data manager of type MDR is specified in the project wizard.

Activator.java

package org.eclipse.cosmos.*mdrname.dataManager;

import org.eclipse.cosmos.dc.dataManager.api.IDataManager;
import org.eclipse.cosmos.dc.dataManager.impl.AbstractDataManagerActivator;

public class Activator extends AbstractDataManagerActivator {

	@Override
	protected IDataManager getDataManagerInstance() {
		return new *MdrnameDataManager();
	}

}

*MdrnameDataManager.java

package org.eclipse.cosmos.*mdrname.dataManager;

import org.eclipse.cosmos.dc.cmdbf.services.query.service.IQueryHandlerFactory;
import org.eclipse.cosmos.dc.dataManager.api.IDataManager;
import org.eclipse.cosmos.dc.mdr.api.IMdrQuery;
import org.eclipse.cosmos.dc.mdr.impl.AbstractMdr;
import org.eclipse.cosmos.dc.mgmt.annotations.ManagedResource;
import org.eclipse.cosmos.samples.cmdbf.services.query.ICMDBfSampleConstants;
import org.eclipse.cosmos.samples.cmdbf.services.query.QueryHandlerFactory;
import org.eclipse.cosmos.samples.cmdbf.services.query.XMLRepository;

@ManagedResource
public class *MdrnameDataManager extends AbstractMdr implements IDataManager, IMdrQuery 
{	
	public *MdrnameDataManager() 
	{
	}

	@Override
	public IQueryHandlerFactory getQueryHandlerFactory() 
	{
		return QueryHandlerFactory.getInstance();
	}

}

config.properties

RESOURCE_ID=Example
DISPLAY_NAME=MDR Example
DESCRIPTION=An example of an MDR
MGMT_DOMAIN_EPR_FILE=META-INF/domainEPR.xml

domainEPR.xml

<?xml version="1.0" encoding="UTF-8"?>
<wsa:EndpointReference xmlns:wsa="http://www.w3.org/2005/08/addressing">
    <wsa:Address>http://localhost:8080/cosmos/services/domain</wsa:Address>
</wsa:EndpointReference>

MANIFEST.MF

Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: Example MDR
Bundle-SymbolicName: org.eclipse.cosmos.*mdrname.mdr
Bundle-Version: 1.0.0
Bundle-Activator: org.eclipse.cosmos.*mdrname.mdr.Activator
Import-Package: org.osgi.framework;version="1.3.0"
Require-Bundle: org.eclipse.cosmos.dc.mdr,
 org.apache.xerces,
 org.eclipse.cosmos.common,
 org.eclipse.cosmos.dc.cmdbf.services,
 org.apache.muse.complete,
 org.eclipse.cosmos.samples.cmdbf.services
Export-Package: org.eclipse.cosmos.*mdrname.mdr

Open Issues/Questions

  • Decide on data mgr project multiplicity, e.g. one for client, one for server etc...
  • What other things are available, e.g. STP or WTP may have annotations for web services.

<mdw>

  • I'd like to see integration with things like "Run on server" where the MDR is essentially opened up. Integration with a test client/harness at that point, e.g. embedding part of the cosmos UI may also be a good thing. Could also include some "pre-canned" queries, e.g. "Show all record types" or something like that.
  • What about the notion of cheat sheets? Any thought of using them here?
  • What about linkages into the resource model and Ali's model mapper ER?

</mdw>


All reviewer feedback should go in the Talk page for 208274. <mdw> Sorry, put comments in line. </mdw>

References

Back to the top