lime
Class LimeTupleSpace

java.lang.Object
  lime.LimeTupleSpace

All Implemented Interfaces:

java.io.Serializable

Direct Known Subclasses:

MoteLimeTupleSpace

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

(package private) static int	CUR_TAG
static java.lang.String	DEFAULT The default name for tuple spaces.
private static int	defaultID
(package private) static int	DEST_TAG
(package private) static int	ID_TAG
(package private) LimeTSMgr	mgr
private java.lang.String	name
(package private) AgentID	owner
(package private) Reactor	reactor
(package private) boolean	shared
static java.lang.String	SYSTEM The name of the Lime system tuple space.
(package private) static int	TAG_NUMBER The number of system fields.
(package private) lights.interfaces.ITupleSpace	ts
(package private) UponMgr	upons

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.
protected static lights.interfaces.ITuple	cloneTuple(lights.interfaces.ITuple t) Copies a tuple.
protected static lights.interfaces.ITuple	cloneTuple(lights.interfaces.ITuple t, int start, int end) Copies a subset of the fields of a tuple in a new tuple.
private LimeTuple	doBlocking(LimeTemplate template, short type)
private LimeTuple[]	doOut(AgentLocation destination, lights.interfaces.ITuple[] tuples, short op)
private LimeTuple[]	doProbe(LimeTemplate template, short type)
private RegisteredReaction[]	filterReactions(RegisteredReaction[] reactions)
private LimeTuple[]	getArray(lights.interfaces.ITuple t)
private LimeTuple[]	getArray(lights.interfaces.ITuple[] t)
java.lang.String	getName() Get the name of the Lime tuple space as given by the user.
(package private) static java.lang.String	getPublicName(java.lang.String n)
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.
(package private) java.lang.String	getUniqueName() Get the name of the Lime tuple space after going through contortions to make the name unique.
LimeTuple	in(LimeTemplate template) Retrieves a tuple that matches a given template, and removes it from the tuple space.
LimeTuple[]	ing(LimeTemplate template) Retrieve all tuples that match a pattern.
LimeTuple	inp(LimeTemplate template) Retrieves a tuple that matches a given template, and removes it from the tuple space, or returns null if no matching tuple exists.
private boolean	isInReaction()
boolean	isOwner() Return true if the thread calling this method is the ILimeAgentAgent object that owns this Lime tuple space object, false otherwise.
private static boolean	isOwner(LimeTupleSpace lts)
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.
(package private) static boolean	isUnspecified(Location l)
LimeTuple	out(AgentLocation destination, lights.interfaces.ITuple tuple) Inserts a tuple in the shared tuple space.
LimeTuple	out(lights.interfaces.ITuple tuple) Inserts a tuple in the shared tuple space.
LimeTuple[]	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.
LimeTuple	rd(LimeTemplate template) Retrieves a copy of a tuple that matches a given template.
LimeTuple[]	rdg(LimeTemplate template) Copy all tuples that match a pattern.
LimeTuple	rdp(LimeTemplate 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.

See Also:

Constant Field Values

DEFAULT

public static final java.lang.String DEFAULT

The default name for tuple spaces.

See Also:

Constant Field Values

ID_TAG

static final int ID_TAG

See Also:

Constant Field Values

CUR_TAG

static final int CUR_TAG

See Also:

Constant Field Values

DEST_TAG

static final int DEST_TAG

See Also:

Constant Field Values

TAG_NUMBER

static final int TAG_NUMBER

The number of system fields.

See Also:

Constant Field Values

owner

AgentID owner

name

private java.lang.String name

mgr

transient LimeTSMgr mgr

ts

lights.interfaces.ITupleSpace ts

reactor

Reactor reactor

upons

UponMgr upons

shared

boolean shared

defaultID

private static final int defaultID

See Also:

Constant Field Values

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.

IllegalTupleSpaceNameException

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.

getUniqueName

java.lang.String getUniqueName()

Get the name of the Lime tuple space after going through contortions to make the name unique.

getPublicName

static java.lang.String getPublicName(java.lang.String n)

out

public LimeTuple 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.

Returns:

the tuple inserted with cur, dest, and id set.

Throws:

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

out

public LimeTuple 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.

Returns:

the tuple inserted with cur, dest, and id set. Note: cur will always be the inserting agent, even if the destination is present when the tuple is output.

Throws:

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

outg

public LimeTuple[] 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

doOut

private LimeTuple[] doOut(AgentLocation destination,
                          lights.interfaces.ITuple[] tuples,
                          short op)
                   throws TupleSpaceEngineException

Throws:

TupleSpaceEngineException

inp

public LimeTuple inp(LimeTemplate 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. 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. If they are, an exception is thrown.

Parameters:

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 LimeTuple[] ing(LimeTemplate template)
                throws TupleSpaceEngineException

Retrieve all tuples that match a pattern. The currnet location of the tuples that can be searched can never be left unspecified. i.e., AgentLocation.UNSPECIFIED is NOT a valid value for current.

Parameters:

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 LimeTuple in(LimeTemplate 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:

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 LimeTuple rdp(LimeTemplate 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. 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. If they are, an exception is thrown.

Parameters:

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 LimeTuple[] rdg(LimeTemplate template)
                throws TupleSpaceEngineException

Copy all tuples that match a pattern. The currnet location of the tuples that can be searched can never be left unspecified. i.e., AgentLocation.UNSPECIFIED is NOT a valid value for current.

Parameters:

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 LimeTuple rd(LimeTemplate 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:

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.

filterReactions

private RegisteredReaction[] filterReactions(RegisteredReaction[] reactions)

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.

cloneTuple

protected static lights.interfaces.ITuple cloneTuple(lights.interfaces.ITuple t)

Copies a tuple.

Parameters:

t - the tuple to be copied.

Returns:

the copy

cloneTuple

protected static lights.interfaces.ITuple cloneTuple(lights.interfaces.ITuple t,
                                                     int start,
                                                     int end)

Copies a subset of the fields of a tuple in a new tuple.

Parameters:

t - the tuple to be copied.

start - the first field to be copied (inclusive)

end - the last field to be copied (exclusive)

Returns:

the copy

isOwner

private static boolean isOwner(LimeTupleSpace lts)

isInReaction

private boolean isInReaction()

isUnspecified

static boolean isUnspecified(Location l)

doBlocking

private LimeTuple doBlocking(LimeTemplate template,
                             short type)
                      throws TupleSpaceEngineException

Throws:

TupleSpaceEngineException

doProbe

private LimeTuple[] doProbe(LimeTemplate template,
                            short type)
                     throws TupleSpaceEngineException

Throws:

TupleSpaceEngineException

getArray

private LimeTuple[] getArray(lights.interfaces.ITuple[] t)

getArray

private LimeTuple[] getArray(lights.interfaces.ITuple t)