com.pietschy.command
Class ActionCommand

java.lang.Object
  extended by com.pietschy.command.Command
      extended by com.pietschy.command.ActionCommand
All Implemented Interfaces:
ActionCommandExecutor, Bindable, Identifiable
Direct Known Subclasses:
AbstractFileCommand, AbstractUndoCommand, CancelSwingWorkerCommand, CloseWindowCommand, DelegatingCommand, LazyCommand, ProxyCommand, ReflectionCommand, SwingWorkerCommand, ToggleCommand

public abstract class ActionCommand
extends Command
implements ActionCommandExecutor

ActionCommands provide the base for all executable commands. Subclasses must implement handleExecute() to provide command specific behaviour.

To be used in groups commands must be bound to a CommandContainer. Commands can be bound to a container directly or to a Swing component. In the latter case the command will search for a CommandContainer that has been bound to an ancestor of the component.

   // create a print command
   ActionCommand command = new ActionCommand("print")
   {
      public void handleExecute()
      {
         // do the printing...
      }
   };

   // and bind it to a CommandContainer
   command.bind(commandContainer);
 

See Also:
CommandContainer, CommandGroup

Field Summary
static java.lang.String PARAMETER_ACTION_EVENT
          The key for the action event hint.
static java.lang.String PARAMETER_INVOKER
          The key for the invoker hint.
static java.lang.String PARAMETER_INVOKER_WINDOW
          The key for the invoker window hint.
static java.lang.String PARAMETER_MODIFIERS
          The key for the modifiers hint.
 
Fields inherited from class com.pietschy.command.Command
internalLog, PROPERTY_ENABLED, PROPERTY_VISIBLE
 
Constructor Summary
  ActionCommand()
          Creates a new anonymous instance.
  ActionCommand(java.lang.String id)
          Creates a new instance with the specified id.
protected ActionCommand(java.lang.String id, boolean loadConfiguration)
          Creates a new command with the specified id.
 
Method Summary
 void addActionCommandListener(ActionCommandListener listener)
          Adds the specified listener to the command.
 void addInterceptor(ActionCommandInterceptor interceptor)
          Adds the specified interceptor to the command.
protected  void bindToContainer(CommandContainer container)
          Invoked to bind this instance to the specified container.
 javax.swing.AbstractButton createButton(ButtonFactory factory, java.util.Map<?,?> parameters)
          Creates a parameterized button that will always invoke the commad with the specified parameters.
 javax.swing.AbstractButton createButton(ButtonFactory factory, java.lang.String context, java.util.Map<?,?> parameters)
          Creates a parameterized button that will always invoke the commad with the specified parameters.
 javax.swing.AbstractButton createButton(java.util.Map<?,?> parameters)
          Creates a parameterized button that will always invoke the commad with the specified parameters.
 javax.swing.AbstractButton createButton(java.lang.String context, java.util.Map<?,?> parameters)
          Creates a parameterized button that will always invoke the commad with the specified parameters.
 javax.swing.JMenuItem createMenuItem(java.util.Map<?,?> parameters)
          Creates a parameterized menu item that will always invoke the commad with the specified parameters.
 javax.swing.JMenuItem createMenuItem(MenuFactory factory, java.util.Map<?,?> parameters)
          Creates a parameterized menu item that will always invoke the commad with the specified parameters.
 javax.swing.JMenuItem createMenuItem(MenuFactory factory, java.lang.String context, java.util.Map<?,?> parameters)
          Creates a parameterized menu item that will always invoke the commad with the specified parameters.
 javax.swing.JMenuItem createMenuItem(java.lang.String context, java.util.Map<?,?> parameters)
          Creates a parameterized menu item that will always invoke the commad with the specified parameters.
protected  void doButtonAttachments(javax.swing.AbstractButton button, java.lang.String faceName)
          Overrides the default implementation to also add an ActionListener to the button.
