com.smartgwt.client.widgets.tree

Class ResultTree

java.lang.Object

com.smartgwt.client.core.BaseClass

com.smartgwt.client.data.RecordList

com.smartgwt.client.widgets.tree.Tree

com.smartgwt.client.widgets.tree.ResultTree

All Implemented Interfaces:

com.google.gwt.event.shared.HasHandlers, HasDataChangedHandlers

public class ResultTree
extends Tree

ResultTrees are an implementation of the Tree API, used to handle hierarchical data, whose nodes are DataSource records which are retrieved from a server.

Modifying ResultTrees

ResultTree nodes cannot be directly added or removed from a paged ResultTree via Tree APIs such as Tree.add() or Tree.remove(), since such trees are considered to be read-only by virtue of containing ResultSets, which are read-only data structures. Even in other FetchModes, calling such APIs will only update the local cache of the ResultTree, rather than triggering any server traffict to update the DataSource.

Use DataSource.addData()/removeData() to add/remove rows from the DataSource, and the ResultTree will reflect the changes automatically. Alternatively, the DataSource.updateCaches() method may be called to only update local caches of the DataSource in question, without generating any server traffic.

To create a locally modifiable cache of records from a DataSource, you can use DataSource.fetchData() to retrieve a List of records which can be modified directly, or you can create a client-only DataSource from the retrieved data to share a modifiable cache between several DataBoundComponents.

Nested Class Summary

Nested classes/interfaces inherited from class com.smartgwt.client.data.RecordList

RecordList.SortNormalizer

Field Summary

Fields inherited from class com.smartgwt.client.data.RecordList

jsObj

Fields inherited from class com.smartgwt.client.core.BaseClass

config, factoryCreated, factoryProperties, id, scClassName

Constructor Summary

Constructors

Constructor and Description
ResultTree()
ResultTree(com.google.gwt.core.client.JavaScriptObject jsObj)

Method Summary

Methods

