KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > objectweb > perseus > cache > api > CacheManager


1 /**
2  * Copyright (C) 2001-2002
3  * - France Telecom R&D
4  * - Laboratoire Logiciels, Systemes, Reseaux - UMR 5526, CNRS-INPG-UJF
5  *
6  * This library is free software; you can redistribute it and/or
7  * modify it under the terms of the GNU Lesser General Public
8  * License as published by the Free Software Foundation; either
9  * version 2 of the License, or (at your option) any later version.
10  *
11  * This library is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14  * Lesser General Public License for more details.
15  *
16  * You should have received a copy of the GNU Lesser General Public
17  * License along with this library; if not, write to the Free Software
18  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
19  *
20  * Release: 1.0
21  *
22  * Authors:
23  *
24  */
25
26 package org.objectweb.perseus.cache.api;
27
28 /**
29  * This interface is the functional (applicative) view for the Caching
30  * Service. All accesses to the cache are made through the
31  * Cache instance provided to the applicative level.
32  *
33  * The primary purpose of the caching service is to improve the
34  * overall system performance. The performance gain is from avoidance
35  * of costs due to I/O operations related to storage/network devices,
36  * recreation-related costs, etc. This service is to be used by
37  * several services such as the persistence service and the
38  * replication service, among others.
39  *
40  * @author Luciano Garcia-Banuelos (Luciano.Garcia@imag.fr)
41  */
42 public interface CacheManager {
43
44     /**
45      * This method allows a in-memory object (incarnation) to be
46      * placed in the cache. Such object is identified by the provided
47      * lid. If there is currently an object associated with lid, an
48      * Exception is thrown.
49      *
50      * @param id The corresponding object identifier.
51      * (It must be generated elsewhere, e.g. by a naming
52      * service).
53      * @param object The object to be cached.
54      * @return the new CacheEntry add in the cache
55      *
56      * @exception CacheException If object/lid are already registered
57      * or either object or lid are null.
58      **/
59     CacheEntry bind(Object JavaDoc id, Object JavaDoc object) throws CacheException;
60
61     /**
62      * This method searches the object, identified by lid, within the
63      * cache. If such an object has been previously added to the cache
64      * the corresponding reference to it will be returned as a result.
65      * NULL is returned otherwise. Note that objects must be added to
66      * the cache to make it available through it, and that objects could
67      * be evicted by the internal replacement algorithm.
68      *
69      * @param id The corresponding object identifier.
70      * @return The reference to the CacheEntry associated to the id.
71      * NULL otherwise.
72      *
73      **/
74     CacheEntry lookup(Object JavaDoc id);
75
76     /**
77      * This method notifies the cache manager the intention to use
78      * the object identified by lid. The cache manager will mark
79      * internally this object, so that this object would not be
80      * evicted from the cache.
81      *
82      * @param ce
83      *
84      * @exception CacheException If the object is not in the cache.
85      **/
86     void fix(CacheEntry ce) throws CacheException;
87
88     /**
89      * This method is used to notify the cache manager that the object
90      * identified by lid is not longer to be used. After executing this
91      * operation, the corresponding object is candidate for eviction,
92      * according to the replacement algorithm. That means, that the object
93      * will remain in the cache, but it may be evicted.
94      *
95      * @param ce
96      *
97      * @exception CacheException If the object has not been previously fixed.
98      */
99     void unfix(CacheEntry ce) throws CacheException;
100
101     /**
102      * Called whenever an object has been accessed. Thus, this method,
103      * gives hints about recency/frequency of use. This hints are used
104      * within the replacement algorithm.
105      *
106      * @param entry The cache entry that has been accessed.
107      * @exception CacheException Whenever an internal error occurs.
108      **/
109     void touch(CacheEntry entry) throws CacheException;
110 }
111
Popular Tags