001: /* ====================================================================
002: * The Jcorporate Apache Style Software License, Version 1.2 05-07-2002
003: *
004: * Copyright (c) 1995-2003 Jcorporate Ltd. All rights reserved.
005: *
006: * Redistribution and use in source and binary forms, with or without
007: * modification, are permitted provided that the following conditions
008: * are met:
009: *
010: * 1. Redistributions of source code must retain the above copyright
011: * notice, this list of conditions and the following disclaimer.
012: *
013: * 2. Redistributions in binary form must reproduce the above copyright
014: * notice, this list of conditions and the following disclaimer in
015: * the documentation and/or other materials provided with the
016: * distribution.
017: *
018: * 3. The end-user documentation included with the redistribution,
019: * if any, must include the following acknowledgment:
020: * "This product includes software developed by Jcorporate Ltd.
021: * (http://www.jcorporate.com/)."
022: * Alternately, this acknowledgment may appear in the software itself,
023: * if and wherever such third-party acknowledgments normally appear.
024: *
025: * 4. "Jcorporate" and product names such as "Expresso" must
026: * not be used to endorse or promote products derived from this
027: * software without prior written permission. For written permission,
028: * please contact info@jcorporate.com.
029: *
030: * 5. Products derived from this software may not be called "Expresso",
031: * or other Jcorporate product names; nor may "Expresso" or other
032: * Jcorporate product names appear in their name, without prior
033: * written permission of Jcorporate Ltd.
034: *
035: * 6. No product derived from this software may compete in the same
036: * market space, i.e. framework, without prior written permission
037: * of Jcorporate Ltd. For written permission, please contact
038: * partners@jcorporate.com.
039: *
040: * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
041: * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
042: * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
043: * DISCLAIMED. IN NO EVENT SHALL JCORPORATE LTD OR ITS CONTRIBUTORS
044: * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
045: * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
046: * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
047: * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
048: * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
049: * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
050: * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
051: * SUCH DAMAGE.
052: * ====================================================================
053: *
054: * This software consists of voluntary contributions made by many
055: * individuals on behalf of the Jcorporate Ltd. Contributions back
056: * to the project(s) are encouraged when you make modifications.
057: * Please send them to support@jcorporate.com. For more information
058: * on Jcorporate Ltd. and its products, please see
059: * <http://www.jcorporate.com/>.
060: *
061: * Portions of this software are based upon other open source
062: * products and are subject to their respective licenses.
063: */
064:
065: package com.jcorporate.expresso.core.cache;
066:
067: /**
068: * Cache.java
069: *
070: * Copyright 1999, 2000, 2001 Jcorporate Ltd.
071: */
072:
073: import java.util.Vector;
074:
075: /**
076: * A cache is a list of Cacheable objects that can be stored in memory,
077: * cleared, added to and removed from. It also
078: * stores information about how many times it has been used.
079: * This interface defines how a generic cache object should behave,
080: * but the specifics are up to the
081: * implementor.
082: * <p>Implementation Note: The implementation of ordered or unordered caches
083: * should be such that getItems() or getItem() will NEVER return an expired
084: * cache item. Implementations should check isExpired() before adding the
085: * cache item to the return list.
086: * </p>
087: */
088: public interface Cache {
089: /**
090: * Add a new item to the cache.
091: *
092: * @param newItem the new item to add to the cache
093: */
094: void addItem(CacheEntry newItem);
095:
096: /**
097: * Clear all items from the cache
098: */
099: void clear();
100:
101: /**
102: * Retrieve the low-level CacheEntry for the cache. This is particularly
103: * useful for debugging or management.
104: *
105: * @param itemKey the key for the entry
106: * @return a CacheEntry object or null if it doesn't exist
107: */
108: CacheEntry getCacheEntry(String itemKey);
109:
110: /**
111: * Get the item indicated by the given key from the cache.
112: * All Cacheable items define a getKey()
113: * method that defines how the item is differentated from other items in the cache
114: *
115: * @param itemKey the key of the item to retrieve
116: * @return the Object stored in the cache.
117: */
118: Cacheable getItem(String itemKey);
119:
120: /**
121: * Retrieve whether the cache instance is an ordered cache [list based]
122: * or unordered cache. [map based]
123: *
124: * @return true if the cache is an ordered cache.
125: */
126: boolean isOrdered();
127:
128: /**
129: * Retrieve Cache Item Count
130: *
131: * @return The number of items in the cache
132: */
133: int getItemCount();
134:
135: /**
136: * Get all the items in the cache
137: *
138: * @return java.util.Vector - The items in the cache
139: */
140: Vector getItems();
141:
142: /**
143: * Get the name of the cache
144: *
145: * @return java.lang.String the name of the cache.
146: */
147: String getName();
148:
149: /**
150: * Get how many times this cache has been used
151: *
152: * @return long
153: */
154: long getUsedCount();
155:
156: /**
157: * Removes the specified item from the cache.
158: *
159: * @param itemKey The item in the cache to remove
160: */
161: void removeItem(Cacheable itemKey);
162:
163: /**
164: * Set the items in the cache
165: *
166: * @param newItems The vector of new items
167: * @throws CacheException If there's an error setting the new items in
168: * the cache
169: */
170: void setItems(Vector newItems) throws CacheException;
171:
172: /**
173: * Eventually the new way to set items
174: *
175: * @param newItems the new items to add
176: * @throws CacheException upon error
177: */
178: void setItems(java.util.List newItems) throws CacheException;
179:
180: /**
181: * Sets the maximum size of the cache
182: *
183: * @param newMax The new maximum size of the cache.
184: */
185: void setMaxSize(int newMax);
186:
187: /**
188: * Sets the name of the cache
189: *
190: * @param newName java.lang.String The new name of the cache.
191: */
192: void setName(String newName);
193:
194: }
|