Interface: TreeDataProvider

Oracle® JavaScript Extension Toolkit (JET)
7.1.0

F18183-01

Signature:

interface TreeDataProvider<K, D> extends DataProvider<K, D>

QuickNav


PREVIEW: This is a preview API. Preview APIs are production quality, but can be changed on a major version without a deprecation path.

TreeDataProvider

Version:
  • 7.1.0
Since:
  • 5.1.0
Module:
  • ojtreedataprovider

Module usage

See JET Module Loading for an overview of module usage within JET.

Typescript Import Format
//To use this interface, import as below.
import {TreeDataProvider} from "ojs/ojtreedataprovider";
Generic Parameters
ParameterDescription
KType of Key
DType of Data

JET In Typescript

A detailed description of working with JET elements and classes in your typescript project can be found at: JET Typescript Usage.

Description

TreeDataProvider is the basic interface for getting runtime data which JET components that display hierarchical list of items (such as oj-tree-view) can use.

This interface extends DataProvider, with the addition of a getChildDataProvider method.

Unless otherwise noted, all methods operate on the set of sibling items with the same parent. For example, fetchFirst returns an iterable for the sibling items with the same parent; getTotalSize returns a promise that resolves to the number of items with the same parent.

To retrieve the children of an item, consumers use the getChildDataProvider method to get another TreeDataProvider for the children of that item.

JET provides some implementations of this interface, such as oj.ArrayTreeDataProvider.

Applications can also create their own implementations of this interface and use them with JET components that support it. For example, an application can create a TreeDataProvider implementation that fetches data from a REST endpoint.

Implementation class must implement all of the interface methods. It should also fire the events described below when appropriate, so that JET components or other consumers can respond to data change accordingly.

Events

Implementation can fire the following events by creating an instance of the event class and passing the event payload in the constructor. All events should be fired at the root-level TreeDataProvider instance, so that consumers only need to add one listener for the entire tree. Events should not be fired at child-level TreeDataProvider returned by getChildDataProvider, as there is no bubbling support for DataProvider events.

oj.DataProviderMutationEvent

This event is fired when items have been added or removed from the data.

Event payload should implement the oj.DataProviderMutationEventDetail interface.

Consumers can add an event listener for the "mutate" event type on the DataProvider object.

oj.DataProviderRefreshEvent

This event is fired when the data has been refreshed and components need to re-fetch the data.

This event contains no additional event payload.

Consumers can add an event listener for the "refresh" event type on the DataProvider object.

Example of implementation firing an oj.DataProviderMutationEvent for removed items:
var removeDetail = {data: removedDataArray,
                    indexes: removedIndexArray,
                    keys: removedKeySet,
                    metadata: removedMetadataArray};
this.dispatchEvent(new oj.DataProviderMutationEvent({remove: removeDetail}));
Example of consumer listening for the "mutate" event type:
var listener = function(event) {
  if (event.detail.remove) {
    var removeDetail = event.detail.remove;
    // Handle removed items
  }
};
dataProvider.addEventListener("mutate", listener);

Methods

containsKeys(parameters : FetchByKeysParameters<K>) : Promise<ContainsKeysResults<K>>

PREVIEW: This is a preview API. Preview APIs are production quality, but can be changed on a major version without a deprecation path.

Check if there are rows containing the specified keys

A generic implementation of this method is available from oj.FetchByKeysMixin. It is for convenience and may not provide the most efficient implementation for your data provider. Classes that implement the DataProvider interface are encouraged to provide a more efficient implementation.

Parameters:
Name Type Description
parameters oj.FetchByKeysParameters contains by key parameters
Since:
  • 4.2.0
Inherited From:
Returns:
Returns Promise which resolves to oj.ContainsKeysResults.
Type
Promise.<oj.ContainsKeysResults>

createOptimizedKeyMap(initialMap?: Map<K, D>): Map<K, D>

PREVIEW: This is a preview API. Preview APIs are production quality, but can be changed on a major version without a deprecation path.

Return an empty Map which is optimized to store key value pairs

Optionally provided by certain DataProvider implementations for storing key/value pairs from the DataProvider in a performant fashion. Sometimes components will need to temporarily store a Map of keys provided by the DataProvider, for example, in the case of maintaining a Map of selected keys. Only the DataProvider is aware of the internal structure of keys such as whether they are primitives, Strings, or objects and how to do identity comparisons. Therefore, the DataProvider can optionally provide a Map implementation which can performantly store key/value pairs surfaced by the DataProvider.

Parameters:
Name Type Argument Description
Optionally Map.<any> <optional>
specify an initial map of key/values for the Map. If not specified, then return an empty Map.
Since:
  • 6.2.0
Inherited From:
Returns:
Returns a Map optimized for handling keys from the DataProvider.
Type
Map.<any>

createOptimizedKeySet(initialSet?: Set<K>): Set<K>

