lime
Class LimeTupleSpace

java.lang.Object
  |
  +--lime.LimeTupleSpace

All Implemented Interfaces:

java.io.Serializable

public class LimeTupleSpace

extends java.lang.Object

implements java.io.Serializable

This class, LimeTupleSpace, provides an implementation for the Interface Tuple Space (ITS), the most basic component of a Lime-based application. It is through the ITS that a process interacts with the rest of the world. In addition to the conventional operations to write a tuple to the tuple space (out) and read or withdraw a matching tuple from the tuple space (rd, in), Lime provides location enhanced operations, reactivity, and operations to set a tuple space's sharing properties (shared or private)

Version:

1.0 alpha

Author:

Amy L. Murphy, Gian Pietro Picco

See Also:

StationaryAgent, Location, Reaction, ReactionListener, Serialized Form

Field Summary

static java.lang.String	DEFAULT The default name for tuple spaces.
static java.lang.String	SYSTEM The name of the Lime system tuple space.

Constructor Summary

LimeTupleSpace()
Create a default Lime tuple space, named DEFAULT.

LimeTupleSpace(java.lang.String name)
Create a named Lime tuple space.

Method Summary

RegisteredReaction[]	addStrongReaction(LocalizedReaction[] reactions) Registers a group of reactions with the Lime tuple space.
RegisteredReaction[]	addWeakReaction(Reaction[] reactions) Registers a group of weak reactions with the Lime tuple space.
java.lang.String	getName() Get the name of the Lime tuple space as given by the user.
RegisteredReaction[]	getRegisteredReactions() Return all the reactions registered on this Lime tuple space, i.e., all those registered by the agent owning this Lime tuple space.
lights.interfaces.ITuple	in(lights.interfaces.ITuple template) Retrieves a tuple that matches a given template, and removes it from the tuple space.
lights.interfaces.ITuple	in(Location current, AgentLocation destination, lights.interfaces.ITuple template) Retrieves a tuple that matches a given template, and removes it from the tuple space.
lights.interfaces.ITuple[]	ing(Location current, AgentLocation destination, lights.interfaces.ITuple template) Retrieve all tuples that match a pattern.
lights.interfaces.ITuple	inp(Location current, AgentLocation destination, lights.interfaces.ITuple template) Retrieves a tuple that matches a given template, and removes it from the tuple space, or returns null if no matching tuple exists.
boolean	isOwner() Return true if the thread calling this method is the ILimeAgentAgent object that owns this Lime tuple space object, false otherwise.
boolean	isRegisteredReaction(RegisteredReaction reaction) Checks whether a given reaction is still registered.
boolean	isShared() Returns true if this tuple space is currently shared, false otherwise.
void	out(AgentLocation destination, lights.interfaces.ITuple tuple) Inserts a tuple in the shared tuple space.
void	out(lights.interfaces.ITuple tuple) Inserts a tuple in the shared tuple space.
void	outg(AgentLocation destination, lights.interfaces.ITuple[] tuples) Write a set of tuples to the tuple space.
void	print() Prints the contents of the tuple space.
lights.interfaces.ITuple	rd(lights.interfaces.ITuple template) Retrieves a copy of a tuple that matches a given template.
lights.interfaces.ITuple	rd(Location current, AgentLocation destination, lights.interfaces.ITuple template) Retrieves a copy of a tuple that matches a given template.
lights.interfaces.ITuple[]	rdg(Location current, AgentLocation destination, lights.interfaces.ITuple template) Copy all tuples that match a pattern.
lights.interfaces.ITuple	rdp(Location current, AgentLocation destination, lights.interfaces.ITuple template) Retrieves a copy of a tuple that matches a given template, or returns null if no matching tuple exists.
void	removeStrongReaction(RegisteredReaction[] reactions) Deregisters a group of strong reactions.
void	removeWeakReaction(RegisteredReaction[] reactions) Deregisters a group of weak reactions.
boolean	setShared(boolean isShared) Enable or disable transient sharing of this tuple space with tuple spaces having the same name.
static boolean	setShared(LimeTupleSpace[] lts, boolean isShared) Enable or disable transient sharing of a set of tuple spaces.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

