XML Configuration

YASL uses XML configuration for creating and initializaing singletons, actions, and menus. Developers are not required to use XML configuration but it is highly recommended. If the XML is not sufficient for initializing an object, developers are always free to code the configuration. (See the setSingletons() and setActions() methods from YASLAppConfigHelper.)

XML Config Files
XML Config Debugging
Singletons Config Tags
- singletonsConfig
- singleton
Actions Config Tags
- actionsConfig
- action
Menus Config Tags
- menu
- menuItem (standard menu item)
- menuItem (separator menu item)
- menuItem (checkbox menu item)
- menuItem (radio button menu item)
- menuBar
Generic Config Tags
- argComplex
- argKeyedObject
- argPrimitive
- argRBString
- map
- mapEntry (mapping to String)
- mapEntry (mapping to keyed object)
- mapEntry (mapping to String from resource bundle)
- mapEntry (mapping to an object created from arguments)
- methodCall
- methodCallArg
- property

XML Config Files

YASL applications rely on two xml files for configuration.

xxxxConfig.xml
Creates and configures singletons and actions.
Top Level Tag: <yaslConfig>
xxxxMenuConfig.xml
Creates and configures menus and menubars.
Top Level Tag: <yaslMenuConfig>

XML Config Debugging

Problems with xml configuration can be difficult to debug. Using debug-level logging to the console enables developers to pinpoint problem tags. To enable the logging from the command line use: java -Dlogging.level=debug -Dlogging.target=console -jar yourapp.jar. This will dump information on the start tags, attributes, and end tags being processed to the console.

Singletons Config Tags

<singletonsConfig>
Wraps singleton config tags.
<singleton>
Creates and stores a singleton in the singleton map. The tag has required attributes and it can take arguments for the class's constructor.

Attribute Required Description

class yes Fully-qualified name of the class to be created. For example, java.lang.String

key yes The key used to access this object in the singletons map.

Sample Usage:
```
<singleton class="java.lang.String" key="test_singleton_0">
  <argPrimitive type="String" value="test string"/>
</singleton>
```

Attribute	Required	Description
class	yes	Fully-qualified name of the class to be created. For example, java.lang.String
key	yes	The key used to access this object in the singletons map.

Actions Config Tags

<actionsConfig>
Wraps action config tags.
<action>
Creates and stores an action in the action map. The tag has required attributes and it can take arguments for the class's constructor.

Attribute Required Description

class yes Fully-qualified name of the class to be created. For example, java.lang.String

key yes The key used to access this object in the actions map.

Sample Usage:
```
<action class="org.yasl.testapp.actions.TestAppStartAction" 
    key="yasl_action_application_start">
  <argKeyedObject keyType="singletons" key="yasl_application"/>
</action>
```

Attribute	Required	Description
class	yes	Fully-qualified name of the class to be created. For example, java.lang.String
key	yes	The key used to access this object in the actions map.

Menus Config

These tags are specific to menu and menubar configuration.

<menu>
Creates a menu object and places the object in the menus map using the value from the key attribute. The constructor typically takes a String argument.

Attribute Required Description

key yes The name associated with the menu for use in other tags.

Sample Usage:
```
<menu key="menu_file">
  <argRBString bundle="$bundleName" key="menu.file"/>
</menu>
```
<menuItem> (standard menu item)
Creates a menu item object and attaches it to a menu.

Attribute Required Description

attachTo yes The name of the menu with which to associate this menu item.

Sample Usage:
```
<menuItem attachTo="menu_file">
  <argKeyedObject keyType="actions" key="yasl_action_application_exit"/>
</menuItem>
```
<menuItem> (separator menu item)
Creates a separator and attaches it to a menu.

Attribute Required Description

attachTo yes The name of the menu with which to associate this menu item.

class yes The class javax.swing.JSeparator or a class that extends it.

Sample Usage:
```
<menuItem attachTo="menu_component" class="javax.swing.JSeparator"/>
```

Attribute	Required	Description
key	yes	The name associated with the menu for use in other tags.

<menuItem> (checkbox menu item)
Creates a checkbox menu item and attaches it to a menu.

