Top Description Fields Constructors Methods
net.sf.ehcache

public Class Element

extends Object
implements Serializable, Cloneable
Class Inheritance
All Implemented Interfaces
java.lang.Cloneable, java.io.Serializable
Imports
net.sf.ehcache.config.CacheConfiguration, net.sf.ehcache.pool.sizeof.annotations.IgnoreSizeOf, net.sf.ehcache.util.TimeUtil, org.slf4j.Logger, .LoggerFactory, java.io.ByteArrayInputStream, .ByteArrayOutputStream, .IOException, .ObjectInputStream, .ObjectOutputStream, .Serializable, java.util.concurrent.atomic.AtomicLongFieldUpdater
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.

Author
Greg Luck
Version
$Id: Element.java 10789 2018-04-26 02:08:13Z adahanne $

Field Summary

Modifier and TypeField and Description
private volatile boolean
cacheDefaultLifespan

private transient long
creationTime

The creation time.

private static final boolean
ELEMENT_VERSION_AUTO

private static final AtomicLongFieldUpdater<Element>
HIT_COUNT_UPDATER

private volatile long
hitCount

The number of times the element was hit.

private volatile long
id

private final Object
key

the cache key.

private transient long
lastAccessTime

The last access time.

private volatile long
lastUpdateTime

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.

private static final Logger
LOG

private static final long
NOT_SET_ID

private static final long
serialVersionUID

serial version Updated for version 1.2, 1.2.1 and 1.7

private volatile int
timeToIdle

The amount of time for the element to idle, in seconds.

private volatile int
timeToLive

The amount of time for the element to live, in seconds.

private final Object
value

the value.

private volatile long
version

version of the element.

Constructor Summary

AccessConstructor and Description
public
Element(final Serializable key, final Serializable value, final long version)

A full constructor.

public
Element(final Object key, final Object value, final long version)

A full constructor.