protected  void doButtonDetachments(javax.swing.AbstractButton button)
          Overrides the default implementation to remove the ActionListener installed by doButtonAttachments(AbstractButton, String).
 void execute()
          Causes the command to perform it's operation.
 void execute(java.util.Map<java.lang.Object,java.lang.Object> parameters)
          Executes this command with the specified parameters.
 javax.swing.Action getActionAdapter()
          Gets an action that mirrors the default face of this command.
 javax.swing.Action getActionAdapter(java.lang.String context)
          Gets an action that mirrors this the specified face of this command.
 java.awt.event.ActionEvent getActionEvent()
          Convenience method for getParameter(ActionCommand.PARAMETER_ACTION_EVENT).
 java.lang.Object getInvoker()
          Convenience method to get the object that invoked the command.
 java.awt.Window getInvokerWindow()
          Convenience method to get the Window ancestor of the object that invoked the command.
 int getModifiers()
          Convenience method to get any modifiers that were specified.
 java.lang.Object getParameter(java.lang.Object key)
          Gets any paramters that may have been specified by a call to ActionCommandExecutor.execute(Map) or that have been explicitly set by putParameter(java.lang.Object, java.lang.Object).
 java.lang.Object getParameter(java.lang.Object name, java.lang.Object defaultValue)
          Gets any parameters that may have been specified by a call to ActionCommandExecutor.execute(Map) or that have been explicitly set by putParameter(java.lang.Object, java.lang.Object).
 java.util.Map<java.lang.Object,java.lang.Object> getParameters()
          Gets all the parameters that have been specified by a call to ActionCommandExecutor.execute(Map) or that have been explicitly set by putParameter(java.lang.Object, java.lang.Object).
protected abstract  void handleExecute()
          Main entry point for command subclasses that must be implemented to provide command specific behaviour.
 void installShortCut(javax.swing.JComponent component, int condition)
          Installs a shortcut into the components input and action maps using the accelerator specified by the default face.
 void installShortCut(javax.swing.JComponent component, java.lang.String faceContext, int condition)
          Installs a shortcut into the components input and action maps using the accelerator of the specified face.
protected  void postExecute()
          This method is called after handleExecute() has been called.
protected  boolean preExecute()
          This method is called prior to handleExecute() being called.
 void putParameter(java.lang.Object key, java.lang.Object value)
          Adds the specified parameter to be available the next time ActionCommandExecutor.execute(java.util.Map) is called.
 void putParameters(java.util.Map<?,?> parameters)
          Adds the specified paramters to be available the next time ActionCommandExecutor.execute(java.util.Map) is called.
 void removeActionCommandListener(ActionCommandListener listener)
          Removes the specified listener from the command
 void removeInterceptor(ActionCommandInterceptor interceptor)
          Removes the specified interceptor from the command.
 void requestDefaultIn(javax.swing.RootPaneContainer container)
          This method will find the first button from this command that is a decendant of the specified RootPaneContainer and configure it as the default button by calling JRootPane.setDefaultButton(javax.swing.JButton).
protected  void unbindFromContainer(CommandContainer container)
          Invoked to unbind this instance to the specified container.
 void uninstallShortCut(javax.swing.JComponent component, int condition)
          Removes the short cut installed by a previous call to installShortCut(JComponent, int)
 void uninstallShortCut(javax.swing.JComponent component, java.lang.String faceContext, int condition)
          Removes the short cut installed by a previous call to installShortCut(JComponent, String, int)
 
Methods inherited from class com.pietschy.command.Command
addContainerPropertyListener, addFace, addHoverListener, addNotify, addPropertyChangeListener, addPropertyChangeListener, attach, bind, bind, bind, buttonIterator, configureAppearance, configureAppearances, configureButtonAppearances, configureButtonStates, configureButtonStates, createButton, createButton, createButton, createButton, createComponent, createMenuItem, createMenuItem, createMenuItem, createMenuItem, detach, faceExists, findBestFace, fireHoverEnded, fireHoverStarted, fireIndexedPropertyChange, fireIndexedPropertyChange, fireIndexedPropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getAlternativeFaceContexts, getButtonFactory, getButtonIn, getCommandContainer, getContainerProperty, getContainerPropertySupport, getDefaultFace, getDefaultFace, getFace, getFace, getId, getMenuFactory, getProperty, getProperty, getPropertyNames, getToolbarFactory, isAnonymous, isAttachedTo, isBound, isEnabled, isVisible, loadConfiguration, notifyCommandContainerHierarchyChanged, putProperties, putProperty, rebind, removeContainerPropertyListener, removeHoverListener, removeNotify, removePropertyChangeListener, removePropertyChangeListener, requestFocusIn, setButtonFactory, setEnabled, setMenuFactory, setToolbarFactory, setVisible, toString, unbind, validateId
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface com.pietschy.command.ActionCommandExecutor
addPropertyChangeListener, addPropertyChangeListener, isEnabled, removePropertyChangeListener, removePropertyChangeListener
 
