Fluency Event Broker

Purpose

The Fluency Event Broker handles the brokering of all the the events inside of Fluency. The Event Broker does this by maintaining lists of interested FluencyEventHandlers for each type of FluencyEvent.
The Fluency Event Broker also allows all of the Swing Event Listeners to be implemented in one class, and used for the entire code base. This will prevent multiple listeners from responding based on the same events, and will also allow the user to modify one place to change how a Swing Event is handled in Fluency.

Design Patterns

The FluencyEventBroker class uses Singleton to allow only one instance of the Event Broker to exist when Fluency is running.  All of the Swing events are wrapped in an adapter class which turns the Swing events into Fluency events, so they can be handled properly inside of Fluency.  When the Event Broker detects a new event, it handles the event and then sends the event to each subscribed FluencyEventHandler which is the Event Broker design pattern.

Progress

This diagram shows the progress of the event listeners in the FluencyEventBroker class:

Red - None of the Swing event listeners have been removed from the code base, and none of the Swing events have been changed into Fluency events

Yellow - Some of the Swing event listeners have been removed from the code base, and all of the Swing events have been changed into Fluency events

Green - The event listeners in FluencyEventBroker are the only source of the events in the Fluency code base

Full Size

Swing listeners to remove (last updated 6:15pm Nov 29)

By searching "swing*istener" (for imports).  This hasn't been combed to ensure all of these actually need to be replaced.

AWT listeners to remove (last updated 7pm Nov 24)

There are currently 77 matches on "awt*istener" (including 10 from FluencyEventBroker and 13 from GlobalGlassPane).  I won't list them all here, but add a table to the row below if you want to claim a class.

FluencyEventBroker

Subscribing to Events

To subscribe a FluencyEventHandler to accept a certain type of event, in that controller's constructor call

FluencyEventBroker.EVENT_BROKER.addEventSubscriber(FluencyEventType.getEventClassName(), FluencyEventHandler <object you want to handle events, probably this>);

This will add the caller to the subscriber list for FluencyEventType (which can be any FluencyEvent in the codebase). The event chosen should be the specific event (i.e. FluencyKeyTypedEvent) rather than the general one (i.e. FluencyKeyEvent).

Publishing

Publishers of certain types of events have to meet certain criteria (for instance, a JLabel cannot publish WindowOpened and WindowClosed events), but the typical syntax for adding a publisher is

FluencyEventBroker.EVENT_BROKER.addEventTypePublisher(this);

where EventType is the superclass event type (i.e. use addMousePublisher for something that will publish MouseClicked events).

Brokering an Event

The broker a Fluency Event to all of the interested subscribers use this type of code:

FluencyEventBroker.EVENT_BROKER.brokerEvent(FluencyEvent);

where FluencyEvent is the event you wish to have brokered.

Fluency Hierarchy Components and the Event Broker

Subscribing and brokering events has been made a bit simpler inside of the FluencyHierarchyComponents since the super class implements a few methods to make it easier.

addEventSubscriber(FluencyEventType.getEventClassName());
generateEvent(FluencyEvent);

The addEventSubscriber method automatically passes in the Fluency Hierarchy Component where it is called from to be used as the subscriber for the event, so there is no need to pass a specific listener to the Event Broker from inside of a Fluency Hierarchy Component. The generateEvent method works by passing the given event on to the Event Broker where it is then brokered to the interested subscribers. Neither of these functions do anything new with the events, and they only exist to make things the event broker interaction a bit simpler inside of the Fluency Hierarchy Components.

Events

Event Syntax

Naming Conventions

New Fluency Events are named Fluency<event type>Event by convention.

Interface contract

Events must report their type as a String according to FluencyEvent.getEventName() and the name should be stored in the implementing class as

public static final String EVENT_NAME

so recipients can accurately check against type. Events must also report their source through FluencyEvent.getOriginatingComponent().

Additionally, events are required (though it is not enforced through an interface) to have a static getEventClassName() that returns the same EVENT_NAME string as the instance method.

Package structure

Events in the codebase are broken down into two sets: nativeevents and swingwrapperevents. These are further broken into several packages (fluencyapplicationevents, internalframeevents, componentevents, focusevents, etc.). It is important to note that when an event is added to the package tree it also needs to be added in the initializer function for the FluencyEventBroker in the deepest applicable package (so the FluencyWindowOpened event is added to the map held in the FluencyEventBroker in addSwingWrapperEvents() -> addWindowEvents()).

Events in the codebase are broken down into two sets: nativeevents and swingwrapperevents. These are further broken into several packages (fluencyapplicationevents, internalframeevents, componentevents, focusevents, etc.).

FluencyEventHandler

FluencyEventHandler objects can handle events in the Fluency system.

Event Receipt

when the FluencyEventHandler.handleEvent(FluencyEvent event) method is called, the receiver should check against the type of events it wants to handle. If the recipient decides to handle the event, it will cast the event to the correct type and perform whatever work it needs to do. FluencyEventHandlers will only receive the types of events they have subscribed to receive. It is important for some FluencyEventHandlers to consider the OriginatingComponent of the event!

Design Diagram

Full Size