Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved


Chapter 3 Performing Basic TIBCO ActiveSpaces Tasks : Defining Data Fields

Defining Data Fields
This section describes how to define data fields and indexes.
Field Definitions
Field definitions describe the format of the data that will be stored in the space. A valid space definition must contain at least one field definition. Field definitions are created by the FieldDef’s create() method, and can be put (or taken) from space definitions. Field definitions can also be reused and put into as many space definitions as needed (for example when using some fields as foreign keys to correlate tuples stored in different spaces).
A field definition is created by using the FieldDef's create() method. A field definition has two mandatory attributes which are provided to the create() method: a name and a type.
The field name is a string and must start with a letter (upper or lower case) or the underscore (_) character and then contain any combination of letters (upper or lower case) and numbers.
The field type must be one of those described in the following table.
A BLOB (binary large object) type is an array of 8 bit values.
The BOOLEAN type has one of two values, true or false, represented by the integers 1 or 0, respectively.
Julian Calendar Any date 64-bit time value
Proleptic Gregorian Calendar 1 A.D. to 64-bit time value.
A field definition’s name and type can be retrieved using the FieldDef object’s getName and getType methods.
Beyond the field’s name and type, a field definition also has the following optional boolean attribute:
Optional (nullable) field You can use the FieldDef object’s setNullable method to specify if the field can be null or not (defaults to false), which marks that field as optional, and use the isNullable to test if the field is optional or not. The equivalent functions in the C API are tibasFiledDefSetNullable() and tibasFieldDefIsNullable().
Key Fields
For the space definition to be valid, at least one of the defined fields must to be used as a key field. In the Java API, you can specify a set of fields to be used as key fields can be specified by using the SpaceDef's setKey method and passing it a number of strings containing the space names.
In the C API, you can call the tibasKeyDefCreate() function to specify a single string containing a comma-separated list of field names to use as a key.
It is also possible to get a list of the name of the fields marked as key fields in a SpaceDef. In Java, by using the SpaceDef's getKey method. And in C, by using the tibasKeyDefGetFieldNames() function.
Defining Key Fields for Distribution (Affinity)
When you define key fields for a tuple, ActiveSpaces allows you to define the key fields in a way that controls their distribution over seeders. This feature of ActiveSpaces is called “affinity.”
By specifying that certain key fields are distribution fields, your application can ensure that tuples that have the same value for a particular field or fields, are stored on the same seeder.
The ActiveSpaces API provides functions and methods for each API set to enable distribution based on affinity:
Java  setDistributionFields()
C  tibasSpaceDef_SetDistributionFields()
.NET  SetDistributionFields
Each function or method takes as its arguments the space definition for the space that is to be defined and a list of fields within quotation marks, separated by commas.
For more information on the C API function, see the reference article for the tibasspaceDef_SetDistributionFields() function in chapter 5 of the TIBCO ActiveSpaces C Reference, “SpaceDef.”
For more information on the Java method, see the JavaDoc entry for setDistributionFields().
Each API set also provides a function to retrieve the distribution key setting for a specified space. For example, the Java API provides the getDistributionFields() method.
Admin CLI Support for Distribution Fields
When you define a space using the define | create space command in the ActiveSpaces Admin CLI, you can specify the distribution_def parameter to set specified keys for distribution fields. And when you issue the show spaces command, the command output indicates any fields that are set up as distribution fields.
For more information, see the reference article for define | create space in chapter 2 of the TIBCO ActiveSpaces Administration Guide, “Administering ActiveSpaces with the Admin CLI.”
Indexes
Indexes are used to accelerate the filtering of data when servicing queries. Indexes are built at space creation (or loading) and use memory to help locate matching records faster than it takes to iterate through every record.
ActiveSpaces always builds a distributed in-memory index of the key fields of the tuples stored in the space, which allows it to be a very fast key-value store. But ActiveSpaces also provides the ability to query for any field of the records contained in the space, and these queries can similarly be serviced faster if indexes are built on the fields used by the query filter statement.
Indexes can be either hash indexes (the default) or tree type indexes, and can contain one or more fields. A hash index is better suited if the set of values to be stored is randomly distributed or the query is selecting for specific values rather than ranges of values. A tree index is better when the query is selecting ordered ranges of values.
SpaceWait
No operations on a space are possible unless the space is in the READY state. To help synchronize applications with the space state, each space has a SpaceWait attribute. This attribute is the number of milliseconds a space operation will block for and wait for the space to reach the READY state if it is not in that state at the time the operation is invoked.
Adding Fields to a Previously Defined Space
ActiveSpaces allows you to alter the fields in a space that is already defined by using the as-admin utility or by calling Metaspace.alterspace(). The C API and the .NET API provide equivalent operations. There is no disruption in service when you alter the space.
Any new fields that you add must be nullable.
If the space has not yet been defined or the space definition is incompatible with the one that is defined (for example, has new fields that are not nullable), ActiveSpaces generates an exception describing what was incorrect.
 
Adding and Dropping Indexes
ActiveSpaces allows you to add indexes to a space that is already defined or drop indexes from the space. You can add or drop indexes by using the as-admin utility or by calling Metaspace.alterspace(). The C API and the .NET API provide equivalent operations. There is no disruption in service. ActiveSpaces builds the new indexes in the background, and when they are ready, sues them automatically to optimize queries.
 
 
Adding and dropping an index using the Java API
The following example shows how to add and drop an index using the Java API.
SpaceDef spaceDef = metaspace.getSpaceDef(“test”);
    spacedef.removeIndexDef(“index1”);
    spaceDef.addIndexDef(…)
    spaceDef.addIndexDef(…)
    spaceDef.putFieldDef(FieldDef….)
metaspace.alterSpace(spaceDef);
 

Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved