Application and Frame Classes

The starting points for a YASL application (see note) are the application starter, application, and frame classes.

• Application Starter
  • yaslAppConfig.properties
  • YASLAppConfigHelper
• Application Classes
  • YASLApplication
  • YASLGUIApplication
  • YASLSwingApplication
• Frame Class
  • YASLSwingAppFrame
  • YASLSwingAppFrameImpl

---

Application Starter

All YASL desktop applications use YASLApplicationStarter as the main-class in their manifest files. YASLApplicationStarter implements the main() method to initialize, configure, and start the application. The information for initialization and configuration is drawn from various properties, xml, and java files.

The YASLApplicationStarter performs the following tasks in the following order for a Swing-type application.

1. Locates the yaslAppConfig.properties file. Typically, this file will be located at the top level of the application's classpath. Alternatively, the location of this file can be set as a system property using the yasl.app.config.file property from the command line. The system property is useful if developers want to test the application using different versions of yaslAppConfig.properties.
2. Initializes itself based on the yaslAppConfig properties. All properties can be overridden with a system property set on the command line.
3. Checks for the presense of the yasl.splash property. If it is present, YASLApplicationStarter creates the splash window, sets its size and duration, then calls the splash window's putUpSplash() method.
4. Creates an instance of YASLAppConfigHelper if one is defined with the yasl.app.config.helper property.
5. Creates an instance of YASLApplication based on the value of the yasl.app.type property. The mapping of application type to class are as follows. Swing type maps to YASLSwingApplicationImpl. Console type maps to YASLApplicationImpl. Applet type maps to YASLGUIApplicationImpl.
6. Registers the YASLApplication object just created as a singleton using the YASLApplication.KEY_APPLICATION reserved singleton key.
7. Tries to configure the application from xml config if an xml config file was mapped to the yasl.app.config property.
8. Tries to configure the application from an instance of YASLAppConfigHelper if it exists.
9. Gets an instance of a YASLSwingAbstractStartAction action using the reserved action key YASLApplication.KEY_ACTION_APPLICATION_START. If the start action object exists, YASLApplicationStarter calls the action's addAppLoadingListener() method passing the splash window as the listener. Next, YASLApplicationStarter makes a synchronous call to the action's actionPerformed() method.
10. Gets the YASLSwingApplication instance.
11. Calls getSwingAppFrame().initUI() on the YASLSwingApplication instance.
12. Calls takeDownSplash() on the splash window.
13. Calls getJFrame().setVisible(true) on the YASLSwingApplication instance.

yaslAppConfig.properties

The properties that can be set in yaslAppConfig.properties are described below. The properties marked in red are required.

yasl.app.type	Defines the type of application. The valid values are: Swing, Console, and Applet.
yasl.app.config	Fully-qualified path to the application config file. For example, /com/myapp/MyAppConfig.xml.
yasl.app.config.helper	Fully-qualified name of the class that extends YASLAppConfigHelper. For example, com.myapp.MyAppConfigHelper.
yasl.splash	Fully-qualified path to the class that extends YASLSplashImpl. For example, org.yasl.helloworld.HelloWorldSplash.
yasl.splash.duration	The minimum length of time in seconds that the splash window will appear.
yasl.splash.width	The width of the splash window.
yasl.splash.height	The height of the splash window.

YASLAppConfigHelper

Xml is the preferred method for configuring a YASL application. If xml configuration is insufficient for an application's needs, it can be augmented or replaced with code-based configuration. To use code-based configuration, an application must implement the methods from the YASLAppConfigHelper interface and associate the fully-qualified name of the class with the yasl.app.config.helper property in yaslAppConfig.properties. The methods from YASLAppConfigHelper will be called by YASLApplicationStarter after it attempts to configure using xml configuration.

The methds from the YASLAppConfigHelper interface are listed below.

/**
 * Sets actions programatically if this cannot be done
 * through xml configuration.
 *
 * @throws YASLApplicationException
 */
public void setActions(YASLApplication app)
        throws YASLApplicationException;

/**
 * Sets singletons programatically if this cannot be done
 * through xml configuration.
 *
 * @throws YASLApplicationException
 */
public void setSingletons(YASLApplication app)
        throws YASLApplicationException;

---

Application Classes

The various application interfaces and their corresponding implementations manage the actions, singletons, and other resources used by an application. They also provide some convenience methods. Developers do not need to override these classes and will interact only with the interfaces.

Diagram 1: YASLApplication Classes Hierarchy

---

YASLApplication

/**
 * 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();

/**
 * 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;

/**
 * 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();

/**
 * Sets the resource manager using the standard resource
 * manager key.
 *
 * @param rmanager YASLResourceManager
 * @throws YASLApplicationException
 */
public void setResourceManager(YASLResourceManager rmanager)
        throws YASLApplicationException;

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

/**
 * 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;

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

/**
 * Returns application type, either gui, command line,
 * or applet.
 *
 * @return YASLApplicationType
 */
public YASLApplicationType getApplicationType();

/**
 * 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();

/**
 * Returns true if the application object is fully
 * initialized. Error information will be written
 * to the errBuf.
 *
 * @param errBuf StringBuffer
 * @return boolean
 */