SYSTEM

public static final java.lang.String SYSTEM

The name of the Lime system tuple space.

DEFAULT

public static final java.lang.String DEFAULT

The default name for tuple spaces.

Constructor Detail

LimeTupleSpace

public LimeTupleSpace(java.lang.String name)
               throws TupleSpaceEngineException,
                      IllegalTupleSpaceNameException

Create a named Lime tuple space. The thread that is creating the tuple space must be an instance of ILimeAgent, otherwise an exception is raised. Such thread will be the owner of the Lime tuple space, i.e., the only one that can invoke operations on it.

Parameters:

name - the name of the tuple space.

Throws:

TupleSpaceEngineException - if a problem is encountered in the underlying tuple space engine.

IllegalTupleSpaceNameException - if the agent tries to create a tuple space with the name SYSTEM.

LimeTupleSpace

public LimeTupleSpace()
               throws TupleSpaceEngineException,
                      IllegalTupleSpaceNameException

Create a default Lime tuple space, named DEFAULT. The thread that is creating the tuple space must be an instance of of ILimeAgent, otherwise an exception is raised. Such thread will be the owner of the Lime tuple space, i.e., the only one that can invoke operations on it.

Throws:

TupleSpaceEngineException - if a problem is encountered in the underlying tuple space engine.

Method Detail

isOwner

public boolean isOwner()

Return true if the thread calling this method is the ILimeAgentAgent object that owns this Lime tuple space object, false otherwise. The owner of the Lime tuple space is the agent which created it. This agent is the only agent in the system that is allowed to perform an operation on this Lime tuple space.

This fact has non-trivial consequences, because attention must be put in ensuring that no other thread is issuing operations on this tuple space. In particular, this is true for user interfaces, where AWT/Swing listeners are executed in a thread that is created by the Java VM. Consequently, GUI listeners can never call directly a method on the Lime tuple space of an agent, otherwise an IllegalTupleSpaceAccessException is raised. Instead, they must somehow coordinate with the agent they are associated with (typically by means of an operation queue, as in LimeConsole), and have the latter perform the operation. In any case, tuple space operations in GUI applications may be dangerous. For instance, a rd perform from an AWT/Swing listener when no matching tuple is available effectively blocks the AWT/Swing thread, thus for instance preventing a correct repainting.

setShared

public boolean setShared(boolean isShared)

Enable or disable transient sharing of this tuple space with tuple spaces having the same name. When a tuple space changes its status from private to shared, it is implicitly engaged with the other tuple spaces in the system. When a tuple space changes its status from shared to private, it is disengaged from any other tuple spaces it was engaged with (both local and remote). Setting a tuple space to shared has no effect if the tuple space is already shared, i.e., no engagement protocol is started. Same holds for setting a private tuple space to private, i.e., no disengagement protocol is started.

Note: setting a tuple space to shared is different from calling engage on the LimeServer. setShared operates only on the public/private status of a tuple space while engage/disengage operate on the status of the host which is holding the tuple spaces.

Parameters:

isShared - true to set the tuple spaces to shared, false to set it to private.

Returns:

true if the tuple space is successfully engaged/disengaged.

setShared

public static boolean setShared(LimeTupleSpace[] lts,
                                boolean isShared)

Enable or disable transient sharing of a set of tuple spaces. When a tuple space changes its status from private to shared, it is implicitly engaged with the other tuple spaces in the system. When a tuple space changes its status from shared to private, it is disengaged from any other tuple spaces it was engaged with (both local and remote). The transition from private to shared (or vice versa) is performed in one atomic step, so that all tuple spaces in the array are engaged or disengaged as part of the same transaction. Setting a tuple space to shared has no effect if the tuple space is already shared, i.e., no engagement protocol is started. Same holds for setting a private tuple space to private i.e., no disengagement protocol is started.

Note: setting a tuple space to shared is different from calling engage on the LimeServer. setShared operates only on the public/private status of a tuple space while engage/disengage operate on the status of the host which is holding the tuple spaces.

