|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object info.rolandkrueger.roklib.util.data.ManagedValue<T>
T
- the data value that this class is supposed to managepublic class ManagedValue<T>
Wrapper class for a single data value that monitors the status of and access
to this value. A ManagedValue
holds one piece of data that can be of
an arbitrary type. It provides additional services for this data that is
otherwise not available or only in a restricted way to the data object
itself.
One recurrent problem with data that does not necessarily need to be
initialized is for external code to determine whether the value is valid or
wasn't initialized yet. When the data is available as an object, one could
test if the object reference is null
. This isn't possible any
longer in the instance that the null
value is a valid value for
the object. The same applies to primitive data types. It is very clumsy if
not impossible to define a specific value, such as 0
, as a
marker for the status of the primitive value.
Class ManagedValue
alleviates this problem. It encapsulates a single
value together with its status without reserving a special value as a status
label. Thus, every possible value, such as null
or
0
can be used as valid data for the encapsulated object.
Furthermore, ManagedValue
lets you query the status of the encapsulated
data object. You can determine whether the object has been set, deleted or
changed, for instance.
Another feature of ManagedValue
is that it allows the locking of the
underlying data object. That is, the owner of the ManagedValue
can
hold an exclusive lock on the value, that prevents other objects from
changing the data of the ManagedValue
.
Nested Class Summary | |
---|---|
static class |
ManagedValue.StatusEnum
State of the encapsulated data object. |
Field Summary | |
---|---|
private ManagedValue.StatusEnum |
mStatus
|
private T |
mValue
|
private Object |
mWriteLock
|
Constructor Summary | |
---|---|
ManagedValue()
Default constructor. |
|
ManagedValue(ManagedValue<T> other)
Copy constructor. |
|
ManagedValue(T initialValue)
Creates a new ManagedValue with an initial value object. |
Method Summary | |
---|---|
boolean |
canRead()
Returns true if the current state of the ManagedValue
is either ManagedValue.StatusEnum.SET or
ManagedValue.StatusEnum.CHANGED . |
void |
deleteValue()
Unsets the data object. |
boolean |
equals(Object obj)
|
ManagedValue.StatusEnum |
getState()
Returns the current state of the data value. |
T |
getValue()
Returns the value object that is managed by this ManagedValue . |
int |
hashCode()
|
boolean |
isChanged()
Returns true if the current state of the ManagedValue
is ManagedValue.StatusEnum.CHANGED . |
boolean |
isDeleted()
Returns true if the current state of the ManagedValue
is ManagedValue.StatusEnum.DELETED . |
boolean |
isLocked()
Returns true if the ManagedValue is currently locked. |
boolean |
isSet()
Returns true if the current state of the ManagedValue
is ManagedValue.StatusEnum.SET . |
boolean |
isUndefined()
Returns true if the current state of the ManagedValue
is ManagedValue.StatusEnum.UNDEFINED . |
void |
lock(Object writeLock)
Locks a ManagedValue . |
void |
reset()
Resets the state of the data value. |
void |
setValue(T value)
Sets the value of the data object. |
void |
setValue(T value,
Object lockKey)
Sets the value of the data object. |
private void |
setValueInternal(T value)
|
String |
toString()
|
void |
unlock(Object writeLock)
Unlocks a previously locked ManagedValue . |
Methods inherited from class java.lang.Object |
---|
clone, finalize, getClass, notify, notifyAll, wait, wait, wait |
Field Detail |
---|
private T mValue
private ManagedValue.StatusEnum mStatus
private Object mWriteLock
Constructor Detail |
---|
public ManagedValue()
ManagedValue.StatusEnum.UNDEFINED
.
public ManagedValue(T initialValue)
ManagedValue
with an initial value object. The state
of the newly created ManagedValue
is
ManagedValue.StatusEnum.SET
.
initialValue
- the initial value objectpublic ManagedValue(ManagedValue<T> other)
ManagedValue
into this object.
other
- an other ManagedValue
Method Detail |
---|
public boolean canRead()
true
if the current state of the ManagedValue
is either ManagedValue.StatusEnum.SET
or
ManagedValue.StatusEnum.CHANGED
.
true
if the current state of the ManagedValue
is either ManagedValue.StatusEnum.SET
or
ManagedValue.StatusEnum.CHANGED
.public void deleteValue()
ManagedValue
is
ManagedValue.StatusEnum.DELETED
.
public ManagedValue.StatusEnum getState()
ManagedValue.StatusEnum
public T getValue()
ManagedValue
.
ManagedValue
.
IllegalStateException
- if the value either hasn't been initialized yet or was deleted
with deleteValue()
public void lock(Object writeLock)
ManagedValue
. By setting a lock, an owner of the
ManagedValue
can assure that no other external process can alter
the ManagedValue
's data object or change its state. If that is
being attempted by an object that doesn't own the lock key, an
IllegalStateException
will be raised. Unlocking the
ManagedValue
is only possible by passing the key object to the
respective unlock methods.
writeLock
- an arbitrary object instance that functions as the key for this
lock
NullPointerException
- if the key object is null
setValue(Object)
,
setValue(Object, Object)
public boolean isLocked()
true
if the ManagedValue
is currently locked.
true
if the ManagedValue
is currently locked.public void reset()
ManagedValue.StatusEnum.CHANGED
. If that is the case
the state is reset to ManagedValue.StatusEnum.SET
. Thus,
reset()
can be used to acknowledge that the
ManagedValue
's data has been changed.
public void setValue(T value)
ManagedValue
must not be
locked when this method is called. The new state of the value object is
either ManagedValue.StatusEnum.SET
if it was undefined or deleted
before this operation or ManagedValue.StatusEnum.CHANGED
if it was
already set.
value
-
IllegalStateException
- if this ManagedValue
is lockedpublic void setValue(T value, Object lockKey)
ManagedValue
is currently locked. The lock's key is provided as
the second parameter. The new state of the value object is either
ManagedValue.StatusEnum.SET
if it was undefined or deleted before this
operation or ManagedValue.StatusEnum.CHANGED
if it was already set.
value
- a new valuelockKey
- the object that was used to lock the ManagedValue
IllegalStateException
- if the ManagedValue
isn't currently locked
IllegalArgumentException
- if the passed lock key is not the same object instance as the key
object that was used to set the lockunlock(Object)
private void setValueInternal(T value)
public boolean isSet()
true
if the current state of the ManagedValue
is ManagedValue.StatusEnum.SET
.
true
if the current state of the ManagedValue
is ManagedValue.StatusEnum.SET
.public boolean isChanged()
true
if the current state of the ManagedValue
is ManagedValue.StatusEnum.CHANGED
.
true
if the current state of the ManagedValue
is ManagedValue.StatusEnum.CHANGED
.public boolean isUndefined()
true
if the current state of the ManagedValue
is ManagedValue.StatusEnum.UNDEFINED
.
true
if the current state of the ManagedValue
is ManagedValue.StatusEnum.UNDEFINED
.public boolean isDeleted()
true
if the current state of the ManagedValue
is ManagedValue.StatusEnum.DELETED
.
true
if the current state of the ManagedValue
is ManagedValue.StatusEnum.DELETED
.public boolean equals(Object obj)
equals
in class Object
public int hashCode()
hashCode
in class Object
public String toString()
toString
in class Object
public void unlock(Object writeLock)
ManagedValue
. Unlock will only succeed
if the given key has the same object reference as the key object that was
used to lock the ManagedValue
with
lock(Object)
. The given key is compared with the lock
key with the ==
operator.
writeLock
- the object that was used to lock the ManagedValue
IllegalStateException
- if the ManagedValue
isn't currently locked
IllegalArgumentException
- if the passed lock key is not the same object instance as the key
object that was used to set the locklock(Object)
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |