Installing Aria

Aria can be installed in a number of ways depending on the intended usage. At its simplest Aria can be downloaded and used as is. At the other end of the scale Aria requires a number of installations to access all features.

Downloading Aria

Aria can be downloaded from the SourceForge website at http://www.sourceforge.org/projects/aria . To download you need to register using a valid e-mail address. Once you have successfully registered you will be sent an e-mail with directions to the download site where you can download the version of Aria that you need.

As a registered user you will be able to subscribe to updates, newsletters and technical tips

Aria components

Aria is a Java platform and therefore requires a recent Java development kit. You need to have a recent JDK (1.5) to run all the features, notably the NetBeans plug-ins. Otherwise, if you do not plan to use the editors you can use just about any JDK you like.

Aria components

On the files release system you can obtain a number of variants of the Aria platform and these are described below. The files are delivered in two variants, one containing non-debug version of the class files and the second compiled with full debug information and include all logging and diagnostic features switched on:

The Aria Jars are compiled for a number of JDKs and accordingly have slightly different feature sets. The fullest feature set is for the most recent JDK.

For mobile and embedded devices the above packaging may not match a platforms capabilities so you may want to compile the source code for the platform that suits your needs. All the source and the build files are available, so you can tweak the feature set to suit your needs. For example, some mobile platforms include Swing and JDBC connectivity while others don't, depending upon the level of compatibility provided. Therefore to avoid proliforation of the number of versions compiled we have stuck to the core JDK when building pre-packaged versions of Aria.

The Aria jars are not signed, since you may need to sign the jars with a single certificate to distribute via Java Web Start. Therefore you need not stick to the packaging provided by the pre-built jars. For a minimal footprint you may even want to strip down the jars so that you only include thoses classes that you absolutely need. However, please ensure that you observe the licensing requirements in this regard if you change or alter the distribution.

Installing NetBeans

Aria includes a NetBeans plug-in for rapid development. Most of the features of Aria are used and accessed via this plug-in and it is therefore most likely that you will also require a version of NetBeans. At the time of writing the target version of NetBeans is version 5.5. Java version 1.5 (JDK 1.5) is also required to run this version of Aria

NetBeans can be downloaded from http://www.netbeans.org.

The NetBeans site also contains extensive documentation of installing and using the IDE.

Loading Aria

Once Aria has been downloaded. The NetBeans plug-in is delivered as a NetBeans module file with the .nbm extension. To load the module you must first start NetBeans. Once started go to the Update Center on the tools menu.

Then choose the ` Install Manually Downloaded Modules (.nbm files)' option. Select the four NetBeans modules: javax-jnlp.nbm, net-aria.nbm. The first of these are the module for the open source Aria module and the third is the module for Aria's add-on features.

When the NetBeans module has been successfully installed the Aria menu item will appear on the main menu.

If you are just installing Aria and AriaEditor, then you can check that the installation has succeeded by check that the New Aria Project wizard is available from the File | New | Project menu option.

Installing the samples

A number of samples are available on the Formaria website. The samples files are simple zip archives of complete projects. To begin working with the samples you can simple download the archive and unzip the archive and open the project using the NetBeans File | Open command. The samples provided with Aria are listed below:

In addition to the samples listed above the source code for the case studies included in this guide can also be downloaded. New samples are occasionally added to the website and it is probably worth checking for updates (http://www.formaria.org). The Formaria website also features numerous technical articles describing new and key features.

Installing the Eclipse plug-in

Like the NetBeans plug-in the Eclipse plug-in provides interactive editing of Aria and Aria applications. The plug-in is easy to install, just unpack the zip archice and drop the enclosed jar into Eclipse's plugin folder and restart the IDE.

When Eclipse restarts you should see the Aria project wizard under the File | New | Other dialog. At present there is no Eclipse version of the Aria plugin.

Building Aria from source

Building Aria from the source code is possible within both the NetBeans and the Eclipse IDEs. All of the source is available from the SourceForge repository. The project's SourceForge.net Subversion repository can be checked out through SVN with the following instruction set:

(Warning: This is a generic Subversion checkout command which will pull all modules, tags and/or branches of the project).

Project source layout

The source code is laid out in a number of packages, as follows:

Building the runtime libraries

The runtime libraries are built using the latest version of NetBeans (6.1 at the time of writing), using the AriaRuntimeCommon project. The project also uses JDK 1.6, although it compiles for earlier JDKs.

To build the runtime you will need to download the main project plus the following libraries or packages from the lib folder described above in See Top level projects.:

In addition to these libraries, some libraries from the Java runtime and JDK are employed. All of these libraries are referenced from relative paths, so if you download the libraries, preserving the directory structure the project should build without modification.

The default build target will generate the runtime libraries in a number of forms:

The version number is appended to the library name in the form version_date, for example AriaRuntimeCommon_1.0.0.v20080726.jar . At present the build produces a Java 6 version , but this will be extended to include support for earlier JDKs and when this is done the JDK version will also be appended to the jar name.

The default build will also copy the AriaRuntimeCommon.jar file to the libs/aria folder which is references by many of the sample projects and applications, so that these applications are always using the latest build. Periodically this library is also commited to SVN (when any significant change is made).

Building the NetBeans plugin from source

Once you have built the runtime environment as described above you can begin to build the NetBeans plugin. The plugin relies on the runtime, running on the same code as the end user applications, but for distribution as part of a plugin the runtime must first be bundled as an installable module for NetBeans.

Indeed, this process of wrapping the runtime libraries or dependancies is used for all the extrenal jars needed by the plugin and for wrapping the code shared with the Eclipse plugin. A suite of modules is therefore used to create the plugin, and this is called the AriaNetBeansSuite .

The source and project files for all plugin modules is again available from the SourceForge SVN repository (see See Subversion access.). To build the project first open the AriaNetBeansSuite project, when this is opened you will be prompted to open all the module projects within the suite. Most of these modules are merely static wrappers for the plugin's libraries, apart from the following:

All the projects have dependancies on the required modules so doing a clean and build on the suite will build everything, including the runtime environment.

The project can be built within NetBeans project view by right clicking on the AriaEditorNetBeansSuite project and choosing Build NBMs . The result of the build is a set of NBM files in the AriaNetBeansSuite/build/updates folder together with the updates.xml file.

Once the modules have been build you can either deploy the contents of the directory or launch the editor in a hosted version of NetBeans by clicking either Run or Debug

Building the Eclipse plugin from source

The process for building the Eclipse plugin is pretty much just a case of downloading the sourec from SVN, opening the project and building. The Eclipse plugin is a single project contained in the AriaEditorEclipse folder.

One possible complication is that the ARIA_PROJECT_ROOT variable needs to be set. Within the Eclipse Window | Preferences | Java | Build Path | Classpath Variables dialog the variable can be added or configured to suit your environment's setup.

Building the sample applications from source

t present the sample applications are only setup within NetBeans. Most of the applications are self contained and refer to libraries within the Aria SVN hierarchy (within the libs folder). One exception to this is the MetroBank example that contains a web server application which relies on the Spring framework.

Since the Spring framrwork is a large and complex environment it is not included with the Aria SVN repository and is instead referenced by the project via some private settings. Within the nbproject/private/private.properties folder there are some settings that will need to be adjusted to match your setup before the build will success. These settings are:

The Metrobank sample is split into two parts, the client and the server parts. More info about this example can be found later in this manual

A quick tour of the editor

This chapter provides a quick tour of the Aria editor within NetBeans. The main features of the editor and the main steps involved in creating an application are described. The chapter is intended only as an introduction so that you can begin exploring the features built into the editor. Later chapters will cover each of the topics in more detail.

Creating a new project

NetBeans includes a range of templates for creating various pieces of applications. The Aria templates are unsurprisingly listed under the Aria heading.

To access the templates choose File | New from the main menu.

The templates included in Aria are as follows:

• New Project: Creates a the stub of a new project
• New Page: Creates a blank page within the current project

To create a new project choose the New Project template. The template is shown below.

To complete the template you must choose a directory into which the new project will be generated. To get started quickly you can just choose the default settings once you have set the target directory.

For the most part the options for creation of the new project are simple.

The settings page also gives options for the project name, which is the name that will be used to identify the project within NetBeans. The application title is the text that appears in the application title bar, this is also the text that some operating systems used to identify the running application. The remaining settings affect the way the application is presented and behaves.

When the application first appears it can be centred on screen or it can appear in the top left of the desktop, the ` Center on screen ' checkbox controls this behavior. The application may also be embedded in an HTML page as an applet or it may be run as a standalone application. In either case it is possible to show the applet/application in a popup window. This window does not have the usual sizeable window border. The ` Popup Window ' checkbox controls this option.

The ` Window Size ' section is straightforward and simply lists some standard window sizes for the new application.

Optionally a Splash Screen can be include. The splash screen is simple an image that is presented as the application loads, the screen typically times out after a few seconds, or it can be dismissed with a user click.

By default the first page displayed is called ` welcome.xml ', but you can choose to display a different page at startup by entering the name of the first page. There is no need to specify the ` .XML ' suffix as this will be assumed, if there is no Java class called by the name of the startup page.

One option you should take care to set correctly is the package name. This can often be confused with a path and instead it is the Java Language package name. For anyone not familiar with package names the appendix gives a brief overview of this language feature

The ` Log level ' controls the amount of information that is displayed in the console while running the application. This applies only when running the application with debug versions of the libraries (the default in Aria).

The Frameset Configuration optionally allows you to configure your application as multiple pages within a single frame or as a single page. Sometimes a frameset is used when common elements repeat across multiple screens, say for example a navigational control panel or a banner headline.

The project is configured with multiple files to help separate the various forms of content. The most important of these are listed in the ` File name configuration ' page.

The final page of the new project wizard provides a place to configure some add-ons for Aria. These options are intended for more experienced users but essentially they allow you to extend the types of components, data bindings and validations that can be used in an application. The parameters are all class names. More details about these options will be given in later chapters.

Once the new project has been created the various folders and configuration files are setup. Some page stubs will also be created ready for you to start building content.

If you have any doubts about the options when creating the project there is no need to worry as all the options available in the new project wizard are also available on the project page. This page is opened once the initial generation of the project is finished.

Once the project is created it is shown in the Project view, which shows all the classes and packages within the project. The Files view shows all the files and resources that are used in the project.

The build.xml file is listed in this view and can be used to trigger actions such as the compiling, building and testing of the application.

A number of directories are created under the project's main directory or folder. The directories are as follows:

The project view

Once a new project has been created the project is automatically opened. The project editor contains much of the information that was in the New Project template and allows you change the project settings at any time during the project lifecycle.

At the top of the project view there is a set of buttons for access to additional parts of the project configuration. The options available in these windows affect all parts of the application, such as the page size and the frameset layout. Some of the options also affect the runtime behavior by adding extensions and modifying the classpath.

Pages and resources

