Overview

To use the External Data Source interface, define the following in your persistent space schema:

<space-config>
    <persistent>
        <enabled>true</enabled>
        <StorageAdapterClass>com.j_spaces.sadapter
         .datasource.DataAdapter</StorageAdapterClass>
    </persistent>
</space-config>

or add the following properties to your <GigaSpaces Root>\config\gs.properties file:

space-config.persistent.enabled=true
space-config.persistent.StorageAdapterClass=com.j_spaces.sadapter.datasource.DataAdapter

External Data Source Configuration

For additional, implementation-specific configuration, you can add the following properties to your gs.properties file, or use the space schema external-data-source element.

gs.properties

Space Schema

<!-- External data source configuration -->
           <external-data-source>
                <!-- external data source implementation class -->
             	<!-- default is com.gigaspaces.datasource.hibernate.HibernateDataSource -->
           		<data-source-class>com.gigaspaces.datasource.hibernate.HibernateDataSource</data-source-class>
           		<!-- name of the data class that will be passed to the data source -->
           		<!-- default is java.lang.Object-->
           		<data-class>java.lang.Object</data-class>
           		<!-- should be  set to true if data source supports java inheritance in queries -->
           		<!-- default is true-->
           		<supports-inheritance>true</supports-inheritance>
           		<!-- should be  set to true if  data source supports  data versions -->
           		<!-- default is false-->
           		<supports-version>false</supports-version>
           		<!-- data source usage mode - options - read-write,read-only -->
           		<!-- default is read-write-->               		
           		<usage>read-write</usage>
           		<!-- user specific properties file - default none-->               		
           		<init-properties-file></init-properties-file>
           </external-data-source>

Data Class Setting

You can define the class of the objects that are passed to the data source.

space-config.external-data-source.data-class=java.lang.Object

This property should always be set to java.lang.Object unless the data source implementation requires the raw space Entry and not the original Java object.

In this case, the configuration should be:

space-config.external-data-source.data-class=com.j_spaces.core.IGSEntry

Central Data Source

Recovery should be set to false in cluster-xml when working with a central data source, since the Entries are already in the database and there is no need to recover them from a backup space.

Central Data Source with Partitioned Space

When running in a partitioned space cluster topology, each partition can use the same database server instance to store its data.

The relevant setting used to control this option is:

set <central-data-source>${com.gs.cluster.cache-loader.central-data-source}</central-data-source>

in cluster-xml.

Inheritance (Sub-Classes) Support

If the underlying data source supports sub-class queries (like Hibernate), the ExternalDataSource is invoked only once for the queried super class. Otherwise, it is called for the super class and each of its sub-classes.

space-config.external-data-source.supports-inheritance=true

External Data Source Life Cycle

The ExternalDataSource provides ability to control the lifecycle of the underlying data source implementation.

The ExternalDataSource.init method configures the data source at space startup.

The ExternalDataSource.shutdown method is called at space shutdown – providing the user the ability to close and release any resources acquired by the data source.

Cache Preload and Refresh Ahead

The user can load data into the space when started, or pre-fetch "extra" to speed up future queries.

To do this, you can override the initialLoad method to return the Entries that should be loaded into the space on startup.

This method returns an iterator that is used by the space to load data from the data source.

Space Mapping Configuration File gs.xml

You can define space class meta data using class and field level decorations. These can be defined via annotations and XML space class mapping configuration files.

For more details, refer to the POJO Class and Field Level Annotations section.

The space classpath includes user classes and gs.xml files that are loaded as resources.

Troubleshooting

To enable logging for ExternalDataSource, edit the <GigaSpaces Root>\config\gs_logging.properties file, and set the persistent level to CONFIG or FINER.

• CONFIG messages are intended to provide a variety of static configuration information, and to assist in debugging problems that may be associated with particular configurations.

  com.gigaspaces.persistent.level = CONFIG

• FINER messages log calls for entering, returning, or throwing an exception to and from cache interface implementations.

  com.gigaspaces.persistent.level = FINER

For details on viewing the exact configuration in which the system is currently running, refer to the Container Maintenance section.