PREVIEW: This is a preview API. Preview APIs are production quality, but can be changed on a major version without a deprecation path.

Return an empty Set which is optimized to store keys

Optionally provided by certain DataProvider implementations for storing keys from the DataProvider in a performant fashion. Sometimes components will need to temporarily store a Set of keys provided by the DataProvider, for example, in the case of maintaining a Set of selected keys. Only the DataProvider is aware of the internal structure of keys such as whether they are primitives, Strings, or objects and how to do identity comparisons. Therefore, the DataProvider can optionally provide a Set implementation which can performantly store keys surfaced by the DataProvider.

Parameters:
Name Type Argument Description
Optionally Set.<any> <optional>
specify an initial set of keys for the Set. If not specified, then return an empty Set.
Since:
  • 6.2.0
Inherited From:
Returns:
Returns a Set optimized for handling keys from the DataProvider.
Type
Set.<any>

fetchByKeys(parameters : FetchByKeysParameters<K>) : Promise<FetchByKeysResults<K, D>>

PREVIEW: This is a preview API. Preview APIs are production quality, but can be changed on a major version without a deprecation path.

Fetch rows by keys

A generic implementation of this method is available from oj.FetchByKeysMixin. It is for convenience and may not provide the most efficient implementation for your data provider. Classes that implement the DataProvider interface are encouraged to provide a more efficient implementation.

Parameters:
Name Type Description
parameters oj.FetchByKeysParameters fetch by key parameters
Since:
  • 4.2.0
Inherited From:
Returns:
Returns Promise which resolves to oj.FetchByKeysResults.
Type
Promise.<oj.FetchByKeysResults>

fetchByOffset(parameters: FetchByOffsetParameters<D>): Promise<FetchByOffsetResults<K, D>>

PREVIEW: This is a preview API. Preview APIs are production quality, but can be changed on a major version without a deprecation path.

Fetch rows by offset

A generic implementation of this method is available from oj.FetchByOffsetMixin. It is for convenience and may not provide the most efficient implementation for your data provider. Classes that implement the DataProvider interface are encouraged to provide a more efficient implementation.

Parameters:
Name Type Description
parameters oj.FetchByOffsetParameters fetch by offset parameters
Since:
  • 4.2.0
Inherited From:
Returns:
Returns Promise which resolves to oj.FetchByOffsetResults.
Type
Promise.<oj.FetchByOffsetResults>

fetchFirst(parameters?: FetchListParameters<D>): AsyncIterable<FetchListResult<K, D>>

PREVIEW: This is a preview API. Preview APIs are production quality, but can be changed on a major version without a deprecation path.

Get an asyncIterator which can be used to fetch a block of data.
Parameters:
Name Type Argument Description
params oj.FetchListParameters <optional>
fetch parameters
Since:
  • 4.2.0
Inherited From:
See:
Returns:
AsyncIterable with oj.FetchListResult
Type
AsyncIterable.<oj.FetchListResult>

getCapability(capabilityName: string): any

PREVIEW: This is a preview API. Preview APIs are production quality, but can be changed on a major version without a deprecation path.

Determines whether this DataProvider supports a certain feature.
Parameters:
Name Type Description
capabilityName string capability name. Supported capability names are: "fetchByKeys", "fetchByOffset", "sort", and "filter".
Since:
  • 4.2.0
Inherited From:
Returns:
capability information or null if unsupported
Type
Object

getChildDataProvider(parentKey: any): TreeDataProvider<K, D>

PREVIEW: This is a preview API. Preview APIs are production quality, but can be changed on a major version without a deprecation path.

Get the data provider for the children of the row identified by parentKey.
Parameters:
Name Type Description
parentKey any key of the row to get child data provider for.
Since:
  • 5.1.0
Returns:
A TreeDataProvider if the row can (but doesn't have to) have children; or null if the row cannot have children. Use the isEmpty method on the returned TreeDataProvider to determine if it currently has children.
Type
TreeDataProvider | null

getTotalSize() → {Promise.<number>}

PREVIEW: This is a preview API. Preview APIs are production quality, but can be changed on a major version without a deprecation path.

Return the total number of rows in this dataprovider
Inherited From:
Returns:
Returns a Promise which resolves to the total number of rows. -1 is unknown row count.
Type
Promise.<number>

isEmpty(): 'yes' | 'no' | 'unknown'

PREVIEW: This is a preview API. Preview APIs are production quality, but can be changed on a major version without a deprecation path.

Returns a string that indicates if this data provider is empty. Valid values are:
  • "yes": this data provider is empty.
  • "no": this data provider is not empty.
  • "unknown": it is not known if this data provider is empty until a fetch is made.
Since:
  • 4.2.0
Inherited From:
Returns:
string that indicates if this data provider is empty
Type
"yes" | "no" | "unknown"