ptolemy.data

Class ObjectToken

java.lang.Object

ptolemy.data.Token

ptolemy.data.ObjectToken

Direct Known Subclasses:

ConceptToken, ImageToken

public class ObjectToken
extends Token

A token that contains a reference to an arbitrary object. Note that when this token constructed, the object passed to the constructor is not cloned. Thus, care must be exercised to ensure that actors do not modify that object in a nondeterministic way, unless such nondeterminism is acceptable.

Since:

Ptolemy II 0.2

Version:

$Id$

Author:

Edward A. Lee

Pt.AcceptedRating:

Yellow (wbwu)

Pt.ProposedRating:

Yellow (yuhong)

Field Summary

Fields

Modifier and Type	Field and Description
protected java.lang.Class	_class The class of the object.
protected java.lang.Object	_value The actual Object.
static ObjectToken	NULL A new empty ObjectToken.

Fields inherited from class ptolemy.data.Token

NIL

Constructor Summary

Constructors

Constructor and Description
ObjectToken() Construct an empty token.
ObjectToken(java.lang.Object value) Construct a token with a reference to the specified object.
ObjectToken(java.lang.Object value, java.lang.Class<?> valueClass) Construct a token with the given value and the given class as the value's type.

Method Summary

Modifier and Type	Method and Description
protected BooleanToken	_isCloseTo(Token rightArgument, double epsilon) Test for closeness of the values of this Token and the argument Token.
protected BooleanToken	_isEqualTo(Token rightArgument) Test for equality of the values of this Token and the argument Token.
static ObjectToken	convert(Token token) Convert the specified token into an instance of ObjectToken.
boolean	equals(java.lang.Object object) Return true if the argument is an instance of ObjectToken and its contained object is equal to the object contained in this token, as tested by the equals() method of the contained object.
Type	getType() Return the type of this token.
java.lang.Object	getValue() Return the value of the token, a reference to an object.
java.lang.Class	getValueClass() Return the class of the object contained in this token.
int	hashCode() Return a hash code value for this token.
BooleanToken	isCloseTo(Token token, double epsilon) Test that the value of this token is close to the first argument, where "close" means that the distance between them is less than or equal to the second argument.
BooleanToken	isEqualTo(Token rightArgument) Compare this ObjectToken to the given argument, and return true if the values contained in the two are the same Java object.
static ObjectToken	object(java.lang.String className) Return an ObjectToken with value null and class specified by the className argument.
java.lang.String	toString() Return the value of this token as a string.

Methods inherited from class ptolemy.data.Token

add, addReverse, divide, divideReverse, isCloseTo, isNil, modulo, moduloReverse, multiply, multiplyReverse, notSupportedConversionMessage, notSupportedIncomparableConversionMessage, notSupportedIncomparableMessage, notSupportedMessage, notSupportedNullNilStringMessage, one, pow, subtract, subtractReverse, zero, zeroReturnType

Methods inherited from class java.lang.Object

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

Field Detail

NULL

public static final ObjectToken NULL

A new empty ObjectToken.

_class

protected java.lang.Class _class

The class of the object.

_value

protected java.lang.Object _value

The actual Object. This is protected to allow access in derived classes only.

Constructor Detail

ObjectToken

public ObjectToken()

Construct an empty token.

ObjectToken

public ObjectToken(java.lang.Object value)
            throws IllegalActionException

Construct a token with a reference to the specified object.

Parameters:

value - The specified object referred to by this token.

Throws:

IllegalActionException - If the argument is not of the appropriate type (may be thrown by derived classes, but is not thrown here).

ObjectToken

public ObjectToken(java.lang.Object value,
                   java.lang.Class<?> valueClass)
            throws IllegalActionException

Construct a token with the given value and the given class as the value's type.

Parameters:

value - The value.

valueClass - The class of the value.

Throws:

IllegalActionException - If the argument is not of the appropriate type.

Method Detail

convert

public static ObjectToken convert(Token token)
                           throws IllegalActionException

