About this book

This user guide provides information on using and developing applications with Aria. The guide is organized into an number of sections.

• Section I Begins with an introduction to Aria, its history and its position on the technology landscape.
• Section II Describes the Aria Integrated Development Environment (IDE) and the basic features that are commonly included in an application are explained.
• Section III Covers more advanced features and the features that are required to build full-featured client-server applications.
• Section IV Illustrates many features by way of case studies.

The guide then concludes with a selection of reference materials.

Formaria also provides step-by-step tutorials, courseware and on-line reference manuals so the focus of this manual is on explaining the concepts of developing applications with Aria. The Formaria web site also features a developer zone where you can find working applications and numerous technical articles.

User Guide Conventions

The documentation for Aria uses the typefaces and symbols described in the table below to indicate special text.

Contacting Formaria developer support

Formaria offers a variety of support options. These include free services on the Internet, where you can search our information base and connect with other users of Formaria products. in addition you can choose from several categories of telephone support, ranging from installation support to fee-based consultant-level support and detailed assistance.

For more information about Formaria’s developer support services, see our website at http://www.formaria.org.

When contacting support, please be prepared to give complete information about your environment, the version of the product you are using, and a detailed description of the problem.

Introduction

This is a draft update of the manual. The Aria project contains some recent changes that are not entirely reflected in this book. In particular classs names no longer start with an X, there is no `optional' package (just renamed) and the build process for the framework and the IDE plugins has changed and the description is yet to be updated in this book.

Aria is a Java and XML framework for creating applications with rich user interfaces.

Aria includes a plugin for the netBeans integrated development environment making the development and testing process as easy as possible without locking you into a proprietary solution. Aria also has a rich set of libraries, tools and wizards for rapid application development.

What is Aria?

First and foremost Aria is a framework for building Java and XML based applications. The aims of Aria are to:

• Reduce the amount of code needed to build an application
• Provide a clean application architecture and infrastructure
• Simplify building and maintaining applications
• Allow easy extension and customization
• Enable lightweight and performant applications

The core of Aria is a small Java library that allows 'pages' of an application to be constructed from an XML declaration or from Java code. Aria offers many add-ons and extensions including a graphical editor/IDE.

Aria can be used for simple single page applications and forms or for complex business applications comprising many page and resources.

What can be built with Aria?

Aria can be used to build a wide variety of applications just a few of which are listed below:

• Simple form based applications
• Management consoles
• Catalogues, Configurators, Browsers
• Selection tools
• Guides/Brochures
• Retail and Point-of-Sale applications
• Kiosk applications
• Mobile applications for field workers and road warriors
• Surveys and market research applications
• Database applications
• e-learning applications
• Informational and promotional applications

Aria is a general purpose tool so it can be used to build just about anything you can imagine building with Java and XML, but it offers the greatest advantage when building client side applications.

Aria also includes many sector specific features and add-ons. See the Xoetrope website for more information on add-ons and case studies highlighting how Aria's has been used to build specific solutions.

What does Aria do?

In a nutshell Aria can be used to build feature rich, smart-client applications. Smart client applications are typified by their ability to make use of client-side computing power. Notably this means that such applications exhibit;

• A feature rich user interface
• A fast and responsive user interface
• Ability to work on-line or standalone
• A simplified application construction
• Ease of updated and processing of dynamic content
• Built-in data management
• Sophisticated functionality
• Optimized bandwidth usage
• Low maintenance and administration characteristics

All of these features can be found in Aria built applications. Furthermore, being Java and XML based, Aria applications are portable so that they can run on a wide variety of devices and platforms.

As a development platform Aria leverages the usual drag and drop techniques to make building applications quick and easy. Aria includes numerous widgets, library functions and wizards to make many common tasks simple.

Simplicity really is the key to Aria, so even if the feature or behavior you desire isn't predefined it usually isn't difficult to implement. As an open system Aria even allows such additions to be made in a reusable way so that you may only need to define the addition once. Even if you need to go beyond Aria's capabilities you can work directly with Java and XML or with third party tools. So, ultimately Aria make the developer's life easier.

How does Aria work?

Aria takes advantage of local computing resources, so instead of going back and forth to a server a Aria application can store and process information locally. As a result you don't see the delays that are typical of some web-based applications. Using the local computing resources means that you can make an application more responsive, offer more and better user interaction and build smarter applications, so-called Rich-Client or Rich Internet Applications (RIA).

Making use of local computing resources also helps simplify some of the tasks involved in building modern software applications. If you don't have to go back and forth to a server for information you don't need to do so much to maintain state information. Furthermore if you can eliminate input errors at source then your business processing should be less complicated.

In addition to the implicit benefits of a rich-client framework Aria also applies some well known architectural techniques to further simplify the process of building applications. The most important of these concepts is the Model-View-Controller (MVC) pattern. With this pattern the key components of an application are separated from one another to simplify development. In Aria the MVC architecture is promoted by the natural separation of the various components in framework and by the coding styles and techniques used for each component.

The Aria MVC components equate to

• View: Pages defined in either XML or Java.
• Model: The data, declaratively bound to the pages or view.
• Controller: The application logic specified in Java and declaratively bound to the other components.

Aria also supports declarative user interface specification and declarative data binding whereby pages, data bindings and event bindings can be specified in XML independently of one another. The late coupling this provides has a number of benefits. Pages can be delivered or updated independently of one another much like HTML pages. This sort of independence of content was one of the major benefits of thin-client and web applications yet Aria manages to deliver similar behavior and benefits in a rich-client framework. Aria however achieves this while leveraging the Java platform, in the process delivering efficient, modular and reusable components.

Much of Aria's benefits stem from this loose coupling of components. Since the View is loosely couple to the data model a new look and feel can be placed on an application with minimal implications for the application behavior or coding. Similarly the application logic can be coded with minimal reference to the user interface or how data is bound and update to that user interface. Imagine being able to write the code for even a simple equation without having to know when or how the input fields are filled out or how to then display the results of your calculation.

The separation of roles pays dividends in a number of ways. People of differing skills can collaborate on a project with perhaps one concentrating on the user interface and visual side while another may be responsible for business logic or data processing. Whether this is actually a realizable business benefit is a moot point, but in the long-run the benefits are very real.

In a maintenance mode it may be many months since a particular feature or aspect of an application has been developed. Being able to `fix' a bug in say the business logic in such a feature is considerably easier when you don't risk breaking a user-interface feature or the data setup or vice versa. Furthermore without mixing user-interface code and business logic the role and intent of each piece of code is more apparent and this make understanding each part of the application a little less involved.