Parameters:

lts - an array of tuple spaces to be set to shared or not shared in one step.

isShared - true to set the tuple spaces to shared, false to set it to private.

Returns:

true if engagement/disengagment was successful.

isShared

public boolean isShared()

Returns true if this tuple space is currently shared, false otherwise.

getName

public java.lang.String getName()

Get the name of the Lime tuple space as given by the user.

out

public void out(lights.interfaces.ITuple tuple)
         throws TupleSpaceEngineException

Inserts a tuple in the shared tuple space. Whether a formal can be written or not to the tuple space and what are the matching rules in this case depends on the rules of the underlying tuple space engine.

Since no destination location is specified in this method, the tuple is inserted in the ITS of the agent that owns this Lime tuple space object. The reactive program is executed to termination before this operation returns.

Parameters:

tuple - the tuple to be inserted.

Throws:

TupleSpaceEngineException - if a problem is encountered in the underlying tuple space engine.

out

public void out(AgentLocation destination,
                lights.interfaces.ITuple tuple)
         throws TupleSpaceEngineException

Inserts a tuple in the shared tuple space. Whether a formal can be written or not to the tuple space and what are the matching rules in this case depends on the rules of the underlying tuple space engine.

A destination (agent) location for the tuple must be specified. If the agent is currently connected, the tuple is delivered to the agent's ITS before the operation returns. Otherwise, the tuple is inserted in the ITS of the agent invoking this operation, thus becoming a "misplaced" tuple. If and when the recipient of the tuple appears in the system, the misplaced tuple will be delivered to its ITS as a consequence of the engagement process (note: it is possible for any agent to remove a misplaced tuple before it reaches its destination). The destination location can be left unspecified (using AgentLocation.UNSPECIFIED), in which case this operation is equivalent to the one without a location parameter. The reactive program is executed to termination before this operation returns.

Parameters:

destination - the agent location specifying the ITS to which the tuple is destined.

tuple - the tuple to be inserted.

Throws:

TupleSpaceEngineException - if a problem is encountered in the underlying tuple space engine.

outg

public void outg(AgentLocation destination,
                 lights.interfaces.ITuple[] tuples)
          throws TupleSpaceEngineException

Write a set of tuples to the tuple space. All tuples must be destined for the same tuple space.

Parameters:

destination - the agent location specifying the ITS to which the tuples are destined

tuples - the tuples to be inserted

Throws:

TupleSpaceEngineException - if a problem is encountered in the underling tuple space engine

in

public lights.interfaces.ITuple in(lights.interfaces.ITuple template)
                            throws TupleSpaceEngineException

Retrieves a tuple that matches a given template, and removes it from the tuple space. The whole transiently shared tuple space is searched. If multiple tuples match the template, one is selected non-deterministically. If no matching tuple is present the operation blocks until such tuple is actually found and retrieved from the tuple space.

Parameters:

template - the template the return tuple must be matched against.

Returns:

a copy of a tuple that matches the template.

Throws:

TupleSpaceEngineException - if a problem is encountered in the underlying tuple space engine.

inp

public lights.interfaces.ITuple inp(Location current,
                                    AgentLocation destination,
                                    lights.interfaces.ITuple template)
                             throws TupleSpaceEngineException

Retrieves a tuple that matches a given template, and removes it from the tuple space, or returns null if no matching tuple exists. Only the projection of the transiently shared tuple space defined by the current and destination locations are searched. If multiple tuples match the template, one is selected non-deterministically.

Parameters:

current - the current location of the tuples can never be left unspecified, i.e., neither the value HostLocation.UNSPECIFIED nor AgentLocation.UNSPECIFIED are allowed, since probe operations are not allowed on the federated tuple space.

destination - the destination location of the tuple that can be searched. The value AgentLocation.UNSPECIFIED is allowed.

template - the template the return tuple must be matched against.

Returns:

a copy of a tuple that matches the template, or null if the tuple cannot be found.

Throws:

TupleSpaceEngineException - if a problem is encountered in the underlying tuple space engine.

ing

