Download 1.2
Latest Release:
June 05, 2008

Documentation:

General: Architecture: Components:

Quick Start: Hello World

The Hello World application provides an example of a bare bones YASL application. This example shows how the architecture fits together with a minimum amount of code. For the steps to build and run the Hello World application, see the Building the Library documentation.

Files specific to the Hello World Application

Diagram 1 provides a graphical description of the relationship between the Hello World application classes and configuration files.

  1. The application starts execution in the main() method of YASLApplicationStarter. The class with the main() method is defined in the manifest.helloworld.mf file. YASLApplicationStarter first locates for the yaslAppConfig.properties file and initializes its references to the splash page data and xml config file (yaslHelloWorldConfig.xml).
  2. YASLApplicationStarter calls the putUpSplash() method of HelloWorldSplash.java to start the splash page display.
  3. YASLApplicationStarter uses the yaslHelloWorldConfig.xml to initialize the application's singleton and action maps. During this initialization, the HelloWorldTestAppFrame class is created and its reference to yaslHelloWorldMenuConfig.xml is set.
  4. YASLApplicationStarter calls HelloWorldTestAppFrame's initUI() method. This method ultimately calls the initUI(Map menuBarMap, Map menuMap) method that all app frame classes must implement.
  5. The initUI() method uses the yaslHelloWorldMenuConfig.xml file to initialize the application's menus and link menu items to actions from the application's action map.
  6. YASLApplicationStarter calls the takeDownSplash() method of HelloWorldSplash.java to dismiss the splash page.
  7. YASLApplicationStarter calls HelloWorldTestAppFrame's setVisible() method.

Diagram 1: Relationships and Method Calls

manifest.helloworld.mf

The manifest file defines the class in the application with the main method, the start point for the application. It also defines the jars that will be on the application's class path. All YASL applications use the YASLApplicationStarter as the start point for the application.

Manifest-Version: 1.0
Main-Class: org/yasl/arch/impl/application/YASLApplicationStarter
Class-Path: yasl-arch-1.2.jar yasl-slf4j-1.2.jar slf4j-api-1.4.3.jar

yaslAppConfig.properties

All YASL applications require this properties file. At a minimum, developers must define values for the yasl.app.type and yasl.app.config keys. The YASLApplicationStarter class uses this properties file to find the application's main configuration file. It references the yasl.splash keys to create and initialize the splash page.

The YASLApplicationStarter first looks for this file in the application's classpath. Secondly, it checks the yasl.app.config.file system property for a fully qualified reference. The following example sets the system property during application launch: java -Dyasl.app.config.file=/org/yasl/testapp/yaslAppConfig.properties -jar yasl-testapp-1.2.jar.

yasl.app.type=Swing

yasl.app.config=/org/yasl/helloworld/config/yaslHelloWorldConfig.xml

yasl.splash=org.yasl.helloworld.HelloWorldSplash
yasl.splash.duration=2
yasl.splash.width=300
yasl.splash.height=200

yaslHelloWorldConfig.xml

This configuration file defines the singletons and actions to be used by the application. During application start-up, the objects defined will be created and stored in the singleton and action maps.

The Hello World application defines three singletons: a resource manager, an application frame, and a preferences manager. The resource manager handles loading images and I18N strings. The preferences manager tracks user preferences, loads them at application start, and saves them to a properties file at application exit. Every YASL desktop application must extend YASLSwingAppFrameImpl and at a minimum, implement the initUI(Map menuBarMap, Map menuMap) method. When the HelloWorldTestAppFrame is created, the path to the menu config file is passed to the constructor. Note that the application uses the default implementations for the resource manager and preferences manager. Also note that each singleton uses a reserved singleton key.

The Hello World application defines two actions: a start action and an exit action. For both actions, the application is using the default implementation. The start action is called automatically during application start-up. Developers can use this hook to load user preferences or any other application config information. The exit action is invoked in response to user actions. It is normally associated with the File | Exit menu option. It saves any config information and halts the application. Note that both the start and exit actions use reserved action keys.

For information on the tags used, see XML Configuration.

<yaslConfig>
  <property key="bundleName" value="org.yasl.helloworld.resources.helloWorldGuiStrings"/>
  <property key="prefsFolder" value="yasl_hello_world"/>
  <property key="prefsFilename" value="hello_world_prefs.properties"/>
  <property key="menuConfig" value="/org/yasl/helloworld/config/yaslHelloWorldMenuConfig.xml"/>

  <singletonsConfig>
    <!-- resource manager -->
    <singleton class="org.yasl.arch.impl.resources.YASLResourceManagerImpl" key="yasl_resource_manager">
      <argPrimitive type="String" value="$bundleName"/>
    </singleton>
    <!-- app frame -->
    <singleton class="org.yasl.helloworld.HelloWorldTestAppFrame" key="yasl_swing_app_frame">
      <argPrimitive type="String" value="$menuConfig"/>
    </singleton>
    <!-- default preferences -->
    <map key="default_prefs" keyType="temporary">
      <mapEntry mapKey="yasl.pref.app.width" mapValue="500"/>
      <mapEntry mapKey="yasl.pref.app.height" mapValue="350"/>
      <mapEntry mapKey="yasl.pref.app.pos.x" mapValue="100"/>
      <mapEntry mapKey="yasl.pref.app.pos.y" mapValue="100"/>
    </map>
    <!-- preferences manager -->
    <singleton class="org.yasl.arch.impl.prefs.PreferencesManagerImpl" key="yasl_preferences_manager">
      <argKeyedObject keyType="temporary" key="default_prefs"/>
      <argPrimitive type="String" value="$prefsFolder"/>
      <argPrimitive type="String" value="$prefsFilename"/>
    </singleton>
    <!-- set header for prefs manager -->
    <methodCall keyType="singletons" 
                key="yasl_preferences_manager" 
                method="setDefaultPreferencesHeader">
      <argRBString bundle="$bundleName" key="app.user.prefs.header"/>
    </methodCall>
  </singletonsConfig>

  <actionsConfig>
    <action class="org.yasl.arch.impl.action.YASLDefaultSwingAppExitAction" 
            key="yasl_action_application_exit">
      <argRBString bundle="$bundleName" key="menu.item.exit"/>
      <argKeyedObject keyType="singletons" key="yasl_application"/>
    </action>
    <action class="org.yasl.arch.impl.action.YASLDefaultSwingAppStartAction"
            key="yasl_action_application_start">
      <argKeyedObject keyType="singletons" key="yasl_application"/>
    </action>
  </actionsConfig>
