ptolemy.data
Class Token

java.lang.Object
  extended byptolemy.data.Token
All Implemented Interfaces:
java.io.Serializable
Direct Known Subclasses:
AbsentToken, AbstractConvertibleToken, AbstractNotConvertibleToken, ActorToken, EventToken, FunctionToken, GeneralToken, ImageToken, KeyToken, MatrixToken, NullToken, ObjectToken, ScalarToken, UnknownToken, XMLToken

public class Token
extends java.lang.Object
implements java.io.Serializable

Token is the base class for data capsules. Tokens are immutable, meaning that their value cannot change after construction. They have a set of polymorphic methods providing a set of basic arithmetic and logical operations. Generally, derived classes should override the methods to implement type specific operations that make sense for a given type. For operations that are non-sensical for a given type, such as division of matrices, the implementation of this base class can be used, which simply throws an exception.

Generally, it is painful to implement both the operation and operationReverse methods of this class. It is also painful to implement tokens that are automatically converted to other tokens in a consistent fashion. As such, there are several subclasses of this class that implement these methods and provide a somewhat nicer abstraction. The ScalarToken derived class is useful for many types that are losslessly convertible to other types and may be associated with units, such as IntToken. The MatrixToken derived class is useful for implementing matrices of ScalarTokens, such as IntMatrixToken. The AbstractNotConvertible derived class is useful for implementing tokens that are not losslessly convertible to a token in implemented in another class, such as ArrayToken. Lastly, AbstractConvertibleToken is useful for implementing tokens that are losslessly convertible to a token in another class, but don't have units, such as BooleanToken.

Instances of this base class *should not* be used to represent pure events, i.e., to indicate that an event is present. To represent pure events, it is better to use the EventToken class. The reasoning is that the type BaseType.GENERAL is reserved to represent types which the type system cannot represent exactly. Using the EventToken class, and the type BaseType.EVENT allows typesafe use of pure events.

Since:
Ptolemy II 0.2
Version:
$Id: Token.java,v 1.108 2004/04/13 05:12:09 cxh Exp $
Author:
Neil Smyth, Yuhong Xiong, Edward A. Lee, Christopher Hylands, Steve Neuendorffer
See Also:
ScalarToken, AbstractConvertibleToken, AbstractNotConvertibleToken, MatrixToken, Serialized Form
Accepted Rating:
Yellow (neuendor)
Proposed Rating:
Green (neuendor)

Constructor Summary
Token()
           
 
Method Summary
 Token add(Token rightArgument)
          Return a new token whose value is the sum of this token and the argument.
 Token addReverse(Token leftArgument)
          Return a new token whose value is the sum of this token and the argument.
 Token divide(Token rightArgument)
          Return a new token whose value is the value of this token divided by the value of the argument token.
 Token divideReverse(Token leftArgument)
          Return a new token whose value is the value of the argument token divided by the value of this token.
 Type getType()
          Return the type of this token.
 BooleanToken isCloseTo(Token token)
          Test that the value of this Token is close to the argument 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)
          Test for equality of the values of this Token and the argument Token.
 Token modulo(Token rightArgument)
          Return a new token whose value is the value of this token modulo the value of the argument token.
 Token moduloReverse(Token leftArgument)
          Return a new token whose value is the value of the argument token modulo the value of this token.
 Token multiply(Token rightArgument)
          Return a new token whose value is the value of this token multiplied by the value of the argument token.
 Token multiplyReverse(Token leftArgument)
          Return a new token whose value is the value of the argument token multiplied by the value of this token.
static java.lang.String notSupportedConversionMessage(Token token, java.lang.String typeString)
          Return a string with an error message that states that the given token cannot be converted to the given token type.
static java.lang.String notSupportedIncomparableConversionMessage(Token token, java.lang.String typeString)
          Return a string with an error message that states that the given token cannot be converted to the given token type.
static java.lang.String notSupportedIncomparableMessage(java.lang.String operation, Token firstToken, Token secondToken)
          Return a string with an error message that states that the given operation is not supported between two tokens, because they have incomparable types and cannot be converted to the same type.
