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

(→‎Graphical View)
(→‎Task Breakdown)
 
(11 intermediate revisions by the same user not shown)
Line 10: Line 10:
 
|05/21/2008
 
|05/21/2008
 
|<ul><li>Initial version</li></ul>
 
|<ul><li>Initial version</li></ul>
 +
|-
 +
|Ali Mehregani
 +
|05/28/2008
 +
|<ul><li>Modified document based on comments in DV call (May 28/08)</li></ul>
 
|}
 
|}
  
Line 66: Line 70:
 
This enhancement is associated with [https://bugs.eclipse.org/bugs/show_bug.cgi?id=224166 bugzilla 224166].
 
This enhancement is associated with [https://bugs.eclipse.org/bugs/show_bug.cgi?id=224166 bugzilla 224166].
 
<p>
 
<p>
−
The purpose of this enhancement is to improve the graph response view displayed when querying an MDR.  The view is currently convoluted and difficult to interpret by a novice user.  This design document lists a number of changes to improve usability and overall structure of the view.
+
The purpose of this enhancement is to improve the graph response view displayed when querying an MDR.  The view is currently convoluted and difficult to interpret by a novice user.  This document lists a number of changes to improve usability and overall structure of the view.
 
</p>
 
</p>
  
Line 76: Line 80:
  
 
</p>
 
</p>
 +
 +
It was collectively agreed during the data visualization call (May 28/2008) for this enhancement not to replace the current graphical view.  Users will have the option to use either one to display the CMDBf response.
  
 
== Implementation Detail ==
 
== Implementation Detail ==
Line 101: Line 107:
 
The graph layout algorithm renders adjacent nodes closer to each other.  This will visually indicate entities that are closer together in relation.  The radius of each node is determined by its order (i.e. outgoing edges from the node) and the color of the node is dependent on the template it belongs to.  Notice a legend is displayed at the bottom of the diagram.
 
The graph layout algorithm renders adjacent nodes closer to each other.  This will visually indicate entities that are closer together in relation.  The radius of each node is determined by its order (i.e. outgoing edges from the node) and the color of the node is dependent on the template it belongs to.  Notice a legend is displayed at the bottom of the diagram.
  
−
=== Registration ===
+
The graph layout algorithm is not sufficient for responses with many items or relationships.  The graph is best suited for 30 or less nodes with a maximum node order of 3.  The graph view will not be generated if this condition is not met.  A warning will be displayed and the space will be reserved for the logical representation (see next section).  Users will have the ability to discard the warning and display the graph if they choose to populate the view.
  
−
CMDBf specifies a registration service by which MDRs register items and relationships with the federating CMDB.  The process for registration involves an XML-based transaction, similar to how the query service works.  This enhancement will provide a transformer to convert a registration request from XML to a POJO graph structure, and will also provide the reverse of that transformation.  In addition, it will provide another transformer that will convert a registration response output by the MDR from a POJO graph structure to the XML-based syntax expected by the CMDBf spec, and will again provide a reverse of that transformation.  The reverse transformations are needed by some clients of the registration service, and also are useful in unit testing of the implementation.
 
  
−
The following new classes will provide these transformations:
+
The image below displays a concrete example based on data from the student-teacher MDR.  The value of this graphical overview is the ability to quickly identify relationships between two different entities.  Using this diagram, the user is quickly able to identify the following relationships:
  
−
org.eclipse.cosmos.dc.cmdbf.services.provisional.registration.transform.RegistrationInputTransformer
+
* Staff01 teaches Student01 and Student03
−
org.eclipse.cosmos.dc.cmdbf.services.provisional.registration.transform.RegistrationOutputTransformer
+
* Staff02 teaches Student01, Student02, Student03
  
−
The following are the transformation APIs on the RegistrationInputTransformer class:
+
<p>
 +
[[Image: graph_response_visual2.png]]
 +
</p>
  
−
static public RegisterRequest transform(InputStream)
+
=== Logical View ===
−
static public InputStream transform(RegisterRequest)
+
  
−
The following are the transformation APIs on the RegistrationOutputTransformer class:
+
A tree structure is provided to allow traversal of the response elements.  Unlike a grid structure, a tree will only occupy the space needed.  The properties view will be used to display any fields associated with a selected tree node.  The image below provides an overview of the tree structure:
  
−
static public RegisterResponse transform(InputStream)
 
−
static public InputStream transform(RegisterResponse)
 
−
 
−
RegisterRequest and RegisterResponse POJOs will consist of APIs and classes that match or closely mirror the corresponding element names in the CMDBf data model.  RegisterRequest will reside in the <tt>org.eclipse.cosmos.dc.cmdbf.services.provisional.registration.transform.input.artifacts</tt> package and RegisterResponse will live in the <tt>org.eclipse.cosmos.dc.cmdbf.services.provisional.registration.transform.response.artifacts</tt> package.
 
−
 
−
Here is a simple example that illustrates the incoming registration input transformation:
 
−
 
−
<tt>InputStream inputStream = new ByteArrayInputStream(example1().getBytes());<br>
 
−
RegisterRequest registerRequest = RegistrationInputTransformer.transform(inputStream);</tt>
 
−
 
−
Assume that <tt>example1()</tt> returns a String containing the XML syntax for a <registerRequest> as specified in the CMDBf spec.
 
−
 
−
== Services ==
 
−
=== Query ===
 
−
 
−
The class diagram below displays the interfaces and default implementations that will be included for the query service.  All that a contributor is required to do is to register the classes that will be used as handlers for the selectors.  The default implementation of the CMDBf query operation will look up the appropriate handlers and will invoke them accordingly.
 
−
<br/><br/><br/>
 
 
<p>
 
<p>
−
[[Image:QueryService-v1.png]]
+
[[Image:graph_response_logical.png]]
 
</p>
 
</p>
  
−
<p>
+
Each level of the tree is described below:
−
The following is a snippet of code that illustrates how a contributor can register a set of selector handlers with the default implementation of <code>ISelectorHandlerFactory</code>.:
+
  
−
<code>
+
* First level: item/relationship template ID
−
<pre>
+
* Second level: the first item/relationship local ID
−
SelectorHandlerFactory.getInstance().addHandlers
+
* Third level: record ID
−
(
+
−
        new URI ("http://cosmos.org/mdrId"),
+
−
        ISelectorHandlerFactory.ITEM_TEMPLATE,
+
−
        new String[]
+
−
        {
+
−
            "org.eclipse.cosmos.sample.handlers.InstanceIdHandler",
+
−
            "org.eclipse.cosmos.sample.handlers.RecordTypeHandler",
+
−
            "org.eclipse.cosmos.sample.handlers.PropertyValueHandler",
+
−
            "org.eclipse.cosmos.sample.handlers.XPath1Handler"
+
−
        }
+
−
);
+
−
</pre>
+
−
</code>
+
  
−
Once the selectors are registered a client can make use of the CMDBf query service using the default implementation of <code>ICMDBfQueryOperation</code>.  The argument passed into the <code>initialize</code> method represents a data provider that will be passed to each of the selector handlers.  The selector handlers can cast the argument to a specific type that can process native queries that is understandable by a specific data provider.  The following snippet of code illustrates how the query operation can be invoked:
+
The properties view will be populated based on selection of nodes.  The following fields will be displayed for each tree item selected:
  
−
<code>
+
{|{{BMTableStyle}}
−
<pre>
+
!align="left"|Tree Item:
−
// Create a CMDBf query operation object and have it initialized
+
!align="left"|Fields:
−
CMDBfQueryOperation cmdbfQueryOperation = new CMDBfQueryOperation();
+
|-
−
cmdbfQueryOperation.initialize(new SampleDataProvider());
+
|Item/Relationship template
−
+
|No fields will be displayed
−
// Execute the query
+
|-
−
Query query = retrieveQuery();
+
|Item/Relationship
−
cmdbfQueryOperation.execute(query);
+
|
−
</pre>
+
* All instance IDs
−
</code>
+
* Additional record types
−
 
+
* For relationships, source and target will also be displayed
−
Assuming <code>retrieveQuery()</code> will return a POJO representation of a CMDBf query.
+
|-
−
 
+
|Records
−
=== Registration ===
+
|
−
The diagram below shows the relationship between the classes of the registration service.  The APIs are very symmetric to the ones provided for the query service.  An adopter will need to subscribe register handlers for specific MDR IDs.  The subscribed register handlers will be invoked if the MDR ID of the registration request matches that of the ID associated with the handler.
+
* Last modified
−
 
+
* Snapshot ID
−
[[Image:RegistrationService-v2.png]]
+
* Base line ID
−
 
+
|}
−
The snippet of code below shows how a client can subscribe a registration handler.  <code>CustomRegistrationHandler</code> is expected to be an implementation of <code>IRegisterHandler</code>.
+
−
 
+
−
<code>
+
−
<pre>
+
−
 
+
−
RegisterHandlerSubscription.getInstance().addHandler
+
−
(
+
−
      new URI("http://cosmos.org/mdrId"),  
+
−
      new CustomRegistrationHandler()
+
−
);
+
−
</pre>
+
−
</code>
+
−
 
+
−
The default implementation of <code>ICMDBfRegistrationOperation</code> can be used to process a registration request.  The snippet below shows how a client can use the operation:
+
−
 
+
−
<code>
+
−
<pre>
+
−
// Perform the initialization
+
−
CMDBfRegistrationOperation registrationOperation = new CMDBfRegistrationOperation();
+
−
registrationOperation.initialize(new SampleDataProvider());
+
−
+
−
// Execute the operation
+
−
Registration registration = retrieveRegistration();
+
−
registrationOperation.execute(registration);
+
−
</pre>
+
−
</code>
+
−
 
+
−
Assuming <code>retrieveRegistration()</code> will return a POJO representation of a CMDBf registration request.
+
−
 
+
−
== ''' Test Coverage ''' ==
+
−
 
+
−
Unit tests will need to perform the following tests:
+
  
−
* Transform a RegisterRequest POJO to XML and back to a POJO, and compare the start and end POJOs
+
Double clicking a record will open a dialog box with the XML content of the associated record.
−
* Transform a RegisterResponse POJO to XML and back to a POJO, and compare the start and end POJOs
+
−
* Process an empty query
+
−
* Processing a query with just one item
+
−
* Processing a query with a relationship and no items
+
−
* Processing a query with matching items and an unmatched relationship
+
−
* Processing a query with matching items and a matched relationship
+
−
* Processing a query with a relationship that has cardinality
+
−
* Processing a query with unregistered selector handlers
+
−
* Processing an empty registration request
+
−
* Processing a registration request with one item
+
−
* Processing a registration request with matched items and missing relationship
+
−
* Processing a registration request with matched items and a relationship
+
−
* Processing a registration request with a relationship and no items
+
−
* Processing a registration request with missing registration handlers
+
  
−
== ''' Task Breakdown ''' ==
+
== Task Breakdown ==
  
−
The following section includes the tasks required to complete this enhancement <!--along with a PERT chart that displays the dependencies of each task-->.
+
The following section includes the tasks required to complete this enhancement  
  
−
[[image:CMDBf-PertChart-v1.png]]
+
# Isolate the query response view as a separate test page (the one that currently exists is outdated) <font color="green">[complete]</font>
 +
# Define a structure to be used by the graph layout algorithm <font color="green">[complete]</font>
 +
# Modify outputters to generate the structure <font color="green">[complete]</font>
 +
# Create the graph layout algorithm <font color="green">[complete]</font>
 +
# Write code to render the graph <font color="green">[complete]</font>
 +
# Define a structure to be used by the logical tree structure (determine if the same structure as the graph layout can be used) <font color="green">[complete]</font>
 +
# Modify outputters to generate the structure <font color="green">[complete]</font>
 +
# Create a tree based on the structure <font color="green">[complete]</font>
 +
# Decorate the tree items with icons
 +
# Use topic publication/subscription to detect tree item selections <font color="green">[complete]</font>
 +
# Populate the properties view based on the selection <font color="green">[complete]</font>
 +
# Create the overall layout of the view <font color="green">[complete]</font>
 +
# Add the graph and logical component to the main view <font color="green">[complete]</font>
 +
# Determine how to add this as an alternative view to displaying the CMDBf query response
  
 +
== Future Direction ==
  
−
# Refactor plugin, package and class names in cmdbf.query plugin to represent the 5 different jar configurations
+
* Showing direction of relationships in the graph view
−
# Refactor the JUnits for the query transformation
+
* Displaying edges only when user hovers over a node
−
# Create graph representation of registration request and response
+
* Adding additional interaction (e.g. display information when hovering over a node)
−
# Create the registration input transformer
+
* Once COSMOS has the capability of adding user profiles, add the ability to disable parts of the view users may not be interested in.
−
# Create the registration output transformer
+
−
# Add in JUnits for the registration transformer
+
−
# Add in the APIs for processing a CMDBf query
+
−
# Implement a generic implementation of the CMDBf query processor
+
−
# Add in JUnits for the CMDBf query APIs
+
−
# Modify the SML repository to make use of the new API set
+
−
# Add in the APIs for processing a CMDBf registration request
+
−
# Implement a generic implementation of the CMDBf registration processor
+
−
# Add in JUnits for the registration APIs
+
  
−
== '''Open Issues/Questions '''==
+
== Open Issues/Questions ==
  
−
All reviewer feedback should go in the [[Talk:COSMOS_Design_204959|Talk page for 204959]].
+
All reviewer feedback should go in the [[Talk:COSMOS_Design_224166|Talk page for 224166]].
 
----
 
----
 
[[Category:COSMOS_Bugzilla_Designs]]
 
[[Category:COSMOS_Bugzilla_Designs]]

Latest revision as of 11:41, 5 June 2008

Improve the Graph Response Viewer

Change History

Name: Date: Revised Sections:
Ali Mehregani 05/21/2008
  • Initial version
Ali Mehregani 05/28/2008
  • Modified document based on comments in DV call (May 28/08)

Workload Estimation

Rough workload estimate in person weeks
Process Sizing Names of people doing the work
Design .5 Ali Mehregani
Code 3.5 Ali Mehregani
Test .5 Ali Mehregani
Documentation 0
Build and infrastructure 0
Code review, etc.* 0
TOTAL 4.5

Terminologies/Acronyms

The terminologies/acronyms below are commonly used throughout this document. The list below defines each term regarding how it is used in this document:

Term Definition
MDR Management Data Repository

Purpose

This enhancement is associated with bugzilla 224166.

The purpose of this enhancement is to improve the graph response view displayed when querying an MDR. The view is currently convoluted and difficult to interpret by a novice user. This document lists a number of changes to improve usability and overall structure of the view.

The image below indicates a number of usability issues with the current view:

Graph response.png

It was collectively agreed during the data visualization call (May 28/2008) for this enhancement not to replace the current graphical view. Users will have the option to use either one to display the CMDBf response.

Implementation Detail

This section outlines an alternative layout to address the issues displayed above. The new layout will consist of two parts:

  1. A graphical view to display a visual overview of the response
  2. A logical tree structure to traverse through the elements of the response

The layout will consist of three sections, indicated in the image below:

Graph response new layout.png

Graphical View

The top most section of the view will consist of a graphical representation of the response. The section will leverage dojox.gfx APIs along with atomic shapes to render a graph. The APIs use SVG in FireFox and VML in IE to render the individual shapes. The end result is a static diagram with cross-browser support.

The image below shows a sample of what the graph will look like:

File:Graph response visual.png

The graph layout algorithm renders adjacent nodes closer to each other. This will visually indicate entities that are closer together in relation. The radius of each node is determined by its order (i.e. outgoing edges from the node) and the color of the node is dependent on the template it belongs to. Notice a legend is displayed at the bottom of the diagram.

The graph layout algorithm is not sufficient for responses with many items or relationships. The graph is best suited for 30 or less nodes with a maximum node order of 3. The graph view will not be generated if this condition is not met. A warning will be displayed and the space will be reserved for the logical representation (see next section). Users will have the ability to discard the warning and display the graph if they choose to populate the view.


The image below displays a concrete example based on data from the student-teacher MDR. The value of this graphical overview is the ability to quickly identify relationships between two different entities. Using this diagram, the user is quickly able to identify the following relationships:

  • Staff01 teaches Student01 and Student03
  • Staff02 teaches Student01, Student02, Student03

Graph response visual2.png

Logical View

A tree structure is provided to allow traversal of the response elements. Unlike a grid structure, a tree will only occupy the space needed. The properties view will be used to display any fields associated with a selected tree node. The image below provides an overview of the tree structure:

Graph response logical.png

Each level of the tree is described below:

  • First level: item/relationship template ID
  • Second level: the first item/relationship local ID
  • Third level: record ID

The properties view will be populated based on selection of nodes. The following fields will be displayed for each tree item selected:

Tree Item: Fields:
Item/Relationship template No fields will be displayed
Item/Relationship
  • All instance IDs
  • Additional record types
  • For relationships, source and target will also be displayed
Records
  • Last modified
  • Snapshot ID
  • Base line ID

Double clicking a record will open a dialog box with the XML content of the associated record.

Task Breakdown

The following section includes the tasks required to complete this enhancement

  1. Isolate the query response view as a separate test page (the one that currently exists is outdated) [complete]
  2. Define a structure to be used by the graph layout algorithm [complete]
  3. Modify outputters to generate the structure [complete]
  4. Create the graph layout algorithm [complete]
  5. Write code to render the graph [complete]
  6. Define a structure to be used by the logical tree structure (determine if the same structure as the graph layout can be used) [complete]
  7. Modify outputters to generate the structure [complete]
  8. Create a tree based on the structure [complete]
  9. Decorate the tree items with icons
  10. Use topic publication/subscription to detect tree item selections [complete]
  11. Populate the properties view based on the selection [complete]
  12. Create the overall layout of the view [complete]
  13. Add the graph and logical component to the main view [complete]
  14. Determine how to add this as an alternative view to displaying the CMDBf query response

Future Direction

  • Showing direction of relationships in the graph view
  • Displaying edges only when user hovers over a node
  • Adding additional interaction (e.g. display information when hovering over a node)
  • Once COSMOS has the capability of adding user profiles, add the ability to disable parts of the view users may not be interested in.

Open Issues/Questions

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

Retrieved from "https://wiki.eclipse.org/index.php?title=COSMOS_Design_224166&oldid=102321"

This page was last modified 11:41, 5 June 2008 by Eclipsepedia user Amehrega.ca.ibm.com.

Back to the top