View Javadoc

1   package org.apache.jcs.engine.memory.behavior;
2   
3   /*
4    * Licensed to the Apache Software Foundation (ASF) under one
5    * or more contributor license agreements.  See the NOTICE file
6    * distributed with this work for additional information
7    * regarding copyright ownership.  The ASF licenses this file
8    * to you under the Apache License, Version 2.0 (the
9    * "License"); you may not use this file except in compliance
10   * with the License.  You may obtain a copy of the License at
11   *
12   *   http://www.apache.org/licenses/LICENSE-2.0
13   *
14   * Unless required by applicable law or agreed to in writing,
15   * software distributed under the License is distributed on an
16   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17   * KIND, either express or implied.  See the License for the
18   * specific language governing permissions and limitations
19   * under the License.
20   */
21  
22  import java.io.IOException;
23  import java.io.Serializable;
24  import java.util.Iterator;
25  import java.util.Set;
26  
27  import org.apache.jcs.engine.behavior.ICacheElement;
28  import org.apache.jcs.engine.behavior.ICompositeCacheAttributes;
29  import org.apache.jcs.engine.control.CompositeCache;
30  import org.apache.jcs.engine.stats.behavior.IStats;
31  
32  /***
33   * For the framework. Insures methods a MemoryCache needs to access.
34   *
35   */
36  public interface IMemoryCache
37  {
38      /***
39       * Initialize the memory cache
40       * <p>
41       * @param cache
42       *            The cache (region) this memory store is attached to.
43       */
44      public void initialize( CompositeCache cache );
45  
46      /***
47       * Destroy the memory cache
48       * <p>
49       * @throws IOException
50       */
51      public void dispose()
52          throws IOException;
53  
54      /***
55       * Get the number of elements contained in the memory store
56       * <p>
57       * @return Element count
58       */
59      public int getSize();
60  
61      /***
62       * Returns the historical and statistical data for a region's memory cache.
63       * <p>
64       * @return Statistics and Infor for the Memory Cache.
65       */
66      public IStats getStatistics();
67  
68      /***
69       * Get an iterator for all elements in the memory cache. This should be
70       * removed since it is fairly dangerous. Other classes should not be able to
71       * directly access items in the memory cache.
72       * <p>
73       * @return An iterator
74       */
75      public Iterator getIterator();
76  
77      /***
78       * Get an Array of the keys for all elements in the memory cache.
79       * <p>
80       * @return Object[]
81       * @TODO This should probably be done in chunks with a range pased in. This
82       *       will be a problem if someone puts a 1,000,000 or so items in a
83       *       region.
84       */
85      public Object[] getKeyArray();
86  
87      /***
88       * Removes an item from the cache
89       * <p>
90       * @param key
91       *            Identifies item to be removed
92       * @return Description of the Return Value
93       * @exception IOException
94       *                Description of the Exception
95       */
96      public boolean remove( Serializable key )
97          throws IOException;
98  
99      /***
100      * Removes all cached items from the cache.
101      * <p>
102      * @exception IOException
103      *                Description of the Exception
104      */
105     public void removeAll()
106         throws IOException;
107 
108     /***
109      * This instructs the memory cache to remove the <i>numberToFree</i>
110      * according to its eviction policy. For example, the LRUMemoryCache will
111      * remove the <i>numberToFree</i> least recently used items. These will be
112      * spooled to disk if a disk auxiliary is available.
113      * <p>
114      * @param numberToFree
115      * @return the number that were removed. if you ask to free 5, but there are
116      *         only 3, you will get 3.
117      * @throws IOException
118      */
119     public int freeElements( int numberToFree )
120         throws IOException;
121 
122     /***
123      * Get an item from the cache
124      * <p>
125      * @param key
126      *            Description of the Parameter
127      * @return Description of the Return Value
128      * @exception IOException
129      *                Description of the Exception
130      */
131     public ICacheElement get( Serializable key )
132         throws IOException;
133 
134     /***
135      * Get an item from the cache without effecting its order or last access
136      * time
137      * <p>
138      * @param key
139      *            Description of the Parameter
140      * @return The quiet value
141      * @exception IOException
142      *                Description of the Exception
143      */
144     public ICacheElement getQuiet( Serializable key )
145         throws IOException;
146 
147     /***
148      * Spools the item contained in the provided element to disk
149      * <p>
150      * @param ce
151      *            Description of the Parameter
152      * @exception IOException
153      *                Description of the Exception
154      */
155     public void waterfal( ICacheElement ce )
156         throws IOException;
157 
158     /***
159      * Puts an item to the cache.
160      * <p>
161      * @param ce
162      *            Description of the Parameter
163      * @exception IOException
164      *                Description of the Exception
165      */
166     public void update( ICacheElement ce )
167         throws IOException;
168 
169     /***
170      * Returns the CacheAttributes for the region.
171      * <p>
172      * @return The cacheAttributes value
173      */
174     public ICompositeCacheAttributes getCacheAttributes();
175 
176     /***
177      * Sets the CacheAttributes of the region.
178      * <p>
179      * @param cattr
180      *            The new cacheAttributes value
181      */
182     public void setCacheAttributes( ICompositeCacheAttributes cattr );
183 
184     /***
185      * Gets the cache hub / region that uses the MemoryCache.
186      * <p>
187      * @return The cache value
188      */
189     public CompositeCache getCompositeCache();
190 
191     /***
192      * Gets the set of keys of objects currently in the group.
193      * <p>
194      * @param group
195      * @return a Set of group keys.
196      */
197     public Set getGroupKeys( String group );
198 
199 }