From edc8d4c789c9db844d2abd59b4b09c5dee3d2a6f Mon Sep 17 00:00:00 2001 From: John Blum Date: Fri, 1 Apr 2022 12:40:57 -0700 Subject: [PATCH] Edit Javadoc in the ClientCacheApplication annotation. --- .../annotation/ClientCacheApplication.java | 188 +++++++++++------- 1 file changed, 114 insertions(+), 74 deletions(-) diff --git a/spring-data-geode/src/main/java/org/springframework/data/gemfire/config/annotation/ClientCacheApplication.java b/spring-data-geode/src/main/java/org/springframework/data/gemfire/config/annotation/ClientCacheApplication.java index 1d6fb1b3..b564e268 100644 --- a/spring-data-geode/src/main/java/org/springframework/data/gemfire/config/annotation/ClientCacheApplication.java +++ b/spring-data-geode/src/main/java/org/springframework/data/gemfire/config/annotation/ClientCacheApplication.java @@ -23,6 +23,7 @@ import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; +import org.apache.geode.cache.Region; import org.apache.geode.cache.client.AllConnectionsInUseException; import org.apache.geode.cache.client.ClientCache; import org.apache.geode.cache.client.Pool; @@ -37,10 +38,15 @@ import org.springframework.data.gemfire.GemfireUtils; import org.springframework.data.gemfire.support.GemfireBeanFactoryLocator; /** - * The {@link ClientCacheApplication} annotation enables a Spring Data GemFire/Geode based application to become - * a GemFire/Geode cache client (i.e. {@link ClientCache}). + * The {@link ClientCacheApplication} annotation enables a Spring Data for Apache Geode based application + * to become an Apache Geode cache client by creating a {@link ClientCache} instance. * * @author John Blum + * @see java.lang.annotation.Documented + * @see java.lang.annotation.Inherited + * @see java.lang.annotation.Retention + * @see java.lang.annotation.Target + * @see org.apache.geode.cache.Region * @see org.apache.geode.cache.client.ClientCache * @see org.apache.geode.cache.client.Pool * @see org.apache.geode.cache.client.PoolFactory @@ -63,7 +69,7 @@ import org.springframework.data.gemfire.support.GemfireBeanFactoryLocator; public @interface ClientCacheApplication { /** - * Indicates whether the "copy on read" is enabled for this cache. + * Configures cache {@literal copy-on-read} functionality, which copies the value when it is read from the cache. * * Defaults to {@literal false}. * @@ -72,7 +78,8 @@ public @interface ClientCacheApplication { boolean copyOnRead() default false; /** - * Configures the percentage of heap at or above which the cache is considered in danger of becoming inoperable. + * Configures the percentage of heap at or above which the cache is considered to be in danger + * of becoming inoperable. * * Defaults to {@link ResourceManager#DEFAULT_CRITICAL_PERCENTAGE}. * @@ -81,7 +88,8 @@ public @interface ClientCacheApplication { float criticalHeapPercentage() default ResourceManager.DEFAULT_CRITICAL_PERCENTAGE; /** - * Configures the percentage of off-heap at or above which the cache is considered in danger of becoming inoperable. + * Configures the percentage of off-heap at or above which the cache is considered to be in danger + * of becoming inoperable. * * Defaults to {@literal 0.0}. * @@ -91,19 +99,21 @@ public @interface ClientCacheApplication { float criticalOffHeapPercentage() default 0.0f; /** - * Used only for clients in a client/server installation. If set, this indicates that the client is durable - * and identifies the client. The ID is used by servers to reestablish any messaging that was interrupted - * by client downtime. + * Configures the ID for a durable client in a client/server topology. + * + * If set, the durable client ID indicates a client is durable so messages persist while the client is offline. + * The ID is used by servers to identify clients and reestablish any messaging that was interrupted by client + * downtime. * * Use {@literal spring.data.gemfire.cache.client.durable-client-id} property in {@literal application.properties}. */ String durableClientId() default ""; /** - * Used only for clients in a client/server installation. Number of seconds this client can remain disconnected - * from its server and have the server continue to accumulate durable events for it. + * Configures the number of seconds that a durable client can remain disconnected from a server cluster + * and for the servers to continue to accumulate (durable) events for the client while offline. * - * Defaults to {@literal 300} seconds, or 5 minutes. + * Defaults to {@literal 300 seconds}, or {@literal 5 minutes}. * * Use {@literal spring.data.gemfire.cache.client.durable-client-timeout} property * in {@literal application.properties}. @@ -111,8 +121,8 @@ public @interface ClientCacheApplication { int durableClientTimeout() default 300; /** - * Configures the percentage of heap at or above which the eviction should begin on Regions configured - * for HeapLRU eviction. + * Configures the percentage of heap at or above which eviction should begin on Regions configured + * for {@literal Heap LRU eviction}. * * Defaults to {@link ResourceManager#DEFAULT_EVICTION_PERCENTAGE}. * @@ -121,8 +131,8 @@ public @interface ClientCacheApplication { float evictionHeapPercentage() default ResourceManager.DEFAULT_EVICTION_PERCENTAGE; /** - * Configures the percentage of off-heap at or above which the eviction should begin on Regions configured - * for HeapLRU eviction. + * Configures the percentage of off-heap at or above which eviction should begin on Regions configured + * for {@literal Heap LRU eviction}. * * Defaults to {@literal 0.0}. * @@ -132,27 +142,29 @@ public @interface ClientCacheApplication { float evictionOffHeapPercentage() default 0.0f; /** - * Configures the free connection timeout for this pool. + * Configures the free connection timeout for the {@literal DEFAULT} {@link Pool}. * * Defaults to {@link PoolFactory#DEFAULT_FREE_CONNECTION_TIMEOUT}. * * Use either the {@literal spring.data.gemfire.pool.default.free-connection-timeout} property - * or the {@literal spring.data.gemfire.pool.free-connection-timeout} property in {@literal application.properties}. + * or the {@literal spring.data.gemfire.pool.free-connection-timeout} property + * in {@literal application.properties}. */ int freeConnectionTimeout() default PoolFactory.DEFAULT_FREE_CONNECTION_TIMEOUT; /** - * Configures the amount of time a connection can be idle before expiring the connection. + * Configures the amount of time that a connection can remain idle before expiring the connection. * * Defaults to {@link PoolFactory#DEFAULT_IDLE_TIMEOUT}. * * Use either the {@literal spring.data.gemfire.pool.default.idle-timeout} property - * or the {@literal spring.data.gemfire.pool.idle-timeout} property in {@literal application.properties}. + * or the {@literal spring.data.gemfire.pool.idle-timeout} property + * in {@literal application.properties}. */ long idleTimeout() default PoolFactory.DEFAULT_IDLE_TIMEOUT; /** - * Configures whether to keep the client queues alive on the server when the client is disconnected + * Configures whether to keep the client event queues alive on the server when the client is disconnected. * * Defaults to {@literal false}. * @@ -161,7 +173,7 @@ public @interface ClientCacheApplication { boolean keepAlive() default false; /** - * Configures the load conditioning interval for this pool. + * Configures the load conditioning interval for the {@literal DEFAULT} {@link Pool}. * * Defaults to {@link PoolFactory#DEFAULT_LOAD_CONDITIONING_INTERVAL}. * @@ -172,45 +184,51 @@ public @interface ClientCacheApplication { int loadConditioningInterval() default PoolFactory.DEFAULT_LOAD_CONDITIONING_INTERVAL; /** - * Configures the GemFire {@link org.apache.geode.distributed.Locator Locators} to which - * this cache client will connect. + * Configures the {@link org.apache.geode.distributed.Locator Locators} to which this cache client will connect. * * Use either the {@literal spring.data.gemfire.pool.default.locators} property - * or the {@literal spring.data.gemfire.pool.locators} property in {@literal application.properties}. + * or the {@literal spring.data.gemfire.pool.locators} property + * in {@literal application.properties}. */ Locator[] locators() default {}; /** - * Configures the log level used to output log messages at GemFire cache runtime. + * Configures the {@literal log-level} used to output log messages at runtime. * * Defaults to {@literal config}. * * Use {@literal spring.data.gemfire.cache.log-level} property in {@literal application.properties}. + * @deprecated Apache Geode cache logging can only be configured using a logging provider (e.g. Log4j). */ + @Deprecated String logLevel() default ClientCacheConfiguration.DEFAULT_LOG_LEVEL; /** - * Configures the max number of client to server connections that the pool will create. + * Configures the maximum number of connections between the client and server that the {@literal DEFAULT} + * {@link Pool} will create. * * Defaults to {@link PoolFactory#DEFAULT_MAX_CONNECTIONS}. * * Use either the {@literal spring.data.gemfire.pool.default.max-connections} property - * or the {@literal spring.data.gemfire.pool.max-connections} property in {@literal application.properties}. + * or the {@literal spring.data.gemfire.pool.max-connections} property + * in {@literal application.properties}. */ int maxConnections() default PoolFactory.DEFAULT_MAX_CONNECTIONS; /** - * Configures the minimum number of connections to keep available at all times. + * Configures the minimum number of connections between the client and server to keep alive and available + * at all times. * * Defaults to {@link PoolFactory#DEFAULT_MIN_CONNECTIONS}. * * Use either the {@literal spring.data.gemfire.pool.default.min-connections} property - * or the {@literal spring.data.gemfire.pool.min-connections} property in {@literal application.properties}. + * or the {@literal spring.data.gemfire.pool.min-connections} property + * in {@literal application.properties}. */ int minConnections() default PoolFactory.DEFAULT_MIN_CONNECTIONS; /** - * If set to true then the created pool can be used by multiple users. + * If set to {@literal true} then the {@literal DEFAULT} {@link Pool} can be used by multiple users. * * Defaults to {@link PoolFactory#DEFAULT_MULTIUSER_AUTHENTICATION}. * @@ -221,33 +239,37 @@ public @interface ClientCacheApplication { boolean multiUserAuthentication() default PoolFactory.DEFAULT_MULTIUSER_AUTHENTICATION; /** - * Configures the name of this GemFire member in the cluster (distributed system). + * Configures the name of {@literal this} Apache Geode member in the cluster (distributed system). * * Defaults to {@literal SpringBasedClientCacheApplication}. * - * Use either the {@literal spring.data.gemfire.name} or the {@literal spring.data.gemfire.cache.name} property + * Use either {@literal spring.data.gemfire.name} or the {@literal spring.data.gemfire.cache.name} property * in {@literal application.properties}. */ String name() default ClientCacheConfiguration.DEFAULT_NAME; /** - * Configures how often to ping servers to verify that they are still alive. + * Configures how often to ping servers and verify that the servers are still alive and responsive. * * Defaults to {@link PoolFactory#DEFAULT_PING_INTERVAL}. * * Use either the {@literal spring.data.gemfire.pool.default.ping-interval} property - * or the {@literal spring.data.gemfire.pool.ping-interval} property in {@literal application.properties}. + * or the {@literal spring.data.gemfire.pool.ping-interval} property + * in {@literal application.properties}. */ long pingInterval() default PoolFactory.DEFAULT_PING_INTERVAL; /** - * By default {@code prSingleHopEnabled} is {@literal true} in which case the client is aware of the location - * of partitions on servers hosting Regions with {@link org.apache.geode.cache.DataPolicy#PARTITION}. + * Configures {@code prSingleHopEnabled} functionality for the {@literal DEFAULT} {@link Pool}. + * + * When {@literal true} the client will be aware of the location of all partitions on servers + * hosting {@link org.apache.geode.cache.DataPolicy#PARTITION} {@link Region Regions}. * * Defaults to {@link PoolFactory#DEFAULT_PR_SINGLE_HOP_ENABLED}. * * Use either the {@literal spring.data.gemfire.pool.default.pr-single-hop-enabled} property - * or the {@literal spring.data.gemfire.pool.pr-single-hop-enabled} property in {@literal application.properties}. + * or the {@literal spring.data.gemfire.pool.pr-single-hop-enabled} property + * in {@literal application.properties}. */ boolean prSingleHopEnabled() default PoolFactory.DEFAULT_PR_SINGLE_HOP_ENABLED; @@ -258,39 +280,44 @@ public @interface ClientCacheApplication { * Defaults to {@link PoolFactory#DEFAULT_READ_TIMEOUT}. * * Use either the {@literal spring.data.gemfire.pool.default.read-timeout} property - * or the {@literal spring.data.gemfire.pool.read-timeout} property in {@literal application.properties}. + * or the {@literal spring.data.gemfire.pool.read-timeout} property + * in {@literal application.properties}. */ int readTimeout() default PoolFactory.DEFAULT_READ_TIMEOUT; /** - * Notifies the server that this durable client is ready to receive updates. + * Configures whether to notify servers (cluster) at runtime after startup that this durable client is ready + * to receive updates and events. * * Defaults to {@literal false}. * * Use either the {@literal spring.data.gemfire.pool.default.ready-for-events} property - * or the {@literal spring.data.gemfire.pool.ready-for-events} property in {@literal application.properties}. + * or the {@literal spring.data.gemfire.pool.ready-for-events} property + * in {@literal application.properties}. */ boolean readyForEvents() default false; /** - * Configures the number of times to retry a request after timeout/exception. + * Configures the number of times to retry a request after timeout or an {@link Exception} occurs while performing + * the cache operation between the client and server. * * Defaults to {@link PoolFactory#DEFAULT_RETRY_ATTEMPTS}. * * Use either the {@literal spring.data.gemfire.pool.default.retry-attempts} property - * or the {@literal spring.data.gemfire.pool.retry-attempts} property in {@literal application.properties}. + * or the {@literal spring.data.gemfire.pool.retry-attempts} property + * in {@literal application.properties}. */ int retryAttempts() default PoolFactory.DEFAULT_RETRY_ATTEMPTS; /** * Configures the server connection timeout for the {@literal DEFAULT} {@literal Pool}. * - * If the pool has a max connections setting, operations will block if there is no free connection for a specific - * server. The server connection timeout specifies how long those operations will block waiting for a free - * connection for a specific server before receiving an {@link AllConnectionsInUseException}. If max connections - * is not set this setting has no effect. This setting differs from {@link #freeConnectionTimeout()}, which sets - * the wait time for any server connection in the pool, whereas this setting sets the wait time for a free - * connection to a specific server. + * If the {@link Pool} has a max connections setting, operations will block if there are no free connections to + * a specific server. The server connection timeout specifies how long those operations will block waiting for + * a free connection tro a specific server before receiving an {@link AllConnectionsInUseException}. If max + * connections is not set then this setting has no effect. This setting differs from {@link #freeConnectionTimeout()}, + * which sets the wait time for any server connection in the {@literal DEFAULT} {@link Pool}, whereas this setting + * sets the wait time for a free connection to a specific server. * * Defaults to {@link PoolFactory#DEFAULT_SERVER_CONNECTION_TIMEOUT}. * @@ -301,51 +328,58 @@ public @interface ClientCacheApplication { int serverConnectionTimeout() default PoolFactory.DEFAULT_SERVER_CONNECTION_TIMEOUT; /** - * Configures the group that all servers in which this pool connects to must belong to. + * Configures the {@link String name} of the group that all servers in which the {@literal DEFAULT} {@link Pool} + * connects to must belong to. * * Defaults to {@link PoolFactory#DEFAULT_SERVER_GROUP}. * * Use either the {@literal spring.data.gemfire.pool.default.server-group} property - * or the {@literal spring.data.gemfire.pool.server-group} property in {@literal application.properties}. + * or the {@literal spring.data.gemfire.pool.server-group} property + * in {@literal application.properties}. */ String serverGroup() default PoolFactory.DEFAULT_SERVER_GROUP; /** - * Configures the GemFire {@link org.apache.geode.cache.server.CacheServer CacheServers} to which - * this cache client will connect. + * Configures the {@link org.apache.geode.cache.server.CacheServer CacheServers} to which this cache client + * will connect. * * Use either the {@literal spring.data.gemfire.pool.default.servers} property - * or the {@literal spring.data.gemfire.pool.servers} property in {@literal application.properties}. + * or the {@literal spring.data.gemfire.pool.servers} property + * in {@literal application.properties}. */ Server[] servers() default {}; /** - * Configures the socket buffer size for each connection made in this pool. + * Configures the {@link java.net.Socket} buffer size used for each connection made in + * the {@literal DEFAULT} {@link Pool}. * * Defaults to {@link PoolFactory#DEFAULT_SOCKET_BUFFER_SIZE}. * * Use either the {@literal spring.data.gemfire.pool.default.socket-buffer-size} property - * or the {@literal spring.data.gemfire.pool.socket-buffer-size} property in {@literal application.properties}. + * or the {@literal spring.data.gemfire.pool.socket-buffer-size} property + * in {@literal application.properties}. */ int socketBufferSize() default PoolFactory.DEFAULT_SOCKET_BUFFER_SIZE; /** - * Configures the {@link Integer socket connect timeout} for the {@literal DEFAULT} {@link Pool}. + * Configures the {@link java.net.Socket} connect timeout used by the {@literal DEFAULT} {@link Pool}. * - * The number of milliseconds specified as socket timeout when the client connects to the servers/locators. - * A timeout of zero is interpreted as an infinite timeout. The connection will then block until established - * or an error occurs. + * Configures the number of milliseconds used as the {@link java.net.Socket} timeout when the client connects to + * the servers and Locators in the cluster. A timeout of zero is interpreted as an infinite timeout. The connection + * will then block until established or an error occurs. * * Defaults to {@link PoolFactory#DEFAULT_SOCKET_CONNECT_TIMEOUT}. * * Use either the {@literal spring.data.gemfire.pool.default.socket-connect-timeout} property - * or the {@literal spring.data.gemfire.pool.socket-connect-timeout} property in {@literal application.properties}. + * or the {@literal spring.data.gemfire.pool.socket-connect-timeout} property + * in {@literal application.properties}. */ int socketConnectTimeout() default PoolFactory.DEFAULT_SOCKET_CONNECT_TIMEOUT; /** * Configures the {@link SocketFactory} {@link String bean name} used by the {@literal DEFAULT} {@link Pool} - * to create connections to both Locators (if configured using {@link #locators()}) and Servers. + * to create {@link java.net.Socket} connections to both Locators (if configured using {@link #locators()}) + * and Servers in the Apache Geodce cluster. * * Defaults to unset. * @@ -361,13 +395,14 @@ public @interface ClientCacheApplication { * Defaults to {@link PoolFactory#DEFAULT_STATISTIC_INTERVAL}. * * Use either the {@literal spring.data.gemfire.pool.default.statistic-interval} property - * or the {@literal spring.data.gemfire.pool.statistic-interval} property in {@literal application.properties}. + * or the {@literal spring.data.gemfire.pool.statistic-interval} property + * in {@literal application.properties}. */ int statisticInterval() default PoolFactory.DEFAULT_STATISTIC_INTERVAL; /** - * Configures the interval in milliseconds to wait before sending acknowledgements to the cache server - * for events received from the server subscriptions. + * Configures the interval in milliseconds to wait before sending acknowledgements from the client to the server + * for events received from server subscriptions. * * Defaults to {@link PoolFactory#DEFAULT_SUBSCRIPTION_ACK_INTERVAL}. * @@ -378,18 +413,20 @@ public @interface ClientCacheApplication { int subscriptionAckInterval() default PoolFactory.DEFAULT_SUBSCRIPTION_ACK_INTERVAL; /** - * If set to true then the created pool will have server-to-client subscriptions enabled. + * Configures server-to-client subscriptions when set to {@literal true} (enabled) + * in the {@literal DEFAULT} {@link Pool}. * * Defaults to {@link PoolFactory#DEFAULT_SUBSCRIPTION_ENABLED}. * * Use either the {@literal spring.data.gemfire.pool.default.subscription-enabled} property - * or the {@literal spring.data.gemfire.pool.subscription-enabled} property in {@literal application.properties}. + * or the {@literal spring.data.gemfire.pool.subscription-enabled} property + * in {@literal application.properties}. */ boolean subscriptionEnabled() default PoolFactory.DEFAULT_SUBSCRIPTION_ENABLED; /** - * Configures the messageTrackingTimeout attribute which is the time-to-live period, in milliseconds, - * for subscription events the client has received from the server. + * Configures the message tracking timeout attribute of the {@literal DEFAULT} {@link Pool}, which is + * the time-to-live period in milliseconds for subscription events the client has received from the server. * * Defaults to {@link PoolFactory#DEFAULT_SUBSCRIPTION_MESSAGE_TRACKING_TIMEOUT}. * @@ -400,30 +437,33 @@ public @interface ClientCacheApplication { int subscriptionMessageTrackingTimeout() default PoolFactory.DEFAULT_SUBSCRIPTION_MESSAGE_TRACKING_TIMEOUT; /** - * Configures the redundancy level for this pools server-to-client subscriptions. + * Configures the redundancy-level for the {@literal DEFAULT} {@link Pool}'s server-to-client subscriptions. * * Defaults to {@link PoolFactory#DEFAULT_SUBSCRIPTION_REDUNDANCY}. * * Use either the {@literal spring.data.gemfire.pool.default.subscription-redundancy} property - * or the {@literal spring.data.gemfire.pool.subscription-redundancy} property in {@literal application.properties}. + * or the {@literal spring.data.gemfire.pool.subscription-redundancy} property + * in {@literal application.properties}. */ int subscriptionRedundancy() default PoolFactory.DEFAULT_SUBSCRIPTION_REDUNDANCY; /** - * Configures the thread local connections policy for this pool. + * Configures the {@link ThreadLocal} connection policy for the {@literal DEFAULT} {@link Pool}. * * Defaults to {@link PoolFactory#DEFAULT_THREAD_LOCAL_CONNECTIONS}. * * Use either the {@literal spring.data.gemfire.pool.default.thread-local-connections} property * or the {@literal spring.data.gemfire.pool.thread-local-connections} property * in {@literal application.properties}. + * @deprecated */ + @Deprecated boolean threadLocalConnections() default PoolFactory.DEFAULT_THREAD_LOCAL_CONNECTIONS; /** - * Determines whether the {@link GemfireBeanFactoryLocator} should be enabled to lookup - * the Spring {@link BeanFactory} to auto-wire and configure/initialize GemFire components - * created in a non-Spring managed, GemFire context. + * Configures whether the {@link GemfireBeanFactoryLocator} should be enabled to lookup the Spring + * {@link BeanFactory} to auto-wire, configure and initialize Apache Geode components created in + * a non-Spring managed, Apache Geode context (for example: {@literal cache.xml}). * * Defaults to {@literal false}. *