Type Conversions for Token Values

Converting a token value to an object is sometimes useful when the value needs to be stored for future use in a generic way.

There are two ways to represent a token value as a Java object.

• Use the Java object corresponding to the value type. See Token Types and Related Java Types for a table that includes the Java class corresponding to each token type. For token types represented by Java primitives, the autoboxing conversions supported by Java can be used.

• Use one of the token object classes provided in DataFlow. These have a number of advantages over value objects:

– Token objects can unambiguously represent null values and understand the semantics of null. In contrast, a null object reference may or may not represent a null token, depending on the implementation of operators. Furthermore, special code for null value handling will be required.

– Token objects provide implementations of methods that are consistent with those for token values. For example, hashCode on an IntToken will match the value returned by TokenUtils.hashCode(IntInput) for the same token value; hashCode on an Integer will not.

– The class hierarchy of token objects matches the token type hierarchy. The lowest common superclass for a token object is DataToken. On the other hand, the lowest common superclass for value objects is Object, which is overly broad.

There are multiple ways to convert token values to token objects, as illustrated below:

IntValued value = ...;
TokenConverter converter = TokenConverters.getConverter(value.getType());
ScalarToken token1 = TokenUtil.asToken(value);
ScalarToken token2 = converter.asToken(value);
IntToken token3 = new IntToken(value); // Only possible because type is statically known

If a large number of conversions will be done, it is generally more efficient to use a TokenConverter instead of repeatedly using TokenUtils.asToken(TokenValued).

It is also useful to convert token values to strings. This can help dataflow operator developers when debugging the data provided by their input ports.

As with conversions to token objects, if many conversions are to be performed, then it is preferable to use a TokenConverter object allocated for that purpose instead of using TokenUtils.asString(TokenValued).