org.springframework.data.gemfire

Class GemfireTemplate

java.lang.Object

org.springframework.data.gemfire.GemfireAccessor

org.springframework.data.gemfire.GemfireTemplate

All Implemented Interfaces:

InitializingBean, GemfireOperations

public class GemfireTemplate
extends GemfireAccessor
implements GemfireOperations

The GemfireTemplate class simplifies Apache Geode data access operations, converting Apache Geode GemFireCheckedExceptions and GemFireExceptions into Spring DataAccessExceptions, following the org.springframework.dao Exception hierarchy. The central method is execute, supporting Apache Geode data 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. This template class is typically used to implement data access operations or business logic services using Apache Geode within their implementation but are Geode-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.

Author:

Costin Leau, John Blum

See Also:

Map, GemFireCheckedException, GemFireException, Region, ClientCache, Query, QueryService, SelectResults, GemfireAccessor, GemfireOperations

Field Summary

Fields inherited from class org.springframework.data.gemfire.GemfireAccessor

logger

Constructor Summary

Constructors

Constructor and Description
GemfireTemplate() Constructs a new, uninitialized instance of GemfireTemplate.
GemfireTemplate(org.apache.geode.cache.Region<K,V> region) Constructs a new instance of the GemfireTemplate initialized with the given Region on which (cache) data access operations will be performed.

Method Summary

Modifier and Type	Method and Description
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> org.apache.geode.cache.Region<K,V>	createRegionProxy(org.apache.geode.cache.Region<K,V> region) Create a close-suppressing proxy for the given Apache Geode cache Region.
<T> T	execute(GemfireCallback<T> action) Executes the given data access operation defined by the GemfireCallback in the context of Apache Geode.
<T> T	execute(GemfireCallback<T> action, boolean exposeNativeRegion) Executes the given data access operation defined by the GemfireCallback in the context of Apache Geode.
<E> org.apache.geode.cache.query.SelectResults<E>	find(String query, Object... arguments) Executes a GemFire query with the given (optional) parameters and returns the result.
<T> T	findUnique(String query, Object... arguments) 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() Determines whether to expose the native Region or the Region proxy to GemfireCallback code.
<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> org.apache.geode.cache.query.SelectResults<E>	query(String query) Shortcut for Region.query(String) method.
<K,V> V	remove(K key)
void	removeAll(Collection<?> keys)
<K,V> V	replace(K key, V value)
<K,V> boolean	replace(K key, V oldValue, V newValue)
protected org.apache.geode.cache.query.QueryService	resolveQueryService(org.apache.geode.cache.Region<?,?> region) Returns the QueryService used by this template in its query/finder methods.
void	setExposeNativeRegion(boolean exposeNativeRegion) Configure whether to expose the native 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()

Constructs a new, uninitialized instance of GemfireTemplate.

See Also:

GemfireTemplate(Region)

GemfireTemplate

public GemfireTemplate(org.apache.geode.cache.Region<K,V> region)

Constructs a new instance of the GemfireTemplate initialized with the given Region on which (cache) data access operations will be performed.

Type Parameters:

K - type of the Region key.

V - type of the Region value.

Parameters:

region - Region on which data access operations will be performed by this template; must not be null.

Throws:

IllegalArgumentException - if Region is null.

See Also:

GemfireAccessor.setRegion(Region), afterPropertiesSet()

Method Detail

afterPropertiesSet

public void afterPropertiesSet()

Specified by:

afterPropertiesSet in interface InitializingBean

Overrides:

afterPropertiesSet in class GemfireAccessor

setExposeNativeRegion

public void setExposeNativeRegion(boolean exposeNativeRegion)

Configure whether to expose the native Region to GemfireCallback code.

Default is false, therefore a Region proxy will be returned, suppressing close calls.

As there is often a need to cast to an 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 indicating whether the native Region should be exposed to the GemfireCallback.

See Also:

GemfireCallback

isExposeNativeRegion

public boolean isExposeNativeRegion()

Determines whether to expose the native Region or the Region proxy to GemfireCallback code.

Returns:

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

See Also:

setExposeNativeRegion(boolean)

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

removeAll

public void removeAll(Collection<?> keys)

Specified by:

removeAll 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> org.apache.geode.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> org.apache.geode.cache.query.SelectResults<E> find(String query,
                                                              Object... arguments)
                                                       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:

query - the OQL query statement to execute.

arguments - 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 query,
                        Object... arguments)
                 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:

query - the OQL query statement to execute.

arguments - 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[])

resolveQueryService

protected org.apache.geode.cache.query.QueryService resolveQueryService(org.apache.geode.cache.Region<?,?> region)

Returns the QueryService used by this template in its query/finder methods.

Parameters:

region - Region used to acquire the QueryService.

Returns:

the QueryService that will perform the Query.

See Also:

Region, Region.getRegionService(), RegionService.getQueryService(), ClientCache.getLocalQueryService()

execute

public <T> T execute(@NonNull
                     GemfireCallback<T> action)
              throws DataAccessException

Executes the given data access operation defined by the GemfireCallback in the context of Apache Geode.

Specified by:

execute in interface GemfireOperations

Type Parameters:

T - type returned by the GemfireCallback.

Parameters:

action - GemfireCallback object defining the Apache Geode action to execute; must not be null.

Returns:

the result of executing the GemfireCallback.

Throws:

DataAccessException - if an Apache Geode error is thrown by a data access operation.

IllegalArgumentException - if GemfireCallback is null.

See Also:

GemfireCallback, execute(GemfireCallback, boolean)

execute

public <T> T execute(@NonNull
                     GemfireCallback<T> action,
                     boolean exposeNativeRegion)
              throws DataAccessException

Executes the given data access operation defined by the GemfireCallback in the context of Apache Geode.

Specified by:

execute in interface GemfireOperations

Type Parameters:

T - type returned by the GemfireCallback.

Parameters:

action - GemfireCallback object defining the Apache Geode action to execute; must not be null.

exposeNativeRegion - boolean value indicating whether to pass the native Region or the Region proxy to the GemfireCallback.

Returns:

the result of executing the GemfireCallback.

Throws:

DataAccessException - if an Apache Geode error is thrown by a data access operation.

IllegalArgumentException - if GemfireCallback is null.

See Also:

GemfireCallback

createRegionProxy

@NonNull
protected <K,V> org.apache.geode.cache.Region<K,V> createRegionProxy(@NonNull
                                                                              org.apache.geode.cache.Region<K,V> region)

Create a close-suppressing proxy for the given Apache Geode cache Region. Called by the execute method.

Type Parameters:

K - type of the Region key.

V - type of the Region value.

Parameters:

region - Region for which a proxy will be created.

Returns:

the Region proxy implementing all interfaces implemented by the passed-in Region object.

See Also:

Region.close(), execute(GemfireCallback, boolean)