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:31 UTC
[26/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/AttributesMutator.java
----------------------------------------------------------------------
diff --git a/gemfire-core/src/main/java/com/gemstone/gemfire/cache/AttributesMutator.java b/gemfire-core/src/main/java/com/gemstone/gemfire/cache/AttributesMutator.java
new file mode 100644
index 0000000..e5bfdb1
--- /dev/null
+++ b/gemfire-core/src/main/java/com/gemstone/gemfire/cache/AttributesMutator.java
@@ -0,0 +1,194 @@
+/*=========================================================================
+ * 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;
+
+
+/**
+ * Supports modification of certain region attributes after the region has been
+ * created. It is recommended that the attributes be completely initialized
+ * using an {@link AttributesFactory} before creating the region instead of
+ * using an <code>AttributesMutator</code> after region creation. This will
+ * avoid a potential performance penalty due to the additional
+ * network traffic.
+ *<p>
+ * The setter methods all return the previous value of the attribute.
+ *
+ * @author Eric Zoerner
+ *
+ *
+ * @see Region#getAttributesMutator
+ * @see RegionAttributes
+ * @see AttributesFactory
+ * @since 3.0
+ */
+public interface AttributesMutator<K,V> {
+
+ /** Returns the Region whose attributes this mutator affects.
+ * @return the Region this mutator affects
+ */
+ public Region<K,V> getRegion();
+
+ /** Changes the timeToLive expiration attributes for the region as a whole
+ *
+ * @param timeToLive the expiration attributes for the region timeToLive
+ * @return the previous value of region timeToLive
+ * @throws IllegalArgumentException if timeToLive is null or if the
+ * ExpirationAction is LOCAL_INVALIDATE and the region is
+ * {@link DataPolicy#withReplication replicated}
+ * @throws IllegalStateException if statistics are disabled for this region.
+ */
+ public ExpirationAttributes setRegionTimeToLive(ExpirationAttributes timeToLive);
+
+ /** Changes the idleTimeout expiration attributes for the region as a whole.
+ * Resets the {@link CacheStatistics#getLastAccessedTime} for the region.
+ *
+ * @param idleTimeout the ExpirationAttributes for this region idleTimeout
+ * @return the previous value of region idleTimeout
+ * @throws IllegalArgumentException if idleTimeout is null or if the
+ * ExpirationAction is LOCAL_INVALIDATE and the region is
+ * {@link DataPolicy#withReplication replicated}
+ * @throws IllegalStateException if statistics are disabled for this region.
+ */
+ public ExpirationAttributes setRegionIdleTimeout(ExpirationAttributes idleTimeout);
+
+ /** Changes the timeToLive expiration attributes for values in this region.
+ *
+ * @param timeToLive the timeToLive expiration attributes for entries
+ * @return the previous value of entry timeToLive
+ * @throws IllegalArgumentException if timeToLive is null or if the
+ * ExpirationAction is LOCAL_DESTROY and the region is {@link DataPolicy#withReplication replicated} or if
+ * the ExpirationAction is LOCAL_INVALIDATE and the region is
+ * {@link DataPolicy#withReplication replicated}
+ * @throws IllegalStateException if statistics are disabled for this region.
+ */
+ public ExpirationAttributes setEntryTimeToLive(ExpirationAttributes timeToLive);
+
+ /**
+ * Changes the custom timeToLive for values in this region
+ * @param custom the new CustomExpiry
+ * @return the old CustomExpiry
+ */
+ public CustomExpiry<K,V> setCustomEntryTimeToLive(CustomExpiry<K,V> custom);
+
+ /** Changes the idleTimeout expiration attributes for values in the region.
+ *
+ * @param idleTimeout the idleTimeout expiration attributes for entries
+ * @return the previous value of entry idleTimeout
+ * @throws IllegalArgumentException if idleTimeout is null or if the
+ * ExpirationAction is LOCAL_DESTROY and the region is
+ * {@link DataPolicy#withReplication replicated}
+ * or if the the ExpirationAction is LOCAL_INVALIDATE and the region is
+ * {@link DataPolicy#withReplication replicated}
+ * @see AttributesFactory#setStatisticsEnabled
+ * @throws IllegalStateException if statistics are disabled for this region.
+ */
+ public ExpirationAttributes setEntryIdleTimeout(ExpirationAttributes idleTimeout);
+
+ /** Changes the CustomExpiry for idleTimeout for values in the region
+ *
+ * @param custom the new CustomExpiry
+ * @return the old CustomExpiry
+ */
+ public CustomExpiry<K,V> setCustomEntryIdleTimeout(CustomExpiry<K,V> custom);
+
+ /** Changes the CacheListener for the region.
+ * Removes listeners already added and calls {@link CacheCallback#close} on each of them.
+ * @param aListener a user defined cache listener
+ * @return the previous CacheListener if a single one exists; otherwise null.
+ * @throws IllegalStateException if more than one cache listener has already been added
+ * @deprecated as of GemFire 5.0, use {@link #addCacheListener} or {@link #initCacheListeners} instead.
+ */
+ @Deprecated
+ public CacheListener<K,V> setCacheListener(CacheListener<K,V> aListener);
+ /**
+ * Adds a cache listener to the end of the list of cache listeners on this region.
+ * @param aListener the user defined cache listener to add to the region.
+ * @throws IllegalArgumentException if <code>aListener</code> is null
+ * @since 5.0
+ */
+ public void addCacheListener(CacheListener<K,V> aListener);
+ /**
+ * Removes a cache listener from the list of cache listeners on this region.
+ * Does nothing if the specified listener has not been added.
+ * If the specified listener has been added then {@link CacheCallback#close} will
+ * be called on it; otherwise does nothing.
+ * @param aListener the cache listener to remove from the region.
+ * @throws IllegalArgumentException if <code>aListener</code> is null
+ * @since 5.0
+ */
+ public void removeCacheListener(CacheListener<K,V> aListener);
+ /**
+ * Removes all cache listeners, calling {@link CacheCallback#close} on each of them, and then adds each listener in the specified array.
+ * @param newListeners a possibly null or empty array of listeners to add to this region.
+ * @throws IllegalArgumentException if the <code>newListeners</code> array has a null element
+ * @since 5.0
+ */
+ public void initCacheListeners(CacheListener<K,V>[] newListeners);
+
+ /** Changes the cache writer for the region.
+ * @param cacheWriter the cache writer
+ * @return the previous CacheWriter
+ */
+ public CacheWriter<K,V> setCacheWriter(CacheWriter<K,V> cacheWriter);
+
+ /** Changes the cache loader for the region.
+ * @param cacheLoader the cache loader
+ * @return the previous CacheLoader
+ */
+ public CacheLoader<K,V> setCacheLoader(CacheLoader<K,V> cacheLoader);
+
+
+ /** Allows changing the eviction controller attributes for the region.
+ *
+ * @return the {@link EvictionAttributesMutator} used to change the EvictionAttributes
+ */
+ public EvictionAttributesMutator getEvictionAttributesMutator();
+
+ /**
+ * Sets cloning on region
+ * @param cloningEnable
+ * @since 6.1
+ */
+ public void setCloningEnabled(boolean cloningEnable);
+ /**
+ * Returns whether or not cloning is enabled on region
+ *
+ * @return True if cloning is enabled (default);
+ * false cloning is not enabled.
+ *
+ * @since 6.1
+ */
+ public boolean getCloningEnabled();
+
+ /**
+ * Adds GatewaySenderId to the list of GatewaySenderIds of the region.
+ * If the GatewaySenderId is not present on this VM then it will try to send it to other VM's
+ *
+ * @param gatewaySenderId
+ */
+ public void addGatewaySenderId(String gatewaySenderId);
+
+ /**
+ * Removes GatewaySenderId from the list of GatewaySenderIds of the region.
+ * @param gatewaySenderId
+ */
+ public void removeGatewaySenderId(String gatewaySenderId);
+
+ /**
+ * Adds AsyncEventQueueId to the list of AsyncEventQueueId of the region.
+ * @param asyncEventQueueId
+ */
+ public void addAsyncEventQueueId(String asyncEventQueueId);
+
+ /**
+ * Removes AsyncEventQueueId from the list of AsyncEventQueuesId of the region.
+ * @param asyncEventQueueId
+ */
+ public void removeAsyncEventQueueId(String asyncEventQueueId);
+}
http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/19459053/gemfire-core/src/main/java/com/gemstone/gemfire/cache/Cache.java
----------------------------------------------------------------------
diff --git a/gemfire-core/src/main/java/com/gemstone/gemfire/cache/Cache.java b/gemfire-core/src/main/java/com/gemstone/gemfire/cache/Cache.java
new file mode 100644
index 0000000..4389fda
--- /dev/null
+++ b/gemfire-core/src/main/java/com/gemstone/gemfire/cache/Cache.java
@@ -0,0 +1,474 @@
+/*=========================================================================
+ * 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;
+
+import java.util.List;
+import java.util.Set;
+import java.util.concurrent.TimeUnit;
+
+import com.gemstone.gemfire.cache.asyncqueue.AsyncEventQueue;
+import com.gemstone.gemfire.cache.asyncqueue.AsyncEventQueueFactory;
+import com.gemstone.gemfire.cache.client.ClientCache;
+import com.gemstone.gemfire.cache.client.Pool;
+import com.gemstone.gemfire.cache.server.CacheServer;
+import com.gemstone.gemfire.cache.snapshot.CacheSnapshotService;
+import com.gemstone.gemfire.cache.util.BridgeServer;
+import com.gemstone.gemfire.cache.util.GatewayConflictResolver;
+import com.gemstone.gemfire.cache.wan.GatewayReceiver;
+import com.gemstone.gemfire.cache.wan.GatewayReceiverFactory;
+import com.gemstone.gemfire.cache.wan.GatewaySender;
+import com.gemstone.gemfire.cache.wan.GatewaySenderFactory;
+import com.gemstone.gemfire.distributed.DistributedMember;
+import com.gemstone.gemfire.distributed.DistributedSystem;
+import com.gemstone.gemfire.i18n.LogWriterI18n;
+
+
+/**
+ * Caches are obtained from the {@link CacheFactory#create()} method.
+ * See {@link CacheFactory} for common usage patterns for creating the cache instance.
+ * <p>
+ * When a cache is created a {@link DistributedSystem} is also created.
+ * This system tells the cache where to find other caches on the network
+ * and how to communicate with them.
+ * The system can also specify a
+ * <a href="../distribution/DistributedSystem.html#cache-xml-file">"cache-xml-file"</a>
+ * property which will cause this cache to be initialized with the contents
+ * of that file. The contents must comply with the
+ * <code>"doc-files/cache8_0.dtd"</code> file
+ * and the top level element must be a <code>cache</code> element.
+ * <p>
+ * When a cache will no longer be used it should be {@link #close() closed}.
+ * Once it {@link #isClosed is closed} any attempt to use it or any {@link Region}
+ * obtained from it will cause a {@link CacheClosedException} to be thrown.
+ *
+ * <p>A cache can have multiple root regions, each with a different name.
+ *
+ * @author Darrel Schneider
+ *
+ * @since 2.0
+ */
+@SuppressWarnings("deprecation")
+public interface Cache extends GemFireCache {
+ /**
+ * Terminates this object cache and releases all the resources.
+ * Calls {@link Region#close} on each region in the cache.
+ * After this cache is closed, any further
+ * method call on this cache or any region object will throw
+ * {@link CacheClosedException}, unless otherwise noted.
+ * @param keepalive whether the server should keep the durable client's queues alive for the timeout period
+ * @throws CacheClosedException if the cache is already closed.
+ * @deprecated as of 6.5 use {@link ClientCache#close(boolean)} instead.
+ */
+ @Deprecated
+ public void close(boolean keepalive);
+
+ /**
+ * Creates a VM region using the specified
+ * RegionAttributes.
+ *
+ * @param name the name of the region to create
+ * @param aRegionAttributes the attributes of the root region
+ * @return the region object
+ * @throws RegionExistsException if a region is already in
+ * this cache
+ * @throws com.gemstone.gemfire.distributed.LeaseExpiredException if lease expired on distributed lock for Scope.GLOBAL
+ * @throws TimeoutException if timed out getting distributed lock for Scope.GLOBAL
+ * @throws CacheClosedException if the cache is closed
+ * @throws IllegalStateException If the supplied RegionAttributes violate the
+ * <a href="AttributesFactory.html#creationConstraints">region creation constraints</a>
+ * with a region of the same name in another cache in the distributed system
+ * @deprecated as of GemFire 5.0, use {@link #createRegion} instead.
+ */
+ @Deprecated
+ public <K,V> Region<K,V> createVMRegion(String name, RegionAttributes<K,V> aRegionAttributes)
+ throws RegionExistsException, TimeoutException;
+
+ /**
+ * Creates a region using the specified RegionAttributes.
+ *
+ * @param name the name of the region to create
+ * @param aRegionAttributes the attributes of the root region
+ * @return the region object
+ * @throws RegionExistsException if a region is already in this cache
+ * @throws com.gemstone.gemfire.distributed.LeaseExpiredException if lease expired on distributed lock for Scope.GLOBAL
+ * @throws TimeoutException if timed out getting distributed lock for Scope.GLOBAL
+ * @throws CacheClosedException if the cache is closed
+ * @throws IllegalStateException If the supplied RegionAttributes violate the
+ * <a href="AttributesFactory.html#creationConstraints">region creation constraints</a>
+ * with a region of the same name in another cache in the distributed system
+ * @since 5.0
+ * @deprecated as of 6.5 use {@link #createRegionFactory(RegionAttributes)} instead
+ */
+ @Deprecated
+ public <K,V> Region<K,V> createRegion(String name, RegionAttributes<K,V> aRegionAttributes)
+ throws RegionExistsException, TimeoutException;
+
+ /**
+ * Creates a {@link RegionFactory} which can be used to specify additional
+ * attributes for {@link Region} creation.
+ * @see #createRegionFactory(RegionShortcut)
+ * @since 6.5
+ */
+ public <K,V> RegionFactory<K,V> createRegionFactory();
+
+ /**
+ * Creates a {@link RegionFactory} for the most commonly used {@link Region} types
+ * defined by {@link RegionShortcut}
+ * @since 6.5
+ */
+ public <K,V> RegionFactory<K,V> createRegionFactory(RegionShortcut atts);
+
+ /**
+ * Creates a {@link RegionFactory} for creating a {@link Region} from
+ * {@link RegionAttributes} mapped to this regionAttributesId
+ * @param regionAttributesId the Id of RegionAttributes to be used
+ * @see #setRegionAttributes(String, RegionAttributes)
+ * @since 6.5
+ */
+ public <K,V> RegionFactory<K,V> createRegionFactory(String regionAttributesId);
+
+ /**
+ * Creates a {@link RegionFactory} for creating a {@link Region} from
+ * the given regionAttributes
+ * @param regionAttributes regionAttributes for the new region
+ * @see #createRegionFactory(RegionShortcut)
+ * @since 6.5
+ */
+ public <K,V> RegionFactory<K,V> createRegionFactory(RegionAttributes<K,V> regionAttributes);
+
+ /**
+ * Internal GemStone method for accessing the internationalized
+ * logging object for GemFire, use {@link #getLogger()} instead.
+ * This method does not throw
+ * <code>CacheClosedException</code> if the cache is closed.
+ * @return the logging object
+ * @deprecated as of 6.5 use getLogger().convertToLogWriterI18n() instead
+ */
+ @Deprecated
+ public LogWriterI18n getLoggerI18n();
+
+ /**
+ * Internal GemStone method for accessing the internationalized
+ * logging object for GemFire, use {@link #getSecurityLogger()} instead.
+ * This method does not throw
+ * <code>CacheClosedException</code> if the cache is closed.
+ * @return the security logging object
+ * @deprecated as of 6.5 use getSecurityLogger().convertToLogWriterI18n() instead
+ */
+ @Deprecated
+ public LogWriterI18n getSecurityLoggerI18n();
+
+ /**
+ * Gets the number of seconds a cache operation will wait to obtain
+ * a distributed lock lease.
+ * This method does not throw
+ * <code>CacheClosedException</code> if the cache is closed.
+ */
+ public int getLockTimeout();
+ /**
+ * Sets the number of seconds a cache operation may wait to obtain a
+ * distributed lock lease before timing out.
+ *
+ * @throws IllegalArgumentException if <code>seconds</code> is less than zero
+ */
+ public void setLockTimeout(int seconds);
+
+ /**
+ * Gets the frequency (in seconds) at which a message will be sent by the
+ * primary cache-server to all the secondary cache-server nodes to remove the
+ * events which have already been dispatched from the queue.
+ *
+ * @return The time interval in seconds
+ */
+ public int getMessageSyncInterval();
+
+ /**
+ * Sets the frequency (in seconds) at which a message will be sent by the
+ * primary cache-server node to all the secondary cache-server nodes to remove
+ * the events which have already been dispatched from the queue.
+ *
+ * @param seconds -
+ * the time interval in seconds
+ * @throws IllegalArgumentException
+ * if <code>seconds</code> is less than zero
+ */
+ public void setMessageSyncInterval(int seconds);
+
+ /**
+ * Gets the length, in seconds, of distributed lock leases obtained
+ * by this cache.
+ * This method does not throw
+ * <code>CacheClosedException</code> if the cache is closed.
+ */
+ public int getLockLease();
+ /**
+ * Sets the length, in seconds, of distributed lock leases obtained
+ * by this cache.
+ *
+ * @throws IllegalArgumentException if <code>seconds</code> is less than zero.
+ */
+ public void setLockLease(int seconds);
+
+ /**
+ * Gets the number of seconds a cache
+ * {@link com.gemstone.gemfire.cache.Region#get(Object) get} operation
+ * can spend searching for a value before it times out.
+ * The search includes any time spent loading the object.
+ * When the search times out it causes the get to fail by throwing
+ * an exception.
+ * This method does not throw
+ * <code>CacheClosedException</code> if the cache is closed.
+ */
+ public int getSearchTimeout();
+ /**
+ * Sets the number of seconds a cache get operation can spend searching
+ * for a value.
+ *
+ * @throws IllegalArgumentException if <code>seconds</code> is less than zero
+ */
+ public void setSearchTimeout(int seconds);
+
+ /**
+ * Creates a new bridge server with the default configuration.
+ *
+ * @see com.gemstone.gemfire.cache.util.BridgeLoader
+ * @see com.gemstone.gemfire.cache.util.BridgeWriter
+ *
+ * @since 4.0
+ * @deprecated as of 5.7 use {@link #addCacheServer} instead.
+ */
+ @Deprecated
+ public BridgeServer addBridgeServer();
+
+ /**
+ * Creates a new cache server, with the default configuration,
+ * that will allow clients to access this cache.
+ * <p>For the default configuration see the constants in
+ * {@link com.gemstone.gemfire.cache.server.CacheServer}.
+ * @see com.gemstone.gemfire.cache.server
+ *
+ * @since 5.7
+ */
+ public CacheServer addCacheServer();
+
+ /**
+ * Returns a collection of all of the <code>BridgeServer</code>s
+ * that can serve the contents of this <code>Cache</code>.
+ * <p>Since <code>5.7</code> this method returns a <code>List</code
+ * instead of a <code>Collection</code>.
+ *
+ * @see #addBridgeServer
+ *
+ * @since 4.0
+ * @deprecated as of 5.7 use {@link #getCacheServers} instead.
+ */
+ @Deprecated
+ public List<CacheServer> getBridgeServers();
+
+ /**
+ * Returns a collection of all of the <code>CacheServer</code>s
+ * that can serve the contents of this <code>Cache</code> to clients.
+ *
+ * @see #addCacheServer
+ *
+ * @since 5.7
+ */
+ public List<CacheServer> getCacheServers();
+
+ /**
+ * Adds a gateway event conflict resolution resolver. This is invoked
+ * if an event is processed that comes from a different distributed system
+ * than the last event to modify the affected entry. It may alter
+ * the event or disallow the event. If it does neither the event is applied
+ * to the cache if its timestamp is newer than what is in the cache or if
+ * it is the same and the event's distributed system ID is larger than that
+ * of the last event to modify the affected entry.
+ * @param resolver
+ * @since 7.0
+ */
+ public void setGatewayConflictResolver(GatewayConflictResolver resolver);
+
+ /**
+ * Returns the current gateway event conflict resolver
+ * @since 7.0
+ */
+ public GatewayConflictResolver getGatewayConflictResolver();
+
+ /**
+ * Sets whether or not this <code>Cache</code> resides in a
+ * long-running "cache server" VM. A cache server may be an
+ * application VM or may be a stand-along VM launched using {@linkplain
+ * com.gemstone.gemfire.admin.AdminDistributedSystem#addCacheServer
+ * administration API} or the <code>cacheserver</code> command line
+ * utility.
+ *
+ * @since 4.0
+ */
+ public void setIsServer(boolean isServer);
+
+ /**
+ * Returns whether or not this cache resides in a "cache server" VM.
+ *
+ * @see #setIsServer
+ *
+ * @since 4.0
+ */
+ public boolean isServer();
+
+ /**
+ * Notifies the server that this client is ready to receive updates.
+ * This method is used by durable clients to notify servers that they
+ * are ready to receive updates. As soon as the server receives this message,
+ * it will forward updates to this client (if necessary).
+ * <p>
+ * Durable clients must call this method after they are done creating regions.
+ * If it is called before the client creates the regions then updates will be lost.
+ * Any time a new {@link Pool} is created and regions have been added to it then
+ * this method needs to be called again.
+ * <p>
+ *
+ * @throws IllegalStateException if called by a non-durable client
+ *
+ * @since 5.5
+ * @deprecated as of 6.5 use {@link ClientCache#readyForEvents} instead.
+ */
+ @Deprecated
+ public void readyForEvents();
+
+ /**
+ * Creates {@link GatewaySenderFactory} for creating a
+ * SerialGatewaySender
+ *
+ * @return SerialGatewaySenderFactory
+ * @since 7.0
+ */
+ public GatewaySenderFactory createGatewaySenderFactory();
+
+ /**
+ * Creates {@link AsyncEventQueueFactory} for creating a
+ * AsyncEventQueue
+ *
+ * @return AsyncEventQueueFactory
+ * @since 7.0
+ */
+ public AsyncEventQueueFactory createAsyncEventQueueFactory();
+
+ /**
+ * Creates {@link GatewayReceiverFactory} for creating a GatewayReceiver
+ *
+ * @return GatewayReceiverFactory
+ * @since 7.0
+ */
+ public GatewayReceiverFactory createGatewayReceiverFactory();
+
+ /**
+ * Returns all {@link GatewaySender}s for this Cache.
+ *
+ * @return Set of GatewaySenders
+ * @since 7.0
+ */
+ public Set<GatewaySender> getGatewaySenders();
+
+ /**
+ * Returns the {@link GatewaySender} with the given id added to this Cache.
+ *
+ * @return GatewaySender with id
+ * @since 7.0
+ */
+ public GatewaySender getGatewaySender(String id);
+ /**
+ * Returns all {@link GatewayReceiver}s for this Cache
+ *
+ * @return Set of GatewaySenders
+ * @since 7.0
+ */
+ public Set<GatewayReceiver> getGatewayReceivers();
+
+ /**
+ * Returns all {@link AsyncEventQueue}s for this Cache
+ *
+ * @return Set of AsyncEventQueue
+ * @since 7.0
+ */
+ public Set<AsyncEventQueue> getAsyncEventQueues();
+
+ /**
+ * Returns the {@link AsyncEventQueue} with the given id added to this Cache.
+ *
+ * @return AsyncEventQueue with id
+ * @since 7.0
+ */
+ public AsyncEventQueue getAsyncEventQueue(String id);
+
+ /**
+ * Returns a set of the other non-administrative members in the distributed system.
+ * @since 6.6
+ */
+ public Set<DistributedMember> getMembers();
+
+ /**
+ * Returns a set of the administrative members in the distributed system.
+ * @since 6.6
+ */
+ public Set<DistributedMember> getAdminMembers();
+
+ /**
+ * Returns a set of the members in the distributed system that have the
+ * given region. For regions with local scope an empty set is returned.
+ * @param r a Region in the cache
+ * @since 6.6
+ */
+ public Set<DistributedMember> getMembers(Region r);
+
+ /**
+ * Obtains the snapshot service to allow the cache data to be imported
+ * or exported.
+ *
+ * @return the snapshot service
+ */
+ public CacheSnapshotService getSnapshotService();
+
+ /**
+ * Test to see whether the Cache is in the process of reconnecting
+ * and recreating a new cache after it has been removed from the system
+ * by other members or has shut down due to missing Roles and is reconnecting.<p>
+ * This will also return true if the Cache has finished reconnecting.
+ * When reconnect has completed you can use {@link Cache#getReconnectedCache} to
+ * retrieve the new cache instance.
+ *
+ * @return true if the Cache is attempting to reconnect or has finished reconnecting
+ */
+ public boolean isReconnecting();
+
+ /**
+ * Wait for the Cache to finish reconnecting to the distributed system
+ * and recreate a new Cache.
+ * @see #getReconnectedCache
+ * @param time amount of time to wait, or -1 to wait forever
+ * @param units
+ * @return true if the cache was reconnected
+ * @throws InterruptedException if the thread is interrupted while waiting
+ */
+ public boolean waitUntilReconnected(long time, TimeUnit units) throws InterruptedException;
+
+ /**
+ * Force the Cache to stop reconnecting. If the Cache
+ * is currently connected this will disconnect and close it.
+ *
+ */
+ public void stopReconnecting();
+
+ /**
+ * Returns the new Cache if there was an auto-reconnect and the cache was
+ * recreated.
+ */
+ public Cache getReconnectedCache();
+
+}
+
http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/19459053/gemfire-core/src/main/java/com/gemstone/gemfire/cache/CacheCallback.java
----------------------------------------------------------------------
diff --git a/gemfire-core/src/main/java/com/gemstone/gemfire/cache/CacheCallback.java b/gemfire-core/src/main/java/com/gemstone/gemfire/cache/CacheCallback.java
new file mode 100644
index 0000000..82e52f9
--- /dev/null
+++ b/gemfire-core/src/main/java/com/gemstone/gemfire/cache/CacheCallback.java
@@ -0,0 +1,38 @@
+/*=========================================================================
+ * 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;
+
+/**
+ * User-defined objects that can be plugged into caching to receive callback
+ * notifications.
+ *
+ * @author Eric Zoerner
+ *
+ * @since 3.0
+ */
+public interface CacheCallback {
+ /** Called when the region containing this callback is closed or destroyed, when
+ * the cache is closed, or when a callback is removed from a region
+ * using an <code>AttributesMutator</code>.
+ *
+ * <p>Implementations should cleanup any external
+ * resources such as database connections. Any runtime exceptions this method
+ * throws will be logged.
+ *
+ * <p>It is possible for this method to be called multiple times on a single
+ * callback instance, so implementations must be tolerant of this.
+ *
+ * @see Cache#close()
+ * @see Region#close
+ * @see Region#localDestroyRegion()
+ * @see Region#destroyRegion()
+ * @see AttributesMutator
+ */
+ public void close();
+}
http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/19459053/gemfire-core/src/main/java/com/gemstone/gemfire/cache/CacheClosedException.java
----------------------------------------------------------------------
diff --git a/gemfire-core/src/main/java/com/gemstone/gemfire/cache/CacheClosedException.java b/gemfire-core/src/main/java/com/gemstone/gemfire/cache/CacheClosedException.java
new file mode 100644
index 0000000..8df8228
--- /dev/null
+++ b/gemfire-core/src/main/java/com/gemstone/gemfire/cache/CacheClosedException.java
@@ -0,0 +1,68 @@
+/*=========================================================================
+ * 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;
+
+import com.gemstone.gemfire.CancelException;
+import com.gemstone.gemfire.internal.cache.GemFireCacheImpl;
+
+/**
+ * Indicates that the caching system has
+ * been closed. Can be thrown from almost any method related to regions or the
+ * <code>Cache</code> after the cache has been closed.
+ *
+ * @author Eric Zoerner
+ *
+ *
+ * @see Cache
+ * @since 3.0
+ */
+public class CacheClosedException extends CancelException {
+private static final long serialVersionUID = -6479561694497811262L;
+
+ /**
+ * Constructs a new <code>CacheClosedException</code>.
+ */
+ public CacheClosedException() {
+ super();
+ }
+
+ /**
+ * Constructs a new <code>CacheClosedException</code> with a message string.
+ *
+ * @param msg a message string
+ */
+ public CacheClosedException(String msg) {
+ super(msg);
+ // bug #43108 - CacheClosedException should include cause of closure
+ GemFireCacheImpl cache = GemFireCacheImpl.getInstance();
+ if (cache != null) {
+ initCause(cache.getDisconnectCause());
+ }
+ }
+
+ /**
+ * Constructs a new <code>CacheClosedException</code> with a message string
+ * and a cause.
+ *
+ * @param msg the message string
+ * @param cause a causal Throwable
+ */
+ public CacheClosedException(String msg, Throwable cause) {
+ super(msg, cause);
+ }
+
+ /**
+ * Constructs a new <code>CacheClosedException</code> with a cause.
+ *
+ * @param cause a causal Throwable
+ */
+ public CacheClosedException(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/CacheEvent.java
----------------------------------------------------------------------
diff --git a/gemfire-core/src/main/java/com/gemstone/gemfire/cache/CacheEvent.java b/gemfire-core/src/main/java/com/gemstone/gemfire/cache/CacheEvent.java
new file mode 100644
index 0000000..5c99dc2
--- /dev/null
+++ b/gemfire-core/src/main/java/com/gemstone/gemfire/cache/CacheEvent.java
@@ -0,0 +1,101 @@
+/*=========================================================================
+ * 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;
+
+import com.gemstone.gemfire.distributed.DistributedMember;
+import com.gemstone.gemfire.internal.cache.EnumListenerEvent;
+
+/**
+ * A region- or entry-related event affecting the cache.
+ * <P>
+ * Prior to release <code>6.0</code> the <code>NOT_AVAILABLE</code> constant
+ * was used to indicate an object value was not available.
+ * However in <code>6.0</code> generic typing was added
+ * to {@link Region} and since this constant's type will not be an
+ * instance of the generic type <code>V</code> returning it would cause
+ * a ClassCastException. So in <code>6.0</code> and later
+ * <code>null</code> is now used in place of <code>NOT_AVAILABLE</code>.
+ *
+ * @see CacheListener
+ *
+ * @author Eric Zoerner
+ *
+ *
+ * @since 2.0
+ */
+public interface CacheEvent<K,V> {
+
+ /** Returns the region to which this cached object belongs or
+ * the region that raised this event for <code>RegionEvent</code>s.
+ * @return the region associated with this object or the region that raised
+ * this event.
+ */
+ public Region<K,V> getRegion();
+
+ /**
+ * Return a description of the operation that triggered this event.
+ * @return the operation that triggered this event.
+ * @since 5.0
+ */
+ public Operation getOperation();
+
+ /** Returns the callbackArgument passed to the method that generated this event.
+ * Provided primarily in case this object or region has already been
+ * destroyed. See the {@link Region} interface methods that take a
+ * callbackArgument parameter.
+ * @return the callbackArgument associated with this event. <code>null</code>
+ * is returned if the callback argument is not propagated to the event.
+ * This happens for events given to {@link TransactionListener}
+ * and to {@link CacheListener} on the remote side of a transaction commit.
+ */
+ public Object getCallbackArgument();
+ /**
+ * Returns <code>true</code> if the callback argument is "available".
+ * Not available means that the callback argument may have existed but it could
+ * not be obtained.
+ * Note that {@link #getCallbackArgument} will return <code>null</code>
+ * when this method returns <code>false</code>.
+ * @since 6.0
+ */
+ public boolean isCallbackArgumentAvailable();
+
+ /** Answer true if this event originated in a cache other than this one.
+ * Answer false if this event originated in this cache.
+ * @return true if this event originated remotely
+ *
+ */
+ public boolean isOriginRemote();
+ /**
+ * Returns the {@link DistributedMember} that this event originated in.
+ * @return the member that performed the operation that originated this event.
+ * @since 5.0
+ */
+ public DistributedMember getDistributedMember();
+
+ /** Answer true if this event resulted from expiration.
+ * @return true if this event resulted from expiration
+ * @deprecated as of GemFire 5.0, use {@link Operation#isExpiration} instead.
+ *
+ */
+ @Deprecated
+ public boolean isExpiration();
+
+ /** Answers true if this event resulted from a distributed operation;
+ * false if a local operation.
+ *
+ * This is useful to distinguish between invalidate and localInvalidate, and
+ * destroy and localDestroy.
+ *
+ * @return true if this event resulted from a distributed operation
+ * @deprecated as of GemFire 5.0, use {@link Operation#isDistributed} instead.
+ *
+ */
+ @Deprecated
+ public boolean isDistributed();
+}
http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/19459053/gemfire-core/src/main/java/com/gemstone/gemfire/cache/CacheException.java
----------------------------------------------------------------------
diff --git a/gemfire-core/src/main/java/com/gemstone/gemfire/cache/CacheException.java b/gemfire-core/src/main/java/com/gemstone/gemfire/cache/CacheException.java
new file mode 100644
index 0000000..9d8e449
--- /dev/null
+++ b/gemfire-core/src/main/java/com/gemstone/gemfire/cache/CacheException.java
@@ -0,0 +1,61 @@
+/*=========================================================================
+ * 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;
+
+import com.gemstone.gemfire.GemFireException;
+
+
+/**
+ * A generic exception, which indicates
+ * a cache error has occurred. All the other cache exceptions are
+ * subclasses of this class. This class is abstract and therefore only
+ * subclasses are instantiated.
+ *
+ * @author Eric Zoerner
+ *
+ * @since 2.0
+ */
+public abstract class CacheException extends GemFireException {
+ /** Constructs a new <code>CacheException</code>. */
+ public CacheException() {
+ super();
+ }
+
+ /** Constructs a new <code>CacheException</code> with a message string. */
+ public CacheException(String s) {
+ super(s);
+ }
+
+ /** Constructs a <code>CacheException</code> with a message string and
+ * a base exception
+ */
+ public CacheException(String s, Throwable cause) {
+ super(s, cause);
+ }
+
+ /** Constructs a <code>CacheException</code> with a cause */
+ public CacheException(Throwable cause) {
+ super(cause);
+ }
+
+ @Override
+ public String toString() {
+ String result = super.toString();
+ Throwable cause = getCause();
+ if (cause != null) {
+ String causeStr = cause.toString();
+ final String glue = ", caused by ";
+ StringBuffer sb = new StringBuffer(result.length() + causeStr.length() + glue.length());
+ sb.append(result)
+ .append(glue)
+ .append(causeStr);
+ result = sb.toString();
+ }
+ return result;
+ }
+}
http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/19459053/gemfire-core/src/main/java/com/gemstone/gemfire/cache/CacheExistsException.java
----------------------------------------------------------------------
diff --git a/gemfire-core/src/main/java/com/gemstone/gemfire/cache/CacheExistsException.java b/gemfire-core/src/main/java/com/gemstone/gemfire/cache/CacheExistsException.java
new file mode 100644
index 0000000..fb4878a
--- /dev/null
+++ b/gemfire-core/src/main/java/com/gemstone/gemfire/cache/CacheExistsException.java
@@ -0,0 +1,57 @@
+/*=========================================================================
+ * 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;
+
+
+/** Thrown when attempting to create a {@link Cache} if one already exists.
+ *
+ * @author Darrel Schneider
+ *
+ * @see CacheFactory#create
+ * @since 3.0
+ */
+public class CacheExistsException extends CacheException {
+private static final long serialVersionUID = 4090002289325418100L;
+
+ /** The <code>Cache</code> that already exists */
+ private final transient Cache cache;
+
+ /////////////////////// Constructors ///////////////////////
+
+ /**
+ * Constructs an instance of <code>CacheExistsException</code> with the specified detail message.
+ * @param msg the detail message
+ */
+ public CacheExistsException(Cache cache, String msg) {
+ super(msg);
+ this.cache = cache;
+ }
+
+ /**
+ * Constructs an instance of <code>CacheExistsException</code> with the specified detail message
+ * and cause.
+ * @param msg the detail message
+ * @param cause the causal Throwable
+ */
+ public CacheExistsException(Cache cache, String msg, Throwable cause) {
+ super(msg, cause);
+ this.cache = cache;
+ }
+
+ /////////////////////// Instance Methods ///////////////////////
+
+ /**
+ * Returns the <code>Cache</code> that already exists.
+ *
+ * @since 4.0
+ */
+ public Cache getCache() {
+ return this.cache;
+ }
+}
http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/19459053/gemfire-core/src/main/java/com/gemstone/gemfire/cache/CacheFactory.java
----------------------------------------------------------------------
diff --git a/gemfire-core/src/main/java/com/gemstone/gemfire/cache/CacheFactory.java b/gemfire-core/src/main/java/com/gemstone/gemfire/cache/CacheFactory.java
new file mode 100755
index 0000000..11536df
--- /dev/null
+++ b/gemfire-core/src/main/java/com/gemstone/gemfire/cache/CacheFactory.java
@@ -0,0 +1,397 @@
+/*=========================================================================
+ * 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;
+
+import java.util.Properties;
+
+import com.gemstone.gemfire.distributed.DistributedSystem;
+import com.gemstone.gemfire.distributed.internal.InternalDistributedSystem;
+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.cache.LocalRegion;
+import com.gemstone.gemfire.internal.i18n.LocalizedStrings;
+import com.gemstone.gemfire.internal.jndi.JNDIInvoker;
+import com.gemstone.gemfire.pdx.PdxInstance;
+import com.gemstone.gemfire.pdx.PdxSerializer;
+
+
+/**
+ * Factory class used to create the singleton {@link Cache cache} and connect to the GemFire singleton {@link DistributedSystem distributed system}. If the application wants to connect to GemFire as a client it should use {@link com.gemstone.gemfire.cache.client.ClientCacheFactory} instead.
+<p> Once the factory has been configured using its {@link #set(String, String)} method you produce a {@link Cache} by calling the {@link #create()} method.
+ * <p>
+ * To get the existing unclosed singleton cache instance call {@link #getAnyInstance}.
+ * <p>
+ * If an instance of {@link DistributedSystem} already exists when this factory
+ * creates a cache, that instance will be used if it is compatible with this factory.
+<p>
+The following examples illustrate bootstrapping the cache using region shortcuts:
+<p>
+Example 1: Create a cache and a replicate region named customers.
+<PRE>
+ Cache c = new CacheFactory().create();
+ Region r = c.createRegionFactory(REPLICATE).create("customers");
+</PRE>
+Example 2: Create a cache and a partition region with redundancy
+<PRE>
+ Cache c = new CacheFactory().create();
+ Region r = c.createRegionFactory(PARTITION_REDUNDANT).create("customers");
+</PRE>
+Example 3: Construct the cache region declaratively in cache.xml
+<PRE>
+ <!DOCTYPE cache PUBLIC
+ "-//GemStone Systems, Inc.//GemFire Declarative Caching 8.0//EN"
+ "http://www.gemstone.com/dtd/cache8_0.dtd">
+ <cache>
+ <region name="myRegion" refid="REPLICATE"/>
+ <!-- you can override or add to the REPLICATE attributes by adding
+ a region-attributes sub element here -->
+ </cache>
+</PRE>
+Now, create the cache telling it to read your cache.xml file:
+<PRE>
+ Cache c = new CacheFactory()
+ .set("cache-xml-file", "myCache.xml")
+ .create();
+ Region r = c.getRegion("myRegion");
+</PRE>
+
+<p> For a complete list of all region shortcuts see {@link RegionShortcut}.
+Applications that need to explicitly control the individual region attributes can do this declaratively in XML or using APIs.
+ *
+ * @author Darrel Schneider
+ *
+ *
+ * @since 3.0
+ */
+public class CacheFactory {
+
+ private final Properties dsProps;
+
+ private final CacheConfig cacheConfig = new CacheConfig();
+
+ /**
+ * Creates a default cache factory.
+ * @since 6.5
+ */
+ public CacheFactory() {
+ this(null);
+ }
+ /**
+ * Create a CacheFactory initialized with the given gemfire properties.
+ * For a list of valid gemfire properties see {@link DistributedSystem}.
+ * @param props the gemfire properties to initialize the factory with.
+ * @since 6.5
+ */
+ public CacheFactory(Properties props) {
+ if (props == null) {
+ props = new Properties();
+ }
+ this.dsProps = props;
+ }
+
+ /**
+ * Sets a gemfire property that will be used when creating the Cache.
+ * For a list of valid gemfire properties see {@link DistributedSystem}.
+ * @param name the name of the gemfire property
+ * @param value the value of the gemfire property
+ * @return a reference to this CacheFactory object
+ * @since 6.5
+ */
+ public CacheFactory set(String name, String value) {
+ this.dsProps.setProperty(name, value);
+ return this;
+ }
+ /**
+ * Creates a new cache that uses the specified <code>system</code>.
+ *
+ * <p>
+ *
+ * The <code>system</code> can specify a <A
+ * href="../distributed/DistributedSystem.html#cache-xml-file">"cache-xml-file"</a>
+ * property which will cause this creation to also create the
+ * regions, objects, and attributes declared in the file. The
+ * contents of the file must comply with the
+ * <code>"doc-files/cache8_0.dtd"></code> file.
+ * Note that when parsing the XML file {@link Declarable} classes
+ * are loaded using the current thread's {@linkplain
+ * Thread#getContextClassLoader context class loader}.
+ *
+ * @param system
+ * a <code>DistributedSystem</code> obtained by calling
+ * {@link DistributedSystem#connect}.
+ *
+ * @return a <code>Cache</code> that uses the specified
+ * <code>system</code> for distribution.
+ *
+ * @throws IllegalArgumentException
+ * If <code>system</code> is not {@link
+ * DistributedSystem#isConnected connected}.
+ * @throws CacheExistsException
+ * If an open cache already exists.
+ * @throws CacheXmlException
+ * If a problem occurs while parsing the declarative caching
+ * XML file.
+ * @throws TimeoutException
+ * If a {@link Region#put(Object, Object)} times out while initializing the
+ * cache.
+ * @throws CacheWriterException
+ * If a <code>CacheWriterException</code> is thrown while
+ * initializing the cache.
+ * @throws GatewayException
+ * If a <code>GatewayException</code> is thrown while
+ * initializing the cache.
+ * @throws RegionExistsException
+ * If the declarative caching XML file describes a region
+ * that already exists (including the root region).
+ * @deprecated as of 6.5 use {@link #CacheFactory(Properties)} instead.
+ */
+ @Deprecated
+ public static synchronized Cache create(DistributedSystem system)
+ throws CacheExistsException, TimeoutException, CacheWriterException,
+ GatewayException,
+ RegionExistsException
+ {
+ return create(system, false, new CacheConfig());
+ }
+
+ private static synchronized Cache create(DistributedSystem system, boolean existingOk, CacheConfig cacheConfig)
+ throws CacheExistsException, TimeoutException, CacheWriterException,
+ GatewayException,
+ RegionExistsException
+ {
+ GemFireCacheImpl instance = GemFireCacheImpl.getInstance();
+
+ if (instance != null && !instance.isClosed()) {
+ if (existingOk) {
+ // Check if cache configuration matches.
+ cacheConfig.validateCacheConfig(instance);
+
+ return instance;
+ } else {
+ // instance.creationStack argument is for debugging...
+ throw new CacheExistsException(instance, LocalizedStrings.CacheFactory_0_AN_OPEN_CACHE_ALREADY_EXISTS.toLocalizedString(instance), instance.creationStack);
+ }
+ }
+ return GemFireCacheImpl.create(system, cacheConfig);
+ }
+
+ /**
+ * Creates a new cache that uses the configured distributed system.
+ * If a connected distributed system already exists it will be used
+ * if it is compatible with the properties on this factory.
+ * Otherwise a a distributed system will be created with the configured properties.
+ * If a cache already exists it will be returned.
+ * <p>If the cache does need to be created it will also be initialized from
+ * cache.xml if it exists.
+ *
+ * @return the created or already existing singleton cache
+ *
+ * @throws CacheXmlException
+ * If a problem occurs while parsing the declarative caching
+ * XML file.
+ * @throws TimeoutException
+ * If a {@link Region#put(Object, Object)} times out while initializing the
+ * cache.
+ * @throws CacheWriterException
+ * If a <code>CacheWriterException</code> is thrown while
+ * initializing the cache.
+ * @throws GatewayException
+ * If a <code>GatewayException</code> is thrown while
+ * initializing the cache.
+ * @throws RegionExistsException
+ * If the declarative caching XML file describes a region
+ * that already exists (including the root region).
+ * @throws ManagementException
+ * If the jmx manager can not be initialized.
+ * @since 6.5
+ */
+ public Cache create()
+ throws TimeoutException, CacheWriterException,
+ GatewayException,
+ RegionExistsException
+ {
+ synchronized(CacheFactory.class) {
+ DistributedSystem ds = null;
+ if (this.dsProps.isEmpty()) {
+ // any ds will do
+ ds = InternalDistributedSystem.getConnectedInstance();
+ }
+ if (ds == null) {
+ ds = DistributedSystem.connect(this.dsProps);
+ }
+ return create(ds, true, cacheConfig);
+ }
+ }
+
+ /**
+ * Gets the instance of {@link Cache} produced by an
+ * earlier call to {@link #create()}.
+ * @param system the <code>DistributedSystem</code> the cache was created with.
+ * @return the {@link Cache} associated with the specified system.
+ * @throws CacheClosedException if a cache has not been created
+ * or the created one is {@link Cache#isClosed closed}
+ */
+ public static Cache getInstance(DistributedSystem system) {
+ return basicGetInstance(system, false);
+ }
+
+ /**
+ * Gets the instance of {@link Cache} produced by an
+ * earlier call to {@link #create()} even if it has been closed.
+ * @param system the <code>DistributedSystem</code> the cache was created with.
+ * @return the {@link Cache} associated with the specified system.
+ * @throws CacheClosedException if a cache has not been created
+ * @since 3.5
+ */
+ public static Cache getInstanceCloseOk(DistributedSystem system) {
+ return basicGetInstance(system, true);
+ }
+
+ private static Cache basicGetInstance(DistributedSystem system, boolean closeOk) {
+
+ // Avoid synchronization if this is an initialization thread to avoid
+ // deadlock when messaging returns to this VM
+ final int initReq = LocalRegion.threadInitLevelRequirement();
+ if (initReq == LocalRegion.ANY_INIT
+ || initReq == LocalRegion.BEFORE_INITIAL_IMAGE) { // fix bug 33471
+ return basicGetInstancePart2(system, closeOk);
+ } else {
+ synchronized (CacheFactory.class) {
+ return basicGetInstancePart2(system, closeOk);
+ }
+ }
+ }
+ private static Cache basicGetInstancePart2(DistributedSystem system, boolean closeOk) {
+ GemFireCacheImpl instance = GemFireCacheImpl.getInstance();
+ if (instance == null) {
+ throw new CacheClosedException(LocalizedStrings.CacheFactory_A_CACHE_HAS_NOT_YET_BEEN_CREATED.toLocalizedString());
+ } else {
+ if (instance.isClosed() && !closeOk) {
+ throw instance.getCacheClosedException(LocalizedStrings.CacheFactory_THE_CACHE_HAS_BEEN_CLOSED.toLocalizedString(), null);
+ }
+ if (!instance.getDistributedSystem().equals(system)) {
+ throw new CacheClosedException(LocalizedStrings.CacheFactory_A_CACHE_HAS_NOT_YET_BEEN_CREATED_FOR_THE_GIVEN_DISTRIBUTED_SYSTEM.toLocalizedString());
+ }
+ return instance;
+ }
+ }
+
+ /**
+ * Gets an arbitrary open instance of {@link Cache} produced by an
+ * earlier call to {@link #create()}.
+ * @throws CacheClosedException if a cache has not been created
+ * or the only created one is {@link Cache#isClosed closed}
+ */
+ public static synchronized Cache getAnyInstance() {
+ GemFireCacheImpl instance = GemFireCacheImpl.getInstance();
+ if (instance == null) {
+ throw new CacheClosedException(LocalizedStrings.CacheFactory_A_CACHE_HAS_NOT_YET_BEEN_CREATED.toLocalizedString());
+ } else {
+ instance.getCancelCriterion().checkCancelInProgress(null);
+ return instance;
+ }
+ }
+
+ /** 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();
+ }
+
+ /** 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 readSerialized true to prefer PdxInstance
+ * @return this CacheFactory
+ * @since 6.6
+ * @see com.gemstone.gemfire.pdx.PdxInstance
+ */
+ public CacheFactory setPdxReadSerialized(boolean readSerialized) {
+ this.cacheConfig.setPdxReadSerialized(readSerialized);
+ 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 CacheFactory
+ * @since 6.6
+ * @see PdxSerializer
+ */
+ public CacheFactory 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 CacheFactory
+ * @since 6.6
+ */
+ public CacheFactory 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
+ * <code>GatewaySender</code> or <code>AsyncEventQueue</code> with PDX then
+ * you should set this to true.
+ *
+ * @param isPersistent
+ * true if the metadata should be persistent
+ * @return this CacheFactory
+ * @since 6.6
+ */
+ public CacheFactory 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 CacheFactory
+ * @since 6.6
+ */
+ public CacheFactory 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/CacheListener.java
----------------------------------------------------------------------
diff --git a/gemfire-core/src/main/java/com/gemstone/gemfire/cache/CacheListener.java b/gemfire-core/src/main/java/com/gemstone/gemfire/cache/CacheListener.java
new file mode 100644
index 0000000..55ee4f7
--- /dev/null
+++ b/gemfire-core/src/main/java/com/gemstone/gemfire/cache/CacheListener.java
@@ -0,0 +1,165 @@
+/*=========================================================================
+ * 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;
+
+/**
+ * <p>
+ * A listener to handle region or entry related events.
+ * </p>
+ *
+ * <p>
+ * Instead of implementing this interface it is recommended that you extend the
+ * {@link com.gemstone.gemfire.cache.util.CacheListenerAdapter} class.
+ * </p>
+ *
+ * <h4>Avoiding the risk of deadlock</h4>
+ * <p>
+ * The methods on a <code>CacheListener</code> are invoked while holding a lock
+ * on the entry described by the {@link EntryEvent}, as a result if the listener
+ * method takes a long time to execute then it will cause the operation that
+ * caused it to be invoked to take a long time. In addition, listener code which
+ * calls {@link Region} methods could result in a deadlock. For example, in
+ * {@link #afterUpdate(EntryEvent)} for entry key k1,
+ * {@link Region#put(Object, Object) put(k2, someVal)} is called at the same
+ * time {@link #afterUpdate(EntryEvent)} for entry key k2 calls
+ * {@link Region#put(Object, Object) put(k1, someVal)} a deadlock may result.
+ * This co-key dependency example can be extended to a co-Region dependency
+ * where listener code in Region "A" performs Region operations on "B" and
+ * listener code in Region "B" performs Region operations on "A". Deadlocks may
+ * be either java-level or distributed multi-VM dead locks depending on Region
+ * configuration. To be assured of no deadlocks, listener code should cause some
+ * other thread to access the region and must not wait for that thread to
+ * complete the task.
+ * </p>
+ *
+ * <h4>Concurrency</h4>
+ * <p>
+ * Multiple events, on different entries, can cause concurrent invocation of
+ * <code>CacheListener</code> methods. Any exceptions thrown by the listener are
+ * caught by GemFire and logged.
+ * </p>
+ *
+ * <h4>Declaring instances in Cache XML files</h4>
+ * <p>
+ * To declare a CacheListener in a Cache XML file, it must also implement
+ * {@link Declarable}
+ * </p>
+ *
+ * @author Eric Zoerner
+ *
+ * @see AttributesFactory#addCacheListener
+ * @see AttributesFactory#initCacheListeners
+ * @see RegionAttributes#getCacheListeners
+ * @see AttributesMutator#addCacheListener
+ * @see AttributesMutator#removeCacheListener
+ * @see AttributesMutator#initCacheListeners
+ * @since 3.0
+ */
+public interface CacheListener<K,V> extends CacheCallback {
+
+ /**
+ * Handles the event of new key being added to a region. The entry did not
+ * previously exist in this region in the local cache (even with a null
+ * value).
+ *
+ * @param event the EntryEvent
+ * @see Region#create(Object, Object)
+ * @see Region#put(Object, Object)
+ * @see Region#get(Object)
+ */
+ public void afterCreate(EntryEvent<K,V> event);
+
+ /**
+ * Handles the event of an entry's value being modified in a region. This
+ * entry previously existed in this region in the local cache, but its
+ * previous value may have been null.
+ *
+ * @param event the EntryEvent
+ * @see Region#put(Object, Object)
+ */
+ public void afterUpdate(EntryEvent<K,V> event);
+
+ /**
+ * Handles the event of an entry's value being invalidated.
+ *
+ * @param event the EntryEvent
+ * @see Region#invalidate(Object)
+ */
+ public void afterInvalidate(EntryEvent<K,V> event);
+
+ /**
+ * Handles the event of an entry being destroyed.
+ *
+ * @param event the EntryEvent
+ * @see Region#destroy(Object)
+ */
+ public void afterDestroy(EntryEvent<K,V> event);
+
+ /**
+ * Handles the event of a region being invalidated. Events are not invoked for
+ * each individual value that is invalidated as a result of the region being
+ * invalidated. Each subregion, however, gets its own
+ * <code>regionInvalidated</code> event invoked on its listener.
+ *
+ * @param event the RegionEvent
+ * @see Region#invalidateRegion()
+ * @see Region#localInvalidateRegion()
+ */
+ public void afterRegionInvalidate(RegionEvent<K,V> event);
+
+ /**
+ * Handles the event of a region being destroyed. Events are not invoked for
+ * each individual entry that is destroyed as a result of the region being
+ * destroyed. Each subregion, however, gets its own
+ * <code>afterRegionDestroyed</code> event invoked on its listener.
+ *
+ * @param event the RegionEvent
+ * @see Region#destroyRegion()
+ * @see Region#localDestroyRegion()
+ * @see Region#close
+ * @see Cache#close()
+ */
+ public void afterRegionDestroy(RegionEvent<K,V> event);
+
+ /**
+ * Handles the event of a region being cleared. Events are not invoked for
+ * each individual entry that is removed as a result of the region being
+ * cleared.
+ *
+ * @param event the RegionEvent
+ *
+ * @see Region#clear
+ * @since 5.0
+ */
+ public void afterRegionClear(RegionEvent<K,V> event);
+
+ /**
+ * Handles the event of a region being created. Events are invoked for
+ * each individual region that is created.
+ * <p>Note that this method is only called
+ * for creates done in the local vm. To be notified of creates done in remote
+ * vms use {@link RegionMembershipListener#afterRemoteRegionCreate}.
+ *
+ * @param event the RegionEvent
+ *
+ * @see Cache#createRegion
+ * @see Region#createSubregion
+ * @since 5.0
+ */
+ public void afterRegionCreate(RegionEvent<K,V> event);
+
+ /**
+ * Handles the event of a region being live after receiving the marker from the server.
+ *
+ * @param event the RegionEvent
+ *
+ * @see Cache#readyForEvents
+ * @since 5.5
+ */
+ public void afterRegionLive(RegionEvent<K,V> event);
+}
http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/19459053/gemfire-core/src/main/java/com/gemstone/gemfire/cache/CacheLoader.java
----------------------------------------------------------------------
diff --git a/gemfire-core/src/main/java/com/gemstone/gemfire/cache/CacheLoader.java b/gemfire-core/src/main/java/com/gemstone/gemfire/cache/CacheLoader.java
new file mode 100644
index 0000000..39fedaf
--- /dev/null
+++ b/gemfire-core/src/main/java/com/gemstone/gemfire/cache/CacheLoader.java
@@ -0,0 +1,55 @@
+/*=========================================================================
+ * 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;
+
+/**
+ * Allows data from outside of the VM to be placed into a region.
+ * When {@link com.gemstone.gemfire.cache.Region#get(Object)} is called for a region
+ * entry that has a <code>null</code> value, the
+ * {@link CacheLoader#load load} method of the
+ * region's cache loader is invoked. The <code>load</code> method
+ * creates the value for the desired key by performing an operation such
+ * as a database query. The <code>load</code> may also perform a
+ * {@linkplain LoaderHelper#netSearch net search}
+ * that will look for the value in a cache instance hosted by
+ * another member of the distributed system.</p>
+ *
+ * @author Dave Monnie
+ *
+ *
+ * @see AttributesFactory#setCacheLoader
+ * @see RegionAttributes#getCacheLoader
+ * @see AttributesMutator#setCacheLoader
+ * @since 2.0
+ */
+public interface CacheLoader<K,V> extends CacheCallback {
+ /**
+ * Loads a value. Application writers should implement this
+ * method to customize the loading of a value. This method is called
+ * by the caching service when the requested value is not in the cache.
+ * Any exception (including an unchecked exception) thrown by this
+ * method is propagated back to and thrown by the invocation of
+ * {@link Region#get(Object, Object)} that triggered this load.
+ * <p>
+ *
+ * @param helper a LoaderHelper object that is passed in from cache service
+ * and provides access to the key, region, argument, and <code>netSearch</code>.
+ * @return the value supplied for this key, or null if no value can be
+ * supplied. A local loader will always be invoked if one exists.
+ * Otherwise one remote loader is invoked.
+ * Returning <code>null</code> causes
+ * {@link Region#get(Object, Object)} to return <code>null</code>.
+ * @throws CacheLoaderException, if an error occurs. This exception or any
+ * other exception thrown by this method will be propagated back to the
+ * application from the get method.
+ *
+ * @see Region#get(Object, Object) Region.get
+ */
+ public V load(LoaderHelper<K,V> helper)
+ throws CacheLoaderException;
+}
http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/19459053/gemfire-core/src/main/java/com/gemstone/gemfire/cache/CacheLoaderException.java
----------------------------------------------------------------------
diff --git a/gemfire-core/src/main/java/com/gemstone/gemfire/cache/CacheLoaderException.java b/gemfire-core/src/main/java/com/gemstone/gemfire/cache/CacheLoaderException.java
new file mode 100755
index 0000000..5770d0d
--- /dev/null
+++ b/gemfire-core/src/main/java/com/gemstone/gemfire/cache/CacheLoaderException.java
@@ -0,0 +1,57 @@
+/*=========================================================================
+ * 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;
+
+/** Thrown from the {@link CacheLoader#load} method indicating that an error
+ * occurred when a CacheLoader was attempting to load a value. This
+ * exception is propagated back to the caller of <code>Region.get</code>.
+ *
+ * @author Eric Zoerner
+ *
+ *
+ * @see com.gemstone.gemfire.cache.Region#get(Object)
+ * @see CacheLoader#load
+ * @since 3.0
+ */
+public class CacheLoaderException extends OperationAbortedException {
+private static final long serialVersionUID = -3383072059406642140L;
+
+ /**
+ * Creates a new instance of <code>CacheLoaderException</code>.
+ */
+ public CacheLoaderException() {
+ }
+
+
+ /**
+ * Constructs an instance of <code>CacheLoaderException</code> with the specified detail message.
+ * @param msg the detail message
+ */
+ public CacheLoaderException(String msg) {
+ super(msg);
+ }
+
+ /**
+ * Constructs an instance of <code>CacheLoaderException</code> with the specified detail message
+ * and cause.
+ * @param msg the detail message
+ * @param cause the causal Throwable
+ */
+ public CacheLoaderException(String msg, Throwable cause) {
+ super(msg, cause);
+ }
+
+ /**
+ * Constructs an instance of <code>CacheLoaderException</code> with the specified cause.
+ * @param cause the causal Throwable
+ */
+ public CacheLoaderException(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/CacheRuntimeException.java
----------------------------------------------------------------------
diff --git a/gemfire-core/src/main/java/com/gemstone/gemfire/cache/CacheRuntimeException.java b/gemfire-core/src/main/java/com/gemstone/gemfire/cache/CacheRuntimeException.java
new file mode 100644
index 0000000..4e0dc3a
--- /dev/null
+++ b/gemfire-core/src/main/java/com/gemstone/gemfire/cache/CacheRuntimeException.java
@@ -0,0 +1,72 @@
+/*=========================================================================
+ * 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;
+
+import com.gemstone.gemfire.GemFireException;
+
+/** A generic runtime exception that indicates
+ * a cache error has occurred. All the other runtime cache exceptions are the
+ * subclass of this class. This class is abstract so only subclasses can be
+ * instantiated
+ *
+ * @author Eric Zoerner
+ *
+ * @since 3.0
+ */
+public abstract class CacheRuntimeException extends GemFireException {
+
+ /**
+ * Creates a new instance of <code>CacheRuntimeException</code> without detail message.
+ */
+ public CacheRuntimeException() {
+ }
+
+
+ /**
+ * Constructs an instance of <code>CacheRuntimeException</code> with the specified detail message.
+ * @param msg the detail message
+ */
+ public CacheRuntimeException(String msg) {
+ super(msg);
+ }
+
+ /**
+ * Constructs an instance of <code>CacheRuntimeException</code> with the specified detail message
+ * and cause.
+ * @param msg the detail message
+ * @param cause the causal Throwable
+ */
+ public CacheRuntimeException(String msg, Throwable cause) {
+ super(msg, cause);
+ }
+
+ /**
+ * Constructs an instance of <code>CacheRuntimeException</code> with the specified cause.
+ * @param cause the causal Throwable
+ */
+ public CacheRuntimeException(Throwable cause) {
+ super(cause);
+ }
+
+ @Override
+ public String toString() {
+ String result = super.toString();
+ Throwable cause = getCause();
+ if (cause != null) {
+ String causeStr = cause.toString();
+ final String glue = ", caused by ";
+ StringBuffer sb = new StringBuffer(result.length() + causeStr.length() + glue.length());
+ sb.append(result)
+ .append(glue)
+ .append(causeStr);
+ result = sb.toString();
+ }
+ return result;
+ }
+}
http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/19459053/gemfire-core/src/main/java/com/gemstone/gemfire/cache/CacheStatistics.java
----------------------------------------------------------------------
diff --git a/gemfire-core/src/main/java/com/gemstone/gemfire/cache/CacheStatistics.java b/gemfire-core/src/main/java/com/gemstone/gemfire/cache/CacheStatistics.java
new file mode 100644
index 0000000..bdcea93
--- /dev/null
+++ b/gemfire-core/src/main/java/com/gemstone/gemfire/cache/CacheStatistics.java
@@ -0,0 +1,121 @@
+/*=========================================================================
+ * 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;
+
+/**
+ * Defines common statistics information
+ * for both region and entries. All of these methods may throw a
+ * CacheClosedException, RegionDestroyedException or an EntryDestroyedException.
+ *
+ * @author Eric Zoerner
+ *
+ *
+ * @see Region#getStatistics
+ * @see Region.Entry#getStatistics
+ * @since 2.0
+ */
+
+public interface CacheStatistics
+{
+ /** For an entry, returns the time that the entry's value was last modified;
+ * for a region, the last time any of the region's entries' values or the
+ * values in subregions' entries were modified. The
+ * modification may have been initiated locally or it may have been an update
+ * distributed from another cache. It may also have been a new value provided
+ * by a loader. The modification time on a region is propagated upward to parent
+ * regions, transitively, to the root region.
+ * <p>
+ * The number is expressed as the number of milliseconds since January 1, 1970.
+ * The granularity may be as course as 100ms, so the accuracy may be off by
+ * up to 50ms.
+ * <p>
+ * Entry and subregion creation will update the modification time on a
+ * region, but <code>destroy</code>, <code>destroyRegion</code>,
+ * <code>invalidate</code>, and <code>invalidateRegion</code>
+ * do not update the modification time.
+ * @return the last modification time of the region or the entry;
+ * returns 0 if entry is invalid or modification time is uninitialized.
+ * @see Region#put(Object, Object)
+ * @see Region#get(Object)
+ * @see Region#create(Object, Object)
+ * @see Region#createSubregion
+ */
+ public long getLastModifiedTime();
+
+ /**
+ * For an entry, returns the last time it was accessed via <code>Region.get</code>;
+ * for a region, the last time any of its entries or the entries of its
+ * subregions were accessed with <code>Region.get</code>.
+ * Any modifications will also update the lastAccessedTime, so
+ * <code>lastAccessedTime</code> is always <code>>= lastModifiedTime</code>.
+ * The <code>lastAccessedTime</code> on a region is propagated upward to
+ * parent regions, transitively, to the the root region.
+ * <p>
+ * The number is expressed as the number of milliseconds
+ * since January 1, 1970.
+ * The granularity may be as course as 100ms, so the accuracy may be off by
+ * up to 50ms.
+ *
+ * @return the last access time of the region or the entry's value;
+ * returns 0 if entry is invalid or access time is uninitialized.
+ * @see Region#get(Object)
+ * @see #getLastModifiedTime
+ * @throws StatisticsDisabledException if statistics are not available
+ */
+ public long getLastAccessedTime() throws StatisticsDisabledException;
+
+ /**
+ * Returns the number of times that {@link Region#get(Object) Region.get} on
+ * the region or the entry was called and there was no value found
+ * locally. Unlike <code>lastAccessedTime</code>, the miss count is
+ * not propagated to parent regions. Note that remote operations
+ * such as a "net search" do not effect the miss count.
+ *
+ * @return the number of cache misses on the region or the
+ * entry.
+ * @throws StatisticsDisabledException if statistics are not available
+ */
+ public long getMissCount() throws StatisticsDisabledException;
+
+ /**
+ * Returns the number of hits for this region or entry. The number
+ * of hits is defined as the number of times when the
+ * {@link Region#get(Object) Region.get} finds a value locally. Unlike
+ * <code>lastAccessedTime</code>, the hit count is not propagated to
+ * parent regions. Note that remote operations such as a "net
+ * search" do not effect the hit count.
+ *
+ * @return the number of hits for this region or entry.
+ * @throws StatisticsDisabledException if statistics are not available
+ */
+ public long getHitCount() throws StatisticsDisabledException;
+
+ /** Return the hit ratio, a convenience method defined as the ratio of hits
+ * to the number of calls to {@link Region#get(Object) Region.get}. If there have been zero
+ * calls to <code>Region.get</code>, then zero is returned.
+ * <p>
+ * The hit ratio is equivalent to:
+ * <pre>
+ * long hitCount = getHitCount();
+ * long total = hitCount + getMissCount();
+ * return total == 0L ? 0.0f : ((float)hitCount / total);
+ * </pre>
+ *
+ * @throws StatisticsDisabledException if statistics are not available
+ * @return the hit ratio as a float
+ */
+ public float getHitRatio() throws StatisticsDisabledException;
+
+
+ /** Reset the missCount and hitCount to zero for this entry.
+ *
+ * @throws StatisticsDisabledException if statistics are not available
+ */
+ public void resetCounts() throws StatisticsDisabledException;
+}