JXTA

net.jxta.util
Class SimpleSelector

java.lang.Object
  extended by net.jxta.util.AbstractSimpleSelectable
      extended by net.jxta.util.SimpleSelector
All Implemented Interfaces:
SimpleSelectable

public final class SimpleSelector
extends AbstractSimpleSelectable

A very primitive version of NIO's select mechanism. Applications should not code to this API yet. This is subject to change and for use only by internal mechanisms. This is only good at implementing efficient polling. Users must wait for a batch of state changes and then figure out which item's state changed to something interesting. The batch returned by simpleSelect is a set of the items which state did change since the previous time select returned. Since a batch is returned as soon as there is at least one item in it, most batches are very small, they will contain the first item that was added, plus whatever few could sneak in between then and when select wakes-up and grabs that batch.

A simpleSelector It is not very usable by multiple threads at once, unless they all do the same thing. Items are removed from the current batch when select returns it. As a result, any state change occurring in-between two calls to select() is guaranteed to be reported by the next call. However, the new state may be observed before the next select call to select returns the corresponding event, which may then be viewed as redundant. So events are reported too much rather than too little.


Nested Class Summary
 
Nested classes/interfaces inherited from interface net.jxta.util.SimpleSelectable
SimpleSelectable.IdentityReference
 
Field Summary
 
Fields inherited from class net.jxta.util.AbstractSimpleSelectable
identityReference
 
Constructor Summary
SimpleSelector()
          Let it be newed for now.
 
Method Summary
 void itemChanged(SimpleSelectable item)
          This method is invoked when the given selectable object has changed.
 Collection<SimpleSelectable> select()
          This blocks unless and until at least one of the selected items reports that it changed.
 
Methods inherited from class net.jxta.util.AbstractSimpleSelectable
getIdentityReference, haveListeners, notifyChange, register, registerListener, unregister, unregisterListener
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

SimpleSelector

public SimpleSelector()
Let it be newed for now. We need to find a place for a factory.

Method Detail

itemChanged

public final void itemChanged(SimpleSelectable item)
This method is invoked when the given selectable object has changed. This permits to cascade selectable objects, so that one reports a change when the other changes, without having to select it. This also permits implementation of this interface by delegating its implementation to a utility class.

An implementation may do what it wants about it. For example, a SimpleSelector will report the change to select() and invoke AbstractSimpleSelectable.notifyChange() thereby reporting its own change to cascaded selectors. Other implementations may only invoke AbstractSimpleSelectable.notifyChange() or may perform more complex tasks.

This is invoked by registered items when their state changes. Records changes for the benefit of select(), and performs notifyChange(), which will cause notification of cascaded selectors, if any. It is thus possible to register selectors with a selector and come to a particular one only when it has something to report.

Parameters:
item - the object that has changed.
See Also:
AbstractSimpleSelectable

select

public Collection<SimpleSelectable> select()
                                    throws InterruptedException
This blocks unless and until at least one of the selected items reports that it changed. Then the list of such items is returned. More than one item may be added to the list by the time it is returned to the invoker.

Note: the result cannot be a set, otherwise we would be prevented from returning objects that overload hashCode/equals. Every item returned will be a distinct object.

The invoker should never assume that all items in the result have indeed changed in any expected manner or even changed at all. The simple action of registering a selector may, and usually does, cause the selectable object to report a change. In some cases a selectable object may just be unable to prove that it has not changed, and thus report a change. It is up to the invoker to inspect the relevant item's state every time.

Throws:
InterruptedException

JXSE