public boolean isInitialized(StringBuffer errBuf);

---

YASLGUIApplication

/**
 * Returns the root pane for the application.
 *
 * @return JRootPane
 */
public JRootPane getParentPane();

/**
 * Sets the glass pane for the parent pane.
 * This will prevent the handling of mouse events.
 */
public void setGlassPane();

/**
 * Unsets the glass pane.
 */
public void unsetGlassPane();

---

YASLSwingApplication

/**
 * Returns the YASLSwingAppFrame instance associated with
 * this application.
 *
 * @return YASLSwingAppFrame
 */
public YASLSwingAppFrame getSwingAppFrame();

/**
 * Returns the JFrame associated with this Swing application.
 * @return JFrame
 */
public JFrame getJFrame();

/**
 * Changes the cursor to the wait cursor.
 */
public void setWaitCursor();

/**
 * Restores the cursor to the non-wait cursor.
 */
public void restoreCursor();

---

Frame Class

The frame class extends org.yasl.arch.impl.application.YASLSwingAppFrameImpl and is primarily responsible for handling menu initialization. The menu details are coded in an xml config file (see XML Config for Menus for detailed information) while the work of reading the config file is handled by the parent class (YASLSwingAppFrameImpl). The frame class need only pass the xml config file to its parent's constructor. Other tasks include:

1. Setting the title bar text.
2. Initializing the frame's display.
3. Setting the menu bar.

These tasks are handled in the initUI(Map menuBarMap, Map menuMap) method. This is an abstract method in YASLSwingAppFrameImpl so frame classes must override it. The method is called by YASLSwingAppFrameImpl from its initUI() method. The map arguments passed into this method are created from the menu xml config file.

If you do not handle menu configuration via an xml file, then you should create and set your menus in the initUI(Map menuBarMap, Map menuMap) method.

The sample code below is drawn from the frame class associated with the YASL Test Application.

public YASLTestAppFrame(String menuConfigFileName) {
  super(menuConfigFileName);
}

protected void initUI(Map menuBarMap, Map menuMap)
    throws Exception {
  YASLSwingApplication yaslSwingApp = getSwingApplication();
  // set resource manager
  YASLResourceManager rmanager = yaslSwingApp.getResourceManager();
  // set title bar text
  this.setTitle(rmanager.getString(AppConstants.BUNDLE_GUI_STRINGS,
                                   "app.title.bar"));
  // get and set menubar
  JMenuBar menuBar = (JMenuBar) menuBarMap.get("main_menubar");
  this.setJMenuBar(menuBar);
}

YASLSwingAppFrame

This interface defines the methods that a frame class must implement in order to work with other classes in the architecture. It is implemented by YASLSwingAppFrameImpl.

public interface YASLSwingAppFrame {
  /**
   * Initializes the application menus and other parts of the
   * application's GUI.
   *
   * @throws Exception
   */
  public void initUI()
      throws Exception;

  /**
   * Returns the swing application instance associated with
   * this frame.
   *
   * @return YASLSwingApplication
   */
  public YASLSwingApplication getSwingApplication();

  /**
   * Returns this frame as a JFrame.
   * 
   * @return JFrame
   */
  public JFrame getJFrame();
}

YASLSwingAppFrameImpl

YASLSwingAppFrameImpl is the base class for frame classes. It extends javax.swing.JFrame and implements YASLSwingAppFrame and java.awt.event.WindowListener. Its primary responsibilities are:

• Processing the xml menu config file.
• Handling window closing events.

The first task is handled in the initUI() method. After processing the xml config file, YASLSwingAppFrameImpl calls initUI(Map menuBarMap, Map menuMap) passing the menuBar and menu maps created during the xml processing. The initUI() method is final.

The second task is handled in the windowClosing(WindowEvent e) method. This method is invoked when the user attempts to close the window from the window's system menu. If an action has been mapped to YASLApplication.KEY_ACTION_APPLICATION_EXIT, the action will be invoked.

public final void initUI()
      throws Exception {
  YASLMenuConfigContentHandler contentHandler =
        new YASLMenuConfigContentHandler(swingApp);
  if (menuConfigFileName != null) {
    ConfigUtils.initFromConfigFile(
            contentHandler,
            ConfigUtils.getInputSource(menuConfigFileName));
  }
  else if (menuConfigFile != null) {
    ConfigUtils.initFromConfigFile(
            contentHandler,
            ConfigUtils.getInputSource(menuConfigFile));
  }
  initUI(contentHandler.getMenuBarMap(),
         contentHandler.getMenuMap());
}

/**
 * Invoked when the user attempts to close the window
 * from the window's system menu.  If the program does not
 * explicitly hide or dispose the window while processing
 * this event, the window close operation will be cancelled.
 */
public void windowClosing(WindowEvent e) {
  try {
      Action exitAction = swingApp.getActionHandler().getActionByKey(
              swingApp.KEY_ACTION_APPLICATION_EXIT);
      exitAction.actionPerformed(null);
  }
  catch (YASLApplicationException ex) {
      // log this and exit??
  }
}

---

Note: YASL can be used to write console applications, desktop applications, and applets. Unless otherwise noted, the documentation will focus on desktop applications.