Methods inherited from interface com.pietschy.command.Identifiable
getId
 

Field Detail

PARAMETER_ACTION_EVENT

public static final java.lang.String PARAMETER_ACTION_EVENT
The key for the action event hint. This hint will be present when ever the command is invoked from an attached AbstractButton.

See Also:
Constant Field Values

PARAMETER_MODIFIERS

public static final java.lang.String PARAMETER_MODIFIERS
The key for the modifiers hint. This hint will be present when ever the command is invoked from an attached AbstractButton.

See Also:
getModifiers(), Constant Field Values

PARAMETER_INVOKER

public static final java.lang.String PARAMETER_INVOKER
The key for the invoker hint. This hint will be present when ever the command is invoked from an attached AbstractButton.

See Also:
getInvoker(), Constant Field Values

PARAMETER_INVOKER_WINDOW

public static final java.lang.String PARAMETER_INVOKER_WINDOW
The key for the invoker window hint. This hint will be present whenever the a Window parent can be found from the invoker.

See Also:
getInvokerWindow(), Constant Field Values
Constructor Detail

ActionCommand

public ActionCommand()
Creates a new anonymous instance. Anonymous commands must be programmatically configured and can only be added to groups using GroupBuilders.


ActionCommand

public ActionCommand(java.lang.String id)
Creates a new instance with the specified id.


ActionCommand

protected ActionCommand(java.lang.String id,
                        boolean loadConfiguration)
Creates a new command with the specified id.

Parameters:
loadConfiguration - true to load the configuration during construction, false to let the subclass invoke it.
Method Detail

bindToContainer

protected void bindToContainer(CommandContainer container)
Invoked to bind this instance to the specified container. This method will add itself to the container if Command.isAnonymous() is false.

Subclasses may override this method to perform additional configuration such as adding a listener to the container. In this case subclasses must also override unbindFromContainer(CommandContainer).

Specified by:
bindToContainer in class Command
Parameters:
container - the container to bind to.
See Also:
unbindFromContainer(CommandContainer)

unbindFromContainer

protected void unbindFromContainer(CommandContainer container)
Invoked to unbind this instance to the specified container. This method will remove itself to the container if Command.isAnonymous() is false.

Specified by:
unbindFromContainer in class Command
Parameters:
container - the container to unbind from.
See Also:
bindToContainer(CommandContainer)

createButton

public javax.swing.AbstractButton createButton(java.util.Map<?,?> parameters)
Creates a parameterized button that will always invoke the commad with the specified parameters.

Parameters:
parameters - the parameters to use when invoking the command from this button.
Returns:
a new button.

createButton

public javax.swing.AbstractButton createButton(java.lang.String context,
                                               java.util.Map<?,?> parameters)
Creates a parameterized button that will always invoke the commad with the specified parameters.

Parameters:
context - the face context to use for the button.
parameters - the parameters to use when invoking the command from this button.
Returns:
a new button.

createButton

public javax.swing.AbstractButton createButton(ButtonFactory factory,
                                               java.util.Map<?,?> parameters)
Creates a parameterized button that will always invoke the commad with the specified parameters.

Parameters:
factory - the factory to use when creating the button.
parameters - the parameters to use when invoking the command from this button.
Returns:
a new button.

createButton

public javax.swing.AbstractButton createButton(ButtonFactory factory,
                                               java.lang.String context,
                                               java.util.Map<?,?> parameters)
Creates a parameterized button that will always invoke the commad with the specified parameters.

Parameters:
factory - the factory to use when creating the button.
context - the face context to use for the button.
parameters - the parameters to use when invoking the command from this button.
Returns:
a new button.

createMenuItem

public javax.swing.JMenuItem createMenuItem(java.util.Map<?,?> parameters)
Creates a parameterized menu item that will always invoke the commad with the specified parameters.

Parameters:
parameters - the parameters to use when invoking the command from this button.
Returns:
a new menu item.

createMenuItem

public javax.swing.JMenuItem createMenuItem(java.lang.String context,
                                            java.util.Map<?,?> parameters)