Creating a new page in Aria is again achieved by choosing File|New. A template is also used to create the page, but this time all you need to do is choose a name for the page and its location. The page should be placed in the `pages' subdirectory of the project.

Later we will see how to add rules and Java code to the page and your will learn that the page name is used as the basis for a Java file. As Java is particular about class names it is best to conform to Java's naming conventions when choosing a page name. Thus the name should be a single word, starting with a capital letter.

The page designer

Once a new page is created it is opened for editing in the editor. Here's an example of a simple page.

At this point it is worth noting some of the overall features of the editor.

Pages can be opened on their own or within a frameset. To open a page with a frameset right click the page within the Files View and choose Open in frameset .

NetBeans also provides many features that will be of use to you as a developer from time to time. For example the Runtime view (not shown above, but accessible from the Window menu) provides access to runtime resources such as databases and servers. Using this view you can for instance drag a database table to a component on your page to establish a data binding, but we will cover this in more detail later in this manual.

Components

At the top right of the editor, when the page designer is active you will see the component palette. The content of the component palette will depend on the type of application being developed and whether or not any extensions have been added to Aria.

As a minimum there will be several core components shown. These are:

Component palette icons

Icon	Component description
	A button object, usually used to initiate some event or action.
	A check box, indicating an option selectable by the user. Where options are mutually exclusive a set of radio buttons should be used.
	A drop down list or combo box, representing a list of choices. A drop down list is usually used where there is a small number of options or where the number of options is too great for a set of radio buttons.
	An edit field, an input field where the user can enter a simple value. An edit field is a key input mechanism and Aria provides support for validation of input data using edit fields.
	An image component. Used to display images stored in the resources folder. Can be used with a MouseHandler to interact with the user.
	A hotspot, a clickable area that can be placed over another object so that when the user click on the hotspot some action occurs.
	An imagemap, like a hotspot except that an irregular/polygonal area can be specified as the clickable area. Like a hotspot the user can click to invoke an action.
	A Label, a simple piece of text. The label text does not normally cause any interaction with the user
	A Panel, a container into which other components can be placed. The panel can optionally be made to display a frame or border.
	A password edit field, a special case of an edit field used for entering a password. As the user types the value of the password the field displays a mask character for each letter or character typed.
	A scroll panel, a special form of a panel that supports scrolling. The pane can optionally be scrolled horizontally or vertically. The scroll pane automatically adjusts itself to the size of its content.
	A table, a simple table component that can display data directly from the model. Headers and alternate row shading are just two of many features that the table control supports.
	A text field, a simple text field. This component supports multiple lines of text.

The user can add any of these components to the page by first selecting a component from the component palette and then placing it by clicking at the desired location on the page.

Components can be nested by placing panels on the page and then placing additional components on the new panel. The panel is then considered to own the new components or children. When the panel is moved so too are the children.

As each component is selected the properties of that component are displayed in the properties palette, the style palette and the component inspector. Properties can be changed by choosing options within the properties palettes or by double clicking on styles. The component inspector is primarily a mechanism for showing the hierarchical relationship between components.

Multiple components can be inspected at once but only the common subset of the properties will be available in the various palettes and you may not always be able to interact with all properties.

When fully configured Aria may include several sets of components or widgets. The components belonging to these widget sets are displayed on separate tabs within the component palette. The availability of some of these widget sets may depend on the project configuration, for example if an AWT application has been chosen then the Swing widgets will not be available.

Styles

Styles in Aria comprise sets of colors and fonts that can be applied to just about any component. The style palette provides a simple way to interact with the styles, by simply selecting a component and double clicking a style value.

Styles can also be changed by simply changing the style file or by changing individual styles (by right clicking on the style palette). Aria even includes a color scheme picker (which again can be accessed by right clicking on the style palette).

The color scheme picker is designed to allow you to quickly choose and experiment with styles that will produce a visually attractive application.

Source code

An application generally isn't a lot of use unless it can do something. Aria is designed to make it easy to build applications and therefore adding custom functionality and business logic is simple.

When you select a component you will see its properties in the property sheet. Depending upon the component type this property sheet may display some event properties. For example a push button will have an ActionHandler property. By typing in the name of the source code method you can edit the Java source code for that method, and if no such method exists the stub of a new method of that name will be inserted into you Java source code file.

Later we will see how such an event handler is actually connected up to the user interface. However it is worth noting that Aria declares such links in the page's XML. You can switch back and forth to this XML by clicking the ( Design and XML ) buttons at the top of the page designer.

Of course you can also find the Java code in the Files view and open the file directly. The file is just a normal Java file and there are no hidden or special sections to worry about.

For example to add a piece of application logic simple choose the component that will initiate the action and within the properties palette find the appropriate response and just enter the name of the response method. Upon pressing Enter the source editor is opened and you can edit the Java code belonging to the event. At any stage you can switch back to the page designer by clicking on the tabs above the source editor or by closing the source editor.

The pageDesigner also allows you to selecting existing functions and attach then to a component. A list of available functions is displayed in the drop when you click on the event handler in the proeprty sheet, so if you do not want to enter the name of new event just choose one of the predefined functions if appropriate.

Once you have added a function and wish to jump to the source code, just hold the CTRL key while you click on the event handler and this will open the source code editor instead of editing the handler name.

In later chapters we will see just how to begin coding custom business logic.

XML

As a technology Aria makes extensive use of XML. XML is used to describe a wide variety of things in Aria, including the user interface. The XML for a UI can be displayed by choosing the XML tab for that page. Furthermore Aria allows two-way editing of the XML whereby any edits to the XML will be reflected in the page and any changes to the page within the page designer will be displayed in the XML. The updates occur as the display is modified by choosing the tabs along the top of the editor.

Later chapters will explain Aria's use of XML in greater depth.

Compilation

Writing code for an application is the first step in making working code. Java is a compiled language and therefore the source code needs to be compiled. The quickest and easiest way to do this is to right click on the project node in the Aria view. The context menu then shows a compile all option and choosing the Compile or Execute option will compile all classes within the project.

NetBeans also includes many options to control compilation, building and testing of an application and you should refer to the NetBeans documentation for more information on the available options.

Testing

Once the project has been successfully compiled you should test it prior to distribution. Aria and the underlying NetBeans platform provide a powerful testing and debugging environment. To test an application simply choose the Debug Project option from the popup menu on the tree icon for the project in build.xml file in the Files View.

Deployment

Finally to make widespread use of your application you need to package and deploy the application. There are wide variety of deployment scenarios and these will be covered in detail in later chapters.

Again NetBeans provides additional plug-ins to help manage the deployment of application, including Java Web Start deployments, and you may wish to download some of these extra plug-ins. Aria generates a stub of a JNLP file that can be used by such plug-ins.

Running Applications

Within Aria starting an application is handled by NetBeans using the normal Run or Debug commands. Outside of NetBeans several methods can be used to start-up Aria applications depending upon how the applications will be deployed. All of these start-up sequences start by invoking the *Applet class and eventually follow a generic initialization process. Some minor variations are accommodated by the Applet class to handle the different ways of setting start-up parameters and the differences in the classloaders.

When starting a Aria application the choice of the Applet class is important as this dictates whether or not the Aria framework constructs Swing or AWT components. If the org.formaria.awt.Applet class is used then AWT components are used, whereas if the org.formaria.swing.Applet version is used Swing components are constructed.

In the examples above it will be assumed that AWT is being used, but the examples will work just as well with Swing if the Swing version of Applet is substituted.

For the purposes of simplicity it will be assumed in the following discussions and examples that Java is installed as default and that Java can be started without additional modification of the environment or path.

Command-line startup sequence for applications

To start an application from the command line it is only necessary to invoke the Applet class.

Command Line startup command

 java -cp AriaRuntimeCommon.jar org.formaria.awt.Applet startup.properties

where startup.properties is the name of the initialization file (which if omitted will default to startup.properties ). The application can take one additional parameter, the default package name. Make sure to use the -cp or -classpath switch instead of the -jar switch (unless yo build a custom self-starting jar).

The default package name for an application is normally set by whichever version of the Applet is used to start the application ( org.formaria.awt for the org.formaria.awt.AXpplet class and org.formaria.swing for the org.formaria.swing.Applet class). It is very rare that this parameter would need to be set as the application will automatically set the appropriate default value.

Note that the startup file is generated by Aria each time the project is built, however Aria actually stores the values is the project.aria file for its own use.

Java Web Start Start-up Sequence

To run a Aria application as a Java Web Start application several preparatory steps are required. Firstly, the application must be packaged as an appropriate set of Jar files.

Next the application Jar files and resources must be signed and placed on a server configured to serve JNLP files. In particular, pay attention to how the mime-type is set for your particular server. In some cases the mime-type can be set by using dynamic content on the server such as JSPs or ASPs instead of vanilla HTML.

Once the Jars files are on the server the JNLP file can be configured. Here's an example:

Java Web Start (JNLP) startup code

 <?xml version="1.0" encoding="UTF8"?>
<!--   created by Aria   -->
<jnlp spec="1.0+" codebase="http://myserver/mydeploymentfolder/" >
<information>
  <title>Aria 1.0</title>
  <vendor>My Company</vendor>
  <homepage href="http://localhost/mywebfolder" />
  <offline-allowed />
</information>
<resources>
  <j2se version="1.1.4+" />
  <jar href="/Project.jar" main="false" download="eager" size="12369" />
  <jar href="lib/AriaRuntimeCommon.jar" main="true" download="eager" size="100131" />
</resources>
<application-desc main-class="org.formaria.awt.Applet" />
<security>
<all-permissions />
</security>
</jnlp>

To actually launch the Web Start Application it is then just a question of invoking the JNLP file. Normally this is done by embedding the link in an HTML page.

Normally it is also the practice to check that JWS is installed and display an appropriate error message if it is not. Sun's JWS web pages give examples and documentation of how to do this.

HTML/ Applet Start-up Sequence

The HTML initialization sequence is like the JNLP in some ways except of course that it is an applet that is being started and not an application. Security settings are also different for applets depending on the environment in which they run.

The HTML fragment required for an applet if as follows:

Basic applet tag

 <APPLET height=480 width=640 archive="lib/AriaRuntimeCommon.jar, 
    build/distrib.jar" code=org.formaria.awt.Applet>
<PARAM NAME="startfile" VALUE="startup.properties">
</APPLET>

Again the Jar file should be signed for distribution and placed on the webserver.

Generic Initialization

Once the Applet class has been invoked the initialization of the application/applet is pretty much the same regardless of how it was started. The sequence (and purpose of each step) is as follows:

1. Register the component factories. The registration process involves reading the ' NumComponentFactories ' parameter from the start-up file and then reading, instantiating and registering the number of component factories listed in the start-up file. Implicitly either an AWT or Swing component factory is already registered
2. Setup the project class. The project class maintains references to all the other resources, managers and factories used by the application. The project manager class can be accessed through a static accessor method and with this mechanism any resource can be easily obtained from the project without the need to carry references to the various objects.
3. Setup the page manager. The page manager controls the application display areas and acts as a broker for displaying frames and pages. The page manager also provides some navigation and page history support. At this point the content is also setup by specifying a frameset (if any) with the ' Frames ' parameter and the content with the ' StartClass ' parameter.
4. Setup the resource access. The resource access provides a simple method of loading resources and hides details of the various classloaders, paths and so on. Resource access is managed by the *Project instance which does some caching of resources such as images that are frequently reused.
5. Setup the style manager. This class loads style information from a file indicated by the 'styleFile' parameter in the start-up file. Styles can be used to configure fonts and colors in a consistent manner.
6. Size the main window. The startup parameters ' ClientWidth ' and ' ClientHeight ' are used to set the size of the main application window. The main window (in the case of an application) can also be centred by setting the start-up property ' CenterWin ' to true.
7. Set the layout. Assuming that some content was configured the application/applet is now laid out. This process will position the various elements of a frameset and the content of the frames or the content of the main window if no frameset is being used.
8. Add a shutdown hook. A shutdown hook is largely used for debug purposes to allow output of logging information. Shutdown hooks were not available on earlier JDKs so this feature may not be in use on all environments (particularly embedded platforms)
9. Display the main window. The application is now ready to display and the main window is shown. If you need to display a splash screen one good place to initiate its display (without subclassing Applet ) is when the first page is created, by embedding code in that page's pageCreated or pageActivated method.

Aria 3.0 refactored must of the startup infrastructure so that there is very little need to know any of the above detail, even if you are building a custom setup or a custom application type. Aria provides several stubs for the propular widgets sets and the normal application styles, however should you need something other than this then you can implement your own startup process quite easily as most of the necessary functionality is encapsulated in the ApplicationContext class which is used to setup the common infrastructure by the Aria framework. An example of this is the sample application that integrates Aria into the run-of-the-mill Swing application as a panel embedded in that application (see See Embedded applications.).

Startup file stubs

Aria creates a number stubs of the startup file whenever a project is generated. These files are found in the root directory of the project and are regenerated each time the project is generated.

Eclipse Debugging

In Eclipse the process of debugging is somewhat different to the NetBeans Experience. To debug the project simply right click the project in the Navigator or Package Explorer and choose the Debug As option and select Java Application .

Before Eclipse can run the application it needs to know the main entry point into the application, and to find this it will pop up a dialog requesting that you select the main class.

The Aria libraries should be on the project classpath and therefore Eclipse should be able to locate the Applet class as shown above. Note that for other application styles you may need to specify additional startup parameters and in this case you will need to create a custom debug configuration - see the Eclipse documentation for more details on doing so.

Getting Started

In this chapter we will see how to build some simple Aria applications using both Java and XML. We will see all the features needed to build a fully functional application within Aria in action. The chapter provides an introduction to the setup mechanisms used within a Aria application. Most of the features described can be configured interactively but to aid understanding they are explained at a lower level.

The chapter assumes that you have already encountered the features described in the previous chapter and that you have a basic understanding of how Java based applications function.

Don't worry if you do not understand all the nuances of the technology described as the various pieces of the application are but together. Later chapters are devoted to the individual features employed.

If you are new to Java we recommend that you study some of the numerous educational resources available on the Internet, some of which are listed in the appendix on Java.

Hello world

Traditionally the first example used in many user guides is the infamous 'Hello World' example where the task is to emit or display the simple text 'Hello World'. In Aria this is very simple, all you need do is create an XML file called 'home.xml', preferably in a new folder. The XML file contains the declaration of the user interface needed for this task. It looks like the following:

Page user-interface declaration

 <Page>
    <Components>
        <Label x="32" y="37" w="100" h="29" content="Hello World"/>
    </Components>
</Page></P>

And that's just about it. The only other thing that is needed is a convenient way of starting the application. To do this we create a startup command file. This command file doesn't have to do very much other than invoking the Java environment and telling it what class to start. The start class in this case is the entry point to the Aria framework or library. It contains the following command:

Command-line startup

 java -classpath .;AriaRuntimeCommon.jar;  org.formaria.awt.Applet

The AriaRuntimeCommon jar is the minimum level of library support that can be used with Aria. It is a version of the Aria core compiled for early JDKs (including the Java environment embedded in Microsoft's Internet Explorer).

To use a fuller more functional JDK, for example to access the Swing toolkit instead of the AWT simply change the startup file to use this command:

Command-line startup for Swing

 java -classpath .;AriaRuntimeCommon.jar; org.formaria.swing.Applet

Running this command will create a Swing user interface (UI) for the application. The two versions of the application should look pretty much the same.

This little example immediately shows a number of the benefits of Aria and XML. Most obviously the UI declaration is very small and compact. Consider all the code needed to get such an example up and running in many languages. Secondly the approach of separating the UI declaration from the implementation makes it easy to switch that implementation, as shown above in switching from the AWT to Swing toolkits.

Hello world redux

Another much touted benefit of Aria is its close integration with Java and the ability to declare the UI in XML or in Java. To emphasize this let's see how we can build the same thing in Java.

This time instead of creating ' home.xml ' we need to create a Java class. Using the normal naming conventions and capitalization we will call this class ' Home.java '. The Java code needed is as follows:

Java UI class

import org.formaria.aria.*;
import org.formaria.awt.*;
 
public class Home extends Page
{
  public Home()
  {
    addComponent( Page.LABEL, 32, 37, 100, 29, "Hello World" );
  }
 }

Now while this isn't as compact as the XML declaration it is nonetheless a little more compact than the traditional Java code used for such an example.

To run this example there is of course another step required, that is, to compile the Java code. This can be done from the command-line, in the root directory of the project. Just type the following command:

Command-line startup for compilation of the Java class

javac Home.java

This should create a file called ' Home.class ' in the same directory. The application can then be run in the very same way as the XML version. The underlying Aria will try loading an an XML file in preference to a Java class, so if it finds your XML file first then that will be used instead of the Java class even if the two files are in the same folder.

Beyond HelloWorld

While the HelloWorld examples offer a minimal way of getting started with Aria it is not normal. Aria can use many different resources and settings to configure and run an application. The HelloWorld examples relied on default settings for most of the Aria configuration.

Normally Aria applications are configured via a startup properties file. This file can be specified as a command-line argument:

Command-line startup using a startup properties file

 java -classpath .;AriaRuntimeCommon.jar; org.formaria.awt.Applet startup.properties

Or, if no command-line argument is provided Aria will look for ' startup.properties '. (And remember that the startup file is regenerated by Aria whenever an application is saved. Aria itself uses a file project.aria to store the properties that are written to the startup.properties file).

It is also useful to separate the various components of an Aria project into separate sub-directories. Thus the XML declarations for pages are put into the ' pages ' sub-directory, while the Java source files are places in the ' src ' sub-directory. Other resources such as images are placed in the ' resources ' sub-directory and finally localization files are placed in the ' lang ' subdirectory.

When using Aria (as we will see in the next chapter), a special class/resource loader is built-in and can locate files in these subdirectories without the need for them to appear on the classpath.

The startup file contains settings that control much of how Aria is configured. Some of the more commonly used configuration settings are shown below and could be used for the HelloWorld example.

Startup properties

CenterWin=true
ClientHeight=480
ClientWidth=640
StartClass=Home
Title=A simple HelloWorld example
StyleFile=styles.xml
UseWindow=true
StartPackage=aria.projects.helloworld

The purpose of these settings is as follows:

Building a simple address form

Most applications require user interaction and some data capture. Typical of this is entry of user details including name, telephone numbers and addresses.

This example goes beyond what was used in HelloWorld and shows some of the major steps in creating an attractive UI. We will start by creating a very simple form and then we will apply some style information to improve the look. In later sections this example will be expanded to produce a fully working, full featured form.

To start with we need a declaration of the input fields needed to capture the user input. We will use XML for this, and at its simplest this looks like the following:

An address form/page declared in XML

 <Page>
  <Components>
    <Label x="42" y="61" w="103" h="20" content="First Name:" alignment="Right"/>
    <Label x="42" y="85" w="102" h="20" content="Last Name:" alignment="Right"/>
    <Label x="42" y="116" w="102" h="20" content="Telephone:" alignment="Right"/>
    <Label x="42" y="137" w="102" h="20" content="Fax:" alignment="Right"/>
    <Label x="42" y="161" w="102" h="20" content="Mobile:" alignment="Right"/>
    <Label x="42" y="196" w="102" h="20" content="Address:" alignment="Right"/>
    <Edit name="firstNameEdit" x="154" y="62" w="100" h="20"/>
    <Edit name="lastNameEdit" x="154" y="85" w="100" h="20"/>
    <Edit name="phoneEdit" x="155" y="115" w="100" h="20"/>
    <Edit name="faxEdit" x="155" y="137" w="100" h="20" />
    <Edit name="mobileEdit" x="154" y="160" w="100" h="20" />
    <Edit name="address1Edit" x="155" y="198" w="248" h="20" />
    <Edit name="address2Edit" x="155" y="222" w="248" h="20" />
    <Edit name="address3Edit" x="155" y="246" w="249" h="20" />
  </Components>
</Page>

In the above declaration the Label fields are all right aligned and the edit fields are all named. We name the edit fields as later we will want to interact with them programmatically.

This form is basic and does not include any formatting specific to any region. The address is comprised of three lines whereas most applications would further customize addresses for things like post or zip codes. We leave such customization as a user exercise as it will not affect the overall behavior of the form.

Note also that the form is laid out using absolute positioning and that in general it is better to use layout managers for the positioning of components (again, this will be covered in later chapters).

Generally the order in which the components are declared is of little importance, but it is in this order that the components are added to the container and therefore this dictates the z-order of the components. The z-order may be of interest if components overlap.

Applying style

To improve the appearance of the form we apply some styling information. This style information simply consists of the name of a style to use when rendering the component.

Aria includes a style editor for interactively setting up the colours and fonts that comprise styles. These styles can then be interactively applied to a component or alternatively the styles can be applied via the Java code as the application executes.

The style details are stored in an XML file pointed to by the startup parameter ' StyleFile '. In the absence of a file name the files ' styles.xml ' is used. A typical style file includes colour and font information as below:

A typical style file

 <styles>
        <style name="banner">
            <color_back value="ffffff"/>
            <color_fore value="0000ff"/>
            <font_face value="arial"/>
            <font_size value="10"/>
            <font_weight value="0"/>
            <font_italic value="0"/>
        </style>
        <style name="base">
            <color_back value="ffffff"/>
            <color_fore value="0000ff"/>
            <font_face value="arial"/>
            <font_size value="10"/>
            <font_weight value="0"/>
            <font_italic value="0"/>
        </style>
        <style name="Caption">
            <color_back value="ffffff"/>
            <color_fore value="008800"/>
            <font_face value="arial"/>
            <font_size value="11"/>
            <font_weight value="0"/>
            <font_italic value="0"/>
            <style name="CaptionSmall">
              <font_size value="8"/>
              <font_italic value="1"/>
        </style>
        </style>
        <style name="footer">
            <color_back value="ffffff"/>
		...
    </styles>

Styles are determined from this hierarchy so that in the above example the style ' CaptionSmall ' is of the same font and colour except with a smaller point size and italicized.

To apply a style to a component you just need to reference the style in the page's XML declaration. Thus applying style to the labels the above address form becomes:

An XML page using styles

 <Page>
  <Components>
    <Label x="42" y="61" w="103" h="20" content="First Name:" alignment="Right" 
      style="Caption"/>
    <Label x="42" y="85" w="102" h="20" content="Last Name:" alignment="Right" 
      style="Caption"/>
    <Label x="42" y="116" w="102" h="20" content="Telephone:" alignment="Right" 
      style="Caption"/>
    <Label x="42" y="137" w="102" h="20" content="Fax:" alignment="Right" 
      style="Caption"/>
    <Label x="42" y="161" w="102" h="20" content="Mobile:" alignment="Right" 
      style="Caption"/>
    <Label x="42" y="196" w="102" h="20" content="Address:" alignment="Right" 
      style="Caption"/>
    <Edit name="firstNameEdit" x="154" y="62" w="100" h="20"/>
    <Edit name="lastNameEdit" x="154" y="85" w="100" h="20"/>
    <Edit name="phoneEdit" x="155" y="115" w="100" h="20"/>
    <Edit name="faxEdit" x="155" y="137" w="100" h="20" />
    <Edit name="mobileEdit" x="154" y="160" w="100" h="20" />
    <Edit name="address1Edit" x="155" y="198" w="248" h="20" />
    <Edit name="address2Edit" x="155" y="222" w="248" h="20" />
    <Edit name="address3Edit" x="155" y="246" w="249" h="20" />
  </Components>
</Page>

Validating user inputs

When a form's data is eventually processed it helps if the data is appropriate for the intended process as much error checking can be eliminated. It also helps if the user is informed about input errors as early as possible.

Aria provides several levels of input validation. Firstly some of the input fields, like edit controls can be configured to accept a limited range of inputs (numbers, dates, passwords) and secondly the input can be validated using declarative validations.

Validations are rules that are applied to input fields. Aria takes the approach that these rules are reusable and therefore the validation rules are declared separate to the UI. The startup file is used to point at the validations declaration or by default a filename of validations.xml is assumed. Some examples of the validation rules are:

A validation rules file

 <Validations>
  	<validation name="age" type="minmax" min="18" max="100" 
      msg="Age must be between 18 and 100"
      mandatory="true"/>
	  <validation name="firstname" type="mandatory" 
      msg="Firstname cannot be blank"/>
	  <validation name="surname" type="mandatory" 
      msg="Surname cannot be blank"/>
</Validations>

The exact content and attributes of the rule depend on the type of validation being configured. The first example shows a min-max rule and specifies the limits for the range. The second and third examples are simple checks for the presence of an input value, a mandatory or obligatory value. Each of the examples includes a message that is shown in case an error is detected.

Validation rule checking is triggered whenever an input field loses input focus or when the user attempts to change the page or navigate to another page.

Of course the rules have to be assigned or attached to the appropriate input field and this is done in the page's XML file. For simplicity we will just assign the name checking but the complete example contains a fuller set of input validations. Thus the page becomes:

An XML page using validation rules

 <Page>
  <Components>
    <Label x="42" y="61" w="103" h="20" content="First Name:" alignment="Right" 
      style="Caption"/>
    <Label x="42" y="85" w="102" h="20" content="Last Name:" alignment="Right" 
      style="Caption"/>
    <Label x="42" y="116" w="102" h="20" content="Telephone:" alignment="Right" 
      style="Caption"/>
    <Label x="42" y="137" w="102" h="20" content="Fax:" alignment="Right" 
      style="Caption"/>
    <Label x="42" y="161" w="102" h="20" content="Mobile:" alignment="Right" 
      style="Caption"/>
    <Label x="42" y="196" w="102" h="20" content="Address:" alignment="Right" 
      style="Caption"/>
    <Edit name="firstNameEdit" x="154" y="62" w="100" h="20"/>
    <Edit name="lastNameEdit" x="154" y="85" w="100" h="20"/>
    <Edit name="phoneEdit" x="155" y="115" w="100" h="20"/>
    <Edit name="faxEdit" x="155" y="137" w="100" h="20" />
    <Edit name="mobileEdit" x="154" y="160" w="100" h="20" />
    <Edit name="address1Edit" x="155" y="198" w="248" h="20" />
    <Edit name="address2Edit" x="155" y="222" w="248" h="20" />
    <Edit name="address3Edit" x="155" y="246" w="249" h="20" />
  </Components>
  <Validations>
    <validation rule="firstname" target="firstNameEdit"/>
    <validation rule="surname" target="lastNameEdit"/>
  </Validations>
</Page>

Using data

A form like the address page can not only be used to capture data but it can also be used to edit data. Aria includes an extensive data model that allows the UI to be separated from the data so that the applications logic need not know how to get, set or maintain values in the UI. The Aria data model is also an abstract hierarchy and can be referred to with expressions. Furthermore the application does not need to know how the data is actually stored as the model will assign storage as needed. Thus the application need only specify where to store the data in the model, for example the address form can be modified to store its edit values in the model.

The figure above shows a typical situation where data is transferred from page to page without one page needing to reference the other directly. Instead the pages refer to the data in model and they are thus less dependant on one another. In the same way the application code can refer to data in the model and the code can even update the data used by the two pages. Again the code is not dependant directly upon the user interface pages.

Normally the links between the components on user interface pages are declared as data bindings.

An XML page binding data to the user-interface components

 <Page>
  <Components>
    <Label x="42" y="61" w="103" h="20" content="First Name:" alignment="Right" 
      style="Caption"/>
    <Label x="42" y="85" w="102" h="20" content="Last Name:" alignment="Right" 
      style="Caption"/>
    <Label x="42" y="116" w="102" h="20" content="Telephone:" alignment="Right" 
      style="Caption"/>
    <Label x="42" y="137" w="102" h="20" content="Fax:" alignment="Right" 
      style="Caption"/>
    <Label x="42" y="161" w="102" h="20" content="Mobile:" alignment="Right" 
      style="Caption"/>
    <Label x="42" y="196" w="102" h="20" content="Address:" alignment="Right" 
      style="Caption"/>
    <Edit name="firstNameEdit" x="154" y="62" w="100" h="20"/>
    <Edit name="lastNameEdit" x="154" y="85" w="100" h="20"/>
    <Edit name="phoneEdit" x="155" y="115" w="100" h="20"/>
    <Edit name="faxEdit" x="155" y="137" w="100" h="20" />
    <Edit name="mobileEdit" x="154" y="160" w="100" h="20" />
    <Edit name="address1Edit" x="155" y="198" w="248" h="20" />
    <Edit name="address2Edit" x="155" y="222" w="248" h="20" />
    <Edit name="address3Edit" x="155" y="246" w="249" h="20" />
  </Components>
  <Validations>
    <validation rule="firstname" target="firstNameEdit"/>
    <validation rule="surname" target="lastNameEdit"/>
  </Validations>
  <Data>
    <Bind target="firstNameEdit" source="customer/firstName"
    <Bind target="lastNameEdit" source="customer/lastName"
    <Bind target="phoneEdit" source="customer/phone"
    <Bind target="faxEdit" source="customer/fax"
    <Bind target="mobileEdit" source="customer/mobile"
    <Bind target="address1Edit" source="customer/addr1"
    <Bind target="address2Edit" source="customer/addr2"
    <Bind target="address3Edit" source="customer/addr3"
  </Data>
</Page>

Aria will automatically update the form so that it displays the data from the model whenever the page is displayed. Aria will also save the data automatically whenever the page goes out of context.

An application has also programmable control over the model and its interaction with the UI. Bindings can be changed and can be made to dynamically point to other locations, but that will be covered in more detail in later chapters.

The data model can be primed with data by configuring a data source via the startup file. The startup file can name a datasets file (datasets.xml by default). The datasets file in turn points to individual data sources. For example datasets.xml is often configured as follows:

A sample dataset reference

<DataSources>
        <DataSource name="InitialValues" filename="datasources.xml"/>
</DataSources

The data source name doesn't have any great significance, but the filename attribute points to the actual data. For this address form example the data might appear as follows:

A sample dataset

<Datasets>
  <dataset id="customer">
     <item value="John" id="firstName"/>
     <item value="Doe" id="lastName"/>
     <item value="353-1-8978677" id="phone"/>
     <item value="Ms" id="fax"/>
     <item value="Dr" id="mobile"/>
     <item value="Rev" id="addr1"/>
     <item value="Fr" id="addr2"/>
     <item value="Fr" id="addr2"/>
  </dataset>
</Datasets>

This sample data will populate the address form when the form is first shown.

Responding to events

So far we have covered the UI declaration, the validations and the data model but all of that is of little benefit unless we can apply some application logic.

Aria relies on Java for its programming and at the core of this is the Page class. Each page in Aria must be derived from this class. Fortunately this is a fairly simple task.

To demonstrate how application logic can be invoked we will add a button to the form so that a new or next page can be displayed. First though we will create the stub of the page's logic code:

A simple Java class with an event handler

package aria.projects.addresses;
 
import org.formaria.aria.*;
import org.formaria.swing.*;
 
public class Welcome extends Page
{
        public Welcome()
        {
        }
 
        public void next()
        	{	
        	}
}

This class contains the stub of the next method that we will later fill out to implement the required logic, but for now we still need to connect it to the UI.

The first step in connecting the page to the new class is to change the XML page definition so that it refers to the class, thus the Page element becomes:

Referencing the Java class in the page's XML declaration

<Page class="aria.projects.addresses.Welcome">

Finally we need to trigger the method in response to the button click event, or in AWT/Swing the action event. To this we add an event handler declaration:

Adding an event handler to the page's XML

<event target="nextBtn" method="next" type="ActionHandler">

The complete form now appears like this:

The complete form

<Page class="aria.projects.addresses.Welcome">
  <Components>
    <Label x="42" y="61" w="103" h="20" content="First Name:" alignment="Right" 
      style="Caption"/>
    <Label x="42" y="85" w="102" h="20" content="Last Name:" alignment="Right" 
      style="Caption"/>
    <Label x="42" y="116" w="102" h="20" content="Telephone:" alignment="Right" 
      style="Caption"/>
    <Label x="42" y="137" w="102" h="20" content="Fax:" alignment="Right" 
      style="Caption"/>
    <Label x="42" y="161" w="102" h="20" content="Mobile:" alignment="Right" 
      style="Caption"/>
    <Label x="42" y="196" w="102" h="20" content="Address:" alignment="Right" 
      style="Caption"/>
    <Edit name="firstNameEdit" x="154" y="62" w="100" h="20"/>
    <Edit name="lastNameEdit" x="154" y="85" w="100" h="20"/>
    <Edit name="phoneEdit" x="155" y="115" w="100" h="20"/>
    <Edit name="faxEdit" x="155" y="137" w="100" h="20" />
    <Edit name="mobileEdit" x="154" y="160" w="100" h="20" />
    <Edit name="address1Edit" x="155" y="198" w="248" h="20" />
    <Edit name="address2Edit" x="155" y="222" w="248" h="20" />
    <Edit name="address3Edit" x="155" y="246" w="249" h="20" />
  </Components>
  <Validations>
    <validation rule="firstname" target="firstNameEdit"/>
    <validation rule="surname" target="lastNameEdit"/>
  </Validations>
  <Data>
    <Bind target="firstNameEdit" source="customer/firstName"
    <Bind target="lastNameEdit" source="customer/lastName"
    <Bind target="phoneEdit" source="customer/phone"
    <Bind target="faxEdit" source="customer/fax"
    <Bind target="mobileEdit" source="customer/mobile"
    <Bind target="address1Edit" source="customer/addr1"
    <Bind target="address2Edit" source="customer/addr2"
    <Bind target="address3Edit" source="customer/addr3"
  </Data>
  <Events>
    <event target="nextBtn" method="next" type="ActionHandler">
  </Events>
</Page>

Changing pages

One of the most common tasks in building an application is providing a means of navigating around the application and since the *Page is the basis of all pages in an Aria application the Page class provides methods for changing pages.

To show the second page we modify the 'next' method.

Implementing the event handler

package aria.projects.addresses;
 
import org.formaria.aria.*;
import org.formaria.swing.*;
 
public class Welcome extends Page
{
        public Welcome()
        {
        }
 
        public void next()
        	{	
         	  pageMgr.showPage( "pageTwo" );
        	}
}

This new code will cause the application to display a page called "pageTwo" whenever the next button is pressed. If the application was coded as above, then it would not be strictly necessarry as Aria 3.0 allows the shortcut of specifying the showPage(pageName) expressions directly within the event handler for the component in question - in this case a button. (Of course some implementation of this new page is required, but that is left as a user exercise).

The pages within an application are managed by the framework and a component on the project called the page manager. Whenever a request is made to show a page the page manager loads the page either from a Java class or by building a page from an XML file. The page is informed of its creation via its pageCreated method once all of its components have been constructed and the new page object is ready for use.

Once it has created the page the page manager requests that the applet displays the page. The page may be loaded as part of a frameset in which case the area in which it is displayed (these areas are named as part of the frameset setup). If a frameset is not being used the default target area is used, this is called the ` content ' area.

