 | Level: Introductory Andy Arhelger (juggle@us.ibm.com), Software Engineer, IBM
Andy Hanson (ahanson@us.ibm.com), Software Engineer, IBM
Tony Erwin (aerwin@us.ibm.com), Software Engineer, IBM
21 Jul 2004 The Abstract User Interface Markup Language toolkit is a rapid-development tool to assist developers in writing GUIs to run as either Swing applications or on the Web -- without any changes. Toolkit creators Andy Arhelger, Andy Hanson, and Tony Erwin take you on a tour of their technology, detailing where to get it, how to install it, and how to use it in this step-by-step article.
The Abstract User Interface Markup Language (AUIML) Toolkit, available from IBM alphaWorks (see Resources) consists of a Visual Builder that produces a panel definition expressed in an XML dialect. The builder will also produce runtime code stubs for data transfer to and from panel widgets and event handling. The application programmers then need only to add the business logic specific to their application to drive a panel. The AUIML definition can then be passed to one of the AUIML Toolkit runtime renderers that will display the panels described in AUIML and manage data transfer and events.
How does AUIML work?
AUIML is an XML dialect that is a platform- and a technology-neutral representation of panels, wizards, property sheets, and so on. AUIML captures relative positioning information of user interface components and delegates their display to a platform-specific renderer. Depending on the platform or device being used, the renderer decides the best way to present the user interface to the user and receive user input. The AUIML XML is created using the Eclipse-based AUIML Visual Builder, which provides developers with a quick way to build and preview user interfaces in the Java Swing and HTML Renderers. The AUIML Visual Builder can also automatically create data beans, event handlers, and help system skeletons for the user interface. Because it plugs into Eclipse, building the user interface and application code is an integrated process.
Benefits of using the AUIML Toolkit
Some of the benefits of using AUIML include:
- Rapid development: You can quickly create GUIs using the Visual Builder's drag-and-drop interface and automatically generated code stubs for managing data transfer and events. This feature allows you to focus on the business logic specific to their applications and not have to worry about the specific idiosyncrasies of various GUI widgets.
- Cross-environment applications: Using the AUIML Toolkit, applications that are created will run single-sourced in multiple rendering environments. The toolkit provides renderers for Swing and for running in the Web as a servlet or portlet. The same binaries can be used to drive applications in both environments; the binaries just need to be deployed differently.
- Insulation from technology change: Because application code is not written directly to the APIs for the environment it is running in, the AUIML renderers absorb the burden of updates and fixes when core technology updates occur.
- Internationalization: The builder automatically stores all translatable strings placed in panels into a Java
ResourceBundle. Locale-specific versions of these bundles can then easily be produced.
- Input validation: The renderers provide built-in, locale-sensitive, input validation. Some of this validation is completely automatic; for example, if the user types "abc" in a numeric field, the renderer will catch the error and display an appropriate error message without the application code needing to worry about it. Various simple data formatting bounds can be defined in the builder, such as Max Value. The renderers will also validate that data provided by the user is within these boundaries and display appropriate error messages if the input is outside the bounds. Applications also have the chance to do more complex validation and display errors.
- Accessibility: The AUIML Toolkit utilizes features of both Swing and the Web to support accessibility. Inside the builder, there is a check-accessibility feature that detects potential accessibility problems in panels and offers suggestions on how they can be corrected.
- Bi-directional (BIDI) support: The AUIML Toolkit renderers utilize BIDI support of their rendering environments to display panels appropriately for languages that are read from right to left, such as Hebrew and Arabic.
- Help: The Visual Builder will also produce stub HTML files and other tools for easy help system development.
 |
