Source Code Cross Referenced for Cache.java in  » 6.0-JDK-Modules » jsr107 » javax » cache » Java Source Code / Java DocumentationJava Source Code and Java Documentation

Java Source Code / Java Documentation
1. 6.0 JDK Core
2. 6.0 JDK Modules
3. 6.0 JDK Modules com.sun
4. 6.0 JDK Modules com.sun.java
5. 6.0 JDK Modules sun
6. 6.0 JDK Platform
7. Ajax
8. Apache Harmony Java SE
9. Aspect oriented
10. Authentication Authorization
11. Blogger System
12. Build
13. Byte Code
14. Cache
15. Chart
16. Chat
17. Code Analyzer
18. Collaboration
19. Content Management System
20. Database Client
21. Database DBMS
22. Database JDBC Connection Pool
23. Database ORM
24. Development
25. EJB Server geronimo
26. EJB Server GlassFish
27. EJB Server JBoss 4.2.1
28. EJB Server resin 3.1.5
29. ERP CRM Financial
30. ESB
31. Forum
32. GIS
33. Graphic Library
34. Groupware
35. HTML Parser
36. IDE
37. IDE Eclipse
38. IDE Netbeans
39. Installer
40. Internationalization Localization
41. Inversion of Control
42. Issue Tracking
43. J2EE
44. JBoss
45. JMS
46. JMX
47. Library
48. Mail Clients
49. Net
50. Parser
51. PDF
52. Portal
53. Profiler
54. Project Management
55. Report
56. RSS RDF
57. Rule Engine
58. Science
59. Scripting
60. Search Engine
61. Security
62. Sevlet Container
63. Source Control
64. Swing Library
65. Template Engine
66. Test Coverage
67. Testing
68. UML
69. Web Crawler
70. Web Framework
71. Web Mail
72. Web Server
73. Web Services
74. Web Services apache cxf 2.0.1
75. Web Services AXIS2
76. Wiki Engine
77. Workflow Engines
78. XML
79. XML UI
Java
Java Tutorial
Java Open Source
Jar File Download
Java Articles
Java Products
Java by API
Photoshop Tutorials
Maya Tutorials
Flash Tutorials
3ds-Max Tutorials
Illustrator Tutorials
GIMP Tutorials
C# / C Sharp
C# / CSharp Tutorial
C# / CSharp Open Source
ASP.Net
ASP.NET Tutorial
JavaScript DHTML
JavaScript Tutorial
JavaScript Reference
HTML / CSS
HTML CSS Reference
C / ANSI-C
C Tutorial
C++
C++ Tutorial
Ruby
PHP
Python
Python Tutorial
Python Open Source
SQL Server / T-SQL
SQL Server / T-SQL Tutorial
Oracle PL / SQL
Oracle PL/SQL Tutorial
PostgreSQL
SQL / MySQL
MySQL Tutorial
VB.Net
VB.Net Tutorial
Flash / Flex / ActionScript
VBA / Excel / Access / Word
XML
XML Tutorial
Microsoft Office PowerPoint 2007 Tutorial
Microsoft Office Excel 2007 Tutorial
Microsoft Office Word 2007 Tutorial
Java Source Code / Java Documentation » 6.0 JDK Modules » jsr107 » javax.cache 
Source Cross Referenced  Class Diagram Java Document (Java Doc) 