public lights.interfaces.ITuple[] ing(Location current,
                                      AgentLocation destination,
                                      lights.interfaces.ITuple template)
                               throws TupleSpaceEngineException

Retrieve all tuples that match a pattern.

Parameters:

current - the currnet location of the tuples that can be searched. The value AgentLocation.UNSPECIFIED is NOT allowed.

destination - the destination location of the tuple that can be searched. The value AgentLocation.UNSPECIFIED is allowed.

template - the template the return tuples must be matched against.

Returns:

an array of all matching tuples, or null if no matching tuple can be found

Throws:

TupleSpaceEngineException - if a problem is encountered in the underlying tuple space engine.

in

public lights.interfaces.ITuple in(Location current,
                                   AgentLocation destination,
                                   lights.interfaces.ITuple template)
                            throws TupleSpaceEngineException

Retrieves a tuple that matches a given template, and removes it from the tuple space. Only the projection of the transiently shared tuple space defined by the current and destination locations are searched. If multiple tuples match the template, one is selected non-deterministically. If no matching tuple is present the operation blocks until such a tuple is actually found and retrieved from the tuple space.

Parameters:

current - the current location of the tuples that can be matched. The value HostLocation.UNSPECIFIED or AgentLocation.UNSPECIFIED are allowed, in which case only the destination location will matter.

destination - the destination location of the tuple that can be searched. The value AgentLocation.UNSPECIFIED is allowed, in which case only the current location will matter.

template - the template the return tuple must be matched against.

Returns:

a copy of a tuple that matches the template.

Throws:

TupleSpaceEngineException - if a problem is encountered in the underlying tuple space engine.

rd

public lights.interfaces.ITuple rd(lights.interfaces.ITuple template)
                            throws TupleSpaceEngineException

Retrieves a copy of a tuple that matches a given template. The whole transiently shared tuple space is searched. If multiple tuples match the template, one is selected non-deterministically. If no matching tuple is present the operation blocks until such a tuple is actually found in the tuple space.

Parameters:

template - the template the return tuple must be matched against.

Returns:

a copy of a tuple that matches the template.

Throws:

TupleSpaceEngineException - if a problem is encountered in the underlying tuple space engine.

rdp

public lights.interfaces.ITuple rdp(Location current,
                                    AgentLocation destination,
                                    lights.interfaces.ITuple template)
                             throws TupleSpaceEngineException

Retrieves a copy of a tuple that matches a given template, or returns null if no matching tuple exists. Only the projection of the transiently shared tuple space defined by the current and destination locations are searched. If multiple tuples match the template, one is selected non-deterministically.

Parameters:

current - the current location of the tuples can never be left unspecified, i.e., neither the value HostLocation.UNSPECIFIED nor AgentLocation.UNSPECIFIED are allowed, since probe operations are not allowed on the federated tuple space.

destination - the destination location of the tuple that can be searched. The value AgentLocation.UNSPECIFIED is allowed.

template - the template the return tuple must be matched against.

Returns:

a copy of a tuple that matches the template, or null if the tuple cannot be found.

Throws:

TupleSpaceEngineException - if a problem is encountered in the underlying tuple space engine.

rdg

public lights.interfaces.ITuple[] rdg(Location current,
                                      AgentLocation destination,
                                      lights.interfaces.ITuple template)
                               throws TupleSpaceEngineException

Copy all tuples that match a pattern.

Parameters:

current - the currnet location of the tuples that can be searched. The value AgentLocation.UNSPECIFIED is NOT allowed.

destination - the destination location of the tuple that can be searched. The value AgentLocation.UNSPECIFIED is allowed.

template - the template the return tuples must be matched against.

Returns:

an array of all matching tuples, or null if no matching tuple can be found

Throws:

TupleSpaceEngineException - if a problem is encountered in the underlying tuple space engine.

rd

public lights.interfaces.ITuple rd(Location current,
                                   AgentLocation destination,
                                   lights.interfaces.ITuple template)
                            throws TupleSpaceEngineException