Attribute	Required	Description
attachTo	yes	The name of the menu with which to associate this menu item.
class	yes	The class javax.swing.JCheckBoxMenuItem or a class that extends it.
selected	no	The initial state of the checkbox, ie checked or unchecked. The valid values are: true (checked) or false (unchecked). The default value is false.

Sample Usage:

<menuItem attachTo="menu_menus" class="javax.swing.JCheckBoxMenuItem" selected="true">
  <argKeyedObject keyType="actions" key="checkbox_menu_item"/>
</menuItem>

<menuItem> (radio button menu item)
Creates a radio button menu item and attaches it to a menu.

Attribute	Required	Description
attachTo	yes	The name of the menu with which to associate this menu item.
class	yes	The class javax.swing.JRadioButtonMenuItem or a class that extends it.
selected	no	The initial state of the radio button, ie checked or unchecked. The valid values are: true (checked) or false (unchecked). The default value is false.
buttonGroup	no	The name of the button group object that a radio button will be associated. A button group enforces the single selction rule among a group of radio buttons.

Sample Usage:

<menuItem attachTo="menu_menus" class="javax.swing.JRadioButtonMenuItem" buttonGroup="menusRadioButtonGroup" selected="true">
  <argKeyedObject keyType="actions" key="radio_menu_item1"/>
</menuItem>

<menuBar>
Creates a menu bar object and places it in the menu bars map.

Attribute	Required	Description
key	yes	The name associated with the menu bar in the menu bars map.

Sample Usage:

Creating a menu bar:
<menuBar key="main_menubar"/>

Adding a menu to a menu bar:
<methodCall keyType="menubars" key="main_menubar" method="add">
  <argKeyedObject keyType="menus" key="menu_file"/>
</methodCall>

Generic Config Tags

These tags are used for action, menu, and singleton config.

<argComplex>
Creates an object. The constructor can take arguments. The created object will then be passed to a constructor or method.

Attribute	Required	Description
class	yes	The type of object to create.

Sample Usage:

<singleton class="java.awt.Rectangle" key="test_singleton_2">
  <argComplex class="java.awt.Dimension">
    <argPrimitive type="int" value="100"/>
    <argPrimitive type="int" value="350"/>
  </argComplex>
</singleton>

<argKeyedObject>
Obtains an object from the specified map and passes it to a constructor or method.

Attribute	Required	Description
keyType	yes	The map from which to obtain the object. The valid values are: actions, menubars, menus, singletons, and temporary.
key	yes	The key used to map the object.
class	no	The class to which the object will be cast when passed to a constructor or method. In most cases the class can be determined programatically.

Sample Usage:

<singleton class="org.yasl.arch.impl.prefs.PreferencesManagerImpl" 
    key="yasl_preferences_manager">
  <argKeyedObject keyType="temporary" key="default_prefs"/>
</singleton>

<argPrimitive>
Creates an argument of a primitive type that will be passed to a constructor or method.

Attribute Required Description

type yes The primitive argument's type. Valid values are: boolean, double, float, int, string.

value yes The value that will be converted into the specified primitive type.

Sample Usage:
```
<singleton class="java.lang.Boolean" key="test_singleton_1">
  <argPrimitive type="boolean" value="true"/>
</singleton>
```

Attribute	Required	Description
type	yes	The primitive argument's type. Valid values are: boolean, double, float, int, string.
value	yes	The value that will be converted into the specified primitive type.

<argRBString>
Obtains a String from a resource bundle for passing to a constructor or method.

Attribute	Required	Description
bundle	yes	The fully qualified name of the resource bundle.
key	yes	The name of the String from the resource bundle.
locale	no	The locale to use when accessing the resource bundle. If not specified the application's default locale will be used.

Sample Usage:

<menu key="menu_help">
  <argRBString bundle="org.yasl.testapp.resources.yaslTestAppGuiStrings" key="menu.help"/>
</menu>

<map>
Creates map objects. Maps are used to initialize other objects or for direct placement in the singletons map.

Attribute	Required	Description
keyType	yes	The map into which the map object will be placed. The valid values are: singletons and temporary.
key	yes	The key used to store this object in the specified map.
class	no	The type of map to create. Default is java.util.HashMap.

Sample Usage:

<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>

