com.ibm.websphere.objectgrid.jpa
Interface ClientLoader

public interface ClientLoader

A client loader loads data into ObjectGrid maps. The data is retrieved from the database back end using a Java Persistence API (JPA) provider. Therefore, a JPA provider is required to utilize this feature. The database here can be any back end supported by the chosen JPA provider.

Typically, a user application provides a persistence unit name, an entity class name, and a JPA query to the client loader. The client loader retrieves the JPA entity manager based on the persistence unit name, uses the entity manager to query the data from database with the provided entity class and JPA query, and finally loads the data into the distributed ObjectGrid maps. Optionally, a persistence property map could be provided to override the configured persistence properties.

If a JPA query is not provided, the default JPA query is "select o from ENTITY o", where "ENTITY" is the entity name.

A client loader loads the data into a distributed ObjectGrid in the following two ways:

1. Preload: In the preload mode, all the entries in the map are cleared before the client load using the JavaMap.clear() method. It gives the map an empty state to start with the load. If the map is entity map and it has cascade-delete relations to other maps, those related maps will be cleared too.
2. Reload: In a reload mode, the map is not cleared. Instead, the client loader runs the JPA query to ObjectGrid and invalidates all the query results from the ObjectGrid maps. If the map is entity map and it has cascade-invalidate relations to other maps, related entities in those maps will be invalidate too. Then it runs the JPA query to the JPA provider to get all the data from the database and load them into the distributed ObjectGrid maps in different partitions. Therefore, the provided JPA query should be supported by the ObjectGrid object query or entity query syntax as well as the JPA query syntax.

Whether the client loader does a preload or reload depends on the isPreload parameter in the load(ObjectGrid, String, String, Map, Class, String, Map, boolean, ClientLoadCallback) method. If the isPreload parameter is true, then it is a preload. Otherwise it is a reload.

Since:

WAS XD 6.1.0.3

Method Summary

void	load(ObjectGrid objectGrid, String mapName, String punitName, Map persistenceProps, Class entityClass, String loadQL, Map queryNamedParams, boolean isPreload, ClientLoadCallback callback) Load data into ObjectGrid maps.

Method Detail

load

void load(ObjectGrid objectGrid,
          String mapName,
          String punitName,
          Map persistenceProps,
          Class entityClass,
          String loadQL,
          Map queryNamedParams,
          boolean isPreload,
          ClientLoadCallback callback)
          throws ObjectGridException

Load data into ObjectGrid maps.

An entity class is required to run the JPA query. If the ObjectGrid map is a map storing POJOs, the entity class has to be provided to this method. However, if the map is an entity map, then an ObjectGrid entity class has already been defined for this map. If the JPA entity class is the same as ObjectGrid entity class, then a null value can be provided to this method.

Morphed entities could exist after reloading. Take a one-to-many entity relation "Department->Employee" as an example. If an employee E1 moved from department A to B in the database, and ObjectGrid map only contains department A, then E1 will still be in ObjectGrid after reloading, but in a morphed state.

The ClientCallback can be used to receive the pre-start load event and the post-finish event. Users can use these events to do some cleanup work. For example, when the callback receives a post-finish load event after reloading, a map cleanup can be done to ensure all the morphed entities are removed.

Before the preload, the client might want to bring the shard to AvailabilityState.PRELOAD state by calling StateManager.setObjectGridState(com.ibm.websphere.objectgrid.AvailabilityState, ObjectGrid) method. When an shard is in AvailabilityState.PRELOAD state, only session object retrieved using ClientLoaderFactory.getClientLoaderSession(Session) can be used to access that shard. After the preload, the client revert the state back to the state.

Parameters:

objectGrid - the ObjectGrid to be loaded. It has to be a client ObjectGrid instance or a server ObjectGrid instance. If it is a local ObjectGrid instance, an IllegalArgumentException will be thrown.

mapName - the name of the map to be loaded

punitName - the JPA persistence unit name. If a persistence unit name is not provided, the first persistence unit in the persistence.xml will be used.

persistenceProps - Additional properties to use when creating the javax.persistence.EntityManagerFactory factory. The values of these properties override any values that may have been configured elsewhere.

entityClass - the entity class.

loadQL - the JPA query string used to query the the JPA entities. If this parameter is not provided, we will create a default query string "select o from ENTITY o".

queryNamedParams - the named parameters to the query

isPreload - indicate whether it is a preload or reload. For preload, we will first invalidate all the data from the map. For reload, we will only invalidate those data matched by the query. into ObjectGrid maps.

callback - the client load callback to receive the pre-start and post-finish events.

Throws:

ObjectGridException - If the preload fails, or any other ObjectGridException occured during the processing.