Package gumbo.util.route

Provides interfaces, services, and utilities that support the "routing" of events, with or without data, between objects.

See:
Description

Interface Summary

EventIn	Marker interface for an event data node that can receive and process events (a data event sink).
EventInOut	Marker interface for an event data node that can both initiate and process events (a data event source and sink).
EventNodeMarker	Marker interface for all event node interfaces and classes, which indicates that the object is connectable for event routing.
EventOut	Marker interface for an event data node that can initiate and send events (a data event source).

Class Summary

AbstractObjectField	An abstract base class for an event data node that maintains and transfers data as an Object, and whose data type is specified explicitly.
AbstractObjectField.EventIn
AbstractObjectField.EventOut
AllTests
AndFilter	Combines boolean inputs into a logical AND output.
BooleanField
BooleanField.EventIn
BooleanField.EventInOut
BooleanField.EventOut
CharField
CharField.EventIn
CharField.EventInOut
CharField.EventOut
ClassField
ClassField.EventIn
ClassField.EventInOut
ClassField.EventOut
CollectionField	An object field whose default data type is Object.
CollectionField.EventIn
CollectionField.EventInOut
CollectionField.EventOut
DebugDataRouter	A router for connecting a "master" target node (node A) to a "slave" debug monitor node (node B).
DebugEventMonitor	Abstract base class for a host object event monitor.
DirectRouters	Predefined "direct" routers intended for use by event node meta-clients (use event nodes) and clients (implement event nodes).
DirectRouters.Router	Connects EventOut to EventIn, one or two-way.
DoubleField
DoubleField.EventIn
DoubleField.EventInOut
DoubleField.EventOut
EventBooleanTest
EventDataNode	An event node that sends and/or receives a single data value.
EventDataRouter	A router for connecting two event data nodes.
EventDataRouterTest
EventGroupNode	An event node that consists of none or more unique and ordered event node "members".
EventGroupRouter
EventGroupRouterTest
EventNode	Intended as a public delegate for sending events between delegator (host) objects.
EventNotifyTest
EventObjectTest
EventRouter	An abstract "strategy" for connecting two event nodes.
ImplRouters	Predefined "implementation" routers intended for use by event node clients (implement event nodes), not meta-clients (use event nodes).
IntField
IntField.EventIn
IntField.EventInOut
IntField.EventOut
NotFilter	Combines notify and boolean inputs into a logical NOT output, with corresponding notify events.
NotifyNode	An event data node that transfers no data (event is for notification only).
NotifyNode.EventIn
NotifyNode.EventInOut
NotifyNode.EventOut
ObjectField	An object field whose default data type is Object.
ObjectField.EventIn
ObjectField.EventInOut
ObjectField.EventOut
OrFilter	Combines boolean inputs into a logical OR output.
RelayDataRouter	Connects EventIn to EventIn, or EventOut to EventOut, one or two-way.
RelayRouters	Predefined "relay" routers intended for use by event node meta-clients (use event nodes) and clients (implement event nodes).
RelayRouters.Router	Connects EventIn to EventIn, or EventOut to EventOut, one or two-way.
StrictGroupRouter
TestBooleanHost
TestGroupHost
TestHost
TestNotifyHost
TestNotifySubHost
TestObjectHost

Package gumbo.util.route Description

Provides interfaces, services, and utilities that support the "routing" of events, with or without data, between objects.

Overview

The reasons for developing yet another event model are:

• VRML-like event routing.
  • Easy to use and modify, with the event "wiring" being explicit.
  • Promotes the assembly of small building blocks into functional units.
• Provided as a delegated service.
  • Can be easily added to existing classes.
  • Can co-exist with the standard Java event model.
    
  • Allows separation of semantics and syntax (same event type use different ways in the same object).
    
• Take advantage of immutable data objects.
  • Avoids creation of lots of small "event" objects.
• Strongly typed parameters at compile time.
  • Event data type is not Object.
  • Event node type implies direction.

General

ToDo:

• Group node mimics normal java interface, with multiple methods
• To generate an event the entire node (e.g. group) is locked.
  

Naming Conventions

Event routing promotes the use of small functional modules. Modules that convert from one type of event to another are called adapters. Modules that input and output the same type of event are called filters. Modules that sense the presence or absence of conditions via input events are called triggers.

Access Levels

There are three levels of access within the event framework. System access refers to those aspects of the event system required to make it work, which generally has package visibility. Internal access has public visibility and allows unrestricted access to the node. Such access is intended for use by a developer for internal connection and state management within the node's host object (delegator). External access has public visibility and supports activities occuring outside of an event node's host object. Clients using the host object and its event nodes typically only make connections between nodes, and do not manipulate the node itself. Ideally, external access is restricted such that the user cannot affect internal node connections or state consistency.

Event Nodes

There are two general types of event nodes. Event element nodes (see EventElementNode) send output events and receive input events, which may involve notification only (see NotifyNode) or may additionally transfer data (see EventDataNode). Event group nodes (see EventGroupNode) allow for the grouping of event nodes. Such groupings permit the definition of complex event interfaces consisting of elements and groups.

Event nodes are inherently directionless in that they can handle both incoming and outgoing events. To achieve strong typing at compile time, marker interfaces are used to establish a node's external direction.

Event Routes

A "route" is not an object, but a mutual state maintained between connected nodes. EventRouter provides several utility methods for making and breaking routes (event connections). Routes can only be established between two compatible event nodes.

By definition, connections between event nodes have a direction, from source node (the sender of output events) to target node (the receiver of input events). For group nodes defining a bi-directional interface, two connections must be established, one for each direction between the nodes. Marker interfaces (EventIn, EventOut, EventInOut) facilitate node typing, event direction definition, and limit external access to the node.

Event Locking

Event nodes incorporate a simple but efficient locking mechanism. When a node receives an event or an attempt is made to connect to the node, the system locks it. A locked node prevents event loops by silently ignoring new input events, and blocks concurrent connection changes by throwing an exception, all of which offers a modicum of thread safety. The event processing thread can access the lock state of a node using isLocked(). Other threads should not rely on this method since it is not sychronized.

Event Subclassing

The general pattern for using event nodes in a host object is to subclass concrete subclasses of EventElementNode and EventGroupNode to support specific syntax (type of event data or composition of the event group) and semantics (purpose of the event node and its events). Subclassing allows full internal access to the node. Public host "get" methods, typically named for the node semantics (e.g. getDragIn()), provide external access to the host's nodes. These methods can return the node itself, making external and internal access the same, or a marker interface that also restricts external access. Once the downstream event chain for a node is established, its sync() method should be called to sync the chain state with that of the node's initial value. See EventElementNode and its subclasses for further details concerning the patterns for event node usage.

Event Marker Interfaces

Direction marker interfaces and message nodes are generally named ???In, ???Out, and ???InOut, indicating the node's ability to handle external input events ("In") and/or to generate external output events ("Out"). Marker interfaces and group nodes for bi-directional group interfaces are generally named ???Plug and ???Jack, indicating the complementary and non-directional nature of these group nodes and their connections.