com.avian.tuple
Class BasicTupleTree

java.lang.Object
  extended by com.avian.tuple.BasicTupleTree

public class BasicTupleTree
extends java.lang.Object

A basic implementation of a tuplespace using ArrayListMultimap from Google Collections. The TupleTree implements the put method and a variety of get methods, such as readFirstMatching and readAllMatching.


Constructor Summary
BasicTupleTree()
          Default constructor for the BasicTupleTree.
 
Method Summary
 java.lang.String getFileName()
          Returns the filename to use when saving the contents of the BasicTupleTree.
 void put(java.lang.String key, java.lang.Object value)
          Puts an Object into the ArrayListMultimap (BasicTupleTree).
 void put(java.lang.String key, java.lang.String value)
          Puts a String value into the ArrayListMultimap (BasicTupleTree).
 void putSingleton(java.lang.String key, java.lang.Object value)
          Puts an Object into the ArrayListMultiMap and verifies that there is no other Object in the tree with that same key.
 java.util.List<java.lang.Object> readAllMatching(java.lang.String key)
          Performs a (modified) get from the ArrayListMultimap and receives a list of Objects but doesn't remove them.
 java.util.List<java.lang.Object> readAndRemoveAllMatching(java.lang.String key)
          Performs a get from the ArrayListMultimap and receives a java.util.List that is associated with the key parameter and removes all of them.
 java.lang.Object readAndRemoveOne(java.lang.String key)
          Performs a get from the ArrayListMultimap using the parameter key String, removes the object, and returns the removed object or null if no matching object found.
 java.lang.Object readFirstMatching(java.lang.String key)
          Performs a (modified) get from the ArrayListMultimap and receives an Object that is associated with the key parameter but doesn't remove it.
 java.lang.Object readSingleton(java.lang.String key)
          Reads an object from the ArrayListMultimap and verifies that it is the only value in the TupleTree with that key.
 void save(java.lang.String outputFileName)
          Writes the contents of the BasicTupleTree to the file that is specified in the output file name that is passed as a parameter.
 void setFileName(java.lang.String fileName)
          Saves the file name parameter that is passed into this method as the name of the file to use when saving the contents of the BasicTupleTree.
 java.lang.String show()
          Provides a formatted output that represents the contents of the BasicTupleTree.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

BasicTupleTree

public BasicTupleTree()
Default constructor for the BasicTupleTree. It requires no parameters and the only thing that it does is to create a new ArrayListMultimap. If previously there was an oak TupleTree, this new one replaces it

Method Detail

put

public void put(java.lang.String key,
                java.lang.String value)
Puts a String value into the ArrayListMultimap (BasicTupleTree). This method performs the out function defined in Linda, storing a String object that is associated with some key. This method(string) was originally used when developing the BasicTupleTree but is expected to become deprecated in the future. The bird that requests the put must be able to get exclusive (synchronized) access to the oak (ArrayListMultimap) before the put can be performed in a thread-safe manner.

Parameters:
key - String identifier that is used to store and retrieve the value in the BasicTupleTree. The key is normally the name of the food that a bird will eat or store.
value - String that is associated with the key.

put

public void put(java.lang.String key,
                java.lang.Object value)
Puts an Object into the ArrayListMultimap (BasicTupleTree). This method performs the out function defined in Linda, storing an Object that is associated with some key. Because the value is an Object and not some specific type, maximum flexibility is available for the users. The bird that requests the put must be able to get exclusive (synchronized) access to the oak (ArrayListMultimap) before the put can be performed in a thread-safe manner.

Parameters:
key - String identifier that is used to store and retrieve the value in the BasicTupleTree. The key is normally the name of the food that a bird will eat or store.
value - Java Object that holds the contents of the "work packet" that the various birds will work upon.

putSingleton

public void putSingleton(java.lang.String key,
                         java.lang.Object value)
Puts an Object into the ArrayListMultiMap and verifies that there is no other Object in the tree with that same key. It will go ahead and store the duplicate values in the tree so program won't crash. putSingleton is useful in situations where there should only be one object with that key, such as shared resources (files, drives, printers, etc). It currently writes a message to System.err but probably should record it in a better way. Can't add it to the object's history because that would presume that any & every object has an addToHistory method.

Parameters:
key - String identifier that is used to store and retrieve the value in the BasicTupleTree. The key is normally the name of the food that a bird will eat or store.
value - Object that holds the contents of the "work packet" that the requesting bird will work upon.

readAllMatching