static java.lang.String notSupportedMessage(java.lang.String operation, Token firstToken, Token secondToken)
          Return a string with an error message that states that the given operation is not supported between two tokens.
 Token one()
          Returns a new Token representing the multiplicative identity.
 Token pow(int times)
          Return a new token computed as follows: For positive times arguments, the result represents the product of this token multiplied by itself the number of times given by the argument.
 Token subtract(Token rightArgument)
          Return a new token whose value is the value of the argument token subtracted from the value of this token.
 Token subtractReverse(Token leftArgument)
          Return a new token whose value is the value of this token subtracted from the value of the argument token.
 java.lang.String toString()
          Return the value of this token as a string that can be parsed by the expression language to recover a token with the same value.
 Token zero()
          Returns a new token representing the additive identity.
static Type zeroReturnType(Type type)
          Return the (exact) return type of the zero function above.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Token

public Token()
Method Detail

add

public Token add(Token rightArgument)
          throws IllegalActionException
Return a new token whose value is the sum of this token and the argument.

Parameters:
rightArgument - The token to add to this token.
Returns:
A new token containing the result.
Throws:
IllegalActionException - If the argument token and this token are of incomparable types, or the operation does not make sense for the given types.

addReverse

public Token addReverse(Token leftArgument)
                 throws IllegalActionException
Return a new token whose value is the sum of this token and the argument.

Parameters:
leftArgument - The token to add this token to.
Returns:
A new token containing the result.
Throws:
IllegalActionException - If the argument token and this token are of incomparable types, or the operation does not make sense for the given types.

divide

public Token divide(Token rightArgument)
             throws IllegalActionException
Return a new token whose value is the value of this token divided by the value of the argument token.

Parameters:
rightArgument - The token to divide into this token.
Returns:
A new token containing the result.
Throws:
IllegalActionException - If the argument token and this token are of incomparable types, or the operation does not make sense for the given types.

divideReverse

public Token divideReverse(Token leftArgument)
                    throws IllegalActionException
Return a new token whose value is the value of the argument token divided by the value of this token.

Parameters:
leftArgument - The token to be divided by the value of this token.
Returns:
A new token containing the result.
Throws:
IllegalActionException - If the argument token and this token are of incomparable types, or the operation does not make sense for the given types.

getType

public Type getType()
Return the type of this token.

Returns:
BaseType.GENERAL

isCloseTo

public final BooleanToken isCloseTo(Token token)
                             throws IllegalActionException
Test that the value of this Token is close to the argument Token. In this base class, we call isEqualTo(). This method should be overridden in derived classes such as DoubleToken and ComplexToken to provide type specific actions for equality testing using an epsilon factor.

Parameters:
token - The token to test closeness of this token with.
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 is not of a type that can be compared with this token.
See Also:
isEqualTo(ptolemy.data.Token)

isCloseTo

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

Parameters:
token - The token to test closeness of this token with.
epsilon - The value that we use to determine whether two tokens are close.
Returns:
A boolean token that contains the value true if the value of this token are close to those of the argument token.
Throws:
IllegalActionException - If the argument token is not of a type that can be compared with this token.

isEqualTo

public BooleanToken isEqualTo(Token rightArgument)
                       throws IllegalActionException
Test for equality of the values of this Token and the argument Token.

Parameters:
rightArgument - The token with which to test equality.
Returns:
A BooleanToken which contains the result of the test.
Throws:
IllegalActionException - If the argument token is not of a type that can be compared with this token.

modulo

public Token modulo(Token rightArgument)
             throws IllegalActionException
Return a new token whose value is the value of this token modulo the value of the argument token.

Parameters:
rightArgument - The token to divide into this token.
Returns:
A new token containing the result.
Throws:
IllegalActionException - If the argument token and this token are of incomparable types, or the operation does not make sense for the given types.

moduloReverse

public Token moduloReverse(Token leftArgument)
                    throws IllegalActionException
Return a new token whose value is the value of the argument token modulo the value of this token.