Retrieves a copy of a tuple that matches a given template. Only the projection of the transiently shared tuple space defined by the current and destination locations are searched. If multiple tuples match the template, one is selected non-deterministically. If no matching tuple is present the operation blocks until such a tuple can be actually found in the tuple space.

Parameters:

current - the current location of the tuples that can be matched. The value HostLocation.UNSPECIFIED or AgentLocation.UNSPECIFIED are allowed, in which case only the destination location will matter.

destination - the destination location of the tuple that can be searched. The value AgentLocation.UNSPECIFIED is allowed, in which case only the current location will matter.

template - the template the return tuple must be matched against.

Returns:

a copy of a tuple that matches the template.

Throws:

TupleSpaceEngineException - if a problem is encountered in the underlying tuple space engine.

isRegisteredReaction

public boolean isRegisteredReaction(RegisteredReaction reaction)

Checks whether a given reaction is still registered. A reaction can be deregistered explicitly by calling removeReaction, or implicitly and automatically if its mode is ONCE and the reaction has already fired.

Parameters:

reaction - the RegisteredReaction whose presence must be checked.

Returns:

true if reaction is still registered with the tuple space, false otherwise.

getRegisteredReactions

public RegisteredReaction[] getRegisteredReactions()

Return all the reactions registered on this Lime tuple space, i.e., all those registered by the agent owning this Lime tuple space.

addStrongReaction

public RegisteredReaction[] addStrongReaction(LocalizedReaction[] reactions)
                                       throws TupleSpaceEngineException

Registers a group of reactions with the Lime tuple space. The operation is performed atomically, i.e., even if some of the reactions become suddenly enabled by the current state of the tuple space, none can fire until all of them have been registered. The reactions must have current and destination location fields.

Parameters:

reactions - an array containing the reactions to be registered.

Returns:

returns an array of handles to the registered reactions. These can later be used to uninstall the reactions.

Throws:

TupleSpaceEngineException - if a problem is encountered in the underlying tuple space engine.

addWeakReaction

public RegisteredReaction[] addWeakReaction(Reaction[] reactions)
                                     throws TupleSpaceEngineException

Registers a group of weak reactions with the Lime tuple space. The operation is NOT performed atomically, as this would involve a distributed transaction. The weak reactions obey to the semantics specified by the weakReaction operation. Thus, they can have either of the location fields unspecified, or no location field at all (i.e., UbiquitousReactions can be specified as well.

Parameters:

reactions - an array containing the reactions to be registered.

Returns:

returns an array of handles to the registered reactions. These can later be used to uninstall the reactions.

Throws:

TupleSpaceEngineException - if a problem is encountered in the underlying tuple space engine.

removeStrongReaction

public void removeStrongReaction(RegisteredReaction[] reactions)
                          throws TupleSpaceEngineException,
                                 NoSuchReactionException

Deregisters a group of strong reactions. The operation is performed atomically, i.e., the reactions are deregistered all together before any other operation or reaction is performed on the tuple space. This operation has all-or-nothing semantics, meaning that either all of the reactions are uninstalled, or none of them are. In other words, if at least one of the reactions specified in the array is not registered with the tuple space, then none of the reactions are disabled and NoSuchReactionException is raised.

Parameters:

reactions - an array containing the reactions to be deregistered.

Throws:

NoSuchReactionException - if some of the reactions are actually not registered.

IllegalTupleSpaceAccessException - if an agent other than the owner is trying to access this tuple space.

TupleSpaceEngineException - if a problem is encountered in the underlying tuple space engine.

NoSuchReactionException - if at least one of the reactions which was being removed does not exist..

removeWeakReaction

public void removeWeakReaction(RegisteredReaction[] reactions)
                        throws TupleSpaceEngineException,
                               NoSuchReactionException

Deregisters a group of weak reactions. The operation is NOT performed atomically.

Parameters:

reactions - an array containing the weak reactions to be deregistered.

Throws:

NoSuchReactionException - if some of the weak reactions are actually not registered.

TupleSpaceEngineException - if a problem is encountered in the underlying tuple space engine.

print

public void print()

Prints the contents of the tuple space. If the tuple space is shared, the host level tuple space is printed. Useful for debugging.