Once the page has been successfully displayed its pageActivated method is invoked.

In displaying the page the page manager first deactivates any page that is currently displayed in the new page's target area. Thus in the case of displaying page `P2' in the above figure the old page `P1' must be removed from the target area. In doing so the page manager calls the pageDeactivated method to indicate the change of state.

Projects

Aria applications are organized into projects with a well defined structure. The project acts to organize and coordinate the project and its resources. At both design and run time the project plays a crucial role in the behavior of the application. To help you better understand this behavior we have included an overview of a project and what it does for a Aria application.

A project's role

A project is a collection of the resources used in an application. The project object within a Aria application manages these resources and provides many facilities for loading and storing resources.

As many of the components in a Aria application are loosely bound to one another some coordination of these otherwise disparate resources is required. The project therefore acts as a central coordinating resource and in programming an application the project is often the first place to look when trying to reference a component of the application.

Aria projects also act as a way of ring-fencing the resources used by an application and the application context. The idea behind this is that you could have multiple projects running with a single JVM and you would therefore need to manage the resources of each project separately..

Originally Aria had used singletons (classes containing a static self reference) to provide easy access to key resource classes such as the StyleManager that one might want to access in a great variety of places. While the singleton pattern made it easy to access these resources it greatly complicated initialization and the project lifecycle, never mind making it difficult to handle more than one project at a time. Aria 2.0 did away with the singletons and now all major objects are owned by the individual projects and ultimately by the project manager. The stricter hierarchy that this imposes makes managing an application somewhat easier and makes initialization clearer

Creating a new project

A new project can be setup using the Aria or AriaEditor plug-ins by starting the New Project Wizard from the file menu. Under NetBeans the wizard creates a new project and the associated infrastructure for a normal Java application project. The new project is immediately ready for running and debugging. Similarly on Eclipse, a complet project is setup and again you can immediately run or debug the application.

The process of creating a new project involves a few steps and choices which will influence the style of the application. Most of these steps can be undone or modified at a later stage, so don't worry too much about the selected options. In most cases you can just choose the default options.

The wizard is staightforward and once the project has been created and open, the project editor shows the sames choices that were available while using the New Project Wizard. The role and use of the various options is explained more in the following paragraphs.

Project setup

A project file is the key to a project. Aria's project files are contained in the root of the project and have a .aria extension. The file is an XML file, but fortunately Aria provides an editor for all the project's settings:

The editor is displayed automatically whenever a project folder is opened. The project also manages access to a number of folders. Each folder contains a distinct type of resource. Here is a summary of those folders:

Project folders

Folder	Usage
Pages	Stores the XML page descriptions
Lang	Stores the language files used for translation of the application.
Resources	Holds various resources used in the project including graphics, configuration files and so on.
Src	The source code for the Java classes is held in this folder. Another folder (classes) may also be created depending on the configuration. The classes folder is a temporary folder and may be deleted at any time.

General setup

When the project initially opens the setup page of the project settings is displayed.

The settings on this page are general initialization and project description settings.

These settings can be configured at any time in the life of the project, but of course they may affect the runtime behavior. For example it is possible to switch widget sets but doing so may affect your business logic code if you have done something that specifically references an individual widget set. Similarly resizing a page to a smaller size may result in components not being visible to the end user.

If there is a problem you can always revert your settings to the previous values and your setup should be restored.

The properties on this page are:

General properties

Property	Usage
Project name	This is the name by which the project is identified within Aria.
Application title	The title of the application. The title is displayed on the application title bar at run-time for a normal application. Some applications do not display a title bar.
Screen size	The width and height of the page. The application frame is adjusted so that the pages are the size specified here. The drop down provides a short-cut to some common sizes and the edit fields allow more precise adjustment of the size.
Centre on screen	Check this option for the application to start-up in the centre of the primary display. Otherwise the application will start in the top left of the display.
Popup window	Check this option to use a popup window. The option can be useful for creation of full screen like applications as no border or title bar is displayed. The option may also be of use for applets where it is not intended that the applet is to appear `embedded' within the html page.
Widget set	Aria applications can run with a number of widget sets and the framework provides a certain level of isolation from the specifics of the widget set. You can use this option to choose or switch widget sets. Support for other widget sets is available outside of the editor.
Initial page name	You can select the page to display when the application starts using this option. If a frameset is being used this page will be displayed in the default content frame.
Package name	Specify the default package name for your application code here. The package name should follow the normal Java package naming conventions.
Log level	Aria provides a logging facility for you applications when they are run with debug libraries. Various levels of verbosity can be chosen. The log is often the first place to look if you encounter problems when running the application.

