net.sf.ehcache

Class Element

public final class Element extends Object implements Serializable, Cloneable

A Cache Element, consisting of a key, value and attributes.

From ehcache-1.2, Elements can have keys and values that are Serializable or Objects. To preserve backward compatibility, special accessor methods for Object keys and values are provided: getObjectKey and getObjectValue. If placing Objects in ehcache, developers must use the new getObject... methods to avoid CacheExceptions. The get... methods are reserved for Serializable keys and values.

Version: $Id: Element.java 191 2006-09-03 22:41:48Z gregluck $

Author: Greg Luck

UNKNOWN: SerializableHasSerializationMethods

Constructor Summary
Element(Serializable key, Serializable value, long version)
A full constructor.
Element(Object key, Object value, long version)
A full constructor.
Element(Serializable key, Serializable value)
Constructor.
Element(Object key, Object value)
Constructor.
Method Summary
Objectclone()
Clones an Element.
booleanequals(Object object)
Equals comparison with another element, based on the key.
longgetCreationTime()
Gets the creationTime attribute of the ElementAttributes object.
longgetExpirationTime()
Returns the expiration time based on time to live.
longgetHitCount()
Gets the hit count on this element.
SerializablegetKey()
Gets the key attribute of the Element object.
longgetLastAccessTime()
Gets the last access time.
longgetLastUpdateTime()
If there is an Element in the Cache and it is replaced with a new Element for the same key, then both the version number and lastUpdateTime should be updated to reflect that.
longgetNextToLastAccessTime()
Gets the next to last access time.
ObjectgetObjectKey()
Gets the key attribute of the Element object.
ObjectgetObjectValue()
Gets the value attribute of the Element object as an Object.
longgetSerializedSize()
The size of this object in serialized form.
intgetTimeToIdle()
intgetTimeToLive()
SerializablegetValue()
Gets the value attribute of the Element object.
longgetVersion()
Gets the version attribute of the ElementAttributes object.
inthashCode()
Gets the hascode, based on the key.
booleanisEternal()
booleanisExpired()
An element is expired if the expiration time as given by getExpirationTime is in the past.
booleanisKeySerializable()
Whether the element's key may be Serialized.
booleanisLifespanSet()
Whether any combination of eternal, TTL or TTI has been set.
booleanisSerializable()
Whether the element may be Serialized.
voidresetAccessStatistics()
Resets the hit count to 0 and the last access time to 0.
voidsetCreateTime()
Sets the creationTime attribute of the ElementAttributes object.
voidsetEternal(boolean eternal)
Sets whether the element is eternal.
voidsetTimeToIdle(int timeToIdleSeconds)
Sets time to idle
voidsetTimeToLive(int timeToLiveSeconds)
Sets time to Live
voidsetVersion(long version)
Sets the version attribute of the ElementAttributes object.
StringtoString()
Returns a String representation of the Element.
voidupdateAccessStatistics()
Sets the last access time to now.
voidupdateUpdateStatistics()
Sets the last access time to now.

Constructor Detail

Element

public Element(Serializable key, Serializable value, long version)
A full constructor.

Creation time is set to the current time. Last Access Time and Previous To Last Access Time are not set.

Since: .4

Element

public Element(Object key, Object value, long version)
A full constructor.

Creation time is set to the current time. Last Access Time and Previous To Last Access Time are not set.

Since: 1.2

Element

public Element(Serializable key, Serializable value)
Constructor.

Parameters: key value

Element

public Element(Object key, Object value)
Constructor.

Parameters: key value

Since: 1.2

Method Detail

clone

public final Object clone()
Clones an Element. A completely new object is created, with no common references with the existing one.

This method will not work unless the Object is Serializable

Warning: This can be very slow on large object graphs. If you use this method you should write a performance test to verify suitability.

Returns: a new Element, with exactly the same field values as the one it was cloned from.

Throws: CloneNotSupportedException

equals

public final boolean equals(Object object)
Equals comparison with another element, based on the key.

getCreationTime

public final long getCreationTime()
Gets the creationTime attribute of the ElementAttributes object.

Returns: The creationTime value

getExpirationTime

public long getExpirationTime()
Returns the expiration time based on time to live. If this element also has a time to idle setting, the expiry time will vary depending on whether the element is accessed.

Returns: the time to expiration

getHitCount

public final long getHitCount()
Gets the hit count on this element.

getKey

public final Serializable getKey()
Gets the key attribute of the Element object.

