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


Chapter 3 Performing Basic TIBCO ActiveSpaces Tasks : Working with Spaces

Working with Spaces
Getting the Name and Definition of a Space
You can get the name and the space definition of the space represented by the Space object by invoking the getName and getSpaceDef methods respectively.
Reading and Writing in a Space
This section describes how to read data from a space and write data to a space.
Getting or Taking a Single Tuple from the Space
Retrieving or taking a single tuple from a space is done using the space’s get or take methods. These methods take a tuple as an argument, which must contain fields of the same name and type as the fields marked as key in the space’s space definition. If there is a tuple in the space containing a tuple whose key field values match exactly the values in the tuple passed as argument stored in the space, these methods return a copy of that tuple inside a Result object. (In the case of the take method, it also atomically removes that tuple from the space.)
Storing a Tuple in a Space
Storing a tuple in a space is done using the space’s put method, which takes the tuple to put as an argument and returns what ever was overwritten in the space (if anything was) by the put.
The put operation is what is called an 'upsert': like both the INSERT and UPDATE SQL statement (actually like a MERGE statement); it will always overwrite what was stored in the space before.
If the tuple contains fields that do not match the names of the fields in the space's definition, those fields are stripped from the tuple stored in the space
If there is already a tuple containing a tuple with the same key field values stored the space at the time the put is invoked, this old tuple is quietly replaced by the new one. If this behavior is not desired, and the users wants to avoid overwriting an existing tuple by mistake, a special form of the space's update method should be used.
At the time the put is invoked, if there is already a matching tuple in the space and that tuple is locked, the method may block. It may block for up to the amount of time specified in the space definition’s LockWait attribute. After this amount of time, if the stored tuple is still locked, the put will fail, and that failure scenario will be indicated by the Result object's Status field (or the return value of the method in C) having a value of LOCKED.
Updating a Tuple in a Space
Put operations always overwrite (and return) whatever was stored before them in the space. But when more than one application updates the same data concurrently, it can be necessary to use “compare and set” type operations.
ActiveSpaces has two compare and set operations:
compareAndPut This is a conditional put operation to atomically change the values associated with a key from one value to another (or fail). It takes an old tuple, and a new tuple as inputs, and returns the current tuple (meaning the new tuple if the compare was a success and the current value stored in the space otherwise). Note that you can pass NULL as an old tuple if you want to make sure your put is an insert rather than an overwrite.
compareAndTake This is a conditional take operation that succeeds only if the tuple that was stored in the space matches the old tuple value it takes as input.
For an example of code that works with tuples, see the documentation on the ASOperations example (ASOperations).

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