public
Element(final Object key, final Object value, final long version, final long creationTime, final long lastAccessTime, final long nextToLastAccessTime, final long lastUpdateTime, final 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.
public
Element(final Object key, final Object value, final long version, final long creationTime, final long lastAccessTime, final long lastUpdateTime, final long hitCount)

Constructor.

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

Constructor used by ElementData.

public
Element(final Object
any non null value
key, final Object
any value, including nulls
value, final int
seconds to idle
timeToIdleSeconds, final int
seconds to live
timeToLiveSeconds)

Constructor

public
Element(final Object
any non null value
key, final Object
any value, including nulls
value, final boolean
whether this element is eternal
eternal)

Constructor

public
Element(final Object
any non null value
key, final Object
any value, including nulls
value, final Boolean
specify as non-null to override cache configuration
eternal, final Integer
specify as non-null to override cache configuration
timeToIdleSeconds, final Integer
specify as non-null to override cache configuration
timeToLiveSeconds)

Deprecated
Constructor used by ehcache-server timeToIdleSeconds and timeToLiveSeconds will have precedence over eternal.
public
Element(final Serializable key, final Serializable value)

Constructor.

public
Element(final Object key, final Object value)

Constructor.

Method Summary

Modifier and TypeMethod and Description
public final Object

Returns:

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

Overrides java.lang.Object.clone.

Clones an Element.
private static Object
deepCopy(final Object oldValue)

public final boolean
equals(final Object
the reference object with which to compare.
object)

Overrides java.lang.Object.equals.

Equals comparison with another element, based on the key.
public final long

Returns:

The creationTime value
getCreationTime()

Gets the creationTime of the Element

pack-priv long

Returns:

System.currentTimeMillis() by default
getCurrentTime()

Seam for testing purposes

public long

Returns:

the time to expiration
getExpirationTime()

Returns the expiration time based on time to live.

public final long
getHitCount()

Gets the hit count on this element.

pack-priv long

Returns:

id the id
getId()

Gets the element identifier (this field is used internally by ehcache)

public final Serializable

Returns:

The key value.
getKey()

Deprecated Please use getObjectKey() instead.
Gets the key attribute of the Element object.
public final long

Returns:

last access time in unix epoch
getLastAccessTime()

Gets the last access time of this element.

public long

Returns:

the time when the last update occured. If this is the original Element, the time will be null
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.

public final long

Returns:

if never updated, creation time is returned, otherwise updated time
getLatestOfCreationAndUpdateTime()

Calculates the latest of creation and update time

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.
public final Object

Returns:

The key as an Object. i.e no restriction is placed on it
getObjectKey()

Gets the key attribute of the Element object.

public final Object

Returns:

The value as an Object. i.e no restriction is placed on it
getObjectValue()

Gets the value attribute of the Element object as an Object.

public final long

Returns:

The serialized size in bytes
getSerializedSize()

The size of this object in serialized form.

public int

Returns:

the time to idle, in seconds
getTimeToIdle()

public int

Returns:

the time to live, in seconds
getTimeToLive()

public final Serializable

Returns:

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

Deprecated Please use getObjectValue() instead.
Gets the value attribute of the Element object.
public final long

Returns:

The version value
getVersion()

Gets the version attribute of the ElementAttributes object.

public final int
hashCode()

Overrides java.lang.Object.hashCode.

Gets the hashcode, based on the key.
pack-priv boolean

Returns:

true if this element has an Id
hasId()

Determines if an Id has been set on this element

public boolean

Returns:

true if the element is eternal
isEternal()

public boolean

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

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

public boolean

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.
isExpired(CacheConfiguration
config to take default parameters from
config)

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

public final boolean

Returns:

true if the element's key is Serializable
isKeySerializable()

Whether the element's key may be Serialized.

public boolean

Returns:

true if set.
isLifespanSet()

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

public final boolean

Returns:

true if the element is Serializable
isSerializable()

Whether the element may be Serialized.

private void
readObject(ObjectInputStream in)

Custom serialization read logic

public final void
resetAccessStatistics()

Resets the hit count to 0 and the last access time to now.

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.
public void
setEternal(final boolean eternal)

Sets whether the element is eternal.

pack-priv void
setId(final long
The new id value
id)

Sets the element identifier (this field is used internally by ehcache).

protected void
setLifespanDefaults(int
TTI in seconds
tti, int
TTL in seconds
ttl, boolean
true if the element is eternal.
eternal)

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

public void
setTimeToIdle(final int
the number of seconds to idle
timeToIdleSeconds)

Sets time to idle

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

public void
setTimeToLive(final int
the number of seconds to live
timeToLiveSeconds)

Sets time to Live

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

public final void
setVersion(final long
The new version value
version)

Sets the version attribute of the ElementAttributes object.

public final String
toString()

Overrides java.lang.Object.toString.

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

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

public final void
updateUpdateStatistics()

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

public boolean

Returns:

false if this Element has a custom lifespan
usesCacheDefaultLifespan()

private void
writeObject(ObjectOutputStream out)

Custom serialization write logic

Inherited from java.lang.Object:
finalizegetClassnotifynotifyAllwaitwaitwait

Field Detail

cacheDefaultLifespanback to summary
private volatile boolean cacheDefaultLifespan
creationTimeback to summary
private transient long creationTime

The creation time.

ELEMENT_VERSION_AUTOback to summary
private static final boolean ELEMENT_VERSION_AUTO
HIT_COUNT_UPDATERback to summary
private static final AtomicLongFieldUpdater<Element> HIT_COUNT_UPDATER
hitCountback to summary
private volatile long hitCount

The number of times the element was hit.

idback to summary
private volatile long id
keyback to summary
private final Object key

the cache key.

Annotations
@IgnoreSizeOf
lastAccessTimeback to summary
private transient long lastAccessTime

The last access time.

lastUpdateTimeback to summary
private volatile long lastUpdateTime

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.

LOGback to summary
private static final Logger LOG
NOT_SET_IDback to summary
private static final long NOT_SET_ID
serialVersionUIDback to summary
private static final long serialVersionUID

serial version Updated for version 1.2, 1.2.1 and 1.7

timeToIdleback to summary
private volatile int timeToIdle

The amount of time for the element to idle, in seconds. 0 indicates unlimited.

timeToLiveback to summary
private volatile int timeToLive

The amount of time for the element to live, in seconds. 0 indicates unlimited.

valueback to summary
private final Object value

the value.

versionback to summary
private volatile long version

version of the element. System.currentTimeMillis() is used to compute version for updated elements. That way, the actual version of the updated element does not need to be checked.

Constructor Detail

Elementback to summary
public Element(final Serializable key, final Serializable value, final long version)

A full constructor.

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

Since
.4
Elementback to summary
public Element(final Object key, final Object value, final 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
Elementback to summary
public Element(final Object key, final Object value, final long version, final long creationTime, final long lastAccessTime, final long nextToLastAccessTime, final long lastUpdateTime, final 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.

Annotations
@Deprecated
Since
1.3
See Also
Element(Object, Object, long, long, long, long, long)
Elementback to summary
public Element(final Object key, final Object value, final long version, final long creationTime, final long lastAccessTime, final long lastUpdateTime, final long hitCount)

Constructor.

Since
1.7
Elementback to summary
public Element(final Object key, final Object value, final long version, final long creationTime, final long lastAccessTime, final long hitCount, final boolean cacheDefaultLifespan, final int timeToLive, final int timeToIdle, final long lastUpdateTime)

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

Since
1.7
Elementback to summary
public Element(final Object key, final Object value, final int timeToIdleSeconds, final int timeToLiveSeconds)

Constructor

Parameters
key:Object

any non null value

value:Object

any value, including nulls

timeToIdleSeconds:int

seconds to idle

timeToLiveSeconds:int

seconds to live

Since
2.7.1
Elementback to summary
public Element(final Object key, final Object value, final boolean eternal)

Constructor

Parameters
key:Object

any non null value

value:Object

any value, including nulls

eternal:boolean

whether this element is eternal

Since
2.7.1
Elementback to summary
public Element(final Object key, final Object value, final Boolean eternal, final Integer timeToIdleSeconds, final 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:Object

any non null value

value:Object

any value, including nulls

eternal:Boolean

specify as non-null to override cache configuration

timeToIdleSeconds:Integer

specify as non-null to override cache configuration

timeToLiveSeconds:Integer

specify as non-null to override cache configuration

Annotations
@Deprecated
Elementback to summary
public Element(final Serializable key, final Serializable value)

Constructor.

Elementback to summary
public Element(final Object key, final Object value)

Constructor.

Since
1.2

Method Detail

cloneback to summary
public final Object clone() throws CloneNotSupportedException

Overrides java.lang.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:Object

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

Annotations
@Override
Exceptions
CloneNotSupportedException:

Doc from java.lang.Object.clone.

if the object's class does not support the Cloneable interface. Subclasses that override the clone method can also throw this exception to indicate that an instance cannot be cloned.

deepCopyback to summary
private static Object deepCopy(final Object oldValue) throws IOException, ClassNotFoundException
equalsback to summary
public final boolean equals(final Object object)

Overrides java.lang.Object.equals.

Equals comparison with another element, based on the key.

Parameters
object:Object

Doc from java.lang.Object.equals.

the reference object with which to compare.

Returns:boolean

Doc from java.lang.Object.equals.

true if this object is the same as the obj argument; false otherwise.

Annotations
@Override
getCreationTimeback to summary
public final long getCreationTime()

Gets the creationTime of the Element

Returns:long

The creationTime value

getCurrentTimeback to summary
pack-priv long getCurrentTime()

Seam for testing purposes

Returns:long

System.currentTimeMillis() by default

getExpirationTimeback to summary
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:long

the time to expiration

getHitCountback to summary
public final long getHitCount()

Gets the hit count on this element.

getIdback to summary
pack-priv long getId()

Gets the element identifier (this field is used internally by ehcache)

Returns:long

id the id

getKeyback to summary
public final Serializable getKey() throws CacheException

Deprecated

Please use getObjectKey() instead.

Gets the key attribute of the Element object.

Returns:Serializable

The key value.

Annotations
@Deprecated
Exceptions
CacheException:
if the key is not Serializable.
getLastAccessTimeback to summary
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:long

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()
getLastUpdateTimeback to summary
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:long

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

getLatestOfCreationAndUpdateTimeback to summary
public final long getLatestOfCreationAndUpdateTime()

Calculates the latest of creation and update time

Returns:long

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

getNextToLastAccessTimeback to summary
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.

Annotations
@Deprecated
See Also
getLastAccessTime()
getObjectKeyback to summary
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:Object

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

See Also
getKey()
getObjectValueback to summary
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:Object

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

Since
1.2
See Also
getValue()
getSerializedSizeback to summary
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:long

The serialized size in bytes

getTimeToIdleback to summary
public int getTimeToIdle()
Returns:int

the time to idle, in seconds

getTimeToLiveback to summary
public int getTimeToLive()
Returns:int

the time to live, in seconds

getValueback to summary
public final Serializable getValue() throws CacheException

Deprecated

Please use getObjectValue() instead.

Gets the value attribute of the Element object.

Returns:Serializable

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

Annotations
@Deprecated
Exceptions
CacheException:
if the value is not Serializable.
getVersionback to summary
public final long getVersion()

Gets the version attribute of the ElementAttributes object.

Returns:long

The version value

hashCodeback to summary
public final int hashCode()

Overrides java.lang.Object.hashCode.

Gets the hashcode, based on the key.

Returns:int

Doc from java.lang.Object.hashCode.

a hash code value for this object.

Annotations
@Override
hasIdback to summary
pack-priv boolean hasId()

Determines if an Id has been set on this element

Returns:boolean

true if this element has an Id

isEternalback to summary
public boolean isEternal()
Returns:boolean

true if the element is eternal

isExpiredback to summary
public boolean isExpired()

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

Returns:boolean

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()
isExpiredback to summary
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:CacheConfiguration

config to take default parameters from

Returns:boolean

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()
isKeySerializableback to summary
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:boolean

true if the element's key is Serializable

Since
1.2
isLifespanSetback to summary
public boolean isLifespanSet()

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

Returns:boolean

true if set.

isSerializableback to summary
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:boolean

true if the element is Serializable

Since
1.2
readObjectback to summary
private void readObject(ObjectInputStream in) throws IOException, ClassNotFoundException

Custom serialization read logic

resetAccessStatisticsback to summary
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.

setCreateTimeback to summary
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.

Annotations
@Deprecated
setEternalback to summary
public void setEternal(final boolean eternal)

Sets whether the element is eternal.

setIdback to summary
pack-priv void setId(final long id)

Sets the element identifier (this field is used internally by ehcache). Setting this field in application code will not be preserved

Parameters
id:long

The new id value

setLifespanDefaultsback to summary
protected void setLifespanDefaults(int tti, int ttl, boolean eternal)

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

Parameters
tti:int

TTI in seconds

ttl:int

TTL in seconds

eternal:boolean

true if the element is eternal.

setTimeToIdleback to summary
public void setTimeToIdle(final 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:int

the number of seconds to idle

setTimeToLiveback to summary
public void setTimeToLive(final 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:int

the number of seconds to live

setVersionback to summary
public final void setVersion(final long version)

Sets the version attribute of the ElementAttributes object.

Parameters
version:long

The new version value

toStringback to summary
public final String toString()

Overrides java.lang.Object.toString.

Returns a String representation of the Element.

Returns:String

Doc from java.lang.Object.toString.

a string representation of the object.

Annotations
@Override
updateAccessStatisticsback to summary
public final void updateAccessStatistics()

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

updateUpdateStatisticsback to summary
public final void updateUpdateStatistics()

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

usesCacheDefaultLifespanback to summary
public boolean usesCacheDefaultLifespan()
Returns:boolean

false if this Element has a custom lifespan

writeObjectback to summary
private void writeObject(ObjectOutputStream out) throws IOException

Custom serialization write logic