com.pietschy.command
Class CommandContainer

java.lang.Object
  extended by com.pietschy.command.CommandContainer
All Implemented Interfaces:
DelegateProvider

public class CommandContainer
extends java.lang.Object
implements DelegateProvider

CommandContainers are the central means by which CommandGroups discover their members.

Each container holds a collection of ActionCommands and CommandGroups. Each container acts as it's own unique namespace for the commands it contains. This allows multiple instances of the same command to exist within a given application. For example, each frame would have its own container allowing two frames to co-exists without any change to the application. The same concept can be applied to duplicated components within the application.

Each container can have a parent specified allowing it to access commands defined anywhere within the parent heirarchy. The special globalInstance() is provided for application global commands. CommandGroups can access commands bound to thier container, or any parent container in the hierarchy.

The library supports two binding approaches, direct binding and component binding. Direct binding binds each command to a specific container. With component binding, commands find their containers based on the swing component heirachy. In this case both the container and the command must be bound to a component. The following example shows a container bound to the main frame and a command bound to a panel within the frame.

   // create the main frame.
   JFrame mainFrame = ..
   CommandContainer container = new CommandContainer();
   container.bind(mainFrame);

   // create the component.
   JPanel myPanel = ...;
   ActionCommand command = new ActionCommand("save") {...}
   command.bind(myPanel);

   // add them together.  At this point the command will
   // automatically search the heirarchy and find the container
   // bound to mainFrame.
   mainFrame.getContentPane().add(myPanel);
 
CommandContainers also provide a property mechanism to distribute application specific data to all commands withing the heirarchy. Examples include setGlassPaneStrategy(GlassPaneStrategy) and setDelegateMediator(DelegateMediator). Applications can also provide their own data using putProperty(String, Object).


Field Summary
(package private) static CommandContainerBindings bindingRegistry
           
(package private)  CommandContainerListener parentListener
           
static java.lang.String PROPERTY_DELEGATE_MEDIATOR
           
static java.lang.String PROPERTY_GLASS_PANE_STRATEGY
           
static java.lang.String PROPERTY_UNDO_CONTEXT
           
 
Constructor Summary
CommandContainer()
          Creates a new insteance.
CommandContainer(CommandContainer parentContainer)
          Creates a new instance with the specifed parent conatiner.
 
Method Summary
 void add(ActionCommand command)
          Adds the specified command to the container.
 void add(ActionCommandDelegate delegate)
          Adds the specified delegate to the container.
 void add(CommandGroup group)
          Adds the specified group to the container.
 void addCommandContainerListener(CommandContainerListener listener)
          Adds the specified listener.
 void bind(java.awt.Component component)
          Binds this conatiner to the specified component.
(package private)  void checkReservedKeys(java.lang.String key)
           
 void debugParents(java.io.PrintWriter w)
          Dumps this containers parent heirarchy the specified writer for debug purposes.
protected  void debugState(com.pietschy.command.CommandContainer.DebugWriter writer)
          Dumps this containers state to the specified writer.
 void debugState(java.io.OutputStream stream)
          Dumps this containers state to the specified output stream for debug purposes.
 void debugState(java.io.PrintWriter w)
          Dumps this containers state to the specified writer for debug purposes.
 Command findCommand(java.lang.String id)
          Searches the container heirarchy for the command with the specified id.
protected  void fireCommandAdded(CommandContainer container, Command command)
          Fires CommandContainerListener.commandAdded(CommandContainerEvent).
protected  void fireCommandRemoved(CommandContainer container, Command commmand)
          Fires CommandContainerListener.commandRemoved(CommandContainerEvent).
protected  void fireParentHierarchyChanged()
          Fires CommandContainerListener.parentHierarchyChanged(CommandContainerEvent).
protected  void firePropertyChanged(java.beans.PropertyChangeEvent event)
          Fires CommandContainerListener.parentHierarchyChanged(CommandContainerEvent) with the specified event.
protected  void firePropertyChanged(java.lang.String key, java.lang.Object oldValue, java.lang.Object newValue)
          Fires CommandContainerListener.containerPropertyChanged(PropertyChangeEvent).
 ActionCommand getActionCommand(java.lang.String id)
          Gets the command with the specified id from the container.
 ActionCommandExecutor getActionCommandExecutor(java.lang.String id)
          Default implementation of DelegateProvider.
 java.awt.Component getBoundComponent()
          Gets the component this container is bound to, or null if the container isn't bound.
 CommandGroup getCommandGroup(java.lang.String id)
          Gets the group with the specified id from the container.
static CommandContainer getContainerFor(java.awt.Component c)
           
 ActionCommandDelegate getDelegate(java.lang.String id)
          Gets the delegate with the specified id from the container.
 DelegateMediator getDelegateMediator()
          Gets the first delegate mediator found in the container heirarchy.
 GlassPaneStrategy getGlassPaneStrategy()
          Gets the first glass pane strategy found in the container heirarchy.
 CommandContainer getParentContainer()
          Gets this conainers parent or null if it doesn't have one.
 java.lang.Object getProperty(java.lang.String propertyName)
          Gets the first property with the specified name found in the container heirarchy.
 UndoContext getUndoContext()
          Gets the first undo context found in the container heirarchy.
static CommandContainer globalInstance()
          Gets the global command conainer instance.
protected  CommandGroup instantiateGroup(java.lang.String id)
          Invoked by findCommand(String) if and only if the command id represents a group, the group can't be found in the parent heirarchy, and the group has been specified as "autoCreate".
 void putProperty(java.lang.String propertyName, java.lang.Object value)
          Sets the specified property on the container and notifies all listeners.
(package private)  void putPropertyInternal(java.lang.String key, java.lang.Object value)
           
 void remove(ActionCommand command)
          Removes the specified group from the container.
 void remove(ActionCommandDelegate delegate)
          Removes the specified delegate from the container.
 void remove(CommandGroup group)
          Removes the specified group from the container.
 void removeCommandContainerListener(CommandContainerListener listener)
          Removes the specified listener.
 void setDelegateMediator(DelegateMediator delegateMediator)
          Sets this containers delegate mediator and notifies all listeners.
 void setGlassPaneStrategy(GlassPaneStrategy glassPaneStrategy)
          Sets this containers glass pane strategy and notifies all listeners.
 void setParentCommandContainer(CommandContainer container)
          Sets this containers parent.
 void setUndoContext(UndoContext undoContext)
          Sets this containers undo context and notifies all listeners.
 void unbind()
          Unbinds from the component previously bound using bind(Component).
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

PROPERTY_GLASS_PANE_STRATEGY

public static final java.lang.String PROPERTY_GLASS_PANE_STRATEGY
See Also:
Constant Field Values

PROPERTY_DELEGATE_MEDIATOR

public static final java.lang.String PROPERTY_DELEGATE_MEDIATOR
See Also:
Constant Field Values

PROPERTY_UNDO_CONTEXT

public static final java.lang.String PROPERTY_UNDO_CONTEXT
See Also:
Constant Field Values

bindingRegistry

static CommandContainerBindings bindingRegistry

parentListener

CommandContainerListener parentListener
Constructor Detail

CommandContainer

public CommandContainer()
Creates a new insteance.


CommandContainer

public CommandContainer(CommandContainer parentContainer)
Creates a new instance with the specifed parent conatiner.

Parameters:
parentContainer - the parent container
Method Detail

globalInstance

public static CommandContainer globalInstance()
Gets the global command conainer instance.

Returns:
the global command conainer instance.

getContainerFor

public static CommandContainer getContainerFor(java.awt.Component c)

getParentContainer

public CommandContainer getParentContainer()
Gets this conainers parent or null if it doesn't have one.

Returns:
this conainers parent or null if it doesn't have one.

setParentCommandContainer

public void setParentCommandContainer(CommandContainer container)
Sets this containers parent. Once configured all CommandContainerListeners will be notfed that the container heirarchy has changed.

Parameters:
container - the new parent container.

bind

public void bind(java.awt.Component component)
Binds this conatiner to the specified component. Commands bound to children of the component will be automatically added to this container.

Parameters:
component - the component to bind to.
See Also:
Command.bind(Component)

unbind

public void unbind()
Unbinds from the component previously bound using bind(Component). All commands that have been bount to this container using Command.bind(Component) will search for a new command container in the swing heirarchy.


getBoundComponent

public java.awt.Component getBoundComponent()
Gets the component this container is bound to, or null if the container isn't bound.

Returns:
the component this container is bound to, or null if the container isn't bound.

setDelegateMediator

public void setDelegateMediator(DelegateMediator delegateMediator)
Sets this containers delegate mediator and notifies all listeners.

Parameters:
delegateMediator - the delegate mediator.

getDelegateMediator

public DelegateMediator getDelegateMediator()
Gets the first delegate mediator found in the container heirarchy.

Returns:
the first delegate mediator found in the container heirarchy or null if mediator is in the current hierarchy.

setGlassPaneStrategy

public void setGlassPaneStrategy(GlassPaneStrategy glassPaneStrategy)
Sets this containers glass pane strategy and notifies all listeners.

Parameters:
glassPaneStrategy - the glass pane strategy.

getGlassPaneStrategy

public GlassPaneStrategy getGlassPaneStrategy()
Gets the first glass pane strategy found in the container heirarchy.

Returns:
the first glass pane strategy found in the container heirarchy or null if no strategy is defined in the current hierarchy.

setUndoContext

public void setUndoContext(UndoContext undoContext)
Sets this containers undo context and notifies all listeners.

Parameters:
undoContext - the undo context.

getUndoContext

public UndoContext getUndoContext()
Gets the first undo context found in the container heirarchy.

Returns:
the first undo context found in the container heirarchy or null if no context is defined in the current hierarchy. .

putProperty

public void putProperty(java.lang.String propertyName,
                        java.lang.Object value)
                 throws ReservedPropertyException
Sets the specified property on the container and notifies all listeners.

This method will throw a ReservedPropertyException if the property name is PROPERTY_DELEGATE_MEDIATOR, PROPERTY_GLASS_PANE_STRATEGY or PROPERTY_UNDO_CONTEXT.

Parameters:
propertyName - the property name
value - the property value
Throws:
ReservedPropertyException

getProperty

public java.lang.Object getProperty(java.lang.String propertyName)
Gets the first property with the specified name found in the container heirarchy.

Parameters:
propertyName - the property name to retrieve.
Returns:
the first property with the specified name found in the container heirarchy or null if the property doesn't exist.

checkReservedKeys

void checkReservedKeys(java.lang.String key)

putPropertyInternal

void putPropertyInternal(java.lang.String key,
                         java.lang.Object value)

add

public void add(ActionCommand command)
Adds the specified command to the container. Normally this is automatically handled by the binding process.

Parameters:
command - the command to add.

add

public void add(CommandGroup group)
Adds the specified group to the container. Normally this is automatically handled by the binding process.

Parameters:
group - the group to add.

add

public void add(ActionCommandDelegate delegate)
Adds the specified delegate to the container. Normally this is automatically handled by the binding process.

Parameters:
delegate - the delegate to add.

remove

public void remove(ActionCommand command)
Removes the specified group from the container. Normally this is automatically handled by the binding process.

Parameters:
command - the group to remove.

remove

public void remove(CommandGroup group)
Removes the specified group from the container. Normally this is automatically handled by the binding process.

Parameters:
group - the group to remove.

remove

public void remove(ActionCommandDelegate delegate)
Removes the specified delegate from the container. Normally this is automatically handled by the binding process.

Parameters:
delegate - the delegate to remove.

getCommandGroup