Installing and running the toolkit
In this section, we'll show you how to install and run the toolkit. First, though, you need to make sure your platform meets the proper requirements. The following list shows the operating systems and software you need to run the AUIML Toolkit:
Operating systems
- AUIML Visual Builder: Windows 2003 Server or XP
- AUIML runtime environment: Windows 2003 Server, XP, or Red Hat Desktop 4 for Intel
- Client browser: Internet Explorer 6.0, Mozilla 1.7, or Firefox 1.02
Software
- For AUIML Visual Builder
- Eclipse 3.0.1 or IBM Rational Software Development Platform 6.0.1
- For AUIML HTML renderer: WebSphere Application Server 6.0 or Tomcat 5.0.28
Installing the toolkit
Download the toolkit (see Resources) and unzip it to your computer.
To add the Visual Builder plugin to Eclipse or IBM Rational Software Development Platform, follow the steps below:
- Select Help, Software Updates, Manage Configuration... from the menu bar.
- Right-click on the top level eclipse item and select New, Extension Location...
- In the Browse For Folder panel, navigate to the location where you unzipped auiml.zip, then navigate to the auiml\VisualBuilder\csa_5.0.0 directory, and click OK, as shown in Figure 1:
Figure 1. Installing the Visual Builder plugin
Running the Swing samples
The sample source is located in the Toolkit\samples\com\ibm\ui\samples directory. There are two ways to run the samples in the Swing environment:
- You can use a simple .bat file. We don't provide one because the runtime can run on various operating systems, and a .bat file is Windows-specific. The code below shows a .bat file that will run the samples in the auiml\Toolkit\ directory in a Windows environment. You should adjust the auiml\Toolkit directory specified in the following listing based on the directory in which you unzipped the toolkit. You can modify this file for other operating systems.
set CONFIG=auiml\Toolkit\csa_runtime\config
set SETTINGS=auiml\Toolkit\csa_runtime\settings
set LIB=auiml\Toolkit\csa_runtime\lib
set EXT=%LIB%\ext
set SAMPLES=auiml\Toolkit\samples\lib\auiDemos.jar
java -cp "%SAMPLES%;%CONFIG%;%SETTINGS%;%LIB%\auibase.jar;%LIB%\auifw.jar;
%LIB%\auii18n.jar;%LIB%\auiswing.jar;%EXT%\jhall.jar;
%EXT%\uil.jar" com.ibm.ui.samples.SampleLauncher
|
- You can also run the samples using Ant. We've supplied a build.xml file to drive the AUIML. Download and install Ant (see Resources), then switch to the Toolkit\Samples directory and enter
ant run at the command line. The samples window will display, as shown in Figure 2. Click on a sample in the list to start the sample.
Figure 2. Running the samples
Running the HTML samples in IBM Rational Software Development Platform
To run the HTML samples, you will need to deploy the auiwebdemos.war file to a Web server. The WAR file may be deployed either to a WebSphere Application Sever or Tomcat. The following instructions are specific to deploying WAR to a Tomcat Web server, which is available from the Apache Jakarta Web site (see Resources). The procedure for deploying to WebSphere Application Sever would be very similar.
- In IBM Rational Software Development Platform, create a new Web project.
- Select File > New > Project from the menu bar.
- On the New Project wizard, expand Web and select Dynamic Web Project as shown in Figure 3:
Figure 3. Create a Web project
- Click Next on the wizard.
- Enter AuimlTest for the project name and make sure Websphere Application Server v6.0 is selected for the Targert Server and click Finish.
- Import the WAR file.
- Associate a project with your Web server.
- Go to the Server Perspective, right-click on your Tomcat server, and select the Add and Remove Projects option.
- Select the AuimlTest project, click the Add button, then click the Finish button, as shown in Figure 6:
Figure 6. Associate a project with your Web server
- Start the Web server.
- Right click on the server again and select Start.
- Run the Web samples.
- Start a Web browser and enter the URL http://localhost:8080/AuimlTest/html/samplelauncher.jsp. A window showing the sample launcher is displayed, as shown in Figure 7:
Figure 7. The Web samples
Running the Web samples with Eclipse
You must have a standalone Web server installed because Eclipse doesn't come with one. WebSphere Application Server Express or Tomcat are two possibilities. These instructions use Tomcat, which is available from the Apache Jakarta Web site (see Resources).
- Start the Tomcat server, then open the Tomcat Web Application Manager (which is at http://localhost:8080/manager/html).
- In the Install section enter the path to auiwebdemos.war in the "Upload a WAR file to install" box (Figure 8).
Figure 8. Tomcat install
- Click on the Install button. You should see the auiwebdemos file listed in the application list.
- Open a browser pointing to http://localhost:8080/auiwebdemos/html/samplelauncher.jsp to display the AUIML Application Launcher window, shown in Figure 9:
Figure 9. Tomcat samples
Creating and running your own AUIML panel
Now that you have successfully run the samples, the next important step is to create your own simple AUIML panel. We will show you how to create a panel using the Visual Builder, which is a plugin for Eclipse. The Visual Builder will let you drag and drop controls to create panels easily.
Designing a simple panel
With the Visual Builder, you can create simple or complex panels. When you start to design a panel, you should have a basic idea of what controls you will need and how you want the controls laid out on the panel. Also, each control has a number of properties that can be set to customize it and to specify initial values. For example, number controls allow you to specify a minimum value and maximum value. These values are set using the properties on the control. We will now create a simple panel with a text entry field and a couple of buttons.
- Open the Visual Builder perspective from IBM Rational Software Development Platform or Eclipse.
- Create a new file in the AuimlTest project, JavaSource folder, by selecting File > New > AUIML file. Then navigate to the JavaSource folder so the parent folder field is AuimlTest/JavaSource, and enter the new file name as AuimlTest.
- Click Finish to create the new AUIML file.
- In the Contents view of the new AuimlTest file, right-click on the Panels item and select Create Panel. You will now see a new item listed under Panels called Panel1. Figure 10 shows the new panel:
Figure 10. Creating an AUIML panel
You will get a blank AUIML panel with OK, Cancel, and Help buttons, like the one shown in Figure 11:
Figure 11. The first panel
- Click on EditBox > String on the control palette, then click in the top-right grid on Panel1. The panel should now look like Figure 12:
Figure 12. Panel with EditBox
- Go to the Properties view and enter Some Text in the Caption property. The panel should now look like Figure 13:
Figure 13. Panel with EditBox and text
Each control can have a caption associated with it, which is all you need for your basic panel. But let's put a title on the panel, too.
- In the Contents view, click on Panel1 to show the properties for the panel.
- Enter Some Title for the Caption property of Panel1. Entering a caption doesn't change what you see in the Visual Builder view for the panel.
- Preview the panel by clicking on the arrow button next to the Preview button on the toolbar, and select IBM Swing. You should get a window that looks like Figure 14:
Figure 14. Swing preview
Click on the arrow next to the Preview button on the toolbar and select IBM HTML 4.0 (Desktop). You should see the window in Figure 15:
Figure 15. HTML preview
- On the menu bar, select File > Save to save the file.
Next, we'll create a Java program to run this panel in the Swing environment.
Running your panel in Swing
To run your panel, complete the following steps:
- Switch to your Java perspective in Eclipse or IBM Rational Software Development Platform.
- Create a new Java class file with a
main() method, and call it RunAuimlTest.java, as shown in Figure 16:
Figure 16. Create a new Java class
Use the code below for RunAuimlTest:
import com.ibm.ui.application.WebApplicationAdapter;
import com.ibm.ui.framework.Capabilities;
import com.ibm.ui.framework.DataBean;
import com.ibm.ui.framework.IllegalUserDataException;
import com.ibm.ui.framework.TaskActionEvent;
import com.ibm.ui.framework.TaskActionListener;
import com.ibm.ui.framework.TaskManagerException;
import com.ibm.ui.framework.UserTaskManager;
public class RunAuimlTest extends WebApplicationAdapter implements DataBean,
TaskActionListener {
static final String auimlFileName = "AuimlTest"; // Package qualified file name
static final String auimlPanelName = "Panel1";
public static void main(String[] args) {
RunAuimlTest runTest = new RunAuimlTest();
runTest.render(WebApplicationAdapter.MODE_VIEW);
}
public RunAuimlTest(){
}
/*
* @see com.ibm.ui.framework.DataBean#load()
*/
public void load() {
}
/*
* @see com.ibm.ui.framework.DataBean#verifyChanges()
*/
public void verifyChanges() throws IllegalUserDataException {
}
/*
* @see com.ibm.ui.framework.DataBean#save()
*/
public void save() {
}
/*
* @see com.ibm.ui.framework.DataBean#getCapabilities()
*/
public Capabilities getCapabilities() {
return null;
}
/*
* @see com.ibm.ui.framework.TaskActionListener#actionPerformed
(com.ibm.ui.framework.TaskActionEvent)
*/
public void actionPerformed(TaskActionEvent event) {
}
/*
* @see com.ibm.ui.application.WebApplicationAdapter#render(java.lang.String)
*/
public void render(String arg0){
try {
// Call load on the dataBean, which sets up the data to be returned
// from the getter methods.
this.load();
// We pass in the name of the auiml file, the panel name, the data bean and
// we get the user context
UserTaskManager utm = new UserTaskManager
(auimlFileName,auimlPanelName,new DataBean[]{this},getUserContext());
// We implement TaskActionListener so add the listener to the utm
utm.addTaskActionListener(this);
utm.invoke(); // Displays the panel
} catch (TaskManagerException e) {
e.printStackTrace();
}
}
}
|
The methods load(), verifyChanges(), save(), and getCapabilities() are from the DataBean implementation, and the actionPerformed() method comes from implementing TaskActionListener. Implementing both DataBean and TaskActionListener in your main class is probably acceptable for a simple example, but for more complex applications you will want DataBean in a separate Java class.
You can set up the Visual Builder to generate the DataBean() method stubs for you automatically. To do so, you need to select the auiml file in the contents view of the Visual Builder. The properties view contains a property called Generate Data Beans, which you should set to true. Then for individual controls, you can specify a Binding property. This property lets you bind a DataBean getter and setter to the control. When you specify a binding for the control, you are specifying a package and class name and attribute. The class name is the DataBean class name and the attribute is built into the getter and setter method names. Then when you save the auiml file, the Visual Builder automatically creates the DataBean class if it doesn't find a matching class, or it will update an existing class.
- Save and compile the code.
You will need to create a run configuration for the RunAuimlTest application, as shown in Figure 17:
Figure 17. Run configuration
The classpath needs to contain the necessary auiml JAR files. Figure 18 shows an example:
Figure 18. Run classpath
When you run the RunAuimlTest program, you should see the test panel come up, as in Figure 19:
Figure 19. Running panel
Deploy and run the application on the Web
Now that you've seen your new AUIML application running in Swing, we'll show you how to run it on your Web application server. To run it, follow these steps:
- Unzip the auiwebdemos.war file (found in the auiml\Toolkit\csa_runtime directory) into a temporary directory.
- Place the files AuimlTest.auiml, AuimlTest.class, and RunAuimlTest.class within the WEB-INF\classes directory (which you may need to create inside of your temporary directory). You can use IBM Rational Software Development Platform or Eclipse to export these files or do it manually. (Alternatively, you can place these files in a new JAR file named myauiml.jar inside of WEB-INF\lib.)
- Zip the temporary directory back into a WAR file named myapplication.war.
- Deploy the new WAR file to the application server of your choice using the appropriate instructions for that particular server type.
- Invoke your AUIML application by pointing your Web browser to http://localhost:8080/myapplication/WnServlet?&Application=RunAuimlTest&WnUserID=anyuser (assuming your Web server is running on your local host). You will see a panel as shown in Figure 20:
Figure 20. Running panel on the Web
Congratulations -- you've now run the same application using two very different platforms, without modifying any code!
Note that for simplicity, we had you use the sample WAR file shipped with AUIML as a base. In actual practice, you'll probably want to start with the aui_war_template.zip file and customize several files, including web.xml, portlet.xml/component.xml (if deploying to portlet or ISC environments), Close.html, Logout.html, GeneralError.html, and GeneralException.html.
Summary
At this point, you've seen a brief glimpse of the power of AUIML technology. Most notably, you've seen how the exact same code can be made to run both in Swing and on the Web -- quite a feat because it takes the notion of "Write Once, Run Anywhere" to a new level. However, to leave it there sells AUIML short because it has so much more to offer.
AUIML is truly a full-fledged development kit that adds tremendous value regardless of whether you're interested in running your application on multiple platforms. We cannot possibly cover all of the features of AUIML in detail within this short article, but here is a small sampling of how AUIML can make your application development easier:
- Rapid prototyping with the Visual Builder. You used the Visual Builder briefly as part of this article, but until you start experimenting with all of the user interface controls (and the various properties for each) you won't be able to comprehend its power. But the Visual Builder's most striking feature may be that you can design your panel, wizard, or property sheet and see how it will look in Swing and on the Web without ever writing a single line of code!
- Ability to concentrate on your business logic. With AUIML, you can spend most of your time as a developer focusing on the back-end of your application instead of fiddling with low-level user interface widget APIs. For the majority of serious applications, your
DataBean implementation will be the only code you'll need to write.
- Built-in data validation. AUIML provides controls for string, number, and date/time types. So, for example, if you place a number field on a panel, then when your application is run it will require the user to enter a properly formatted number within the range you specified in the Visual Builder. If the user fails to do so, AUIML provides an appropriate error message and asks the user to fix the problem. All of this validation occurs without you having to write any validation code.
- Built-in internationalization (including BIDI support). For the most part, to run in multiple languages all you have to worry about is translating your application-specific text. AUIML takes care of such tedious work as formatting/parsing your number and date/time fields in accordance with the rules for the end user's locale.
- Complex user interface widgets to meet advanced needs:
- Tables that provide such advanced features as filtering, sorting, and searching your data with no additional code.
- Large tables that are used to deal with big data sets. The basic idea is that the AUIML framework asks your
DataBean to provide portions of your data set as the user needs it. This means, for example, that you don't have to load your entire log file with 100,000 entries before the user can start using your application.
- Tree tables that are used to display tabular data in a hierarchical format (such as a directory browser showing file details).
- Robust help system to provide your end-users with the information they need to run your application. The help system requires little more from you than providing your help text.
As you can see, there's obviously a lot more to AUIML than just being able to run cross platform. We encourage you to experiment with the samples provided with the AUIML Toolkit to learn more about all of these features on your own. We hope that you find AUIML to be a great time saver in your Java application development.
Resources
About the authors | 
| | Andy Arhelger has been on the AUIML Toolkit development team in Rochester, Minnesota, for the past three years. He has extensive experience with GUI, Swing, J2EE, and Web development. |
| 
| | Andy Hanson has been designing and developing GUI software using XML technologies for the last five years. He is employed at IBM Rochester, Minnesota. |
| 
| | Tony Erwin is a software engineer for IBM in Rochester, Minnesota. Tony joined IBM in 1998 and has been actively involved in the various facets of GUI design and development throughout his career. |
Rate this page
| |
