org.bushe.swing.event
Class EventServiceAction

java.lang.Object
  javax.swing.AbstractAction
      org.bushe.swing.event.EventServiceAction

All Implemented Interfaces:

java.awt.event.ActionListener, java.io.Serializable, java.lang.Cloneable, java.util.EventListener, javax.swing.Action

Direct Known Subclasses:

ContainerEventServiceAction, EventBusAction

public abstract class EventServiceAction
extends javax.swing.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 java.lang.String	EVENT_BUS_EVENT_CLASS_NAME
static java.lang.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(java.lang.String actionName, javax.swing.ImageIcon icon)

Method Summary

void	actionPerformed(java.awt.event.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(java.awt.event.ActionEvent event) Override to return the EventService on which to publish.
protected java.lang.Object	getEventServiceEvent(java.awt.event.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.
java.lang.Object	getName()
boolean	getThrowsExceptionOnNullEventService() By default, exceptions are throw if getEventService() returns null.
java.lang.String	getTopicName(java.awt.event.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 java.lang.Object	getTopicValue(java.awt.event.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(java.lang.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 java.lang.String EVENT_SERVICE_TOPIC_NAME

See Also:

Constant Field Values

EVENT_BUS_EVENT_CLASS_NAME

public static final java.lang.String EVENT_BUS_EVENT_CLASS_NAME

See Also:

Constant Field Values

Constructor Detail

EventServiceAction

public EventServiceAction()

EventServiceAction

public EventServiceAction(java.lang.String actionName,
                          javax.swing.ImageIcon icon)

Method Detail

getEventService

protected abstract EventService getEventService(java.awt.event.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(java.lang.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 java.lang.String getTopicName(java.awt.event.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 java.lang.Object getTopicValue(java.awt.event.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 java.lang.Object getName()

Returns:

the name of the action (javax.swing.Action#NAME)

getEventServiceEvent

protected java.lang.Object getEventServiceEvent(java.awt.event.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(java.awt.event.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:

java.lang.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