info.rolandkrueger.roklib.util.data
Class ManagedValue<T>

java.lang.Object
  info.rolandkrueger.roklib.util.data.ManagedValue<T>

Type Parameters:

T - the data value that this class is supposed to manage

public class ManagedValue<T>
extends Object

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.

Author:

Roland Krueger

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

mValue

private T mValue

mStatus

private ManagedValue.StatusEnum mStatus

mWriteLock

private Object mWriteLock

Constructor Detail

ManagedValue

public ManagedValue()

Default constructor. Sets the state of the underlying data object to ManagedValue.StatusEnum.UNDEFINED.

ManagedValue

public ManagedValue(T initialValue)

Creates a new ManagedValue with an initial value object. The state of the newly created ManagedValue is ManagedValue.StatusEnum.SET.

Parameters:

initialValue - the initial value object

ManagedValue

public ManagedValue(ManagedValue<T> other)

Copy constructor. Copies the exact state of the other ManagedValue into this object.

Parameters:

other - an other ManagedValue

Method Detail

canRead

public boolean canRead()

Returns true if the current state of the ManagedValue is either ManagedValue.StatusEnum.SET or ManagedValue.StatusEnum.CHANGED.

Returns:

true if the current state of the ManagedValue is either ManagedValue.StatusEnum.SET or ManagedValue.StatusEnum.CHANGED.

deleteValue

public void deleteValue()

Unsets the data object. The new state of the ManagedValue is ManagedValue.StatusEnum.DELETED.

getState

public ManagedValue.StatusEnum getState()

Returns the current state of the data value.

Returns:

the current state of the data value.

See Also:

ManagedValue.StatusEnum

getValue

public T getValue()

Returns the value object that is managed by this ManagedValue.

Returns:

the value object that is managed by this ManagedValue.

Throws:

IllegalStateException - if the value either hasn't been initialized yet or was deleted with deleteValue()

lock

public void lock(Object writeLock)

Locks a 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.

Parameters:

writeLock - an arbitrary object instance that functions as the key for this lock

Throws:

NullPointerException - if the key object is null

See Also:

setValue(Object), setValue(Object, Object)

isLocked

public boolean isLocked()

Returns true if the ManagedValue is currently locked.

Returns:

true if the ManagedValue is currently locked.

reset

public void reset()

Resets the state of the data value. This will only have any effect if the current status is 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.

setValue

public void setValue(T value)

Sets the value of the data object. The 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.

Parameters:

value -

Throws:

IllegalStateException - if this ManagedValue is locked

setValue

public void setValue(T value,
                     Object lockKey)

Sets the value of the data object. This method can be used if and only if the 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.

Parameters:

value - a new value

lockKey - the object that was used to lock the ManagedValue

Throws:

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 lock

See Also:

unlock(Object)

setValueInternal

private void setValueInternal(T value)

isSet

public boolean isSet()

Returns true if the current state of the ManagedValue is ManagedValue.StatusEnum.SET.

Returns:

true if the current state of the ManagedValue is ManagedValue.StatusEnum.SET.

isChanged

public boolean isChanged()

Returns true if the current state of the ManagedValue is ManagedValue.StatusEnum.CHANGED.

Returns:

true if the current state of the ManagedValue is ManagedValue.StatusEnum.CHANGED.

isUndefined

public boolean isUndefined()

Returns true if the current state of the ManagedValue is ManagedValue.StatusEnum.UNDEFINED.

Returns:

true if the current state of the ManagedValue is ManagedValue.StatusEnum.UNDEFINED.

isDeleted

public boolean isDeleted()

Returns true if the current state of the ManagedValue is ManagedValue.StatusEnum.DELETED.

Returns:

true if the current state of the ManagedValue is ManagedValue.StatusEnum.DELETED.

equals

public boolean equals(Object obj)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

toString

public String toString()

Overrides:

toString in class Object

unlock

public void unlock(Object writeLock)

Unlocks a previously locked 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.

Parameters:

writeLock - the object that was used to lock the ManagedValue

Throws:

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 lock

See Also:

lock(Object)