org.codehaus.activespace
Interface Space

All Known Implementing Classes:

JmsSpace

public interface Space

Represents an ActiveSpace which is similar to a JavaSpace logically but with a more constrainted API so that it can be more efficiently mapped onto a high performance message bus and allow some other tricks to maximise performance and scalability.

A Space can work in two primary modes, either a Publish / Subscribe mode (all spaces get a copy of an object) or a Queue based mode (only 1 space instance gets an object).

In addition each Space can take full advantage of the underlying message bus features like topic hierarchies, wildcards for grouping, SQL 92 selectors for querying and filtering spaces as well as content based routing if a JMS provider supports it. All of the available Quality of Services that the JMS provider implements can be used such as reliable messaging, durable (peristent messaging) together with message acknowlegement, JMS transactions and full XA transactions across any J2EE resources.

Rather than provide random access APIs such as arbitrary queries, ActiveSpace is designed for high performance streaming of objects around a cluster and so users are encouraged to create a space and reuse it and then close it when you are finished with it to help the provider optimise object flow around the grid.

Version:

$Revision: 1.4 $

Method Summary

void	addSpaceListener(SpaceListener listener) Adds a listener to objects in this space for items
void	close() Closes down this space and any resources it might be using if it is no longer required
Space	createChildSpace(String query) Creates a filter-space of the current Space using an SQL92 predicate
int	getDispatchMode() Returns the dispatch mode of objects in this space, whether only 1 consumer will see each object or whether all consumers of the space will see their own copy of the object.
String	getName() Returns the name of this space
void	put(Object value) Puts an object into a space so that it is usable by any other user of the space fabric
void	put(Object value, long lease) Puts an object into a space so that it is usable by any other user of the space fabric but only keep it around for the given lease time
void	removeSpaceListener(SpaceListener listener) Removes a listener to objects in this space
Object	take() This method will block forever until an item is available in this space for processing
Object	take(long timeout) This method will block until the maximum timeout until an item is available in this space for processing
Object	takeNoWait() This method will not block and return immediately with an object from the sapce or return null if no item is available

Method Detail

put

public void put(Object value)

Puts an object into a space so that it is usable by any other user of the space fabric

Parameters:

value -

put

public void put(Object value,
                long lease)

Puts an object into a space so that it is usable by any other user of the space fabric but only keep it around for the given lease time

Parameters:

value -

lease - the time in milliseconds to keep the object around for

take

public Object take()

This method will block forever until an item is available in this space for processing

Returns:

an object from the space

take

public Object take(long timeout)

This method will block until the maximum timeout until an item is available in this space for processing

Returns:

an object from the space or null if the timeout has occurred

takeNoWait

public Object takeNoWait()

This method will not block and return immediately with an object from the sapce or return null if no item is available

addSpaceListener

public void addSpaceListener(SpaceListener listener)

Adds a listener to objects in this space for items

removeSpaceListener

public void removeSpaceListener(SpaceListener listener)

Removes a listener to objects in this space

Parameters:

listener -

createChildSpace

public Space createChildSpace(String query)
                       throws SpaceException

Creates a filter-space of the current Space using an SQL92 predicate

Parameters:

query -

Returns:

a new space

Throws:

SpaceException

getName

public String getName()

Returns the name of this space

Returns:

the name of the space

getDispatchMode

public int getDispatchMode()

Returns the dispatch mode of objects in this space, whether only 1 consumer will see each object or whether all consumers of the space will see their own copy of the object. The value is one of SpaceFactory.DISPATCH_ONE_CONSUMER, SpaceFactory.DISPATCH_ALL_CONSUMERS or SpaceFactory.DISPATCH_ONE_CONSUMER_EXCLUSIVE

Returns:

whether or not the space is operating in a queue mode; if in queue mode this method returns true else if in publish/subscribe mode this method returns false

close

public void close()
           throws SpaceException

Closes down this space and any resources it might be using if it is no longer required

Throws:

SpaceException