001package org.apache.commons.jcs3.engine.behavior;
002
003/*
004 * Licensed to the Apache Software Foundation (ASF) under one
005 * or more contributor license agreements.  See the NOTICE file
006 * distributed with this work for additional information
007 * regarding copyright ownership.  The ASF licenses this file
008 * to you under the Apache License, Version 2.0 (the
009 * "License"); you may not use this file except in compliance
010 * with the License.  You may obtain a copy of the License at
011 *
012 *   http://www.apache.org/licenses/LICENSE-2.0
013 *
014 * Unless required by applicable law or agreed to in writing,
015 * software distributed under the License is distributed on an
016 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
017 * KIND, either express or implied.  See the License for the
018 * specific language governing permissions and limitations
019 * under the License.
020 */
021
022import java.io.Serializable;
023import java.util.ArrayList;
024import java.util.List;
025
026import org.apache.commons.jcs3.engine.control.event.behavior.IElementEventHandler;
027
028/**
029 * Interface for cache element attributes classes. Every item is the cache is associated with an
030 * element attributes object. It is used to track the life of the object as well as to restrict its
031 * behavior. By default, elements get a clone of the region's attributes.
032 */
033public interface IElementAttributes extends Serializable, Cloneable
034{
035    /**
036     * Sets the maxLife attribute of the IAttributes object.
037     * <p>
038     * @param mls The new MaxLifeSeconds value
039     */
040    void setMaxLife(long mls);
041
042    /**
043     * Sets the maxLife attribute of the IAttributes object. How many seconds it can live after
044     * creation.
045     * <p>
046     * If this is exceeded the element will not be returned, instead it will be removed. It will be
047     * removed on retrieval, or removed actively if the memory shrinker is turned on.
048     * @return The MaxLifeSeconds value
049     */
050    long getMaxLife();
051
052    /**
053     * Sets the idleTime attribute of the IAttributes object. This is the maximum time the item can
054     * be idle in the cache, that is not accessed.
055     * <p>
056     * If this is exceeded the element will not be returned, instead it will be removed. It will be
057     * removed on retrieval, or removed actively if the memory shrinker is turned on.
058     * @param idle The new idleTime value
059     */
060    void setIdleTime( long idle );
061
062    /**
063     * Size in bytes. This is not used except in the admin pages. It will be 0 by default
064     * and is only updated when the element is serialized.
065     * <p>
066     * @param size The new size value
067     */
068    void setSize( int size );
069
070    /**
071     * Gets the size attribute of the IAttributes object
072     * <p>
073     * @return The size value
074     */
075    int getSize();
076
077    /**
078     * Gets the createTime attribute of the IAttributes object.
079     * <p>
080     * This should be the current time in milliseconds returned by the sysutem call when the element
081     * is put in the cache.
082     * <p>
083     * Putting an item in the cache overrides any existing items.
084     * @return The createTime value
085     */
086    long getCreateTime();
087
088    /**
089     * Gets the LastAccess attribute of the IAttributes object.
090     * <p>
091     * @return The LastAccess value.
092     */
093    long getLastAccessTime();
094
095    /**
096     * Sets the LastAccessTime as now of the IElementAttributes object
097     */
098    void setLastAccessTimeNow();
099
100    /**
101     * Gets the idleTime attribute of the IAttributes object
102     * @return The idleTime value
103     */
104    long getIdleTime();
105
106    /**
107     * Gets the time left to live of the IAttributes object.
108     * <p>
109     * This is the (max life + create time) - current time.
110     * @return The TimeToLiveSeconds value
111     */
112    long getTimeToLiveSeconds();
113
114    /**
115     * Can this item be spooled to disk
116     * <p>
117     * By default this is true.
118     * @return The spoolable value
119     */
120    boolean getIsSpool();
121
122    /**
123     * Sets the isSpool attribute of the IElementAttributes object
124     * <p>
125     * By default this is true.
126     * @param val The new isSpool value
127     */
128    void setIsSpool( boolean val );
129
130    /**
131     * Is this item laterally distributable. Can it be sent to auxiliaries of type lateral.
132     * <p>
133     * By default this is true.
134     * @return The isLateral value
135     */
136    boolean getIsLateral();
137
138    /**
139     * Sets the isLateral attribute of the IElementAttributes object
140     * <p>
141     * By default this is true.
142     * @param val The new isLateral value
143     */
144    void setIsLateral( boolean val );
145
146    /**
147     * Can this item be sent to the remote cache.
148     * <p>
149     * By default this is true.
150     * @return The isRemote value
151     */
152    boolean getIsRemote();
153
154    /**
155     * Sets the isRemote attribute of the IElementAttributes object.
156     * <p>
157     * By default this is true.
158     * @param val The new isRemote value
159     */
160    void setIsRemote( boolean val );
161
162    /**
163     * This turns off expiration if it is true.
164     * @return The IsEternal value
165     */
166    boolean getIsEternal();
167
168    /**
169     * Sets the isEternal attribute of the IElementAttributes object
170     * @param val The new isEternal value
171     */
172    void setIsEternal( boolean val );
173
174    /**
175     * Adds a ElementEventHandler. Handler's can be registered for multiple events. A registered
176     * handler will be called at every recognized event.
177     * @param eventHandler The feature to be added to the ElementEventHandler
178     */
179    void addElementEventHandler( IElementEventHandler eventHandler );
180
181    /**
182     * Gets the elementEventHandlers.
183     * <p>
184     * Event handlers are transient. The only events defined are in memory events. All handlers are
185     * lost if the item goes to disk.
186     * @return The elementEventHandlers value, null if there are none
187     */
188    ArrayList<IElementEventHandler> getElementEventHandlers();
189
190    /**
191     * Sets the eventHandlers of the IElementAttributes object
192     * @param eventHandlers value
193     */
194    void addElementEventHandlers( List<IElementEventHandler> eventHandlers );
195
196    long getTimeFactorForMilliseconds();
197
198    void setTimeFactorForMilliseconds(long factor);
199
200    /**
201     * Clone object
202     */
203    IElementAttributes clone();
204}