org.bushe.swing.event
Class EventServiceAction

java.lang.Object
  extended by javax.swing.AbstractAction
      extended by org.bushe.swing.event.EventServiceAction
All Implemented Interfaces:
ActionListener, Serializable, Cloneable, EventListener, Action
Direct Known Subclasses:
ContainerEventServiceAction, EventBusAction

public abstract class EventServiceAction
extends AbstractAction

Abstract class that publishes a Swing ActionEvent (or another object) to an EventService.

This abstract class ties the Swing Actions with the Event Bus. When fired, an ActionEvent is published on an EventService - either the global EventBus or a Container EventService.

There are two derivatives of this class: The EventBusAction, which publishes the ActionEvent on the global EventBus, and the ContainerEventServiceAction, which publishes the ActionEvent on the a local ContainerEventService.

By default the ActionEvent is published on an EventService topic corresponding to this action's Action.ACTION_COMMAND_KEY. Though this behavior is highly configurable. See getTopicName(ActionEvent) and setTopicName(String) for ways to customize the topic used. Override getTopicValue(ActionEvent) to publish an object other than the ActionEvent.

Instead of publishing on a topic, the ActionEvent can be published using class-based publication, use setPublishesOnTopic(boolean) to set this behavior. When using class-based publication, the ActionEvent is published by default. Override getEventServiceEvent(ActionEvent) to publish an object other than the ActionEvent.

See Also:
Serialized Form

Field Summary
static String EVENT_BUS_EVENT_CLASS_NAME
           
static String EVENT_SERVICE_TOPIC_NAME
           
 
Fields inherited from class javax.swing.AbstractAction
changeSupport, enabled
 
Fields inherited from interface javax.swing.Action
ACCELERATOR_KEY, ACTION_COMMAND_KEY, DEFAULT, DISPLAYED_MNEMONIC_INDEX_KEY, LARGE_ICON_KEY, LONG_DESCRIPTION, MNEMONIC_KEY, NAME, SELECTED_KEY, SHORT_DESCRIPTION, SMALL_ICON
 
Constructor Summary
EventServiceAction()
           
EventServiceAction(String actionName, ImageIcon icon)
           
 
Method Summary
 void actionPerformed(ActionEvent event)
          Publishes the event on the EventService returned by getEventService(event)

Gets the EventService from getEventService(java.awt.event.ActionEvent).

protected abstract  EventService getEventService(ActionEvent event)
          Override to return the EventService on which to publish.
