COSMOS Design Interaction Model

Background

The design of the COSMOS user interface implores a model-view controller architecture. As a result there's a clear separation between the presentation information and the raw data. First understand that there are two parts to the UI:

• Web interface
• Reports

Consider the following diagram that shows how the web ui is separated from the data.

Note that the ui widgets consume JSON data structures that are produced by a set of servlets. An "outputter" class is associated with each servlet. The purpose of the outputter class is to take in some form on input object and transform the contents of the output to JSON. The outputter class contains specific transform domain logic. As a result the outputter class contains is aware of the input format and the output format that a specific widget requires. This architecture will allow the support of additional output formats other than JSON. Furthermore if the input data structure changes the changes are isolated in the outputter class.

Now let us consider the COSMOS reports. Fortunately, COSMOS reports follow the BIRT report programming model. As a result each COSMOS report template constructs a dataset based on an Object Data Access(ODA) component to access the raw data from a datasource.

Again there's a clean separation between presentation information and data access. The ODA contains the binding and query APIs. The dataset and datasource defined in the report template contains the logic and business logic to manipulate the data without affecting the cosmetic data (ie. layout of tables, charts, color of fonts, etc.) If the data binding to the datasource or query logic change, only the datasets are affected.

With the following said, the interaction model between the COSMOS UI only effects the binding and query logic. Let us consider these two issues separately.

Actors

The following are actors that are involved in the binding, and query operations. Note this design document assume that there is only one data broker. Additional thought is required to support multiple data brokers.

• Client - an application that consumes data from an MDR
• Data Broker - holds registry of MDR end point references.
• MDR - managed data repository

Binding operation

After executing the binding operation the client should have the means to query a MDR.

First the client requires a handle to the data broker. Therefore some form of bootstrapping is required. org.eclipse.cosmos.dc.remote.wsdm.spec.DataBrokerClient provides the following boot strap api.

public static EndpointReference getDataBrokerEPR( String hostAddress, int runtimePort ) throws Exception

Note that a host address and a runtime port is required to get the EPR for the data broker. This information is configured by the client and will most likely be configured in the web.xml of the COSMOS web UI.

Once the EPR is received the client can create an instance of the DataBrokerClient to use the convenient APIs to get anEPR representing a MDR as mentioned in the COSMOS Designed document for enhancement 197867(http://wiki.eclipse.org/COSMOS_Design_197867).

//
// get the Data Broker client from its endpointReference
//
DataBrokerClient brokerClient = new DataBrokerClient( brokerEPR ); 		
//
// get the Data Managers from the Data Broker for the "Performance" classification
//
Element result = brokerClient.getDataManagers( "Performance" );				
System.out.println(XmlUtils.toString(result));

Note the getDataManagers("Performance") call will return a DOM element that repesents a list of EPRs.

Open Issue - Why does the DataBrokerClient.getDataManagers api return a DOM element? Are there cases where the getDataManagers may not be EPRs? Was this api designed to be very generic?

If an API is not provided to return a list of EPRs, each client will need to write an API that converts the DOM element to a list of EPRs.

Query operation

Once the client resolves the list of EPRs a web service client can be created to query the MDRs. Each web service client defines a set of convenient APIs that will help the client to query the MDR. For example, org.eclipse.cosmos.dc.remote.wsdm.spec.StatisticalQueryClient contains a set of convenient apis to extract statistical observations from a statistical data repository. The following shows the code snippet that demonstrates this operation.

// get the Statistical MDR client from its endpointReference
//
StatisticalQueryClient statClient = new StatisticalQueryClient( statEPR ); 			
//
// get the Data Managers from the Data Broker for the "Performance" classification
//
Collection<StatisiticalTuple> obervations = stataClient.dimensionQuerydataset, keyset, dimension, start, stop);

Similarly, there should exist a Web service client interface for monitoring data (CBE) and an interface to query the SML repository. Note: the web service client interface will provide an API to send CMDBf queries and return XML graph response.

COSMOS Web UI Scenarios

Let us now look at the COSMOS Web UI Scenarios to understand the interaction model between the Web UI Client and the data broker and MDRs.

Presenting resources in the Web UI tree widget

The following diagram shows the flow of presenting a list of tomcat servers in the navigator tree.