Aria is in some senses is a fairly typical development environment or framework for building Java applications, a plug-in for the NetBeans IDE is even a key feature. Aria however aims to make the process of building and maintaining applications as simple as possible.

Using the techniques described above Aria eliminates much of the normal `plumbing' code and allows you to get on with building real value into your application. In saving large amounts of coding the burden of developing and maintaining applications is also greatly lightened.

Licensing

Aria is available under the open source MPL and GPL/LGPL license which allows developers to download and use the software or to bundle it with commercial applications.

Any enquiries about licensing can be addressed to support@formaria.org.

Why Aria

There is no doubt that modern software is complex, and this complexity it often the bane of quality, performance and usability. Aria started out as a way of making life easier for the developer. The framework initially set out to eliminate some of the most basic and tedious coding tasks rather than as a complete replacement for existing practices. The stratgey of augmention rather than replacement has been followed throughout the frameworks's development and this leaves the developer free to use the best tools for a particular job, using all of Aria or just those parts that suit.

Over time Aria has developed to include a range of advanced features and tools that ease the task of building modern applications, but Aria's central theme remains the task of making it easier to build advanced, feature rich applications.

Background

Aria is a Java-based system that sets out to solve many of the problems encountered when building Rich Internet Applications (RIA).

Users are demanding more features, more performance, better integration and generally greater usability from their applications. A competitive market and demanding users means that modern applications are becoming more and more complex, often to the point where development is at the limit of the available resources and maintenance is highly expensive. For the many organizations this complexity may translate into less that ideal behavior or reduced functionality within the application.

While Aria is based upon Java, Java in its basic form can be misused, and to some extent Java suffers from some shortcomings from the application developer's perspective in that there is no out-of-the-box support is included for high-level abstractions such as the MVC architecture, and there is little high-level support for communication and data-access, and in some cases excessive plumbing is often required to perform simple tasks.

Aria aims to eliminate much of the plumbing involved in building RIAs, so that the developer can concentrate on adding value to the application.

Many of today's client applications, be they built on Java or not, suffer from code bloat and poor maintainability. Poor maintainability often derives from the use of IDEs and the throwaway nature of the code they generate. Unaddressed, this lack of emphasis on good design and quality leads to poor performance. For many, this poorly constructed application type is typified by the monolithic fat-client application, with all its deployment and maintenance issues.

One common solution to the problems of fat clients is to employ a thin-client architecture, moving processing to the server side and removing client administration woes, yet this solution is not without its own perils. Shifting the problem of poor design to the server won't win many awards and introduces many of its own problems, like security and session handling, not to mention performance.

Hybrid application types like Ajax share most of this thin-client legacy but added apparent interactivity, however, this comes add the price of even greater complexity and all without the architectural merits of either the fat or thin client application. Ajax applications also suffer from a lack of tooling, whereas a typical Java developer will have an abundance of superb tools.

Despite the poor reputation gained by some client applications, there has been a resurgence of interest in smart client applications. Most client devices, even handheld devices, now have sufficient processing capability to perform useful work and this is wasted in a thin-client environment. Many of the fat-client problems have been solved and the thin-client solution is not the panacea that many had desired.

The Aria library is an open-source framework designed to solve some of the problems involved in building modern smart client applications.

Why do we build applications at all?

It may seem obvious to say that we build application to meet business needs, yet it is worth reflecting on the bigger picture. What do we hope to accomplish with our applications?

Typical requirements include getting the work done in an efficient and effective manner and having a reliable and maintainable system. All quite straightforward, but what about keeping the customer happy? Quite often the job is not just about getting the immediate business done but also about keeping the customers happy.

Many of today's applications fall short of providing an all round satisfying user experience. Frequently the user simply wants to accomplish the task at hand with the least amount of pain. At other times the user wants a richer, more informative experience, one that adds value.

Aria can help you provide fast and effective client solutions.

The Form Metaphor

According to 2001 analyst estimates American businesses alone spend upward of $15 billion transferring data from paper-based forms such as loan applications and purchase orders to their computer systems. Billions more is invested every year in web based forms and other electronic forms. Not surprising when you consider the ubiquity of the humble form. Almost every business process involves form processing of one sort or another. In a broader view forms are an essential part of the data capture process for many businesses.

Electronic data capture and form processing offers many advantages over paper alternatives and act as the basis for a wide range of business applications. In many cases it may not even be possible to achieve comparable results with a paper based approach. Electronic forms can be of great value to both the end user (ease of use and error checking) and for backend processing (speed, quality and security).

Today a wide range of technologies are available for electronic forms processing. Many of the newer technologies are enabling completely new areas of automation and better, more functional applications. Couple this with other related technologies like mobile computing and wireless communication and you have many exciting new opportunities for improving workflow and communications.

From a business perspective automated form processing can bring many returns above and beyond the direct savings. The improved data can lead to better analysis of the customer relationship. Closing the enquiry-sales-fulfilment loop to manual data entry can even reduce leakage from the sales cycle. Where field workers or representatives are involved, faster more efficient technology will empower the employee.

In an application context the notion of a form can be quite vague but for the purposes of this guide we will assume that a form is a fairly discrete component that helps capture a subset of data. How that form is presented to the user can vary greatly within the definition of the user interface but from the point of view of the application logic the form's role is fairly well defined and helps for a logical subdivision of an application.

Beyond Forms

HTML forms have been the mainstay of web applications for some time. Although forms can be considered a workhorse of data capture, their use as the de facto user interface is not particularly well suited to the demands of modern business processes or for more complex application design. It is common for applications to comprise whole sets of forms and much of their value comes from relating the information on one form to another and to business intelligence.

It is easy to see that the smarter an application appears and the more responsive it is to the user, the richer the experience. Many of the web technologies in use today go to great lengths to provide such responsiveness and such intelligence, yet in many ways they face an uphill struggle. The infrastructure required to deploy some of these frameworks can be significant and rapidly pushes up the total cost of ownership despite what may be the obvious technical merits of an individual technology.

HTML was designed primarily for the display and linking of static text and static content. Extensions, plug-ins and many server side technologies have added to the power and capability of the basic HTML technology. The so called thin client that these technologies popularized has gained enormous popularity over the last few years. Despite the ubiquity and popularity of the thin client there are many areas where these web technologies have been less successful.

HTML's limits

An HTML application or form normally requires a request to the web server to provide updated content. Plug-ins or scripting may be used in some situations to avoid the round trip to the server and provide some element of local interactivity but often at the cost of complexity.

For anything other than simple applications the mix of HTML, JavaScript and server side technologies can rapidly lead to a complex technology solution. In many ways the solution is often more complex that the original problem. The more complex the applications become the greater the strain for these solutions to be effective.

Even without the implementation and delivery issues, HTML based applications suffer from the inherent delays associated with having to make frequent requests to the server. A simple round trip leads to noticeable delays in responding to user interaction and hence there is a limit to what is effective in terms of user interactivity with such applications.

Scripting

One of the defining characteristics of many web frameworks is the use of client-side scripting technologies. While scripting may be acceptable for small scale use it does not work well for large scale use. Scripting lacks many of the object-oriented features that programmers expect of a modern platform. Couple this to the common problem of separating roles with a environment that normally sees scripts embedded in user interface declarations and you can end up with a complex mess.

Underlying HTML's use is of course the browser, with all its security restrictions and compatibility problems. Even within an individual browser the lifecycle of a page can prove troublesome, making it difficult to maintain state. HTML is just not a natural fit for the needs of many modern applications.

Application delivery in a connected world

Today, a new range of connected workers has emerged, the road warrior, the business traveller, the salesman, the field worker, the PDA/Smart device owner. This type of user presents many new challenges. Typical of these demands is the occasionally connected nature of their usage. It's not much good to have smart devices if it is assumed that the application software needs constant connectivity, or if the applications cannot cope with loss of connectivity mid session.

Rich Client to the Rescue

Desktop computers and even the majority of mobile devices have significant computing power and therefore it is well within their capacity to handle much of what is delegated to the web server by thin client applications. One of the cornerstones of performance is locality of computing. Holding true to this maxim, locality of computing for a form application means that such things as data validation, prompting, user interaction can be handled locally. Doing things locally means not having to wait for a round trip to the server to complete. This alone can lead to faster, more interactive applications and interacting with data locally can also facilitate disconnected and mobile applications. Add to the local interactivity the rich user interfaces that can be built for today's rich client applications and you can get some very attractive applications.

So Why Aria?

Aria is a rich client application development platform designed to improve the way in which Forms and internet applications can be built. Bringing together two powerful technologies, Java and XML, Aria offers many advantages in terms of ease of development, performance and portability. These advantages lead directly to reduced development and maintenance costs. The rapid development process that Aria enables also means that you may have more time to devote to improving content and creativity.

The open source Aria framework addresses many of the problems discussed above and then some more. Aria adds many additional widgets for building applications and business sector specific features and wizards, not found in the basic open source platform. Aria also provides client-server support so that applications can more easily work within a corporate environment and communicate with back-end services.

Aria comes with a feature packed editor and is built in an open way, supporting open standards. Vendor lock-in is avoided and the editor can be used in conjunction with other tools. So even if your authors and developers don't want to use low level technologies like XML they can build applications with the familiar drag and drop metaphors.

The Development challenge

For many organizations the move to thin clients was driven by administrative issues as much as implementation ones. The thin client was seen as a way of reducing administrative and helpdesk requirements as the client application had zero footprint. Furthermore the assumed ease of updating content was considered a major benefit in itself.

The penalty for this approach was that more responsibility was placed on the server side. All the users, all the user information and preferences had to be managed by the server. All the processing was shifted to the server as well. While architecturally this structure may have seemed simpler it often involved several tiers and a large array of systems.

The return of the rich client will not do away with many of the demands placed on today's servers but it will certainly reduce the load and in many ways simplify the applications. With each client managing its own state the server can be focused on providing the centralized enterprise level facilities to which it is best suited.

A rich client framework like Aria implemented in a single language is considerably simpler than the highly layered approaches common in today's thin client systems. The problems that dogged rich clients of the past are but a memory. Zero footprint and incremental updates are a given. Security and a richer user experience are bonus.

Individual features of Aria are worth using on their own not to mention using them in concert with other Aria features. Take for example Aria's method of constructing user-interface components via factories. This feature alone saves large amounts of code over what would be generated by a typical IDE. Aria is a modular system so you can employ just one feature like this on its own, mixing and matching to your needs. Aria, can therefore be integrated into new, old or legacy applications without difficulty. For legacy applications the Aria framework can provide a convenient way of adding new and modern features to what may otherwise be tired looking applications.

Above all Aria is designed by programmers for programmers.

Related Technologies

Aria is built upon an open architecture and hence it can support a wide variety of technologies. Equally Aria can be used in an ad hoc manner whereby parts of the package can be used and other parts replaced or supplemented by other technologies. Aria was designed to support good programming practices and the use of best of breed tools so in many ways the technologies listed in this chapter need not be seen as competing technologies and can be used comfortably alongside Aria.

Aria versus HTML

HTML is well known and can be used for a wide variety of presentations and even for simple form applications. However HTML is not well suited to anything other than trivial applications. The mix of HTML with the scripts typically needed for interactive web pages can be a nightmare to develop and maintain. The scripting code tends to get heavily embedded in the HTML and it is therefore difficult to decipher and reuse.

Numerous attempts have been made to address the needs of web applications but many of these attempts require large plug-ins or are restricted to a Windows platform. We believe that Aria strikes a good balance, requiring no plug-ins, a small download requirement, pages that can be downloaded individually or en-masse all while still managing to have powerful programming capabilities.

The XML used by Aria is easy to read and understand. Separation of the scripting means that the XML is clean and compact; ideal for offloading to a graphic designer if so desired. The Java code used in place of the XML can run in the browser's native environment and is pure code, again no mixing of content so from the programmer's perspective this too is desirable.

Aria versus AJAX

AJAX isn't a new kid on the block, having been around in many guises for several years. AJAX is essentially a technique for updating a web page without having to request a page refresh. AJAX can update a fragment of the page and the end user has the impression of a more responsive environment as only some of the page updates. Indeed AJAX may be a little more efficient than vanilla HTML as the fragments of HTML/XML it pulls down during updates will conserve some bandwidth.

AJAX can enable some client side processing of data but it is at heart still a scripting technology, still burdened with all the drawbacks of scripting and of being browser based.

Aria versus Java

So why not program in Java? Aria's use of XML makes it compact and simplifies the process of creating forms and more generally simplifies the creation of a UI. The separation of concerns means that the core business logic can be separated from the UI with the consequence that the code is easier to develop and maintain. Not only that, but the code is also more likely to be reusable. In comparison to a Java solution developed with a typical integrate development environment we normally see a reduction of 50-70% in the size of the codebase.

Despite the benefits that Aria can bring we do not mean to suggest it can do everything. Java is a very powerful programming platform and Aria has been designed to work with Java and therefore the full power of Java is available to a Aria application.

Careful coding means that Aria can run with the browser's built in Java support (JDK 1.1.4 of Internet Explorer) and on a wide range of mobile devices. The result is that you aren't really faced with the choice of Java or Aria; rather you have the option of using the best features of both systems to give a powerful small footprint system.

Sun's Swing and NetBeans teams continue to make great strides in improving the Java desktop experience, however, most of the new technologies they introduce require a recent JDK and this may not be available to everyone. Most of Aria's technology is available on a wide range of JVMs.

Despite the overlap between Aria and some of the newer Swing features we plan to support emerging technologies as they mature and become available, particularly where they are standardized. Aria 3.0 introduces a new application architecture to make it easier to customize the basic application startup and behavior, and in this respect additional support for Swing has been added by way of a new startup object that can essentially integrate a Aria application as a component within a run-o-the-mill Swing application. Aria 3.0 also extends the Swing widget support, making use of third party Swing components very simple.

So what does all this mean? Well Aria and Aria play very well with Swing and standard Java desktop technologies. For the most part you can view Aria as a code saving technology for Swing, and after that you can use the normal Swing coding conventions.

Aria versus Servlet and Server Side Technologies

A number of server side technologies have been used to assist in the development of web applications. The Apache Foundation has produced several of these libraries, notably the Struts library. Sun, Microsoft, IBM, Oracle and others have added to the range of server side technologies available to the developer. The various technologies that these tools offer almost all produce HTML or XML that is rendered on the client. The server side tools add many facilities for validation of data and control of the client integration with the server but on the whole they fall short of offering the type of rich client that can be built with Aria and the client side technologies outlined above.

Of course most modern applications rely on a server side process to implement key business functions. Aria is no different and in this sense it is complementary to server side technologies. However Aria relieves the server of the challenges involved in much client state information.

Aria can integrate with business components on the backend via a variety of protocols and processes, be that simple HTML forms, J2EE, Soap or .Net. Aria's service model neatly encapsulates these services so that the much of the detail can be hidden from the application programmer.

Not only can you choose Aria and/or Java but using XML you can easily move from AWT to Swing, without recoding, so for a Windows user this means it is possible to run with Internet Explorer without need for additional downloads or plug-ins.

Support for other widget sets (e.g. LCDUI/Blackberry) is being developed from prototype).

Aria versus .NET

Microsoft's .Net platform has been gaining widespread coverage and Microsoft has made some forays into the forms market. Aria can be run on this platform via the J# language (a clone of Java) if required. On some mobile platforms this may be desirable where a JVM is not available or is a cost impediment.

However Java is by far the more mature platform and the available resources are far more extensive. In using .Net there is also the risk of getting locked into a Microsoft environment and the consequent costs. At the core, Aria being an open source platform gives you plenty of options.

Aria versus XUL , *XForms, XAML et al

Mozilla, Microsoft and others have produced a variety of XML formats for user interface description. These formats share many of the same objectives as Aria and unsurprisingly they use many similar techniques to construct applications. One of the advantages of XML in this context is that the formats are relatively open and so it is possible to render these documents with the Aria add-on libraries published by Formaria.

Aria differs from these libraries in a number of key ways. Firstly XUL and its variants rely heavily on client side scripting making them more difficult to program and maintain than the pure Java used in Aria. Many of the XUL variants are rendered with the Java Swing library making them unsuitable for resource challenged situations such as exist on mobile devices, Aria can be rendered with the AWT and hence memory and bandwidth are conserved. And of course XUL can't be compiled so it always pays the cost for parsing

Microsoft's XAML format deserves separate mention even though it is in many ways similar to XUL. XAML of course is not yet widely available. The licensing model offered by Microsoft may make use of XAML prohibitively expensive and the availability of XAML clients may be limited to the very latest Windows desktops.

Of course given Microsoft's strength in the market place the impact of Longhorn and XAML will be significant. The XAML architecture mimics that of Aria in many ways and provides many of the same features and facilities so we take this as an endorsement of the Aria architecture. In many ways Aria does for Java what XAML does for Windows.

The World Wide Web consortium is promoting XForms as part of the XHTML standard and again this offers a variation on the XUL theme. XForms embodies a rich data model and supports lifecycle semantics for a rich web client. Like XUL, XForms relies heavily on scripting, although to a much lesser degree than HTML forms. Again the add-on Aria libraries can render and interoperate with XForms. Aria differs in that its data model and update semantics are more cleanly separated in the industry standard MVC architecture making for a clean maintenance structure and clear programming structures.

A prototype filter is under development that allows Aria to read formats such as XForms, Infopath and XAML.

Aria versus Ajax

Ajax is something of a juggernaut powered by the hype surrounding Tim O'Reilly's Web 2.0 notion, however Ajax has been around quite some time and even featured in a precursor to Aria and Aria. Without doubt, Ajax is an improvement on vanilla HTML and even DHTML, but as has been mentioned above this comes at a price. Ajax applications are often quite complex, having a mix of client and server side technologies and a mix of programming metaphors and language. While this might be highly important to developers, end users probably couldn't care less about this complexity, so long as they can get the job done. Therefore Ajax has alot of merit and may well be the best choice for some applications. Conversely as applications grow and the shortcomings of the Ajax platform begin to exhibit themselves then a Aria or Aria based application begins to become more attractive.

Quite often the power user will demand better performance or better desktop integration than can be delivered by Ajax and here Aria can help. Therefore, if the system is not too complex and there is only occassional or light use of an application then Ajax could be a good choice. Where performance, or integration, or flexibility, or complexity are bigger issues then Aria may be the better option.

What may surprise some, who wrote of Java as slow and clunky, is that a Java application like Aria can be visually attractive, with lots of rich user interface features and great performance. Where that visual impact is important Aria is also the better option.

Other issues

The technology used in Aria is only one part of the overall application development story. There are many factors that affect how a project is implemented and managed. The following sections highlight some of these important factors to consider when embarking on a development project of any significance.

Legacy application support

Not everyone has the luxury of starting with a clean slate, and importantly Aria does not necessitate such an approach. The open architecture employed by Aria makes it easy to use Aria when and where possible. This may simply be the use of Aria to cleanup some code or it may be more extensive. Aria can be added incrementally to a project.

Legacy applications frequently suffer from maintenance issues such as spaghetti like code and the mixing of concerns so that it is often difficult to identify key business logic. Aria can greatly simplify this code by allowing much of the plumbing to be removed or hidden. Not only does this save code and reduce the complexity but it also make the business logic more apparent.

But why fix a working system? It's quite simple really; it's easier to maintain a small code base than a large one, and it's easier again to maintain a clean code base than a convoluted one. Using Aria as part of the cleanup means that the real value in an existing application can be preserved and prepared for tomorrow's challenges rather than facing a rebuild.

Aria's support for new technologies like POJOs, data binding and modern user interface components also mean that Aria can be a good choice for extending, reviving or refreshing existing applications.

Simple single language support

Many of today's applications and systems are composed of a variety of subsystems, often in different languages and invariably requiring multiple developers with different skill sets. In contrast Aria has a single language implementation. Java is used throughout and can be supplemented with simple XML (and this XML can be hidden from sight by use of the IDE).

Separation of roles

Aria promotes a clean architecture by separating development roles and concerns. As has already been remarked Aria makes business logic stand out by removing plumbing code. Aria goes further by separating the applications data, services and user interface into distinct components. Not only does this facilitate maintenance but it also helps promote good development practices.

Occasionally connected

Modern applications have to cope with a wide variety of connected devices. Despite the ubiquity of internet access it cannot be assumed that there is always a connection available. Even if there is a connection available quality of service considerations, or security concerns may mean that an application must cope gracefully with intermittent connectivity.

Aria not only supports this capability but provides sophisticated mechanisms for handling remote communications, routing and fault tolerance. Added to this is Aria's ability to support store and forward mechanisms so that once connectivity becomes available data can be sent to the server or updates retrieved.

Branding

Many companies sell through channels and these channels require branding of the application to suit the channel. Aria stylesheets facilitate this rebranding without change to the code.

Within Aria you can easily replace colors, fonts, text and other resources. This together with the separation of concerns enforced by the MVC architecture means that you can efficiently build an application to support multiple brands or sales channels. Furthermore the open architecture means that it is possible to deliver modular solutions whereby resellers and related businesses can integrate content in a coherent manner.

Performance and server load

Because Aria promotes the idea of a rich client and of performing more processing on the client side there is a consequent reduction in the load on the server. This locality of computing also leads to direct performance gains from a user perspective. Local calculations may not require a round trip to the server for data retrieval and once retrieved the data can be accessed efficiently. Moving processing to the client also removes several layers of processing (security, load balancing, logging etc...) from the server so not only can the processing/calculation be performed efficiently on the local machine but the server can also act in a more efficient manner by serving up coarse grained objects (more content and less overhead as requests are amalgamated).

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.

Styles

Most applications try to use consistent styling and Aria provides support for consistent coloring and typography through its style manager. Aria's style management allows all the information and details of colors and fonts to be maintained separately from the rest of the UI description. Not only does this make it easy to reference particular style elements but it also makes it easy to switch styles say, for example, when rebranding an application for a different sets of end-users.

Using styles

In the introduction section we saw how styles could be applied when adding components either via XML or within Java code. Aria provides interactive visual tools to help design and use styles. Within Aria a style can be applied by selecting a component or several components and clicking on the chosen style in the style palette.

Changing a style

Color schemes

Aria extends the notion of styles by including a color scheme chooser to provide coherent sets of styles.

You can edit a set of styles as a color scheme by choosing the Color Scheme... option from the Style Palette's popup menu. The Color Chooser provides a convenient way of specifying sympathetic systems of colors and styles. The chooser consists of a number of areas for choosing the colors and then applying these colors to a set of styles. The color chooser has two parts, the first allows the choice of a set of sympathetic colors and the second allows selection of these colors for various usages. On the left hand side is a color wheel where you can choose a base color. This base color can be manipulated using two sliders for brightness and saturation. The hue can also be modified by clicking at some point within the inner circle. The Hue, Saturation and Brightness values can also be entered directly as numeric values. Clicking on the selected color preview (just below the color wheel) pops up a list of system colors (see the image on the right). The system colors can also be selected whenever the color wheel is available. Once the color has been chosen the colors and the variants are shown in a preview area. The number and type of variants displayed depend on the color scheme chosen. By default the scheme is monochromatic but other schemes can be chosen from the drop down list at the top of the chooser. Below the preview area is a table of colors and you can click on any on these to use it as the base color. On the second page of the chooser is an area where you can configure the styles. Simply click on the various sample texts to modify the foreground color, the background color or the font. A set of radio buttons allow you choose from these options. Once the set of styles has been selected click OK to save the styles under the specified style name. If a new style is being created the styles will be added to the style palette. Alternatively if the style name is already in use then the styles will be updated once the chooser is closed.