Download 1.2
Latest Release:
June 05, 2008

Documentation:

General: Architecture: Components:

Actions and Singletons

The real work in a YASL application takes place in the action and singleton classes. In the Model-View-Controller pattern, actions handle user-driven events—acting as the "Controller," while singletons hold and manipulate data—acting as the "Model." The actions and singletons are stored in separate maps in key-class pairs.

Base Action Classes

Action classes handle user-driven events, such as menu selections and button clicks. Action classes for desktop applications will extend YASLSwingAbstractAction (from org.yasl.arch.impl.action). The complete lineage for an action class follows this path: 

AbstractAction (from javax.swing)
   YASLGUIAbstractAction (from org.yasl.arch.impl.action)
      YASLSwingAbstractAction (from org.yasl.arch.impl.action)
         YourActionClass

Most of the action classes that developers create will implement the following:

  1. a constructor that calls a parent constructor
  2. the performAction method (an abstract method defined in YASLGUIAbstractAction)

From the performAction method, developers have access to the application instance as a YASLApplication, YASLGUIApplication, or YASLSwingApplication instance. The API for the application instance provides access to the application's singletons and JFrame instance. The performAction method is called from the actionPerformed method implemented in YASLGUIAbstractAction. The call to performAction can be made synchronously or asynchronously. The default method is asynchronous in which the performAction call is wrapped in a Runnable instance that is queued on the event dispatching thread. To signal a synchronous call, set the action command for the event to YASLGUIAbstractAction.COMMAND_SYNCHRONOUS_CALL. 

/**
 * Abstract method that is called from the
 * actionPerformed method. Extending classes must 
 * implement their action specific code in this method.
 *
 * @param e ActionEvent
 * @throws Exception
 */
protected abstract void performAction(ActionEvent e)
        throws Exception;

/**
 * A command string that signals the call to the action's method
 * should be synchronous instead of the default asynchronous call.
 */
public static final String COMMAND_SYNCHRONOUS_CALL = "synchronous_call";

/**
 * Creates a Runnable object that wraps a call to
 * performAction. The runnable object is started with a 
 * call to invokeLater (from javax.swing.SwingUtilities).
 *
 * @see java.lang.Runnable
 *
 * @param e ActionEvent
 */
public final void actionPerformed(ActionEvent e) {
    final ActionEvent event = e;
    // in some special cases, we will want to do a
    // synchronous call
    // for example: the start application action is called
    // synchronously
    if (e != null &&
        COMMAND_SYNCHRONOUS_CALL.equalsIgnoreCase(e.getActionCommand())) {
        try {
            performAction(event);
        }
        catch (Exception ex) {
            yaslApplication.getErrorHandler().handleAppError(ex);
        }
    }
    // do the standard asynchronous call
    else {
        Runnable runner = new Runnable() {
            public void run() {
                try {
                    performAction(event);
                }
                catch (Exception ex) {
                    yaslApplication.getErrorHandler().handleAppError(ex);
                }
            }
        };
        SwingUtilities.invokeLater(runner);
    }
}

YASLGUIAbstractAction API

The public and protected API for YASLGUIAbstractAction is listed below. The initialState argument passed into all the constructors determines if the action is initially enabled or disabled.

/**
 * Sets the NAME and SHORT_DESCRIPTION properties to the value
 * of the name param.
 * Stores a reference to the YASLGUIApplication instance and
 * sets the action to the passed initialState.
 * 
 * @param name String
 * @param initialState boolean
 * @param yaslApp YASLGUIApplication
 */
public YASLGUIAbstractAction(String name,
                             boolean initialState,
                             YASLGUIApplication yaslApp)

/**
 * Sets the NAME and SHORT_DESCRIPTION properties to the value
 * of the name param. Also sets the SMALL_ICON property.
 * Stores a reference to the YASLGUIApplication instance and
 * sets the action to the passed initialState.
 * 
 * @param name String
 * @param initialState boolean
 * @param imageIcon ImageIcon
 * @param yaslApp YASLGUIApplication
 */
public YASLGUIAbstractAction(String name,
                             boolean initialState,
                             ImageIcon imageIcon,
                             YASLGUIApplication yaslApp)

