1 /* Open Source Java Caching Service
2 * Copyright (C) 2002 Frank Karlstrøm
3 * This library is free software; you can redistribute it and/or
4 * modify it under the terms of the GNU Lesser General Public
5 * License as published by the Free Software Foundation; either
6 * version 2.1 of the License, or (at your option) any later version.
7 *
8 * This library is distributed in the hope that it will be useful,
9 * but WITHOUT ANY WARRANTY; without even the implied warranty of
10 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
11 * Lesser General Public License for more details.
12 *
13 * You should have received a copy of the GNU Lesser General Public
14 * License along with this library; if not, write to the Free Software
15 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
16 *
17 * The author can be contacted by email: fjankk@users.sourceforge.net
18 */
19 package javax.util.jcache;
20
21 import java.util.Enumeration;
22
23
24 /**
25 * Contains several usefull methods for configuring, administering and
26 * monitoring the Cache.
27 *
28 * @author Frank Karlstrøm
29 * @deprecated will be reomved with no replacement.
30 */
31 public interface Cache {
32 /**
33 * initializes the cache, allocates space for metadata and starts the
34 * service threads. The cache is a process wide service, so it can only be
35 * initialized once per process. Subsequent init calls are ignored.
36 *
37 * @param attributes contains configuration information to initialize the
38 * cache system.
39 * @throws CacheNotAvailableException if the cache is not ready.
40 */
41 void init(CacheAttributes attributes)
42 throws CacheNotAvailableException;
43
44 /**
45 * will create a CacheAttributes object based on the values in a Java
46 * properties file, then call the method init. The properties file opened
47 * is called jcache.properties If this method is called, the init() method
48 * is not neccessary to call.
49 * @throws CacheNotAvailableException if the cache is not ready.
50 */
51 void open() throws CacheNotAvailableException;
52
53 /**
54 * will create a CacheAttributes object based on the values in a Java
55 * properties file, then call the method init. The properties file opened
56 * is called jcache.properties If this method is called, the init() method
57 * is not neccessary to call.
58 * @throws CacheNotAvailableException if the cache is not ready.
59 */
60 void open(String configFile) throws CacheNotAvailableException;
61
62 /**
63 * will mark the cache as "not ready" and shutdown the cache. Marking the
64 * cache as "not ready" will prevent any threads from accessing the Cache
65 * during shutdown. If the cache is distributed, close will unregister
66 * with the distributed caching system. The method should be called as a
67 * part of process termination.
68 */
69 void close();
70
71 /**
72 * will mark all objects in the cache, both disk and memory, as invalid,
73 * forcing objects to be reloaded. All processes sharing the disk cache
74 * are notified when the cache is flushed.
75 *
76 * @throws CacheException if an error occurs.
77 */
78 void flush() throws CacheException;
79
80 /**
81 * will mark all objects in the cache as invalid, forcing objects to be
82 * reloaded. Flushing the memory cache will also invalidate memory objects
83 * spooled to disk. Objects that are only cached on disk will not be
84 * affected.
85 *
86 * @throws CacheException if an error occurs.
87 */
88 void flushMemory() throws CacheException;
89
90 /**
91 * will mark all objects in the cache as invalid, forcing objects to be
92 * reloaded. Flushing the disk cache will also invalidate memory objects
93 * spooled to disk. All processes sharing the disk cache are notified when
94 * the cache is flushed.
95 *
96 * @throws CacheException if an error occurs.
97 */
98 void flushDisk() throws CacheException;
99
100 /**
101 * returns the current version of the cache.
102 *
103 * @return the current version of the cache.
104 */
105 float getVersion();
106
107 /**
108 * returns true if the cache has been initialized and not closed, false
109 * otherwise.
110 *
111 * @return true if the cache has been initialized and not closed, false
112 * otherwise.
113 */
114 boolean isReady();
115
116 /**
117 * returns true if the cache is currently in distributed mode, that it is
118 * distributing updates and invalidates within the site, false if all
119 * cache actions are local only.
120 *
121 * @return true if the cache is currently in distributed mode, that it is
122 * distributing updates and invalidates within the site, false if
123 * all cache actions are local only.
124 */
125 boolean isDistributed();
126
127 /**
128 * will return an Enumeration of CacheObjectInfo objects describing the
129 * objects in all regions in the cache. CacheObjectInfo will include
130 * information such as the object name, the type, what group it is
131 * associated with, the reference count, the expiration time if any and
132 * object attributes.
133 *
134 * @return an Enumeration of CacheObjectInfo objects.
135 */
136 Enumeration listCacheObjects();
137
138 /**
139 * will return an Enumeration of CacheObjectInfo objects describing the
140 * objects in the specified in the cache. CacheObjectInfo will include
141 * information such as the object name, the type, what group it is
142 * associated with, the reference count, the expiration time if any and
143 * object attributes.
144 *
145 * @param region the region to get the Enumeration for.
146 *
147 * @return an Enumeration of CacheObjectInfo objects.
148 *
149 * @throws RegionNotFoundException if an invalid or non existing region is
150 * specified.
151 */
152 Enumeration listCacheObjects(String region)
153 throws RegionNotFoundException;
154
155 /**
156 * returns the current attributes of the cache including the cache version
157 * number, wether the cache is local or distributed, the maximum number of
158 * objects in the cache, the disk cache location, and the disk cache size.
159 *
160 * @return the current attributes of this cache.
161 *
162 * @throws CacheNotAvailableException if the cache is not ready.
163 */
164 CacheAttributes getAttributes() throws CacheNotAvailableException;
165
166 /**
167 * sets the log severity of the cache system. This determines wich messages
168 * the cache formats and logs into the log destination. Severity's are
169 * defined in the CacheLogger class.
170 *
171 * @param severity the severity level to set
172 */
173 void setLogSeverity(int severity);
174 }