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 modules

Component	Usage
Aria	Aria can be used with just about any Java development environment. All you need do to begin working with Aria is add the AriaRuntimeCommon.jar module to your project's classpath. To use Aria in this way simple download the jar file and installed it somewhere that can be accessed by your development environment.
NetBeans plug-in module	The Aria editor is based on the NetBeans platform and is delivered as plug-in for the NetBeans IDE. Installation of this module is described in detail below.
Eclipse plug-in module	An Eclipse plug-in provides wizards for creation of projects and pages and supports editing and debugging of Aria projects.

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:

Aria modules

Component	Usage
AriaRuntimeCommon.jar	This Jar contains all the class files needed for core Aria development using the AWT widget set.

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:

Sample applications

Sample	Description
Hello World	The classic introduction.
Navigation	A simple example showing how to navigate within an application.
Translation	An example showing how translations can be setup and used.
Counter	A very basic calculator showing how to link in Java code to add custom logic to an application.
Address Forms	Some simple forms showing the key concepts of data binding and validation.
Mortgages	A more complete example showing how to build a working example. This example is also used as a tutorial on how to use Aria.

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:

Subversion access

svn co https://aria.svn.sourceforge.net/svnroot/aria aria

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

Top level projects

Folder/Package	Role
AriaRuntimeCommon	Contains all the source code, resources and build files for the runtime libraries.
AriaEditorCommon	Source common to both the NetBeans and Eclipse projects
AriaEditorEclipse	An Eclipse specific project for building the Eclipse plugin
AriaEditorNetBeansSuite	A collection of projects for building the NetBeans plugin. Most of the sub-projects are merely wrappers for the plugin's dependancies.
AriaMobileMidp	A version of Aria for MIDP. This project is developed in parallel to AriaRuntimeCommon and has diverging source.
lib	A collection of libraries needed for the Aria projects.
other	Contains non Java code for `other' clients stubs.
samples	A collection of sample projects and utilities
docs	The source FrameMaker documents that go to making up this manual.

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

Libraries used by the AriaRuntimeCommon project

Library	Description
beanshell	Libraries for BeanShell scripting support
commons	Apache Common libraries. including commons-codec .
google	The Google translation service API
hsqldb	The hsqldb library which is used in some samples for off-line or lightweight database access. Aria includes some support for packaging hsqldb databases in the jars distributed with Java Web Start
itext	The iText library for PDF generation (export functionality)
jakarta	The Jakarta regular expression library, plus the BCEL library for byte code manipulation (used for DTO class generation).
jdic	SwingLab's JDIC project used for system tray and browser integration.
jmf	The Java Media Framework used for video and audio support.
netscape	Netscape's JavaScript integration support
jxl	Excel export
jgoodies	JGoodies look and feel support libraries
multisplit	SwingLab's MultiSplit layout manager (incidentally maintained by Aria contributors).
swt	Eclipse SWT libraries
tomcat	The servlet API
svgSalamander	SVG widget and rendering support
tablelayout	An advanced layout manager
timingframework	SwingLab's animation and timing library
xalan	XML support

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:

Runtime libraries produced by the default build

Library	Contents
AriaRuntimeCommon.jar	The complete runtime library include all versions of the widgets.
AriaRuntimeCore_<version>.jar	The core library minus any widgets
AriaRuntimeAwt_<version>.jar	The AWT specific widgets
AriaRuntimeSwing_<version>.jar	The Swing specific widgets
AriaRuntimeSwt_<version>.jar	The SWT specific widgets

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:

Non-static projects for building the NetBeans module suite

Folder/Package	Role
AriaRuntimeCommonModule	Contains all the source code, resources and build files for the runtime libraries.
AriaRuntimeCommonModule	A wrapper for the runtime library, the library wrapped by this module is updated dynamically when the module builds, so it wraps the latest runtime library.
AriaEditorCommon	Source common to both the NetBeans and Eclipse projects
AriaEditorCommonModule	A wrapper for AriaEditorCommon project, operating in the same way as the runtime module so that the wrapper uses the latest build of the common module
AriaEditorNetBeansSuite	A collection of projects for building the NetBeans plugin. Most of the sub-projects are merely wrappers for the plugin's dependancies.

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:

External Spring Dependancies

Setting	Role
spring.libraries=C:\\Tools\\spring-framework-2.5.4\\lib	Points to the root folder of the Spring distribution. Use Spring 2.5.x. See http://www.springframework.org/
spring.modules=C:\\Tools\\spring-modules-0.9-with-dependencies	References the root of the Spring Modules installation. (see https://springmodules.dev.java.net/)
spring.security=C:\\Tools\\spring-security-2.0.2	References the root of the Spring Security installation (formerly Acegi, see http://static.springframework.org/spring-security/site/).

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