Modifier and Type	Method and Description
Tree	applyFilter(Tree tree, Criteria criteria, TreeFilterMode filterMode, DataSource dataSource) The ResultTree will call applyFilter() when it needs to locally filter the tree using the current filter criteria.
Tree	applyFilter(Tree tree, Criteria criteria, TreeFilterMode filterMode, DataSource dataSource, DSRequest requestProperties) The ResultTree will call applyFilter() when it needs to locally filter the tree using the current filter criteria.
int	compareCriteria(Criteria newCriteria, Criteria oldCriteria) Default behavior is to call DataSource.compareCriteria() to determine whether new criteria is equivalent to the old criteria (returns 0) or not.
int	compareCriteria(Criteria newCriteria, Criteria oldCriteria, DSRequest requestProperties) Default behavior is to call DataSource.compareCriteria() to determine whether new criteria is equivalent to the old criteria (returns 0) or not.
com.google.gwt.core.client.JavaScriptObject	create()
void	dataArrived(TreeNode parentNode) This callback fires whenever the resultTree receives new nodes from the server, after the new nodes have been integrated into the tree.
TreeNode	get(int pos) Get the item in the openList at a particular position.
PreserveOpenState	getAutoPreserveOpenState() Controls what happens to the "open state" - the set of nodes opened or closed by the end user after tree data is loaded - when an entirely new tree of nodes is loaded from the server, as a consequence of calling ResultTree.invalidateCache() or of changing criteria such that the current cache of nodes is dropped.
boolean	getCanReturnOpenFolders() When using fetchMode:"paged" and providing multiple levels of the tree in one DSResponse, this property specifies the default value assumed for the canReturnOpenSubfoldersProperty when no value for that property is provided for a node.
java.lang.String	getCanReturnOpenSubfoldersProperty() When using fetchMode:"paged" and providing multiple levels of the tree in one DSResponse, canReturnOpenSubfoldersProperty may be set on any folder to indicate whether child folders might be returned by the server already open.
java.lang.String	getChildCountProperty() When using fetchMode:"paged" and providing multiple levels of the tree in one DSResponse, childCountProperty must be set for any folders that include only a partial list of children.
TreeNode[]	getData() Optional initial data for the tree.
DataSource	getDataSource() What DataSource is this resultTree associated with?
java.lang.Boolean	getDefaultIsFolder() Controls whether nodes are assumed to be folders or leaves by default.
java.lang.Boolean	getDefaultNewNodesToRoot() This attribute governs how to handle cache-synch when a new node is added to this dataSource with no explicit parentId.
java.lang.Boolean	getDisableCacheSync() By default when the data of this ResultTree's dataSource is modified, the ResultTree will be updated to display these changes.
java.lang.Boolean	getDiscardParentlessNodes() When data is loaded from the server, should nodes with an explicit value for the parentIdField which doesn't map to a valid parent node be dropped? If set to false, for loadDataOnDemand:false trees, parentless nodes will be added as children of the root node - for loadDataOnDemand:true, they will be added as children of the folder currently requesting children.
FetchMode	getFetchMode() Mode of fetching records from server.
java.lang.Boolean	getKeepParentsOnFilter() If set, tree-based filtering is performed such that parent nodes are kept as long as they have children that match the filter criteria, even if the parents themselves do not match the filter criteria.
java.lang.Boolean	getLoadDataOnDemand() Does this resultTree load data incrementally as folders within the tree are opened, or is it all loaded in a single request?
java.lang.String	getOpenState() Returns a snapshot of the current open state of this tree's data as a TreeGridOpenState object.
static ResultTree	getOrCreateRef(com.google.gwt.core.client.JavaScriptObject jsObj)
java.lang.Boolean	getProgressiveLoading() Sets progressive loading mode for this ResultTree.
TreeNode[]	getRange(int start, int end) Get a range of items from the open list
java.lang.Integer	getResultSize() How many tree nodes to retrieve at once from each large set of children in the tree.
com.google.gwt.core.client.JavaScriptObject	getRootNode() This attribute may be used to specify a root value for the parentIdField of this resultTree.
java.lang.String[]	getServerFilterFields() When keepParentsOnFilter is enabled for fetchMode:"local" ResultTrees, this property lists field names that will be sent to the server if they are present in the criteria.
java.lang.Boolean	getUpdateCacheFromRequest() When a successful Add, Update or Remove type operation fires on this ResultTree's dataSource, if data is unset, should we integrate the submitted data values (from the request) into our data-set?
void	invalidateCache() Manually invalidate this ResultTree's cache.
void	setAutoPreserveOpenState(PreserveOpenState autoPreserveOpenState) Controls what happens to the "open state" - the set of nodes opened or closed by the end user after tree data is loaded - when an entirely new tree of nodes is loaded from the server, as a consequence of calling ResultTree.invalidateCache() or of changing criteria such that the current cache of nodes is dropped.
void	setCanReturnOpenFolders(boolean canReturnOpenFolders) When using fetchMode:"paged" and providing multiple levels of the tree in one DSResponse, this property specifies the default value assumed for the canReturnOpenSubfoldersProperty when no value for that property is provided for a node.
void	setCanReturnOpenSubfoldersProperty(java.lang.String canReturnOpenSubfoldersProperty) When using fetchMode:"paged" and providing multiple levels of the tree in one DSResponse, canReturnOpenSubfoldersProperty may be set on any folder to indicate whether child folders might be returned by the server already open.
void	setChildCountProperty(java.lang.String childCountProperty) When using fetchMode:"paged" and providing multiple levels of the tree in one DSResponse, childCountProperty must be set for any folders that include only a partial list of children.
void	setCriteria(Criteria newCriteria) Set the filter criteria to use when fetching rows.
void	setData(TreeNode... data) Optional initial data for the tree.
void	setDataSource(DataSource dataSource) What DataSource is this resultTree associated with?
void	setDefaultIsFolder(java.lang.Boolean defaultIsFolder) Controls whether nodes are assumed to be folders or leaves by default.
void	setDefaultNewNodesToRoot(java.lang.Boolean defaultNewNodesToRoot) This attribute governs how to handle cache-synch when a new node is added to this dataSource with no explicit parentId.
void	setDisableCacheSync(java.lang.Boolean disableCacheSync) By default when the data of this ResultTree's dataSource is modified, the ResultTree will be updated to display these changes.
void	setDiscardParentlessNodes(java.lang.Boolean discardParentlessNodes) When data is loaded from the server, should nodes with an explicit value for the parentIdField which doesn't map to a valid parent node be dropped? If set to false, for loadDataOnDemand:false trees, parentless nodes will be added as children of the root node - for loadDataOnDemand:true, they will be added as children of the folder currently requesting children.
void	setFetchMode(FetchMode fetchMode) Mode of fetching records from server.
void	setKeepParentsOnFilter(java.lang.Boolean keepParentsOnFilter) If set, tree-based filtering is performed such that parent nodes are kept as long as they have children that match the filter criteria, even if the parents themselves do not match the filter criteria.
void	setLoadDataOnDemand(java.lang.Boolean loadDataOnDemand) Does this resultTree load data incrementally as folders within the tree are opened, or is it all loaded in a single request?
void	setOpenState(java.lang.String openState) Reset the set of open folders within this tree's data to match the TreeGridOpenState object passed in.
void	setProgressiveLoading(java.lang.Boolean progressiveLoading) Sets progressive loading mode for this ResultTree.
void	setResultSize(java.lang.Integer resultSize) How many tree nodes to retrieve at once from each large set of children in the tree.
void	setRootNode(com.google.gwt.core.client.JavaScriptObject rootNode) This attribute may be used to specify a root value for the parentIdField of this resultTree.
void	setServerFilterFields(java.lang.String... serverFilterFields) When keepParentsOnFilter is enabled for fetchMode:"local" ResultTrees, this property lists field names that will be sent to the server if they are present in the criteria.
void	setUpdateCacheFromRequest(java.lang.Boolean updateCacheFromRequest) When a successful Add, Update or Remove type operation fires on this ResultTree's dataSource, if data is unset, should we integrate the submitted data values (from the request) into our data-set?
void	unloadChildren(TreeNode node) Deprecated. It's recommended that you instead use Tree.reloadChildren() to reload the children of a folder, or Tree.removeChildren() if you need to clear the cached children of a folder to add specific local data.
java.lang.Boolean	willFetchData(Criteria newCriteria) Will changing the criteria for this resultTree require fetching new data from the server or can the new criteria be satisfied from data already cached on the client?

Methods inherited from class com.smartgwt.client.widgets.tree.Tree

