net.sf.tuplespace
Interface TupleSpace

All Known Implementing Classes:

SimpleTupleSpace

public interface TupleSpace

Describes a tuple space.

Tuple spaces are areas where multiple objects can be deposited, and retrieved from some time later. It does not matter who puts a tuple, and who retrieves a tuple from the space. The provider and retriever might be different objects, in different threads, in different JVMs. It does not matter.

Objects wanting to put an object in the space should simply call addToSpace(net.sf.tuplespace.Tuple). This method will not block, allowing the caller to continue it's work.

Objects wanting to retrieve information from the space should instead call readAndRemove(net.sf.tuplespace.Template). The Template will be used to find matching tuples in the space. When a tuple is found that matches, readAndRemove(net.sf.tuplespace.Template) will return, with the found tuple.

Implementors must guarantee atomicity—which means that a tuple can be offered only once, and that a tuple can only be retrieved once.

Method Summary

void	addToSpace(Tuple tuple) Adds tuple to the space.
Tuple	readAndRemove(Template template) Blocks until a Tuple matching Template is available.
Tuple	readAndRemoveWithTimeout(Template template, long timeout) Blocks for a maximum of timeout milliseconds, until a Tuple matching Template is available.

Method Detail

readAndRemove

public Tuple readAndRemove(Template template)
                    throws InterruptedWhileWaitingException

Blocks until a Tuple matching Template is available.

Parameters:

template - A template, describing what the caller would like to retrieve from the space.

Returns:

The tuple retrieved from the space.

Throws:

InterruptedWhileWaitingException - When an InterruptedException is thrown while waiting.

IllegalArgumentException - When template is null.

readAndRemoveWithTimeout

public Tuple readAndRemoveWithTimeout(Template template,
                                      long timeout)
                               throws InterruptedWhileWaitingException,
                                      IllegalArgumentException

Blocks for a maximum of timeout milliseconds, until a Tuple matching Template is available.

If timeout is lower than or equal to zero, the method will not block, and will immediately return the tuple, or null.

Since Java's time resolution is poor, the actual timeout might be different. Implementors should guarantee a minimum timeout at least equal to timeout, but might not be able to guarantee the actual maximum time.

Parameters:

template - A template, describing what the caller would like to retrieve from the space.

timeout - The maximum number of milliseconds to block.

Returns:

The tuple retrieved from the space, or null if none could be found before the timeout was reached.

Throws:

InterruptedWhileWaitingException - When an InterruptedException is thrown while waiting.

IllegalArgumentException - When template is null.

See Also:

readAndRemove(net.sf.tuplespace.Template)

addToSpace

public void addToSpace(Tuple tuple)
                throws IllegalArgumentException

Adds tuple to the space.

When this method returns, the tuple will have been made available to other objects waiting for a Template matching this tuple.

This method does not block.

Parameters:

tuple - The tuple being offered to other objects.

Throws:

IllegalArgumentException - When tuple is null.