public java.util.List<java.lang.Object> readAllMatching(java.lang.String key)
Performs a (modified) get from the ArrayListMultimap and receives a list of Objects but doesn't remove them. Although not specifically defined in Linda, this method has been useful during early development so that we can see what kinds of Objects are building up in the BasicTupleTree. The bird that requests the read must be able to get exclusive (synchronized) access to the oak (ArrayListMultimap) before the get can be performed in a thread-safe manner.

Parameters:
key - String identifier that is used as the key to retrieve a list of all values in the BasicTupleTree which have this key.
Returns:
List of Objects that are associated with the parameter but are not removed from the BasicTupleTree. Calling method must know the types of objects that are being returned and cast them into the correct types of objects

readFirstMatching

public java.lang.Object readFirstMatching(java.lang.String key)
Performs a (modified) get from the ArrayListMultimap and receives an Object that is associated with the key parameter but doesn't remove it. Although not specifically defined in Linda, this read/peek/non-changing get method has been useful during early development so that we can see what kinds of Objects are building up in the BasicTupleTree. The bird that requests the read must be able to get exclusive (synchronized) access to the oak (ArrayListMultimap) before the get can be performed in a thread-safe manner.

Internally, a get is performed that returns a list of all values (Objects) that are associated with the parameter (key). Since the ArrayListMultimap doesn't specify or expect to provide any order or sequence in the Objects in the list, all Objects are assumed to be equivalent, so the first item in the list is returned.

Parameters:
key - String identifier that is used as the key to retrieve a value from the BasicTupleTree.
Returns:
Object that is associated with the parameter but is not removed from the BasicTupleTree.

readAndRemoveOne

public java.lang.Object readAndRemoveOne(java.lang.String key)
Performs a get from the ArrayListMultimap using the parameter key String, removes the object, and returns the removed object or null if no matching object found. Does not block or wait for the value if nothing matched. The bird that requests the get must be able to get exclusive (synchronized) access to the oak (ArrayListMultimap) before the get can be performed in a thread-safe manner.

Internally, a get is performed that returns a list of all values (Objects) that are associated with the parameter (key). Since the ArrayListMultimap doesn't specify or expect to provide any order or sequence in the Objects in the list, all Objects are assumed to be equivalent, so the first item in the list is returned.

Parameters:
key - String identifier that is used as the key to retrieve a value from the BasicTupleTree.
Returns:
Object that was removed from the BasicTupleTree. If nothing matched the key, null is returned.

readSingleton

public java.lang.Object readSingleton(java.lang.String key)
Reads an object from the ArrayListMultimap and verifies that it is the only value in the TupleTree with that key. Removes and returns a matching object or returns null if nothing matched. If an object already existed with that key, it prints an error message to System.err and returns one of the values even if there is more than object with that key so program won't crash and bird won't hang. Useful in situations where there should only be one object with that key, such as shared resources (files, drives, printers, etc).

Parameters:
key - String identifier that is used as the key to retrieve a list of all values in the BasicTupleTree which have this key.
Returns:
Object that was removed from the BasicTupleTree. If nothing matched the key, null is returned.

readAndRemoveAllMatching

public java.util.List<java.lang.Object> readAndRemoveAllMatching(java.lang.String key)
Performs a get from the ArrayListMultimap and receives a java.util.List that is associated with the key parameter and removes all of them. The bird that requests the get must be able to get exclusive (synchronized) access to the oak (ArrayListMultimap) before the get can be performed in a thread-safe manner.

Parameters:
key - String identifier that is used as the key to retrieve a list of value from the BasicTupleTree.
Returns:
List of Java Objects that were removed from the BasicTupleTree. If nothing matched the key, null is returned.

getFileName

public java.lang.String getFileName()
Returns the filename to use when saving the contents of the BasicTupleTree.

Returns:
String to use as the filename to save the contents of the BasicTupleTree. If the filename was not set, null is returned.

setFileName

public void setFileName(java.lang.String fileName)
Saves the file name parameter that is passed into this method as the name of the file to use when saving the contents of the BasicTupleTree.

Parameters:
fileName - String to use when saving the contents of the BasicTupleTree.

show

public java.lang.String show()
Provides a formatted output that represents the contents of the BasicTupleTree. The returned String is typically sent to a JTextArea for on-screen display or sent to save method to be written to a file.

Returns:
String with the formatted output that represents the contents of the BasicTupleTree.

save

public void save(java.lang.String outputFileName)
Writes the contents of the BasicTupleTree to the file that is specified in the output file name that is passed as a parameter. Internally calls the show method so the on-screen results match the text file contents.

Parameters:
outputFileName - String that specifies the file that should have the contents of the BasicTupleTree written to it.