Creates a parameterized menu item that will always invoke the commad with the specified parameters.

Parameters:
context - the face context to use for the menu item.
parameters - the parameters to use when invoking the command from this button.
Returns:
a new menu item.

createMenuItem

public javax.swing.JMenuItem createMenuItem(MenuFactory factory,
                                            java.util.Map<?,?> parameters)
Creates a parameterized menu item that will always invoke the commad with the specified parameters.

Parameters:
factory - the factory to use when creating the menu item.
parameters - the parameters to use when invoking the command from this button.
Returns:
a new menu item.

createMenuItem

public javax.swing.JMenuItem createMenuItem(MenuFactory factory,
                                            java.lang.String context,
                                            java.util.Map<?,?> parameters)
Creates a parameterized menu item that will always invoke the commad with the specified parameters.

Parameters:
factory - the factory to use when creating the menu item.
context - the face context to use for the menu item.
parameters - the parameters to use when invoking the command from this button.
Returns:
a new menu item.

handleExecute

protected abstract void handleExecute()
Main entry point for command subclasses that must be implemented to provide command specific behaviour.

This method should never be called directly to invoke a command. All command invocation must be performed using the execute() and execute(Map) methods.


execute

public final void execute(java.util.Map<java.lang.Object,java.lang.Object> parameters)
Executes this command with the specified parameters. The parameter are added to any that have been previously configured using putParameter(java.lang.Object, java.lang.Object). The paramters are only available for this execution of the command.

Specified by:
execute in interface ActionCommandExecutor
Parameters:
parameters - the paramters this command is to use.
See Also:
putParameter(java.lang.Object, java.lang.Object), getParameter(java.lang.Object)

execute

public final void execute()
Causes the command to perform it's operation. Subclasses must implement handleExecute() to customize this commands behaviour.


requestDefaultIn

public void requestDefaultIn(javax.swing.RootPaneContainer container)
This method will find the first button from this command that is a decendant of the specified RootPaneContainer and configure it as the default button by calling JRootPane.setDefaultButton(javax.swing.JButton).

Parameters:
container - the root pane container to check.

putParameter

public void putParameter(java.lang.Object key,
                         java.lang.Object value)
Adds the specified parameter to be available the next time ActionCommandExecutor.execute(java.util.Map) is called.

Parameters:
key - the parameter name.
value - the parameter value.

putParameters

public void putParameters(java.util.Map<?,?> parameters)
Adds the specified paramters to be available the next time ActionCommandExecutor.execute(java.util.Map) is called.

Parameters:
parameters - the parameters to add.

getParameter

public java.lang.Object getParameter(java.lang.Object key)
Gets any paramters that may have been specified by a call to ActionCommandExecutor.execute(Map) or that have been explicitly set by putParameter(java.lang.Object, java.lang.Object).

Parameters:
key - the name of the paramter.
Returns:
the parameter value or null if the paramter hasn't been specified.

getParameter

public java.lang.Object getParameter(java.lang.Object name,
                                     java.lang.Object defaultValue)
Gets any parameters that may have been specified by a call to ActionCommandExecutor.execute(Map) or that have been explicitly set by putParameter(java.lang.Object, java.lang.Object).

Parameters:
name - the name of the paramter.
defaultValue - the default value to return if the parameter was null.
Returns:
the parameter value or defaultValue if the parameter was null.
See Also:
putParameter(java.lang.Object, java.lang.Object)

getParameters

public java.util.Map<java.lang.Object,java.lang.Object> getParameters()
Gets all the parameters that have been specified by a call to ActionCommandExecutor.execute(Map) or that have been explicitly set by putParameter(java.lang.Object, java.lang.Object).

Returns:
all the parameters configured for the current execution.
See Also:
putParameter(java.lang.Object, java.lang.Object)

getModifiers

public int getModifiers()
Convenience method to get any modifiers that were specified. Modifiers are always copied from any action event that triggers this command.


getInvoker

public java.lang.Object getInvoker()
Convenience method to get the object that invoked the command. If the command was invoked from from a button (or menu) then the invoker will be that button.

Returns:
the AbstractButton that invoked to command. If the command was manually invoked this will return null unless the parameter PARAMETER_INVOKER has been explicitly set.

getInvokerWindow

