Perforce JViews TGO Sample: Tree 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 tree supports standard interaction for expanding and collapsing nodes, as well as multiple selection. Click a node to select it. Use the The sample also shows how to define custom behavior. Double-clicking any tree node shows a small dialog with some information about the associated business object. Right-clicking any node displays a contextual pop-up menu that allows you to set the selected nodes as roots of the tree. To reset the tree to its original state, right-click outside any node and select 'Reset root nodes' from the pop-up menu. Using the 'Filter pattern' text field in the lower part of the window you can apply a basic filter to the tree. Type a text into the field, then press Return. Only the nodes with names containing the given pattern will be displayed. Note that a node will only be shown if its parent is also shown. Using '1' or '2' as the pattern gives the best results in this sample. Finally, the sample shows how the look of the predefined business objects and the tree component can be customized through style sheets. You can select from a number of predefined style sheet files (each of which change a single aspect of the representation) using the 'Style sheet' list in the lower part of the screen.Shift
key to select several adjacent nodes or Ctrl
to select non-adjacent nodes. You will see the names of the selected nodes appear in the 'Current selection' area at the bottom of the screen. The JTGO tree component has two representations for selection: Highlight and Checkbox. To switch between the two modes use the 'Selection mode' list in the lower part of the sample window.
How to Run the Sample as an Application
This sample can
be run as an application.
The installation directory contains
an executable JAR file,
tree-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
- Creating a tree component
- Using the data source API to define business object relationships
- Using the data source API to add business objects
- Sorting tree nodes
- Managing selection in a tree
- Showing a contextual pop-up menu
- Defining custom interactions
- Filtering tree nodes
- Changing the rendering of the tree and its nodes
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 tree component through an adapter (ilog.cpl.tree.IlpContainmentTreeAdapter) which converts business objects into representation objects that are stored in the tree component model (ilog.cpl.tree.IlpTreeModel). The business model is mapped to the tree 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 business objects and their relationships do not necessarily have to be created at the same time.
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 source is very important. It is recommended to create the relationships before adding the business objects so that the adapter does not have to recreate the representation objects due to changes in the business object relationships notified by the data source. 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 Although this is not mandatory for the tree component, it is also recommended to add the child objects before the parent objects into the data source.
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);
Installation Directory
The Tree Component - Data Source API sample is installed here.
Classes Involved
-
ilog.cpl.IlpSystem
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.IlpTree
The tree component.
-
ilog.cpl.util.IlpAttributeComparator
The comparator used to sort nodes in the tree component.
-
ilog.cpl.tree.IlpTreeSelectionModel
The selection model implementation of the tree component.
-
ilog.cpl.interactor.IlpAbstractPopupMenuFactory
The pop-up menu factory helper implementation.
-
ilog.cpl.util.selection.IlpObjectSelectionModel
The selection model that handles business objects.
-
ilog.cpl.util.IlpFilter
The interface that defines object filters.
Source Files
-
datasourceAPI.Main
The entry point of the sample.
-
datasourceAPI.ObjectCreationSupport
The utility class that provides static methods to create the business objects used in the sample.