Tuple
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.
A tuple contains fields that are identified by names, each of which is unique within the tuple. A field name must start with a letter (upper or lowercase) or the underscore character (_), followed by any combination of letters (upper or lower case) and numbers. Field names are case-sensitive.
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.
Examples
tuple.putString(“Name”,”John Doe”) tuple.putInt(“Age”,40)
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:
tuple.put(“Name”,”John Doe”) tuple.put(“Age”,40)
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.
Tuple fields
In Java, getting a field of a scalar type will return an object rather than the primitive type for the field. For example, tuple.getInt(“Age”) will return an object of type Integer (rather than an int).
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 5.
| Upcasting Supported to... | Type of Field in Tuple |
|---|---|
| Short | Short, Int, Long, Float, Double |
| Int | Short, Int, Long, Float, Double |
| Long | Short, Int, Long, Float, Double |
| Float | Short, Int, Long, Float, Double |
| Double | Short, Int, Long, Float, Double |
| Blob | Blob, String |
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.
A tuple can also be seen as a self-describing data structure in that it offers methods that can be used to inspect the fields contained in the tuple:
- The size method returns the number of fields in the tuple
- The getFieldNames method returns a String[] in Java, while in C it returns a pointer to a tibasStringList object.
You can serialize or deserialize a tuple into a platform-independent stream of bytes using the serialize and deserialize methods.
And finally a convenience toString method can also be used to generate an XML representation of the tuple into a string.