Parameters:
leftArgument - The token to apply modulo to by the value of this token.
Returns:
A new token containing the result.
Throws:
IllegalActionException - If the argument token and this token are of incomparable types, or the operation does not make sense for the given types.

multiply

public Token multiply(Token rightArgument)
               throws IllegalActionException
Return a new token whose value is the value of this token multiplied by the value of the argument token.

Parameters:
rightArgument - The token to multiply this token by.
Returns:
A new token containing the result.
Throws:
IllegalActionException - If the argument token and this token are of incomparable types, or the operation does not make sense for the given types.

multiplyReverse

public Token multiplyReverse(Token leftArgument)
                      throws IllegalActionException
Return a new token whose value is the value of the argument token multiplied by the value of this token.

Parameters:
leftArgument - The token to be multiplied by the value of this token.
Returns:
A new token containing the result.
Throws:
IllegalActionException - If the argument token and this token are of incomparable types, or the operation does not make sense for the given types.

notSupportedConversionMessage

public static java.lang.String notSupportedConversionMessage(Token token,
                                                             java.lang.String typeString)
Return a string with an error message that states that the given token cannot be converted to the given token type.

Parameters:
token - The token being converted.
typeString - A string representing the type that is being converted to.
Returns:
A string error message.

notSupportedIncomparableConversionMessage

public static java.lang.String notSupportedIncomparableConversionMessage(Token token,
                                                                         java.lang.String typeString)
Return a string with an error message that states that the given token cannot be converted to the given token type.

Parameters:
token - The token being converted.
typeString - A string representing the type that is being converted to.
Returns:
A string error message.

notSupportedIncomparableMessage

public static java.lang.String notSupportedIncomparableMessage(java.lang.String operation,
                                                               Token firstToken,
                                                               Token secondToken)
Return a string with an error message that states that the given operation is not supported between two tokens, because they have incomparable types and cannot be converted to the same type.

Parameters:
operation - A string naming the unsupported token operation.
firstToken - The first token in the message.
secondToken - The second token in the message.
Returns:
A string error message.

notSupportedMessage

public static java.lang.String notSupportedMessage(java.lang.String operation,
                                                   Token firstToken,
                                                   Token secondToken)
Return a string with an error message that states that the given operation is not supported between two tokens.

Parameters:
operation - A string naming the unsupported token operation.
firstToken - The first token in the message.
secondToken - The second token in the message.
Returns:
A string error message.

one

public Token one()
          throws IllegalActionException
Returns a new Token representing the multiplicative identity. It should be overridden in subclasses.

Returns:
A new Token containing the multiplicative identity.
Throws:
IllegalActionException - If this method is not supported by the derived class.

pow

public Token pow(int times)
          throws IllegalActionException
Return a new token computed as follows:

subtract

public Token subtract(Token rightArgument)
               throws IllegalActionException
Return a new token whose value is the value of the argument token subtracted from the value of this token.

Parameters:
rightArgument - The token to subtract from this token.
Returns:
A new token containing the result.
Throws:
IllegalActionException - If the argument token and this token are of incomparable types, or the operation does not make sense for the given types.

subtractReverse

public Token subtractReverse(Token leftArgument)
                      throws IllegalActionException
Return a new token whose value is the value of this token subtracted from the value of the argument token.

Parameters:
leftArgument - The token to subtract this token from.
Returns:
A new token containing the result.
Throws:
IllegalActionException - If the argument token and this token are of incomparable types, or the operation does not make sense for the given types.

toString

public java.lang.String toString()
Return the value of this token as a string that can be parsed by the expression language to recover a token with the same value. This method should be overridden by derived classes. In this base class, return the String "present" to indicate that an event is present.

Returns:
The String "present".

zero

public Token zero()
           throws IllegalActionException
Returns a new token representing the additive identity. It should be overridden in subclasses.

Returns:
A new Token containing the additive identity.
Throws:
IllegalActionException - If this method is not supported by the derived class.

zeroReturnType

public static Type zeroReturnType(Type type)
Return the (exact) return type of the zero function above. The argument type is always returned

Parameters:
type - The type of the argument to the corresponding function.
Returns:
The type of the value returned from the corresponding function.