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@sourceforge.net
18 */
19 package javax.util.jcache;
20
21 /**
22 * This class defines the attributes an object in the cache can have.
23 * @deprecated removed with no replacement.
24 */
25 public interface Attributes {
26 //This class is completely implemented.
27 /** Event wich is fired when invalidation of an cacheobject is fired. */
28 public static final int INVALIDATE_EVENT = 0;
29 /**
30 * Indicates the object is distributed, updates and invalidations are
31 * distributed to other processes. Default is to not distribute changes.
32 */
33 public static final long DISTRIBUTE = 1;
34 /**
35 * Indicates to not flush the object from the cache if the object is
36 * distributed and the cache is isolated from other caches. Default is to
37 * flush the object. This flag is ignored if a "time to live" is specified,
38 * or the object is local.
39 */
40 public static final long NOFLUSH = 2;
41 /**
42 * Indicates a reply should be sent from the remote caches if this object is
43 * updated or invalidated. The default is no reply. If the object is local,
44 * this flag is ignored.
45 */
46 public static final long REPLY = 4;
47 /**
48 * Indicates that the updates to this object should be synchronized. If this
49 * flag is set, only the owner of an object can update or invalidate the
50 * object. The default is no synchronization.
51 */
52 public static final long SYNCHRONIZE = 8;
53 /**
54 * Indicates the object shoulod be spooled to disk when the object is being
55 * removed from the memory cache because of space limitations. This flag is
56 * only valid for memory objects.
57 */
58 public static final long SPOOL = 16;
59 /**
60 * Indicates the group object should be destroyed when the associated time
61 * to live expires. In the default case only the child objects are
62 * invalidated. The group remains valid.
63 */
64 public static final long GROUP_TTL_DESTROY = 32;
65 /**
66 * Indicates the object was created in the cache and can't be recreated if
67 * removed from the cache. Original objects don't get removed from the cache
68 * even when they are not referenced. Original objects must be invalidated
69 * before they get removed fromthe cache.
70 */
71 public static final long ORIGINAL = 64;
72
73 /**
74 * Is used to specify wich attributes should be set in the attributes
75 * object. The different attributes wich is valid is defined as public
76 * static variables in the {@link Attributes}class.
77 *
78 * @param theFlags The attributes to set. the attributes may be OR-ed
79 * together. I.e. Attributes.DISTRIBUTE | Attributes.SYNCHRONIZE
80 * Invalid flags are silently ignored. To reset all flags you use
81 * 0 as a parameter. I.e. setFlags(0)
82 */
83 public abstract void setFlags(final long theFlags);
84
85 /**
86 * Will associate a loader object with this object.
87 *
88 * @param aLoader The loader to set. This parameter can be null.
89 */
90 public abstract void setLoader(final CacheLoader aLoader);
91
92 /**
93 * Sets the version attribute. Is only maintained for user convenience. It
94 * is not used internally by the cache.
95 *
96 * @param aVersion the version number to set.
97 */
98 public abstract void setVersion(final long aVersion);
99
100 /**
101 * Will set the maximum time the associated cache object will stay in the
102 * cache before it is invalidated. The time starts when the object is loaded
103 * into the cache(by the {@link CacheLoader}object or put by the
104 * {@link CacheAccess#replace(Object, Object)}) or when the time to live
105 * attribute is set by the {@link CacheLoader#setAttributes(Object,
106 * Attributes)} method.
107 *
108 * @param ttl the time to live in seconds. The {@link #timeToSeconds(int,
109 * int, int, int)} can be used to convert days, hours, minutes to
110 * seconds.
111 *
112 * @throws InvalidArgumentException if a negative value for ttl is supplied.
113 */
114 public abstract void setTimeToLive(final long ttl) throws InvalidArgumentException;
115
116 /**
117 * Will set the maximum time the associated cache object will stay in the
118 * cache before it is invalidated. For regions and groups, this will
119 * establish a default time to live that is applied individually to each
120 * member in the group or region. It will not cause the entire group or
121 * region to time out as a whole. For individual objects, the default time
122 * to live is equivalent with time to live. If both are set the default time
123 * to live is ignored. The time starts when the object is loaded into the
124 * cache(by the {@link CacheLoader}objector put by the {@link
125 * CacheAccess#replace(Object, Object)}) or when the time to live attribute
126 * is set by the {@link CacheLoader#setAttributes(Object,Attributes)}
127 * method.
128 *
129 * @param ttl the time to live in seconds. The {@link #timeToSeconds(int,
130 * int, int, int)} can be used to convert days, hours, minutes to
131 * secounds.
132 *
133 * @throws InvalidArgumentException if a negative value for ttl is supplied.
134 */
135 public abstract void setDefaultTimeToLive(final long ttl) throws InvalidArgumentException;
136
137 public abstract long getDefaultTimeToLive();
138
139 /**
140 * sets the maximum time the associated cache object will remain in the
141 * cache without being referenced before it is invalidated.
142 *
143 * @param idle is in seconds. The {@link #timeToSeconds(int, int, int,int)}
144 * can be used to convert days, hours, minutes to secounds.
145 *
146 * @throws InvalidArgumentException if a negative value for idle is
147 * supplied.
148 */
149 public abstract void setIdleTime(final long idle) throws InvalidArgumentException;
150
151 /**
152 * Register an event listener object to be executed when the specified event
153 * occurs with relationship to the associated object. Currently the only
154 * invalidate event being monitored is Attributes.INVALIDATE_EVENT. If
155 * invalid parameters are passed such as invalid events, or null as
156 * listener, this method silently returns without doing any changes to this
157 * object.
158 *
159 * @param event The event to listen for.
160 * @param aListener the listener to fire when the event occurs.
161 *
162 *@todo Should these Attributes only have one Listener, or should several be
163 * supported?
164 */
165 public abstract void setListener(final int event, final CacheEventListener aListener);
166
167 /**
168 * Is used to specify the size in bytes of the object being cached. This is
169 * used to determine when the cache capacity is reached. If the cache is not
170 * using object size to determine the capacity (It can also use object
171 * counts) this value is ignored.
172 *
173 * @param aSize the size to be set. if this parameter is smaller than zero,
174 * this method silently returns.
175 */
176 public abstract void setSize(final int aSize);
177
178 /**
179 * returns the size of the object. this size is set by the {@link
180 * #setSize(int)} method, or in the case of StreamAccess objects, the size
181 * is calculated by the cache.
182 * @todo create and implement an online size calculator.
183 * @return the size of the object, or 0 if the size has not been set.
184 */
185 public abstract int getSize();
186
187 /**
188 * Checks wether the flags are set or not.
189 *
190 * @param theFlags the flags to be checked. may be OR-ed together, for wich
191 * this method will return true only if all flags are set.
192 *
193 * @return true if the specified attribute is set, false otherwise.
194 */
195 public abstract boolean isSet(final long theFlags);
196
197 /**
198 * returns the time the object was loaded into the cache. The time is the
199 * number of milliseconds since midnight, January 1, 1970 (UTC).
200 *
201 * @return the time the object was loaded into the cache. The time is the
202 * number of milliseconds since midnight, January 1, 1970 (UTC).
203 */
204 public abstract long getCreateTime();
205
206 /**
207 * returns the {@link CacheLoader}attribute.
208 *
209 * @return the {@link CacheLoader}attribute.
210 */
211 public abstract CacheLoader getLoader();
212
213 /**
214 * returns the current value of version.
215 *
216 * @return the current value of version.
217 */
218 public abstract long getVersion();
219
220 /**
221 * returns the current value for the idle time interval.
222 *
223 * @return the current value for the idle time interval.
224 */
225 public abstract long getIdleTime();
226
227 /**
228 * returns the current value for the time to live interval.
229 *
230 * @return the current value for the time to live interval.
231 */
232 public abstract long getTimeToLive();
233
234 /**
235 * resets the Attributes to its default values. The attributes wich are
236 * reset are expiration time attributes, time to live, default time to
237 * live, idle time and event handlers.
238 *
239 * @todo This method should be package private, thus this class should be
240 * moved to org.fjank.jcache, an interface should be extracted, and
241 * that should be public, and in this package.
242 */
243 public abstract void reset();
244
245 /**
246 * Sets the createTime.
247 *
248 * @param aCreateTime The createTime to set
249 */
250 public abstract void setCreateTime(final long aCreateTime);
251 /**
252 * Will convert the time specified into seconds.
253 *
254 * @param days number of days.
255 * @param hours number of hours.
256 * @param minutes number of minutes.
257 * @param seconds number of seconds.
258 *
259 * @return the converted time in seconds.
260 *
261 * @throws InvalidArgumentException if any of the parameters are negative
262 * values.
263 */
264 public long timeToSeconds(final int days, final int hours, final int minutes, final int seconds) throws InvalidArgumentException;
265 /**
266 * Gets the CacheEventListener.
267 * @author Philippe Fajeau
268 * @return The CacheEventListener.
269 */
270 public abstract CacheEventListener getListener();
271 public void applyAttributes(Attributes attributes);
272 }