001:        package javax.cache;
002:
003:        import java.util.Collection;
004:        import java.util.Map;
005:
006:        /**
007:         * <p/>
008:         * A cache, being a mechanism for efficient temporary storage of objects
009:         * for the purpose of improving the overall performance of an application
010:         * system, should not be necessary for the application to function correctly,
011:         * it only improves the performance.
012:         * <p/>
013:         * A cache could be scoped, for examples to a JVM, all JVMs on a node, all
014:         * nodes in a cluster, etc. Operations that are scoped to a cache such as put
015:         * or load would affect all JVM�s in the cache.  So the object loaded in 1 JVM
016:         * would be equally available to all other JVMs in the cache.
017:         * <p/>
018:         * Objects are identified in the cache by a key. A key can be any Java
019:         * object that implements the equals and  hashcode methods. If the object is
020:         * to be distributed or persisted (if supported) it must implement
021:         * serializable.
022:         * Each object in the cache will have a CacheEntry object associated with
023:         * it. This object will encapsulate the metadata associated with the cached
024:         * object. Mainly it represents the object statistics.
025:         * "CacheStatistics" represents the read-only statistics of the cache,
026:         * while "CacheAttributes" represents the user settable attributes of the
027:         * cache.
028:         * <p/>
029:         * What now follows are explanations of the behavior of the standard Map
030:         * methods:
031:         * <p/>
032:         * Returns true if the cache contains the specified key.  The search is
033:         * scoped to the cache. Other caches in the system will not be searched
034:         * and a CacheLoader will not be called.
035:         *
036:         * @param key key whose presence in this cache is to be tested.
037:         * @return true, if the cache contains the specified key.
038:         * <p/>
039:         * public boolean containsKey(Object key);
040:         * <p/>
041:         * <p/>
042:         * Returns <tt>true</tt> if this cache maps one or more keys to the
043:         * specified value.  More formally, returns <tt>true</tt> if and only if
044:         * this cache contains at least one mapping to a value <tt>v</tt> such that
045:         * <tt>(value==null ? v==null : value.equals(v))</tt>.
046:         * @param value value whose presence in this cache is to be tested.
047:         * @return true if the cache contains one or more keys to the specified value.
048:         * <p/>
049:         * public boolean containsValue(Object value);
050:         * <p/>
051:         * // REVIEW talip: will the behavior stay unspecified?? Implementation can
052:         * // mark the entry as removed so that iterator can skip it.
053:         * <p/>
054:         * Returns a set view of the objects currently contained in the cache.
055:         * A CacheLoader will not be called. The behavior is unspecified for the
056:         * case when an object is removed from the cache while the return set is
057:         * being traversed.
058:         * @return a set view of the mappings contained in this cache.
059:         * <p/>
060:         * public Set entrySet();
061:         * <p/>
062:         * <p/>
063:         * Equality is based on the Set returned by entrySet.  Equal will return
064:         * true if the two objects are referencing the same object or
065:         * entrySet.equals(((Map)o).entrySet()) returns true.
066:         * <p/>
067:         * <p/>
068:         * public boolean equals(Object o);
069:         * <p/>
070:         * <p/>
071:         * <p/>
072:         * Returns the hash code value for this cache.
073:         * @return the hash code value for this cache.
074:         * <p/>
075:         * public int hashCode();
076:         * <p/>
077:         * <p/>
078:         * Return true if entrySet().isEmpty() return true.
079:         * @return true if entrySet().isEmpty() returns true.
080:         * <p/>
081:         * public boolean isEmpty();
082:         * <p/>
083:         * <p/>
084:         * Returns a set view of the keys currently contained in the cache.  A
085:         * CacheLoader will not be called. The behavior is unspecified for the
086:         * case when an object is remove from the cache while the return set is
087:         * being traversed.
088:         * @return a set view of the keys in this cache
089:         * <p/>
090:         * public Set keySet();
091:         * <p/>
092:         * <p/>
093:         * Copies all of the mappings from the specified map to the cache.  This
094:         * would be equivalent to t.entrySet() then iterating through the Set and
095:         * calling put with each key value pair.
096:         * @param t the map whose mappings to be copied to this cache.
097:         * <p/>
098:         * public void putAll(Map t);
099:         * <p/>
100:         * <p/>
101:         * Returns the size of this map.
102:         * @return the number of objects in the cache. This should be the same
103:         * value as entrySet().size();
104:         * <p/>
105:         * public int size();
106:         * <p/>
107:         * <p/>
108:         * Returns a collection view of the values contained in this cache.
109:         * @return a collection view of the values contained in this cache.
110:         * <p/>
111:         * public Collection values();
112:         * <p/>
113:         * <p/>
114:         * The get method will return, from the cache, the object associated with
115:         * the argument "key". If the object is not in the cache, the associated
116:         * cache loader will be called. If no loader is associated with the object,
117:         * a null is returned.  If a problem is encountered during the retrieving
118:         * or loading of the object, an exception (to be defined) will be thrown.
119:         * If the "arg" argument is set, the arg object will be passed to the
120:         * CacheLoader.load method.  The cache will not dereference the object.
121:         * If no "arg" value is provided a null will be passed to the load method.
122:         * The storing of null values in the cache is permitted, however, the get
123:         * method will not distinguish returning a null stored in the cache and
124:         * not finding the object in the cache. In both cases a null is returned.
125:         * @param key key whose associated value is to be returned.
126:         * @return the value to which this cache maps the specified key, or
127:         * <tt>null</tt> if the cache contains no mapping for this key.
128:         * <p/>
129:         * public Object get(Object key);
130:         * <p/>
131:         * // REVIEW adam@bea.com 23-Jun-04 - I think that it is strange that get()
132:         * // doesn't throw an exception whereas getAll() does.  I understand the
133:         * // historical reason for it, but think it looks ugly nonetheless.
134:         * <p/>
135:         * The put method adds the object "value" to the cache identified by the
136:         * object "key".
137:         * <p/>
138:         * public Object put(Object key, Object value);
139:         * <p/>
140:         * The remove method will delete the object from the cache including the
141:         * key, the associated value and the associated CacheStatistics object.
142:         * <p/>
143:         * public Object remove(Object key);
144:         * <p/>
145:         * /**
146:         * The clear method will remove all objects from the cache including the
147:         * key, the associated value and the associated CacheStatistics object.
148:         * <p/>
149:         * public void clear();
150:         */
151:        public interface Cache<K, V> extends Map<K, V> // @@@ Should be ConcurrentMap, NYI
152:        {
153:
154:            enum State {
155:                STARTING, RUNNING, STOPPING, TERMINATED
156:            }
157:
158:            /**
159:             * The getAll method will return, from the cache, a Map of the objects
160:             * associated with the Collection of keys in argument "keys". If the objects
161:             * are not in the cache, the associated cache loader will be called. If no
162:             * loader is associated with an object, a null is returned.  If a problem
163:             * is encountered during the retrieving or loading of the objects, an
164:             * exception will be thrown.
165:             * If the "arg" argument is set, the arg object will be passed to the
166:             * CacheLoader.loadAll method.  The cache will not dereference the object.
167:             * If no "arg" value is provided a null will be passed to the loadAll
168:             * method.
169:             * The storing of null values in the cache is permitted, however, the get
170:             * method will not distinguish returning a null stored in the cache and
171:             * not finding the object in the cache. In both cases a null is returned.
172:             */
173:            Map<K, V> getAll(Collection<? extends K> keys)
174:                    throws CacheException;
175:
176:            /**
177:             * The load method provides a means to "pre load" the cache. This method
178:             * will, asynchronously, load the specified object into the cache using
179:             * the associated cacheloader. If the object already exists in the cache,
180:             * no action is taken. If no loader is associated with the object, no object
181:             * will be loaded into the cache.  If a problem is encountered during the
182:             * retrieving or loading of the object, an exception should
183:             * be logged.
184:             * If the "arg" argument is set, the arg object will be passed to the
185:             * CacheLoader.load method.  The cache will not dereference the object. If
186:             * no "arg" value is provided a null will be passed to the load method.
187:             * The storing of null values in the cache is permitted, however, the get
188:             * method will not distinguish returning a null stored in the cache and not
189:             * finding the object in the cache. In both cases a null is returned.
190:             *
191:             * @param key key whose associated value to be loaded using the
192:             *            associated cacheloader if this cache doesn't contain it.
193:             * @throws CacheException //REVIEW when??? is this a wrapper exception for the
194:             *                        the exceptions occured during the loading?
195:             */
196:            void load(K key) throws CacheException;
197:
198:            /**
199:             * The loadAll method provides a means to "pre load" objects into the cache.
200:             * This method will, asynchronously, load the specified objects into the
201:             * cache using the associated cache loader. If the an object already exists
202:             * in the cache, no action is taken. If no loader is associated with the
203:             * object, no object will be loaded into the cache.  If a problem is
204:             * encountered during the retrieving or loading of the objects, an
205:             * exception (to be defined) should be logged.
206:             * The getAll method will return, from the cache, a Map of the objects
207:             * associated with the Collection of keys in argument "keys". If the objects
208:             * are not in the cache, the associated cache loader will be called. If no
209:             * loader is associated with an object, a null is returned.  If a problem
210:             * is encountered during the retrieving or loading of the objects, an
211:             * exception (to be defined) will be thrown.
212:             * If the "arg" argument is set, the arg object will be passed to the
213:             * CacheLoader.loadAll method.  The cache will not dereference the object.
214:             * If no "arg" value is provided a null will be passed to the loadAll
215:             * method.
216:             *
217:             * @param keys collection of the keys whose associated values to be loaded into
218:             *             this cache by using the associated cacheloader if this cache doesn't contain
219:             *             them.
220:             * @throws CacheException //REVIEW when??? is this a wrapper exception for the
221:             *                        the exceptions occured during the loading?
222:             */
223:            void loadAll(Collection<? extends K> keys) throws CacheException;
224:
225:            /**
226:             * The peek method will return the object associated with "key" if it
227:             * currently exists (and is valid) in the cache. If not, a null is
228:             * returned.  With "peek" the CacheLoader will not be invoked and other
229:             * caches in the system will not be searched.
230:             *
231:             * @param key key whose associated value is to be peeked.
232:             */
233:            V peek(K key);
234:
235:            /**
236:             * Returns the CacheEntry object associated with the object identified by
237:             * "key". If the object is not in the cache, or the object is expired,
238:             * a null is returned.
239:             */
240:            CacheEntry<K, V> getCacheEntry(K key);
241:
242:            /**
243:             * Returns the CacheStatistics object associated with the cache.
244:             * May return null if the cache does not support statistics gathering.
245:             */
246:            CacheStatistics getStatistics();
247:
248:            /**
249:             * /**
250:             * The evict method will remove objects from the cache that are no longer
251:             * valid.  Objects where the specified expiration time has been reached.
252:             */
253:            void evict();
254:
255:            /**
256:             * Add a listener to the list of cache listeners
257:             */
258:            void addListener(CacheListener<K, V> listener);
259:
260:            /**
261:             * Remove a listener from the list of cache listeners
262:             */
263:            void removeListener(CacheListener<K, V> listener);
264:
265:            State getState();
266:
267:            String getName();
268:
269:            V put(K key, V value, long timeToLive);
270:
271:            void shutdown();
272:
273:            void clearStatistics();
274:
275:            CacheStatistics getCacheStatistics();
276:
277:            /**
278:             * All caches belong to a CacheManager  
279:             * @return the CacheManager for this Cache
280:             */
281:            CacheManager getCacheManager();
282:
283:            // REVIEW BG: This should not be called from user code, only from a CacheManager.  Should probably not be in the API, but the SPI
284:            void setCacheManager(CacheManager cacheManager);
285:
286:        }
www.java2java.com | Contact Us
Copyright 2009 - 12 Demo Source and Support. All rights reserved.
All other trademarks are property of their respective owners.