org.springframework.data.gemfire
Class GemfireTemplate

java.lang.Object
  extended by org.springframework.data.gemfire.GemfireAccessor
      extended by org.springframework.data.gemfire.GemfireTemplate
All Implemented Interfaces:
InitializingBean, GemfireOperations

public class GemfireTemplate
extends GemfireAccessor
implements GemfireOperations

Helper class that simplifies GemFire data access code and converts GemFireCheckedException and GemFireException into Spring DataAccessException, following the org.springframework.dao exception hierarchy. The central method is execute, supporting GemFire access code implementing the GemfireCallback interface. It provides dedicated handling such that neither the GemfireCallback implementation nor the calling code needs to explicitly care about handling Region life-cycle exceptions. Typically used to implement data access or business logic services that use GemFire within their implementation but are GemFire-agnostic in their interface. The latter or code calling the latter only have to deal with business objects, query objects, and org.springframework.dao exceptions.

See Also:
Map, GemfireAccessor, GemfireOperations, Region, Query, QueryService, SelectResults

Field Summary
 
Fields inherited from class org.springframework.data.gemfire.GemfireAccessor
log
 
Constructor Summary
GemfireTemplate()
           
GemfireTemplate(com.gemstone.gemfire.cache.Region<K,V> region)
           
 
Method Summary
 void afterPropertiesSet()
           
 boolean containsKey(Object key)
           
 boolean containsKeyOnServer(Object key)
           
 boolean containsValue(Object value)
           
 boolean containsValueForKey(Object key)
           
<K,V> void
create(K key, V value)
           
protected
<K,V> com.gemstone.gemfire.cache.Region<K,V>
createRegionProxy(com.gemstone.gemfire.cache.Region<K,V> region)
          Create a close-suppressing proxy for the given GemFire Cache Region.
<T> T
execute(GemfireCallback<T> action)
          Execute the action specified by the given action object within a Region.
<T> T
execute(GemfireCallback<T> action, boolean exposeNativeRegion)
          Execute the action specified by the given action object within a Region.
<E> com.gemstone.gemfire.cache.query.SelectResults<E>
find(String queryString, Object... params)
          Executes a GemFire query with the given (optional) parameters and returns the result.
<T> T
findUnique(String queryString, Object... params)
          Executes a GemFire query with the given (optional) parameters and returns the result.
<K,V> V
get(K key)
           
<K,V> Map<K,V>
getAll(Collection<?> keys)
           
 boolean isExposeNativeRegion()
          Returns whether to expose the native GemFire Cache Region or a Region proxy to the GemfireCallback code.
protected  com.gemstone.gemfire.cache.query.QueryService lookupQueryService(com.gemstone.gemfire.cache.Region<?,?> region)
          Returns the query service used by the template in its find methods.
<K,V> V
put(K key, V value)
           
<K,V> void
putAll(Map<? extends K,? extends V> map)
           
<K,V> V
putIfAbsent(K key, V value)
           
<E> com.gemstone.gemfire.cache.query.SelectResults<E>
query(String query)
          Shortcut for Region.query(String) method.
<K,V> V
remove(K key)
           
<K,V> V
replace(K key, V value)
           
<K,V> boolean
replace(K key, V oldValue, V newValue)
           
 void setExposeNativeRegion(boolean exposeNativeRegion)
          Sets whether to expose the native Gemfire Region to GemfireCallback code.
 
Methods inherited from class org.springframework.data.gemfire.GemfireAccessor
convertGemFireAccessException, convertGemFireAccessException, convertGemFireQueryException, getRegion, setRegion
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

GemfireTemplate

public GemfireTemplate()

GemfireTemplate

public GemfireTemplate(com.gemstone.gemfire.cache.Region<K,V> region)
Method Detail

afterPropertiesSet

public void afterPropertiesSet()
Specified by:
afterPropertiesSet in interface InitializingBean
Overrides:
afterPropertiesSet in class GemfireAccessor

setExposeNativeRegion

public void setExposeNativeRegion(boolean exposeNativeRegion)
Sets whether to expose the native Gemfire Region to GemfireCallback code. Default is "false": a Region proxy will be returned, suppressing close calls.

As there is often a need to cast to a interface, the exposed proxy implements all interfaces implemented by the original Region. If this is not sufficient, turn this flag to "true".

Parameters:
exposeNativeRegion - a boolean value to indicate whether the native GemFire Cache Region should be exposed to the GemfireCallback.
See Also:
GemfireCallback

isExposeNativeRegion

public boolean isExposeNativeRegion()
Returns whether to expose the native GemFire Cache Region or a Region proxy to the GemfireCallback code.

Returns:
a boolean value indicating whether the native GemFire Cache Region or Region proxy is exposed to the GemfireCallback code.

containsKey

public boolean containsKey(Object key)
Specified by:
containsKey in interface GemfireOperations

containsKeyOnServer

public boolean containsKeyOnServer(Object key)
Specified by:
containsKeyOnServer in interface GemfireOperations

containsValue

public boolean containsValue(Object value)
Specified by:
containsValue in interface GemfireOperations

containsValueForKey

public boolean containsValueForKey(Object key)
Specified by:
containsValueForKey in interface GemfireOperations

create

public <K,V> void create(K key,
                         V value)
Specified by:
create in interface GemfireOperations

get

public <K,V> V get(K key)
Specified by:
get in interface GemfireOperations

getAll

public <K,V> Map<K,V> getAll(Collection<?> keys)
Specified by:
getAll in interface GemfireOperations

put

public <K,V> V put(K key,
                   V value)