public CommandGroup getCommandGroup(java.lang.String id)
Gets the group with the specified id from the container. Returns null if the group is not bound to the container.

Parameters:
id - the group id.
Returns:
the group with the specified id, or null if the group isn't bound to the container.

getActionCommand

public ActionCommand getActionCommand(java.lang.String id)
Gets the command with the specified id from the container. Returns null if the command is not bound to the container.

Parameters:
id - the command id.
Returns:
the command with the specified id, or null if the command isn't bound to the container.

getDelegate

public ActionCommandDelegate getDelegate(java.lang.String id)
Gets the delegate with the specified id from the container. Returns null if the delegate is not bound to the container.

Parameters:
id - the delegate id.
Returns:
the delegate with the specified id, or null if the delegate isn't bound to the container.

findCommand

public Command findCommand(java.lang.String id)
Searches the container heirarchy for the command with the specified id. It will return either an ActionCommand or CommandGroup.

If a group id is specifed, the group isn't found in the parent hierarchy, and the group is configured as autoCreate=true then this container will automatically instantiate the group, bind it to this container and return it.

Parameters:
id - the command id.
Returns:
the command or group with the specified id.

getActionCommandExecutor

public ActionCommandExecutor getActionCommandExecutor(java.lang.String id)
Default implementation of DelegateProvider.

Specified by:
getActionCommandExecutor in interface DelegateProvider
Parameters:
id - the id of interest.
Returns:
the ActionCommandDelegate with the specified id or if null the ActionCommand with the specified id. Null if neither are found.

instantiateGroup

protected CommandGroup instantiateGroup(java.lang.String id)
Invoked by findCommand(String) if and only if the command id represents a group, the group can't be found in the parent heirarchy, and the group has been specified as "autoCreate".

This method will check if a className has been specified in the configuration and will attempt to create an instance of that type. The class must have a public constructor that takes a single string argument for the group id.

Parameters:
id - the group id.
Returns:
a new group with the specified id.

addCommandContainerListener

public void addCommandContainerListener(CommandContainerListener listener)
Adds the specified listener.

Parameters:
listener - the listener to add.

removeCommandContainerListener

public void removeCommandContainerListener(CommandContainerListener listener)
Removes the specified listener.

Parameters:
listener - the listener to remove.

fireParentHierarchyChanged

protected void fireParentHierarchyChanged()
Fires CommandContainerListener.parentHierarchyChanged(CommandContainerEvent).


fireCommandAdded

protected void fireCommandAdded(CommandContainer container,
                                Command command)
Fires CommandContainerListener.commandAdded(CommandContainerEvent).


fireCommandRemoved

protected void fireCommandRemoved(CommandContainer container,
                                  Command commmand)
Fires CommandContainerListener.commandRemoved(CommandContainerEvent).


firePropertyChanged

protected void firePropertyChanged(java.lang.String key,
                                   java.lang.Object oldValue,
                                   java.lang.Object newValue)
Fires CommandContainerListener.containerPropertyChanged(PropertyChangeEvent).


firePropertyChanged

protected void firePropertyChanged(java.beans.PropertyChangeEvent event)
Fires CommandContainerListener.parentHierarchyChanged(CommandContainerEvent) with the specified event.


debugState

public void debugState(java.io.PrintWriter w)
Dumps this containers state to the specified writer for debug purposes.

Parameters:
w - the write to use.

debugState

public void debugState(java.io.OutputStream stream)
Dumps this containers state to the specified output stream for debug purposes.

Parameters:
stream - the output stream to use.

debugParents

public void debugParents(java.io.PrintWriter w)
Dumps this containers parent heirarchy the specified writer for debug purposes.

Parameters:
w - the write to use.

debugState

protected void debugState(com.pietschy.command.CommandContainer.DebugWriter writer)
Dumps this containers state to the specified writer.

Parameters:
writer - the writer to use.


Copyright © 2006 - 2007 Andrew Pietsch