add, add, add, add, addDataChangedHandler, addList, addList, addList, addList, allChildrenLoaded, closeAll, closeAll, closeFolder, closeFolders, find, find, find, findById, getAllNodes, getAllNodes, getAutoOpenRoot, getChildren, getChildrenProperty, getChildrenResultSet, getDefaultNodeTitle, getDescendantFolders, getDescendantFolders, getDescendantLeaves, getDescendantLeaves, getDescendants, getDescendants, getFilteredTree, getFilteredTree, getFolders, getIdField, getIsFolderProperty, getLeaves, getLength, getLevel, getLoadState, getModelType, getName, getNameProperty, getOpenList, getOpenProperty, getParent, getParentIdField, getParentPath, getParents, getPath, getPathDelim, getReportCollisions, getRoot, getRootValue, getSeparateFolders, getShowRoot, getSortFoldersBeforeLeaves, getTitle, getTitleProperty, hasChildren, hasFolders, hasLeaves, isDescendantOf, isFolder, isLeaf, isLoaded, isOpen, isRoot, linkNodes, loadChildren, loadChildren, move, move, nodeForRecord, openAll, openAll, openFolder, openFolders, reloadChildren, remove, removeChildren, removeList, setAutoOpenRoot, setChildrenProperty, setDefaultNodeTitle, setIdField, setIsFolderProperty, setJavaScriptObject, setModelType, setNameProperty, setOpenProperty, setParentIdField, setPathDelim, setProperty, setProperty, setProperty, setProperty, setReportCollisions, setRoot, setRootValue, setRootValue, setSeparateFolders, setShowRoot, setSortFoldersBeforeLeaves, setTitleProperty

Methods inherited from class com.smartgwt.client.data.RecordList

add, addAt, addDataChangedHandler, addList, addList, addListAt, contains, contains, containsAll, duplicate, equals, find, find, find, findAll, findAll, findAll, findAll, findAll, findAll, findAll, findAll, findIndex, findIndex, findIndex, findIndex, findIndex, findIndex, findIndex, findIndex, findNextIndex, findNextIndex, findNextIndex, findNextIndex, findNextIndex, findNextIndex, findNextIndex, findNextIndex, findNextIndex, findNextIndex, first, getItems, getJsObj, getOrCreateJsObj, getProperty, getRangeList, getValueMap, indexOf, indexOf, intersect, isARecordList, isCreated, isEmpty, last, lastIndexOf, lastIndexOf, remove, removeAt, removeList, set, setLength, setSort, sort, sort, sortByProperty, sortByProperty, toArray

Methods inherited from class com.smartgwt.client.core.BaseClass

applyFactoryProperties, asSGWTComponent, createJsObj, destroy, doAddHandler, doInit, error, error, errorIfNotCreated, fireEvent, getAttribute, getAttributeAsBoolean, getAttributeAsDate, getAttributeAsDouble, getAttributeAsElement, getAttributeAsFloat, getAttributeAsInt, getAttributeAsJavaScriptObject, getAttributeAsMap, getAttributeAsString, getAttributeAsStringArray, getClassName, getConfig, getHandlerCount, getID, getRef, getScClassName, getTestInstance, hasAutoAssignedID, internalSetID, internalSetID, isFactoryCreated, onBind, onInit, registerID, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setConfig, setFactoryCreated, setID, setScClassName

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface com.google.gwt.event.shared.HasHandlers

fireEvent

Constructor Detail

ResultTree

public ResultTree()

ResultTree

public ResultTree(com.google.gwt.core.client.JavaScriptObject jsObj)

Method Detail

getOrCreateRef

public static ResultTree getOrCreateRef(com.google.gwt.core.client.JavaScriptObject jsObj)

create

public com.google.gwt.core.client.JavaScriptObject create()

Overrides:

create in class Tree

setAutoPreserveOpenState

public void setAutoPreserveOpenState(PreserveOpenState autoPreserveOpenState)

Controls what happens to the "open state" - the set of nodes opened or closed by the end user after tree data is loaded - when an entirely new tree of nodes is loaded from the server, as a consequence of calling ResultTree.invalidateCache() or of changing criteria such that the current cache of nodes is dropped.

Parameters:

autoPreserveOpenState - Default value is "whenUnique"

getAutoPreserveOpenState

public PreserveOpenState getAutoPreserveOpenState()

Controls what happens to the "open state" - the set of nodes opened or closed by the end user after tree data is loaded - when an entirely new tree of nodes is loaded from the server, as a consequence of calling ResultTree.invalidateCache() or of changing criteria such that the current cache of nodes is dropped.

Returns:

PreserveOpenState

setCanReturnOpenFolders

public void setCanReturnOpenFolders(boolean canReturnOpenFolders)
                             throws java.lang.IllegalStateException

When using fetchMode:"paged" and providing multiple levels of the tree in one DSResponse, this property specifies the default value assumed for the canReturnOpenSubfoldersProperty when no value for that property is provided for a node.

Parameters:

canReturnOpenFolders - Default value is false

Throws:

java.lang.IllegalStateException - this property cannot be changed after the underlying component has been created

getCanReturnOpenFolders

public boolean getCanReturnOpenFolders()

When using fetchMode:"paged" and providing multiple levels of the tree in one DSResponse, this property specifies the default value assumed for the canReturnOpenSubfoldersProperty when no value for that property is provided for a node.

Returns:

boolean

setCanReturnOpenSubfoldersProperty

public void setCanReturnOpenSubfoldersProperty(java.lang.String canReturnOpenSubfoldersProperty)
                                        throws java.lang.IllegalStateException

When using fetchMode:"paged" and providing multiple levels of the tree in one DSResponse, canReturnOpenSubfoldersProperty may be set on any folder to indicate whether child folders might be returned by the server already open. If the property is set to false on a folder then subfolders of that folder are never allowed to be returned already open. This enables the paging mechanism to be more efficient in the amount of data that it requests from the server.