1. The client sends a request to ask for a list of tomcat servers.
2. The Navigator servlet contacts the broker and asks for the EPR that has SML information.
3. The broker returns a list of EPRs that have SML information.
4. The Navigator servlet constructs a web service client that provides the API to construct CMDBf queries on a SML repository MDR. The navigator servlet then constructs a CMDBf query that asks the SML repository for a list of tomcat servers.
5. A graph result is returned to the navigator servlet
6. The navigator servlet parses the Graph result response and constructs a JSON structure that is consumed by the navigator DOJO widget. The information is presented in a tree.

Presenting properties of a resource in the Web UI table

At this point the user wants to inspect the properties on a resource and determine if there's any data collected for the resource. As a result, the end user clicks on a resource in the navigator tree to see the properties of that resource. A request is sent to the properties servlet with a resource id.

Open issue: How does the client determine whether a resource has collected data? Where is this information stored?

One suggestion is that the broker contains this information. If this is the case the properties servlet needs to query the broker to determine if the resource has any collected data. Therefore, the properties servlet needs the ability to query the meta data of the broker to get a list of key family values based on a resource id. If a set of key family values ("statistical", "cbe", etc.) are associated with the resource, these values are presented to the end user showing that there is some form of collected data for this resource. In addition the properties servlet will query the SML repository for additional properties values for these resource based on the resource id. At this point if the user wants to generate a report based on a particular key family they would select the appropriate report type. A request is sent to the COSMOS report system containing the key family value that was selected along with the resource id. This information would be used to query the data broker to get the MDR that has the collected data. A query would be constructed and sent to the MDR to get the statistical tuples. The query and binding logic would be located in the BIRT ODA.

The following diagram shows the flow of presenting the properties of a particular tomcat server.

1. The end user clicks on a tomcat node in the tree. The client sends a request, containing the resource id, to the properties servlet for the list of properties.
2. The Properties servlet contacts the data broker and asks if there are any EPRs that have collected data for the particular resource. for the EPR that has SML information.
3. The broker returns a list of key family values that are associated with the resource.
4. The Properties constructs a CMDBf query that asks the SML MDR for the properties of the particular resource.
5. A graph result is returned to the Properties servlet containing the property values.
6. The Properties servlet parses the Graph result response and constructs a JSON structure that is consumed by the property table DOJO widget. If there a list of key family values are returned in step 3 this list is presented to the user to indicate that there is collected data for this resource. For example, the list can show whether the resource has statistical or monitoring (CBE) collected data.

Open Issue: Is the resource id sufficient to get the properties for a particular resource? Does the client need any other additional information to query the SML repository?

Generating a report from the Web UI

At this point the user is presented with a table of properties associated with a resource. In this scenario the table widget will show that the resource has statistical data and provide a button that will allow the user to send a request to the back end to generate a report. Once the user clicks the button a request containing the resource id, key set family (statistical) and a report template id is sent to the report viewer. The report viewer delegates the request to the report template that contains the binding and query logic. The report template binding logic will have boot strap code to get a handle of the data broker. The binding logic will also include the steps to get the right MDR that has the statistical data for the particular resource. Once the MDR is retrieved a query can be sent to the MDR to get the observation tuples to generate the report.

Open Issue: The resource id stored in the data broker to get the statistical data has to correspond to the resource id stored in the SML repository

Open Issues Talks

Why does the DataBrokerClient.getDataManagers api return a DOM element? Are there cases where the getDataManagers may not be EPRs? Was this API designed to be very generic?

How does the client determine whether a resource has collected data? Where is this information stored?

[Sheldon's comment]One suggestion is that the client can query the broker for this information. This means that the Broker will contain meta information such as the key family value and resource id. Note this mean that when a MDR will register with the broker multiple times for each resource id it manages.

Is the resource id sufficient to get the properties for a particular resource? Does the client need any other additional information to query the SML repository?

The resource id stored in the data broker to get the statistical data has to correspond to the resource id stored in the SML repository

Interaction Enhancements between Data Visualization client and Data Collection runtime

200254 Refactor Navigator and Properties Servlet to integrate with Broker APIs

200274 Refactor Navigator and Properties servlet to create CMDBf queries

200275 Refactor BIRT ODA to use Data Collection Convenient query asembly APIs