Perforce JViews TGO Sample: Equipment Component - Data Source API
Description
This sample shows how to use the Perforce JViews TGO data source API to create business objects.
How to Use the Sample
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
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 Perforce 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.