Convert the specified token into an instance of ObjectToken. This method does lossless conversion. If the argument is already an instance of ObjectToken, it is returned without any change. Otherwise, if the argument is below ObjectToken in the type hierarchy, it is converted to an instance of ObjectToken or one of the subclasses of ObjectToken and returned. If none of the above condition is met, an exception is thrown.

Parameters:

token - The token to be converted to an ObjectToken.

Returns:

An ObjectToken.

Throws:

IllegalActionException - If the conversion cannot be carried out.

equals

public boolean equals(java.lang.Object object)

Return true if the argument is an instance of ObjectToken and its contained object is equal to the object contained in this token, as tested by the equals() method of the contained object.

Overrides:

equals in class java.lang.Object

Parameters:

object - An instance of Object.

Returns:

True if the argument is an instance of ObjectToken and its contained object is equal to the object contained in this token.

getType

public Type getType()

Return the type of this token.

Overrides:

getType in class Token

Returns:

BaseType.OBJECT

getValue

public java.lang.Object getValue()

Return the value of the token, a reference to an object.

Returns:

The Object in this token.

getValueClass

public java.lang.Class getValueClass()

Return the class of the object contained in this token.

Returns:

The class of the object.

hashCode

public int hashCode()

Return a hash code value for this token. This method returns the hash code of the contained object.

Overrides:

hashCode in class java.lang.Object

Returns:

A hash code value for this token.

isCloseTo

public final BooleanToken isCloseTo(Token token,
                                    double epsilon)
                             throws IllegalActionException

Test that the value of this token is close to the first argument, where "close" means that the distance between them is less than or equal to the second argument. This method only makes sense for tokens where the distance between them is reasonably represented as a double. If the argument token is not of the same type as this token, then either this token or the argument will be converted, if possible, to the type of the other.

Subclasses should not generally override this method, but override the protected _isCloseTo() method to ensure that type conversion is performed consistently.

Overrides:

isCloseTo in class Token

Parameters:

token - The token to test closeness of this token with.

epsilon - The value that we use to determine whether two tokens are close. Ignored in this class.

Returns:

A boolean token that contains the value true if the value and units of this token are close to those of the argument token.

Throws:

IllegalActionException - If the argument token and this token are of incomparable types, or the operation does not make sense for the given types.

isEqualTo

public BooleanToken isEqualTo(Token rightArgument)

Compare this ObjectToken to the given argument, and return true if the values contained in the two are the same Java object.

Overrides:

isEqualTo in class Token

Parameters:

rightArgument - The argument.

Returns:

true if the values are the same Java object, or false otherwise.

object

public static ObjectToken object(java.lang.String className)
                          throws IllegalActionException

Return an ObjectToken with value null and class specified by the className argument.

Parameters:

className - The className.

Returns:

The ObjectToken.

Throws:

IllegalActionException - If the class with className as its name cannot be loaded.

toString

public java.lang.String toString()

Return the value of this token as a string. The returned syntax looks like a function call to a one argument method named "object". The argument is the string representation of the contained object, or the string "null" if the object is null. Notice that this syntax is not currently parsable by the expression language.

Overrides:

toString in class Token

Returns:

A String representing the object.

_isCloseTo

protected BooleanToken _isCloseTo(Token rightArgument,
                                  double epsilon)
                           throws IllegalActionException

Test for closeness of the values of this Token and the argument Token. It is assumed that the type of the argument is an ObjectToken.

Parameters:

rightArgument - The token to add to this token.

epsilon - The value that we use to determine whether two tokens are close. This parameter is ignored by this class.

Returns:

A BooleanToken containing the result.

Throws:

IllegalActionException - If this method is not supported by the derived class.

_isEqualTo

protected BooleanToken _isEqualTo(Token rightArgument)
                           throws IllegalActionException

Test for equality of the values of this Token and the argument Token. It is assumed that the type of the argument is ObjectToken.

Parameters:

rightArgument - The token to add to this token.

Returns:

A BooleanToken containing the result.

Throws:

IllegalActionException - If this method is not supported by the derived class.