You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@geode.apache.org by rv...@apache.org on 2015/04/28 23:40:22 UTC
[17/51] [partial] incubator-geode git commit: Init
http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/19459053/gemfire-core/src/main/java/com/gemstone/gemfire/cache/client/ClientCacheFactory.java
----------------------------------------------------------------------
diff --git a/gemfire-core/src/main/java/com/gemstone/gemfire/cache/client/ClientCacheFactory.java b/gemfire-core/src/main/java/com/gemstone/gemfire/cache/client/ClientCacheFactory.java
new file mode 100644
index 0000000..48bc074
--- /dev/null
+++ b/gemfire-core/src/main/java/com/gemstone/gemfire/cache/client/ClientCacheFactory.java
@@ -0,0 +1,680 @@
+/*=========================================================================
+ * Copyright (c) 2002-2014 Pivotal Software, Inc. All Rights Reserved.
+ * This product is protected by U.S. and international copyright
+ * and intellectual property laws. Pivotal products are covered by
+ * more patents listed at http://www.pivotal.io/patents.
+ *========================================================================
+ */
+
+package com.gemstone.gemfire.cache.client;
+
+import java.util.Properties;
+
+import com.gemstone.gemfire.cache.CacheClosedException;
+import com.gemstone.gemfire.cache.Region;
+import com.gemstone.gemfire.cache.server.CacheServer;
+import com.gemstone.gemfire.distributed.DistributedSystem;
+import com.gemstone.gemfire.internal.GemFireVersion;
+import com.gemstone.gemfire.internal.cache.CacheConfig;
+import com.gemstone.gemfire.internal.cache.GemFireCacheImpl;
+import com.gemstone.gemfire.internal.i18n.LocalizedStrings;
+import com.gemstone.gemfire.internal.jndi.JNDIInvoker;
+import com.gemstone.gemfire.pdx.PdxSerializer;
+import com.gemstone.gemfire.pdx.PdxInstance;
+
+/**
+Factory class used to create the singleton {@link ClientCache client cache} and connect to one or more GemFire Cache Servers. If the application wants to connect to GemFire as a peer it should use {@link com.gemstone.gemfire.cache.CacheFactory} instead.
+<p> Once the factory has been configured using its set* methods you produce a {@link ClientCache} by calling the {@link #create} method.
+The
+<a href="../distribution/DistributedSystem.html#cache-xml-file">"cache-xml-file"</a>
+property can be used to specify a cache.xml file to initialize the cache with.
+The contents of this file must comply with the
+ <code>"doc-files/cache8_0.dtd"</code> file and the top level element must be a <code>client-cache</code> element.
+<p> Client connections are managed through connection {@link Pool pools}. ClientCacheFactory creates a single pool to use by default on the cache it creates. ClientCacheFactory can also be used to configure the default connection pool using its <code>setPool*</code> and <code>addPool*</code> methods. In most cases, the defaults used by this implementation will suffice. For the default pool attributes see {@link PoolFactory}.
+If no pool is configured and a pool was not declared in cache.xml or created using {@link PoolManager} then a default one will be created that connects to a server on the default cache server port and local host. If multiple pools are declared in cache.xml or created by the PoolFactory then no default pool will exist and <code>ClientRegionFactory.setPoolName</code> will need to be called on each region created.
+<p>
+To get the existing unclosed singleton client cache instance call {@link #getAnyInstance}.
+<p>
+The following examples illustrate bootstrapping the client cache using region shortcuts:
+<p>
+Example 1: Connect to a CacheServer on the default host and port and access a region "customers"
+<PRE>
+ ClientCache c = new ClientCacheFactory().create();
+ Region r = c.createClientRegionFactory(PROXY).create("customers");
+ // The PROXY shortcut tells GemFire to route all requests to the servers
+ //. i.e. there is no local caching
+</PRE>
+Example 2: Connect using the GemFire locator and create a local LRU cache
+<PRE>
+ ClientCache c = new ClientCacheFactory()
+ .addPoolLocator(host, port)
+ .create();
+ Region r = c.createClientRegionFactory(CACHING_PROXY_HEAP_LRU)
+ .create("customers");
+ // The local LRU "customers" data region will automatically start evicting, by default, at 80% heap utilization threshold
+</PRE>
+Example 3: Access the query service
+<PRE>
+ QueryService qs = new ClientCacheFactory().create().getQueryService();
+</PRE>
+Example 4: Construct the client cache region declaratively in cache.xml
+<PRE>
+ <!DOCTYPE client-cache PUBLIC
+ "-//GemStone Systems, Inc.//GemFire Declarative Caching 6.5//EN"
+ "http://www.gemstone.com/dtd/cache8_0.dtd">
+ <client-cache>
+ <pool name="myPool">
+ <locator host="hostName" port="10334"/>
+ </pool>
+ <region name="myRegion" refid="PROXY"/>
+ <!-- you can override or add to the PROXY attributes by adding
+ a region-attributes sub element here -->
+ </client-cache>
+</PRE>
+Now, create the cache telling it to read your cache.xml file:
+<PRE>
+ ClientCache c = new ClientCacheFactory()
+ .set("cache-xml-file", "myCache.xml")
+ .create();
+ Region r = c.getRegion("myRegion");
+</PRE>
+
+<p> For a complete list of all client region shortcuts see {@link ClientRegionShortcut}.
+Applications that need to explicitly control the individual region attributes can do this declaratively in XML or using API.
+<p>
+Example 5: Define custom region attributes for persistence in XML and create region using API.
+ Define new region attributes with ID "MYAPP_CACHING_PROXY_MEM_LRU" that overrides the
+ "CACHING_PROXY" shortcut
+<PRE>
+ <!DOCTYPE client-cache PUBLIC
+ "-//GemStone Systems, Inc.//GemFire Declarative Caching 8.0//EN"
+ "http://www.gemstone.com/dtd/cache8_0.dtd">
+ <client-cache>
+ <!-- now create a named region attributes that uses the CACHING_PROXY shortcut
+ and adds a memory LRU limited to 900 megabytes -->
+ <region-attributes id="MYAPP_CACHING_PROXY_MEM_LRU" refid="CACHING_PROXY" >
+ <lru-memory-size maximum="900"/>
+ </region-attributes>
+ </client-cache>
+</PRE>
+Now, create the data region in the client cache using this new attributes ID.
+<PRE>
+ ClientCache c = new ClientCacheFactory()
+ .set("cache-xml-file", "myCache.xml")
+ .addPoolLocator(host, port)
+ .create();
+ Region r = c.createClientRegionFactory("MYAPP_CACHING_PROXY_MEM_LRU").create("customers");
+</PRE>
+ * @since 6.5
+ * @author darrel
+ */
+public class ClientCacheFactory {
+
+ private PoolFactory pf;
+
+ private final Properties dsProps;
+
+ private final CacheConfig cacheConfig = new CacheConfig();
+
+ /**
+ * Creates a new client cache factory.
+ */
+ public ClientCacheFactory() {
+ this.dsProps = new Properties();
+ }
+ /**
+ * Create a new client cache factory given the initial gemfire properties.
+ * @param props The initial gemfire properties to be used.
+ * These properties can be overridden using the {@link #set} method
+ * For a full list of valid gemfire properties see {@link com.gemstone.gemfire.distributed.DistributedSystem}.
+ */
+ public ClientCacheFactory(Properties props) {
+ if (props == null) {
+ props = new Properties();
+ }
+ this.dsProps = props;
+ }
+
+ /**
+ * Sets a gemfire property that will be used when creating the ClientCache.
+ * For a full list of valid gemfire properties see {@link com.gemstone.gemfire.distributed.DistributedSystem}.
+ * @param name the name of the gemfire property
+ * @param value the value of the gemfire property
+ * @return a reference to this ClientCacheFactory object
+ */
+ public ClientCacheFactory set(String name, String value) {
+ this.dsProps.setProperty(name, value);
+ return this;
+ }
+
+ /**
+ * Create a singleton client cache. If a client cache already exists in this
+ * vm that is not compatible with this factory's configuration then create
+ * will fail.
+ * <p> While creating the cache instance any declarative cache configuration (cache.xml) is processed and used to initialize the created cache.
+ * <P>Note that the cache that is produced is a singleton. Before a different instance
+ * can be produced the old one must be {@link ClientCache#close closed}.
+ * @return the singleton client cache
+ * @throws IllegalStateException if a client cache already exists and it
+ * is not compatible with this factory's configuration.
+ */
+ public ClientCache create() {
+ return basicCreate();
+ }
+
+ private ClientCache basicCreate() {
+ synchronized (ClientCacheFactory.class) {
+ GemFireCacheImpl instance = GemFireCacheImpl.getInstance();
+
+ {
+ String propValue = this.dsProps.getProperty("mcast-port");
+ if (propValue != null) {
+ int mcastPort = Integer.parseInt(propValue);
+ if (mcastPort != 0) {
+ throw new IllegalStateException("On a client cache the mcast-port must be set to 0 or not set. It was set to " + mcastPort);
+ }
+ }
+ }
+ {
+ String propValue = this.dsProps.getProperty("locators");
+ if (propValue != null && !propValue.equals("")) {
+ throw new IllegalStateException("On a client cache the locators property must be set to an empty string or not set. It was set to \"" + propValue + "\".");
+ }
+ }
+ this.dsProps.setProperty("mcast-port", "0");
+ this.dsProps.setProperty("locators", "");
+ DistributedSystem system = DistributedSystem.connect(this.dsProps);
+
+ if (instance != null && !instance.isClosed()) {
+ // this is ok; just make sure it is a client cache
+ if (!instance.isClient()) {
+ throw new IllegalStateException("A client cache can not be created because a non-client cache already exists.");
+ }
+
+ // check if pool is compatible
+ Pool pool = instance.determineDefaultPool(this.pf);
+ if (pool == null) {
+ if (instance.getDefaultPool() != null) {
+ throw new IllegalStateException("Existing cache's default pool was not compatible");
+ }
+ }
+
+ // Check if cache configuration matches.
+ cacheConfig.validateCacheConfig(instance);
+
+ return instance;
+ } else {
+ GemFireCacheImpl gfc = GemFireCacheImpl.create(true, this.pf, system, cacheConfig);
+ return gfc;
+ }
+ }
+ }
+
+ private PoolFactory getPoolFactory() {
+ if (this.pf == null) {
+ this.pf = PoolManager.createFactory();
+ }
+ return this.pf;
+ }
+
+ /**
+ * Sets the free connection timeout for this pool.
+ * If the pool has a max connections setting, operations will block
+ * if all of the connections are in use. The free connection timeout
+ * specifies how long those operations will block waiting for
+ * a free connection before receiving
+ * an {@link AllConnectionsInUseException}. If max connections
+ * is not set this setting has no effect.
+ * @see #setPoolMaxConnections(int)
+ * @param connectionTimeout the connection timeout in milliseconds
+ * @return a reference to <code>this</code>
+ * @throws IllegalArgumentException if <code>connectionTimeout</code>
+ * is less than or equal to <code>0</code>.
+ */
+ public ClientCacheFactory setPoolFreeConnectionTimeout(int connectionTimeout) {
+ getPoolFactory().setFreeConnectionTimeout(connectionTimeout);
+ return this;
+ }
+ /**
+ * Sets the load conditioning interval for this pool.
+ * This interval controls how frequently the pool will check to see if
+ * a connection to a given server should be moved to a different
+ * server to improve the load balance.
+ * <p>A value of <code>-1</code> disables load conditioning
+ * @param loadConditioningInterval the connection lifetime in milliseconds
+ * @return a reference to <code>this</code>
+ * @throws IllegalArgumentException if <code>connectionLifetime</code>
+ * is less than <code>-1</code>.
+ */
+ public ClientCacheFactory setPoolLoadConditioningInterval(int loadConditioningInterval) {
+ getPoolFactory().setLoadConditioningInterval(loadConditioningInterval);
+ return this;
+ }
+
+ /**
+ * Sets the socket buffer size for each connection made in this pool.
+ * Large messages can be received and sent faster when this buffer is larger.
+ * Larger buffers also optimize the rate at which servers can send events
+ * for client subscriptions.
+ * @param bufferSize the size of the socket buffers used for reading and
+ * writing on each connection in this pool.
+ * @return a reference to <code>this</code>
+ * @throws IllegalArgumentException if <code>bufferSize</code>
+ * is less than or equal to <code>0</code>.
+ */
+ public ClientCacheFactory setPoolSocketBufferSize(int bufferSize) {
+ getPoolFactory().setSocketBufferSize(bufferSize);
+ return this;
+ }
+
+ /**
+ * Sets the thread local connections policy for this pool.
+ * If <code>true</code> then any time a thread goes to use a connection
+ * from this pool it will check a thread local cache and see if it already
+ * has a connection in it. If so it will use it. If not it will get one from
+ * this pool and cache it in the thread local. This gets rid of thread contention
+ * for the connections but increases the number of connections the servers see.
+ * <p>If <code>false</code> then connections are returned to the pool as soon
+ * as the operation being done with the connection completes. This allows
+ * connections to be shared amonst multiple threads keeping the number of
+ * connections down.
+ * @param threadLocalConnections if <code>true</code> then enable thread local
+ * connections.
+ * @return a reference to <code>this</code>
+ */
+ public ClientCacheFactory setPoolThreadLocalConnections(boolean threadLocalConnections) {
+ getPoolFactory().setThreadLocalConnections(threadLocalConnections);
+ return this;
+ }
+
+
+ /**
+ * Sets the number of milliseconds to wait for a response from a server before
+ * timing out the operation and trying another server (if any are available).
+ * @param timeout number of milliseconds to wait for a response from a server
+ * @return a reference to <code>this</code>
+ * @throws IllegalArgumentException if <code>timeout</code>
+ * is less than <code>0</code>.
+ */
+ public ClientCacheFactory setPoolReadTimeout(int timeout) {
+ getPoolFactory().setReadTimeout(timeout);
+ return this;
+ }
+
+
+ /**
+ * Set the minimum number of connections to keep available at all times.
+ * When the pool is created, it will create this many connections.
+ * If <code>0</code> then connections will not be made until an actual operation
+ * is done that requires client-to-server communication.
+ * @param minConnections the initial number of connections
+ * this pool will create.
+ * @return a reference to <code>this</code>
+ * @throws IllegalArgumentException if <code>minConnections</code>
+ * is less than <code>0</code>.
+ */
+ public ClientCacheFactory setPoolMinConnections(int minConnections) {
+ getPoolFactory().setMinConnections(minConnections);
+ return this;
+ }
+
+
+ /**
+ * Set the max number of client to server connections that the pool will create. If all of
+ * the connections are in use, an operation requiring a client to server connection
+ * will block until a connection is available.
+ * @see #setPoolFreeConnectionTimeout(int)
+ * @param maxConnections the maximum number of connections in the pool.
+ * this pool will create. -1 indicates that there is no maximum number of connections
+ * @return a reference to <code>this</code>
+ * @throws IllegalArgumentException if <code>maxConnections</code>
+ * is less than <code>minConnections</code>.
+ */
+ public ClientCacheFactory setPoolMaxConnections(int maxConnections) {
+ getPoolFactory().setMaxConnections(maxConnections);
+ return this;
+ }
+
+
+ /**
+ * Set the amount of time a connection can be idle before expiring the connection.
+ * If the pool size is greater than the minimum specified by
+ * {@link #setPoolMinConnections(int)}, connections which have been idle
+ * for longer than the idleTimeout will be closed.
+ * @param idleTimeout The amount of time in milliseconds that an idle connection
+ * should live before expiring. -1 indicates that connections should never expire.
+ * @return a reference to <code>this</code>
+ * @throws IllegalArgumentException if <code>idleTimout</code>
+ * is less than <code>-1</code>.
+ */
+ public ClientCacheFactory setPoolIdleTimeout(long idleTimeout) {
+ getPoolFactory().setIdleTimeout(idleTimeout);
+ return this;
+ }
+
+
+ /**
+ * Set the number of times to retry a request after timeout/exception.
+ * @param retryAttempts The number of times to retry a request
+ * after timeout/exception. -1 indicates that a request should be
+ * tried against every available server before failing
+ * @return a reference to <code>this</code>
+ * @throws IllegalArgumentException if <code>idleTimout</code>
+ * is less than <code>-1</code>.
+ */
+ public ClientCacheFactory setPoolRetryAttempts(int retryAttempts) {
+ getPoolFactory().setRetryAttempts(retryAttempts);
+ return this;
+ }
+
+
+ /**
+ * How often to ping servers to verify that they are still alive. Each
+ * server will be sent a ping every pingInterval if there has not
+ * been any other communication with the server.
+ *
+ * These pings are used by the server to monitor the health of
+ * the client. Make sure that the pingInterval is less than the
+ * maximum time between pings allowed by the cache server.
+ * @param pingInterval The amount of time in milliseconds between
+ * pings.
+ * @return a reference to <code>this</code>
+ * @throws IllegalArgumentException if <code>pingInterval</code>
+ * is less than or equal to <code>0</code>.
+ * @see CacheServer#setMaximumTimeBetweenPings(int)
+ */
+ public ClientCacheFactory setPoolPingInterval(long pingInterval) {
+ getPoolFactory().setPingInterval(pingInterval);
+ return this;
+ }
+
+
+ /**
+ * How often to send client statistics to the server.
+ * Doing this allows <code>gfmon</code> to monitor clients.
+ * <p>A value of <code>-1</code> disables the sending of client statistics
+ * to the server.
+ *
+ * @param statisticInterval The amount of time in milliseconds between
+ * sends of client statistics to the server.
+ * @return a reference to <code>this</code>
+ * @throws IllegalArgumentException if <code>statisticInterval</code>
+ * is less than <code>-1</code>.
+ */
+ public ClientCacheFactory setPoolStatisticInterval(int statisticInterval) {
+ getPoolFactory().setStatisticInterval(statisticInterval);
+ return this;
+ }
+
+
+ /**
+ * Configures the group that all servers this pool connects to must belong to.
+ * @param group the server group that this pool will connect to.
+ * If <code>null</code> or <code>""</code> then all servers will be connected to.
+ * @return a reference to <code>this</code>
+ */
+ public ClientCacheFactory setPoolServerGroup(String group) {
+ getPoolFactory().setServerGroup(group);
+ return this;
+ }
+
+
+ /**
+ * Add a locator, given its host and port, to this factory.
+ * The locator must be a server locator and will be used to discover other running
+ * cache servers and locators.
+ * @param host the host name or ip address that the locator is listening on.
+ * @param port the port that the locator is listening on
+ * @return a reference to <code>this</code>
+ * @throws IllegalArgumentException if <code>host</code> is an unknown host
+ * according to {@link java.net.InetAddress#getByName(String)} or if port is outside
+ * the valid range of [1..65535] inclusive.
+ * @throws IllegalStateException if a server has already been {@link #addPoolServer added} to this factory.
+ */
+ public ClientCacheFactory addPoolLocator(String host, int port) {
+ getPoolFactory().addLocator(host, port);
+ return this;
+ }
+
+
+ /**
+ * Add a server, given its host and port, to this factory.
+ * The server must be a cache server and this client will
+ * directly connect to without consulting a server locator.
+ * @param host the host name or ip address that the server is listening on.
+ * @param port the port that the server is listening on
+ * @return a reference to <code>this</code>
+ * @throws IllegalArgumentException if <code>host</code> is an unknown host
+ * according to {@link java.net.InetAddress#getByName(String)} or if port is outside
+ * the valid range of [1..65535] inclusive.
+ * @throws IllegalStateException if a locator has already been {@link #addPoolLocator added} to this factory.
+ */
+ public ClientCacheFactory addPoolServer(String host, int port) {
+ getPoolFactory().addServer(host, port);
+ return this;
+ }
+
+
+ /**
+ * If set to <code>true</code> then the created pool will have server-to-client
+ * subscriptions enabled.
+ * If set to <code>false</code> then all <code>Subscription*</code> attributes
+ * are ignored at create time.
+ * @return a reference to <code>this</code>
+ */
+ public ClientCacheFactory setPoolSubscriptionEnabled(boolean enabled) {
+ getPoolFactory().setSubscriptionEnabled(enabled);
+ return this;
+ }
+
+
+ /**
+ * Sets the redundancy level for this pools server-to-client subscriptions.
+ * If <code>0</code> then no redundant copies will be kept on the servers.
+ * Otherwise an effort will be made to maintain the requested number of
+ * copies of the server-to-client subscriptions. At most one copy per server will
+ * be made up to the requested level.
+ * @param redundancy the number of redundant servers for this client's subscriptions.
+ * @return a reference to <code>this</code>
+ * @throws IllegalArgumentException if <code>redundancyLevel</code>
+ * is less than <code>-1</code>.
+ */
+ public ClientCacheFactory setPoolSubscriptionRedundancy(int redundancy) {
+ getPoolFactory().setSubscriptionRedundancy(redundancy);
+ return this;
+ }
+
+ /**
+ * Sets the messageTrackingTimeout attribute which is the time-to-live period, in
+ * milliseconds, for subscription events the client has received from the server. It's used
+ * to minimize duplicate events.
+ * Entries that have not been modified for this amount of time
+ * are expired from the list
+ * @param messageTrackingTimeout number of milliseconds to set the timeout to.
+ * @return a reference to <code>this</code>
+ * @throws IllegalArgumentException if <code>messageTrackingTimeout</code>
+ * is less than or equal to <code>0</code>.
+ */
+ public ClientCacheFactory setPoolSubscriptionMessageTrackingTimeout(int messageTrackingTimeout) {
+ getPoolFactory().setSubscriptionMessageTrackingTimeout(messageTrackingTimeout);
+ return this;
+ }
+
+
+ /**
+ * Sets the interval in milliseconds
+ * to wait before sending acknowledgements to the cache server for
+ * events received from the server subscriptions.
+ *
+ * @param ackInterval number of milliseconds to wait before sending event
+ * acknowledgements.
+ * @return a reference to <code>this</code>
+ * @throws IllegalArgumentException if <code>ackInterval</code>
+ * is less than or equal to <code>0</code>.
+ */
+ public ClientCacheFactory setPoolSubscriptionAckInterval(int ackInterval) {
+ getPoolFactory().setSubscriptionAckInterval(ackInterval);
+ return this;
+ }
+
+
+ /**
+ * By default setPRSingleHopEnabled is <code>true</code>
+ * in which case the client is aware of the location of partitions on servers hosting
+ * {@link Region regions} with
+ * {@link com.gemstone.gemfire.cache.DataPolicy#PARTITION}.
+ * Using this information, the client routes the client cache operations
+ * directly to the server which is hosting the required partition for the
+ * cache operation using a single network hop.
+ * This mode works best
+ * when {@link #setPoolMaxConnections(int)} is set
+ * to <code>-1</code> which is the default.
+ * This mode causes the client to have more connections to the servers.
+ * <p>
+ * If setPRSingleHopEnabled is <code>false</code> the client may need to do an extra network hop on servers
+ * to go to the required partition for that cache operation.
+ * The client will use fewer network connections to the servers.
+ * <p>
+ * Caution: for {@link com.gemstone.gemfire.cache.DataPolicy#PARTITION partition} regions
+ * with
+ * {@link com.gemstone.gemfire.cache.PartitionAttributesFactory#setLocalMaxMemory(int) local-max-memory}
+ * equal to zero, no cache operations mentioned above will be routed to those
+ * servers as they do not host any partitions.
+ *
+ * @return the newly created pool.
+ */
+ public ClientCacheFactory setPoolPRSingleHopEnabled(boolean enabled) {
+ getPoolFactory().setPRSingleHopEnabled(enabled);
+ return this;
+ }
+
+
+ /**
+ * If set to <code>true</code> then the created pool can be used by multiple
+ * users. <br>
+ * <br>
+ * Note: If set to true, all the client side regions must be
+ * {@link ClientRegionShortcut#PROXY proxies}. No client side storage is allowed.
+ *
+ * @return a reference to <code>this</code>
+ */
+ public ClientCacheFactory setPoolMultiuserAuthentication(boolean enabled) {
+ getPoolFactory().setMultiuserAuthentication(enabled);
+ return this;
+ }
+
+
+ /** Returns the version of the cache implementation.
+ * @return the version of the cache implementation as a <code>String</code>
+ */
+ public static String getVersion() {
+ return GemFireVersion.getGemFireVersion();
+ }
+ /**
+ * Gets an arbitrary open instance of {@link ClientCache} produced by an
+ * earlier call to {@link #create}.
+ * @throws CacheClosedException if a cache has not been created
+ * or the only created one is {@link ClientCache#isClosed closed}
+ * @throws IllegalStateException if the cache was created by CacheFactory instead
+ * of ClientCacheFactory
+ */
+ public static synchronized ClientCache getAnyInstance() {
+ GemFireCacheImpl instance = GemFireCacheImpl.getInstance();
+ if (instance == null) {
+ throw new CacheClosedException(LocalizedStrings.CacheFactory_A_CACHE_HAS_NOT_YET_BEEN_CREATED.toLocalizedString());
+ } else {
+ if (!instance.isClient()) {
+ throw new IllegalStateException("The singleton cache was created by CacheFactory not ClientCacheFactory.");
+ }
+ instance.getCancelCriterion().checkCancelInProgress(null);
+ return instance;
+ }
+ }
+
+ /** Sets the object preference to PdxInstance type.
+ * When a cached object that was serialized as a PDX is read
+ * from the cache a {@link PdxInstance} will be returned instead of the actual domain class.
+ * The PdxInstance is an interface that provides run time access to
+ * the fields of a PDX without deserializing the entire PDX.
+ * The PdxInstance implementation is a light weight wrapper
+ * that simply refers to the raw bytes of the PDX that are kept
+ * in the cache. Using this method applications can choose to
+ * access PdxInstance instead of Java object.
+ * <p>Note that a PdxInstance is only returned if a serialized PDX is found in the cache.
+ * If the cache contains a deserialized PDX, then a domain class instance is returned instead of a PdxInstance.
+ *
+ * @param pdxReadSerialized true to prefer PdxInstance
+ * @return this ClientCacheFactory
+ * @since 6.6
+ * @see com.gemstone.gemfire.pdx.PdxInstance
+ */
+ public ClientCacheFactory setPdxReadSerialized(boolean pdxReadSerialized) {
+ this.cacheConfig.setPdxReadSerialized(pdxReadSerialized);
+ return this;
+ }
+
+ /**
+ * Set the PDX serializer for the cache. If this serializer is set,
+ * it will be consulted to see if it can serialize any domain classes which are
+ * added to the cache in portable data exchange format.
+ * @param serializer the serializer to use
+ * @return this ClientCacheFactory
+ * @since 6.6
+ * @see PdxSerializer
+ */
+ public ClientCacheFactory setPdxSerializer(PdxSerializer serializer) {
+ this.cacheConfig.setPdxSerializer(serializer);
+ return this;
+ }
+
+ /**
+ * Set the disk store that is used for PDX meta data. When
+ * serializing objects in the PDX format, the type definitions
+ * are persisted to disk. This setting controls which disk store
+ * is used for that persistence.
+ *
+ * If not set, the metadata will go in the default disk store.
+ * @param diskStoreName the name of the disk store to use
+ * for the PDX metadata.
+ * @return this ClientCacheFactory
+ * @since 6.6
+ */
+ public ClientCacheFactory setPdxDiskStore(String diskStoreName) {
+ this.cacheConfig.setPdxDiskStore(diskStoreName);
+ return this;
+ }
+
+ /**
+ * Control whether the type metadata for PDX objects is persisted to disk.
+ * The default for this setting is false.
+ * If you are using persistent regions with PDX then you must set this to true.
+ * If you are using a WAN gateway with PDX then you should set this to true.
+ *
+ * @param isPersistent true if the metadata should be persistent
+ * @return this ClientCacheFactory
+ * @since 6.6
+ */
+ public ClientCacheFactory setPdxPersistent(boolean isPersistent) {
+ this.cacheConfig.setPdxPersistent(isPersistent);
+ return this;
+ }
+ /**
+ * Control whether pdx ignores fields that were unread during deserialization.
+ * The default is to preserve unread fields be including their data during serialization.
+ * But if you configure the cache to ignore unread fields then their data will be lost
+ * during serialization.
+ * <P>You should only set this attribute to <code>true</code> if you know this member
+ * will only be reading cache data. In this use case you do not need to pay the cost
+ * of preserving the unread fields since you will never be reserializing pdx data.
+ *
+ * @param ignore <code>true</code> if fields not read during pdx deserialization should be ignored;
+ * <code>false</code>, the default, if they should be preserved.
+ * @return this ClientCacheFactory
+ * @since 6.6
+ */
+ public ClientCacheFactory setPdxIgnoreUnreadFields(boolean ignore) {
+ this.cacheConfig.setPdxIgnoreUnreadFields(ignore);
+ return this;
+ }
+
+}
http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/19459053/gemfire-core/src/main/java/com/gemstone/gemfire/cache/client/ClientNotReadyException.java
----------------------------------------------------------------------
diff --git a/gemfire-core/src/main/java/com/gemstone/gemfire/cache/client/ClientNotReadyException.java b/gemfire-core/src/main/java/com/gemstone/gemfire/cache/client/ClientNotReadyException.java
new file mode 100755
index 0000000..2297789
--- /dev/null
+++ b/gemfire-core/src/main/java/com/gemstone/gemfire/cache/client/ClientNotReadyException.java
@@ -0,0 +1,47 @@
+/*=========================================================================
+ * Copyright (c) 2002-2014 Pivotal Software, Inc. All Rights Reserved.
+ * This product is protected by U.S. and international copyright
+ * and intellectual property laws. Pivotal products are covered by
+ * more patents listed at http://www.pivotal.io/patents.
+ *========================================================================
+ */
+
+package com.gemstone.gemfire.cache.client;
+
+import com.gemstone.gemfire.cache.OperationAbortedException;
+
+/**
+ * A <code>ClientNotReadyException</code> indicates a client attempted to invoke
+ * the {@link com.gemstone.gemfire.cache.Cache#readyForEvents}
+ * method, but failed.
+ * <p>This exception was moved from the <code>util</code> package in 5.7.
+ *
+ * @author darrel
+ *
+ * @since 5.7
+ * @deprecated as of 6.5 this exception is no longer thrown by GemFire so any code that catches it should be removed.
+ *
+ */
+public class ClientNotReadyException extends OperationAbortedException {
+private static final long serialVersionUID = -315765802919271588L;
+ /**
+ * Constructs an instance of <code>ClientNotReadyException</code> with the
+ * specified detail message.
+ *
+ * @param msg the detail message
+ */
+ public ClientNotReadyException(String msg) {
+ super(msg);
+ }
+
+ /**
+ * Constructs an instance of <code>ClientNotReadyException</code> with the
+ * specified detail message and cause.
+ *
+ * @param msg the detail message
+ * @param cause the causal Throwable
+ */
+ public ClientNotReadyException(String msg, Throwable cause) {
+ super(msg, cause);
+ }
+}
http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/19459053/gemfire-core/src/main/java/com/gemstone/gemfire/cache/client/ClientRegionFactory.java
----------------------------------------------------------------------
diff --git a/gemfire-core/src/main/java/com/gemstone/gemfire/cache/client/ClientRegionFactory.java b/gemfire-core/src/main/java/com/gemstone/gemfire/cache/client/ClientRegionFactory.java
new file mode 100644
index 0000000..f8fc717
--- /dev/null
+++ b/gemfire-core/src/main/java/com/gemstone/gemfire/cache/client/ClientRegionFactory.java
@@ -0,0 +1,337 @@
+/*=========================================================================
+ * Copyright (c) 2002-2014 Pivotal Software, Inc. All Rights Reserved.
+ * This product is protected by U.S. and international copyright
+ * and intellectual property laws. Pivotal products are covered by
+ * more patents listed at http://www.pivotal.io/patents.
+ *=========================================================================
+ */
+package com.gemstone.gemfire.cache.client;
+
+import com.gemstone.gemfire.cache.AttributesFactory;
+import com.gemstone.gemfire.cache.CacheClosedException;
+import com.gemstone.gemfire.cache.CacheListener;
+import com.gemstone.gemfire.cache.CustomExpiry;
+import com.gemstone.gemfire.cache.EvictionAttributes;
+import com.gemstone.gemfire.cache.ExpirationAttributes;
+import com.gemstone.gemfire.cache.Region;
+import com.gemstone.gemfire.cache.RegionDestroyedException;
+import com.gemstone.gemfire.cache.RegionExistsException;
+import com.gemstone.gemfire.compression.Compressor;
+
+/**
+ * A factory for constructing {@link ClientCache client cache} {@link Region
+ * regions}. Instances of this interface can be created using region shortcuts
+ * by calling
+ * {@link ClientCache#createClientRegionFactory(ClientRegionShortcut)} or using
+ * named region attributes by calling
+ * {@link ClientCache#createClientRegionFactory(String)}.
+ * <p>
+ * The factory can then be customized using its methods.
+ * <p>
+ * The final step is to produce a {@link Region} by calling
+ * {@link #create(String)}.
+ * <p>
+ * Client regions may be:
+ * <ul>
+ * <li>PROXY: which pass through to server and have no local data.
+ * <li>CACHING_PROXY: which fetch data from servers and cache it locally.
+ * <li>LOCAL: which only have local data; they do not communicate with the
+ * servers.
+ * </ul>
+ * See {@link ClientRegionShortcut} for the shortcuts for these three types of
+ * client regions.
+ * <p>
+ * Example: Create a client region with a CacheListener
+ *
+ * <PRE>
+ * ClientCache c = new ClientCacheFactory().addLocator(host, port).create();
+ * // Create local caching region that is connected to a server side region
+ * // Add a cache listener before creating region
+ * Region r = c.createClientRegionFactory(CACHING_PROXY).addCacheListener(
+ * myListener).create("customers");
+ * </PRE>
+ *
+ * @author darrel
+ * @since 6.5
+ */
+
+public interface ClientRegionFactory<K,V> {
+ /**
+ * Adds a cache listener to the end of the list of cache listeners on this factory.
+ * @param aListener the cache listener to add
+ * @return a reference to this ClientRegionFactory object
+ * @throws IllegalArgumentException if <code>aListener</code> is null
+ * @see AttributesFactory#addCacheListener
+ */
+ public ClientRegionFactory<K,V> addCacheListener(CacheListener<K,V> aListener);
+
+ /**
+ * Removes all cache listeners and then adds each listener in the specified array.
+ * for the next <code>RegionAttributes</code> created.
+ * @param newListeners a possibly null or empty array of listeners to add to this factory.
+ * @return a reference to this ClientRegionFactory object
+ * @throws IllegalArgumentException if the <code>newListeners</code> array has a null element
+ * @see AttributesFactory#initCacheListeners
+ */
+ public ClientRegionFactory<K,V> initCacheListeners(CacheListener<K,V>[] newListeners);
+
+ /**
+ * Sets the eviction attributes that controls growth of the Region to be created.
+ *
+ * @param evictionAttributes for the Region to create
+ * @return a reference to this ClientRegionFactory object
+ */
+ public ClientRegionFactory<K,V> setEvictionAttributes(EvictionAttributes evictionAttributes);
+
+ /**
+ * Sets the idleTimeout expiration attributes for region entries for the next
+ * <code>RegionAttributes</code> created.
+ *
+ * @param idleTimeout
+ * the idleTimeout ExpirationAttributes for entries in this region
+ * @return a reference to this ClientRegionFactory object
+ * @throws IllegalArgumentException
+ * if idleTimeout is null
+ * @see AttributesFactory#setEntryIdleTimeout
+ */
+ public ClientRegionFactory<K,V> setEntryIdleTimeout(ExpirationAttributes idleTimeout);
+
+ /**
+ * Sets the custom idleTimeout for the next <code>RegionAttributes</code>
+ * created.
+ *
+ * @param custom the custom method
+ * @return the receiver
+ * @see AttributesFactory#setCustomEntryIdleTimeout(CustomExpiry)
+ */
+ public ClientRegionFactory<K,V> setCustomEntryIdleTimeout(CustomExpiry<K,V> custom);
+
+ /**
+ * Sets the timeToLive expiration attributes for region entries for the next
+ * <code>RegionAttributes</code> created.
+ *
+ * @param timeToLive
+ * the timeToLive ExpirationAttributes for entries in this region
+ * @return a reference to this ClientRegionFactory object
+ * @throws IllegalArgumentException
+ * if timeToLive is null
+ * @see AttributesFactory#setEntryTimeToLive
+ */
+ public ClientRegionFactory<K,V> setEntryTimeToLive(ExpirationAttributes timeToLive);
+
+ /**
+ * Sets the custom timeToLive expiration method for the next
+ * <code>RegionAttributes</code> created.
+ * @param custom the custom method
+ * @return the receiver
+ * @see AttributesFactory#setCustomEntryTimeToLive(CustomExpiry)
+ */
+ public ClientRegionFactory<K,V> setCustomEntryTimeToLive(CustomExpiry<K,V> custom);
+
+ /**
+ * Sets the idleTimeout expiration attributes for the region itself for the
+ * next <code>RegionAttributes</code> created.
+ *
+ * @param idleTimeout
+ * the ExpirationAttributes for this region idleTimeout
+ * @return a reference to this ClientRegionFactory object
+ * @throws IllegalArgumentException
+ * if idleTimeout is null
+ * @see AttributesFactory#setRegionIdleTimeout
+ */
+ public ClientRegionFactory<K,V> setRegionIdleTimeout(ExpirationAttributes idleTimeout);
+
+ /**
+ * Sets the timeToLive expiration attributes for the region itself for the
+ * next <code>RegionAttributes</code> created.
+ *
+ * @param timeToLive
+ * the ExpirationAttributes for this region timeToLive
+ * @return a reference to this ClientRegionFactory object
+ * @throws IllegalArgumentException
+ * if timeToLive is null
+ * @see AttributesFactory#setRegionTimeToLive
+ */
+ public ClientRegionFactory<K,V> setRegionTimeToLive(ExpirationAttributes timeToLive);
+
+ /**
+ * Sets the key constraint for the next <code>RegionAttributes</code>
+ * created. Keys in the region will be constrained to this class (or
+ * subclass). Any attempt to store a key of an incompatible type in the region
+ * will cause a <code>ClassCastException</code> to be thrown.
+ *
+ * @param keyConstraint
+ * The Class to constrain the keys to, or null if no constraint
+ * @return a reference to this ClientRegionFactory object
+ * @throws IllegalArgumentException
+ * if <code>keyConstraint</code> is a class denoting a primitive
+ * type
+ * @see AttributesFactory#setKeyConstraint
+ */
+ public ClientRegionFactory<K,V> setKeyConstraint(Class<K> keyConstraint);
+
+ /**
+ * Sets the value constraint for the next <code>RegionAttributes</code>
+ * created. Values in the region will be constrained to this class (or
+ * subclass). Any attempt to store a value of an incompatible type in the
+ * region will cause a <code>ClassCastException</code> to be thrown.
+ *
+ * @param valueConstraint
+ * The Class to constrain the values to, or null if no constraint
+ * @return a reference to this ClientRegionFactory object
+ * @throws IllegalArgumentException
+ * if <code>valueConstraint</code> is a class denoting a primitive
+ * type
+ * @see AttributesFactory#setValueConstraint
+ */
+ public ClientRegionFactory<K,V> setValueConstraint(Class<V> valueConstraint);
+
+ /**
+ * Sets the entry initial capacity for the next <code>RegionAttributes</code>
+ * created. This value is used in initializing the map that holds the entries.
+ *
+ * @param initialCapacity
+ * the initial capacity of the entry map
+ * @return a reference to this ClientRegionFactory object
+ * @throws IllegalArgumentException if initialCapacity is negative.
+ * @see java.util.HashMap
+ * @see AttributesFactory#setInitialCapacity
+ */
+ public ClientRegionFactory<K,V> setInitialCapacity(int initialCapacity);
+
+ /**
+ * Sets the entry load factor for the next <code>RegionAttributes</code>
+ * created. This value is used in initializing the map that holds the entries.
+ *
+ * @param loadFactor
+ * the load factor of the entry map
+ * @return a reference to this ClientRegionFactory object
+ * @throws IllegalArgumentException
+ * if loadFactor is nonpositive
+ * @see java.util.HashMap
+ * @see AttributesFactory#setLoadFactor
+ */
+ public ClientRegionFactory<K,V> setLoadFactor(float loadFactor);
+
+ /**
+ * Sets the concurrency level tof the next <code>RegionAttributes</code>
+ * created. This value is used in initializing the map that holds the entries.
+ *
+ * @param concurrencyLevel
+ * the concurrency level of the entry map
+ * @return a reference to this ClientRegionFactory object
+ * @throws IllegalArgumentException
+ * if concurrencyLevel is nonpositive
+ * @see AttributesFactory#setConcurrencyLevel
+ */
+ public ClientRegionFactory<K,V> setConcurrencyLevel(int concurrencyLevel);
+
+ /**
+ * Enables or disabled concurrent modification checks
+ * @since 7.0
+ * @param concurrencyChecksEnabled whether to perform concurrency checks on operations
+ */
+ public void setConcurrencyChecksEnabled(boolean concurrencyChecksEnabled);
+
+ /**
+ * Sets the DiskStore name attribute.
+ * This causes the region to belong to the DiskStore.
+ * @param name the name of the diskstore
+ * @return a reference to this ClientRegionFactory object
+ *
+ * @see AttributesFactory#setDiskStoreName
+ */
+ public ClientRegionFactory<K,V> setDiskStoreName(String name);
+
+ /**
+ * Sets whether or not the writing to the disk is synchronous.
+ *
+ * @param isSynchronous
+ * boolean if true indicates synchronous writes
+ * @return a reference to this ClientRegionFactory object
+ */
+ public ClientRegionFactory<K,V> setDiskSynchronous(boolean isSynchronous);
+
+ /**
+ * Sets whether statistics are enabled for this region and its entries.
+ *
+ * @param statisticsEnabled
+ * whether statistics are enabled
+ * @return a reference to this ClientRegionFactory object
+ * @see AttributesFactory#setStatisticsEnabled
+ */
+ public ClientRegionFactory<K,V> setStatisticsEnabled(boolean statisticsEnabled);
+
+ /**
+ * Sets cloning on region
+ * @param cloningEnable
+ * @return a reference to this ClientRegionFactory object
+ * @see AttributesFactory#setCloningEnabled
+ */
+ public ClientRegionFactory<K,V> setCloningEnabled(boolean cloningEnable);
+
+ /**
+ * Sets the pool name attribute.
+ * This causes regions that use these attributes
+ * to be a client region which communicates with the
+ * servers that the connection pool communicates with.
+ * <p>The named connection pool must exist on the cache at the time these
+ * attributes are used to create a region. See {@link PoolManager#createFactory}
+ * for how to create a connection pool.
+ * @param poolName the name of the connection pool to use
+ * @return a reference to this ClientRegionFactory object
+ * @throws IllegalStateException if a cache loader or cache writer has already
+ * been set.
+ * @see PoolManager
+ */
+ public ClientRegionFactory<K,V> setPoolName(String poolName);
+
+ /**
+ * Set the compressor to be used by this region for compressing
+ * region entry values.
+ * @param compressor a compressor
+ * @return a reference to this RegionFactory instance
+ * @since 8.0
+ */
+ public ClientRegionFactory<K,V> setCompressor(Compressor compressor);
+
+ /**
+ * Creates a region in the {@link ClientCache} using
+ * the configuration contained in this ClientRegionFactory. Validation of the
+ * provided attributes may cause exceptions to be thrown if there are problems
+ * with the configuration data.
+ *
+ * @param name
+ * the name of the region to create
+ *
+ * @return the region object
+ * @throws RegionExistsException
+ * if a region with the given name already exists in this cache
+ * @throws CacheClosedException
+ * if the cache is closed
+ */
+ public Region<K,V> create(String name) throws RegionExistsException;
+ /**
+ * Creates a sub-region in the {@link ClientCache} using
+ * the configuration contained in this ClientRegionFactory. Validation of the
+ * provided attributes may cause exceptions to be thrown if there are problems
+ * with the configuration data.
+ *
+ * @param parent
+ * the existing region that will contain the created sub-region
+ * @param name
+ * the name of the region to create
+ *
+ * @return the region object
+ * @throws RegionExistsException
+ * if a region with the given name already exists in this cache
+ * @throws RegionDestroyedException
+ * if the parent region has been closed or destroyed
+ * @throws CacheClosedException
+ * if the cache is closed
+ * @since 7.0
+ */
+ public Region<K,V> createSubregion(Region<?,?> parent, String name) throws RegionExistsException;
+
+
+}
http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/19459053/gemfire-core/src/main/java/com/gemstone/gemfire/cache/client/ClientRegionShortcut.java
----------------------------------------------------------------------
diff --git a/gemfire-core/src/main/java/com/gemstone/gemfire/cache/client/ClientRegionShortcut.java b/gemfire-core/src/main/java/com/gemstone/gemfire/cache/client/ClientRegionShortcut.java
new file mode 100644
index 0000000..b3c0590
--- /dev/null
+++ b/gemfire-core/src/main/java/com/gemstone/gemfire/cache/client/ClientRegionShortcut.java
@@ -0,0 +1,99 @@
+/*=========================================================================
+ * Copyright (c) 2002-2014 Pivotal Software, Inc. All Rights Reserved.
+ * This product is protected by U.S. and international copyright
+ * and intellectual property laws. Pivotal products are covered by
+ * more patents listed at http://www.pivotal.io/patents.
+ *========================================================================
+ */
+
+package com.gemstone.gemfire.cache.client;
+
+import com.gemstone.gemfire.cache.*;
+
+/**
+ * Each enum represents a predefined {@link RegionAttributes} in a {@link ClientCache}.
+ * These enum values can be used to create regions using a {@link ClientRegionFactory}
+ * obtained by calling {@link ClientCache#createClientRegionFactory(ClientRegionShortcut)}.
+ * <p>Another way to use predefined region attributes is in cache.xml by setting
+ * the refid attribute on a region element or region-attributes element to the
+ * string of each value.
+ * @since 6.5
+ * @author darrel
+ */
+public enum ClientRegionShortcut {
+ /**
+ * A PROXY region has no local state and forwards all operations to a server.
+ * The actual RegionAttributes for a PROXY set the {@link DataPolicy} to {@link DataPolicy#EMPTY}.
+ */
+ PROXY,
+
+ /**
+ * A CACHING_PROXY region has local state but can also send operations to a server.
+ * If the local state is not found then the operation is sent to the server
+ * and the local state is updated to contain the server result.
+ * The actual RegionAttributes for a CACHING_PROXY set the {@link DataPolicy} to {@link DataPolicy#NORMAL}.
+ */
+ CACHING_PROXY,
+
+ /**
+ * A CACHING_PROXY_HEAP_LRU region has local state but can also send operations to a server.
+ * If the local state is not found then the operation is sent to the server
+ * and the local state is updated to contain the server result.
+ * It will also destroy entries once it detects that the java vm is running low
+ * of memory.
+ * The actual RegionAttributes for a CACHING_PROXY_HEAP_LRU set the {@link DataPolicy} to {@link DataPolicy#NORMAL}.
+ * and {@link EvictionAttributes} are set to {@link EvictionAlgorithm#LRU_HEAP}
+ * with {@link EvictionAction#LOCAL_DESTROY}.
+ */
+ CACHING_PROXY_HEAP_LRU,
+ /**
+ * A CACHING_PROXY_OVERFLOW region has local state but can also send operations to a server.
+ * If the local state is not found then the operation is sent to the server
+ * and the local state is updated to contain the server result.
+ * It will also move the values of entries to disk once it detects that the
+ * java vm is running low of memory.
+ * The actual RegionAttributes for a CACHING_PROXY_OVERFLOW set the {@link DataPolicy} to {@link DataPolicy#NORMAL}.
+ * and {@link EvictionAttributes} are set to {@link EvictionAlgorithm#LRU_HEAP}
+ * with {@link EvictionAction#OVERFLOW_TO_DISK}.
+ */
+ CACHING_PROXY_OVERFLOW,
+
+ /**
+ * A LOCAL region only has local state and never sends operations to a server.
+ * The actual RegionAttributes for a LOCAL region set the {@link DataPolicy} to {@link DataPolicy#NORMAL}.
+ */
+ LOCAL,
+ /**
+ * A LOCAL_PERSISTENT region only has local state and never sends operations to a server
+ * but it does write its state to disk and can recover that state when the region
+ * is created.
+ * The actual RegionAttributes for a LOCAL_PERSISTENT region set the {@link DataPolicy} to {@link DataPolicy#PERSISTENT_REPLICATE}.
+ */
+ LOCAL_PERSISTENT,
+ /**
+ * A LOCAL_HEAP_LRU region only has local state and never sends operations to a server.
+ * It will also destroy entries once it detects that the java vm is running low
+ * of memory.
+ * The actual RegionAttributes for a LOCAL_HEAP_LRU region set the {@link DataPolicy} to {@link DataPolicy#NORMAL} and {@link EvictionAttributes} are set to {@link EvictionAlgorithm#LRU_HEAP}
+ * with {@link EvictionAction#LOCAL_DESTROY}.
+ */
+ LOCAL_HEAP_LRU,
+ /**
+ * A LOCAL_OVERFLOW region only has local state and never sends operations to a server.
+ * It will also move the values of entries to disk once it detects that the
+ * java vm is running low of memory.
+ * The actual RegionAttributes for a LOCAL_OVERFLOW region set the {@link DataPolicy} to {@link DataPolicy#NORMAL} and {@link EvictionAttributes} are set to {@link EvictionAlgorithm#LRU_HEAP}
+ * with {@link EvictionAction#OVERFLOW_TO_DISK}.
+ */
+ LOCAL_OVERFLOW,
+ /**
+ * A LOCAL_PERSISTENT_OVERFLOW region only has local state and never sends operations to a server
+ * but it does write its state to disk and can recover that state when the region
+ * is created.
+ * It will also remove the values of entries from memory once it detects that the
+ * java vm is running low of memory.
+ * The actual RegionAttributes for a LOCAL_PERSISTENT_OVERFLOW region set the {@link DataPolicy} to {@link DataPolicy#PERSISTENT_REPLICATE} and {@link EvictionAttributes} are set to {@link EvictionAlgorithm#LRU_HEAP}
+ * with {@link EvictionAction#OVERFLOW_TO_DISK}.
+ */
+ LOCAL_PERSISTENT_OVERFLOW
+}
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/19459053/gemfire-core/src/main/java/com/gemstone/gemfire/cache/client/NoAvailableLocatorsException.java
----------------------------------------------------------------------
diff --git a/gemfire-core/src/main/java/com/gemstone/gemfire/cache/client/NoAvailableLocatorsException.java b/gemfire-core/src/main/java/com/gemstone/gemfire/cache/client/NoAvailableLocatorsException.java
new file mode 100644
index 0000000..70fb6c1
--- /dev/null
+++ b/gemfire-core/src/main/java/com/gemstone/gemfire/cache/client/NoAvailableLocatorsException.java
@@ -0,0 +1,50 @@
+/*=========================================================================
+ * Copyright (c) 2002-2014 Pivotal Software, Inc. All Rights Reserved.
+ * This product is protected by U.S. and international copyright
+ * and intellectual property laws. Pivotal products are covered by
+ * more patents listed at http://www.pivotal.io/patents.
+ *=========================================================================
+ */
+package com.gemstone.gemfire.cache.client;
+
+
+/**
+ * An exception indicating that there are no active locators available to connect to.
+ * @author dsmith
+ * @since 5.7
+ */
+public class NoAvailableLocatorsException extends ServerConnectivityException {
+ private static final long serialVersionUID = -8212446737778234890L;
+
+ /**
+ * Create a new instance of NoAvailableLocatorsException without a detail message or cause.
+ */
+ public NoAvailableLocatorsException() {
+ }
+
+ /**
+ * Create a new instance of NoAvailableServersException with a detail message
+ * @param message the detail message
+ */
+ public NoAvailableLocatorsException(String message) {
+ super(message);
+ }
+
+ /**
+ * Create a new instance of NoAvailableLocatorsException with a detail message and cause
+ * @param message the detail message
+ * @param cause the cause
+ */
+ public NoAvailableLocatorsException(String message, Throwable cause) {
+ super(message, cause);
+ }
+
+ /**
+ * Create a new instance of NoAvailableLocatorsException with a and cause
+ * @param cause the cause
+ */
+ public NoAvailableLocatorsException(Throwable cause) {
+ super(cause);
+ }
+
+}
http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/19459053/gemfire-core/src/main/java/com/gemstone/gemfire/cache/client/NoAvailableServersException.java
----------------------------------------------------------------------
diff --git a/gemfire-core/src/main/java/com/gemstone/gemfire/cache/client/NoAvailableServersException.java b/gemfire-core/src/main/java/com/gemstone/gemfire/cache/client/NoAvailableServersException.java
new file mode 100644
index 0000000..23bdfaa
--- /dev/null
+++ b/gemfire-core/src/main/java/com/gemstone/gemfire/cache/client/NoAvailableServersException.java
@@ -0,0 +1,50 @@
+/*=========================================================================
+ * Copyright (c) 2002-2014 Pivotal Software, Inc. All Rights Reserved.
+ * This product is protected by U.S. and international copyright
+ * and intellectual property laws. Pivotal products are covered by
+ * more patents listed at http://www.pivotal.io/patents.
+ *=========================================================================
+ */
+package com.gemstone.gemfire.cache.client;
+
+
+/**
+ * An exception indicating that there are no active servers available to connect to.
+ * @author dsmith
+ * @since 5.7
+ */
+public class NoAvailableServersException extends ServerConnectivityException {
+ private static final long serialVersionUID = -8212446737778234890L;
+
+ /**
+ * Create a new instance of NoAvailableServersException without a detail message or cause.
+ */
+ public NoAvailableServersException() {
+ }
+
+ /**
+ * Create a new instance of NoAvailableServersException with a detail message
+ * @param message the detail message
+ */
+ public NoAvailableServersException(String message) {
+ super(message);
+ }
+
+ /**
+ * Create a new instance of NoAvailableServersException with a detail message and cause
+ * @param message the detail message
+ * @param cause the cause
+ */
+ public NoAvailableServersException(String message, Throwable cause) {
+ super(message, cause);
+ }
+
+ /**
+ * Create a new instance of NoAvailableServersException with a and cause
+ * @param cause the cause
+ */
+ public NoAvailableServersException(Throwable cause) {
+ super(cause);
+ }
+
+}
http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/19459053/gemfire-core/src/main/java/com/gemstone/gemfire/cache/client/Pool.java
----------------------------------------------------------------------
diff --git a/gemfire-core/src/main/java/com/gemstone/gemfire/cache/client/Pool.java b/gemfire-core/src/main/java/com/gemstone/gemfire/cache/client/Pool.java
new file mode 100644
index 0000000..99c318b
--- /dev/null
+++ b/gemfire-core/src/main/java/com/gemstone/gemfire/cache/client/Pool.java
@@ -0,0 +1,242 @@
+/*=========================================================================
+ * Copyright (c) 2002-2014 Pivotal Software, Inc. All Rights Reserved.
+ * This product is protected by U.S. and international copyright
+ * and intellectual property laws. Pivotal products are covered by
+ * more patents listed at http://www.pivotal.io/patents.
+ *=========================================================================
+ */
+package com.gemstone.gemfire.cache.client;
+
+import java.net.InetSocketAddress;
+import java.util.Properties;
+
+import com.gemstone.gemfire.cache.Cache;
+import com.gemstone.gemfire.cache.RegionFactory;
+import com.gemstone.gemfire.cache.query.QueryService;
+
+
+/**
+ * A pool for connections from a client to a set of GemFire Cache Servers.
+ * <p>A single instance of this interface can be created using {@link ClientCacheFactory#create}.
+ * Multiple instances may also be created using
+ * {@link PoolFactory#create}.
+ * A {@link PoolFactory} instance is created by calling
+ * {@link PoolManager#createFactory}. So to create a default <code>Pool</code> do this:
+ * <PRE>
+ new ClientCacheFactory().create();
+ * </PRE>
+ * or this:
+ * <PRE>
+ PoolManager.createFactory().create("myPool");
+ * </PRE>
+ * Instances may also be created by declaring them in cache.xml with a <code>pool</code> element.
+ * <p>Existing Pool instances can be found using {@link PoolManager#find(String)}
+ * and {@link PoolManager#getAll}.
+ * <p>The pool name must be configured
+ * on the client regions that will use this pool by calling
+ * {@link RegionFactory#setPoolName}.
+ *
+ * @author darrel
+ * @since 5.7
+ *
+ */
+public interface Pool {
+
+ /**
+ * Get the name of the connection pool
+ *
+ * @return the name of the pool
+ * @see PoolFactory#create
+ */
+ public String getName();
+
+ /**
+ * Returns the connection timeout of this pool.
+ * @see PoolFactory#setFreeConnectionTimeout
+ */
+ public int getFreeConnectionTimeout();
+ /**
+ * Returns the load conditioning interval of this pool.
+ * @see PoolFactory#setLoadConditioningInterval
+ */
+ public int getLoadConditioningInterval();
+ /**
+ * Returns the socket buffer size of this pool.
+ * @see PoolFactory#setSocketBufferSize
+ */
+ public int getSocketBufferSize();
+ /**
+ * Returns the read timeout of this pool.
+ * @see PoolFactory#setReadTimeout
+ */
+ public int getReadTimeout();
+ /**
+ * Get the minimum connections for this pool.
+ * @see PoolFactory#setMinConnections(int)
+ */
+ public int getMinConnections();
+ /**
+ * Get the maximum connections for this pool.
+ * @see PoolFactory#setMaxConnections(int)
+ */
+ public int getMaxConnections();
+ /**
+ * Get the maximum connections for this pool.
+ * @see PoolFactory#setIdleTimeout(long)
+ */
+ public long getIdleTimeout();
+ /**
+ * Get the ping interval for this pool.
+ * @see PoolFactory#setPingInterval(long)
+ */
+ public long getPingInterval();
+ /**
+ * Get the statistic interval for this pool.
+ * @see PoolFactory#setStatisticInterval(int)
+ */
+ public int getStatisticInterval();
+ /**
+ * Get the retry attempts for this pool.
+ * @see PoolFactory#setRetryAttempts(int)
+ */
+ public int getRetryAttempts();
+ /**
+ * Returns <code>true</code> if thread local connections are enabled on this pool.
+ * @see PoolFactory#setThreadLocalConnections
+ */
+ public boolean getThreadLocalConnections();
+
+ /**
+ * Returns the true if a server-to-client subscriptions are enabled on this pool.
+ * @see PoolFactory#setSubscriptionEnabled
+ */
+ public boolean getSubscriptionEnabled();
+ /**
+ * Returns true if single-hop optimisation is enabled on this pool.
+ * @see PoolFactory#setPRSingleHopEnabled
+ * @since 6.5
+ */
+ public boolean getPRSingleHopEnabled();
+ /**
+ * Returns the subscription redundancy level of this pool.
+ * @see PoolFactory#setSubscriptionRedundancy
+ */
+ public int getSubscriptionRedundancy();
+ /**
+ * Returns the subscription message tracking timeout of this pool.
+ * @see PoolFactory#setSubscriptionMessageTrackingTimeout
+ */
+ public int getSubscriptionMessageTrackingTimeout();
+ /**
+ * Returns the subscription ack interval of this pool.
+ * @see PoolFactory#setSubscriptionAckInterval(int)
+ */
+ public int getSubscriptionAckInterval();
+
+ /**
+ * Returns the server group of this pool.
+ * @see PoolFactory#setServerGroup
+ */
+ public String getServerGroup();
+ /**
+ * Returns true if multiuser mode is enabled on this pool.
+ * @see PoolFactory#setMultiuserAuthentication(boolean)
+ * @since 6.5
+ */
+ public boolean getMultiuserAuthentication();
+
+
+ /**
+ * Returns an unmodifiable list of {@link java.net.InetSocketAddress} of the
+ * locators this pool is using. Each locator is either one
+ * {@link PoolFactory#addLocator added explicitly}
+ * when the pool was created or were discovered using the explicit locators.
+ * <p> If a pool has no locators then it can not discover servers or locators at runtime.
+ */
+ public java.util.List<InetSocketAddress> getLocators();
+ /**
+ * Returns an unmodifiable list of {@link java.net.InetSocketAddress} of the
+ * servers this pool is using. These servers where either
+ * {@link PoolFactory#addServer added explicitly}
+ * when the pool was created or were discovered using this pools {@link #getLocators locators}.
+ */
+ public java.util.List<InetSocketAddress> getServers();
+
+ /**
+ * Destroys this pool closing any connections it produced.
+ * @param keepAlive
+ * whether the server should keep the durable client's
+ * subscriptions alive for the timeout period
+ * @throws IllegalStateException
+ * if the pool is still in use
+ */
+ public void destroy(boolean keepAlive);
+
+ /**
+ * Destroys this pool closing any connections it produced.
+ * @throws IllegalStateException if the pool is still in use
+ */
+ public void destroy();
+
+ /**
+ * Indicates whether this Pool has been
+ * destroyed.
+ *
+ * @return true if the pool has been destroyed
+ */
+ public boolean isDestroyed();
+
+ /**
+ * If this pool was configured to to use thread local connections,
+ * then this method will release the connection cached for the calling thread.
+ * The connection will then be available for use by other threads.
+ *
+ * If this pool is not using thread local connections, this method
+ * will have no effect.
+ */
+ public void releaseThreadLocalConnection();
+
+ /**
+ * Returns the QueryService for this Pool. The query operations performed
+ * using this QueryService will be executed on the servers that are associated
+ * with this pool.
+ *
+ * @return the QueryService
+ */
+ public QueryService getQueryService();
+
+ /**
+ * Returns the approximate number of pending subscription events maintained at
+ * server for this durable client pool at the time it (re)connected to the
+ * server. Server would start dispatching these events to this durable client
+ * pool when it receives {@link ClientCache#readyForEvents()} from it.
+ * <p>
+ * Durable clients can call this method on reconnect to assess the amount of
+ * 'stale' data i.e. events accumulated at server while this client was away
+ * and, importantly, before calling {@link ClientCache#readyForEvents()}.
+ * <p>
+ * Any number of invocations of this method during a single session will
+ * return the same value.
+ * <p>
+ * It may return a zero value if there are no events pending at server for
+ * this client pool. A negative value returned tells us that no queue was
+ * available at server for this client pool.
+ * <p>
+ * A value -1 indicates that this client pool reconnected to server after its
+ * 'durable-client-timeout' period elapsed and hence its subscription queue at
+ * server was removed, possibly causing data loss.
+ * <p>
+ * A value -2 indicates that this client pool connected to server for the
+ * first time.
+ *
+ * @return int The number of subscription events maintained at server for this
+ * durable client pool at the time this pool (re)connected. A negative
+ * value indicates no queue was found for this client pool.
+ * @throws IllegalStateException
+ * If called by a non-durable client or if invoked any time after
+ * invocation of {@link ClientCache#readyForEvents()}.
+ * @since 8.1
+ */
+ public int getPendingEventCount();
+
+}
http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/19459053/gemfire-core/src/main/java/com/gemstone/gemfire/cache/client/PoolFactory.java
----------------------------------------------------------------------
diff --git a/gemfire-core/src/main/java/com/gemstone/gemfire/cache/client/PoolFactory.java b/gemfire-core/src/main/java/com/gemstone/gemfire/cache/client/PoolFactory.java
new file mode 100644
index 0000000..3f09262
--- /dev/null
+++ b/gemfire-core/src/main/java/com/gemstone/gemfire/cache/client/PoolFactory.java
@@ -0,0 +1,462 @@
+/*=========================================================================
+ * Copyright (c) 2010-2014 Pivotal Software, Inc. All Rights Reserved.
+ * This product is protected by U.S. and international copyright
+ * and intellectual property laws. Pivotal products are covered by
+ * one or more patents listed at http://www.pivotal.io/patents.
+ *=========================================================================
+ */
+package com.gemstone.gemfire.cache.client;
+
+import com.gemstone.gemfire.cache.server.CacheServer;
+import com.gemstone.gemfire.cache.*; // for javadocs
+import com.gemstone.gemfire.cache.query.*; // for javadocs
+
+
+/**
+ * This interface provides for the configuration and creation of instances of
+ * {@link Pool}.
+ * <p>Every pool needs to have at least one {@link #addLocator locator} or {@link #addServer server} added
+ * to it. Locators should be added unless direct connections to
+ * bridge servers are desired.
+ * <p>The setter methods are used to specify
+ * non-default values for the other pool properties.
+ * <p>Once it is configured {@link #create}
+ * will produce an instance.
+ * <p>The factory can be restored to its default
+ * configuration by calling {@link #reset}.
+ * <p>Instances of this interface can be created by calling
+ * {@link PoolManager#createFactory}.
+ * <p>
+ * If a subscription is going to be made using a pool then subscriptions
+ * {@link #setSubscriptionEnabled must be enabled} on the pool.
+ * Subscriptions are made using these APIs:
+ * <ul>
+ * <li>{@link QueryService#newCq(String, CqAttributes)}
+ * <li>{@link QueryService#newCq(String, CqAttributes, boolean)}
+ * <li>{@link QueryService#newCq(String, String, CqAttributes)}
+ * <li>{@link QueryService#newCq(String, String, CqAttributes, boolean)}
+ * <li>{@link Region#registerInterest(Object)}
+ * <li>{@link Region#registerInterest(Object, boolean)}
+ * <li>{@link Region#registerInterest(Object, InterestResultPolicy)}
+ * <li>{@link Region#registerInterest(Object, InterestResultPolicy, boolean)}
+ * <li>{@link Region#registerInterestRegex(String)}
+ * <li>{@link Region#registerInterestRegex(String, boolean)}
+ * <li>{@link Region#registerInterestRegex(String, InterestResultPolicy)}
+ * <li>{@link Region#registerInterestRegex(String, InterestResultPolicy, boolean)}
+ * </ul>
+ *
+ * @author darrel
+ * @since 5.7
+ */
+public interface PoolFactory {
+ /**
+ * The default amount of time, in milliseconds, which we will wait for a free
+ * connection if max connections is set and all of the connections are in use.
+ * <p>Current value: <code>10000</code>.
+ */
+ public static final int DEFAULT_FREE_CONNECTION_TIMEOUT = 10000;
+
+ /**
+ * The default interval in which the pool will check to see if
+ * a connection to a given server should be moved to a different
+ * server to improve the load balance.
+ * <p>Current value: <code>300,000</code> (which is 5 minutes).
+ */
+ public static final int DEFAULT_LOAD_CONDITIONING_INTERVAL = 1000*60*5;
+
+ /**
+ * Default size in bytes of the socket buffer on each connection established.
+ * <p>Current value: <code>32768</code>.
+ */
+ public static final int DEFAULT_SOCKET_BUFFER_SIZE = 32768;
+
+ /**
+ * The default amount of time, in milliseconds, to wait for a response from a server
+ * <p>Current value: <code>10000</code>.
+ */
+ public static final int DEFAULT_READ_TIMEOUT = 10000;
+
+ /**
+ * The default number of connections to initially create
+ * <p>Current value: <code>1</code>.
+ */
+ public static final int DEFAULT_MIN_CONNECTIONS = 1;
+
+ /**
+ * The default maximum number of connections to create
+ * <p>Current value: <code>-1</code>.
+ */
+ public static final int DEFAULT_MAX_CONNECTIONS = -1;
+
+ /**
+ * The default amount of time in milliseconds, to wait for a connection to become idle
+ * <p>Current value: <code>5000</code>.
+ */
+ public static final long DEFAULT_IDLE_TIMEOUT = 5000;
+
+ /**
+ * The default number of times to retry an operation after a timeout or exception.
+ * <p>Current value: <code>-1</code>.
+ */
+ public static final int DEFAULT_RETRY_ATTEMPTS = -1;
+
+ /**
+ * The default frequency, in milliseconds, to ping servers.
+ * <p>Current value: <code>10000</code>.
+ */
+ public static final long DEFAULT_PING_INTERVAL = 10000;
+
+ /**
+ * The default frequency, in milliseconds, that client statistics
+ * will be sent to the server.
+ * <p>Current value: <code>-1</code>.
+ */
+ public static final int DEFAULT_STATISTIC_INTERVAL = -1;
+
+ /**
+ * The default value for whether connections should have affinity to the thread
+ * that last used them.
+ * <p>Current value: <code>false</code>.
+ */
+ public static final boolean DEFAULT_THREAD_LOCAL_CONNECTIONS = false;
+
+ /**
+ * The default value for whether to establish a server to client subscription.
+ * <p>Current value: <code>false</code>.
+ */
+ public static final boolean DEFAULT_SUBSCRIPTION_ENABLED = false;
+
+ /**
+ * The default redundancy for servers holding subscriptions established by this
+ * client
+ * <p>Current value: <code>0</code>.
+ */
+ public static final int DEFAULT_SUBSCRIPTION_REDUNDANCY = 0;
+
+ /**
+ * The default amount of time, in milliseconds, that messages sent from a
+ * server to a client will be tracked. The tracking is done to minimize
+ * duplicate events.
+ * <p>Current value: <code>900000</code>.
+ */
+ public static final int DEFAULT_SUBSCRIPTION_MESSAGE_TRACKING_TIMEOUT = 900000;
+
+ /**
+ * The default amount of time, in milliseconds, to wait before
+ * sending an acknowledgement to the server about events
+ * received from the subscriptions.
+ * <p>Current value: <code>100</code>.
+ */
+ public static final int DEFAULT_SUBSCRIPTION_ACK_INTERVAL = 100;
+
+ /**
+ * The default server group.
+ * <p>Current value: <code>""</code>.
+ */
+ public static final String DEFAULT_SERVER_GROUP = "";
+
+ /**
+ * The default value for whether to have single hop optimisations enabled.
+ * <p>Current value: <code>true</code>.
+ * @since 6.5
+ */
+ public static final boolean DEFAULT_PR_SINGLE_HOP_ENABLED = true;
+ /**
+ * The default value for whether to use multiuser mode.
+ * <p>Current value: <code>false</code>.
+ * @since 6.5
+ */
+ public static final boolean DEFAULT_MULTIUSER_AUTHENTICATION = false;
+ /**
+ * Sets the free connection timeout for this pool.
+ * If the pool has a max connections setting, operations will block
+ * if all of the connections are in use. The free connection timeout
+ * specifies how long those operations will block waiting for
+ * a free connection before receiving
+ * an {@link AllConnectionsInUseException}. If max connections
+ * is not set this setting has no effect.
+ * @see #setMaxConnections(int)
+ * @param connectionTimeout the connection timeout in milliseconds
+ * @return a reference to <code>this</code>
+ * @throws IllegalArgumentException if <code>connectionTimeout</code>
+ * is less than or equal to <code>0</code>.
+ */
+ public PoolFactory setFreeConnectionTimeout(int connectionTimeout);
+ /**
+ * Sets the load conditioning interval for this pool.
+ * This interval controls how frequently the pool will check to see if
+ * a connection to a given server should be moved to a different
+ * server to improve the load balance.
+ * <p>A value of <code>-1</code> disables load conditioning
+ * @param loadConditioningInterval the connection lifetime in milliseconds
+ * @return a reference to <code>this</code>
+ * @throws IllegalArgumentException if <code>connectionLifetime</code>
+ * is less than <code>-1</code>.
+ */
+ public PoolFactory setLoadConditioningInterval(int loadConditioningInterval);
+ /**
+ * Sets the socket buffer size for each connection made in this pool.
+ * Large messages can be received and sent faster when this buffer is larger.
+ * Larger buffers also optimize the rate at which servers can send events
+ * for client subscriptions.
+ * @param bufferSize the size of the socket buffers used for reading and
+ * writing on each connection in this pool.
+ * @return a reference to <code>this</code>
+ * @throws IllegalArgumentException if <code>bufferSize</code>
+ * is less than or equal to <code>0</code>.
+ */
+ public PoolFactory setSocketBufferSize(int bufferSize);
+ /**
+ * Sets the thread local connections policy for this pool.
+ * If <code>true</code> then any time a thread goes to use a connection
+ * from this pool it will check a thread local cache and see if it already
+ * has a connection in it. If so it will use it. If not it will get one from
+ * this pool and cache it in the thread local. This gets rid of thread contention
+ * for the connections but increases the number of connections the servers see.
+ * <p>If <code>false</code> then connections are returned to the pool as soon
+ * as the operation being done with the connection completes. This allows
+ * connections to be shared amonst multiple threads keeping the number of
+ * connections down.
+ * @param threadLocalConnections if <code>true</code> then enable thread local
+ * connections.
+ * @return a reference to <code>this</code>
+ */
+ public PoolFactory setThreadLocalConnections(boolean threadLocalConnections);
+
+ /**
+ * Sets the number of milliseconds to wait for a response from a server before
+ * timing out the operation and trying another server (if any are available).
+ * @param timeout number of milliseconds to wait for a response from a server
+ * @return a reference to <code>this</code>
+ * @throws IllegalArgumentException if <code>timeout</code>
+ * is less than <code>0</code>.
+ */
+ public PoolFactory setReadTimeout(int timeout);
+
+ /**
+ * Set the minimum number of connections to keep available at all times.
+ * When the pool is created, it will create this many connections.
+ * If <code>0</code> then connections will not be made until an actual operation
+ * is done that requires client-to-server communication.
+ * @param minConnections the initial number of connections
+ * this pool will create.
+ * @return a reference to <code>this</code>
+ * @throws IllegalArgumentException if <code>minConnections</code>
+ * is less than <code>0</code>.
+ */
+ public PoolFactory setMinConnections(int minConnections);
+
+ /**
+ * Set the max number of client to server connections that the pool will create. If all of
+ * the connections are in use, an operation requiring a client to server connection
+ * will block until a connection is available.
+ * @see #setFreeConnectionTimeout(int)
+ * @param maxConnections the maximum number of connections in the pool.
+ * this pool will create. -1 indicates that there is no maximum number of connections
+ * @return a reference to <code>this</code>
+ * @throws IllegalArgumentException if <code>maxConnections</code>
+ * is less than <code>minConnections</code>.
+ */
+ public PoolFactory setMaxConnections(int maxConnections);
+
+ /**
+ * Set the amount of time a connection can be idle before expiring the connection.
+ * If the pool size is greater than the minimum specified by
+ * {@link PoolFactory#setMinConnections(int)}, connections which have been idle
+ * for longer than the idleTimeout will be closed.
+ * @param idleTimeout The amount of time in milliseconds that an idle connection
+ * should live before expiring. -1 indicates that connections should never expire.
+ * @return a reference to <code>this</code>
+ * @throws IllegalArgumentException if <code>idleTimout</code>
+ * is less than <code>-1</code>.
+ */
+ public PoolFactory setIdleTimeout(long idleTimeout);
+
+ /**
+ * Set the number of times to retry a request after timeout/exception.
+ * @param retryAttempts The number of times to retry a request
+ * after timeout/exception. -1 indicates that a request should be
+ * tried against every available server before failing
+ * @return a reference to <code>this</code>
+ * @throws IllegalArgumentException if <code>retryAttempts</code>
+ * is less than <code>-1</code>.
+ */
+ public PoolFactory setRetryAttempts(int retryAttempts);
+
+ /**
+ * How often to ping servers to verify that they are still alive. Each
+ * server will be sent a ping every pingInterval if there has not
+ * been any other communication with the server.
+ *
+ * These pings are used by the server to monitor the health of
+ * the client. Make sure that the pingInterval is less than the
+ * maximum time between pings allowed by the bridge server.
+ * @param pingInterval The amount of time in milliseconds between
+ * pings.
+ * @return a reference to <code>this</code>
+ * @throws IllegalArgumentException if <code>pingInterval</code>
+ * is less than or equal to <code>0</code>.
+ * @see CacheServer#setMaximumTimeBetweenPings(int)
+ */
+ public PoolFactory setPingInterval(long pingInterval);
+
+ /**
+ * How often to send client statistics to the server.
+ * Doing this allows <code>gfmon</code> to monitor clients.
+ * <p>A value of <code>-1</code> disables the sending of client statistics
+ * to the server.
+ *
+ * @param statisticInterval The amount of time in milliseconds between
+ * sends of client statistics to the server.
+ * @return a reference to <code>this</code>
+ * @throws IllegalArgumentException if <code>statisticInterval</code>
+ * is less than <code>-1</code>.
+ */
+ public PoolFactory setStatisticInterval(int statisticInterval);
+
+ /**
+ * Configures the group that all servers this pool connects to must belong to.
+ * @param group the server group that this pool will connect to.
+ * If <code>null</code> or <code>""</code> then all servers will be connected to.
+ * @return a reference to <code>this</code>
+ */
+ public PoolFactory setServerGroup(String group);
+
+ /**
+ * Add a locator, given its host and port, to this factory.
+ * The locator must be a server locator and will be used to discover other running
+ * bridge servers and locators.
+ * @param host the host name or ip address that the locator is listening on.
+ * @param port the port that the locator is listening on
+ * @return a reference to <code>this</code>
+ * @throws IllegalArgumentException if <code>host</code> is an unknown host
+ * according to {@link java.net.InetAddress#getByName(String)} or if port is outside
+ * the valid range of [1..65535] inclusive.
+ * @throws IllegalStateException if a server has already been {@link #addServer added} to this factory.
+ */
+ public PoolFactory addLocator(String host, int port);
+
+ /**
+ * Add a server, given its host and port, to this factory.
+ * The server must be a bridge server and this client will
+ * directly connect to without consulting a server locator.
+ * @param host the host name or ip address that the server is listening on.
+ * @param port the port that the server is listening on
+ * @return a reference to <code>this</code>
+ * @throws IllegalArgumentException if <code>host</code> is an unknown host
+ * according to {@link java.net.InetAddress#getByName(String)} or if port is outside
+ * the valid range of [1..65535] inclusive.
+ * @throws IllegalStateException if a locator has already been {@link #addLocator added} to this factory.
+ */
+ public PoolFactory addServer(String host, int port);
+
+ /**
+ * If set to <code>true</code> then the created pool will have server-to-client
+ * subscriptions enabled.
+ * If set to <code>false</code> then all <code>Subscription*</code> attributes
+ * are ignored at create time.
+ * @return a reference to <code>this</code>
+ */
+ public PoolFactory setSubscriptionEnabled(boolean enabled);
+
+ /**
+ * Sets the redundancy level for this pools server-to-client subscriptions.
+ * If <code>0</code> then no redundant copies will be kept on the servers.
+ * Otherwise an effort will be made to maintain the requested number of
+ * copies of the server-to-client subscriptions. At most one copy per server will
+ * be made up to the requested level.
+ * @param redundancy the number of redundant servers for this client's subscriptions.
+ * @return a reference to <code>this</code>
+ * @throws IllegalArgumentException if <code>redundancyLevel</code>
+ * is less than <code>-1</code>.
+ */
+ public PoolFactory setSubscriptionRedundancy(int redundancy);
+ /**
+ * Sets the messageTrackingTimeout attribute which is the time-to-live period, in
+ * milliseconds, for subscription events the client has received from the server. It's used
+ * to minimize duplicate events.
+ * Entries that have not been modified for this amount of time
+ * are expired from the list
+ * @param messageTrackingTimeout number of milliseconds to set the timeout to.
+ * @return a reference to <code>this</code>
+ * @throws IllegalArgumentException if <code>messageTrackingTimeout</code>
+ * is less than or equal to <code>0</code>.
+ */
+ public PoolFactory setSubscriptionMessageTrackingTimeout(int messageTrackingTimeout);
+
+ /**
+ * Sets the interval in milliseconds
+ * to wait before sending acknowledgements to the bridge server for
+ * events received from the server subscriptions.
+ *
+ * @param ackInterval number of milliseconds to wait before sending event
+ * acknowledgements.
+ * @return a reference to <code>this</code>
+ * @throws IllegalArgumentException if <code>ackInterval</code>
+ * is less than or equal to <code>0</code>.
+ */
+ public PoolFactory setSubscriptionAckInterval(int ackInterval);
+
+ /**
+ * Resets the configuration of this factory to its defaults.
+ * @return a reference to <code>this</code>
+ */
+ public PoolFactory reset();
+
+ /**
+ * Create a new Pool for connecting a client to a set of GemFire Cache Servers.
+ * using this factory's settings for attributes.
+ *
+ * @param name the name of the pool, used when connecting regions to it
+ * @throws IllegalStateException if a pool with <code>name</code> already exists
+ * @throws IllegalStateException if a locator or server has not been added.
+ * @return the newly created pool.
+ */
+ public Pool create(String name);
+
+ /**
+ * By default setPRSingleHopEnabled is <code>true</code>
+ * in which case the client is aware of the location of partitions on servers hosting
+ * {@link Region regions} with
+ * {@link com.gemstone.gemfire.cache.DataPolicy#PARTITION}.
+ * Using this information, the client routes the client cache operations
+ * directly to the server which is hosting the required partition for the
+ * cache operation using a single network hop.
+ * This mode works best
+ * when {@link #setMaxConnections(int)} is set
+ * to <code>-1</code> which is the default.
+ * This mode causes the client to have more connections to the servers.
+ * <p>
+ * If setPRSingleHopEnabled is <code>false</code> the client may need to do an extra network hop on servers
+ * to go to the required partition for that cache operation.
+ * The client will use fewer network connections to the servers.
+ * <p>
+ * Caution: for {@link com.gemstone.gemfire.cache.DataPolicy#PARTITION partition} regions
+ * with
+ * {@link com.gemstone.gemfire.cache.PartitionAttributesFactory#setLocalMaxMemory(int) local-max-memory}
+ * equal to zero, no cache operations mentioned above will be routed to those
+ * servers as they do not host any partitions.
+ *
+ * @return a reference to <code>this</code>
+ * @since 6.5
+ */
+ public PoolFactory setPRSingleHopEnabled(boolean enabled);
+
+ /**
+ * If set to <code>true</code> then the created pool can be used by multiple
+ * authenticated users. <br>
+ *
+ * This setting should only be used for applications that require the client
+ * to authenticate itself with the server multiple users.
+ *
+ * <br>
+ * Note: If set to true, all the client side regions must have their
+ * data-policy set to empty.
+ *
+ * @return a reference to <code>this</code>
+ * @see ClientCache#createAuthenticatedView(java.util.Properties)
+ * @since 6.5
+ */
+ public PoolFactory setMultiuserAuthentication(boolean enabled);
+
+}