For example, setting the canReturnOpenSubfoldersProperty value to false on a node is appropriate if the server-side code determines that the the node's children consist of entirely leaf nodes.

Parameters:

canReturnOpenSubfoldersProperty - Default value is "canReturnOpenSubfolders"

Throws:

java.lang.IllegalStateException - this property cannot be changed after the underlying component has been created

See Also:

setCanReturnOpenFolders(boolean)

getCanReturnOpenSubfoldersProperty

public java.lang.String getCanReturnOpenSubfoldersProperty()

When using fetchMode:"paged" and providing multiple levels of the tree in one DSResponse, canReturnOpenSubfoldersProperty may be set on any folder to indicate whether child folders might be returned by the server already open. If the property is set to false on a folder then subfolders of that folder are never allowed to be returned already open. This enables the paging mechanism to be more efficient in the amount of data that it requests from the server.

For example, setting the canReturnOpenSubfoldersProperty value to false on a node is appropriate if the server-side code determines that the the node's children consist of entirely leaf nodes.

Returns:

String

See Also:

getCanReturnOpenFolders()

setChildCountProperty

public void setChildCountProperty(java.lang.String childCountProperty)
                           throws java.lang.IllegalStateException

When using fetchMode:"paged" and providing multiple levels of the tree in one DSResponse, childCountProperty must be set for any folders that include only a partial list of children. For a deeper discussion see the Paging large sets of children section of the TreeDataBinding overview.

Parameters:

childCountProperty - Default value is "childCount"

Throws:

java.lang.IllegalStateException - this property cannot be changed after the underlying component has been created

See Also:

Multi-Level Child Paging Example

getChildCountProperty

public java.lang.String getChildCountProperty()

When using fetchMode:"paged" and providing multiple levels of the tree in one DSResponse, childCountProperty must be set for any folders that include only a partial list of children. For a deeper discussion see the Paging large sets of children section of the TreeDataBinding overview.

Returns:

String

See Also:

Multi-Level Child Paging Example

setData

public void setData(TreeNode... data)
             throws java.lang.IllegalStateException

Optional initial data for the tree. If the fetchMode is "basic" or "local" then the format of this data is exactly the same parentId-linked list of tree nodes as documented on data (when the modelType is set to "parent"). If the fetchMode is "paged" then the format is extended to allow the childCountProperty to be set on folder nodes.

Providing an initial set of nodes in this way does not affect the behavior of the ResultTree in its loading of unloaded folders. An equivalent result is achieved if the first fetch from the server returns this same data.

If fetchMode is "paged" then you may make folder-by-folder choices as to whether to use paging for the childen of each folder. If you would like to use paging in a folder then you may include a partial list of that folder's children with the data, provided that you set the childCountProperty to the total number of children. Otherwise you will need to include either all children of the folder or none of the children. Open folders without any children provided will cause immediate, new fetches for the children, as usual.

Because the initial data is treated exactly as though it were returned from the tree's first server fetch, the order of the initial data must match the initial sort order of the TreeGrid displaying the data or, if no such sort is specified, the native storage order on the server. For example, consider initial data containing n records having the parentId "X", meaning they are all in the same folder. These n records are the records at indices 0 through (n - 1) that are stored on the server under the parent node. If the childCountProperty set on the parent node indicates that there are m > n total rows under the parent node then the records at indices n to (m - 1) will be fetched from the server as the user scrolls the additional rows into view.

Note : This is an advanced setting

Overrides:

setData in class Tree

Parameters:

data - Default value is null

Throws:

java.lang.IllegalStateException - this property cannot be changed after the underlying component has been created

See Also:

Tree.setData(com.smartgwt.client.widgets.tree.TreeNode[]), TreeNode, TreeDataBinding overview and related methods

getData

public TreeNode[] getData()

Optional initial data for the tree. If the fetchMode is "basic" or "local" then the format of this data is exactly the same parentId-linked list of tree nodes as documented on data (when the modelType is set to "parent"). If the fetchMode is "paged" then the format is extended to allow the childCountProperty to be set on folder nodes.

Providing an initial set of nodes in this way does not affect the behavior of the ResultTree in its loading of unloaded folders. An equivalent result is achieved if the first fetch from the server returns this same data.

If fetchMode is "paged" then you may make folder-by-folder choices as to whether to use paging for the childen of each folder. If you would like to use paging in a folder then you may include a partial list of that folder's children with the data, provided that you set the childCountProperty to the total number of children. Otherwise you will need to include either all children of the folder or none of the children. Open folders without any children provided will cause immediate, new fetches for the children, as usual.

Because the initial data is treated exactly as though it were returned from the tree's first server fetch, the order of the initial data must match the initial sort order of the TreeGrid displaying the data or, if no such sort is specified, the native storage order on the server. For example, consider initial data containing n records having the parentId "X", meaning they are all in the same folder. These n records are the records at indices 0 through (n - 1) that are stored on the server under the parent node. If the childCountProperty set on the parent node indicates that there are m > n total rows under the parent node then the records at indices n to (m - 1) will be fetched from the server as the user scrolls the additional rows into view.

Overrides:

getData in class Tree

Returns:

TreeNode...

See Also:

Tree.getData(), TreeNode, TreeDataBinding overview and related methods

setDefaultIsFolder

public void setDefaultIsFolder(java.lang.Boolean defaultIsFolder)
                        throws java.lang.IllegalStateException

Controls whether nodes are assumed to be folders or leaves by default.

Nodes that have children or have the isFolderProperty set to true will always be considered folders. Other nodes will be considered folders or leaves by default according to this setting.

