rcf.core.concurrent.events
Interface EventSyndicate

All Superinterfaces:

EventSink<Event>

All Known Implementing Classes:

ArrayEventSyndicate, HashEventSyndicate

@Revision(value="$Revision: 1.13 $",
          date="$Date: 2006/12/15 20:37:49 $",
          tag="$Name:  $")
public interface EventSyndicate
extends EventSink<Event>

A syndicate which distributes events from a single EventSource to many EventSinks, according to the Class of the event and the class of events for which the event sink was registered with add(Reference, Class). For a more in depth discussion of the event model, see rcf.core.concurrent.events.

Note that the methods of this interface are compatible with both Collection and MapCollection. This is vital as it means that this interface can be easily implemented by either a map or a collection.

TODO: Javadoc review, Seal/Finalize

Version:

$Revision: 1.13 $

Author:

Greg Gibeling

Method Summary

<E extends Event> ImmutableIterator<?>	add(Reference<EventSink<? super E>> _sinkReference, Class<E> _class) Register an event sink to receive all of the events from the EventSource for this syndicate, which are assignable to the specified class.
boolean	event(Event event) Report the event to all EventSinks which have been registered through add(Reference, Class) with _class.isAssignableFrom(event.getClass()).
boolean	isEmpty() Check if this event syndicate is empty; size() == 0.
<E extends Event> ImmutableIterator<?>	remove(Reference<EventSink<? super E>> _sinkReference, Class<E> _class) Deregister an event sink to stop receiving events from the EventSource for this syndicate.
int	size() Get the number of event sinks which have been registered with the syndicate.

Method Detail

add

<E extends Event> ImmutableIterator<?> add(Reference<EventSink<? super E>> _sinkReference,
                                           Class<E> _class)

Register an event sink to receive all of the events from the EventSource for this syndicate, which are assignable to the specified class.

Parameters:

_sinkReference - A reference to the event sink, which this syndicate is supposed to call EventSink.event(Event) on. Notice that this is a reference, so that WeakReferences can be used to avoid having this syndicate send events to an event sink which would otherwise have been garbage collected.

_class - The class of events the EventSink specified by _sinkReference wants to receive from this syndicate.

Returns:

An iterator which can be used to remove this sink from the syndicate. This return type is also chosen to be compatible with Collection and MapCollection.

event

boolean event(Event event)

Report the event to all EventSinks which have been registered through add(Reference, Class) with _class.isAssignableFrom(event.getClass()). Note the the reporting of an event will be interrupted if the Event.isCancelled() method returns true. An event syndicate must not report a cancelled event to any event sink, however it may report an event which will later be cancelled.

Specified by:

event in interface EventSink<Event>

Parameters:

event - The event from the EventSource, which is to be reported to all of the EventSinks registered through add(Reference, Class).

Returns:

true if the syndicate isn't empty. false to indicate that the syndicate can be freed.

See Also:

EventSink.event(rcf.core.concurrent.events.Event)

isEmpty

boolean isEmpty()

Check if this event syndicate is empty; size() == 0.

Returns:

true if this syndicate is empty.

remove

<E extends Event> ImmutableIterator<?> remove(Reference<EventSink<? super E>> _sinkReference,
                                              Class<E> _class)

Deregister an event sink to stop receiving events from the EventSource for this syndicate.

Parameters:

_sinkReference - A reference to the event sink, which this syndicate should no longer report events to. Note that the Reference.type() of the reference is immaterial.

_class - The class of events the EventSink specified by _sinkReference was to receiving from this syndicate.

Returns:

An iterator which can be used to remove this sink from the syndicate. This return type is also chosen to be compatible with Collection and MapCollection.

size

int size()

Get the number of event sinks which have been registered with the syndicate.

Returns:

The number of event sinks which have been registered with the syndicate.