Frames setup

Aria supports the notion of framesets much the same way as HTML does. Frames are subdivisions of the screen or more precisely the applications client area. The frameset divides this space into several target areas with each target area containing a page. The target areas can be updated by displaying new pages within one or another.

It is entirely up to the individual application how these frames are updated. If no target area is specified when displaying a page the default content target is updated.

The content of some targets can be long running to provide application wide facilities such as navigation panels, headers and footers. An application need not employ a frameset.

The frameset is based on a border area and the editor page visually reflects this setup. Each of the areas can be named and a size can be suggested for the area. At least one target area must be included and normally this is the content target.

Files Setup

Rather than try to shoehorn everything into one configuration file Aria uses a main configuration file, the project file to direct the framework to individual configuration files for particular elements of the project. These configuration files are identified on the file page.

Each configuration file can be located by clicking on the button next to the edit field to popup the file chooser.

The list of files is not exhaustive and as we will see later there may be more configuration files needed for some projects. Most of the configuration files are optional so it is not fatal if you are missing one or another. The system will attempt to load a default if one file is missing and any difficulty is logged.

The individual files are:

File settings

File	Usage
Styles	The style file contains information about the colours and fonts used within an application much like cascading stylesheets are used for HTML. By default the style file is located in the resources folder and is called styles.xml.
Frames	As mentioned above an application can optionally use a frameset. The frameset configuration is saved to the file specified here. If no frames file is found then it is assumed that the application has a single content area called content. The default frameset file is frames.xml and it should be found in the pages folder.
Model data	Aria applications include a rich data model. The data model can be configured in a wide variety of ways with various data sources contributing to the overall model. Loading of the data model is initiated by reading of the model data configuration specified by the file name here. The default file is datasets.xml and it is normally placed in the resources folder.
Validation rules	Validation rules are rules that specify what is valid data, they constrain the user input to particular ranges of data that is at first glance acceptable to the application. The validation rules are configured via the validations file specified here.
Look and feel	The look and feel of the application only requires a choice of files if the Synth look and feel is employed.