If defaultIsFolder is unset, the ResultTree will automatically set it to match the value of loadDataOnDemand. This means that, when using folder-by-folder load on demand (loadDataOnDemand:true), by default a newly loaded node will be considered to be a folder that has not loaded its children yet.

When not using folder-by-folder load on demand, by default a newly loaded node is considered a leaf. If you set defaultIsFolder:true explicitly, by default a newly loaded node is considered to be a folder with no children.

See Tree.isFolder() for details on how to explicitly mark nodes as folders or leaves.

Overrides:

setDefaultIsFolder in class Tree

Parameters:

defaultIsFolder - Default value is null

Throws:

java.lang.IllegalStateException - this property cannot be changed after the underlying component has been created

See Also:

TreeGrid.setLoadDataOnDemand(java.lang.Boolean)

getDefaultIsFolder

public java.lang.Boolean getDefaultIsFolder()

Controls whether nodes are assumed to be folders or leaves by default.

Nodes that have children or have the isFolderProperty set to true will always be considered folders. Other nodes will be considered folders or leaves by default according to this setting.

If defaultIsFolder is unset, the ResultTree will automatically set it to match the value of loadDataOnDemand. This means that, when using folder-by-folder load on demand (loadDataOnDemand:true), by default a newly loaded node will be considered to be a folder that has not loaded its children yet.

When not using folder-by-folder load on demand, by default a newly loaded node is considered a leaf. If you set defaultIsFolder:true explicitly, by default a newly loaded node is considered to be a folder with no children.

See Tree.isFolder() for details on how to explicitly mark nodes as folders or leaves.

Overrides:

getDefaultIsFolder in class Tree

Returns:

Boolean

See Also:

TreeGrid.getLoadDataOnDemand()

setDefaultNewNodesToRoot

public void setDefaultNewNodesToRoot(java.lang.Boolean defaultNewNodesToRoot)

This attribute governs how to handle cache-synch when a new node is added to this dataSource with no explicit parentId.

If set to true, when a new node is added to this dataSource via DataSource.addData(), with no explicit parentId, the node will be added as a child of the root node of this result tree. Otherwise it will be ignored.

Similar logic applies to updated nodes - if this property is true and the parentId of an updated node is cleared, it will be moved to become a child of root, otherwise it will be dropped from the tree.

Note : This is an advanced setting

Parameters:

defaultNewNodesToRoot - Default value is false

getDefaultNewNodesToRoot

public java.lang.Boolean getDefaultNewNodesToRoot()

This attribute governs how to handle cache-synch when a new node is added to this dataSource with no explicit parentId.

If set to true, when a new node is added to this dataSource via DataSource.addData(), with no explicit parentId, the node will be added as a child of the root node of this result tree. Otherwise it will be ignored.

Similar logic applies to updated nodes - if this property is true and the parentId of an updated node is cleared, it will be moved to become a child of root, otherwise it will be dropped from the tree.

Returns:

Boolean

setDisableCacheSync

public void setDisableCacheSync(java.lang.Boolean disableCacheSync)
                         throws java.lang.IllegalStateException

By default when the data of this ResultTree's dataSource is modified, the ResultTree will be updated to display these changes. Set this flag to true to disable this behavior.

Note : This is an advanced setting

Parameters:

disableCacheSync - Default value is false

Throws:

java.lang.IllegalStateException - this property cannot be changed after the underlying component has been created

getDisableCacheSync

public java.lang.Boolean getDisableCacheSync()

By default when the data of this ResultTree's dataSource is modified, the ResultTree will be updated to display these changes. Set this flag to true to disable this behavior.

Returns:

Boolean

setDiscardParentlessNodes

public void setDiscardParentlessNodes(java.lang.Boolean discardParentlessNodes)
                               throws java.lang.IllegalStateException

When data is loaded from the server, should nodes with an explicit value for the parentIdField which doesn't map to a valid parent node be dropped? If set to false, for loadDataOnDemand:false trees, parentless nodes will be added as children of the root node - for loadDataOnDemand:true, they will be added as children of the folder currently requesting children.

This effectively allows nodes to be loaded into the current (or root) folder without needing an explicit parentIdField value that matches the folder's ID or rootValue for the resultTree.

Note: For loadDataOnDemand:false trees, if this property is unset at init time, it will default to true if an explicit rootNode has been specified. This ensures that if the data tree retrieved from the server includes ancestors of the desired root-node we don't display them. Otherwise this property always defaults to false.

Note : This is an advanced setting

Overrides:

setDiscardParentlessNodes in class Tree

Parameters:

discardParentlessNodes - Default value is null

Throws:

java.lang.IllegalStateException - this property cannot be changed after the underlying component has been created

getDiscardParentlessNodes

public java.lang.Boolean getDiscardParentlessNodes()

When data is loaded from the server, should nodes with an explicit value for the parentIdField which doesn't map to a valid parent node be dropped? If set to false, for loadDataOnDemand:false trees, parentless nodes will be added as children of the root node - for loadDataOnDemand:true, they will be added as children of the folder currently requesting children.

This effectively allows nodes to be loaded into the current (or root) folder without needing an explicit parentIdField value that matches the folder's ID or rootValue for the resultTree.

Note: For loadDataOnDemand:false trees, if this property is unset at init time, it will default to true if an explicit rootNode has been specified. This ensures that if the data tree retrieved from the server includes ancestors of the desired root-node we don't display them. Otherwise this property always defaults to false.

Overrides:

getDiscardParentlessNodes in class Tree