/**
 * Sets the NAME and SHORT_DESCRIPTION properties.
 * Stores a reference to the YASLGUIApplication instance and
 * sets the action to the passed initialState.
 * 
 * @param name String
 * @param shortName String
 * @param initialState boolean
 * @param yaslApp YASLGUIApplication
 */
public YASLGUIAbstractAction(String name,
                             String shortName,
                             boolean initialState,
                             YASLGUIApplication yaslApp)

/**
 * Sets the NAME, SHORT_DESCRIPTION, and SMALL_ICON properties.
 * Stores a reference to the YASLGUIApplication instance and
 * sets the action to the passed initialState.
 *
 * @param name String
 * @param shortName String
 * @param initialState boolean
 * @param imageIcon ImageIcon
 * @param yaslApp YASLGUIApplication
 */
public YASLGUIAbstractAction(String name,
                             String shortName,
                             boolean initialState,
                             ImageIcon imageIcon,
                             YASLGUIApplication yaslApp)

/**
 * Sets the NAME and SHORT_DESCRIPTION properties to the
 * param value.
 *
 * @param name String
 */
public void setName(String name)

/**
 * Sets the NAME and SHORT_DESCRIPTION properties to the
 * respective param values.
 *
 * @param name String
 * @param shortName String
 */
public void setName(String name,
                    String shortName)

/**
 * Returns the NAME property.
 *
 * @return String
 */
public String getName()

/**
 * Resets the action to its initial state.
 */
public void setToInitialState()

/**
 * Returns the initial state.
 *
 * @return boolean
 */
public boolean getInitialState()

/**
 * Returns the application object as a YASLApplication instance.
 *
 * @return YASLApplication
 */
protected YASLApplication getYASLApplication()

/**
 * Returns the application object as a YASLGUIApplication instance.
 *
 * @return YASLGUIApplication
 */
protected YASLGUIApplication getYASLGUIApplication()

YASLSwingAbstractAction API

The public and protected API for YASLSwingAbstractAction is listed below. YASLSwingAbstractAction stores and provides access to the YASLSwingApplication instance. All other functionality is inherited from the parent class.

/**
 * Sets the NAME and SHORT_DESCRIPTION properties to the value
 * of the name param.
 * Stores a reference to the YASLSwingApplication instance and
 * sets the action to the passed initialState.
 *
 * @param name String
 * @param initialState boolean
 * @param yaslApp YASLSwingApplication
 */
public YASLSwingAbstractAction(String name,
                               boolean initialState,
                               YASLSwingApplication yaslApp)

/**
 * Sets the NAME and SHORT_DESCRIPTION properties to the value
 * of the name param. Also sets the SMALL_ICON property.
 * Stores a reference to the YASLSwingApplication instance and
 * sets the action to the passed initialState.
 *
 * @param name String
 * @param initialState boolean
 * @param imageIcon ImageIcon
 * @param yaslApp YASLSwingApplication
 */
public YASLSwingAbstractAction(String name,
                               boolean initialState,
                               ImageIcon imageIcon,
                               YASLSwingApplication yaslApp)

/**
 * Sets the NAME and SHORT_DESCRIPTION properties.
 * Stores a reference to the YASLSwingApplication instance and
 * sets the action to the passed initialState.
 *
 * @param name String
 * @param shortName String
 * @param initialState boolean
 * @param yaslApp YASLSwingApplication
 */
public YASLSwingAbstractAction(String name,
                               String shortName,
                               boolean initialState,
                               YASLSwingApplication yaslApp)

/**
 * Sets the NAME, SHORT_DESCRIPTION, and SMALL_ICON properties.
 * Stores a reference to the YASLSwingApplication instance and
 * sets the action to the passed initialState.
 *
 * @param name String
 * @param shortName String
 * @param initialState boolean
 * @param imageIcon ImageIcon
 * @param yaslApp YASLSwingApplication
 */
public YASLSwingAbstractAction(String name,
                               String shortName,
                               boolean initialState,
                               ImageIcon imageIcon,
                               YASLSwingApplication yaslApp)

/**
 * Returns the application object as a YASLSwingApplication instance.
 *
 * @return YASLSwingApplication
 */
protected YASLSwingApplication getYASLSwingApplication()

YASLSwingAbstractStartAction

This abstract class adds methods to handle events for the splash page. The splash page class implements the YASLAppLoadingListener interface. The methods and implementations for YASLSwingAbstractStartAction are listed below.

