Package net.sf.ehcache

Class Element

java.lang.Object

net.sf.ehcache.Element

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable

public class Element
extends java.lang.Object
implements java.io.Serializable, java.lang.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$

Author:

Greg Luck

See Also:

Serialized Form

Constructor Summary

Constructors

Constructor	Description
Element(java.io.Serializable key, java.io.Serializable value)	Constructor.
Element(java.io.Serializable key, java.io.Serializable value, long version)	A full constructor.
Element(java.lang.Object key, java.lang.Object value)	Constructor.
Element(java.lang.Object key, java.lang.Object value, boolean eternal)	Constructor
Element(java.lang.Object key, java.lang.Object value, int timeToIdleSeconds, int timeToLiveSeconds)	Constructor
Element(java.lang.Object key, java.lang.Object value, long version)	A full constructor.
Element(java.lang.Object key, java.lang.Object value, long version, long creationTime, long lastAccessTime, long hitCount, boolean cacheDefaultLifespan, int timeToLive, int timeToIdle, long lastUpdateTime)	Constructor used by ElementData.
Element(java.lang.Object key, java.lang.Object value, long version, long creationTime, long lastAccessTime, long lastUpdateTime, long hitCount)	Constructor.
Element(java.lang.Object key, java.lang.Object value, long version, long creationTime, long lastAccessTime, long nextToLastAccessTime, long lastUpdateTime, long hitCount)	Deprecated. The nextToLastAccessTime field is unused since version 1.7, setting it will have no effect.
Element(java.lang.Object key, java.lang.Object value, java.lang.Boolean eternal, java.lang.Integer timeToIdleSeconds, java.lang.Integer timeToLiveSeconds)	Deprecated.

Method Summary

Modifier and Type	Method	Description
java.lang.Object	clone()	Clones an Element.
boolean	equals(java.lang.Object object)	Equals comparison with another element, based on the key.
long	getCreationTime()	Gets the creationTime of the Element
long	getExpirationTime()	Returns the expiration time based on time to live.
long	getHitCount()	Gets the hit count on this element.
java.io.Serializable	getKey()	Deprecated. Please use getObjectKey() instead.
long	getLastAccessTime()	Gets the last access time of this element.
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.
long	getLatestOfCreationAndUpdateTime()	Calculates the latest of creation and update time
long	getNextToLastAccessTime()	Deprecated. The nextToLastAccessTime field is unused since version 1.7, retrieving it will return the lastAccessTime.
java.lang.Object	getObjectKey()	Gets the key attribute of the Element object.
java.lang.Object	getObjectValue()	Gets the value attribute of the Element object as an Object.
long	getSerializedSize()	The size of this object in serialized form.
int	getTimeToIdle()
int	getTimeToLive()
java.io.Serializable	getValue()	Deprecated. Please use getObjectValue() instead.
long	getVersion()	Gets the version attribute of the ElementAttributes object.
int	hashCode()	Gets the hashcode, based on the key.
boolean	isEternal()
boolean	isExpired()	An element is expired if the expiration time as given by getExpirationTime() is in the past.
boolean	isExpired(CacheConfiguration config)	An element is expired if the expiration time as given by getExpirationTime() is in the past.
boolean	isKeySerializable()	Whether the element's key may be Serialized.
boolean	isLifespanSet()	Whether any combination of eternal, TTL or TTI has been set.
boolean	isSerializable()	Whether the element may be Serialized.
void	resetAccessStatistics()	Resets the hit count to 0 and the last access time to now.
void	setCreateTime()	Deprecated. Resetting the creation time is not recommended as of version 1.7
void	setEternal(boolean eternal)	Sets whether the element is eternal.
protected void	setLifespanDefaults(int tti, int ttl, boolean eternal)	Set the default parameters of this element - those from its enclosing cache.
void	setTimeToIdle(int timeToIdleSeconds)	Sets time to idle
void	setTimeToLive(int timeToLiveSeconds)	Sets time to Live
void	setVersion(long version)	Sets the version attribute of the ElementAttributes object.
java.lang.String	toString()	Returns a String representation of the Element.
void	updateAccessStatistics()	Sets the last access time to now and increase the hit count.
void	updateUpdateStatistics()	Sets the last access time to now without updating the hit count.
boolean	usesCacheDefaultLifespan()

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