Returns:

Boolean

setFetchMode

public void setFetchMode(FetchMode fetchMode)
                  throws java.lang.IllegalStateException

Mode of fetching records from server.

fetchMode:"local" implies that local filtering will always be performed. See keepParentsOnFilter for additional filtering details.

fetchMode:"basic" or "paged" implies that if search criteria change, the entire tree will be discarded and re-fetched from the server. When retrieving the replacement tree data, the default behavior will be to preserve the openState for any nodes that the server returns which were previously opened by the user. Note that this implies that if loadDataOnDemand is enabled and the server returns only root-level nodes, open state will be preserved only for root-level nodes, and children of open root-level nodes will be immediately fetched from the server if they are not included in the server's initial response.

fetchMode:"paged" enables paging for nodes that have very large numbers of children. Whenever the children of a folder are loaded, the resultTree will set startRow and endRow when requesting children from the DataSource, and will manage loading of further children on demand, similar to how a ResultSet manages paging for lists. For a deeper discussion see the Paging large sets of children section of the TreeDataBinding overview.

Parameters:

fetchMode - Default value is "basic"

Throws:

java.lang.IllegalStateException - this property cannot be changed after the underlying component has been created

See Also:

TreeDataBinding overview and related methods, Paging for Children Example

getFetchMode

public FetchMode getFetchMode()

Mode of fetching records from server.

fetchMode:"local" implies that local filtering will always be performed. See keepParentsOnFilter for additional filtering details.

fetchMode:"basic" or "paged" implies that if search criteria change, the entire tree will be discarded and re-fetched from the server. When retrieving the replacement tree data, the default behavior will be to preserve the openState for any nodes that the server returns which were previously opened by the user. Note that this implies that if loadDataOnDemand is enabled and the server returns only root-level nodes, open state will be preserved only for root-level nodes, and children of open root-level nodes will be immediately fetched from the server if they are not included in the server's initial response.

fetchMode:"paged" enables paging for nodes that have very large numbers of children. Whenever the children of a folder are loaded, the resultTree will set startRow and endRow when requesting children from the DataSource, and will manage loading of further children on demand, similar to how a ResultSet manages paging for lists. For a deeper discussion see the Paging large sets of children section of the TreeDataBinding overview.

Returns:

FetchMode

See Also:

TreeDataBinding overview and related methods, Paging for Children Example

setKeepParentsOnFilter

public void setKeepParentsOnFilter(java.lang.Boolean keepParentsOnFilter)
                            throws java.lang.IllegalStateException

If set, tree-based filtering is performed such that parent nodes are kept as long as they have children that match the filter criteria, even if the parents themselves do not match the filter criteria. If not set, filtering will exclude parent nodes not matching the criteria and all nodes below it in the tree.

When keepParentsOnFilter is enabled for paged ResultTrees, server-side filtering is required.

When enabled for non-paged trees, fetchMode:"local" is automatically enabled so that all filtering behavior shifts to the client-side and full criteria are no longer sent to the server. Instead, server fetches will always load all nodes, or with loadDataOnDemand:true, will always load all nodes under a given parent. This means that the server does not need to implement special tree filtering logic.

Optionally, serverFilterFields can be set to a list of field names that will be sent to the server whenever they are present in the criteria.

Parameters:

keepParentsOnFilter - Default value is null

Throws:

java.lang.IllegalStateException - this property cannot be changed after the underlying component has been created

See Also:

TreeDataBinding overview and related methods

getKeepParentsOnFilter

public java.lang.Boolean getKeepParentsOnFilter()

If set, tree-based filtering is performed such that parent nodes are kept as long as they have children that match the filter criteria, even if the parents themselves do not match the filter criteria. If not set, filtering will exclude parent nodes not matching the criteria and all nodes below it in the tree.

When keepParentsOnFilter is enabled for paged ResultTrees, server-side filtering is required.

When enabled for non-paged trees, fetchMode:"local" is automatically enabled so that all filtering behavior shifts to the client-side and full criteria are no longer sent to the server. Instead, server fetches will always load all nodes, or with loadDataOnDemand:true, will always load all nodes under a given parent. This means that the server does not need to implement special tree filtering logic.

Optionally, serverFilterFields can be set to a list of field names that will be sent to the server whenever they are present in the criteria.

Returns:

Boolean

See Also:

TreeDataBinding overview and related methods

setLoadDataOnDemand

public void setLoadDataOnDemand(java.lang.Boolean loadDataOnDemand)
                         throws java.lang.IllegalStateException

Does this resultTree load data incrementally as folders within the tree are opened, or is it all loaded in a single request?

Parameters:

loadDataOnDemand - Default value is true

Throws:

java.lang.IllegalStateException - this property cannot be changed after the underlying component has been created

See Also:

TreeGrid.setLoadDataOnDemand(java.lang.Boolean)

getLoadDataOnDemand

public java.lang.Boolean getLoadDataOnDemand()

Does this resultTree load data incrementally as folders within the tree are opened, or is it all loaded in a single request?

Returns:

Boolean

See Also:

TreeGrid.getLoadDataOnDemand()

setProgressiveLoading

public void setProgressiveLoading(java.lang.Boolean progressiveLoading)

Sets progressive loading mode for this ResultTree. The ResultTree will copy this setting onto the DSRequests that it issues, overriding the OperationBinding- and DataSource-level settings, in cases where the use of progressive loading does not affect the correctness of the tree's paging algorithm.

This setting is applied automatically by DataBoundComponents that have their own explicit setting for progressiveLoading.