Returns: The key value. If the key is not Serializable, null is returned and an info log message emitted

See Also: getObjectKey

getLastAccessTime

public final long getLastAccessTime()
Gets the last access time. Access means a get. So a newly created Element will have a last access time equal to its create time.

getLastUpdateTime

public long getLastUpdateTime()
If there is an Element in the Cache and it is replaced with a new Element for the same key, then both the version number and lastUpdateTime should be updated to reflect that. The creation time will be the creation time of the new Element, not the original one, so that TTL concepts still work.

Returns: the time when the last update occured. If this is the original Element, the time will be null

getNextToLastAccessTime

final long getNextToLastAccessTime()
Gets the next to last access time. This is package protected as it should not be used outside internal Cache housekeeping.

See Also: getLastAccessTime

getObjectKey

public final Object getObjectKey()
Gets the key attribute of the Element object.

This method is provided for those wishing to use ehcache as a memory only cache and enables retrieval of non-Serializable values from elements.

Returns: The key as an Object. i.e no restriction is placed on it

See Also: getKey

getObjectValue

public final Object getObjectValue()
Gets the value attribute of the Element object as an Object.

This method is provided for those wishing to use ehcache as a memory only cache and enables retrieval of non-Serializable values from elements.

Returns: The value as an Object. i.e no restriction is placed on it

Since: 1.2

See Also: getValue

getSerializedSize

public final long getSerializedSize()
The size of this object in serialized form. This is not the same thing as the memory size, which is JVM dependent. Relative values should be meaningful, however.

Warning: This method can be very slow for values which contain large object graphs.

If the key or value of the Element is not Serializable, an error will be logged and 0 will be returned.

Returns: The serialized size in bytes

getTimeToIdle

public int getTimeToIdle()

Returns: the time to idle, in seconds

getTimeToLive

public int getTimeToLive()

Returns: the time to live, in seconds

getValue

public final Serializable getValue()
Gets the value attribute of the Element object.

Returns: The value which must be Serializable. If not use Element. If the value is not Serializable, null is returned and an info log message emitted

See Also: getObjectValue

getVersion

public final long getVersion()
Gets the version attribute of the ElementAttributes object.

Returns: The version value

hashCode

public final int hashCode()
Gets the hascode, based on the key.

isEternal

public boolean isEternal()

Returns: true if the element is eternal

isExpired

public boolean isExpired()
An element is expired if the expiration time as given by getExpirationTime is in the past.

Returns: true if the Element is expired, otherwise false. If no lifespan has been set for the Element it is considered not able to expire.

See Also: getExpirationTime

isKeySerializable

public final boolean isKeySerializable()
Whether the element's key may be Serialized.

While Element implements Serializable, it is possible to create non Serializable elements and/or non Serializable keys for use in MemoryStores.

This method checks that an instance of an Element's key really is Serializable and will not throw a NonSerializableException if Serialized.

Returns: true if the element's key is Serializable

Since: 1.2

isLifespanSet

public boolean isLifespanSet()
Whether any combination of eternal, TTL or TTI has been set.

Returns: true if set.

isSerializable

public final boolean isSerializable()
Whether the element may be Serialized.

While Element implements Serializable, it is possible to create non Serializable elements for use in MemoryStores. This method checks that an instance of Element really is Serializable and will not throw a NonSerializableException if Serialized.

Returns: true if the element is Serializable

Since: 1.2

resetAccessStatistics

public final void resetAccessStatistics()
Resets the hit count to 0 and the last access time to 0.

setCreateTime

public final void setCreateTime()
Sets the creationTime attribute of the ElementAttributes object.

setEternal

public void setEternal(boolean eternal)
Sets whether the element is eternal.

Parameters: eternal

setTimeToIdle

public void setTimeToIdle(int timeToIdleSeconds)
Sets time to idle

Parameters: timeToIdleSeconds the number of seconds to idle

setTimeToLive

public void setTimeToLive(int timeToLiveSeconds)
Sets time to Live

Parameters: timeToLiveSeconds the number of seconds to live

setVersion

public final void setVersion(long version)
Sets the version attribute of the ElementAttributes object.

Parameters: version The new version value

toString

public final String toString()
Returns a String representation of the Element.

updateAccessStatistics

public final void updateAccessStatistics()
Sets the last access time to now.

updateUpdateStatistics

public final void updateUpdateStatistics()
Sets the last access time to now.