Package ptolemy.data

Class Token

  • Direct Known Subclasses:
    AbsentToken, AbstractConvertibleToken, AbstractNotConvertibleToken, ActorToken, BluetoothToken, ControlToken, DummyReferenceToken, EventToken, FunctionToken, GeneralToken, KeyToken, MatrixToken, NullToken, ObjectToken, PointerToken, PtrToken, ScalarToken, Scene2DToken, SceneGraphToken, TestToken, TupleToken, UnknownToken, XMLToken
    public class Token
extends java.lang.Object
    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 NIL for details.

    Since:
    Ptolemy II 0.2
    Version:
    $Id$
    Author:
    Neil Smyth, Yuhong Xiong, Edward A. Lee, Christopher Brooks, Steve Neuendorffer
    See Also:
    ScalarToken, AbstractConvertibleToken, AbstractNotConvertibleToken, MatrixToken
    Pt.AcceptedRating:
    Red (cxh) nil token code
    Pt.ProposedRating:
    Yellow (cxh)

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static Token NIL
      A token that represents a missing value.

    • Constructor Summary

      Constructors 
      Constructor Description
      Token()
      Create a Token.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      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.
      boolean isNil()
      Return true if the token is nil, (aka null or missing).
      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.
      static java.lang.String notSupportedNullNilStringMessage​(java.lang.String type, java.lang.String init)
      Return a string with an error message that states that the token cannot be created with a string that is null or the value of the init parameter.
      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

    • Field Detail

      • NIL

        public static final Token NIL
        A token that represents a missing value. Null or missing tokens are common in analytical systems like R and SAS where they are used to handle sparsely populated data sources. In database parlance, missing tokens are sometimes called null tokens. Since null is a Java keyword, we use the term "nil". The toString() method on a nil token returns the string "nil".

    • Constructor Detail

      • Token

        public Token()
        Create a 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. If either this token or the argument token is a nil token, then NIL is returned.
        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. If either this token or the argument token is a nil token, then NIL is returned.
        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. If either this token or the argument token is a nil token, then NIL is returned.
        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. If either this token or the argument token is a nil token, then a boolean token that contains the value false is returned.
        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. If either this token or the argument token is a nil token, then a boolean token that contains the value false is returned.
        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. If either this token or the argument token is a nil token, then a boolean token that contains the value false is returned.
        Throws:
        IllegalActionException - If the argument token is not of a type that can be compared with this token.

      • isNil

        public boolean isNil()
        Return true if the token is nil, (aka null or missing). Nil or missing tokens occur when a data source is sparsely populated.
        Returns:
        True if the token is equals() to NIL.

      • 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. If either this token or the argument token is a nil token, then NIL is returned.
        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. If either this token or the argument token is a nil token, then NIL is returned.
        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. If either this token or the argument token is a nil token, then NIL is returned.
        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. If this token is a nil token, then NIL is returned.
        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:
        For positive times arguments, the result represents the product of this token multiplied by itself the number of times given by the argument.
        For negative times arguments, the result represents the multiplicative inverse of the product of this token multiplied by itself the number of times given by the absolute value of the argument.
        More succinctly: one().divide(pow(-times))
        If the argument is zero, then the result is defined to be the result of applying the one() method to this token.

        The token type returned by this method is the same as the type of this token. Note that the method is different from java.lang.Math.pow(), since it returns an integer given an integer token type, and is also well defined for matrix types.

        Parameters:
        times - The number of times to multiply.
        Returns:
        The power. If this token is a nil token, then NIL is returned.
        Throws:
        IllegalActionException - If the token is not compatible for this operation. Specifically, if the Token type does not support division (for example matrices) then using a negative times argument may throw an exception.

      • 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. If either this token or the argument token is a nil token, then NIL is returned.
        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. If either this token or the argument token is a nil token, then NIL is returned.
        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. If this token is NIL then return "nil"
        Overrides:
        toString in class java.lang.Object
        Returns:
        The String "present", unless this token is NIL, in which case return the String "nil".

      • 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. If this token is a nil token, then NIL is returned.
        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.

      • notSupportedNullNilStringMessage

        public static java.lang.String notSupportedNullNilStringMessage​(java.lang.String type,
                                                                java.lang.String init)
        Return a string with an error message that states that the token cannot be created with a string that is null or the value of the init parameter.
        Parameters:
        type - The type we are trying to create.
        init - The initialization string.
        Returns:
        A string error message.