Interface: DataProvider

Oracle® JavaScript Extension Toolkit (JET)
5.2.0
E97691-01

QuickNav

Methods

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

DataProvider extends EventTarget

Version:
  • 5.2.0
Since:
  • 4.2.0
Module:
  • ojdataprovider
DataProvider is the basic interface for getting runtime data which JET components that display list of items (such as oj-table and oj-list-view) can use.

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

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 DataProvider 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.

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);
Since:
  • 4.2.0

Methods

containsKeys(parameters) → {Promise.<oj.ContainsKeysResults>}

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
Returns:
Returns Promise which resolves to oj.ContainsKeysResults.
Type
Promise.<oj.ContainsKeysResults>
Example

Check if keys 1001 and 556 are contained

var containsKeys = [1001, 556];
dataprovider.containsKeys({keys: containsKeys}).then(function(value) {
  var results = value['results'];
  if (results.has(1001)) {
    console.log('Has key 1001');
  } else if (results.has(556){
    console.log('Has key 556');
  }
});

fetchByKeys(parameters) → {Promise.<oj.FetchByKeysResults>}

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
Returns:
Returns Promise which resolves to oj.FetchByKeysResults.
Type
Promise.<oj.FetchByKeysResults>
Example

Fetch for keys 1001 and 556

var fetchKeys = [1001, 556];
dataprovider.fetchByKeys({keys: fetchKeys}).then(function(value) {
  // get the data for key 1001
  console.log(value.results.get(1001).data);
});

fetchByOffset(parameters) → {Promise.<oj.FetchByOffsetResults>}

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
Returns:
Returns Promise which resolves to oj.FetchByOffsetResults.
Type
Promise.<oj.FetchByOffsetResults>
Example

Fetch by offset 5 rows starting at index 2

dataprovider.fetchByOffset({size: 5, offset: 2}).then(function(value) {
  var results = result['results'];
  var data = results.map(function(value) {
    return value['data'];
  });
  var keys = results.map(function(value) {
    return value['metadata']['key'];
  });
});

fetchFirst(params) → {AsyncIterable.<oj.FetchListResult>}

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
See:
Returns:
AsyncIterable with oj.FetchListResult
Type
AsyncIterable.<oj.FetchListResult>
Example

Get an asyncIterator and then fetch first block of data by executing next() on the iterator. Subsequent blocks can be fetched by executing next() again.

var asyncIterator = dataprovider.fetchFirst(options)[Symbol.asyncIterator]();
asyncIterator.next().then(function(result) {
  var value = result.value;
  var data = value.data;
  var keys = value.metadata.map(function(val) {
    return val.key;
});

getCapability(capabilityName) → {Object}

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
Returns:
capability information or null if unsupported
Type
Object
Example

Check what kind of fetchByKeys is supported.

var capabilityInfo = dataprovider.getCapability('fetchByKeys');
if (capabilityInfo.implementation == 'iteration') {
  // the DataProvider supports iteration for fetchByKeys
  ...

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
Returns:
Returns a Promise which resolves to the total number of rows. -1 is unknown row count.
Type
Promise.<number>
Example

Get the total rows

dataprovider.getTotalSize().then(function(value) {
  if (value == -1) {
    // we don't know the total row count
  } else {
    // the total count
    console.log(value);
});

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
Returns:
string that indicates if this data provider is empty
Type
"yes" | "no" | "unknown"
Example

Check if empty

var isEmpty = dataprovider.isEmpty();
console.log('DataProvider is empty: ' + isEmpty);