</yaslConfig>

yaslHelloWorldMenuConfig.xml

This configuration file defines menu, menuitem, and menubar items for the application and associates actions with the menuitems. Note that the key used for the menubar object, main_menubar, is the same as the key used to retrieve the menubar object to set in the HelloWorldTestAppFrame class's initUI(Map menuBarMap, Map menuMap) method. Any menubar object created in this config file will be placed in a menuBarMap and any menu object created will be placed in the menuMap. These maps will be passed to the initUI method.

For information on the tags used, see XML Configuration.

<yaslMenuConfig>
  <property key="bundleName" value="org.yasl.helloworld.resources.helloWorldGuiStrings"/>

  <!-- file menu -->
  <menu key="menu_file">
    <argRBString bundle="$bundleName" key="menu.file"/>
  </menu>

  <!-- file menu items -->
  <menuItem attachTo="menu_file">
    <argKeyedObject keyType="actions" key="yasl_action_application_exit"/>
  </menuItem>

  <!-- menubar -->
  <menuBar key="main_menubar"/>
  <!-- add menus to menubar -->
  <methodCall keyType="menubars" key="main_menubar" method="add">
    <argKeyedObject keyType="menus" key="menu_file"/>
  </methodCall>

</yaslMenuConfig>

helloWorldGuiStrings.properties

Defines text to be referenced by the resource manager for use in the application.

# application info
app.title.bar=Hello World

# comment to place at top of user prefs file
app.user.prefs.header=yasl hello world app user preferences

menu.item.exit=Goodbye World

menu.file=File

HelloWorldTestAppFrame.java

All YASL applications must extend YASLSwingAppFrameImpl to create an application frame object. The frame object must implement the initUI(Map menuBarMap, Map menuMap) method. The HelloWorldTestAppFrame sets the text for the title bar and sets the menu bar.

package org.yasl.helloworld;

import java.util.Map;

import javax.swing.JMenuBar;

import org.yasl.arch.application.YASLSwingApplication;
import org.yasl.arch.impl.application.YASLSwingAppFrameImpl;
import org.yasl.arch.resources.YASLResourceManager;

/**
 *
 * @author Jeff Chapman
 * @version 1.0
 */
public class HelloWorldTestAppFrame
        extends YASLSwingAppFrameImpl {

    public HelloWorldTestAppFrame(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(rmanager.getDefaultBundle(),
                                         "app.title.bar"));
        // get and set menubar
        JMenuBar menuBar = (JMenuBar) menuBarMap.get("main_menubar");
        this.setJMenuBar(menuBar);
    }
}

HelloWorldSplash.java

Applications that need a splash page can extend YASLSplashImpl and implement the buildSplashPanel(JPanel panel, JLabel messageLabel, JProgressBar loadingProgress) method. The Hello World application displays a title, copyright information, and an indeterminate progress bar.

package org.yasl.helloworld;

import java.awt.BorderLayout;
import java.awt.Color;
import java.awt.Font;

import javax.swing.BorderFactory;
import javax.swing.JLabel;
import javax.swing.JPanel;
import javax.swing.JProgressBar;

import org.yasl.arch.impl.splash.YASLSplashImpl;

/**
 *
 * @author Jeff Chapman
 * @version 1.0
 */
public class HelloWorldSplash
        extends YASLSplashImpl {

    public HelloWorldSplash() {
        super();
    }

    protected void buildSplashPanel(JPanel panel,
                                    JLabel messageLabel,
                                    JProgressBar loadingProgress) {
        JLabel mainLabel = new JLabel("Hello World", JLabel.CENTER);
        mainLabel.setFont(new Font("Sans-Serif", Font.BOLD, 30));

        JLabel copyRight = new JLabel("Copyright 2008, YASL", JLabel.CENTER);
        copyRight.setFont(new Font("Sans-Serif", Font.BOLD, 12));

        JPanel mainPanel = new JPanel(new BorderLayout());
        mainPanel.add(mainLabel, BorderLayout.CENTER);
        mainPanel.add(copyRight, BorderLayout.SOUTH);

        panel.setLayout(new BorderLayout(0,3));
        panel.add(mainPanel, BorderLayout.CENTER);
        panel.add(loadingProgress, BorderLayout.SOUTH);
        panel.setBorder(BorderFactory.createLineBorder(Color.red, 10));;
    }

    protected JProgressBar getProgressBar() {
        JProgressBar bar = new JProgressBar(JProgressBar.HORIZONTAL);
        bar.setIndeterminate(true);
        return bar;
    }
}

    SourceForge.net Logo