Rogue Wave JViews TGO Sample: Network Component - Data Source API

Description

This sample shows how to use the Rogue Wave JViews TGO data source API to create business objects.

How to Use the Sample

The main frame contains a basic network component, with several different types of nodes and links displayed on a background map. A network component has a default toolbar which provides a set of predefined interactors:

When the Select interactor is enabled, you can expand nodes that contain objects. The sample includes such a node: SubNetwork. To expand the node, click the icon at the top right of the node. To collapse the expanded node, click the icon at the top right of the expanded node frame.

How to Run the Sample as an Application

This sample can also be run as an application. The installation directory contains an executable JAR file, network-datasourceAPI.jar, that allows you to execute the sample with a double click from a file browser. Note that if you are using Internet Explorer, you can open the installation directory and execute the JAR file from the browser. This technique may not work in other Web browsers.

Alternatively, you can run the sample application from the command line. First check that the Ant utility is properly configured. If not, see the instructions on how to configure Ant for Rogue Wave JViews.

Then, go to the installation directory of the sample and type:

ant run

Topics Covered

Detailed Description

This sample shows how to specify and populate the business model using only the API. It is nearly identical to sample basic.Main, but here the data source API is used instead of an XML file.
The business model is controlled by the mutable data source interface (ilog.cpl.datasource.IlpMutableDataSource), which allows the creation of parent-child and link-extremity relationships. This API is internally used by the default data source implementation (ilog.tgo.datasource.IltDefaultDataSource) when processing business data through XML. It can also be invoked by applications that directly manipulate business data.

The available methods to define business data relationships are:


The data source is attached to the network component through an adapter (ilog.cpl.network.IlpNetworkAdapter) which converts business objects into representation objects that are stored in the network component model (ilog.cpl.network.IlpNetworkModel). The business model is mapped to the network model, preserving the objects relationships.

The best way to create the relationships and business objects will vary from one application to another. In this sample, the business objects are known in advance and not intended to change. They are created by static methods of the class datasourceAPI.ObjectCreationSupport while their relationships are managed by method createBusinessData() (in class datasourceAPI.Main). This helps illustrate that the business objects and their relationships do not necessarily have to be created at the same time.

To be fully API driven, the sample also configures the expansion type of the container SubNetwork through a mutable style sheet (ilog.cpl.css.IlpMutableStyleSheet), which allows the dynamic modification of CSS rules through the API. Once instantiated, the mutable style sheet has to be set as a regular style sheet using method ilog.cpl.IlpNetwork.setStyleSheets. When a declaration is updated, removed from or added to the mutable style sheet, the CSS engine will process the modification automatically. When reloading the style sheets (method reloadCSSStyles() in class datasourceAPI.Main), the mutable style sheet is also taken into account, otherwise it would be lost.

When reloading the business objects (method reloadBusinessObjects() in class datasourceAPI.Main), the data source is first cleared, then followed by a call to method createBusinessData (in class datasourceAPI.Main) so that the business objects and relationships are re-created accordingly.

Considerations: The order in which the business objects and their relationships are defined in the data sources is very important. Representation objects created as leaves (ilog.cpl.model.container.IlpRepresentationNode.isLeaf) cannot have children. This means that whenever the data source promotes a leaf to a node in the business model, the adapter has to remove the corresponding representation object (leaf) and recreate it as a node allowed to have children. This operation might impact performance depending on the number of nodes. The following rules should be taken into account:

1. Create relationships first
It is recommended to create the business objects relationships before adding the objects into the data source.

2. Add children before their parent
When adding objects to the data source, it is also recommended to add child objects before adding the parent objects.

3. Add endpoints before their links
Similarly, it is better to add the two endpoints of a link before adding the link itself.

The example below illustrates the three rules above:
  datasource.setParent(parent, child);
  datasource.setLink(link, endPointA, endPointB);
  datasource.addObject(endPointA);
  datasource.addObject(endPointB);
  datasource.addObject(link);
  datasource.addObject(child);
  datasource.addObject(parent);

When the business data and their relationships are known in advance, it is likewise important to create all the relationships and to add all the objects before connecting the data source to the network component. When the data source is already connected and the number of changes is big, the operations should be carried out in the scope of a batch (ilog.cpl.datasource.IlpAbstractDataSource.startBatch and ilog.cpl.datasource.IlpAbstractDataSource.endBatch), which will suppress the data source notifications temporarily:
  datasource.setParent(parent, child);
  datasource.setLink(link, endPointA, endPointB);
  datasource.startBatch();
  datasource.addObject(endPointA);
  datasource.addObject(endPointB);
  datasource.addObject(link);
  datasource.addObject(child);
  datasource.addObject(parent);
  datasource.endBatch();


Installation Directory

The Network Component - Data Source API sample is installed here.

Classes Involved

Source Files

Copyright © Rogue Wave Software, Inc. 1997, 2015. All rights reserved. Legal terms.