Rogue Wave JViews TGO Sample: Equipment 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 sample shows a typical equipment view, with shelves containing cards, and cards containing ports and LEDs.

The JTGO equipment component provides multiple predefined modes of interaction. In this sample, the default behavior is to allow objects to be selected but not moved. You can select a different mode from the toolbar at the top of the screen. The following interactors are enabled in the sample:

• Select
  Allows you to select all objects. To select a shelf, click close to its border. To select multiple objects, drag a rectangle around them.
  
• Pan
  Moves the contents of the view.
  
• Zoom In
  Zooms in by a specified factor.
  
• Zoom Out
  Zooms out by a specified factor.
  
• Zoom Back
  Restores the view to the previous zoom factor.
  
• Reset Zoom
  Resets the zoom factor to the original setting.
  
• Fit to Contents
  Resizes the image so that the whole content displays in the available area.
  
• Zoom on Rectangle
  Zooms in on an area delimited by dragging a rectangle around it.
  

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, equipment-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

• Initializing a JTGO application using a deployment descriptor
• Creating an equipment component
• Using a mutable style sheet to dynamically modify the CSS configuration
• Using the data source API to define business object relationships
• Using the data source API to add business objects

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:

• ilog.cpl.datasource.IlpMutableDataSource.setChildren: Declares an object as having children.
• ilog.cpl.datasource.IlpMutableDataSource.setParent: Declares an object as being the parent of another object.
• ilog.cpl.datasource.IlpMutableDataSource.setLink: Declares an object as being a link with given endpoints.

The data source is attached to the equipment component through an adapter (ilog.cpl.equipment.IlpEquipmentAdapter) which converts business objects into representation objects that are stored in the equipment component model (ilog.cpl.equipment.IlpEquipmentModel). The business model is mapped to the equipment 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 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 some graphic properties 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.IlpEquipment.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 the 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 equipment 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 Equipment Component - Data Source API sample is installed here.

Classes Involved

• ilog.tgo.IltSystem

  The class that initializes a JViews TGO application.

• ilog.tgo.datasource.IltDefaultDataSource

  The default data source implementation. It provides an API to specify the business model and add business data.

• ilog.cpl.IlpEquipment

  The equipment component.

• ilog.cpl.model.IlpObject

  The business object definition.

• ilog.cpl.equipment.renderer.IlpBackgroundsRenderer

  This class gives control over the backgrounds of an equipment component.

Source Files

• datasourceAPI.Main

  The entry point of the sample, responsible for populating the business model using the data source API.

• datasourceAPI.ObjectCreationSupport

  The utility class that provides static methods to create the business objects used in the sample.

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