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"

('''Extensibility''')
Line 120: Line 120:
 
This is addressed in [[#Updating Data Manager Project|Updating Data Manager Project]].
 
This is addressed in [[#Updating Data Manager Project|Updating Data Manager Project]].
 
</li>
 
</li>
<li>Developer exports data manager code for deployment.<br>
+
<li>Developer wants to start data manager in Eclipse.<br>
This is addressed in [[#Export Wizard|Export Wizard]].
+
This is addressed in [[#Deployment|Deployment]].
 
</ol>
 
</ol>
  
Line 198: Line 198:
  
  
When the 'Create Data Manager' project wizard is launched, properties general to all data managers can be set:
+
When the 'Create Data Manager' project wizard is launched, properties general to all data managers can be set on the first page:
  
 
<ol>
 
<ol>
Line 205: Line 205:
 
<li>Display Name
 
<li>Display Name
 
<li>Description
 
<li>Description
<li>Deployment target (Tomcat/OSGI)
+
<li>Whether to create a client-side plug-in
<li>Type of data manager (standard data manager) / MDR (query service) / federating CMDB (query & reg service)
+
 
</ol>
 
</ol>
  
Line 212: Line 211:
 
[[Image:208274_create_data_mgr_wizard.jpg]]
 
[[Image:208274_create_data_mgr_wizard.jpg]]
  
When the developer selects one of the types "MDR" or "federating CMDB" for the data manager project, there will be custom pages added to the wizard based on registered extension points so that metadata specific to those project types can be input.
+
'''Create client plug-in option'''
 +
 
 +
When the <b>Create client plug-in</b> option is selected, the user will be prompted for a custom class to be instantiated for the client.  If the option is not selected, the default implementation of <code>MdrClient</code> will be used.
 +
 
 +
<!--When the developer selects one of the types "MDR" or "federating CMDB" for the data manager project, there will be custom pages added to the wizard based on registered extension points so that metadata specific to those project types can be input.-->
  
 
==== '''Generating EPRs''' ====
 
==== '''Generating EPRs''' ====
Line 219: Line 222:
  
 
[[Image:208274 create data mgr wizard page2.jpg]]
 
[[Image:208274 create data mgr wizard page2.jpg]]
 +
 +
==== '''Deployment target selection''' ====
 +
 +
The next page of the project creation wizard will allow the selection of the deployment target for the data manager.  The choices presented will be gathered through a new extension point.  The provided implementation will pre-define the targets of J2EE and OSGi, and adopters can add custom deployment targets.
 +
 +
Another extension point will allow adopters to provide custom wizard pages for the selected deployment target.  These pages will allow input of target-specific properties.
 +
 +
==== '''Data manager type selection''' ====
 +
 +
Following the wizard page(s) related to the deployment target, a wizard page will be displayed to prompt the developer for the type of data manager to be created.  There will be a new extension point to supply the list of data manager types; the default implementation of the extension point will define the values "Standard data manager", "Management data repository (MDR)", and "Federating CMDB".  For each type, other information such as icon, description, abstract parent class, and prerequisite plug-in will be indicated in the extension point.
 +
 +
There will be yet another extension point that specifies which data manager types are allowed for the indicated deployment target; this subset will be presented for user selection.
 +
 +
Another extension point will allow adopters to provide custom wizard pages for the selected data manager type.  These will allow the input of properties unique to the data manager type.
  
 
=== '''Updating Data Manager Project''' ===
 
=== '''Updating Data Manager Project''' ===
Line 333: Line 350:
 
A developer will want to be able to import an existing data manager into Eclipse.  We will need to provide an import wizard (using the Eclipse import dialog extension point) for the case where the data manager is not being built from scratch.  The developer would select '''File > Import...''' from the Eclipse menu bar to navigate to this wizard.
 
A developer will want to be able to import an existing data manager into Eclipse.  We will need to provide an import wizard (using the Eclipse import dialog extension point) for the case where the data manager is not being built from scratch.  The developer would select '''File > Import...''' from the Eclipse menu bar to navigate to this wizard.
  
=== '''Export Wizard''' ===
+
=== '''Deployment''' ===
  
When a data manager is ready to be deployed, the developer would invoke the export wizard from the '''File > Export...''' option on the Eclipse menu bar. This wizard would ask questions such as how the data manager is to be packaged (J2EE or OSGi) and the target location for both the server component and for the client component.
+
We will provide a context menu option for data manager projects as follows: <b>Systems Management > Deploy...</b>. This will allow the developer to run the data manager within Eclipse.  The problem with using the standard <b>Run...</b> menu option is there are multiple, tedious steps involved in setting up the launch configuration.  See [[COSMOS_Programming_Model#Running_the_MDR_within_Eclipse]] for an example of those manual steps.  The new menu option will ensure all of these steps happen under the covers.
  
 
== '''Open Issues/Questions '''==
 
== '''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-->
* What other things are available, e.g. STP or WTP may have annotations for web services
+
  
 
All reviewer feedback should go in the [[Talk:COSMOS_Design_208274|Talk page for 208274]].
 
All reviewer feedback should go in the [[Talk:COSMOS_Design_208274|Talk page for 208274]].

Revision as of 14:04, 29 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
David Whiteman 1/24/2008
  • edits per MDW feedback
David Whiteman 1/25/2008
  • edits per Ali feedback

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. It also includes the Eclipse tooling specified in this design.

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.
  3. Developer wants to start data manager in Eclipse.
    This is addressed in Deployment.

Development environment

  • Developer will install a set of plug-ins into the Eclipse workbench, and will download noted COSMOS prerequisites.
  • 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
  • Documentation on how to build data managers will be provided, and integrated with the Eclipse help system

Extensibility

  • Adopters will create extensions to the COSMOS framework in the Eclipse workbench environment.
  • The following extension points will be provided:
    • Project creation wizard pages for specialized data manager types (e.g. MDR, federating CMDB)
    • Export wizard pages for packaging type (e.g. J2EE, OSGi)
    • Manage relationships between the two
  • Examples and documentation on how to extend the COSMOS framework will be provided, integrated with the Eclipse help system.

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:

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. NOTE: The *mdrname variable in the package names will use the value of the "Data manager name" field, in lowercase form, with spaces removed. The *userpackageprefix variable is a value supplied by the user to indicate the prefix for all generated package names.

  • Creates projects:
    • *userpackageprefix.*mdrname.dataManager.server
    • *userpackageprefix.*mdrname.dataManager.client
    • *userpackageprefix.*mdrname.dataManager.common
  • 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 (SHOULD WE LIST org.apache.muse.complete INSTEAD? WHERE TO GET THIS?)
    • org.eclipse.osgi_3.3.2.R33x*
    • org.eclipse.cosmos.common
    • org.eclipse.dc.dataManager (only when project is standard data manager)
    • org.eclipse.dc.mdr (only when project is MDR)
    • org.eclipse.cosmos.management.common (WHAT IS THIS?)
  • Creates Plug-in Dependencies (Common Project)
    • org.eclipse.dc.dataManager.common
  • Creates Plug-in Dependencies (Client Project)
    • org.eclipse.dc.dataManager.client


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

  1. MdrName
  2. Resource_ID
  3. Display Name
  4. Description
  5. Whether to create a client-side plug-in

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

Create client plug-in option

When the Create client plug-in option is selected, the user will be prompted for a custom class to be instantiated for the client. If the option is not selected, the default implementation of MdrClient will be used.


Generating EPRs

Building EPRs by hand is a tedious and error prone activity. This is a place where UIs can be really helpful, since you can have integrated help, lists of valid values, and more readable labels. Plus, typing raw XML is laborious. This section defines a UI so users don't have to hand-code these EPRs. 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

Deployment target selection

The next page of the project creation wizard will allow the selection of the deployment target for the data manager. The choices presented will be gathered through a new extension point. The provided implementation will pre-define the targets of J2EE and OSGi, and adopters can add custom deployment targets.

Another extension point will allow adopters to provide custom wizard pages for the selected deployment target. These pages will allow input of target-specific properties.

Data manager type selection

Following the wizard page(s) related to the deployment target, a wizard page will be displayed to prompt the developer for the type of data manager to be created. There will be a new extension point to supply the list of data manager types; the default implementation of the extension point will define the values "Standard data manager", "Management data repository (MDR)", and "Federating CMDB". For each type, other information such as icon, description, abstract parent class, and prerequisite plug-in will be indicated in the extension point.

There will be yet another extension point that specifies which data manager types are allowed for the indicated deployment target; this subset will be presented for user selection.

Another extension point will allow adopters to provide custom wizard pages for the selected data manager type. These will allow the input of properties unique to the data manager type.

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

The parent class of the data manager class depends on the data manager type:

  • standard data manager: AbstractDataManager
  • MDR: AbstractMdr
  • Federating CMDB: AbstractFederatingCMDB (ref: COSMOS_Design_215267)
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

The contents of this file are built from the values entered on the first page of the project creation wizard. This file will also be updated when you change these values using the project editor wizard, which is opened when you edit this file in Eclipse.

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

domainEPR.xml

The contents of this file depend on the values entered on the Endpoint Reference page of the Project Creation Wizard. This file will also be updated when you change these values using the project editor wizard, which is opened when you edit this file in Eclipse.

<?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

  • The Bundle-Name is set using the Data Manager Name value
  • The *userpackageprefix variable in the package name will be a user-prompted value used for the prefix on all generated packages
  • The *mdrname variable in the package names will use the value of the "Data manager name" field, in lowercase form, with spaces removed
Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: Example MDR
Bundle-SymbolicName: *userpackageprefix.*mdrname.mdr
Bundle-Version: 1.0.0
Bundle-Activator: *userpackageprefix.*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: *userpackageprefix.*mdrname.mdr

Import Wizard

A developer will want to be able to import an existing data manager into Eclipse. We will need to provide an import wizard (using the Eclipse import dialog extension point) for the case where the data manager is not being built from scratch. The developer would select File > Import... from the Eclipse menu bar to navigate to this wizard.

Deployment

We will provide a context menu option for data manager projects as follows: Systems Management > Deploy.... This will allow the developer to run the data manager within Eclipse. The problem with using the standard Run... menu option is there are multiple, tedious steps involved in setting up the launch configuration. See COSMOS_Programming_Model#Running_the_MDR_within_Eclipse for an example of those manual steps. The new menu option will ensure all of these steps happen under the covers.

Open Issues/Questions

All reviewer feedback should go in the Talk page for 208274.

References

Back to the top