net.sourceforge.hiveevents
Interface Channel<T>

All Superinterfaces:

Consumer<T>

All Known Implementing Classes:

ChannelImpl, SyncChannelImpl

public interface Channel<T>
extends Consumer<T>

General Event Channel interface. A Channel is used to link (in a loosely coupled way) event suppliers with event consumers.

All event suppliers must supply events according to the push-model. Event consumers may accept events according to the push- or pull-models.

Every consumer in a Channel (whatever push- or pull-) is given a unique integral id at the time of regsitration. This id must be used to unregister the consumer from this Channel.

Push consumers are served according to the priority with which they have been registered. The lower the value, the higher the priority (i.e. push consumers with lowest priority values will be served first).

Author:

Jean-Francois Poilpret

Method Summary

void	block() Temporarily block the Channel, ie any supplied event will be stored inside the Channel but not dispatched to consumers until the Channel is unblocked.
java.lang.String	getName() Get the name (unique identifier) of this Channel.
T[]	pull(int idConsumer) Called by a registered pull-consumer to retrieve all events supplied to the Channel since the previous call to pull() (or since registration if this is the first call).
T[]	pull(int idConsumer, long timeout) Called by a registered pull-consumer to retrieve all events supplied to the Channel since the previous call to pull() (or since registration if this is the first call).
void	push(T event) Called by an event supplier to trigger this Channel to notify all consumers about a new event.
int	registerPullConsumer() Registers a pull-consumer to this Channel.
int	registerPullConsumer(Filter<T> filter) Registers a pull-consumer to this Channel.
int	registerPushConsumer(int priority, Consumer<T> consumer) Registers a push-consumer to this Channel.
int	registerPushConsumer(int priority, Filter<T> filter, Consumer<T> consumer) Registers a push-consumer to this Channel.
void	unblock() Unblocks a Channel that was blocked ie any event that was received during the blocking time is dispatched to all consumers and any new event received will be normally dispatched as well.
void	unblockPullConsumer(int idConsumer) Unblocks a pull consumer that is currently waiting for a timed pull call to return some events.
void	unregisterAllConsumers() Unregister all consumers from this Channel.
void	unregisterConsumer(int idConsumer) Unregister the identified consumer from this Channel.

Method Detail

getName

java.lang.String getName()

Get the name (unique identifier) of this Channel.

Returns:

the name of the Channel

block

void block()

Temporarily block the Channel, ie any supplied event will be stored inside the Channel but not dispatched to consumers until the Channel is unblocked.

If called n times, unblock() must also be called n times to unblock the Channel.

unblock

void unblock()

Unblocks a Channel that was blocked ie any event that was received during the blocking time is dispatched to all consumers and any new event received will be normally dispatched as well.

This method has no effect if the Channel is not currently blocked. It has no effect either if it has been called less times than block().

unregisterConsumer

void unregisterConsumer(int idConsumer)

Unregister the identified consumer from this Channel. That consumer will not be notified of any event any longer.

Parameters:

idConsumer - the unique id of the consumer to unregister. If this id does not exist, then the method does nothing.

unregisterAllConsumers

void unregisterAllConsumers()

Unregister all consumers from this Channel.

registerPushConsumer

int registerPushConsumer(int priority,
                         Consumer<T> consumer)

Registers a push-consumer to this Channel. From now on, this consumer will be notified of all events supplied to the Channel.

Normally, the Channel only keeps a weak reference to every push consumer (until it is unregistered or until it has no strong references left). However, for convenience reasons when using consumer instances which we do not want to (or cannot) keep a strong reference, consumers can implement the PersistentConsumer marker interface, for these, the Channel keeps a strong reference so that they are not garbage collected until they are explicitly unregistered.

Parameters:

priority - the priority (order) with which the new consumer should be notified of new events, the lower the sooner.

consumer - the actual instance that will be notified (push()) when events are supplied to the Channel

Returns:

the unique id of the new consumer for this Channel

registerPushConsumer

int registerPushConsumer(int priority,
                         Filter<T> filter,
                         Consumer<T> consumer)

Registers a push-consumer to this Channel. From now on, this consumer will be notified of all events (if they are validated by the supplied Filter) supplied to the Channel.

Parameters:

priority - the priority (order) with which the new consumer should be notified of new events, the lower the sooner.

filter - a filter instance that will be called for each event received by the Channel in order to decide whether the new consumer must be notified of this event or not

consumer - the actual instance that will be notified (push()) when events are supplied to the Channel

Returns:

the unique id of the new consumer for this Channel

registerPullConsumer

int registerPullConsumer()

Registers a pull-consumer to this Channel. From now on, this consumer will be notified of all events supplied to the Channel (provided that a thread periodically calls pull() on this Channel on behalf of that consumer).

Returns:

the unique id of the new consumer for this Channel (to be used in the invocation of pull())

registerPullConsumer

int registerPullConsumer(Filter<T> filter)

Registers a pull-consumer to this Channel. From now on, this consumer will be notified of all events (if they are validated by the supplied Filter) supplied to the Channel (provided that a thread periodically calls pull() on this Channel on behalf of that consumer).

Parameters:

filter - a filter instance that will be called for each event received by the Channel in order to decide whether the new consumer must be notified of this event or not

Returns:

the unique id of the new consumer for this Channel (to be used in the invocation of pull())

unblockPullConsumer

void unblockPullConsumer(int idConsumer)

Unblocks a pull consumer that is currently waiting for a timed pull call to return some events. Has no effect if the given consumer does not exist, is not a pull consumer, or is not currently waiting in a blocking pull() call.

Parameters:

idConsumer - the unique id of the consumer to unblock.

pull

T[] pull(int idConsumer)

Called by a registered pull-consumer to retrieve all events supplied to the Channel since the previous call to pull() (or since registration if this is the first call).

This method is blocking for the calling thread until there are events to return.

Parameters:

idConsumer - the unique id of the consumer that pulls data. If this id does not exist, then the method returns null.

Returns:

the list of events that have occurred since previous call (events that did not pass the filter are not part of that list).

pull

T[] pull(int idConsumer,
         long timeout)

Called by a registered pull-consumer to retrieve all events supplied to the Channel since the previous call to pull() (or since registration if this is the first call).

This method is blocking for the calling thread until there are events to return or the specified timeout is elapsed.

Parameters:

idConsumer - the unique id of the consumer to unregister. If this id does not exist, then the method returns null.

timeout - maximum time (in ms) to wait for events to come; if 0, then the method returns immediately whether there are events or not.

Returns:

the list of events that have occurred since previous call (events that did not pass the filter are not part of that list).

push

void push(T event)

Called by an event supplier to trigger this Channel to notify all consumers about a new event.

Specified by:

push in interface Consumer<T>

Parameters:

event - the event notified (can be anything)