gumbo.util.route
Class EventDataNode

java.lang.Object
  |
  +--gumbo.util.AbstractDisposable
        |
        +--gumbo.util.route.EventNode
              |
              +--gumbo.util.route.EventDataNode

All Implemented Interfaces:

Disposable, EventNodeMarker

Direct Known Subclasses:

AbstractObjectField, BooleanField, CharField, DoubleField, IntField, NotifyNode

public abstract class EventDataNode

extends EventNode

An event node that sends and/or receives a single data value. A data node has a "node type" defined by its EventDataNode subclass, and a "data type" defined implicitly by its node type (such as NotifyNode and primitive data type fields, such as DoubleField) or explicitly at construction time (see ObjectField).

By default, when a data node receives an event, either as an input or with set(), it saves the value and processes the event, by calling process(). It can also relay the event to any receivers. Relay occurs after the value change, but before processing, after processing, or not at all.

Event data nodes that maintain a data value state are called "event fields". By convention, fields contain a set(), get(), implSet(), and implSend() method with a strongly typed data value (as in DoubleField). Fields also contain a no-argument constructor and a srongly typed data value constructor, for initialization. implSet() and implSend() are intended for exclusive use by event handlers.

Version:

$Revision: 1.2 $

Author:

Jon Barrilleaux (jonb@jmbaai.com) of JMB and Associates Inc.

Constructor Summary

EventDataNode()

Method Summary

protected boolean	checkRouter(EventRouter router) Called by the system to check a router before using it to connect this node to another node.
protected abstract void	checkSender(EventDataNode sender) Called by the system (subclasses) to check a sender before connecting it to this node.
void	enableDebug(boolean enable) Enables/disables debug event reporting.
protected abstract java.lang.String	getDataValue() Get this node's data value as a string.
java.util.List	getReceivers() Returns an immutable view of the event nodes (EventDataNode) connected to this node as event receivers.
int	getRelayType() Gets the relay type of this event node.
java.util.Set	getSenders() Returns an immutable view of the event nodes (EventDataNode) connected to this node as event senders.
protected void	implDispose() Disconnects this node's senders and receivers, and then disposes its fields.
boolean	implSend() Used by the system (subclasses and hosts) to send the current data value of this node to its receivers, without event processing and regardless of event relaying.
protected void	implSysProcess() Used by the system (this class and subclasses) to process an input event.
boolean	isReceiver(EventNodeMarker receiver) Returns true if an event node is connected to this node as an event receiver.
boolean	isSender(EventNodeMarker sender) Returns true if an event node is connected to this node as an event sender.
protected void	process() Called by the system (this class) when this node needs to process an event, whether the event is received through a connection or results from a set() method.
void	setDebug(java.lang.String tag) Sets the configuration for debug event reporting, with the debug message being the debug tag (see setDebug(tag, msg)).
void	setDebug(java.lang.String tag, java.lang.String msg) Sets the configuration for debug event reporting.
protected void	setRelayType(int type) Used by the system (subclasses and hosts) to set when and if input events (receive or set) are relayed as output events (send).
boolean	sync() Synchronizes this node and its receivers to its current data value.

Methods inherited from class gumbo.util.route.EventNode

isLocked

Methods inherited from class gumbo.util.AbstractDisposable

dispose, isDisposed

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

EventDataNode

public EventDataNode()

Method Detail

implSend

public final boolean implSend()

Used by the system (subclasses and hosts) to send the current data value of this node to its receivers, without event processing and regardless of event relaying. TODO: Should set() be used instead, which would eliminate this method.

isSender

public final boolean isSender(EventNodeMarker sender)

Returns true if an event node is connected to this node as an event sender.

isReceiver

public final boolean isReceiver(EventNodeMarker receiver)

Returns true if an event node is connected to this node as an event receiver.

getSenders

public final java.util.Set getSenders()

Returns an immutable view of the event nodes (EventDataNode) connected to this node as event senders. Never null.

getReceivers

public final java.util.List getReceivers()

Returns an immutable view of the event nodes (EventDataNode) connected to this node as event receivers. Never null.

getRelayType

public int getRelayType()

Gets the relay type of this event node. See setRelayType().

Returns:

The relay type. -1 for relay before processing. 1 for relay after processing. 0 for no relay.

setDebug

public void setDebug(java.lang.String tag,
                     java.lang.String msg)

Sets the configuration for debug event reporting. If debug reporting is enabled (see enableDebug()) and debug conditions are satisfied (see Debug), a debug message is reported each time an event is received or sent. Does not affect the use of this node's special debug connection. Replaces any previous debug tag and message for this node. The default configuration blocks debug reporting. Typically, debug conditions are satisfied by setting the following VM arguments.
-Ddebug.enabled=true -Ddebug.tags=tag
.

Parameters:

tag - Debug tag (see Debug). Never null.

msg - Debug message. If the node has a value, "=value" will be appended. Never null.

setDebug

public void setDebug(java.lang.String tag)

Sets the configuration for debug event reporting, with the debug message being the debug tag (see setDebug(tag, msg)).

Parameters:

tag - Debug tag (see Debug). Never null.

enableDebug

public void enableDebug(boolean enable)

Enables/disables debug event reporting. The default is true (enabled), but nothing will be reported until debugging has been set (see setDebug()).

getDataValue

protected abstract java.lang.String getDataValue()

Get this node's data value as a string. Used by the system to contruct a debug message.

Returns:

The data value. Empty if no value (NotifyNode). Never null.

checkSender

protected abstract void checkSender(EventDataNode sender)

Called by the system (subclasses) to check a sender before connecting it to this node. Implementers should throw an exception if the sender is invalid, and can assume that the sender is non-null.

process

protected void process()

Called by the system (this class) when this node needs to process an event, whether the event is received through a connection or results from a set() method. Default implementation: Does nothing. Subclasses should override this method to do something useful for the host.

setRelayType

protected final void setRelayType(int type)

Used by the system (subclasses and hosts) to set when and if input events (receive or set) are relayed as output events (send). Should only be set once, during initialization.

Parameters:

type - <1 for relay before processing. >1 for relay after processing. 0 for no relay. The default is after processing.

implSysProcess

protected final void implSysProcess()

Used by the system (this class and subclasses) to process an input event. Includes relaying it as an output event to receivers according to the relay mode and the debug connection.

checkRouter

protected boolean checkRouter(EventRouter router)

Description copied from class: EventNode

Called by the system to check a router before using it to connect this node to another node. Implementers should throw an exception if the router is invalid, and return false if the connection should be silently ignored. Can assume that the router is non-null.

Specified by:

checkRouter in class EventNode

sync

public final boolean sync()

Description copied from class: EventNode

Synchronizes this node and its receivers to its current data value. Equivalent to sending an event to this node with its current data value (sets this node's data value, processes the event and, if enabled, relays the event to receivers). Typically used during host object construction. Only affects stateful data nodes (fields), directly or as a group member.

Specified by:

sync in class EventNode

implDispose

protected void implDispose()

Disconnects this node's senders and receivers, and then disposes its fields.

Specified by:

implDispose in class AbstractDisposable