Specified by:
put in interface GemfireOperations

putAll

public <K,V> void putAll(Map<? extends K,? extends V> map)
Specified by:
putAll in interface GemfireOperations

putIfAbsent

public <K,V> V putIfAbsent(K key,
                           V value)
Specified by:
putIfAbsent in interface GemfireOperations

remove

public <K,V> V remove(K key)
Specified by:
remove in interface GemfireOperations

replace

public <K,V> V replace(K key,
                       V value)
Specified by:
replace in interface GemfireOperations

replace

public <K,V> boolean replace(K key,
                             V oldValue,
                             V newValue)
Specified by:
replace in interface GemfireOperations

query

public <E> com.gemstone.gemfire.cache.query.SelectResults<E> query(String query)
Description copied from interface: GemfireOperations
Shortcut for Region.query(String) method. Filters the values of this region using the predicate given as a string with the syntax of the WHERE clause of the query language. The predefined variable this may be used inside the predicate to denote the current element being filtered. This method evaluates the passed in where clause and returns results. It is supported on servers as well as clients. When executed on a client, this method always runs on the server and returns results. When invoking this method from the client, applications can pass in a where clause or a complete query.

Specified by:
query in interface GemfireOperations
Type Parameters:
E - type parameter specifying the type of the select results.
Parameters:
query - an OQL Query language boolean query predicate.
Returns:
A SelectResults containing the values of this Region that match the predicate.
See Also:
Region.query(String)

find

public <E> com.gemstone.gemfire.cache.query.SelectResults<E> find(String queryString,
                                                                  Object... params)
                                                       throws InvalidDataAccessApiUsageException
Description copied from interface: GemfireOperations
Executes a GemFire query with the given (optional) parameters and returns the result. Note this method expects the query to return multiple results; for queries that return only one element use GemfireOperations.findUnique(String, Object...). As oppose, to the GemfireOperations.query(String) method, this method allows for more generic queries (against multiple regions even) to be executed. Note that the local query service is used if the region is configured as a client without any pool configuration or server connectivity - otherwise the query service on the default pool is being used.

Specified by:
find in interface GemfireOperations
Type Parameters:
E - type parameter specifying the type of the select results.
Parameters:
queryString - the OQL query statement to execute.
params - an array of Object values used as arguments to bind to the OQL query parameters (such as $1).
Returns:
A SelectResults instance holding the objects matching the query
Throws:
InvalidDataAccessApiUsageException - in case the query returns a single result (not a SelectResults).
See Also:
QueryService.newQuery(String), Query.execute(Object[]), SelectResults

findUnique

public <T> T findUnique(String queryString,
                        Object... params)
             throws InvalidDataAccessApiUsageException
Description copied from interface: GemfireOperations
Executes a GemFire query with the given (optional) parameters and returns the result. Note this method expects the query to return a single result; for queries that return multiple elements use GemfireOperations.find(String, Object...). As oppose, to the GemfireOperations.query(String) method, this method allows for more generic queries (against multiple regions even) to be executed. Note that the local query service is used if the region is configured as a client without any pool configuration or server connectivity - otherwise the query service on the default pool is being used.

Specified by:
findUnique in interface GemfireOperations
Type Parameters:
T - type parameter specifying the returned result type.
Parameters:
queryString - the OQL query statement to execute.
params - an array of Object values used as arguments to bind to the OQL query parameters (such as $1).
Returns:
The (single) object that represents the result of the query.
Throws:
InvalidDataAccessApiUsageException - in case the query returns multiple objects (through SelectResults).
See Also:
QueryService.newQuery(String), Query.execute(Object[])

lookupQueryService

protected com.gemstone.gemfire.cache.query.QueryService lookupQueryService(com.gemstone.gemfire.cache.Region<?,?> region)
Returns the query service used by the template in its find methods.

Parameters:
region - region to find the local query service from
Returns:
query service to use, local or generic
See Also:
Region, Region.getRegionService(), RegionService.getQueryService(), ClientCache.getLocalQueryService()

execute

public <T> T execute(GemfireCallback<T> action)
          throws DataAccessException
Description copied from interface: GemfireOperations
Execute the action specified by the given action object within a Region.

Specified by:
execute in interface GemfireOperations
Type Parameters:
T - type parameter specifying the returned result type.
Parameters:
action - callback object that specifies the Gemfire action to execute.
Returns:
a result object returned by the action, or null.
Throws:
DataAccessException - in case of GemFire errors.

execute

public <T> T execute(GemfireCallback<T> action,
                     boolean exposeNativeRegion)
          throws DataAccessException
Description copied from interface: GemfireOperations
Execute the action specified by the given action object within a Region.

Specified by:
execute in interface GemfireOperations
Type Parameters:
T - type parameter specifying the returned result type.
Parameters:
action - callback object that specifies the Gemfire action to execute.
exposeNativeRegion - whether to expose the native GemFire region to callback code.
Returns:
a result object returned by the action, or null.
Throws:
DataAccessException - in case of GemFire errors.

createRegionProxy

protected <K,V> com.gemstone.gemfire.cache.Region<K,V> createRegionProxy(com.gemstone.gemfire.cache.Region<K,V> region)
Create a close-suppressing proxy for the given GemFire Cache Region. Called by the execute method.

Type Parameters:
K - the Region key class type.
V - the Region value class type.
Parameters:
region - the GemFire Cache Region to create a proxy for.
Returns:
the Region proxy implementing all interfaces implemented by the passed-in Region object.
See Also:
Region.close(), execute(GemfireCallback, boolean)