5 Invoking Methods
Every element and subexpression in an expression represents an
instance of the Token class in Ptolemy II (or more
likely, a class derived from Token). The expression language supports
invocation of any method of a given token, as long as
the arguments of the method are of type Token and the return type is
Token (or a class derived from Token, or something that the expression
parser can easily convert to a token, such as a string, double,
int, etc.). The syntax for this is (token ).methodName(args), where methodName is the name of
the method and args is a comma-separated set of
arguments. Each argument can itself be an expression. Note that the
parentheses around the token are not required, but might be
useful for clarity. As an example, the ArrayToken and RecordToken
classes have a length() method, illustrated by the following examples:
{1, 2, 3}.\index{length()}
{a=1, b=2, c=3}.length()
each of which returns the integer 3.
The MatrixToken classes have three
particularly useful methods, illustrated in the following examples:
[1, 2; 3, 4; 5, 6].\index{getRowCount()}
which returns 3, and
[1, 2; 3, 4; 5, 6].getColumnCount()
which returns 2, and
[1, 2; 3, 4; 5, 6].toArray()
which returns 1, 2, 3, 4, 5, 6. The latter function can be particularly useful for creating arrays using MATLAB-style syntax. For example, to obtain an array with the integers from 1 to 100, you can enter:
[1:1:100].toArray()
6 Casting
The cast function can be used to explicitly cast a value into a type.
When the cast function is invoked with cast(type, value), where type
is the target type and value is the value to be cast, a new value is
returned (if a predefined casting is applicable) that is in the specified type.
For example, cast(long, 1) yields 1L, which is equal to 1 but is in the
long data type, and cast(string, 1) yields "1", which is in the string
data type.
6.1 Object Types
An object token encapsulates a Java object. Methods defined in the Java class of
that object can be invoked in an expression. For example, in a model that
contains an actor named C, C in an expression may refer to that actor
in an object token.
An object token has a type, which is an object type that is specific for the
class of the encapsulated Java object or any class that is a superclass of that
class. For example, with C being a Const actor, expression C
is of an object type that is specific to the Java class ptolemy.actor.lib.Const.
An object type specific to Java class A can be specified with
object(Ä"), and its value is null. Comparison between object tokens
is by reference with the Java objects that they encapsulate. Therefore,
object(Ä") == object("B") is always true, because the values in both
tokens are null.
6.2 Relationship between Object Types
An object type A is more specific than object type B if the Java class
represented by A is a subclass of that represented by B.
For example, object("ptolemy.actor.TypedIOPort") is more specific than
object("ptolemy.actor.IOPort") and object("ptolemy.kernel.Port").
The most general object type is object (without any argument). Conceptually
it encapsulates a null class (which, of course, does not exist in Java). The most
specific object type is object("ptolemy.data.type.ObjectType$BottomClass")
(which is not very useful in practice). The family of object types forms a
lattice.
6.3 Object Tokens
Object tokens are tokens of object types. A predefined object token is
null, which has null as the value and the null class as the Java
class. Its type is object. It is special in that it can be cast
into any object type. For example, you can cast it into a port with
cast(object("ptolemy.kernel.Port"), null). If you enter this in
the expression evaluator, you shall see the stringification of the
token as öbject(null: ptolemy.kernel.Port)".
(Notice that the string here is not a valid Ptolemy expression. In fact, most
object tokens do not have string representations that are valid expressions, and
therefore, they cannot be stored permanently in a Ptolemy model.)
Except for null, for a Ptolemy expression that evaluates to an object
token, the Java class represented by that token's type is always the most
specific class. For example, if C is a Const actor, then C in an
expression refers to an object token that has actor C as its value, and
object("ptolemy.actor.lib.Const") as its type. You can cast this type into
a more general actor type by doing cast(object("ptolemy.actor.Actor"), C).
6.4 Casting between Object Types
An object token can be cast into a different object type, as long as the target
object type represents a Java class that the encapsulated object is in. That
class need not always be a superclass of the class that the object type
represents.
For example, again let C be a Const actor. As discussed, the following
expression casts it into a more general actor type:
cast(object("ptolemy.actor.Actor"), C)
The result of the cast is another object token with C as its value and
object("ptolemy.actor.Actor") as its type. That token can be casted
back into one of a more specific object type:
cast(object("ptolemy.actor.TypedAtomicActor"),
cast(object("ptolemy.actor.Actor"), C))
This is valid because the value C is in any of the mentioned classes.
As mentioned, null is a special object token that can be cast into any
object type. Any object token can also be cast into the most general object type,
which is object. The only object that can be cast into the most specific
object type, object("ptolemy.data.type.ObjectType$BottomClass"), is
null.
6.5 Method Invocation
Native Java methods may be invoked on the objects encapsulated in object tokens.
For example, if C is a Const actor, C.portList() returns a list of
its ports. The returned list itself is a Java object in the class java.util.List,
so it is encapsulated in an object token. You may further invoke
C.portList().isEmpty() to test whether the list is empty. In that case, the
isEmpty method is invoked on the returned list. The isEmpty method returns
a Java boolean value, and the boolean type corresponds to the Ptolemy boolean
data type, so the value is converted into the latter type.