Extensions setup

Aria offers numerous extension possibilities an some of these extensions can be configured here.

The most common extensions, adding a component factory, adding and data binding factory and adding a validation factory can all be configured here.

The add option allows you to select the class that implements the appropriate extension.

It is worth noting that Aria now includes a facility to register components via XML so you do not need to build a custom component factory to use additional components. The component factories are covered in detail in later chapters.

Extra setup

As an extensible framework it is difficult if not impossible for Aria to know all the configuration parameters in advance. Therefore we have provided a generic facility to specify project configuration parameters.

The Extra page provides a table where you can add, remove and edit project settings. These settings are persisted to the project file.

Extensions can install additional parameters and third party configuration parameters are likely to appear in this list. Aria itself uses this facility for some of its optional parameters and you will see this project editing facility referenced in later chapters.

Services provided

From a programming perspective the project provides the following services:

• File access
• Image loading
• Startup parameter management
• Resource management
• Pages
• Styles
• Images
• Data model
• Classpaths

Aria tries to simplify access to resources and therefore the project sometime needs to search several possible locations to find an individual resource. At it simplest a Aria project normally refers to:

• The project root,
• The pages folder,
• The lang folder,
• The resources folder,
• The Jar classpaths

The project can be accessed through the ProjectManager class which provides a static accessor:

Locating a project

Project currentProject = ProjectManger.getCurrentProject();

This manual refers to the project on many occasions and this serves to highlight the pivotal role that a project has in managing a project. As mentioned above, when developing code within a Aria application the project is also often the first place to look when trying to find a particular resource.

As of Aria 2.0 the Page class includes a reference project to the current project so the above code may no longer be necessary in most situations.

Build Pages with the Page Designer

Once you have setup a project the next task is to create some content, and this means adding pages to you application. Aria includes many advanced features for editing pages, forms and other content for you rapplication, but this chapter gives a flying overview of the main features of the editor.

The role of pages

Pages are one of the main the building blocks of a Aria application and in most cases they tie in closely with the lifecycle and navigation of your applications main elements. Pages are designed to help you lead through the story (or more prosaically, the workflow) of your application, but pages are still quite flexible and not so strictly tied to the navigation that they restrict how you present your information, and later we will see how the role of pages is affected by the application style.

Creating a new page

Once a project has been created you can use the New Page Wizard to create a new page. The wizard is very simple, just taking the name of the new page as an input. If you are using the Files view within NetBeans then you can right click on the `pages' folder and choose the New Aria Page... option.

Once the new page has been created it is opened in the page designer.

Opening the page

The pages created by Aria are inserted into the pages folder, and this folder is automatically added to the project classspath. New pages are automatically opened, but existing ones can be opened by double-clicking on the page file or by choosing the Open option from the node's context menu. By default the page opens as a standalone page, but it can also be opened in the context of the pages named by the frameset, by choosing the Open in frameset command.

On Eclipse the behavior varies slightly and initially the default action when double clicking a page may be to open the page's XML in the default text editor, however once the page has first been opened subsequent double clicks will open the Aria page designer. Eclipse users may also have to open the AriaEditor perspective before all features of the page designer are available (see the Window|Show View|Other option).

Pages must belong to a project and normally a page can only exist or operate within the context of its project as the project provides access to the resources used by the page. Therefore to successfully use a page the owning project must first be opened, and to ensure this relationship is maintained Aria will open the project whenever you first attempt to open a page within a project.

For an overview of the main elements of the page designer please see .

Opening the page in a frameset

A page can also be opened as an element of the frameset (the content/center element) by choosing the Open in frameset command from the page node's context menu. When the page is opened in this way the page will be viewed as though the frameset devides the main window into named target areas that can be controller by the page manager. This editing mode assumes that the frameset is being used as part of an SDI (Single Document Interface) application even though the frameset can be used for other application styles.

Can should be taken with this editing mode it the pages referenced and opened by the framset are already open in other page designer windows. There will be a single instance of any page edited within the page designer and if the same page is opened in multple instances of the page designer then the changes made in one instance will affect the others (in fact the page being edited is just shown in the other instance of the designer once it becomes active).

The image below shows the Welcome page being as part of the frameset, in this case in the center of the frameset.

Preferred page size

If a page is bein used within a frameset it is not tied to any particular target area within the frameset and the application can instead chose to show it in any area. However, in practice the page will usually be shown in specific area and at a specific size. Some layouts can accomodate radical resizing depending on the content but for many it is useful to know the size that will be used for the default layout. By right clicking on a page's node you can choose the Preferred page size... option and set the default size for the component.

The dialog allows you to choose the area to use for the page based on the areas assigned by the frameset. Note that the application area is normally larger than the sum of the sizes of the pages held within the frameset as the application also includes decorations like borders and headers. Also not that even including the size consumed by headers and borders there may be some deviation if the application's end user has setup their computer with larger or smaller than normal fonts as default (this affects the header size) or tweak the operating system's user interface in a variety of ways. Using layout managers rather than absolute layout will help overcome the poblems caused by such differences between systems.

Adding components

Once the page has been opened for editing, adding components is straightforward. The component palette at the top right contains icons for most of the components that can be added to your application. If Aria is installed you will see two pages of components (two tabs) and you can also register new components or third party components for use in Aria (see See Working with components.).

To add a component, just click on the icon corresponding to the component you want to add, move the mouse to the point on the page where you want to insert the new component and click the mouse. The new component should be inserted at this point. If you do not recognise the icon for a component just let the mouse hover over the icon for a moment and you should see a tooltip telling you what type of component is represented by the icon.

If you have already added components to the page you may also be able to add component as children of existing components. Some components like panels and scrollpanes act as containers for other components, so to add a child to such a component just click on the container into which you want to insert your new component instead of the page.

Selecting and sizing a component

A component can be selected by clicking on the component, and multiple components can be selected by holding down the CTRL key while clicking on the components. (Only the common properties will be displayed in the property sheet)

A selected component (or components) can be moved by dragging it to another part of the page. The selected component can be sized by grabbing and dragging one of the selection handles.

The movement and positioning of the components will be affected by the grid and snapping properties of the page designer. You can access these propeties by right clicking on the page and selecting the appropriate options from the context menu.

If any of the snapping options are selected the components will snap to the appropriate positions so as to match the snap options. The arrow keys can also be used to move the components and moving the components with the arrow keys also honours the snapping properties of the page designer.

If the arrow keys are being used to manipulate the components holding down the CTRL key while using the keys cause the component size to vary instead of the position.

Sometimes the snapping options will make the components seem to stick to a particular position. A short sharp movement usually frees the component, but as an alternative you can type the coordinates or sizes directly into the component's property sheet to manipulate its position and size.

Equally, when dragging a component the size of the component may vary so that its edges honour the page designer's alignment properties, but when the component goes out of range of the snapping zone its size should be restored.

Nudging a component

A selected component can be nudged or moved using the arrow keys. Movements with the arrow keys are still influenced by the snap settings, the grid options and the layout managers and therefore using the arrow keys to nudge a component will lead to its size and positions being updated which can be desireable when properties have been changed via the property sheets.

Aligning components

The page designer properties also include the option to have components Snap to siblings so that components align with one another. When using this option and dragging components about the form alignment hints are briefly shown to indicate how one edge aligns, or snaps to another. When aligning edges the page designer attempts to allow for the operating system's recommendations for component spacing.

Setting up guides

Supplementing the snapping options are guides, which can either enforce layout considerations or merely act as a layout aide. Guides can be setup interactively once the designer has been placed into the edit mode, by clicking the button at the junction of the horizontal and vertical rulers. When in the mode the rulers change color.

In the (guide) edit mode, clicking on a ruler and dragging the mouse onto the page will add a new guide to the page. Equally a guide can be deleted by dragging it back to the ruler.

Further setup options for the guides can be configured by right clicking an individual guide and choosing Guide options... There options are covered in more detail in later sections (see See Guides.). You can also add columns and rows for regular form layouts by choosing the Setup columns... option.

Once the guides have been added you can select the Snap to guides option so that moving the components will snap them to the nearest guide within the snap zone. Setting this mode is not necessary if you wish to use the guides as a visual indication only. To exit the guide edit mode, again click on the button ath the junction of the rulers.

Layout managers and constraints

The final factor influencing the layout of components is the use of layout managers. Layout managers automatically adjust the size and position of a component when its parent has been resized. Each container (page or panel etc...) can have a layout manager, set via the property sheet for that container, and in turn each component can have layout constraints should the parent use constraints (some don't). For more information on how layout managers are used see See Layout..

In the context of the above overview of moving and sizing a component it should be noted that a layout manager will trump any of the above features and layout the component as it sees fit. Of course Aria's own layout managers may respect the positioning defined with the page designer, but this behavior varies from layout manager to layout manager.

Setting properties

When a component is selected the properties of that component are shown in a property sheet to the bottom right of the page designer.

Once the component properties are listed in the property sheet they can be set by clicking on the property value. The property can then be edited. Some properties will display a list of appropriate values from which you can select, whereas others will allow you freely enter a value of your choice. Editing of a property is normally completed by pressing the enter key, or by selecting another property or component. Once the new property has been entered the component is updated.

In-situ editing

For conveniece, a property sheet can be shown next to the component under the cursor. This mode of editing properties is known as in-situ editing. The in-situ editing mode can be changed by toggling the mode using the toolbar toggle button. The mode can be turned on and off, or a full property sheet, a cut-down mode can be shown.

Just as with the property sheet you click on a property value to edit that value. The in-situ editor follows the cursor after a short delay, so some care may be needed when moving the cursor from the component to the in-situ property sheet, but after some experimentation it should save you some mouse clicks and cursor movement.

Normally the page properties do not show in the in situ editor as they would constantly get in the way of normal editing, but the page properties can be displayed in the in situ editor by moving the cursor to the top left corner of the page while holding down the CTRL key.

Similarly, the in situ editor normally masks components beneath the editor to avoid unintentionally selecting other components while trying to edit a components properties. However sometimes it is desireable to select a component that is obscured by the in situ editor, and to do so hold the CTRL key down while moving the cursor.

Quickly setting the content

Another useful labour saving shortcut is to double click a component so that the editor for the default property is displayed. Typically the default property controls the content or text displayed in the component, or else the component name.

Styling a component

Components can be styled in a number of ways and depending upon the individual component there may be one or more styles. Like any other property the styles can be set using the property sheet or with the in-situ property sheet. AriaEditor also includes a style palette, located in the same area as the property sheet (but on the tab marked `Styles' ).

