| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> |
| <!-- NewPage --> |
| <html lang="en"> |
| <head> |
| <link rel="canonical" href="https://ignite.apache.org/jcache/1.0.0/javadoc/javax/cache/package-summary.html" /> |
| <!-- Generated by javadoc (version 1.7.0_25) on Fri Mar 28 13:34:25 EST 2014 --> |
| <meta http-equiv="Content-Type" content="text/html" charset="UTF-8"> |
| <title>javax.cache (JSR107 API and SPI 1.0.0 API)</title> |
| <meta name="date" content="2014-03-28"> |
| <link rel="stylesheet" type="text/css" href="../../stylesheet.css" title="Style"> |
| |
| <script> |
| (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ |
| (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), |
| m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) |
| })(window,document,'script','https://www.google-analytics.com/analytics.js','ga'); |
| |
| ga('create', 'UA-61232409-1', 'auto'); |
| ga('send', 'pageview'); |
| |
| </script></head> |
| <body> |
| <script type="text/javascript"><!-- |
| if (location.href.indexOf('is-external=true') == -1) { |
| parent.document.title="javax.cache (JSR107 API and SPI 1.0.0 API)"; |
| } |
| //--> |
| </script> |
| <noscript> |
| <div>JavaScript is disabled on your browser.</div> |
| </noscript> |
| <!-- ========= START OF TOP NAVBAR ======= --> |
| <div class="topNav"><a name="navbar_top"> |
| <!-- --> |
| </a><a href="#skip-navbar_top" title="Skip navigation links"></a><a name="navbar_top_firstrow"> |
| <!-- --> |
| </a> |
| <ul class="navList" title="Navigation"> |
| <li><a href="../../overview-summary.html">Overview</a></li> |
| <li class="navBarCell1Rev">Package</li> |
| <li>Class</li> |
| <li><a href="package-use.html">Use</a></li> |
| <li><a href="package-tree.html">Tree</a></li> |
| <li><a href="../../deprecated-list.html">Deprecated</a></li> |
| <li><a href="../../index-all.html">Index</a></li> |
| <li><a href="../../help-doc.html">Help</a></li> |
| </ul> |
| </div> |
| <div class="subNav"> |
| <ul class="navList"> |
| <li>Prev Package</li> |
| <li><a href="../../javax/cache/annotation/package-summary.html">Next Package</a></li> |
| </ul> |
| <ul class="navList"> |
| <li><a href="../../index.html?javax/cache/package-summary.html" target="_top">Frames</a></li> |
| <li><a href="package-summary.html" target="_top">No Frames</a></li> |
| </ul> |
| <ul class="navList" id="allclasses_navbar_top"> |
| <li><a href="../../allclasses-noframe.html">All Classes</a></li> |
| </ul> |
| <div> |
| <script type="text/javascript"><!-- |
| allClassesLink = document.getElementById("allclasses_navbar_top"); |
| if(window==top) { |
| allClassesLink.style.display = "block"; |
| } |
| else { |
| allClassesLink.style.display = "none"; |
| } |
| //--> |
| </script> |
| </div> |
| <a name="skip-navbar_top"> |
| <!-- --> |
| </a></div> |
| <!-- ========= END OF TOP NAVBAR ========= --> |
| <div class="header"> |
| <h1 title="Package" class="title">Package javax.cache</h1> |
| <div class="docSummary"> |
| <div class="block">This package contains the API for JCache.</div> |
| </div> |
| <p>See: <a href="#package_description">Description</a></p> |
| </div> |
| <div class="contentContainer"> |
| <ul class="blockList"> |
| <li class="blockList"> |
| <table class="packageSummary" border="0" cellpadding="3" cellspacing="0" summary="Interface Summary table, listing interfaces, and an explanation"> |
| <caption><span>Interface Summary</span><span class="tabEnd"> </span></caption> |
| <tr> |
| <th class="colFirst" scope="col">Interface</th> |
| <th class="colLast" scope="col">Description</th> |
| </tr> |
| <tbody> |
| <tr class="altColor"> |
| <td class="colFirst"><a href="../../javax/cache/Cache.html" title="interface in javax.cache">Cache</a><K,V></td> |
| <td class="colLast"> |
| <div class="block">A <a href="../../javax/cache/Cache.html" title="interface in javax.cache"><code>Cache</code></a> is a Map-like data structure that provides temporary storage |
| of application data.</div> |
| </td> |
| </tr> |
| <tr class="rowColor"> |
| <td class="colFirst"><a href="../../javax/cache/Cache.Entry.html" title="interface in javax.cache">Cache.Entry</a><K,V></td> |
| <td class="colLast"> |
| <div class="block">A cache entry (key-value pair).</div> |
| </td> |
| </tr> |
| <tr class="altColor"> |
| <td class="colFirst"><a href="../../javax/cache/CacheManager.html" title="interface in javax.cache">CacheManager</a></td> |
| <td class="colLast"> |
| <div class="block">A <a href="../../javax/cache/CacheManager.html" title="interface in javax.cache"><code>CacheManager</code></a> provides a means of establishing, configuring, |
| acquiring, closing and destroying uniquely named <a href="../../javax/cache/Cache.html" title="interface in javax.cache"><code>Cache</code></a>s.</div> |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| </li> |
| <li class="blockList"> |
| <table class="packageSummary" border="0" cellpadding="3" cellspacing="0" summary="Class Summary table, listing classes, and an explanation"> |
| <caption><span>Class Summary</span><span class="tabEnd"> </span></caption> |
| <tr> |
| <th class="colFirst" scope="col">Class</th> |
| <th class="colLast" scope="col">Description</th> |
| </tr> |
| <tbody> |
| <tr class="altColor"> |
| <td class="colFirst"><a href="../../javax/cache/Caching.html" title="class in javax.cache">Caching</a></td> |
| <td class="colLast"> |
| <div class="block">The <a href="../../javax/cache/Caching.html" title="class in javax.cache"><code>Caching</code></a> class provides a convenient means for an application to |
| acquire an appropriate <a href="../../javax/cache/spi/CachingProvider.html" title="interface in javax.cache.spi"><code>CachingProvider</code></a> implementation.</div> |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| </li> |
| <li class="blockList"> |
| <table class="packageSummary" border="0" cellpadding="3" cellspacing="0" summary="Exception Summary table, listing exceptions, and an explanation"> |
| <caption><span>Exception Summary</span><span class="tabEnd"> </span></caption> |
| <tr> |
| <th class="colFirst" scope="col">Exception</th> |
| <th class="colLast" scope="col">Description</th> |
| </tr> |
| <tbody> |
| <tr class="altColor"> |
| <td class="colFirst"><a href="../../javax/cache/CacheException.html" title="class in javax.cache">CacheException</a></td> |
| <td class="colLast"> |
| <div class="block">Thrown to indicate an exception has occurred in the Cache.</div> |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| </li> |
| </ul> |
| <a name="package_description"> |
| <!-- --> |
| </a> |
| <h2 title="Package javax.cache Description">Package javax.cache Description</h2> |
| <div class="block">This package contains the API for JCache. JCache describes the technique |
| whereby Java developers use a <code>CachingProvider</code> to temporarily cache Java |
| objects. It provides a common way for Java programs to create, access, update |
| and remove entries from caches. |
| <h1>Core Concepts</h1> |
| The Java Caching API defines five core interfaces: <code>CachingProvider</code>, |
| <code>CacheManager</code>, <code>Cache</code>, <code>Entry</code> and <code>ExpiryPolicy</code>. |
| <p> |
| A <code>CachingProvider</code> defines the mechanism to establish, configure, |
| acquire, manage and control zero or more <code>CacheManager</code>s. An application |
| may access and use zero or more <code>CachingProvider</code>s at runtime. |
| <p> |
| A <code>CacheManager</code> defines the mechanism to establish, configure, acquire, |
| manage and control zero or more uniquely named <code>Cache</code>s all within the |
| context of the <code>CacheManager</code>. A <code>CacheManager</code> is owned by |
| a single <code>CachingProvider</code>. |
| <p> |
| A <code>Cache</code> is a Map-like data-structure that permits the temporary storage |
| of Key-based Values, some what like <code>Map</code> data-structure. A |
| <code>Cache</code> is owned by a single <code>CacheManager</code>. |
| <p> |
| An <code>Entry</code> is a single key-value pair stored by a <code>Cache</code>. |
| <p> |
| Each entry stored by a <code>Cache</code> has a defined duration, called the Expiry |
| Duration, during which they may be accessed, updated and removed. Once this |
| duration has passed, the entry is said to be expired. Once expired, entries are |
| no longer available to be accessed, updated or removed, just as if they never |
| existed in a <code>Cache</code>. Expiry is set using an <code>ExpiryPolicy</code>. |
| <h1>Store-By-Value and Store-By-Reference</h1> |
| Entries are stored by individual <code>Cache</code>s using one of two mechanisms: |
| store-by-value and store-by-reference. |
| <h2>Store-By-Value</h2> |
| The default mechanism, called store-by-value, instructs an implementation to |
| make a copy of application provided keys and values prior to storing them in a |
| <code>Cache</code> and later to return a new copy of the entries when accessed from a |
| <code>Cache</code>. |
| <p> |
| The purpose of copying entries as they are stored in a <code>Cache</code> and again when |
| they are returned from a <code>Cache</code> is to allow applications to continue mutating |
| the state of the keys and values without causing side-effects to entries held |
| by a <code>Cache</code>. |
| <h2>Store-By-Reference</h2> |
| The alternative and optional mechanism, called store-by-reference, instructs a |
| <code>Cache</code> implementation to simply store and return references to the application |
| provided keys and values, instead of making a copies as required by the |
| store-by-value approach. Should an application later mutate the keys or values |
| provided to a <code>Cache</code> using store-by-reference semantics, the side-effects of the |
| mutations will be visible to those accessing the entries from the <code>Cache</code>, |
| without an application having to update the <code>Cache</code>. |
| <h1><code>Cache</code>s and <code>Map</code>s</h1> |
| While <code>Cache</code>s and <code>Map</code>s share somewhat similar APIs, |
| <code>Cache</code>s are not Maps and <code>Map</code>s are not <code>Cache</code>s. |
| The following section outlines the main similarities and differences. |
| <p> |
| Like <code>Map</code>-based data-structures: |
| <ul> |
| <li><code>Cache</code> values are stored and accessed through an associated key.</li> |
| <li>Each key may only be associated with a single value in a <code>Cache</code>. |
| <li>Great care must be exercised if mutable objects are used as keys. The |
| behavior of a <code>Cache</code> is undefined if a key is mutated in a manner that |
| affects equals comparisons when a key is used with a <code>Cache</code>.</li> |
| <li><code>Cache</code>s depend on the concept of equality to determine when keys |
| and values are the same. Consequently custom key and value classes should |
| define a suitable implementation of the <code>Object#equals</code> method.</li> |
| <li> Custom key classes should additionally provide a suitable implementation |
| of the <code>Object#hashCode()</code> method. |
| <p> |
| Although recommended, implementations are not required to call either the |
| Object.hashCode or Object.equals methods defined by custom key classes. |
| Implementations are free to use optimizations whereby the invocation of these |
| methods is avoided. |
| <p> |
| As this specification does not define the concept of object equivalence it |
| should be noted applications that make use of custom key classes and rely on |
| implementation specific optimizations to determine equivalence may not be |
| portable.</li> |
| </ul> |
| Unlike <code>Map</code>-based data-structures: |
| <ul> |
| <li><code>Cache</code> keys and values must not be null.</li> |
| <li>Any attempt to use null for keys or values will result in a |
| <code>NullPointerException</code> being thrown, regardless of the use.</li> |
| <li>Entries may expire.</li> |
| <li>Entries may be evicted.</li> |
| <li>To support the compare-and-swap (CAS) operations, those that atomically |
| compare and exchange values, custom value classes should provide a suitable |
| implementation of <code>Object#equals</code>. |
| <p> |
| Although recommended, implementations are not required to call the |
| <code>Object#equals</code> method defined by custom value classes. Implementations |
| are free to implement optimizations whereby the invocation of this method is avoided. |
| </li> |
| <li>Implementations may require Keys and Values to be serializable in some |
| manner.</li> |
| <li><code>Cache</code>s may be configured to control how entries are stored, |
| either using |
| store-by-value or optionally using store-by-reference semantics.</li> |
| <li> Implementations may optionally enforce security restrictions. In case of a |
| violation, a <code>SecurityException</code> must be thrown.</li> |
| </ul> |
| <h1>Consistency</h1> |
| Consistency refers to the behavior of caches and the guarantees that exist when |
| concurrent cache mutation occur together with the visibility of the mutations |
| when multiple threads are accessing a cache. |
| <p> |
| All implementations must support the Default Consistency model as outlined |
| below. |
| <h2>Default Consistency</h2> |
| When using the default consistency mode, most <code>Cache</code> operations are performed as |
| if a locking mechanism exists for each key in a <code>Cache</code>. When a cache |
| operation acquires an exclusive read and write lock on a key all subsequent |
| operations on that key will block until that lock is released. The consequences |
| are that operations performed by a thread happen-before read or mutation |
| operations performed by another thread, including threads in different |
| Java Virtual Machines. |
| <p> |
| For some <code>Cache</code> operations the value returned by a <code>Cache</code> is considered the last |
| value. The last value might be an old value or a new value, especially in the |
| case where an entry is concurrently being updated. It is implementation |
| dependent which is returned. |
| <p> |
| Other operations follow a different convention in that mutations may only occur |
| when the current state of an entry matches a desired state. In such operations |
| multiple threads are free to compete to apply these changes i.e. as if they |
| share a lock. |
| <p> |
| As these methods must interact with other <code>Cache</code> operations acting as if they |
| had an exclusive lock, the CAS methods cannot write new values without acting |
| as if they also had an exclusive lock. |
| <p> |
| See the JCache Specification for further details. |
| <h2>Further Consistency Models</h2> |
| An implementation may provide support for different consistency models in |
| addition to the required <em>Default Consistency</em> mode |
| <h1>A Simple Example</h1> |
| This simple example creates a default <code>CacheManager</code>, configures a |
| <code>Cache</code> on it called “simpleCache” with a key type of String and a value |
| type of Integer and an expiry of one hour and then performs a some cache |
| operations. |
| <p> |
| <pre><code> |
| //resolve a cache manager |
| CachingProvider cachingProvider = Caching.getCachingProvider(); |
| CacheManager cacheManager = cachingProvider.getCacheManager(); |
| |
| //configure the cache |
| MutableConfiguration<String, Integer> config = |
| new MutableConfiguration<>() |
| .setTypes(String.class, Integer.class) |
| .setExpiryPolicyFactory(AccessedExpiryPolicy.factoryOf(ONE_HOUR)) |
| .setStatisticsEnabled(true); |
| |
| //create the cache |
| Cache<String, Integer> cache = cacheManager.createCache("simpleCache", config); |
| |
| //cache operations |
| String key = "key"; |
| Integer value1 = 1; |
| cache.put("key", value1); |
| Integer value2 = cache.get(key); |
| cache.remove(key); |
| </code></pre></div> |
| <dl><dt><span class="strong">Since:</span></dt> |
| <dd>1.0</dd> |
| <dt><span class="strong">Author:</span></dt> |
| <dd>Greg Luck</dd></dl> |
| </div> |
| <!-- ======= START OF BOTTOM NAVBAR ====== --> |
| <div class="bottomNav"><a name="navbar_bottom"> |
| <!-- --> |
| </a><a href="#skip-navbar_bottom" title="Skip navigation links"></a><a name="navbar_bottom_firstrow"> |
| <!-- --> |
| </a> |
| <ul class="navList" title="Navigation"> |
| <li><a href="../../overview-summary.html">Overview</a></li> |
| <li class="navBarCell1Rev">Package</li> |
| <li>Class</li> |
| <li><a href="package-use.html">Use</a></li> |
| <li><a href="package-tree.html">Tree</a></li> |
| <li><a href="../../deprecated-list.html">Deprecated</a></li> |
| <li><a href="../../index-all.html">Index</a></li> |
| <li><a href="../../help-doc.html">Help</a></li> |
| </ul> |
| </div> |
| <div class="subNav"> |
| <ul class="navList"> |
| <li>Prev Package</li> |
| <li><a href="../../javax/cache/annotation/package-summary.html">Next Package</a></li> |
| </ul> |
| <ul class="navList"> |
| <li><a href="../../index.html?javax/cache/package-summary.html" target="_top">Frames</a></li> |
| <li><a href="package-summary.html" target="_top">No Frames</a></li> |
| </ul> |
| <ul class="navList" id="allclasses_navbar_bottom"> |
| <li><a href="../../allclasses-noframe.html">All Classes</a></li> |
| </ul> |
| <div> |
| <script type="text/javascript"><!-- |
| allClassesLink = document.getElementById("allclasses_navbar_bottom"); |
| if(window==top) { |
| allClassesLink.style.display = "block"; |
| } |
| else { |
| allClassesLink.style.display = "none"; |
| } |
| //--> |
| </script> |
| </div> |
| <a name="skip-navbar_bottom"> |
| <!-- --> |
| </a></div> |
| <!-- ======== END OF BOTTOM NAVBAR ======= --> |
| <p class="legalCopy"><small>Copyright © 2014. All Rights Reserved.</small></p> |
| </body> |
| </html> |