public YASLSwingAbstractStartAction(YASLSwingApplication yaslApp) {
    super("app start", true, yaslApp);
}

public void addAppLoadingListener(YASLAppLoadingListener listener) {
    if(listener != null) {
        synchronized (listeners) {
            listeners.add(listener);
        }
    }
}

protected void fireAppLoadingEvent(final YASLAppLoadingEvent event) {
    int cnt = 0;
    YASLAppLoadingListener[] listenersArray = null;
    synchronized(listeners) {
        cnt = listeners.size();
        listenersArray = (YASLAppLoadingListener[])listeners.toArray(new YASLAppLoadingListener[cnt]);
    }
    for(int idx = 0; idx < cnt; idx++) {
        listenersArray[idx].handleAppLoadingEvent(event);
    }
}

Action Handler

The action handler manages a collection of action classes in a map. At present, the handler provides a wrapper and interface to the map. Future development in this area will focus on an API for enabling and disabling actions in response to application events. The action handler interface, defined in YASLActionHandler (from org.yasl.arch.action), is implemented by YASLActionHandlerImpl (from org.yasl.arch.impl.action).

The YASLActionHandler interface is listed below.

/**
 * Returns the Action associated with the passed key.
 *
 * @param actionKey String
 * @return Action
 */
public Action getActionByKey(String actionKey);

/**
 * Adds an action to the handler and associates it with the
 * passed key.
 *
 * @param actionKey String
 * @param action Action
 */
public void addActionByKey(String actionKey, Action action);

/**
 * Returns true if an action is associated with the passed key.
 *
 * @param actionKey String
 * @return boolean
 */
public boolean isKeyInUse(String actionKey);

/**
 * Returns a non-modifiable set of keys to actions.
 *
 * @return Set
 */
public Set getActionKeys();

YASLActionEvent

This event class extends ActionEvent and allows developers to pass additional information to an action class as keyed properties. The api is listed below.

public void addProperty(Object key, Object value)

public void addProperties(Map props) 

public Object getProperty(Object key)

Reserved Action Keys

The reserved action keys are defined in YASLApplication (from org.yasl.arch.application).

Singletons—Storing and Accessing

Singletons are stored in a map located in the YASLApplication instance. The map is accessed via API methods defined in the YASLApplication interface (from org.yasl.arch.application). Singletons are also stored in the map during XML configuration.

/**
 * Returns true if a singleton is mapped to the passed key.
 *
 * @param key String
 * @return boolean
 */
public boolean isSingletonMapped(String key);

/**
 * Returns a non-modifiable set of the keys used to map 
 * singletons in the application.
 *
 * @return Set
 */
public Set getSingletonKeys();

/**
 * Singletons are stored in a map with items accessed via a key. These
 * can be any type of application-specific object.
 *
 * @param key String
 * @return Object
 * @throws YASLApplicationException
 */
public Object getSingleton(String key)
        throws YASLApplicationException;

/**
 * Maps an application-specific object to a key.
 *
 * @param key String
 * @param singleton Object
 * @throws YASLApplicationException
 */
public void setSingleton(String key, Object singleton)
        throws YASLApplicationException;

The methods below are convenience methods for accessing specific singletons.

/**
 * Returns the action handler using the standard action 
 * handler key. If the action handler has not been set when
 * this method is called, the default action handler will
 * be set. 
 * 
 * For most applications the default action handler is
 * sufficient.
 *
 * @return YASLActionHandler
 */
public YASLActionHandler getActionHandler();

/**
 * Returns the resource manager using the standard resource
 * manager key. If the resource manager has not been set when
 * this method is called, a default resource manager will
 * be set.
 *
 * @return YASLResourceManager
 */
public YASLResourceManager getResourceManager();

/**
 * Returns the error handler using the standard error 
 * handler key. If the error handler has not been set when
 * this method is called, a default error handler will
 * be set.
 *
 * @return YASLErrorHandler
 */
public YASLErrorHandler getErrorHandler();

Reserved Singleton Keys

The reserved singleton keys are defined in YASLApplication (from org.yasl.arch.application). Developers should use KEY_PREFERENCES_MANAGER and KEY_RESOURCE_MANAGER when storing their preferences and resource managers. Developers should NOT store anything using KEY_APPLICATION.

    SourceForge.net Logo