To set the style using the style palette select a component or components and double click a style within the style palette. The styles (mostly the colours and fonts) associated with the style are applied to the component. If the style is changed at some later stage then the component will be updated to reflected the modified style.

New styls can be configured by right clicking on a style in the style palette.

Delete, Cut, Copy and Paste

You can delete, cut, copy and paste components using the normal keyboad shortcuts, and by right clicking and choosing from the context menu. When components are cut and pasted they can be inserted multiple times. The insertion point is at the cursor position.

As the components are added they are renamed to avoid a name collision. Components can also be cut and pasted between panels and pages.

Locking components

Components can be locked so that they are not moved or modified accidentally. To lock a component right click on the component and choose lock from the context menu. The component can also be locked by choosing the component within the Component Inspector and using the inspector's context menu.

When a component is locked using the Component Inspector its children are also locked, and therefore a combination of the two context menus can help you quicked toggle the locking status of a hierarchy of components.

Hidden components

Components can be shown or hidden usisng the Visible property via the property sheets. Of course an invisible component cannot be selected in the normal way within the page designer, however the component will still be listed in the component inspector and selected via the component inspector, and once selected the component properties can be changed via the proeprty sheet.

Hooking up code

A page layout without code and functionality is little use and therefore the property sheet lists the events that can be associated with the selected component.

Adding an event handler is simply a matter of inserting the name of the event's response handler method in the property sheet. Once the value has been entered, the Java source code for the handler is inserted. Under the hood, the Aria framework takes care of the event handling plumbing.

In some cases you may not want to add a new event handler, so instead you can select the existing methods as the event handler from a list of methods shown in the property sheet.

Inserting predefined code

Within the source code editor you have access to all the normal code templates available within the IDE (be that NetBeans or Eclipse). In addition to the templates the source code editor's context menu include the Run Aria helper... option. Choosing this option pops up a dialog that lists some common Aria code fragments (this list can be extended).

Working with data

Aria supports many data formats and data source (including customized datasources) and the Aria plug-in allows for easy setup of the data sources and the data bindings that will be used to channel data into the on screen components.

Setting up a database table

Within NetBeans the Runtime window allows access to servers and other runtime resources. To setup a database within the Runtime view, first open the view from the Window menu and right click the Databases node. Add a database, following the instructions provided by the IDE. Even if you intend to use a standalone database like HSQLDB it is worth setting the database in server mode so that you can make best use of the tools provided by the IDE.

Once the database server has been setup choose the Aria | Visualization | Show the data visualizer view to open the Data Visualizer . Once open you can drag and drop tables from the Runtime | Database to the Data Visualizer to register the table and configure it for use in standalone application. A project must be open before the visualizer can be opened.

Setting up POJOs

TODO insert screen shots of setting a data binding

Setting up static data

For some nodes you can configure the data model as you go within the visualizer (you can also do this at runtime). The data visualizer includes toolbar buttons to allow you select the paths and to add or delete nodes. See Data binding. for more detailed information on using and managing data bindings.

Binding

Once data is available in the visualizer you can use it in multiple ways. The simplest way of setting up a binding is to drag and drop a node to the component to which it will be bound. Using drag and drop in this way fully configures the bindings.

For some types of nodes and some types of data a popup dialog may appear requesting further specification of the data binding attributes, for instance specifying the field to display in a drop down list or combo box.

Alternatively you can copy and paste the data path so as to later insert it in a data binding specification or path.

TODO insert screen shots of setting a data source

TODO insert screen shots of setting a data binding

Working with validations

TODO insert screen shots of setting a data source

And now for the XML

At times you may wish to work with XML directly, or use features that cannot be coded directly with the page designer and therefore the XML is just a click away. The page designer's toolbar has a button marked XML , which when clicked shows the XML editor.

You can switch back and forth between the XML and the Design view of the page designer at any time and the views are updated in the process.

Working with included pages

An advanced feature of Aria, that we will see more of in later chapters, is that one page can be included in another. The page designer offers some support for this, allowing you view and edit pages that have been composed in this way, however the editor does not yet allow you to choose which page a new component will be belong to. Instead the page designer uses the component hierarchy to decide what components belong to what page. Therefore the children of a component such as a panel belong to an included panel will themselves belong to the included panel.

Saving

Finally, your edits need to be saved and this can be done on a page by page basis using the normal File | Save menu action, or all edits can be saved at once using the File | Save All menu action.

Modified pages or resources are shown in the Files or Project view with a red dot or with an asterisk. When saved the dot/asterisk should disappear.

Building Pages with XML

As we have already seen, Aria allows pages to be built without having to write Java code to setup the user interface components. The functionality afforded by this process is not complex and contributes greatly towards the goal of removing trivial screen building from your Java code.

Pages built with Aria can be integrated with pages coded directly in Java and with Java classes containing just your application logic. Very little change is needed to the application to employ this package, in fact all you need do is use the XML page names when making requests to show a page.

The next few sections provide an overview of what can be done with the XML declarations. Later chapters go into greater detail about specific features such as validation and data binding.

Basic form building

The basic components and layout of a user interface can be described in an external XML. The XML file contains entries for the individual components on the page which are processed by the Aria framework when it constructs a page.

You can think of a page as panel or container that holds your user interface components. The page is constructed from either a Java class or from an XML file by the page manager component built into the Aria framework.

In processing the XML the framework constructs a page object and adds the specified components to it. The page and the objects added are all normal Java components so once the page has been setup you can interact with all the components as though the page had been constructed with Java code.

A snippet of the XML file for the form shown above is shown below.

A basic address page described in XML

 <?xml version="1.0" encoding="UTF-8"?></P>
<P>
 <Page>
   <Components>
     <Panel x="10" y="10" w="210" h="80" border="1">
       <Label x="5" y="10" w="90" h="20" content="Firstname:" style="prompt"/>
       <Edit x="100" y="10" w="100" h="20" content="Joe"/>
       <Label x="5" y="30" w="90" h="20" content="Surname:" style="prompt"/>
       <Edit x="100" y="30" w="100" h="20" content="Bloggs"/>
       <Label x="5" y="50" w="90" h="20" content="Age:" style="prompt"/>
       <Edit x="100" y="50" w="100" h="20" content="38"/>
     </Panel>
   </Components>
 </Page>

Perhaps the most important thing to note about this sample is that there is absolutely no Java code written in order to display it.

This absence of a Java class leads to the important question of how it is possible for a page to be both and XML file and a Java class. The answer of course is that it isn't. Aria constructs an instance of a Java class, the Page class by default and populates it with the components you have specified in the XML.

Indeed, you can even customize this page class to add your own functionality and behavior by specifying the class to create and populate (as in the example below where an instance of QuestionPage is constructed).

Much can be achieved with this simple step of putting the user interface declaration into XML. Some additional processing and aggregation of content can be performed, for example by adding a new XML element it is possible to allows for repeated inclusion of children.

Thus one page can be composed of multiple pages.

An advanced page decription showing repeating elements, embedded data etc

 <?xml version="1.0" encoding="UTF-8"?>
 <Page next="Finished" layout="Border" class="org.formaria.xforms.awt.QuestionPage">
 <Components>
         <Panel layout="Box" layoutStyle="0" constraint="center">
             <Repeat while="hasMoreQuestions()">
                 <Include file="template"/>
             </Repeat>
         </Panel>
 </Components>

This aggregation further extends the separation of UI from the data model by allowing multiple instances of a component or set of components to be included. The data or content displayed by these components can be even pulled from a data model on demand.

Built-in components

Aria includes a set of built-in components that can be used interchangeably in Swing or AWT applications. These components are listed below along with a brief description. The XML element name is shown in brackets[]. Note that this name is not case sensitive.

More details of these controls can be found in the appendix.

The component can be used by creating an child element of the ' Components ' element or one of its children (a panel for instance). The new element should begin with the name of the component type (as listed above in parenthesis), for example a new button is described as

Specifying a button

The actual attributes depend on the component type.

Common properties

Although the full set of attributes for a component are specific to that component, a subset of these attributes are shared by all components. These attributes are optional and need not be specified in all cases.

The attribute names in the XML are case insensitive, but generally they are specified in lower case. Some of the attribute properties are used for constant values, for example when specifying alignment term like `left' and `right' are used. In such cases the attribute values are also case insensitive.

Panels

Panels differ from other components in that they are designed to contain other components. The ' panel ' element needs to span the children to conform to normal XML document structure e.g.

A panel

 <?xml version="1.0" encoding="UTF-8"?>
 <Page>
 <Components>
   <Panel layout="Box" layoutStyle="0" constraint="center" border="1">
      <Labelx="5" y="10" w="90" h="20" content="Firstname:" style="prompt"/>
      <Edit x="100" y="10" w="100" h="20" content="Joe"/>
   </Panel>
 </Components>

Panels may also specify a border attribute so as to display a thin line border around the edges of the panel. The value for the border attribute should be '1' for a border or '0' for none or else the attribute can be omitted.

The panel is considered to own its children so showing or hiding a panel will also show or hide its children.

A panel can include a layout manager by specifying the 'layout' attribute. In the above example the layout is set to the ' Box ' layout type. If a layout is being used each of its children should be given a 'constraint' attribute.

ScrollPanes

Scrollpanes have many of the same properties as panels, however they implicitly have associated layout managers. These layout managers will in some circumstances resize the children of the scrollpane, for example where tables are being used.

Layout managers are not always necessary with the scrollpanes and in such circumstances you will need to appropriately size the scrollpane and its content.

Frames

Frameset support is included to allow for inclusion of non swapping areas of the screen such as toolbars, navigation controls, headers and sidebars. Each frame contains an Page and is positioned using a layout manager. Navigation commands such showPage have been enhanced to take the name of the target frame.

A frameset

 <?xml version="1.0" encoding="UTF-8"?>
 <FrameSet>
   <Frame name="header" constraint="NORTH" width="640" height="80" content="header"/>
   <Frame name="content" constraint="CENTER" width="640" height="350" content="Welcome"/>
   <Frame name="footer" constraint="SOUTH" width="640" height="50" content="footer"/>
 </FrameSet>

By default the frames are described in the frames.xml file an example of which is shown below.

The container for the frames or target areas has a BorderLayout .

Using imported pages

As mentioned earlier pages can be imported into others by using the import tag in the XML file. Importing pages allows reuse of common page elements and also helps promote consistency within the user interface.

In this example we're importing a simple navigation screen in two other files. The imported file defines two buttons within a panel as follows

The included file

 <Component type="PANEL" x="10" y="180" w="210" h="40" border="1">
   <Button name="btnProceed" x="40" y="10" w="60" h="20" content="Next"/>
   <Button name="btnPrevious" x="110" y="10" w="60" h="20" content="Previous" 
   style="btnReverse"/>
 </Component>

Now, in order to use this screen we simply use the Include tag within another screen.

The include statement

And to attach events to the buttons we add events for each screen.

Attaching an event

 <Events>
    <Event name="nextPage" target="btnProceed" type="MouseHandler" 
      next="xmlimportsamplescr2"/>
 </Events>

Aria provides support for the Include element so that it can be nested within the Components element or its children. An example of this can be seen in conjunction with the Repeat element.

