Perforce JViews TGO Sample: Network 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
When the Select interactor is enabled, you can expand nodes that contain objects. The sample includes such a node:
Allows you to select and move objects in the view.
Moves the contents of the view.
Zooms in by a specified factor.
Zooms out by a specified factor.
Restores the view to the previous zoom factor.
Resets the zoom factor to the original setting.
Resizes the image so that the whole content displays in the available area.
Zooms in on an area delimited by dragging a rectangle around it.
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
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 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 a network 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 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
-
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.IlpNetwork
The network component.
-
ilog.cpl.model.IlpObject
The business object definition.
-
ilog.cpl.network.renderer.IlpToolBarRenderer
This class gives control over the toolbar of a network component.
-
ilog.cpl.network.renderer.IlpBackgroundsRenderer
This class gives control over the backgrounds of a network 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.
-
datasourceAPI.AlarmPopupMenuFactory
The factory that creates the pop-up menu in the objects.
-
datasourceAPI.ShowDetailsAction
The action that displays details about objects upon a double-click.