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.
Nil, null or missing tokens are common in analytical systems like R and SAS where they are used to handle sparsely populated data sources. This class has support for such tokens, see {@link #NIL} for details.
@author Neil Smyth, Yuhong Xiong, Edward A. Lee, Christopher Brooks,Steve Neuendorffer
@version $Id: Token.java,v 1.142 2007/12/07 06:31:37 cxh Exp $
@since Ptolemy II 0.2
@Pt.ProposedRating Yellow (cxh)
@Pt.AcceptedRating Red (cxh) nil token code
@see ScalarToken
@see AbstractConvertibleToken
@see AbstractNotConvertibleToken
@see MatrixToken