Note: This property only has an effect for fetchMode:"paged" ResultTrees.

Parameters:

progressiveLoading - Default value is null

See Also:

DataSource.setProgressiveLoading(java.lang.Boolean), OperationBinding.progressiveLoading, DSRequest.setProgressiveLoading(java.lang.Boolean), ProgressiveLoading overview and related methods

getProgressiveLoading

public java.lang.Boolean getProgressiveLoading()

Sets progressive loading mode for this ResultTree. The ResultTree will copy this setting onto the DSRequests that it issues, overriding the OperationBinding- and DataSource-level settings, in cases where the use of progressive loading does not affect the correctness of the tree's paging algorithm.

This setting is applied automatically by DataBoundComponents that have their own explicit setting for progressiveLoading.

Note: This property only has an effect for fetchMode:"paged" ResultTrees.

Returns:

Boolean

See Also:

DataSource.getProgressiveLoading(), OperationBinding.progressiveLoading, DSRequest.getProgressiveLoading(), ProgressiveLoading overview and related methods

setResultSize

public void setResultSize(java.lang.Integer resultSize)
                   throws java.lang.IllegalStateException

How many tree nodes to retrieve at once from each large set of children in the tree.

Applicable only with fetchMode: "paged". When a paged ResultTree is asked for rows that have not yet been loaded, it will fetch adjacent rows that are likely to be required soon, in batches of this size.

Note : This is an advanced setting

Parameters:

resultSize - Default value is 75

Throws:

java.lang.IllegalStateException - this property cannot be changed after the underlying component has been created

See Also:

TreeDataBinding overview and related methods

getResultSize

public java.lang.Integer getResultSize()

How many tree nodes to retrieve at once from each large set of children in the tree.

Applicable only with fetchMode: "paged". When a paged ResultTree is asked for rows that have not yet been loaded, it will fetch adjacent rows that are likely to be required soon, in batches of this size.

Returns:

Integer

See Also:

TreeDataBinding overview and related methods

setServerFilterFields

public void setServerFilterFields(java.lang.String... serverFilterFields)
                           throws java.lang.IllegalStateException

When keepParentsOnFilter is enabled for fetchMode:"local" ResultTrees, this property lists field names that will be sent to the server if they are present in the criteria.

Parameters:

serverFilterFields - Default value is null

Throws:

java.lang.IllegalStateException - this property cannot be changed after the underlying component has been created

getServerFilterFields

public java.lang.String[] getServerFilterFields()

When keepParentsOnFilter is enabled for fetchMode:"local" ResultTrees, this property lists field names that will be sent to the server if they are present in the criteria.

Returns:

String...

setUpdateCacheFromRequest

public void setUpdateCacheFromRequest(java.lang.Boolean updateCacheFromRequest)
                               throws java.lang.IllegalStateException

When a successful Add, Update or Remove type operation fires on this ResultTree's dataSource, if data is unset, should we integrate the submitted data values (from the request) into our data-set?

Note : This is an advanced setting

Parameters:

updateCacheFromRequest - Default value is true

Throws:

java.lang.IllegalStateException - this property cannot be changed after the underlying component has been created

getUpdateCacheFromRequest

public java.lang.Boolean getUpdateCacheFromRequest()

When a successful Add, Update or Remove type operation fires on this ResultTree's dataSource, if data is unset, should we integrate the submitted data values (from the request) into our data-set?

Returns:

Boolean

applyFilter

public Tree applyFilter(Tree tree,
               Criteria criteria,
               TreeFilterMode filterMode,
               DataSource dataSource)

The ResultTree will call applyFilter() when it needs to locally filter the tree using the current filter criteria.

Default behavior is to call Tree.getFilteredTree() to obtain a new, filtered tree.

Override this method or Tree.getFilteredTree() to implement your own client-side filtering behavior. Note that the original tree should not be affected.

Parameters:

tree - the source tree to be filtered

criteria - the filter criteria

filterMode - mode to use for filtering

dataSource - dataSource for filtering if the Tree does not already have one

Returns:

the filtered tree (copy)

applyFilter

public Tree applyFilter(Tree tree,
               Criteria criteria,
               TreeFilterMode filterMode,
               DataSource dataSource,
               DSRequest requestProperties)

The ResultTree will call applyFilter() when it needs to locally filter the tree using the current filter criteria.

Default behavior is to call Tree.getFilteredTree() to obtain a new, filtered tree.

Override this method or Tree.getFilteredTree() to implement your own client-side filtering behavior. Note that the original tree should not be affected.

Parameters:

tree - the source tree to be filtered

criteria - the filter criteria

filterMode - mode to use for filtering

dataSource - dataSource for filtering if the Tree does not already have one

requestProperties - Request properties block. This allows developers to specify properties that would impact the filter such as textMatchStyle

Returns:

the filtered tree (copy)

compareCriteria

public int compareCriteria(Criteria newCriteria,
                  Criteria oldCriteria)

Default behavior is to call DataSource.compareCriteria() to determine whether new criteria is equivalent to the old criteria (returns 0) or not.

See DataSource.compareCriteria() for a full explanation of the default behavior. The CriteriaPolicy used is "dropOnChange".

Override this method or DataSource.compareCriteria() to implement your own client-side filtering behavior.

Parameters:

newCriteria - new filter criteria

oldCriteria - old filter criteria

Returns:

0 if the criteria are equivalent, -1 if the criteria are different

See Also:

CriteriaPolicy

compareCriteria

