[jbosscache-commits] JBoss Cache SVN: r7726 - core/branches/flat/src/main/java/org/horizon.

[jbosscache-commits at lists.jboss.org]

Author: manik.surtani at jboss.com
Date: 2009-02-18 12:40:47 -0500 (Wed, 18 Feb 2009)
New Revision: 7726

Modified:
   core/branches/flat/src/main/java/org/horizon/Cache.java
Log:
Javadocs

Modified: core/branches/flat/src/main/java/org/horizon/Cache.java
===================================================================
--- core/branches/flat/src/main/java/org/horizon/Cache.java	2009-02-18 17:32:24 UTC (rev 7725)
+++ core/branches/flat/src/main/java/org/horizon/Cache.java	2009-02-18 17:40:47 UTC (rev 7726)
@@ -32,7 +32,25 @@
 import java.util.concurrent.TimeUnit;
 
 /**
+ * The central interface of Horizon.  A Cache provides a highly concurrent, optionally distributed data structure with
+ * additional features such as: <ul> <li>JTA transaction compatibility</li> <li>Eviction support to prevent evicting
+ * entries from memory to prevent {@link OutOfMemoryError}s</li> <li>Persisting entries to a {@link
+ * org.horizon.loader.CacheStore}, either when they are evicted as an overflow, or all the time, to maintain persistent
+ * copies that would withstand server failure or restarts.</li> </ul>
+ * <p/>
+ * For convenience, Cache extends {@link java.util.concurrent.ConcurrentMap} and implements all methods accordingly,
+ * although methods like {@link java.util.concurrent.ConcurrentMap#keySet()}, {@link
+ * java.util.concurrent.ConcurrentMap#values()} and {@link java.util.concurrent.ConcurrentMap#entrySet()} are expensive
+ * (prohibitively so when using a distributed cache) and frequent use of these methods is not recommended.
+ * <p/>
+ * Also, like most {@link java.util.concurrent.ConcurrentMap} implementations, Cache does not support the use of
+ * <tt>null</tt> keys (although <tt>null</tt> values are allowed).
+ * <p/>
+ * Please see the Horizon documentation for more details.
+ * <p/>
+ *
  * @author Mircea.Markus at jboss.com
+ * @author Manik Surtani
  * @since 1.0
  */
 public interface Cache<K, V> extends ConcurrentMap<K, V>, Lifecycle, Listenable {