The declarations within the included file are processed as though they are part of the page within which they are included. Therefore an include `page' does not actually cause one page to be instantiated within another.

Repeat elements

The Repeat element includes a while attribute that specifies the criteria for repetition. In the example above a method returning a boolean value is invoked.

The features supports component, event and data binding elements. Generally the repeat attribute is used in conjunction with the include element so that common page fragments can be reused and included multiple time within a page.

In the example below the repeat attribute is used in this way to repeatedly include a radio button component.

The complete example

 <?xml version="1.0" encoding="UTF-8"?>
 <Page>
 <Components>
   <Panel layout="Border" style="question" w="640" h="75" constraint="center">
     <Panel layout="Flow" style="question" constraint="north" >
       <Image name="icon" w="20" h="20" content="qmark.gif" style="Question"/>
       <Label name="qtext" w="620" h="20" content="getNextQuestion()" style="Question"/>
     </Panel>
     <Panel layout="Box" layoutStyle="1" constraint="center" w="630" h="55">
       <Repeat while="${hasMoreOptions()}">
         <RadioButton w="100" h="20" content="${getNextOption()}" name="${getOptionId()}"
                     style="question/response"/>
       </Repeat>
     </Panel>
   </Panel>
 </Components>

The example is intended to be embedded in another page via an include element and therefore the method calls are implemented by the parent page's class.

Layout managers

Layout managers can be used in Aria via both Java code and XML. In the Java API a new method has been added to the ComponentFactory class to allow components to be constructed with a layout manager as an alternative to the absolute coordinates.

The new method takes one parameter, the layout manager constraint.

Adding a component via Java (API)

The constraint depends on the type of layout manager being used, so for example for a BorderLayout the constraints are BorderLayout.NORTH, BorderLayout.WEST and so on. However before using this method of adding components the LayoutManager needs to be set. Again this can be accomplished with the component factory by calling the method within Java

Specifying a layout (API)

The layoutType can be one of the Page constants:

In the XML page descriptions layout managers can be specified for both pages and panels. An example is shown below. For both the Page element and Panel components two attributes can be used: ' layout ' and ' layoutStyle '. The layout attribute specifies the layout type ( Border, Flow, Card, Grid or GridBag ) and is case insensitive. If the attribute is omitted a NULL layout is assumed. The layout attribute ties into a set of attributes in the applications style file.

The components are then added using a constraint attribute instead of the x,y,w and h attributes of the NULL layout. The attribute strings are converted to constants via the LayoutHelper class.

A simple border layout

 <?xml version="1.0" encoding="UTF-8"?>
 <Page layout="BORDER">
 <Components>
         <Button name="northBtn" constraint="NORTH" content="NORTH"/>
         <Button name="westBtn" constraint="WEST" content="WEST"/>
         <Button name="eastBtn" constraint="EAST" content="EAST"/>
         <Button name="southBtn" constraint="SOUTH" content="SOUTH"/>
         <Button name="centerBtn" constraint="CENTER" content="CENTER"/>
 </Components>

Some layout managers (such as the FlowLayout ) rely on the preferred size of a component to calculate the layout. In such cases a W and H attribute can be specified to set the components preferred and minimum size.

More details on the layouts can be found in the chapter See Layout..

Validations

Validations are rules that can be used to check that input is correct. Aria includes a number of built-in validation types, but since the validation of input can range from a trivial to a complex task the framework for performing validations is extensible. Ultimately you can add your own input validation rules and checks to an application.

Validations often have a general role within an application. For example the validation for a phone number or address could be of use in many places and in many applications. Therefore validation rules are specified in a separate XML file (named validations.xml by default) so that they can be used across projects. An example of the file's contents is:

A validation rules file

 <Validations>
 <validation name="firstNameRule" type="mandatory" 
         msg="The [firstname] cannot be blank" mandatory="true"/>
 <validation name="surnameRule" type="mandatory" 
         msg="The [surname] cannot be blank" mandatory="true"/>
 <validation name="ageRule" type="minmax" min="18" max="100" 
         msg="The [age] ({value} [years]) must be between {min} [years] and {max} [years]"
         mandatory="true"/>
</Validations>

The validation rules include a warning or error message that is displayed should the validation fail, i.e. if the user input is not valid. The message can include references to the parameters used to control the validation rule, the example shows the user value being embedded in the warning message as the {value} tag.

Details of the tags that can be used and the validations rules can be found in the reference documentation.

Three validation rules are specified for the example page shown below. The validations are then assigned to the input fields in the page XML. The complete XML for the form is as follows:

A complete example

 <Component type="PANEL" x="10" y="180" w="210" h="40" border="1">
     <Label x="10" y="10" w="150" h="20" content="First Name"/>
     <Edit name="firstNameEdit" x="170" y="10" w="100" h="20"/>
 
     <Label x="10" y="40" w="150" h="20" content="First Name"/>
     <Edit name="secondNameEdit" x="170" y="40" w="100" h="20"/>
 
     <Label x="10" y="70" w="150" h="20" content="First Name"/>
     <Edit name="ageEdit" x="170" y="70" w="100" h="20"/>
 
     <Button name="validateBtn" x="10" y="130" w="150" h="20"/>
 </Component>
 <Validations>
     <Validation name="firstNameEdit" rule="firstNameRule" />
    <Validation name="secondNameEdit" rule="surnameRule" />
    <Validation name="ageEdit" rule="ageRule" />
</Validations>
     <Events>
     <Event target="validateBtn" method="checkValidations"/>
 </Events>

The checkValidations method can of course be overloaded (or another method can be invoked) to do whatever custom processing is desired.

Normally it is not necessary to add such an additional check of the validations as the validations are checked upon page transition. The default behavior is to display a warning or error (for mandatory validations) message, taking the error message from the validations file and substituting values as appropriate.

Events

Under the hood Aria uses the normal Java mechanism of adding events listeners to the components on your page, however all the details of adding the events are hidden within the framework. All you need do is write a response method implementing your business logic and then tell the framework when you want that method called.

Once your XML page has been loaded by the Aria framework it exists as Java class. By changing this class you can add your own functionality and behavior to a page, even customizing the event handling for components.

To illustrate the event handling mechanism at work we need to re-introduce some Java code. First off we need to create a place in which to insert our Java code and we do this by setting the class attribute for a page. The framework that loads your page expects an instance of the Page class or one of its derivatives so we need to extend that base class.

In the example below our own custom class is derived from Page so that calls specified in the XML can be intercepted by the custom class.

Specifying a support class/page

The XML file now specifies this custom class as its base class and defines the two buttons which have attached events.

Binding to a class

 <Page class="org.formaria.samples.xmlbuild.EventHandling">
 <Components>
     <Button name="btnProceed" x="40" y="10" w="60" h="20" content="Proceed"/>
     <Button name="btnCancel" x="110" y="10" w="60" h="20" content="Cancel"/>
 </Components>
 <Events>
     <Event name="nextPage" target="btnProceed" method="nextPage"
            type="ActionHandler" next="xmlnavsamplescr2"/>
     <Event name="cancel" target="btnCancel" method="cancel" type="ActionHandler"/>
 </Events>
 </Page>

So now our Java code needs to handle the events by implementing the referenced methods:

Coding event handlers

 public void nextPage()
 {
    // Do something here...
    PageManager.showPage( getAttribute( "next" ) );
 }
 
 public void cancel()
 {
    Button button = ( Button ) findComponent( "btnCancel" );
    button.setText( "Clicked!" );
 }

On execution the Aria framework intercepts the action events (having been told to add an action listener for each button) and invokes the nextPage method when the btnProceed button is clicked, or the cancel method for a click on the btnCancel button.

All the plumbing needed to hook up the events and the response methods are hidden for your convenience and to make the code clearer. The hiding of the plumbing also helps reduce your code dependence of the base class. In later chapters (See Evaluated attributes and helpers.) we will see how to break free of this dependency altogether.

In some rare circumstances you may want to have more control or information about the events so the Aria framework allows you to retrieve the current event object (the event that caused your method to be invoked), you can do this by calling the getCurrentEvent() method of the base class.

Data bindings

Aria uses a data binding technique that allows components to reference data through links that point to the data's location within a hierarchical model. The data contained within this model can be simple scalar values or more complex types like lists and tables.

The bindings that link the user interface components to the data in the model take care of reading the data and updating the user interface (UI) component. The bindings can also save data to the model whenever the value stored within the user interface component changes.

Since the model lives for the duration of the application the same data model data (or nodes) can be used in many different places. For example the data from one page can be saved to the model and then reused on another page.

To establish a link between a user interface component and a node with the data model all that needs to be known is where the data resides in that model. Once the location has been declared Aria takes care of getting and saving the data.

An example of this is shown below:

Adding data

 <Data>
    <Bind target="firstNameEdit" source="defaultData/first" />
    <Bind target="secondNameEdit" source="defaultData/second" />
 </Data>

Here the data from two edit fields is persisted to two separate nodes within the data model. If the same binding specifications were inserted in another page then the edit fields to which the data was bound would update automatically when the new page was displayed.

The data model can also be accessed directly from your Java code and therefore you can use the same data within your event handlers or business logic. It is worth noting that once your data has been saved to the model it is independent of the user interface component from which it originated.

This data independence has a number of fringe benefits. Firstly your business logic can be free of dependencies on the user interface and therefore the user interface can be modified in appearance and form without affecting the workings of your business logic. In this way you could rebrand an application or refactor the user interface, even changing the type of component used to capture the user input.

Secondly, because your application code references the data through a relatively abstract mechanism it is not explicitly aware of the data source. Therefore the data source can be changed independently of the UI and of the application logic. During the life of an application this can occur at several levels. At design time some dummy data may be assembled in text files and then migrated to database tables as the application grows and ultimately the database may then be accessed remotely as the application is finally deployed. Such changes can be accommodated seamlessly by the data binding framework.

Building Pages with Java

Building pages with Java

Building a Aria application with Java is a little more complicated than using XML by its very nature however if the same sort of steps are followed in constructing the code then a simple UI application will result.

Java has many advantages over XML and notable amongst these is the reusability engendered by the object oriented nature of the language. Pages created in XML can be reused and extended (they can even be extended with XML). While an XML page is processed once as the page is loaded a Java page can have an extended lifecycle and hence a more extensive setup process. However, that said, Java and XML can be used in unison, mixing and matching as appropriate for your application.

Many of the steps and techniques used in the last chapter will be reused in this chapter, so even if you are not using XML for page declarations we would advise your to read the preceeding chapter for background information. The steps involved are much the same and differ only in implementation. Since the native Java objects are being used directly instead of via XML more features will be available, but for the purposes of the simple examples being used few of these additional features are required. As with other introductory chapters later chapters will cover the features employed in more detail.

Basic form building

At its very simplest a Aria-Java page requires a class derived from Page , the basis of all Aria pages. The traditional HelloWorld example can thus be coded:

Hello World coded in Java

 
 import org.formaria.aria.*;
 import org.formaria.swing.*;
 
 public class HelloWorld extends Page
 {
   public HelloWorld()
   {
     componentFactory.addComponent( LABEL, 10, 40, 90, 20, "Hello World" );
   }
 }
 

In the above example the page's base class, Page , has defined a component factory to help construct components. The addComponent method of this factory is used to create a new component at the specified position, add it to the page, and sets its content. The constant ' LABEL ' is also defined by Page as a convenience to help identify the component type consistently. Constants are defined for all the built in types, other types are identified by name (a string value).

The use of the factory saves several method calls that are normally used when an IDE generates the UI. The more compact form produced makes it easier to see what is going on and in the long run it is thus easier to maintain.

Using stylesheets

Stylesheets specify sets of colors and fonts. These styles are arranged hierarchically and are intended to add consistency to an application's look. Using styles with the component factory also saves some more setup code.

Like many of the components in Aria the styles are defined in a styles file. The startup file should include a setting for a ' StyleFile ' which points to the styles file.

Startup Properties including a style file reference

 UseWindow=false
 ClientWidth=240
 ClientHeight=300
 StartPackage=org.formaria.samples.simple
 StartClass=StyleSheet
 Title=Simple Form Sample
 StyleFile=stylesheetstyle.xml

To use the styles the component factory addComponent method signature has been extended to take an extra parameter, the name of the style. The Label components might all use the explicit style 'prompt', whereas the Edit components are styled implicitly by including the Edit style (if it exists) in the stylesheet. In fact each component has a default style name based upon its type name, but you can override these defaults and specify the style explicitly by appending the style name to the addComponent method call. The fragment below shows two such component additions.

Adding a label and an edit field

 componentFactory.addComponent( LABEL, 5, 10, 90, 20, "Firstname:", "prompt" );
 txtFirstname = (XEdit)componentFactory.addComponent( EDIT, 100, 10, 100, 20, "Joe" );

The construction of the buttons shows the explicit and implicit use of styles. Following on from this the ' Proceed ' button has the XButton style applied because it does not specify a style whereas the ' Cancel ' has specified it's own style.

Adding OK and Cancel buttons

 btnOK = (Button)componentFactory.addComponent( BUTTON, 40, 10, 60, 20, "Proceed" );
 btnCancel = (Button)componentFactory.addComponent( BUTTON, 110,10,60, 20, 
			"Cancel", "BtnReverse" )

The result of this is shown below. What you see should be identical to what you would have seen had the page been constructed via XML:

Event handling

Using the same page as in the previous section we can see how events are hooked up easily to components without the need to add listeners or import the usual event packages.

Events are added by calling the addSomeEvtHandler of the Page, where SomeEvt is the event type, for example Item , Mouse , Action and so on. These calls take two parameters, the first being the component which we want to attach the event to and the second being the method to call when the event is triggered.

Adding event handlers

   private void addEvents()
   {
     addTextHandler( txtCarCost, "changeAdvance" );
     addTextHandler( txtDeposit, "changeAdvance" );
     addMouseHandler( btnOK, "proceed" );
   }

The called methods must be declared as public void .

Simple event handlers

   public void changeAdvance()
   {
     float cost = Float.parseFloat( txtCarCost.getText() );
     float deposit = Float.parseFloat( txtDeposit.getText() );
     txtAdvance.setText( String.valueOf( cost-deposit) );
   }
 
   public void proceed()
   {
     if ( wasMouseClicked() )
       btnOK.setLabel( "Clicked!" );
   }

The example illustrates a common error in adding events. In the implementation of the proceed method above you can see that we can use the Page.wasMouseClicked() method to determine if it was a `click' which triggered the event. The mouse handler is invoked for multiple events like the mouse press, mouse move and mouse release events and we do not want to respond to all of those events.

