View Javadoc

1   /*
2    * This file is part of Domingo
3    * an Open Source Java-API to Lotus Notes/Domino
4    * hosted at http://domingo.sourceforge.net
5    *
6    * Copyright (c) 2003-2007 Beck et al. projects GmbH Munich, Germany (http://www.bea.de)
7    *
8    * This library is free software; you can redistribute it and/or
9    * modify it under the terms of the GNU Lesser General Public
10   * License as published by the Free Software Foundation; either
11   * version 2.1 of the License, or (at your option) any later version.
12   *
13   * This library is distributed in the hope that it will be useful,
14   * but WITHOUT ANY WARRANTY; without even the implied warranty of
15   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16   * Lesser General Public License for more details.
17   *
18   * You should have received a copy of the GNU Lesser General Public
19   * License along with this library; if not, write to the Free Software
20   * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
21   */
22  
23  package de.bea.domingo.cache;
24  
25  import java.util.Collection;
26  import java.util.Set;
27  
28  /***
29   * Cache Interface.
30   *
31   * @author <a href=mailto:kriede@users.sourceforge.net>Kurt Riede</a>
32   */
33  public interface Cache {
34  
35      /***
36       * Returns an object with a given key from the cache.
37       *
38       * @param key the key
39       *
40       * @return object with given key
41       */
42      Object get(Object key);
43  
44      /***
45       * Puts an object with a key into the cache.
46       *
47       * @param key the key
48       * @param value the object
49       */
50      void put(Object key, Object value);
51  
52      /***
53       * Checks if a given key exists in the cache.
54       *
55       * @param key the key
56       * @return <code>true</code> if the given key exists in the cache, else
57       *         <code>false</code>
58       */
59      boolean containsKey(Object key);
60  
61      /***
62       * Returns the number of elements in this cache (its cardinality). If this
63       * set contains more than <tt>Integer.MAX_VALUE</tt> elements, returns
64       * <tt>Integer.MAX_VALUE</tt>.
65       *
66       * @return the number of elements in this set (its cardinality).
67       */
68      int size();
69  
70      /***
71       * Removes the mapping for this key from this cache if present (optional
72       * operation). <p>
73       *
74       * This implementation iterates over <tt>entrySet()</tt> searching for an
75       * entry with the specified key.  If such an entry is found, its value is
76       * obtained with its <tt>getValue</tt> operation, the entry is removed
77       * from the Collection (and the backing cache) with the iterator's
78       * <tt>remove</tt> operation, and the saved value is returned.  If the
79       * iteration terminates without finding such an entry, <tt>null</tt> is
80       * returned.  Note that this implementation requires linear time in the
81       * size of the cache; many implementations will override this method.
82       *
83       * @param key key whose mapping is to be removed from the cache.
84       * @return previous value associated with specified key, or <tt>null</tt>
85       *         if there was no entry for key.  (A <tt>null</tt> return can
86       *         also indicate that the cache previously associated <tt>null</tt>
87       *         with the specified key, if the implementation supports
88       *         <tt>null</tt> values.)
89       */
90      Object remove(Object key);
91  
92      /***
93       * Removes all mappings from this map (optional operation).
94       */
95      void clear();
96  
97      /***
98       * Returns a set view of the keys contained in this cache.  The set is
99       * backed by the cache, so changes to the cache are reflected in the set, and
100      * vice-versa.  The set supports element removal, which removes the
101      * corresponding mapping from this cache, via the <tt>Iterator.remove</tt>,
102      * <tt>Set.remove</tt>, <tt>removeAll</tt>, <tt>retainAll</tt>, and
103      * <tt>clear</tt> operations.  It does not support the <tt>add</tt> or
104      * <tt>addAll</tt> operations.
105      *
106      * @return a set view of the keys contained in this cache.
107      */
108     Set keySet();
109 
110     /***
111      * Returns a collection view of the values contained in this cache.  The
112      * collection is backed by the cache, so changes to the cache are reflected in
113      * the collection, and vice-versa.  The collection supports element
114      * removal, which removes the corresponding mapping from this cache, via the
115      * <tt>Iterator.remove</tt>, <tt>Collection.remove</tt>,
116      * <tt>removeAll</tt>, <tt>retainAll</tt>, and <tt>clear</tt> operations.
117      * It does not support the <tt>add</tt> or <tt>addAll</tt> operations.
118      *
119      * @return a collection view of the values contained in this cache.
120      */
121     Collection values();
122 }