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.

‹ A quick tour of the editor up Getting Started ›