Element

public Element(java.io.Serializable key,
               java.io.Serializable value,
               long version)

A full constructor.

Creation time is set to the current time. Last Access Time is not set.

Since:

.4

Element

public Element(java.lang.Object key,
               java.lang.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

@Deprecated
public Element(java.lang.Object key,
               java.lang.Object value,
               long version,
               long creationTime,
               long lastAccessTime,
               long nextToLastAccessTime,
               long lastUpdateTime,
               long hitCount)

Deprecated.

The nextToLastAccessTime field is unused since version 1.7, setting it will have no effect. Use #Element(Object, Object, long, long, long, long, long) instead

Constructor.

Since:

1.3

See Also:

Element(Object, Object, long, long, long, long, long)

Element

public Element(java.lang.Object key,
               java.lang.Object value,
               long version,
               long creationTime,
               long lastAccessTime,
               long lastUpdateTime,
               long hitCount)

Constructor.

Since:

1.7

Element

public Element(java.lang.Object key,
               java.lang.Object value,
               long version,
               long creationTime,
               long lastAccessTime,
               long hitCount,
               boolean cacheDefaultLifespan,
               int timeToLive,
               int timeToIdle,
               long lastUpdateTime)

Constructor used by ElementData. Needs to be public since ElementData might be in another classloader

Since:

1.7

Element

public Element(java.lang.Object key,
               java.lang.Object value,
               int timeToIdleSeconds,
               int timeToLiveSeconds)

Constructor

Parameters:

key - any non null value

value - any value, including nulls

timeToIdleSeconds - seconds to idle

timeToLiveSeconds - seconds to live

Since:

2.7.1

Element

public Element(java.lang.Object key,
               java.lang.Object value,
               boolean eternal)

Constructor

Parameters:

key - any non null value

value - any value, including nulls

eternal - whether this element is eternal

Since:

2.7.1

Element

@Deprecated
public Element(java.lang.Object key,
               java.lang.Object value,
               java.lang.Boolean eternal,
               java.lang.Integer timeToIdleSeconds,
               java.lang.Integer timeToLiveSeconds)

Deprecated.

Constructor used by ehcache-server timeToIdleSeconds and timeToLiveSeconds will have precedence over eternal. Which means that what ever eternal says, non-null timeToIdleSeconds or timeToLiveSeconds will result in the element not being eternal

Parameters:

key - any non null value

value - any value, including nulls

eternal - specify as non-null to override cache configuration

timeToIdleSeconds - specify as non-null to override cache configuration

timeToLiveSeconds - specify as non-null to override cache configuration

Element

public Element(java.io.Serializable key,
               java.io.Serializable value)

Constructor.

Parameters:

key -

value -

Element

public Element(java.lang.Object key,
               java.lang.Object value)

Constructor.

Parameters:

key -

value -

Since:

1.2

Method Detail

getKey

@Deprecated
public final java.io.Serializable getKey()
                                  throws CacheException

Deprecated.

Please use getObjectKey() instead.

Gets the key attribute of the Element object.

Returns:

The key value.

Throws:

CacheException - if the key is not Serializable.

getObjectKey

public final java.lang.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()

getValue

@Deprecated
public final java.io.Serializable getValue()
                                    throws CacheException

Deprecated.

Please use getObjectValue() instead.

Gets the value attribute of the Element object.

Returns:

The value which must be Serializable. If not use getObjectValue().

Throws:

CacheException - if the value is not Serializable.

getObjectValue

public final java.lang.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()

equals

public final boolean equals(java.lang.Object object)

Equals comparison with another element, based on the key.

Overrides:

equals in class java.lang.Object

setTimeToLive

public void setTimeToLive(int timeToLiveSeconds)

Sets time to Live

Value must be a positive integer, 0 means infinite time to live.

If calling this method with 0 as the parameter, consider using setEternal(boolean) or make sure you also explicitly call setTimeToIdle(int).

Parameters:

timeToLiveSeconds - the number of seconds to live

setTimeToIdle

public void setTimeToIdle(int timeToIdleSeconds)

Sets time to idle

Value must be a positive integer, 0 means infinite time to idle.

If calling this method with 0 as the parameter, consider using setEternal(boolean) or make sure you also explicitly call setTimeToLive(int).

Parameters:

timeToIdleSeconds - the number of seconds to idle

hashCode

public final int hashCode()

Gets the hashcode, based on the key.

Overrides:

hashCode in class java.lang.Object

setVersion

public final void setVersion(long version)

Sets the version attribute of the ElementAttributes object.

Parameters:

version - The new version value

setCreateTime

@Deprecated
public final void setCreateTime()

Deprecated.

Resetting the creation time is not recommended as of version 1.7

Sets the creationTime attribute of the ElementAttributes object.

Note that in a Terracotta clustered environment, resetting the creation time will not have any effect.

getCreationTime

public final long getCreationTime()

Gets the creationTime of the Element

Returns:

The creationTime value

getLatestOfCreationAndUpdateTime

public final long getLatestOfCreationAndUpdateTime()

Calculates the latest of creation and update time

Returns:

if never updated, creation time is returned, otherwise updated time

getVersion

public final long getVersion()

Gets the version attribute of the ElementAttributes object.

Returns:

The version value

getLastAccessTime

public final long getLastAccessTime()

Gets the last access time of this element.

Access means the element was written into a cache or read from it. When first instantiated an Element has a lastAccessTime of 0, unless passed into the constructor.

Returns:

last access time in unix epoch

See Also:

Element(Object, Object, long, long, long, long, boolean, int, int, long), Element(Object, Object, long, long, long, long, long), resetAccessStatistics(), updateAccessStatistics()

getNextToLastAccessTime

@Deprecated
public final long getNextToLastAccessTime()

Deprecated.

The nextToLastAccessTime field is unused since version 1.7, retrieving it will return the lastAccessTime. Use #getLastAccessTime() instead.

Gets the next to last access time.

See Also:

getLastAccessTime()

getHitCount

public final long getHitCount()

Gets the hit count on this element.

resetAccessStatistics

public final void resetAccessStatistics()

Resets the hit count to 0 and the last access time to now. Used when an Element is put into a cache.

updateAccessStatistics

public final void updateAccessStatistics()

Sets the last access time to now and increase the hit count.

updateUpdateStatistics

public final void updateUpdateStatistics()

Sets the last access time to now without updating the hit count.

toString

public final java.lang.String toString()

Returns a String representation of the Element.

Overrides:

toString in class java.lang.Object

clone

public final java.lang.Object clone()
                             throws java.lang.CloneNotSupportedException

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.

Overrides:

clone in class java.lang.Object

Returns:

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

Throws:

java.lang.CloneNotSupportedException

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

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.

This method was tweaked in 1.6 as it has been shown that Serializable classes can be serializaed as can null, regardless of what class it is a null of. ObjectOutputStream.write(null) works and ObjectInputStream.read() will read null back.

Returns:

true if the element is Serializable

Since:

1.2

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

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

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()

isExpired

public boolean isExpired(CacheConfiguration config)

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

This method in addition propogates the default TTI/TTL values of the supplied cache into this element.

Parameters:

config - config to take default parameters from

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()

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

isEternal

public boolean isEternal()

Returns:

true if the element is eternal

setEternal

public void setEternal(boolean eternal)

Sets whether the element is eternal.

Parameters:

eternal -

isLifespanSet

public boolean isLifespanSet()

Whether any combination of eternal, TTL or TTI has been set.

Returns:

true if set.

getTimeToLive

public int getTimeToLive()

Returns:

the time to live, in seconds

getTimeToIdle

public int getTimeToIdle()

Returns:

the time to idle, in seconds

usesCacheDefaultLifespan

public boolean usesCacheDefaultLifespan()

Returns:

false if this Element has a custom lifespan

setLifespanDefaults

protected void setLifespanDefaults(int tti,
                                   int ttl,
                                   boolean eternal)

Set the default parameters of this element - those from its enclosing cache.

Parameters:

tti - TTI in seconds

ttl - TTL in seconds

eternal - true if the element is eternal.