<mapEntry> (mapping to String)
Creates a key-value pair for a String object to be placed in a map.

Attribute Required Description

mapKey yes The name used to map the object that will be added to the map.

mapValue yes The value to which the key maps.

Sample Usage:
```
<mapEntry mapKey="yasl.pref.app.width" mapValue="500"/>
```

<mapEntry> (mapping to keyed object)
Creates a key-value pair for a keyed object to be placed in a map.

Attribute	Required	Description
mapKey	yes	The name used to map the object that will be added to the map.
key	yes	The key used to map the object.
keyType	yes	The map from which to obtain the object. The valid values are: actions, menubars, menus, singletons, and temporary.

Sample Usage:

<mapEntry mapKey="keyForKeyedObj2" key="test_singleton_2" keyType="singletons"/>

<mapEntry> (mapping to String from resource bundle)
Creates a key-value pair for a String from a resource bundle to be placed in a map.

Attribute	Required	Description
mapKey	yes	The name used to map the object that will be added to the map.
key	yes	The name of the String from the resource bundle.
bundle	yes	The fully qualified name of the resource bundle.
locale	no	The locale to use when accessing the resource bundle. If not specified the application's default locale will be used.

Sample Usage:

<mapEntry mapKey="keyForRBString" bundle="org.yasl.testapp.resources.yaslTestAppGuiStrings" key="app.title.bar"/>

<mapEntry> (mapping to an object created from arguments)
Creates a key-value pair for an object created with or without arguments.

Attribute Required Description

mapKey yes The name used to map the object that will be added to the map.

class yes The type of object to create.

Sample Usage:
```
<mapEntry mapKey="keyForObj" class="java.awt.Dimension"/>
<mapEntry mapKey="keyForObjWithArgs" class="java.awt.Dimension">
  <argPrimitive type="int" value="100"/>
  <argPrimitive type="int" value="350"/>
</mapEntry>
```

<methodCall>
Obtains the requested object from the specified map and calls the requested method.

Attribute	Required	Description
keyType	yes	The map from which to obtain the object. The valid values are: actions, menubars, menus, singletons, and temporary.
key	yes	The key used to map the object.
method	yes	The name of the method to call.

Sample Usage:

<methodCall keyType="menubars" key="main_menubar" method="add">
  <argKeyedObject keyType="menus" key="menu_file"/>
</methodCall>

<methodCallArg>
Obtains the requested object from the specified map and calls the requested method. The returned object will be cast to the specified type and applied as an argument to a method or constructor.

Attribute	Required	Description
keyType	yes	The map from which to obtain the object. The valid values are: actions, menubars, menus, singletons, and temporary.
key	yes	The key used to map the object.
method	yes	The name of the method to call.
returnClass	no	The value returned by the method will be cast to the specified type. This parameter is required only if you want to cast the returned value to a type that is different from the type normally returned by the method.

Sample Usage:

<singleton class="java.lang.String" key="test_singleton_4">
  <methodCallArg keyType="singletons" key="test_singleton_0" method="substring">
    <argPrimitive type="int" value="2"/>
    <argPrimitive type="int" value="6"/>
  </methodCallArg>
</singleton>

<property>
Defines a property that can be referenced by other tags. Properties can also be defined as System properties from the command line.

Attribute	Required	Description
key	yes	The name of the property used for referencing it from other tags. To reference the property, prefix it's name with a $.
value	yes	The String associated with this property.

Sample Usage:

Defining the property:
<property key="bundleName" value="org.yasl.testapp.resources.yaslTestAppGuiStrings"/>

Using the property:
<action class="org.yasl.debugging.actions.YASLApplicationInspectorAction" key="appinspector_component">
  <argRBString bundle="$bundleName" key="menu.item.appinspector"/>
  <argKeyedObject keyType="singletons" key="yasl_application"/>
</action>

Yet Another Swing Library

Swing Application Framework and Components

Documentation:

XML Configuration

XML Config Files

XML Config Debugging

Singletons Config Tags

Actions Config Tags

Menus Config

Generic Config Tags

Attribute	Required	Description
mapKey	yes	The name used to map the object that will be added to the map.
mapValue	yes	The value to which the key maps.