From 17ec3138c8ff0e29eb74cce8129857047e17b506 Mon Sep 17 00:00:00 2001 From: John Blum Date: Wed, 7 May 2014 19:46:56 -0700 Subject: [PATCH] Completed SGF-272 refactoring SDG API Javadoc comments as well as cleaning up all Javadoc warnings reported by the SDG Gradle-based build when building on Java 7 and Java 8. --- .../data/gemfire/CacheFactoryBean.java | 66 ++++++++++------ .../data/gemfire/DeclarableSupport.java | 14 ++-- .../FixedPartitionAttributesFactoryBean.java | 5 +- .../data/gemfire/GemfireAccessor.java | 2 + .../data/gemfire/GemfireCallback.java | 5 +- .../data/gemfire/GemfireOperations.java | 27 ++++--- .../data/gemfire/GemfireTemplate.java | 34 ++++---- .../gemfire/GemfireTransactionManager.java | 11 +-- .../data/gemfire/RegionFactoryBean.java | 12 ++- .../data/gemfire/RegionLookupFactoryBean.java | 10 +-- .../data/gemfire/SubRegionFactoryBean.java | 14 +++- .../client/ClientCacheFactoryBean.java | 47 ++++++----- .../function/annotation/GemfireFunction.java | 22 +++++- .../gemfire/function/annotation/OnMember.java | 29 ++++--- .../function/annotation/OnMembers.java | 27 ++++--- .../gemfire/function/annotation/OnRegion.java | 26 ++++--- .../gemfire/function/annotation/OnServer.java | 39 ++++++---- .../function/annotation/OnServers.java | 36 +++++---- .../EnableGemfireFunctionExecutions.java | 24 +++++- .../execution/GemfireFunctionOperations.java | 78 +++++++++++-------- .../GemfireOnRegionFunctionTemplate.java | 6 +- .../OnRegionFunctionProxyFactoryBean.java | 13 ++-- .../ContinuousQueryListenerContainer.java | 13 +++- ...mfireListenerExecutionFailedException.java | 15 ++-- .../ContinuousQueryListenerAdapter.java | 9 ++- .../mapping/GemfirePersistentProperty.java | 10 ++- .../gemfire/mapping/MappingPdxSerializer.java | 5 +- .../data/gemfire/mapping/Regions.java | 5 +- .../data/gemfire/repository/Wrapper.java | 19 +++-- .../config/EnableGemfireRepositories.java | 28 +++++-- .../query/GemfireRepositoryQuery.java | 2 +- .../StringBasedGemfireRepositoryQuery.java | 2 +- .../support/GemfireRepositoryFactory.java | 3 +- .../gemfire/support/GemfireCacheManager.java | 51 +++++++++--- .../gemfire/support/GemfireDaoSupport.java | 58 +++++++++----- .../wan/AsyncEventQueueFactoryBean.java | 27 +++++-- .../wan/GatewayReceiverFactoryBean.java | 6 +- .../support/GemfireDaoSupportTests.java | 43 +++++----- 38 files changed, 536 insertions(+), 307 deletions(-) diff --git a/src/main/java/org/springframework/data/gemfire/CacheFactoryBean.java b/src/main/java/org/springframework/data/gemfire/CacheFactoryBean.java index 196290aa..ea8ccaf4 100644 --- a/src/main/java/org/springframework/data/gemfire/CacheFactoryBean.java +++ b/src/main/java/org/springframework/data/gemfire/CacheFactoryBean.java @@ -329,7 +329,7 @@ public class CacheFactoryBean implements BeanNameAware, BeanFactoryAware, BeanCl * Sets the PDX properties for the given object. Note this is implementation * specific as it depends on the type of the factory passed in. * - * @param factory + * @param factory the GemFire CacheFactory used to apply the PDX configuration settings. */ protected void applyPdxOptions(Object factory) { if (factory instanceof CacheFactory) { @@ -571,63 +571,74 @@ public class CacheFactoryBean implements BeanNameAware, BeanFactoryAware, BeanCl } /** - * - * @param copyOnRead + * Set the copyOnRead attribute of the Cache. + * + * @param copyOnRead a boolean value indicating whether the object stored in the Cache is copied on gets. */ public void setCopyOnRead(Boolean copyOnRead) { this.copyOnRead = copyOnRead; } /** - * - * @param lockTimeout + * Sets the number of seconds in which the implicit object lock request will timeout. + * + * @param lockTimeout an integer value specifying the object lock request timeout. */ public void setLockTimeout(Integer lockTimeout) { this.lockTimeout = lockTimeout; } /** - * - * @param lockLease + * Sets the number of seconds for implicit and explicit object lock leases to timeout. + * + * @param lockLease an integer value indicating the object lock lease timeout. */ public void setLockLease(Integer lockLease) { this.lockLease = lockLease; } /** - * - * @param messageSyncInterval + * Set for client subscription queue synchronization when this member acts as a server to clients + * and server redundancy is used. Sets the frequency (in seconds) at which the primary server sends messages + * to its secondary servers to remove queued events that have already been processed by the clients. + * + * @param messageSyncInterval an integer value specifying the number of seconds in which the primary server + * sends messages to secondary servers. */ public void setMessageSyncInterval(Integer messageSyncInterval) { this.messageSyncInterval = messageSyncInterval; } /** - * - * @param searchTimeout + * Set the number of seconds a netSearch operation can wait for data before timing out. + * + * @param searchTimeout an integer value indicating the netSearch timeout value. */ public void setSearchTimeout(Integer searchTimeout) { this.searchTimeout = searchTimeout; } /** - * - * @param evictionHeapPercentage + * Set the Cache's eviction heap percentage attribute. + * + * @param evictionHeapPercentage float-point value indicating the Cache's heap use percentage to trigger eviction. */ public void setEvictionHeapPercentage(Float evictionHeapPercentage) { this.evictionHeapPercentage = evictionHeapPercentage; } /** - * - * @param criticalHeapPercentage + * Set the Cache's critical heap percentage attribute. + * + * @param criticalHeapPercentage floating point value indicating the critical heap percentage. */ public void setCriticalHeapPercentage(Float criticalHeapPercentage) { this.criticalHeapPercentage = criticalHeapPercentage; } /** - * + * Set whether the Cache should be closed. + * * @param close set to false if destroy() should not close the cache */ public void setClose(boolean close) { @@ -635,16 +646,22 @@ public class CacheFactoryBean implements BeanNameAware, BeanFactoryAware, BeanCl } /** - * - * @param transactionListeners + * Sets the list of TransactionListeners used to configure the Cache to receive transaction events after + * the transaction is processed (committed, rolled back). + * + * @param transactionListeners the list of GemFire TransactionListeners listening for transaction events. + * @see com.gemstone.gemfire.cache.TransactionListener */ public void setTransactionListeners(List transactionListeners) { this.transactionListeners = transactionListeners; } /** - * - * @param transactionWriter + * Sets the TransactionWriter used to configure the Cache for handling transaction events, such as to veto + * the transaction or update an external DB before the commit. + * + * @param transactionWriter the GemFire TransactionWriter callback receiving transaction events. + * @see com.gemstone.gemfire.cache.TransactionWriter */ public void setTransactionWriter(TransactionWriter transactionWriter) { this.transactionWriter = transactionWriter; @@ -661,8 +678,9 @@ public class CacheFactoryBean implements BeanNameAware, BeanFactoryAware, BeanCl } /** - * - * @param dynamicRegionSupport + * Sets an instance of the DynamicRegionSupport to support Dynamic Regions in this GemFire Cache. + * + * @param dynamicRegionSupport the DynamicRegionSupport class to setup Dynamic Regions in this Cache. */ public void setDynamicRegionSupport(DynamicRegionSupport dynamicRegionSupport) { this.dynamicRegionSupport = dynamicRegionSupport; @@ -838,7 +856,9 @@ public class CacheFactoryBean implements BeanNameAware, BeanFactoryAware, BeanCl } /** - * return lazyInitialize + * Determines whether this Cache instance will be lazily initialized. + * + * @return a boolean value indicating whether this Cache instance will be lazily initialized. */ public boolean isLazyInitialize() { return lazyInitialize; diff --git a/src/main/java/org/springframework/data/gemfire/DeclarableSupport.java b/src/main/java/org/springframework/data/gemfire/DeclarableSupport.java index 8c3c1f08..f5fb7baf 100644 --- a/src/main/java/org/springframework/data/gemfire/DeclarableSupport.java +++ b/src/main/java/org/springframework/data/gemfire/DeclarableSupport.java @@ -62,7 +62,9 @@ public abstract class DeclarableSupport implements CacheCallback, Declarable { /** * Initialize the current instance based on the given properties. * - * @param props + * @param props the Properties used to initialize this Declarable. + * @see com.gemstone.gemfire.cache.Declarable#init(java.util.Properties) + * @see java.util.Properties */ protected void initInstance(Properties props) { } @@ -78,14 +80,14 @@ public abstract class DeclarableSupport implements CacheCallback, Declarable { } /** - * Sets the key under which the enclosing beanFactory can be found. Needed - * only if multiple beanFactories are used with GemFire inside the same - * class loader / class space. + * Sets the key under which the enclosing BeanFactory can be found. Needed only if multiple BeanFactories + * are used with GemFire inside the same class loader / class space. * * @see GemfireBeanFactoryLocator - * @param key + * @param key a String specifying the key used to lookup the "enclosing" BeanFactory in the presenence of + * multiple BeanFactories. */ public void setFactoryKey(String key) { this.factoryKey = key; } -} \ No newline at end of file +} diff --git a/src/main/java/org/springframework/data/gemfire/FixedPartitionAttributesFactoryBean.java b/src/main/java/org/springframework/data/gemfire/FixedPartitionAttributesFactoryBean.java index 996d0f31..f3f4bc94 100644 --- a/src/main/java/org/springframework/data/gemfire/FixedPartitionAttributesFactoryBean.java +++ b/src/main/java/org/springframework/data/gemfire/FixedPartitionAttributesFactoryBean.java @@ -30,8 +30,11 @@ public class FixedPartitionAttributesFactoryBean implements FactoryBean the Region key class type. + * @param the Region value class type. * @return the GemFire Cache Region. * @see com.gemstone.gemfire.cache.Region */ diff --git a/src/main/java/org/springframework/data/gemfire/GemfireCallback.java b/src/main/java/org/springframework/data/gemfire/GemfireCallback.java index 858bd272..30c9a4fc 100644 --- a/src/main/java/org/springframework/data/gemfire/GemfireCallback.java +++ b/src/main/java/org/springframework/data/gemfire/GemfireCallback.java @@ -41,8 +41,11 @@ public interface GemfireCallback { * A thrown custom RuntimeException is treated as an application exception: it gets propagated to * the caller of the template. * - * @param region a GemFire Cache Region. + * @param region the GemFire Cache Region upon which the operation of this callback will be performed. * @return a result object, or null if no result. + * @throws GemFireCheckedException for checked Exceptions occurring in GemFire. + * @throws GemFireException for runtime Exceptions occurring in GemFire. + * @see org.springframework.data.gemfire.GemfireTemplate * @see com.gemstone.gemfire.cache.Region */ T doInGemfire(Region region) throws GemFireCheckedException, GemFireException; diff --git a/src/main/java/org/springframework/data/gemfire/GemfireOperations.java b/src/main/java/org/springframework/data/gemfire/GemfireOperations.java index ac32108b..227b8189 100644 --- a/src/main/java/org/springframework/data/gemfire/GemfireOperations.java +++ b/src/main/java/org/springframework/data/gemfire/GemfireOperations.java @@ -64,13 +64,14 @@ public interface GemfireOperations { * 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. * + * @param type parameter specifying the type of the select results. + * @param query the OQL query statement to execute. + * @param params an array of Object values used as arguments to bind to the OQL query parameters (such as $1). + * @return A {@link SelectResults} instance holding the objects matching the query + * @throws InvalidDataAccessApiUsageException in case the query returns a single result (not a {@link SelectResults}). * @see QueryService#newQuery(String) * @see Query#execute(Object[]) * @see SelectResults - * @param query GemFire query - * @param params Values that are bound to parameters (such as $1) in this query. - * @return A {@link SelectResults} instance holding the objects matching the query - * @throws InvalidDataAccessApiUsageException in case the query returns a single result (not a {@link SelectResults}). */ SelectResults find(String query, Object... params) throws InvalidDataAccessApiUsageException; @@ -83,12 +84,13 @@ public interface GemfireOperations { * 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. * - * @see QueryService#newQuery(String) - * @see Query#execute(Object[]) - * @param query GemFire query - * @param params Values that are bound to parameters (such as $1) in this query. + * @param type parameter specifying the returned result type. + * @param query the OQL query statement to execute. + * @param params an array of Object values used as arguments to bind to the OQL query parameters (such as $1). * @return The (single) object that represents the result of the query. * @throws InvalidDataAccessApiUsageException in case the query returns multiple objects (through {@link SelectResults}). + * @see QueryService#newQuery(String) + * @see Query#execute(Object[]) */ T findUnique(String query, Object... params) throws InvalidDataAccessApiUsageException; @@ -98,16 +100,18 @@ public interface GemfireOperations { * 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. - - * @see Region#query(String) - * @param query A query language boolean query predicate. + * + * @param type parameter specifying the type of the select results. + * @param query an OQL Query language boolean query predicate. * @return A SelectResults containing the values of this Region that match the predicate. + * @see Region#query(String) */ SelectResults query(String query); /** * Execute the action specified by the given action object within a Region. * + * @param type parameter specifying the returned result type. * @param action callback object that specifies the Gemfire action to execute. * @return a result object returned by the action, or null. * @throws org.springframework.dao.DataAccessException in case of GemFire errors. @@ -117,6 +121,7 @@ public interface GemfireOperations { /** * Execute the action specified by the given action object within a Region. * + * @param type parameter specifying the returned result type. * @param action callback object that specifies the Gemfire action to execute. * @param exposeNativeRegion whether to expose the native GemFire region to callback code. * @return a result object returned by the action, or null. diff --git a/src/main/java/org/springframework/data/gemfire/GemfireTemplate.java b/src/main/java/org/springframework/data/gemfire/GemfireTemplate.java index c7491f59..c3dbf140 100644 --- a/src/main/java/org/springframework/data/gemfire/GemfireTemplate.java +++ b/src/main/java/org/springframework/data/gemfire/GemfireTemplate.java @@ -84,21 +84,24 @@ public class GemfireTemplate extends GemfireAccessor implements GemfireOperation } /** - * 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 {@link Region}. - * If this is not sufficient, turn this flag to "true". - * @see GemfireCallback + * 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 {@link Region}. If this is not sufficient, turn this flag to "true". + * + * @param exposeNativeRegion a boolean value to indicate whether the native GemFire Cache Region should be exposed + * to the GemfireCallback. + * @see org.springframework.data.gemfire.GemfireCallback */ public void setExposeNativeRegion(boolean exposeNativeRegion) { this.exposeNativeRegion = exposeNativeRegion; } /** - * Returns whether to expose the native GemFire Region to GemfireCallback - * code, or rather a Region proxy. + * Returns whether to expose the native GemFire Cache Region or a Region proxy to the GemfireCallback code. + * + * @return a boolean value indicating whether the native GemFire Cache Region or Region proxy is exposed + * to the GemfireCallback code. */ public boolean isExposeNativeRegion() { return this.exposeNativeRegion; @@ -458,13 +461,14 @@ public class GemfireTemplate extends GemfireAccessor implements GemfireOperation } /** - * Create a close-suppressing proxy for the given GemFire {@link Region}. + * Create a close-suppressing proxy for the given GemFire Cache {@link Region}. * Called by the execute method. - * - * @param region the GemFire Region to create a proxy for - * @return the Region proxy, implementing all interfaces - * implemented by the passed-in Region object - * @see Region#close() + * + * @param the Region key class type. + * @param the Region value class type. + * @param region the GemFire Cache Region to create a proxy for. + * @return the Region proxy implementing all interfaces implemented by the passed-in Region object. + * @see com.gemstone.gemfire.cache.Region#close() * @see #execute(GemfireCallback, boolean) */ @SuppressWarnings("unchecked") diff --git a/src/main/java/org/springframework/data/gemfire/GemfireTransactionManager.java b/src/main/java/org/springframework/data/gemfire/GemfireTransactionManager.java index 61ea5c76..8cf37f57 100644 --- a/src/main/java/org/springframework/data/gemfire/GemfireTransactionManager.java +++ b/src/main/java/org/springframework/data/gemfire/GemfireTransactionManager.java @@ -81,7 +81,7 @@ public class GemfireTransactionManager extends AbstractPlatformTransactionManage /** * Creates a new GemfireTransactionManager instance. * - * @param cache + * @param cache a reference to the GemFire Cache associated with Cache transactions. */ public GemfireTransactionManager(Cache cache) { this.cache = cache; @@ -211,10 +211,11 @@ public class GemfireTransactionManager extends AbstractPlatformTransactionManage } /** - * Sets the Gemfire {@link Region} (as an alternative in setting in the - * cache directly). - * - * @param region Gemfire region + * Sets the GemFire Cache {@link Region} (as an alternative in setting in the Cache directly). + * + * @param the Region key class type. + * @param the Region value class type. + * @param region the Gemfire Cache Region directly involved in the Cache transaction. */ public void setRegion(Region region) { Assert.notNull(region, "non-null arguments are required"); diff --git a/src/main/java/org/springframework/data/gemfire/RegionFactoryBean.java b/src/main/java/org/springframework/data/gemfire/RegionFactoryBean.java index ee47b90d..849b67de 100644 --- a/src/main/java/org/springframework/data/gemfire/RegionFactoryBean.java +++ b/src/main/java/org/springframework/data/gemfire/RegionFactoryBean.java @@ -583,16 +583,20 @@ public class RegionFactoryBean extends RegionLookupFactoryBean imple } /** - * Indicates whether the region referred by this factory bean, will be - * closed on shutdown (default true). + * Indicates whether the Region referred to by this factory bean will be closed on shutdown (default true). + * + * @param close a boolean value indicating whether this Region should be closed on member shutdown. + * @see #setDestroy(boolean) */ public void setClose(boolean close) { this.close = close; } /** - * Indicates whether the region referred by this factory bean, will be - * destroyed on shutdown (default false). + * Indicates whether the Region referred to by this factory bean will be destroyed on shutdown (default false). + * + * @param destroy a boolean value indicating whether the Region is to be destroy on member shutdown. + * @see #setDestroy(boolean) */ public void setDestroy(boolean destroy) { this.destroy = destroy; diff --git a/src/main/java/org/springframework/data/gemfire/RegionLookupFactoryBean.java b/src/main/java/org/springframework/data/gemfire/RegionLookupFactoryBean.java index ac307000..fe0bed9a 100644 --- a/src/main/java/org/springframework/data/gemfire/RegionLookupFactoryBean.java +++ b/src/main/java/org/springframework/data/gemfire/RegionLookupFactoryBean.java @@ -80,12 +80,12 @@ public class RegionLookupFactoryBean implements FactoryBean>, } /** - * Fall back method in case the named region does not exist. - * By default, this implementation throws an exception. + * Fallback method in case the named Region does not exist. By default, this implementation throws an exception. * - * @param cache GemFire cache - * @param regionName region name - * @throws Exception + * @param cache a reference to the GemFire Cache. + * @param regionName the name of the GemFire Cache Region. + * @return the Region in the GemFire Cache with the given name. + * @throws Exception if the lookup operation fails. */ protected Region lookupFallback(GemFireCache cache, String regionName) throws Exception { throw new BeanInitializationException(String.format("Cannot find Region [%1$s] in Cache [%2$s].", diff --git a/src/main/java/org/springframework/data/gemfire/SubRegionFactoryBean.java b/src/main/java/org/springframework/data/gemfire/SubRegionFactoryBean.java index 87c6aa20..7d6fac0e 100644 --- a/src/main/java/org/springframework/data/gemfire/SubRegionFactoryBean.java +++ b/src/main/java/org/springframework/data/gemfire/SubRegionFactoryBean.java @@ -139,27 +139,35 @@ public class SubRegionFactoryBean extends com.gemstone.gemfire.cache.Attri /** * Set to true if the subregion should already exist, e.g., specified by * <lookup-region> + * + * @param lookupOnly a boolean value indicating whether this Subregion should be looked up instead of created. */ public void setLookupOnly(boolean lookupOnly) { this.lookupOnly = lookupOnly; } /** - * Set the bean name - the same as the subregion full path + * Set the bean name - the same as the Subregion full path. + * + * @param name the name of this Subregion bean in the Spring context. */ public void setName(String name) { this.name = name; } /** - * Set the simple name of the region + * Set the simple name of this Subregion. + * + * @param regionName the simple name of this Subregion. */ public void setRegionName(String regionName) { this.regionName = regionName; } /** - * Set the parent Region + * Set the parent Region. + * + * @param parent a reference to the parent Region. */ public void setParent(Region parent) { this.parentRegion = parent; diff --git a/src/main/java/org/springframework/data/gemfire/client/ClientCacheFactoryBean.java b/src/main/java/org/springframework/data/gemfire/client/ClientCacheFactoryBean.java index 3a5f56a8..5f16be45 100644 --- a/src/main/java/org/springframework/data/gemfire/client/ClientCacheFactoryBean.java +++ b/src/main/java/org/springframework/data/gemfire/client/ClientCacheFactoryBean.java @@ -40,6 +40,7 @@ import com.gemstone.gemfire.pdx.PdxSerializer; * * @author Costin Leau * @author Lyndon Adams + * @author John Blum */ public class ClientCacheFactoryBean extends CacheFactoryBean { @@ -189,23 +190,35 @@ public class ClientCacheFactoryBean extends CacheFactoryBean { } /** - * Inform cluster client cache is ready to receive events. + * Inform the GemFire cluster that this client cache is ready to receive events. */ private void readyForEvents(){ ClientCache clientCache = ClientCacheFactory.getAnyInstance(); - if( readyForEvents != null && readyForEvents.booleanValue() && !clientCache.isClosed()){ + + if (Boolean.TRUE.equals(readyForEvents) && !clientCache.isClosed()) { try { clientCache.readyForEvents(); - }catch(IllegalStateException ex){ - // Cannot be called for a non-durable client so exception is throw + } + catch (IllegalStateException ignore) { + // Cannot be called for a non-durable client so exception is thrown. } } } - + + /** + * Sets the pool used by this client. + * + * @param pool the GemFire pool used by the Client Cache to obtain connections to the GemFire cluster. + */ + public void setPool(Pool pool) { + Assert.notNull(pool, "pool cannot be null"); + this.pool = pool; + } + /** * Sets the pool name used by this client. - * - * @param poolName + * + * @param poolName set the name of the GemFire Pool used by the GemFire Client Cache. */ public void setPoolName(String poolName) { Assert.hasText(poolName, "pool name is required"); @@ -213,9 +226,11 @@ public class ClientCacheFactoryBean extends CacheFactoryBean { } /** - * Set the readyForEvents event flag. - * - * @param readyForEvents + * Set the readyForEvents flag. + * + * @param readyForEvents sets a boolean flag to notify the server that this durable client is ready + * to receive updates. + * @see #getReadyForEvents() */ public void setReadyForEvents(Boolean readyForEvents){ this.readyForEvents = readyForEvents; @@ -225,16 +240,6 @@ public class ClientCacheFactoryBean extends CacheFactoryBean { return this.readyForEvents; } - /** - * Sets the pool used by this client. - * - * @param pool - */ - public void setPool(Pool pool) { - Assert.notNull(pool, "pool cannot be null"); - this.pool = pool; - } - @Override protected void applyPdxOptions(Object factory) { if (factory instanceof ClientCacheFactory) { @@ -242,4 +247,4 @@ public class ClientCacheFactoryBean extends CacheFactoryBean { } } -} \ No newline at end of file +} diff --git a/src/main/java/org/springframework/data/gemfire/function/annotation/GemfireFunction.java b/src/main/java/org/springframework/data/gemfire/function/annotation/GemfireFunction.java index a709022b..3b5b515e 100644 --- a/src/main/java/org/springframework/data/gemfire/function/annotation/GemfireFunction.java +++ b/src/main/java/org/springframework/data/gemfire/function/annotation/GemfireFunction.java @@ -27,26 +27,40 @@ import java.lang.annotation.Target; @Retention(RetentionPolicy.RUNTIME) @Target({ElementType.METHOD}) public @interface GemfireFunction { + /** * The name of the registered function. If not provided the simple method name will be used * @return the function id */ String id() default ""; + /** - * is the function HA - highly available + * Attribute to determine whether the GemFire Function is HA (Highly Available). + * + * @return a boolean value indicating whether the defined GemFire Function is HA. */ boolean HA() default false; + /** - * is the function optimized for write operations + * Attribute to determine whether the GemFire Function is optimized for write operations. + * + * @return a boolean value indicating if the GemFire Function is configured for optimized write operations. */ boolean optimizeForWrite() default false; + /** - * controls the maximum number of results sent at one time + * Controls the maximum number of results sent at one time. + * + * @return an integer value indicating the batch size, or the number of results sent at one time. */ int batchSize() default 0; + /** - * normally follows the method return type, i.e., false if void, true otherwise. This allows overriding + * Normally follows the method return type, i.e., false if void, true otherwise. This allows overriding * a void method which uses the resultSender directly. + * + * @return a boolean value indicating if the GemFire Function is expected to return a result. */ boolean hasResult() default false; + } diff --git a/src/main/java/org/springframework/data/gemfire/function/annotation/OnMember.java b/src/main/java/org/springframework/data/gemfire/function/annotation/OnMember.java index 58430cbb..8deab09f 100644 --- a/src/main/java/org/springframework/data/gemfire/function/annotation/OnMember.java +++ b/src/main/java/org/springframework/data/gemfire/function/annotation/OnMember.java @@ -26,21 +26,26 @@ import java.lang.annotation.Target; @Retention(RetentionPolicy.RUNTIME) @Target({ElementType.TYPE}) public @interface OnMember { - + /** - * The bean name - */ - String id() default ""; - - /** - * Optional ResultCollector bean reference + * The bean name of the POJO interface defining the GemFire Function executions. + * + * @return the bean name (id) of the POJO interface defining the GemFire Function executions. */ - String resultCollector() default ""; - - //TODO SpEL expression for DistributedMember? - + String id() default ""; + /** - * groups + * The GemFire Group to which the members must belong to target the Function execution. + * + * @return the name of the GemFire Group to which the members must belong for the targeted the Function execution. */ String groups() default ""; + + /** + * Optional ResultCollector bean reference. + * + * @return an optional bean name of the ResultCollector to process the Function results. + */ + String resultCollector() default ""; + } diff --git a/src/main/java/org/springframework/data/gemfire/function/annotation/OnMembers.java b/src/main/java/org/springframework/data/gemfire/function/annotation/OnMembers.java index 3bc9dc39..7ab8e0d2 100644 --- a/src/main/java/org/springframework/data/gemfire/function/annotation/OnMembers.java +++ b/src/main/java/org/springframework/data/gemfire/function/annotation/OnMembers.java @@ -25,21 +25,26 @@ import java.lang.annotation.Target; @Retention(RetentionPolicy.RUNTIME) @Target({ElementType.TYPE}) public @interface OnMembers { - + /** - * The bean name - */ + * The bean name of the POJO interface defining the GemFire Function executions. + * + * @return the bean name (id) of the POJO interface defining the GemFire Function executions. + */ String id() default ""; - + /** - * Optional ResultCollector bean reference + * The GemFire Group to which the members must belong to target the Function execution. + * + * @return the name of the GemFire Group to which the members must belong for the targeted the Function execution. + */ + String groups() default ""; + + /** + * Optional ResultCollector bean reference. + * + * @return an optional bean name of the ResultCollector to process the Function results. */ String resultCollector() default ""; - //TODO SpEL expression for DistributedMembers? - - /** - * groups - */ - String groups() default ""; } diff --git a/src/main/java/org/springframework/data/gemfire/function/annotation/OnRegion.java b/src/main/java/org/springframework/data/gemfire/function/annotation/OnRegion.java index 0cbb3b6e..93420998 100644 --- a/src/main/java/org/springframework/data/gemfire/function/annotation/OnRegion.java +++ b/src/main/java/org/springframework/data/gemfire/function/annotation/OnRegion.java @@ -27,18 +27,24 @@ import java.lang.annotation.Target; public @interface OnRegion { /** - * The bean name - */ + * The bean name of the POJO interface defining the GemFire Function executions. + * + * @return the bean name (id) of the POJO interface defining the GemFire Function executions. + */ String id() default ""; - + /** - * Optional ResultCollector bean reference + * A reference to the bean id of the GemFire Region. + * + * @return the bean name (id) of the GemFire Region. + */ + String region(); + + /** + * Optional ResultCollector bean reference. + * + * @return an optional bean name of the ResultCollector to process the Function results. */ String resultCollector() default ""; - - /** - * The reference to the bean id of the region - * @return the region id - */ - String region(); + } diff --git a/src/main/java/org/springframework/data/gemfire/function/annotation/OnServer.java b/src/main/java/org/springframework/data/gemfire/function/annotation/OnServer.java index b2020fe5..1bbf0ab3 100644 --- a/src/main/java/org/springframework/data/gemfire/function/annotation/OnServer.java +++ b/src/main/java/org/springframework/data/gemfire/function/annotation/OnServer.java @@ -25,26 +25,33 @@ import java.lang.annotation.Target; @Retention(RetentionPolicy.RUNTIME) @Target({ElementType.TYPE}) public @interface OnServer { - + /** - * The bean name - */ + * The bean name of the POJO interface defining the GemFire Function executions. + * + * @return the bean name (id) of the POJO interface defining the GemFire Function executions. + */ String id() default ""; - + /** - * Optional ResultCollector bean reference + * A reference to the cache. + * + * @return a bean name reference to the GemFire Cache. + */ + String cache() default ""; + + /** + * The pool bean name (optional). + * + * @return an optional bean name of the GemFire Pool. + */ + String pool() default ""; + + /** + * Optional ResultCollector bean reference. + * + * @return an optional bean name of the ResultCollector to process the Function results. */ String resultCollector() default ""; - /** - * The pool bean id (optional) - * @return - */ - - String pool() default ""; - /** - * A reference to the cache - */ - String cache() default ""; - } diff --git a/src/main/java/org/springframework/data/gemfire/function/annotation/OnServers.java b/src/main/java/org/springframework/data/gemfire/function/annotation/OnServers.java index 0028931e..d3104ba0 100644 --- a/src/main/java/org/springframework/data/gemfire/function/annotation/OnServers.java +++ b/src/main/java/org/springframework/data/gemfire/function/annotation/OnServers.java @@ -27,23 +27,31 @@ import java.lang.annotation.Target; public @interface OnServers { /** - * The bean name + * The bean name of the POJO interface defining the GemFire Function executions. + * + * @return the bean name (id) of the POJO interface defining the GemFire Function executions. */ String id() default ""; - + /** - * Optional ResultCollector bean reference - */ - String resultCollector() default ""; - - /** - * The pool bean name (optional) - * @return - */ - String pool() default ""; - - /** - * A reference to the cache + * A reference to the cache. + * + * @return a bean name reference to the GemFire Cache. */ String cache() default ""; + + /** + * The pool bean name (optional). + * + * @return an optional bean name of the GemFire Pool. + */ + String pool() default ""; + + /** + * Optional ResultCollector bean reference. + * + * @return an optional bean name of the ResultCollector to process the Function results. + */ + String resultCollector() default ""; + } diff --git a/src/main/java/org/springframework/data/gemfire/function/config/EnableGemfireFunctionExecutions.java b/src/main/java/org/springframework/data/gemfire/function/config/EnableGemfireFunctionExecutions.java index 123175c4..e071f25a 100644 --- a/src/main/java/org/springframework/data/gemfire/function/config/EnableGemfireFunctionExecutions.java +++ b/src/main/java/org/springframework/data/gemfire/function/config/EnableGemfireFunctionExecutions.java @@ -27,7 +27,6 @@ import org.springframework.context.annotation.Import; * These include interfaces annotated with one of {code} @OnRegion, @OnServer, @OnServers, @OnMember, @OnMembers{code} * * @author David Turanski - * */ @Target(ElementType.TYPE) @Retention(RetentionPolicy.RUNTIME) @@ -40,29 +39,46 @@ public @interface EnableGemfireFunctionExecutions { * Alias for the {@link #basePackages()} attribute. Allows for more concise annotation declarations e.g.: * {@code @EnableGemfireRepositories("org.my.pkg")} instead of * {@code @EnableGemfireRepositories(basePackages="org.my.pkg")}. + * + * @return an array of Strings indicating the names of packages to scan during component scanning. + * @see #basePackages() */ String[] value() default {}; + /** * Base packages to scan for annotated components. {@link #value()} is an alias for (and mutually exclusive with) this * attribute. Use {@link #basePackageClasses()} for a type-safe alternative to String-based package names. + * + * @return an array of Strings indicating the names of packages to scan during component scanning. + * @see #basePackageClasses() */ String[] basePackages() default {}; /** - * Type-safe alternative to {@link #basePackages()} for specifying the packages to scan for annotated components. The - * package of each class specified will be scanned. Consider creating a special no-op marker class or interface in - * each package that serves no purpose other than being referenced by this attribute. + * Type-safe alternative to {@link #basePackages()} for specifying the packages to scan for annotated components. + * The package of each class specified will be scanned. Consider creating a special no-op marker class or interface + * in each package that serves no purpose other than being referenced by this attribute. + * + * @return an array of Class types used to get the packages to scan during component scanning. + * @see #basePackages() */ Class[] basePackageClasses() default {}; /** * Specifies which types are eligible for component scanning. Further narrows the set of candidate components from * everything in {@link #basePackages()} to everything in the base packages that matches the given filter or filters. + * + * @return an array of Filters indicating which types are eligible for component scanning. + * @see org.springframework.context.annotation.ComponentScan.Filter */ Filter[] includeFilters() default {}; /** * Specifies which types are not eligible for component scanning. + * + * @return an array of Filters indicating which types are not eligible for component scanning. + * @see org.springframework.context.annotation.ComponentScan.Filter */ Filter[] excludeFilters() default {}; + } diff --git a/src/main/java/org/springframework/data/gemfire/function/execution/GemfireFunctionOperations.java b/src/main/java/org/springframework/data/gemfire/function/execution/GemfireFunctionOperations.java index 1b0d5d22..cf74b94b 100644 --- a/src/main/java/org/springframework/data/gemfire/function/execution/GemfireFunctionOperations.java +++ b/src/main/java/org/springframework/data/gemfire/function/execution/GemfireFunctionOperations.java @@ -24,49 +24,61 @@ import com.gemstone.gemfire.cache.execute.Function; public interface GemfireFunctionOperations { /** - * Execute an unregistered function - * @param function the function - * @param args calling arguments - * @return the contents of the results collector + * Execute an unregistered GemFire Function with the given arguments. + * + * @param type parameter specifying the result type of the Function execution. + * @param function the GemFire Function object to execute. + * @param args an array of Object arguments to the Function call. + * @return the contents of the ResultsCollector. */ public abstract Iterable execute(Function function, Object... args); - + + /** + * Execute a GemFire Function registered with the given ID. + * + * @param type parameter specifying the result type of the Function execution. + * @param functionId the ID under which the GemFire function is registered. + * @param args an array of Object arguments to the Function call. + * @return the results + */ + public abstract Iterable execute(String functionId, Object... args); + /** - * Execute an unregistered function with an expected singleton result - * @param function the function - * @param args calling arguments - * @return the first item in the results collector + * Execute an unregistered GemFire Function with the expected singleton result. + + * @param type parameter specifying the result type of the Function execution. + * @param function the GemFire Function object. + * @param args an array of Object arguments to the Function call. + * @return the first item in the ResultsCollector. + * @see com.gemstone.gemfire.cache.execute.Function */ public abstract T executeAndExtract(Function function, Object... args); /** - * Execute a function registered with an ID - * @param functionId the function ID - * @param args the calling arguments - * @return the results - */ - public abstract Iterable execute(String functionId, Object... args); - - /** - * Execute a function registered with an ID with no return value - * @param functionId the function ID - * @param args the calling arguments - */ - public void executeWithNoResult(String functionId, Object... args); - - /** - * Execute a function registered with an ID and with an expected singleton result - * @param functionId the function ID - * @param args the calling arguments + * Execute a GemFire Function registered with an ID and with an expected singleton result + + * @param type parameter specifying the result type of the Function execution. + * @param functionId the ID under which the GemFire function is registered. + * @param args an array of Object arguments to the Function call. * @return the first item in the results collector */ - public abstract T executeAndExtract(String functionId, Object... args); - - + public abstract T executeAndExtract(String functionId, Object... args); + + /** + * Execute a GemFire Function registered with the given ID having no return value. + + * @param functionId the ID under which the GemFire function is registered. + * @param args an array of Object arguments to the Function call. + */ + public void executeWithNoResult(String functionId, Object... args); + /** - * Execute a function using a native GemFire {@link com.gemstone.gemfire.cache.execute.Execution} instance - * @param callback a callback providing the execution instance - * @return the execution result + * Execute a GemFire Function using a native GemFire {@link com.gemstone.gemfire.cache.execute.Execution} instance. + * + * @param type parameter specifying the result type of the Function execution. + * @param callback a callback providing the execution instance. + * @return the Function execution result. + * @see org.springframework.data.gemfire.function.execution.GemfireFunctionCallback */ public abstract T execute(GemfireFunctionCallback callback); diff --git a/src/main/java/org/springframework/data/gemfire/function/execution/GemfireOnRegionFunctionTemplate.java b/src/main/java/org/springframework/data/gemfire/function/execution/GemfireOnRegionFunctionTemplate.java index 35aabe4b..04086e34 100644 --- a/src/main/java/org/springframework/data/gemfire/function/execution/GemfireOnRegionFunctionTemplate.java +++ b/src/main/java/org/springframework/data/gemfire/function/execution/GemfireOnRegionFunctionTemplate.java @@ -28,8 +28,10 @@ public class GemfireOnRegionFunctionTemplate extends AbstractFunctionTemplate im private Region region; /** - * - * @param region + * Constructs an instance of the GemFireOnRegionFunctionTemplate with the given GemFire Cache Region. + * + * @param region the GemFire Cache Region upon which the Function will be executed. + * @see com.gemstone.gemfire.cache.Region */ public GemfireOnRegionFunctionTemplate(Region region) { Assert.notNull(region, "Region cannot be null"); diff --git a/src/main/java/org/springframework/data/gemfire/function/execution/OnRegionFunctionProxyFactoryBean.java b/src/main/java/org/springframework/data/gemfire/function/execution/OnRegionFunctionProxyFactoryBean.java index 75542764..7cc7e829 100644 --- a/src/main/java/org/springframework/data/gemfire/function/execution/OnRegionFunctionProxyFactoryBean.java +++ b/src/main/java/org/springframework/data/gemfire/function/execution/OnRegionFunctionProxyFactoryBean.java @@ -22,18 +22,19 @@ import org.springframework.data.gemfire.util.ArrayUtils; * @author David Turanski * */ -public class OnRegionFunctionProxyFactoryBean extends GemfireFunctionProxyFactoryBean { +public class OnRegionFunctionProxyFactoryBean extends GemfireFunctionProxyFactoryBean { + private OnRegionExecutionMethodMetadata methodMetadata; + /** - * @param serviceInterface + * @param serviceInterface the Service class interface specifying the operations to proxy. * @param gemfireOnRegionOperations an {@link GemfireOnRegionOperations} instance */ - public OnRegionFunctionProxyFactoryBean(Class serviceInterface, - GemfireOnRegionOperations gemfireOnRegionOperations) { - super(serviceInterface, (GemfireFunctionOperations) gemfireOnRegionOperations); + public OnRegionFunctionProxyFactoryBean(Class serviceInterface, GemfireOnRegionOperations gemfireOnRegionOperations) { + super(serviceInterface, gemfireOnRegionOperations); methodMetadata = new OnRegionExecutionMethodMetadata(serviceInterface); } - + @Override protected Iterable invokeFunction(Method method, Object[] args) { diff --git a/src/main/java/org/springframework/data/gemfire/listener/ContinuousQueryListenerContainer.java b/src/main/java/org/springframework/data/gemfire/listener/ContinuousQueryListenerContainer.java index f269ccc6..d177d6de 100644 --- a/src/main/java/org/springframework/data/gemfire/listener/ContinuousQueryListenerContainer.java +++ b/src/main/java/org/springframework/data/gemfire/listener/ContinuousQueryListenerContainer.java @@ -127,6 +127,7 @@ public class ContinuousQueryListenerContainer implements BeanNameAware, Initiali *

The default implementation builds a {@link org.springframework.core.task.SimpleAsyncTaskExecutor} * with the specified bean name (or the class name, if no bean name is specified) as thread name prefix.

* + * @return an instance of the TaskExecutor used to process CQ events asynchronously. * @see org.springframework.core.task.SimpleAsyncTaskExecutor#SimpleAsyncTaskExecutor(String) */ protected TaskExecutor createDefaultTaskExecutor() { @@ -303,9 +304,11 @@ public class ContinuousQueryListenerContainer implements BeanNameAware, Initiali } /** - * Set an ErrorHandler to be invoked in case of any uncaught exceptions thrown - * while processing a event. By default there will be no ErrorHandler - * so that error-level logging is the only result. + * Set an ErrorHandler to be invoked in case of any uncaught exceptions thrown while processing a CQ event. + * By default there will be no ErrorHandler so that error-level logging is the only result. + * + * @param errorHandler the ErrorHandler invoked when uncaught exceptions are thrown while processing the CQ event. + * @see org.springframework.util.ErrorHandler */ public void setErrorHandler(ErrorHandler errorHandler) { this.errorHandler = errorHandler; @@ -427,7 +430,9 @@ public class ContinuousQueryListenerContainer implements BeanNameAware, Initiali /** * Execute the specified listener. * - * @see #handleListenerException + * @param listener the ContinuousQueryListener to notify of the CQ event. + * @param event the CQ event. + * @see #handleListenerException(Throwable) */ protected void executeListener(ContinuousQueryListener listener, CqEvent event) { try { diff --git a/src/main/java/org/springframework/data/gemfire/listener/GemfireListenerExecutionFailedException.java b/src/main/java/org/springframework/data/gemfire/listener/GemfireListenerExecutionFailedException.java index 98c7cc94..bd867463 100644 --- a/src/main/java/org/springframework/data/gemfire/listener/GemfireListenerExecutionFailedException.java +++ b/src/main/java/org/springframework/data/gemfire/listener/GemfireListenerExecutionFailedException.java @@ -31,19 +31,20 @@ public class GemfireListenerExecutionFailedException extends InvalidDataAccessAp /** * Constructs a new GemfireListenerExecutionFailedException instance. * - * @param msg - * @param cause + * @param message a String describing the cause of the exception. */ - public GemfireListenerExecutionFailedException(String msg, Throwable cause) { - super(msg, cause); + public GemfireListenerExecutionFailedException(String message) { + super(message); } /** * Constructs a new GemfireListenerExecutionFailedException instance. * - * @param msg + * @param message a String describing the cause of the exception. + * @param cause a Throwable that was underlying cause of this exception. */ - public GemfireListenerExecutionFailedException(String msg) { - super(msg); + public GemfireListenerExecutionFailedException(String message, Throwable cause) { + super(message, cause); } + } diff --git a/src/main/java/org/springframework/data/gemfire/listener/adapter/ContinuousQueryListenerAdapter.java b/src/main/java/org/springframework/data/gemfire/listener/adapter/ContinuousQueryListenerAdapter.java index 36c6649e..54c06651 100644 --- a/src/main/java/org/springframework/data/gemfire/listener/adapter/ContinuousQueryListenerAdapter.java +++ b/src/main/java/org/springframework/data/gemfire/listener/adapter/ContinuousQueryListenerAdapter.java @@ -125,9 +125,10 @@ public class ContinuousQueryListenerAdapter implements ContinuousQueryListener { } /** - * Specify the name of the default listener method to delegate to, - * for the case where no specific listener method has been determined. - * Out-of-the-box value is {@link #ORIGINAL_DEFAULT_LISTENER_METHOD "handleEvent}. + * Specify the name of the default listener method to delegate to in the case where no specific listener method + * has been determined. Out-of-the-box value is {@link #ORIGINAL_DEFAULT_LISTENER_METHOD "handleEvent}. + * + * @param defaultListenerMethod the name of the default listener method to invoke. * @see #getListenerMethodName */ public void setDefaultListenerMethod(String defaultListenerMethod) { @@ -137,6 +138,8 @@ public class ContinuousQueryListenerAdapter implements ContinuousQueryListener { /** * Return the name of the default listener method to delegate to. + * + * @return the name of the default listener method to invoke on CQ events. */ protected String getDefaultListenerMethod() { return this.defaultListenerMethod; diff --git a/src/main/java/org/springframework/data/gemfire/mapping/GemfirePersistentProperty.java b/src/main/java/org/springframework/data/gemfire/mapping/GemfirePersistentProperty.java index 48ec4550..c92ebc18 100644 --- a/src/main/java/org/springframework/data/gemfire/mapping/GemfirePersistentProperty.java +++ b/src/main/java/org/springframework/data/gemfire/mapping/GemfirePersistentProperty.java @@ -32,10 +32,12 @@ import org.springframework.data.mapping.model.SimpleTypeHolder; public class GemfirePersistentProperty extends AnnotationBasedPersistentProperty { /** - * @param field - * @param propertyDescriptor - * @param owner - * @param simpleTypeHolder + * Constructs an instance of the GemfirePersistentProperty with entity information. + * + * @param field the entity field corresponding to the persistent property. + * @param propertyDescriptor PropertyDescriptor for the entity's persistent property. + * @param owner the entity owning the persistent property. + * @param simpleTypeHolder type holder for primitive types. */ public GemfirePersistentProperty(Field field, PropertyDescriptor propertyDescriptor, PersistentEntity owner, SimpleTypeHolder simpleTypeHolder) { diff --git a/src/main/java/org/springframework/data/gemfire/mapping/MappingPdxSerializer.java b/src/main/java/org/springframework/data/gemfire/mapping/MappingPdxSerializer.java index 93a6b2f3..49b822d7 100644 --- a/src/main/java/org/springframework/data/gemfire/mapping/MappingPdxSerializer.java +++ b/src/main/java/org/springframework/data/gemfire/mapping/MappingPdxSerializer.java @@ -93,8 +93,9 @@ public class MappingPdxSerializer implements PdxSerializer, ApplicationContextAw } /** - * Configures custom pdx serializers to use for specific types - * @param customSerializers + * Configures custom PDX serializers to use for specific class types. + * + * @param customSerializers a mapping of domain object class types and their corresponding PDX serializer. */ public void setCustomSerializers(Map, PdxSerializer> customSerializers) { this.customSerializers = customSerializers; diff --git a/src/main/java/org/springframework/data/gemfire/mapping/Regions.java b/src/main/java/org/springframework/data/gemfire/mapping/Regions.java index 5d08c842..45320408 100644 --- a/src/main/java/org/springframework/data/gemfire/mapping/Regions.java +++ b/src/main/java/org/springframework/data/gemfire/mapping/Regions.java @@ -65,7 +65,8 @@ public class Regions implements Iterable> { * Returns the {@link Region} the given type is mapped to. Will try to find * a {@link Region} with the simple class name in case no mapping * information is found. - * + * + * @param the Region value class type. * @param type must not be {@literal null}. * @return the {@link Region} the given type is mapped to. */ @@ -81,6 +82,8 @@ public class Regions implements Iterable> { /** * Returns the {@link Region} with the given name or path. * + * @param the Region key class type. + * @param the Region value class type. * @param namePath must not be {@literal null}, and either identifies the Region by name or the fully-qualified path. * @return the {@link Region} with the given name or path. */ diff --git a/src/main/java/org/springframework/data/gemfire/repository/Wrapper.java b/src/main/java/org/springframework/data/gemfire/repository/Wrapper.java index 97a664a6..31cb06d5 100644 --- a/src/main/java/org/springframework/data/gemfire/repository/Wrapper.java +++ b/src/main/java/org/springframework/data/gemfire/repository/Wrapper.java @@ -33,11 +33,10 @@ public final class Wrapper { /** * The entity to handle as well as the key. * - * @param entity + * @param entity the application domain object/entity to wrap. * @param key must not be {@literal null}. */ public Wrapper(T entity, KEY key) { - Assert.notNull(key); this.entity = entity; @@ -64,8 +63,7 @@ public final class Wrapper { */ @Override public boolean equals(Object value) { - - if (this == value) { + if (value == this) { return true; } @@ -75,7 +73,7 @@ public final class Wrapper { Wrapper that = (Wrapper) value; - return this.key.equals(that.key) && ObjectUtils.nullSafeEquals(this.entity, that.entity); + return (this.key.equals(that.key) && ObjectUtils.nullSafeEquals(this.entity, that.entity)); } /* @@ -84,7 +82,6 @@ public final class Wrapper { */ @Override public int hashCode() { - int result = 17; result += 31 * key.hashCode(); @@ -92,4 +89,14 @@ public final class Wrapper { return result; } + + /* + * (non-Javadoc) + * @see java.lang.Object#toString() + */ + @Override + public String toString() { + return ObjectUtils.nullSafeToString(getEntity()); + } + } diff --git a/src/main/java/org/springframework/data/gemfire/repository/config/EnableGemfireRepositories.java b/src/main/java/org/springframework/data/gemfire/repository/config/EnableGemfireRepositories.java index d0ea08b8..63d09589 100644 --- a/src/main/java/org/springframework/data/gemfire/repository/config/EnableGemfireRepositories.java +++ b/src/main/java/org/springframework/data/gemfire/repository/config/EnableGemfireRepositories.java @@ -43,15 +43,21 @@ import org.springframework.data.repository.query.QueryLookupStrategy.Key; public @interface EnableGemfireRepositories { /** - * Alias for the {@link #basePackages()} attribute. Allows for more concise annotation declarations e.g.: + * Alias for the {@link #basePackages()} attribute. Allows for more concise annotation declarations, e.g. * {@code @EnableGemfireRepositories("org.my.pkg")} instead of * {@code @EnableGemfireRepositories(basePackages="org.my.pkg")}. + * + * @return a String array specifying the packages to search for GemFire Repositories. + * @see #basePackages() */ String[] value() default {}; /** * Base packages to scan for annotated components. {@link #value()} is an alias for (and mutually exclusive with) this * attribute. Use {@link #basePackageClasses()} for a type-safe alternative to String-based package names. + * + * @return a String array specifying the packages to search for GemFire Repositories. + * @see #value() */ String[] basePackages() default {}; @@ -59,17 +65,23 @@ public @interface EnableGemfireRepositories { * Type-safe alternative to {@link #basePackages()} for specifying the packages to scan for annotated components. The * package of each class specified will be scanned. Consider creating a special no-op marker class or interface in * each package that serves no purpose other than being referenced by this attribute. + * + * @return an array of classes used to determine the packages to scan for GemFire Repositories. */ Class[] basePackageClasses() default {}; /** * Specifies which types are eligible for component scanning. Further narrows the set of candidate components from * everything in {@link #basePackages()} to everything in the base packages that matches the given filter or filters. + * + * @return an array of Filters used to specify Repositories to be included during the component scan. */ Filter[] includeFilters() default {}; /** * Specifies which types are not eligible for component scanning. + * + * @return an array of Filters used to specify Repositories to be excluded during the component scan. */ Filter[] excludeFilters() default {}; @@ -78,7 +90,8 @@ public @interface EnableGemfireRepositories { * for a repository named {@code PersonRepository} the corresponding implementation class will be looked up scanning * for {@code PersonRepositoryImpl}. * - * @return + * @return a String indicating the postfix to append to the Repository interface name when looking up the custom + * Repository implementing class. */ String repositoryImplementationPostfix() default "Impl"; @@ -86,7 +99,7 @@ public @interface EnableGemfireRepositories { * Configures the location of where to find the Spring Data named queries properties file. Will default to * {@code META-INFO/jpa-named-queries.properties}. * - * @return + * @return a String indicating the location of the name queries properties file. */ String namedQueriesLocation() default ""; @@ -94,7 +107,7 @@ public @interface EnableGemfireRepositories { * Returns the key of the {@link QueryLookupStrategy} to be used for lookup queries for query methods. Defaults to * {@link Key#CREATE_IF_NOT_FOUND}. * - * @return + * @return the Key used to determine the Query lookup and creation strategy. */ Key queryLookupStrategy() default Key.CREATE_IF_NOT_FOUND; @@ -102,16 +115,17 @@ public @interface EnableGemfireRepositories { * Returns the {@link FactoryBean} class to be used for each repository instance. Defaults to * {@link GemfireRepositoryFactoryBean}. * - * @return + * @return the {@link FactoryBean} class type used for each Repository interface. */ Class repositoryFactoryBeanClass() default GemfireRepositoryFactoryBean.class; - // Gemfire specific configuration /** * Configures the name of the {@link GemfireMappingContext} bean definition to be used to create repositories * discovered through this annotation. If not configured a default one will be created. * - * @return + * @return the bean name of the {@link org.springframework.data.mapping.context.MappingContext} used by the + * Repository to map entities to the underlying data store. */ String mappingContextRef() default ""; + } diff --git a/src/main/java/org/springframework/data/gemfire/repository/query/GemfireRepositoryQuery.java b/src/main/java/org/springframework/data/gemfire/repository/query/GemfireRepositoryQuery.java index b70e8e95..e7e065ed 100644 --- a/src/main/java/org/springframework/data/gemfire/repository/query/GemfireRepositoryQuery.java +++ b/src/main/java/org/springframework/data/gemfire/repository/query/GemfireRepositoryQuery.java @@ -21,7 +21,7 @@ import org.springframework.util.Assert; /** * Base class for GemFire specific {@link RepositoryQuery} implementations. - *

+ *

* @author Oliver Gierke * @author David Turanski * @author John Blum diff --git a/src/main/java/org/springframework/data/gemfire/repository/query/StringBasedGemfireRepositoryQuery.java b/src/main/java/org/springframework/data/gemfire/repository/query/StringBasedGemfireRepositoryQuery.java index 26afa5e7..a69b6abb 100644 --- a/src/main/java/org/springframework/data/gemfire/repository/query/StringBasedGemfireRepositoryQuery.java +++ b/src/main/java/org/springframework/data/gemfire/repository/query/StringBasedGemfireRepositoryQuery.java @@ -31,7 +31,7 @@ import com.gemstone.gemfire.cache.query.internal.ResultsBag; /** * {@link GemfireRepositoryQuery} using plain {@link String} based OQL queries. - *

+ *

* @author Oliver Gierke * @author David Turanski * @author John Blum diff --git a/src/main/java/org/springframework/data/gemfire/repository/support/GemfireRepositoryFactory.java b/src/main/java/org/springframework/data/gemfire/repository/support/GemfireRepositoryFactory.java index 31d676c8..8cd664f7 100644 --- a/src/main/java/org/springframework/data/gemfire/repository/support/GemfireRepositoryFactory.java +++ b/src/main/java/org/springframework/data/gemfire/repository/support/GemfireRepositoryFactory.java @@ -57,7 +57,8 @@ public class GemfireRepositoryFactory extends RepositoryFactorySupport { * Creates a new {@link GemfireRepositoryFactory}. * * @param regions must not be {@literal null}. - * @param context + * @param context the {@link MappingContext} used by the constructed Repository for mapping entities + * to the underlying data store. */ public GemfireRepositoryFactory(Iterable> regions, MappingContext, GemfirePersistentProperty> context) { diff --git a/src/main/java/org/springframework/data/gemfire/support/GemfireCacheManager.java b/src/main/java/org/springframework/data/gemfire/support/GemfireCacheManager.java index e9378961..64699ba3 100644 --- a/src/main/java/org/springframework/data/gemfire/support/GemfireCacheManager.java +++ b/src/main/java/org/springframework/data/gemfire/support/GemfireCacheManager.java @@ -33,29 +33,52 @@ import com.gemstone.gemfire.cache.Region; * * @author Costin Leau * @author David Turanski + * @author John Blum + * @see org.springframework.cache.Cache + * @see org.springframework.cache.CacheManager + * @see org.springframework.cache.support.AbstractCacheManager + * @see com.gemstone.gemfire.cache.Cache + * @see com.gemstone.gemfire.cache.Region */ +@SuppressWarnings("unused") public class GemfireCacheManager extends AbstractCacheManager { private com.gemstone.gemfire.cache.Cache gemfireCache; + private Set> regions; + /** + * Loads the GemFire Cache Regions managed by this CacheManager. + * + * @return a Collection of GemFire Cache Regions (caches) to be managed by this SDG CacheManager. + * @see org.springframework.cache.Cache + * @see com.gemstone.gemfire.cache.Cache#rootRegions() + */ @Override protected Collection loadCaches() { - if (regions == null) { - Assert.notNull(gemfireCache, "a backing GemFire cache is required"); - Assert.isTrue(!gemfireCache.isClosed(), "the GemFire cache is closed; an open instance is required"); + Assert.state(gemfireCache != null, "A backing GemFire Cache is required."); + Assert.state(!gemfireCache.isClosed(), "The GemFire Cache is closed; an open instance is required."); + regions = gemfireCache.rootRegions(); } - + Collection caches = new LinkedHashSet(regions.size()); + for (Region region: this.regions) { caches.add(new GemfireCache(region)); } - + return caches; } + /** + * Gets a Cache (GemFire Cache Region) by name. + * + * @param name a String indicating the name of the Cache to get. + * @return a Cache with the given name. + * @see org.springframework.cache.Cache + */ @Override public Cache getCache(String name) { Cache cache = super.getCache(name); @@ -63,10 +86,10 @@ public class GemfireCacheManager extends AbstractCacheManager { if (cache == null) { // check the gemfire cache again // in case the cache was added at runtime + Region region = gemfireCache.getRegion(name); - Region reg = gemfireCache.getRegion(name); - if (reg != null) { - cache = new GemfireCache(reg); + if (region != null) { + cache = new GemfireCache(region); addCache(cache); } } @@ -77,17 +100,21 @@ public class GemfireCacheManager extends AbstractCacheManager { /** * Sets the GemFire Cache backing this {@link CacheManager}. * - * @param gemfireCache + * @param gemfireCache the GemFire Peer Cache instance. + * @see com.gemstone.gemfire.cache.Cache */ public void setCache(com.gemstone.gemfire.cache.Cache gemfireCache) { this.gemfireCache = gemfireCache; } /** - * Sets a set of regions to use (alternative to injecting the GemFire Cache) - * @param regions + * Sets the Regions to use (alternative to injecting the GemFire Cache). + * + * @param regions the Set of Regions (caches) managed by this CacheManager. + * @see com.gemstone.gemfire.cache.Region */ public void setRegions(Set> regions) { this.regions = regions; } -} \ No newline at end of file + +} diff --git a/src/main/java/org/springframework/data/gemfire/support/GemfireDaoSupport.java b/src/main/java/org/springframework/data/gemfire/support/GemfireDaoSupport.java index da06affb..1c5ee859 100644 --- a/src/main/java/org/springframework/data/gemfire/support/GemfireDaoSupport.java +++ b/src/main/java/org/springframework/data/gemfire/support/GemfireDaoSupport.java @@ -35,36 +35,31 @@ import com.gemstone.gemfire.cache.Region; * A custom GemfireTemplate instance can be used through overriding createGemfireTemplate. * * @author Costin Leau + * @author John Blum + * @see org.springframework.dao.support.DaoSupport */ public class GemfireDaoSupport extends DaoSupport { private GemfireOperations gemfireTemplate; /** - * Sets the GemFire Region to be used by this DAO. - * Will automatically create a GemfireTemplate for the given Region. + * Sets the GemFire Cache Region to be used by this DAO. Will automatically create + * an instance of the GemfireTemplate for the given Region. * - * @param region + * @param region the GemFire Cache Region upon which this DAO operates. + * @see com.gemstone.gemfire.cache.Region + * @see #createGemfireTemplate(com.gemstone.gemfire.cache.Region) */ public void setRegion(Region region) { this.gemfireTemplate = createGemfireTemplate(region); } /** - * Creates a GemfireTemplate for the given Region. - *

Can be overridden in subclasses to provide a GemfireTemplate instance - * with different configuration, or a custom GemfireTemplate subclass. - * @param region the GemFire Region to create a GemfireTemplate for - * @return the new GemfireTemplate instance - * @see #setRegion - */ - protected GemfireOperations createGemfireTemplate(Region region) { - return new GemfireTemplate(region); - } - - /** - * Set the GemfireTemplate for this DAO explicitly, - * as an alternative to specifying a GemFire {@link Region}. + * Set the GemfireTemplate for this DAO explicitly as an alternative to specifying a GemFire Cache {@link Region}. + * + * @param gemfireTemplate the GemfireTemplate to be use by this DAO. + * @see org.springframework.data.gemfire.GemfireOperations + * @see org.springframework.data.gemfire.GemfireTemplate * @see #setRegion */ public final void setGemfireTemplate(GemfireOperations gemfireTemplate) { @@ -72,15 +67,36 @@ public class GemfireDaoSupport extends DaoSupport { } /** - * Return the GemfireTemplate for this DAO, pre-initialized - * with the Region or set explicitly. + * Returns the GemfireTemplate for this DAO, pre-initialized with the Region or set explicitly. + * + * @return an instance of the GemfireTemplate to perform data access operations on the GemFire Cache Region. + * @see org.springframework.data.gemfire.GemfireOperations + * @see org.springframework.data.gemfire.GemfireTemplate */ public final GemfireOperations getGemfireTemplate() { return gemfireTemplate; } + /** + * Creates an instance of the GemfireTemplate for the given GemFire Cache Region. + *

Can be overridden in subclasses to provide a GemfireTemplate instance with different configuration, + * or even a custom GemfireTemplate subclass. + * + * @param region the GemFire Cache Region for which the GemfireTemplate is created. + * @return a new GemfireTemplate instance configured with the given GemFire Cache Region. + * @see com.gemstone.gemfire.cache.Region + * @see #setRegion + */ + protected GemfireOperations createGemfireTemplate(Region region) { + return new GemfireTemplate(region); + } + + /** + * Verifies that this DAO has been configured properly. + */ @Override protected final void checkDaoConfig() { - Assert.notNull(gemfireTemplate, "region or gemfireTemplate is required"); + Assert.state(gemfireTemplate != null, "A GemFire Cache Region or an instance of the GemfireTemplate is required."); } -} \ No newline at end of file + +} diff --git a/src/main/java/org/springframework/data/gemfire/wan/AsyncEventQueueFactoryBean.java b/src/main/java/org/springframework/data/gemfire/wan/AsyncEventQueueFactoryBean.java index ac23bc49..fdf0e2f2 100644 --- a/src/main/java/org/springframework/data/gemfire/wan/AsyncEventQueueFactoryBean.java +++ b/src/main/java/org/springframework/data/gemfire/wan/AsyncEventQueueFactoryBean.java @@ -180,43 +180,56 @@ public class AsyncEventQueueFactoryBean extends AbstractWANComponentFactoryBean< } /** - * @param asyncEventQueue the asyncEventQueue to set + * @param asyncEventQueue overrides Async Event Queue returned by this FactoryBean. */ public void setAsyncEventQueue(AsyncEventQueue asyncEventQueue) { this.asyncEventQueue = asyncEventQueue; } /** - * @param dispatcherThreads the dispatcherThreads to set + * Set the number of dispatcher threads used to process Region events from the associated Aysnc Event Queue (AEQ). + * + * @param dispatcherThreads an integer indicating the number of dispatcher threads used to process Region events + * from the associated queue. */ public void setDispatcherThreads(Integer dispatcherThreads) { this.dispatcherThreads = dispatcherThreads; } /** - * @param batchTimeInterval + * Set the Aysync Event Queue's (AEQ) interval between sending batches. + * + * @param batchTimeInterval an integer value indicating the maximum number of milliseconds that can elapse + * between sending batches. */ public void setBatchTimeInterval(Integer batchTimeInterval) { this.batchTimeInterval = batchTimeInterval; } /** - * - * @param batchConflationEnabled + * Enable or disable the Async Event Queue's (AEQ) should conflate messages. + * + * @param batchConflationEnabled a boolean value indicating whether to conflate queued events. */ public void setBatchConflationEnabled(Boolean batchConflationEnabled) { this.batchConflationEnabled = batchConflationEnabled; } /** - * @param diskSynchronous + * Set the Async Event Queue (AEQ) disk write synchronization policy. + * + * @param diskSynchronous a boolean value indicating whether disk writes are synchronous. */ public void setDiskSynchronous(Boolean diskSynchronous) { this.diskSynchronous = diskSynchronous; } /** - * @param orderPolicy + * Set the Async Event Queue (AEQ) ordering policy (e.g. KEY, PARTITION, THREAD). When dispatcher threads + * are greater than 1, the ordering policy configures the way in which multiple dispatcher threads + * process Region events from the queue. + * + * @param orderPolicy a String to indicate the AEQ order policy. */ public void setOrderPolicy(String orderPolicy) { this.orderPolicy = orderPolicy; diff --git a/src/main/java/org/springframework/data/gemfire/wan/GatewayReceiverFactoryBean.java b/src/main/java/org/springframework/data/gemfire/wan/GatewayReceiverFactoryBean.java index ab12bdec..ac39fb6e 100644 --- a/src/main/java/org/springframework/data/gemfire/wan/GatewayReceiverFactoryBean.java +++ b/src/main/java/org/springframework/data/gemfire/wan/GatewayReceiverFactoryBean.java @@ -47,8 +47,10 @@ public class GatewayReceiverFactoryBean extends AbstractWANComponentFactoryBean< private String bindAddress; /** - * - * @param cache + * Constructs an instance of the GatewayReceiverFactoryBean class for configuring an initializing + * a GemFire Gateway Receiver. + * + * @param cache a reference to the GemFire Cache used to setup the Gateway Receiver. */ public GatewayReceiverFactoryBean(Cache cache) { super(cache); diff --git a/src/test/java/org/springframework/data/gemfire/support/GemfireDaoSupportTests.java b/src/test/java/org/springframework/data/gemfire/support/GemfireDaoSupportTests.java index 2827fc79..88fe602a 100644 --- a/src/test/java/org/springframework/data/gemfire/support/GemfireDaoSupportTests.java +++ b/src/test/java/org/springframework/data/gemfire/support/GemfireDaoSupportTests.java @@ -15,45 +15,46 @@ */ package org.springframework.data.gemfire.support; -import java.util.ArrayList; -import java.util.List; +import static org.junit.Assert.assertEquals; +import static org.junit.Assert.assertNotNull; +import static org.junit.Assert.assertTrue; -import junit.framework.TestCase; +import java.util.concurrent.atomic.AtomicBoolean; +import org.junit.Test; import org.springframework.data.gemfire.GemfireOperations; import org.springframework.data.gemfire.GemfireTemplate; /** * @author Costin Leau - * + * @author John Blum */ -public class GemfireDaoSupportTests extends TestCase { +public class GemfireDaoSupportTests { + @Test @SuppressWarnings("rawtypes") public void testGemfireDaoSupportWithTemplate() throws Exception { - GemfireOperations template = new GemfireTemplate(); - final List test = new ArrayList(); + final AtomicBoolean flag = new AtomicBoolean(false); + GemfireDaoSupport dao = new GemfireDaoSupport() { - @SuppressWarnings("unchecked") protected void initDao() { - test.add("test"); + flag.set(true); } }; - dao.setGemfireTemplate(template); + + GemfireOperations expectedTemplate = new GemfireTemplate(); + + dao.setGemfireTemplate(expectedTemplate); dao.afterPropertiesSet(); + assertNotNull("template not created", dao.getGemfireTemplate()); - assertEquals("incorrect template", template, dao.getGemfireTemplate()); - assertEquals("initDao not called", test.size(), 1); + assertEquals("incorrect template", expectedTemplate, dao.getGemfireTemplate()); + assertTrue("initDao not called", flag.get()); } + @Test(expected = IllegalStateException.class) public void testInvalidDaoTemplate() throws Exception { - GemfireDaoSupport dao = new GemfireDaoSupport() { - }; - try { - dao.afterPropertiesSet(); - fail("expected exception"); - } catch (IllegalArgumentException iae) { - // okay - } + new GemfireDaoSupport().afterPropertiesSet(); } -} \ No newline at end of file + +}