public java.awt.Window getInvokerWindow()
Convenience method to get the Window ancestor of the object that invoked the command. If the invoker is null, or doesn't descend from Component then null is returned. Otherwise, an attempt to find the Window ancestor is made using the current WindowSearchStrategy.

Returns:
null if the invoker is null, doesn't extend Component or doesn't have a Window ancestor. Otherwise the invokers Window ancestor is returned acording to the current WindowSearchStrategy.
See Also:
getInvoker()

getActionEvent

public java.awt.event.ActionEvent getActionEvent()
Convenience method for getParameter(ActionCommand.PARAMETER_ACTION_EVENT).


doButtonAttachments

protected void doButtonAttachments(javax.swing.AbstractButton button,
                                   java.lang.String faceName)
Overrides the default implementation to also add an ActionListener to the button.

Overrides:
doButtonAttachments in class Command
Parameters:
button - the button to attach to.
faceName - the face the button will be using.

doButtonDetachments

protected void doButtonDetachments(javax.swing.AbstractButton button)
Overrides the default implementation to remove the ActionListener installed by doButtonAttachments(AbstractButton, String).

Overrides:
doButtonDetachments in class Command
Parameters:
button - the button to detach from.

getActionAdapter

public javax.swing.Action getActionAdapter()
Gets an action that mirrors the default face of this command.

Returns:
an Action that mirrors the default face.

getActionAdapter

public javax.swing.Action getActionAdapter(java.lang.String context)
Gets an action that mirrors this the specified face of this command.

Parameters:
context - the face context to base the action on. The Actions properties will mirror those of the specified face.
Returns:
an action the mirrors the specified face.

preExecute

protected boolean preExecute()
This method is called prior to handleExecute() being called. It invokes all the ActionCommandInterceptors and notifies all the ActionCommandListeners

Returns:
true if all the interceptors returned true, false otherwise.

postExecute

protected void postExecute()
This method is called after handleExecute() has been called. It invokes all the ActionCommandInterceptors and notifies all the ActionCommandListeners.


addActionCommandListener

public void addActionCommandListener(ActionCommandListener listener)
Adds the specified listener to the command. The listener will be notified before and after the command is executed.

Parameters:
listener - the listener to add.
See Also:
removeActionCommandListener(com.pietschy.command.ActionCommandListener)

removeActionCommandListener

public void removeActionCommandListener(ActionCommandListener listener)
Removes the specified listener from the command

Parameters:
listener - the listener to remove
See Also:
addActionCommandListener(com.pietschy.command.ActionCommandListener)

addInterceptor

public void addInterceptor(ActionCommandInterceptor interceptor)
Adds the specified interceptor to the command. The interceptor will be invoked before and after the command is executed.

Parameters:
interceptor - the interceptor to add.
See Also:
removeInterceptor(ActionCommandInterceptor)

removeInterceptor

public void removeInterceptor(ActionCommandInterceptor interceptor)
Removes the specified interceptor from the command.

Parameters:
interceptor - the interceptor to remove.
See Also:
addInterceptor(ActionCommandInterceptor)

installShortCut

public void installShortCut(javax.swing.JComponent component,
                            int condition)
Installs a shortcut into the components input and action maps using the accelerator specified by the default face.

Parameters:
component - The component to install the short cut in.
condition - The condition as per JComponent.getInputMap(int).

installShortCut

public void installShortCut(javax.swing.JComponent component,
                            java.lang.String faceContext,
                            int condition)
Installs a shortcut into the components input and action maps using the accelerator of the specified face.

Parameters:
component - The component to install the short cut in.
faceContext - The face that defines the required accelerator.
condition - The condition as per JComponent.getInputMap(int).

uninstallShortCut

public void uninstallShortCut(javax.swing.JComponent component,
                              int condition)
Removes the short cut installed by a previous call to installShortCut(JComponent, int)

Parameters:
component - The component the short cut was installed on.
condition - The condition as per JComponent.getInputMap(int).

uninstallShortCut

public void uninstallShortCut(javax.swing.JComponent component,
                              java.lang.String faceContext,
                              int condition)
Removes the short cut installed by a previous call to installShortCut(JComponent, String, int)

Parameters:
component - The component the short cut was installed on.
condition - The condition as per JComponent.getInputMap(int).


Copyright © 2006 - 2007 Andrew Pietsch