jcache/1.0.0/javadoc/javax/cache/package-summary.html - ignite-website - Git at Google

 <!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&nbsp;javax.cache</h1>
 <div class="docSummary">
 <div class="block">This package contains the API for JCache.</div>
 </div>
 <p>See:&nbsp;<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">&nbsp;</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>&lt;K,V&gt;</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>&lt;K,V&gt;</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">&nbsp;</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">&nbsp;</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 &#169; 2014. All Rights Reserved.</small></p>
 </body>
 </html>
	<!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>