Interface: DataGridProvider

Oracle® JavaScript Extension Toolkit (JET)
17.0.0
F92240-01

Since:
  • 11.0.0
Module:
  • ojdatagridprovider

QuickNav

Methods

Description

The DataGridProvider interface defines the contract by which the JET datagrid retrieves data. By exposing this contract as an interface, we allow for a range of possible data retrieval strategies, while shielding components from dependencies on any one particular implementation choice.

The DataGridProvider expects consumers to retrieve data by offset in a two-dimensional manner, for specific ranges of row and column data to be retrieved by offset and count.

The DataGridProvider contract has the following characteristics:

  • Asynchronous: Even in cases where data is available synchronously (eg. the data is already in a local array), the DataGridProvider contract provides access to the data via asynchronous APIs. As such, consumers are able to interact with the data in a consistent manner, regardless of how the data is retrieved.
  • Stateless: The DataGridProvider’s data retrieval APIs are inherently stateless. Attempts to retrieve data are atomic and are not impacted by previous interactions with the DataGridProvider. This avoids potential brittleness when multiple consumers are interacting with the same DataGridProvider instance.
  • Index-based: The DataGridProvider contract does not rely on keys, but instead relies on data version information to ensure reliable interactions with the data set. Not mandating keys avoids often costly lookup for the DataGridProvider implementers.
  • Read only (with mutation notifications): The DataGridProvider contract does not include mutation APIs. That is, the DataGridProvider contract defines APIs for reading data, not for writing data. However, DataGridProvider implementations may expose their own type-specific mutation APIs, and the DataGridProvider contract defines an event-based mechanism for notifying consumers of data changes.
  • Not Sortable/Filterable: Sorting and Filtering contracts cause issues with providing consistent mutations. The DataGridProvider contract leaves these operations to the user and suggests refresh/new data when the data is sorted or filtered.

Custom Implementations

There is a DataProvider based out of the box DataGridProvider implementation RowDataGridProvider starting in JET 13.1.0. It is important to understand the limitations detailed there to understand if you should write your own.

See the JET cookbook samples for examples on how to implement your own.

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

A generic implementation of DataGridProvider#addEventListener and DataGridProvider#removeEventListener is available from EventTargetMixin.applyMixin which can be used in custom implementations of DataGridProvider. It is for convenience and may not provide the most efficient implementation for your data provider.

Events

Implementations can fire the following events by creating an instance of the event class and passing the event payload in the constructor.

DataGridProviderAddEvent

This event is fired when items have been added to the data.

Event payloads should implement the DataGridProviderAddOperationEventDetail interface.

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

DataGridProviderRemoveEvent

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

Event payloads should implement the DataGridProviderRemoveOperationEventDetail interface.

Consumers can add an event listener for the "remove" event type on the DataGridProvider object.

DataGridProviderUpdateEvent

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

Event payloads should implement the DataGridProviderUpdateOperationEventDetail interface.

Consumers can add an event listener for the "update" event type on the DataGridProvider object.

DataGridProviderRefreshEvent

This event is fired when items have been removed from the data. Consumers can add an event listener for the "refresh" event type on the DataGridProvider object.


Usage

Signature:

interface DataGridProvider<D>

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

For additional information visit:


Methods

addEventListener(eventType: string, listener: EventListener): void

Add a callback function to listen for a specific event type. Currently supported events are DataGridProviderRefreshEvent, DataGridProviderAddEvent, DataGridProviderRemoveEvent, and DataGridProviderUpdateEvent.
Parameters:
Name Type Description
eventType string The event type to listen for.
listener EventListener The callback function that receives the event notification.

fetchByOffset(parameters: FetchByOffsetGridParameters): Promise<FetchByOffsetGridResults<D>>

Fetch data for specified fetch regions by offset and count.

Parameters passed in will indicate which regions of the data to fetch.

Inspect FetchByOffsetGridParameters and FetchByOffsetGridResults for details on expected values.

The results for the fetch should contain every item which is within the bounds of the fetch at all. This includes header or cell items that have extents that cross the boundary of the fetch.

Results allows for categorical iteration of fetch regions, but not offset/count iteration, via the next property.

If a the DataGridProvider supports mutations it should implement a versioning strategy to indicate the version of returned result set.

Parameters:
Name Type Description
parameters FetchByOffsetGridParameters fetch by offset parameters
Since:
  • 11.0.0
Returns:

Returns Promise which resolves to FetchByOffsetGridResults.

Type
Promise.<FetchByOffsetGridResults>

getCapability(capabilityName: string): any

Determines whether this DataGridProvider defines a certain feature.
Parameters:
Name Type Description
capabilityName string capability name. Defined capability names are: "version".
Since:
  • 11.0.0
Returns:

capability information or null if undefined

Type
any
Example

Check what kind of fetchByKeys is defined.

let capabilityInfo = dataGridProvider.getCapability('version');
if (capabilityInfo.implementation == 'monotonicallyIncreasing') {
  // the DataGridProvider supports monotonicallyIncreasing for version
  ...

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

Returns a string that indicates if this DataGridProvider is empty. Valid values are:
  • "yes": this DataGridProvider is empty.
  • "no": this DataGridProvider is not empty.
  • "unknown": it is not known if this DataGridProvider is empty until a fetch is made.
Since:
  • 11.0.0
Returns:

string that indicates if this DataGridProvider is empty

Type
"yes" | "no" | "unknown"
Example

Check if empty

let isEmpty = dataGridProvider.isEmpty();
console.log('DataGridProvider is empty: ' + isEmpty);

removeEventListener(eventType: string, listener: EventListener): void

Remove a listener previously registered with addEventListener.
Parameters:
Name Type Description
eventType string The event type that the listener was registered for.
listener EventListener The callback function that was registered.