Summary: External Data Source API

External Data Source Components

External Data Source has three major functionalities, each of which is defined by a specific interface:

  • Data Retrieval - Determines how data is retrieved from the data source, when it is needed by the space.
  • Data Persistency - Determines how data is updated in the data source, when it is changed in the space.
  • Initialization and Shutdown - Determines:
    • How the data source is configured - database name,location.
    • Which data is loaded into the space at startup.
    • How to close the data source.

API Matrix

EDS Implements:SQLDataProvider, DataPersister

Client Call EDS Call
write iterator SQLQuery,write
take remove
read with ID iterator SQLQuery
read iterator SQLQuery
readMultiple iterator SQLQuery
takeMultiple iterator SQLQuery, remove
readMultiple SQLQuery iterator SQLQuery
takeMultiple SQLQuery iterator SQLQuery ,remove

EDS Implements:DataProvider, DataPersister

Client Call EDS Call
write read using ID,write
take remove
read with ID iterator
read iterator
readMultiple iterator
takeMultiple iterator , remove
readMultiple SQLQuery  
takeMultiple SQLQuery  

EDS Implements:DataProvider,SQLDataProvider,DataPersister

Client Call EDS Call
write iterator SQLQuery,write
take remove
read with ID iterator SQLQuery
read iterator SQLQuery
readMultiple iterator SQLQuery
takeMultiple iterator SQLQuery, remove
readMultiple SQLQuery iterator SQLQuery
takeMultiple SQLQuery iterator SQLQuery ,remove

Implementation Options

Based on your application persistency requirements - you may need to implement all EDS interfaces or only few of them.
For example - when your application should load data from the database without writing data into back into the database (using EDS read-only usage mode), you should implement only the SQLDataProvider interface. In such a case you may write data into the database via the Mirror Service by implementing the BulkDataPersister.

Data Retrieval

There are two options to implement Data retrieval:

SQL-based API

The SQLDataProvider allows you to implement a full-featured EDS with databases that support SQL queries.
When the EDS implements the SQLDataProvider interface, all space data retrieval operations are translated to SQLQuery and passed to DataIterator iterator(SQLQuery query). The result is an iterator of the fetched data, that is iterated by the space, and the data is inserted into the space memory. See Default implementation of SQLDataProvider.iterator().

Object-based API

The DataProvider should be used for databases that don't support SQL queries.

  • DataIterator iterator(userObjectTemplate): This method is called when read is performed with a template. The original template is passed as the parameter to iterator(). The result is an iterator of the fetched data that is iterated by the space, and the data is inserted into the space memory.
  • Object read(Object userObjectTemplate): This method is used to optimize queries that always return a single object - reads with UID. The data is the user object template that has a non-null UID. The result should be a matching object found in the EDS with the same ID.

Data Persistency

There are two options to implement Data Persistency:

Batch Persistency Mode

If the EDS implements the BulkDataPersister interface, data persistency operations are translated to a list of BulkItem(operation+data), and passed to executeBulk(List<BulkItem> items).
The BulkItem is an object that has two components - the data that was changed and the operation that was executed - WRITE/UPDATE/REMOVE. See Default implementation of BulkDataPersister.executeBulk()

Single Persistency Mode

The DataPersister interface has three methods for each space operation:

  • write(Object userObject) - Invoked when a new object is inserted to the space.
  • update(Object userObject) - Invoked when an object is updated in the space.
  • remove(Object userObject) - Invoked when an object is removed from the space.
userObject is always the original user object unless stated otherwise. See the space-config.external-data-source.data-class at the External Data Source Properties section.

Initialization and Shutdown

Initialization and Shutdown done via the ManagedDataSource interface:

  • init(Properties customProperties) is called on space startup, so all the EDS initialization is done in this method. All the configuration is passed in the customProperties parameter. This is the content of a properties file that is completely implementation dependant, and can be configured in the following way: see EDS Configuration and Default implementation of ManagedDataSource.init()
  • DataIterator initialLoad() is called just after the init(). It returns an iterator to the data that should be inserted into the space on startup. This can be all of the data, or only a subset. This depends on the implementation - see Default implementation of ManagedDataSource.initialLoad()
  • shutdown() is called before the space is closed. This is the place to close all the database connections, or any other resources that EDS was using - see Default implementation of ManagedDataSource.shutdown()

All External Data Source APIs

GigaSpaces.com - Legal Notice - 3rd Party Licenses - Site Map - API Docs - Forum - Downloads - Blog - White Papers - Contact Tech Writing - Gen. by Atlassian Confluence