The problem is that although we may be responding to a mouse click, the appropriate handler for a button click is in fact an action handler. Therefore instead of using the addMouseHandler the addActionHandler should have been used. Correcting this error the declaration now looks like:

Revised addition of event handlers

   private void addEvents()
   {
     addTextHandler( txtCarCost, "changeAdvance" );
     addTextHandler( txtDeposit, "changeAdvance" );
     addActionHandler( btnOK, "proceed" );
   } 

With this revision we can simplify the response method to remove the unnecessary checks.

Revised simple event handlers

   public void changeAdvance()
   {
     float cost = Float.parseFloat( txtCarCost.getText() );
     float deposit = Float.parseFloat( txtDeposit.getText() );
     txtAdvance.setText( String.valueOf( cost-deposit) );
   }
 
   public void proceed()
   {
     btnOK.setLabel( "Clicked!" );
   }

If you do indeed need to do more analysis of the event which triggered the call you can access the event with the Page.getCurrentEvent() method and check the event type and properties. The EventHandler returned from the getCurrentEvent() method needs to be cast to the appropriate Handler type depending on how it was declared.

Data binding

Continuing with the example, we next add data bindings to put some content into the page. In the most basic setup, input controls can be bound to data stored in an XML file. Static data is data contained in flat files bundled with the application. Such data is often used for test purposes or during initial development of an application.

To work with data bindings a little configuration is needed and the startup file now requires the entry ModelData=simpledatasets.xml . The referenced file contains the static data. The data in the file is then bound to the input controls using TextBinding objects.

Inserting data bindings

   private void addBindings()
   {
     addBinding( new TextBinding(txtFirstname, "customer/firstname") );
     addBinding( new TextBinding(txtSurname, "customer/surname") );
     addBinding( new ListBinding(cmbAge, "customer/ageRanges") );
 
     addBinding( new ListBinding(txtCarCost, "financial/carcost") );
     addBinding( new TextBinding(txtDeposit, "financial/deposit") );
   } 

Validations

Validations are rules that can be used to check that user input is correct. Reusable validation rules are specified in an XML file (named validations.xml by default). For example:

Validation rules

 <Validations>
  <validation name="firstname" type="mandatory" msg="The [firstname] cannot be blank"
    mandatory="true"/>
  <validation name="surname" type="mandatory" msg="The [surname] cannot be blank" 
	mandatory="true"/>
  <validation name="age" type="minmax" min="18" max="100" 
    msg="The [age] ({value} [years]) must be between {min} [years] and {max} [years]" 
    mandatory="true"/>
 </Validations>

Here three validation rules are specified for the example shown below. The first two rules merely check that some input has been provided while the third rule checks that an age value is within a minimum and maximum range.

Older versions of the Aria platform required an explicit call to setup the validation handling with a call to the ' setExceptionHandler ' method of the Page , this is no longer the case.

To use the validations we need to bind the validation to the components with a call to addValidation .

Binding the validatin rules to input fields

 addValidation( txtFirstname, "firstname" );
 addValidation( txtSurname, "surname" );
 addValidation( txtAge, "age" );

Putting the complete example together we get:

The complete example

 package org.formaria.samples.simple;
 
 import org.formaria.aria.*;
 import org.formaria.aria.data.*;
 
 public class DataBinding extends Page
 {
   Edit txtFirstname, txtSurname, txtCarCost, txtDeposit, txtAdvance;
   ComboBox cmbAge;
   Panel pnlClientInfo, pnlFinancialInfo, pnlButtons;
   Button btnOK, btnCancel;
 
   public DataBinding()
   {
     pnlClientInfo = (Panel)componentFactory.addComponent( PANEL, 10, 10, 210, 80 );
     pnlFinancialInfo = (Panel)componentFactory.addComponent( PANEL, 10, 100, 210, 80 );
     pnlButtons = (Panel)componentFactory.addComponent( PANEL, 10, 200, 210, 40 );
     pnlClientInfo.setDrawFrame( Panel.BORDER_BEVEL );
     pnlFinancialInfo.setDrawFrame( Panel.BORDER_BEVEL );
     pnlButtons.setDrawFrame( Panel.BORDER_BEVEL );
     componentFactory.setParentComponent( pnlClientInfo );
     componentFactory.addComponent( LABEL, 5, 10, 90, 20, "Firstname:", "prompt");
     txtFirstname = (Edit)componentFactory.addComponent( EDIT, 100, 10, 100, 20 );
     componentFactory.addComponent( LABEL, 5, 30, 90, 20, "Surname:", "prompt");
     txtSurname = (Edit)componentFactory.addComponent( EDIT, 100, 30, 100, 20 );
     componentFactory.addComponent( LABEL, 5, 50, 90, 20, "Age:", "prompt");
     cmbAge = (ComboBox)componentFactory.addComponent( COMBO, 100, 50, 100, 20, 
			null, "Edit" );
 
     componentFactory.setParentComponent( pnlFinancialInfo );
     componentFactory.addComponent( LABEL, 5, 10, 90, 20, "Car cost:", "prompt");
     txtCarCost = (Edit)componentFactory.addComponent( EDIT, 100, 10, 100, 20 );
     componentFactory.addComponent( LABEL, 5, 30, 90, 20, "Deposit:", "prompt");
     txtDeposit = (Edit)componentFactory.addComponent( EDIT, 100, 30, 100, 20 );
     componentFactory.addComponent( LABEL, 5, 50, 90, 20, "Advance:", "prompt");
     txtAdvance = (Edit)componentFactory.addComponent( EDIT, 100, 50, 100, 20 );
     txtAdvance.setEnabled( false );
 
     componentFactory.setParentComponent( pnlButtons );
     btnOK = (Button)componentFactory.addComponent( BUTTON, 40, 10, 60, 20, "Proceed" );
     btnCancel = (XButton)componentFactory.addComponent( BUTTON, 110, 10, 60, 20, "Cancel",
                 "BtnReverse" );
 
	 addEvents();
     addBindings();
 }
 
 public void pageActivated()  
   {
     changeAdvance();
   }
 
   private void addEvents()
   {
     addTextHandler( txtCarCost, "changeAdvance" );
     addTextHandler( txtDeposit, "changeAdvance" );
     addActionHandler( btnOK, "proceed" );
   }
 
   private void addBindings()
   {
     addBinding( new TextBinding(txtFirstname, "customer/firstname") );
     addBinding( new TextBinding(txtSurname, "customer/surname") );
     addBinding( new ListBinding(cmbAge, "customer/ageRanges") );
     addBinding( new TextBinding(txtCarCost, "financial/carcost") );
     addBinding( new TextBinding(txtDeposit, "financial/deposit") );
   }
 
   public void changeAdvance()
   {
     float cost = Float.valueOf( txtCarCost.getText() ).floatValue();
     float deposit = Float.valueOf( txtDeposit.getText() ).floatValue();
 
     txtAdvance.setText( String.valueOf( cost - deposit) );
   }
 
   public void proceed()
   {
     btnOK.setLabel( "Clicked!" );
   }
 }

The example makes use of the page's lifecycle method, pageActivated to call the changeAdvance method and update the page once all the components have been setup and the data loaded.

Annotations

If you use Java 5 and later you can take advantage of some annotations to save on coding. The annotations replicate features that can be coded directly in early versions of Java, so you are not missing out on any features if you cannot use Java 5 in this context. The annotations are as follows:

The annotations are probably of most use to the Java programmer, but the @Find annotation can save a significant amount of boiler plate code for all users, thereby making the code more readable.

The annotations require that you include the appropriate classes from the org.formaria.annotation package. See your IDE's documentation for inserting and optimizing imports. (In NetBeans press ALT+SHIFT+F to find the necessary imports).

Buddy helpers

In some ways Java coding is more complex than the equivalent XML however once we get over that initial hurdle Java coding can be considerably simpler. One common example of this is the BuddyHelper class that is used to setup labeled components.

Using the BuddyHelper, one call can setup two (or even three) components. The helper is designed to add a label (and sometimes a suffix for say a dimension). The helper not only saves a call to the component factory for adding the label but it also makes it a little easier to get alignments correct. (Remember that layout managers are normally preferable to the null layout).

In the above example the name edit fields could be added with this code:

A buddy in use

 BuddyHelper buddy = new BuddyHelper( (StyleFactory)componentFactory );
 imgSingle = (Edit)buddy.addComponent( EDIT, 5, 100, 10, 200, 20, 
                                          panelWidth, 28, "First Name", "", "prompt" );
 imgDouble = ( Edit )buddy.addComponent( EDIT, 5, 100, 30, 200, 20, 
                                          panelWidth, 28, "Second Name", "", "prompt" );

Aria has many other helpers like this that can help in building Java application. These helpers are not restricted to UI component creating and they cover all areas of Aria including the data model, events and so on and are available throughout the lifecycle of the application.

Other helpers

Aria provides numerous helper classes aimed to simplify Java coding and to remove those verbose typecasting requirements.

Logging

For most applications it is useful to use logging during the develop stage of a project.

Aria provides the DebugLogger class to provide integrated logging features. This log class keeps track of the number of errors and warnings generated. The amount of logging output can also be configured by setting a log level in this class. Ultimately almost all logging can be suppressed by setting the log level to SILENT . This log level is application wide and can be set or reset at any point in the application lifecycle.

At startup the ' LogLevel ' property is used to set the initial value.

Aria itself uses logging extensively and this can lead to verbose console output. To further help cut down on the logging Aria can be built in two forms - with debug logging on or off. The BuildProperties.DEBUG flag controls this logging.

The flag is defined statically so that the compiler will eliminate any code that is excluded by the flag (when it is set to false). This same mechanism can be used to conditionally include logging code in your pages:

Adding debug logging

 if ( BuildProperties.DEBUG ) </P>
   DebugLogger.logWarning( "Some log message" );</P>

The actual mechanism used for logging can be controlled by the LogWriter startup parameter, but normally this is configured for you and should need no change.

Compilation and building

Java applications need to be compiled before they can be run. Aria provides facilities to do this building but it is also possible to build an application from the command line or from a third party tool.

Compiling an application is fairly straightforward as all the classes needed for a build are contained in the AriaRuntimeCommon.jar file. Individual files can be compiled with the Javac command on the command-line, but we recommend using the ANT build tool.

However, as the extent and complexity of a project increases it will be worth considering using the tools that Aria provides by way of NetBeans or tools such as Eclipse or their commercial equivalents such as JBuilder. These tools provide much more than just compilation support and can be of great benefit when testing and debugging a project.

Switching toolkits

When building an Aria application with Java it is necessary to derive the page from the Page class and add components to that page. As part of this process it is necessary to import the definitions of the various objects used in the page, including the Aria components. At this point it is therefore necessary to choose between the AWT and Swing toolkits as one or the other must be imported.

This import implies a dependency on one of the toolkits. However given judicious programming it should not be a big task to move from one toolkit to the other if you have only used Aria components and have avoided toolkit specific features.

In fact all you need do to convert from one toolkit to the other is to change the imports, recompile and test. Of course there will be some differences in the look and feel of the application but by in large the behavior should not change.

Switching toolkits is probably a rare occurrence yet it still remains a good idea to try and reduce dependencies with an application. If possible you should try and isolate dependence of one toolkit or another if only for the purpose of keeping your code clean and clear.

Beyond the basics

Sometimes what is built into a platform may not cover all your needs and it is necessary to add extensions and third party components. Aria is based on an open design and with Java at the core there are many ways to add and extend the platform.

For example if components outside of the basic framework are employed then they can be registered with Aria, See Choosing how to install components. and accessed with the techniques described above. Since third party components are not built-in Aria can only have a limited view or understanding of those components and therefore you may need to manipulate the components directly. Programming in Java allows you do this and once you obtain a reference to a component you can access all its features either directly through the public API or through reflection.