Voyager ORB

com.objectspace.voyager.space
Class Subspace

com.objectspace.voyager.space.Subspace

public class Subspace
implements ISubspace, IRemote, java.io.Serializable

A Subspace is the building block of Space(tm), which is Voyager's backbone for scaleable distributed computing. A subspace can hold zero or more objects and can be connected to zero or more neighboring subspaces. A network of subspaces formed in this manner forms a single logical space which is in essence a distributed container.

When a message/event is sent into a subspace, it is cloned to each of the neighboring subspaces before it is delivered to every object in the local subspace. This results in a very rapid parallel fanout of the message/event to every object in the space. A special mechanism in each subspace ensures that no message/event is accidentally processed more than once, regardless of how the subspaces are linked together.

Subspaces may be linked to form a highly interconnected topology to avoid single points of failure and thus ensure fault tolerance.

A subspace is serializable and therefore may be persisted.

Version:
3.0
See Also:
Serialized Form

Field Summary
static byte ALL
          Purge references to neighbors and objects that are dead or unreachable.
static byte DIED
          Purge references to dead neighbors and objects.
static byte DISCONNECTED
          Purge references to unreachable neighbors and objects.
static byte NONE
          Do not purge any references.
 
Constructor Summary
Subspace()
          Create a new empty Subspace with no neighbors.
 
Method Summary
 void add(java.lang.Object object)
          Add the specified object to this subspace.
 void addSubspaceListener(SubspaceListener listener)
          Add the specified listener.
 void connect(ISubspace subspace)
          Create a bi-directional connection with the specified subspace.
 boolean contains(java.lang.Object object)
          Return true if I contain the specified object.
 void disconnect(ISubspace subspace)
          Break the bi-directional connection with the specified subspace.
 java.lang.Object[] getContents()
          Return an array of my objects.
 java.lang.Object getMarker(java.lang.Object key)
          Return the value associated with the key, or null if there is none.
 Proxy getMulticastProxy(java.lang.String classname)
          Return a multicast proxy associated with the specified class.
 ISubspace[] getNeighbors()
          Return an array of references to all my neighboring subspaces.
 byte getPurgePolicy()
          Return my current purge policy.
 boolean isNeighbor(ISubspace subspace)
          Return true if the subspace given is a neighbor of this subspace.
 void purge(byte rule)
          Purge myself using the specified rule.
 java.lang.Object putMarker(java.lang.Object key, java.lang.Object value, long lifetime)
          Add and remember the key/value pair until the specified number of milliseconds has elapsed.
 boolean remove(java.lang.Object object)
          Remove the specified object from this subspace.
 void removeSubspaceListener(SubspaceListener listener)
          Remove the specified listener.
 void setPurgePolicy(byte policy)
          Set my purge policy.
 int size()
          Return the number of objects I contain.
 java.lang.String toString()
          Return a string that describes me.
 

Field Detail

DIED

public static final byte DIED
Purge references to dead neighbors and objects.

DISCONNECTED

public static final byte DISCONNECTED
Purge references to unreachable neighbors and objects.

ALL

public static final byte ALL
Purge references to neighbors and objects that are dead or unreachable.

NONE

public static final byte NONE
Do not purge any references.
Constructor Detail

Subspace

public Subspace()
Create a new empty Subspace with no neighbors.
Method Detail

toString

public java.lang.String toString()
Return a string that describes me.

getMulticastProxy

public Proxy getMulticastProxy(java.lang.String classname)
                        throws java.lang.ClassNotFoundException
Return a multicast proxy associated with the specified class. All messages sent to this proxy are multicast to all objects in my space that are type-compatible with the specified class.
Specified by:
getMulticastProxy in interface ISubspace
Parameters:
classname - The class whose instances will receive oneway messages.
Throws:
java.lang.ClassNotFoundException - The specified class could not be found.

connect

public void connect(ISubspace subspace)
Create a bi-directional connection with the specified subspace. This operation makes the two subspaces neighbors and part of the same logical space.
Specified by:
connect in interface ISubspace
Parameters:
subspace - The subspace to connect with.

disconnect

public void disconnect(ISubspace subspace)
Break the bi-directional connection with the specified subspace. At this point, the subspaces cease to be neighbors.
Specified by:
disconnect in interface ISubspace
Parameters:
subspace - The subspace to disconnect from.

getNeighbors

public ISubspace[] getNeighbors()
Return an array of references to all my neighboring subspaces.
Specified by:
getNeighbors in interface ISubspace

isNeighbor

public boolean isNeighbor(ISubspace subspace)
Return true if the subspace given is a neighbor of this subspace.
Specified by:
isNeighbor in interface ISubspace
Parameters:
subspace - The subspace to test against.

add

public void add(java.lang.Object object)
Add the specified object to this subspace.
Specified by:
add in interface ISubspace
Parameters:
reference - The object to add.

remove

public boolean remove(java.lang.Object object)
Remove the specified object from this subspace. Return true if the object was found, and false otherwise.
Specified by:
remove in interface ISubspace
Parameters:
object - The object to remove.

getContents

public java.lang.Object[] getContents()
Return an array of my objects.
Specified by:
getContents in interface ISubspace

contains

public boolean contains(java.lang.Object object)
Return true if I contain the specified object.
Specified by:
contains in interface ISubspace
Parameters:
object - The object to find.

size

public int size()
Return the number of objects I contain.
Specified by:
size in interface ISubspace

addSubspaceListener

public void addSubspaceListener(SubspaceListener listener)
Add the specified listener.
Specified by:
addSubspaceListener in interface ISubspace
Parameters:
listener - The listener to add.

removeSubspaceListener

public void removeSubspaceListener(SubspaceListener listener)
Remove the specified listener.
Specified by:
removeSubspaceListener in interface ISubspace
Parameters:
listener - The listener to remove.

putMarker

public java.lang.Object putMarker(java.lang.Object key,
                                  java.lang.Object value,
                                  long lifetime)
Add and remember the key/value pair until the specified number of milliseconds has elapsed. Return the previous value that was associated with the key, or null if there was none. The ability to add a key/value marker is often used by messengers to ensure that they don't visit a subspace more that once. Neither the key or the value receive messages or events that propagate through a space.
Specified by:
putMarker in interface ISubspace
Parameters:
key - The key.
value - The value to associate with the key.
lifetime - The number of milliseconds that the key/value pair should be remembered.

getMarker

public java.lang.Object getMarker(java.lang.Object key)
Return the value associated with the key, or null if there is none.
Specified by:
getMarker in interface ISubspace
Parameters:
key - The key.

setPurgePolicy

public void setPurgePolicy(byte policy)
Set my purge policy.
Specified by:
setPurgePolicy in interface ISubspace
Parameters:
policy - The new purge policy

getPurgePolicy

public byte getPurgePolicy()
Return my current purge policy.
Specified by:
getPurgePolicy in interface ISubspace

purge

public void purge(byte rule)
Purge myself using the specified rule. If rule is DIED, remove dead neighbors and contents. If rule is DISCONNECTED, remove disconnected neighbors and contents. If rule is ALL, remove dead and disconnected neighbors and contents.
Specified by:
purge in interface ISubspace
Parameters:
rule - The purge rule to use.

ObjectSpace Inc.

(c) Copyright 1997-1999 ObjectSpace, Inc.
14850 Quorum Drive, Suite 500
Dallas, Texas 75240