The simplest way to look at a tuple is as a map of fields, that is, an object in which you can put,
get, and
remove fields. A tuple can also be seen as a self-contained, self-describing set of fields. Tuples are self-describing in that you can get a list of the names of all the fields contained in a tuple (although not in any specific order). A tuple does not have any reference to any metaspace or space in particular. A copy of the tuple is made inside an tuple during a space put operation.
It is not necessary to be connected to any metaspace or joined to a space in order to create and use a tuple. You can, for example, extract a tuple out of the tuple that was returned by a get from one space, modify it by changing field values (or adding or removing fields), and then to
put that tuple into another space (as long as the fields in the tuple are compatible with that space’s field definitions). And you can
put a tuple into a space and then re-use the same tuple object by updating one of the field values and using it to do another
put in the same space.
Fields also have a value and a type (see Field Definitions for the list of field types supported by ActiveSpaces). The tuple object has a
put method for each one of the supported field types.
The Java API also has an overloaded generic put method that uses the type of the value being passed to establish the type of the field, for example:
The tuple object also has a set of get methods used to get fields of the appropriate type. For example,
tuple.getString(“Name”) will return a string.
This is because if there is no field by the name requested in the get method in the tuple, a null is returned, rather than an exception being thrown. It is therefore important, especially when using autoboxing, to always check if the
get method returned a null when dealing with tuples that may or may not contain the requested field, for example, when a space is defined with some
Nullable (optional) fields. Trying to get a field that exists in the tuple but is of a different type than expected will, however, throw a runtime exception. Because objects are returned for all field types, the Java API also has a generic
get method that returns an object of corresponding type for the requested field, or null if there is no such field in the tuple.
When using the C API, which unlike the Java methods, returns a status code—a tibasTuple_Get… function call will return
NULL if there is no field by the requested name, and will return
TIBAS_INVALID_TYPE if a field of that name exists in the tuple but is of a different type than what is being requested.
Automatic lossless type upcasting is however supported when getting fields from a tuple. This means that, for example, if the tuple contains a field named 'A' of type
short, doing a
getLong("A") will succeed and return a
long that is set to the value of the field. The supported automatic type conversions are shown in
Table 7.
You can test for the presence of a named field inside a particular tuple by using either the exists method or the
isNull method, which both return a boolean indicating the presence or absence of the field in the tuple.
You can also find out the type of a particular field in the tuple using the getFieldType method, which can return a field type value of
NULL (
TIBAS_NULL in C).
The choice of which method to use is a matter of preference. Programmers more familiar with messaging systems may prefer to test for the existence of a field, while programmers more familiar with database systems may prefer to test whether a field
is NULL. In ActiveSpaces, a
NULL field is actually a non-existing field.
And finally a convenience toString method can also be used to generate an XML representation of the tuple into a string.