public int compareCriteria(Criteria newCriteria,
                  Criteria oldCriteria,
                  DSRequest requestProperties)

Default behavior is to call DataSource.compareCriteria() to determine whether new criteria is equivalent to the old criteria (returns 0) or not.

See DataSource.compareCriteria() for a full explanation of the default behavior. The CriteriaPolicy used is "dropOnChange".

Override this method or DataSource.compareCriteria() to implement your own client-side filtering behavior.

Parameters:

newCriteria - new filter criteria

oldCriteria - old filter criteria

requestProperties - dataSource request properties

Returns:

0 if the criteria are equivalent, -1 if the criteria are different

See Also:

CriteriaPolicy

dataArrived

public void dataArrived(TreeNode parentNode)

This callback fires whenever the resultTree receives new nodes from the server, after the new nodes have been integrated into the tree.

Parameters:

parentNode - The parentNode for which children were just loaded

get

public TreeNode get(int pos)

Get the item in the openList at a particular position.

Overrides:

get in class RecordList

Parameters:

pos - position of the node to get

Returns:

node at that position

getOpenState

public java.lang.String getOpenState()

Returns a snapshot of the current open state of this tree's data as a TreeGridOpenState object.

This object can be passed to ResultTree.setOpenState() or TreeGrid.setOpenState() to open the same set of folders within the tree's data (assuming the nodes are still present in the data).

Returns:

current open state for the grid.

See Also:

setOpenState(java.lang.String)

getRange

public TreeNode[] getRange(int start,
                  int end)

Get a range of items from the open list

Overrides:

getRange in class RecordList

Parameters:

start - start position

end - end position (NOT inclusive)

Returns:

list of nodes in the open list

invalidateCache

public void invalidateCache()

Manually invalidate this ResultTree's cache.

Generally a ResultTree will observe and incorporate updates to the DataSource that provides its records, but when this is not possible, invalidateCache() allows manual cache invalidation.

Components bound to this ResultTree will typically re-request the currently visible portion of the dataset, causing the ResultTree to re-fetch data from the server.

setOpenState

public void setOpenState(java.lang.String openState)

Reset the set of open folders within this tree's data to match the TreeGridOpenState object passed in.

Used to restore previous state retrieved from the tree by a call to ResultTree.getOpenState().

Parameters:

openState - Object describing the desired set of open folders.. See TreeGridOpenState

See Also:

getOpenState()

unloadChildren

public void unloadChildren(TreeNode node)

Deprecated. It's recommended that you instead use Tree.reloadChildren() to reload the children of a folder, or Tree.removeChildren() if you need to clear the cached children of a folder to add specific local data.

Unload the children of a folder, returning the folder to the "unloaded" state.

Overrides:

unloadChildren in class Tree

Parameters:

node - folder in question

willFetchData

public java.lang.Boolean willFetchData(Criteria newCriteria)

Will changing the criteria for this resultTree require fetching new data from the server or can the new criteria be satisfied from data already cached on the client?

This method can be used to determine whether TreeGrid.fetchData() or TreeGrid.filterData() will cause a server side fetch when passed a certain set of criteria.

Parameters:

newCriteria - new criteria to test.

Returns:

true if server fetch would be required to satisfy new criteria.

setDataSource

public void setDataSource(DataSource dataSource)
                   throws java.lang.IllegalStateException

What DataSource is this resultTree associated with?

Parameters:

dataSource - dataSource Default value is null

Throws:

java.lang.IllegalStateException - this property cannot be changed after the underlying component has been created

See Also:

Databinding overview and related methods, DataSource fields Example

getDataSource

public DataSource getDataSource()

What DataSource is this resultTree associated with?

Returns:

DataSource

See Also:

Databinding overview and related methods, DataSource fields Example

setRootNode

public void setRootNode(com.google.gwt.core.client.JavaScriptObject rootNode)
                 throws java.lang.IllegalStateException

This attribute may be used to specify a root value for the parentIdField of this resultTree. This overrides the default rootValue for this tree, allowing a component to navigate a tree starting at a specific node.

May be overridden via treeRootValue for ResultTrees generated by a TreeGrid component.

Parameters:

rootNode - rootNode Default value is null

Throws:

java.lang.IllegalStateException - this property cannot be changed after the underlying component has been created

getRootNode

public com.google.gwt.core.client.JavaScriptObject getRootNode()

This attribute may be used to specify a root value for the parentIdField of this resultTree. This overrides the default rootValue for this tree, allowing a component to navigate a tree starting at a specific node.

May be overridden via treeRootValue for ResultTrees generated by a TreeGrid component.

Returns:

Object

setCriteria

public void setCriteria(Criteria newCriteria)

Set the filter criteria to use when fetching rows.

Depending on the result of ResultTree.compareCriteria() and setting for fetchMode, setting criteria may cause a trip to the server to get a new set of nodes, or may simply cause already-fetched nodes to be re-filtered according to the new criteria.

For a basic overview on when server fetches are generally performed, see fetchMode. However, this is not the final determination of when server fetches occur. Criteria can be split into local criteria and server criteria by specifying serverFilterFields. Thus, even when using fetchMode:"local" a new server fetch will occur if the server criteria changes. For details on how the criteria is split, see DataSource.splitCriteria().

Note: if criteria is being split to retrieve server criteria portion and the criteria is an AdvancedCriteria, the criteria must consist of a single "and" operator and one or more simple criteria below it. No other logical operators may be used. In other words, the AdvancedCriteria provided must be exactly representable by a simple criteria.

Parameters:

newCriteria - the filter criteria