drm.core
Class Collective

java.lang.Object
  |
  +--drm.core.Collective
All Implemented Interfaces:
java.lang.Runnable, java.io.Serializable

public final class Collective
extends java.lang.Object
implements java.lang.Runnable, java.io.Serializable

This class implements a proxy to a collective. An entity can use this class either to observe what is going on (ie reading) or to participate in the collective effort, ie also to contribute to the common effort or issue commands. In the first case the entity is an Observer, in the second case a Contributor, in the third a Controller. These roles can be implemented by the same entity or by different entities.

To join a collective it is not enough to construct a collective object with eg

 Collective c = new Collective("mycollective",this);
 
The collective member also has to forward messages of type "collectiveUpdate-mycollective" by calling handleMessage(Message,Object).

See Also:
Observer, Contributor, Controller, Serialized Form

Field Summary
static long COMMAND_TIMEOUT
          Commands older than this time are removed.
static long CONTRIBUTION_TIMEOUT
          Contributions older than this many milliseconds are thrown away.
static long MAX_CACHE_SIZE
          Max size of cache.
static long MAX_COMMANDS_SIZE
          Max size of active commands database.
static long REFRESHRATE
          An information exchange attempt is initiated after waiting this many ms-s.
 
Constructor Summary
Collective(Collective c, Observer o, Contributor cb, Controller cr)
          Construct a Collective object.
Collective(java.lang.String name, Observer o)
          Construct a Collective object.
Collective(java.lang.String name, Observer o, Contributor c)
          Construct a Collective object.
Collective(java.lang.String name, Observer o, Contributor cb, Controller c)
          Construct a Collective object.
Collective(java.lang.String name, Observer o, Controller c)
          Construct a Collective object.
 
Method Summary
 void addPeerAddress(Address a)
          Adds a peer address to exchange information with.
 void close()
          This stops the service.
 java.util.List getCommands()
          Returns known active commands in an unmodifiable list.
 ContributionBox getContribution(java.lang.String name)
          Returns the contribution of the given entity.
 java.util.List getContributions()
          Returns known contributions in an unmodifiable list.
 boolean handleMessage(Message m, java.lang.Object o)
          Handles a message.
 void run()
          This method is the main function of the thread of the collective.
 java.lang.String toString()
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

CONTRIBUTION_TIMEOUT

public static final long CONTRIBUTION_TIMEOUT
Contributions older than this many milliseconds are thrown away.

MAX_CACHE_SIZE

public static final long MAX_CACHE_SIZE
Max size of cache. Reading at most this many random contributions is cheap as they are stored locally.

MAX_COMMANDS_SIZE

public static final long MAX_COMMANDS_SIZE
Max size of active commands database.

REFRESHRATE

public static final long REFRESHRATE
An information exchange attempt is initiated after waiting this many ms-s.

COMMAND_TIMEOUT

public static final long COMMAND_TIMEOUT
Commands older than this time are removed.
Constructor Detail

Collective

public Collective(java.lang.String name,
                  Observer o)
Construct a Collective object. The parameter is the owner, the object that participates in the collective.
Parameters:
name - The name of the collective we want to join.
o - The observer that reads information from the collective.

Collective

public Collective(java.lang.String name,
                  Observer o,
                  Contributor c)
Construct a Collective object.
Parameters:
name - The name of the collective we want to join.
o - The observer that reads information from the collective.
c - The contributor that contributes to the collective effort.

Collective

public Collective(java.lang.String name,
                  Observer o,
                  Controller c)
Construct a Collective object.
Parameters:
name - The name of the collective we want to join.
o - The observer that reads information from the collective.
c - The controller that issues collective-wide commands.

Collective

public Collective(java.lang.String name,
                  Observer o,
                  Contributor cb,
                  Controller c)
Construct a Collective object.
Parameters:
name - The name of the collective we want to join.
o - The observer that reads information from the collective. It must be non-null.
cb - The contributor that contributes to the collective effort.
c - The controller that issues collective-wide commands.

Collective

public Collective(Collective c,
                  Observer o,
                  Contributor cb,
                  Controller cr)
Construct a Collective object.
Parameters:
c - The contributions, the commands and the name will be initialized from this object.
o - The observer that reads information from the collective. It must be non-null.
cb - The contributor that contributes to the collective effort.
c - The controller that issues collective-wide commands.
Method Detail

close

public void close()
This stops the service. Restarting is not possible.

handleMessage

public boolean handleMessage(Message m,
                             java.lang.Object o)
Handles a message. Knows type "collectiveUpdate-"+name only. It is the responsibility of the owner to propagate messages of this type using this method.

run

public final void run()
This method is the main function of the thread of the collective. It does housekeeping and regularly talks to peers to exchange information. It can be stopped by calling close().
Specified by:
run in interface java.lang.Runnable
See Also:
close()

addPeerAddress

public void addPeerAddress(Address a)
Adds a peer address to exchange information with. This class needs peer addresses to talk to. The implementation of the collective requires that we know at least one peer from the same collective. Through this method a peer can be explicitly set. If a peer with the same name exists, its address will be updated. The running collective can ask its owner for peers as well using Observer.getPeerAddresses().

getContribution

public ContributionBox getContribution(java.lang.String name)
Returns the contribution of the given entity. If no contribution is known returns null.

getContributions

public java.util.List getContributions()
Returns known contributions in an unmodifiable list. The list contains at most MAX_CACHE_SIZE random elements from the contribution repository. Might return the same list when called again if there is two little time between the calls. The dynamic type of elements is ContributionBox. It is safe to call it frequently. Threads should care of synchronization when iterating over it.

getCommands

public java.util.List getCommands()
Returns known active commands in an unmodifiable list. The list contains at most MAX_COMMANDS_SIZE elements from the command database. It is safe to call it frequently. Threads should care of synchronization when iterating over the it.

toString

public java.lang.String toString()
Overrides:
toString in class java.lang.Object