protected  Object getEventServiceEvent(ActionEvent event)
          If isPublishesOnTopic() returns false (i.e., when using class-based rather than topic-based publication), then override this method to publish an on object other than the ActionEvent.
 Object getName()
           
 boolean getThrowsExceptionOnNullEventService()
          By default, exceptions are throw if getEventService() returns null.
 String getTopicName(ActionEvent event)
          The topic name is the first non-null value out of: A topic name explicitly set via setTopicName(String) the action's getValue("event-service-topic") EVENT_SERVICE_TOPIC_NAME the action's getValue("ID") (for compatibility with the SAM ActionManager's ID) the action's Action.ACTION_COMMAND_KEY the action event's Action.ACTION_COMMAND_KEY the action's Action.NAME the value is used (if the value is not a String, the value's toString() is used).
protected  Object getTopicValue(ActionEvent event)
          By default, the ActionEvent is the object published on the topic.
 boolean isPublishesOnTopic()
           
 void setPublishesOnTopic(boolean onTopic)
          Sets whether this action publishes on a topic or uses class-based publication.
 void setThrowsExceptionOnNullEventService(boolean throwsExceptionOnNullEventService)
          By default, exceptions are thrown if getEventService() returns null.
 void setTopicName(String topicName)
          Explicitly sets the topic name this action publishes on.
 
Methods inherited from class javax.swing.AbstractAction
addPropertyChangeListener, clone, firePropertyChange, getKeys, getPropertyChangeListeners, getValue, isEnabled, putValue, removePropertyChangeListener, setEnabled
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

EVENT_SERVICE_TOPIC_NAME

public static final String EVENT_SERVICE_TOPIC_NAME
See Also:
Constant Field Values

EVENT_BUS_EVENT_CLASS_NAME

public static final String EVENT_BUS_EVENT_CLASS_NAME
See Also:
Constant Field Values
Constructor Detail

EventServiceAction

public EventServiceAction()

EventServiceAction

public EventServiceAction(String actionName,
                          ImageIcon icon)
Method Detail

getEventService

protected abstract EventService getEventService(ActionEvent event)
Override to return the EventService on which to publish.

Parameters:
event - the event passed to #execute(ActionEvent)
Returns:
the event service to publish on, if null and getThrowsExceptionOnNullEventService() is true (default) an exception is thrown
See Also:
EventBusAction, ContainerEventServiceAction

isPublishesOnTopic

public boolean isPublishesOnTopic()
Returns:
true if this action publishes on a topic, false if it uses class-based publication.

setPublishesOnTopic

public void setPublishesOnTopic(boolean onTopic)
Sets whether this action publishes on a topic or uses class-based publication.

Parameters:
onTopic - true if publishes on topic (the default), false if using class-based publication.

setTopicName

public void setTopicName(String topicName)
Explicitly sets the topic name this action publishes on.

A topic name does not need to be explicitly set. See getTopicName(ActionEvent) to understand how the topic name is determined implicitly.


getTopicName

public String getTopicName(ActionEvent event)
The topic name is the first non-null value out of:
  1. A topic name explicitly set via setTopicName(String)
  2. the action's getValue("event-service-topic") EVENT_SERVICE_TOPIC_NAME
  3. the action's getValue("ID") (for compatibility with the SAM ActionManager's ID)
  4. the action's Action.ACTION_COMMAND_KEY
  5. the action event's Action.ACTION_COMMAND_KEY
  6. the action's Action.NAME the value is used (if the value is not a String, the value's toString() is used).

    To use a different name, override this method.

    Parameters:
    event - the event passed to #execute(ActionEvent)
    Returns:
    the topic name to publish on, getId() by default

getTopicValue

protected Object getTopicValue(ActionEvent event)
By default, the ActionEvent is the object published on the topic. Override this method to publish another object.

Parameters:
event - the event passed to #execute(ActionEvent)
Returns:
the topic value to publish, getId() by default

getName

public Object getName()
Returns:
the name of the action (javax.swing.Action#NAME)

getEventServiceEvent

protected Object getEventServiceEvent(ActionEvent event)
If isPublishesOnTopic() returns false (i.e., when using class-based rather than topic-based publication), then override this method to publish an on object other than the ActionEvent.

Returns:
the Object to publish, cannot be null

actionPerformed

public void actionPerformed(ActionEvent event)
Publishes the event on the EventService returned by getEventService(event)

Gets the EventService from getEventService(java.awt.event.ActionEvent). Checks isPublishesOnTopic(). If true, gets the topic name from getTopicName(java.awt.event.ActionEvent) and the topic value from getTopicValue(ActionEvent), and publishes the value on the topic on the EventService. If false, gets event from getEventServiceEvent(java.awt.event.ActionEvent), and publishes the event on the EventService.

Parameters:
event - the action event to publish.
Throws:
RuntimeException - if getThrowsExceptionOnNullEventService() && getEventService(event) == null

getThrowsExceptionOnNullEventService

public boolean getThrowsExceptionOnNullEventService()
By default, exceptions are throw if getEventService() returns null.

Returns:
false to suppress this behavior

setThrowsExceptionOnNullEventService

public void setThrowsExceptionOnNullEventService(boolean throwsExceptionOnNullEventService)
By default, exceptions are thrown if getEventService() returns null.

Parameters:
throwsExceptionOnNullEventService - true to suppress the exception when there is no event service


Copyright © 2011 Bushe Enterprises, Inc.. All Rights Reserved.