JAXX Support

I attended
the technical session by Ethan Nicholas
on the JAXX Framework last
week at JavaOne.
I downloaded it yesterday and spent a few hours experimenting
with it. I'm still skeptical - I really miss having a graphical tool for
doing layout. But the NetBeans IDE
is a big tent - so for those of you who
are interested, here are the steps I used to get some basic support for
doing JAXX development.

Install the software

I used JDK5,
NetBeans IDE v5.0, and
JAXX 1.0.

Set a Property for the JAXX Installation

There is a build.properties file in the NetBeans IDE's user folder (for
more info. on the location of the user folder, see this FAQ entry).
I added
this line to it:

  
    jaxx.dir=F:\\tools\\windows\\dev\\jaxx\\jaxx-1.0<br><br>      
  

It will come in handy later. I should point out that this does not have to
be in build.properties - I could have defined it later in one of the project's
properties files, so adjust this advice to your own personal taste.

Add .jaxx as a File Type for the IDE's XML Editor

In the IDE, choose Tools > Options and then click the
Advanced Options button in the lower-left corner. Under the
IDE Configuration folder expand the System folder and then
under it expand the Object Types entry. Select its XML Objects
entry. Doing that will change the right-hand side of the dialog. Over
on the right-hand side, click the button with the three dots (...) that is
next to Extensions and MIME types:

That will bring up a small dialog that looks like:

In the Item field type jaxx and then click the Add button. Then
click OK and then click Close on the Options dialog. Admittedly,
this is a bit tedious, but well worth it. The IDE will now use its XML editor
to display files ending with the .jaxx extension. So I get syntax highlighting,
code completion (if there's a .dtd or XML schema), indentation support, etc.
In other words, .jaxx files look like this:

Instead of like this:

Create a Library Entry for JAXX

This step is optional, but it is more convenient to have
a library defined. Choose Tools > Library Manager and then
click the New Library button. I called the library JAXX and specified
the jaxx-runtime.jar so I ended up with this entry:

Create a Java Project

With the one-time setup stuff out of the way, I proceeded to create a project.
Choose File > New Project. Under Categories choose General
and under Projects choose Java Application then click Next. I called
my project Components, since that is the sample JAXX application that I chose
to use for this trial run. Note that the Create Main Class option is not checked:

Add Additional Source Folders

So what do I have so far? An empty project with a single source folder: src. It
seems to me that for doing development with JAXX I need two additional folders:
one for the .jaxx files and another for the generated .java files that are produced
by the JAXX compiler, which is called jaxxc.
By default jaxxc deletes the .java files it produces after it invokes javac to produce .class
files from those .java files. But keeping the .java files produced by jaxxc has some important benefits.
First, it allows me to use the rest of the build.xml that the IDE generated for
building, cleaning, debugging, and running my project. In other words, if I just
insert an Ant target up front that runs jaxxc before the compile target then
everything can just proceed normally from there. The other big benefit is for
debugging - if I have the .java files then I can easily debug any problems by using the
IDE's debugger.

But I do not want those generated .java files intermixed with any "normal" .java
source files I might want to create. This is easy to fix. Right-click the
entry for the project in the IDE's Projects window and select Properties
from the context menu. The top half of the right side of the dialog has a form
where you can add source package folders and specify the label used for each
folder. I added two entries, so that I ended up with this:

Copy in some Sample Source

I used the Components example program from the JAXX 1.0 /examples folder. I
copied all the .jaxx files from the /Components folder to my project's /jaxx folder and then I copied the
/images folder from the /Components folder to my project's /src folder, so
that my /src now has a folder in it named /images. Note that I could have instead just
set my project's Source Folder properties to point to the JAXX 1.0 /examples/Components folder, but
for this experiment I wanted to keep things separate.

Add Targets to build.xml

Since I did not provide one, the IDE created a build.xml for me. It has
some handy targets that I can override in order to add custom functionality.
In this case, I need two: one to run the jaxxc compiler and another to
delete the generated .java files. To edit build.xml, open the IDE's Files
window (Window > Files) and expand the entry for the
project. The build.xml file will be listed under it and you can double-click
it to open it. Add this target for running the jaxxc compiler:

  
    <target name="-pre-compile">
        <exec executable="${jaxx.dir}/bin/jaxxc.bat" dir="jaxx">
            <arg line="*.jaxx -k -j -d ../generated"/>
            <env key="JAVA_HOME" path="${jdk.home}"/>
        </exec>
    </target>  
  

A couple of comments here. First, there is an Ant task available for running jaxxc. Unfortunately,
I could not get it to work with this sample application. I noticed this on the
JAXX known issues page:
"There are some problems with the classpath searching with a remapped source directory
(the "srcdir" attribute of the Ant task) or destination directory (the "destdir"
attribute of the Ant task or the "-d" option on the jaxxc command line).
This can cause dependency files to be reported as missing during compilation.
The fix for this issue has been checked into the Subversion repository." That
sounds like the problem I was seeing, so I changed my ant target to just invoke
the batch file directly instead of using the Ant task. This leads to my second comment: this target is
a bit of a hack. In particular, it should use a property for the name of the command - as it
is now it will only work on Windows (because on Unix the name of the shell script
is just "jaxxc"). Also, property values should be used for the source and
target folders.

Add this target to have the generated .java files removed when the IDE's Clean
Project command is invoked:

  
    <target name="-post-clean">
        <delete>
            <fileset dir="generated" includes="**/*.java"/>
        </delete>        
    </target>
  

Set the Main Class

In the Projects window, right-click the entry for the project and choose
Properties from the context menu. On the left-hand side of the dialog click Run.
In the Main Class field specify Components and then click OK.

Add a Reference to the JAXX Library

In the Projects window, right-click the entry for the project and choose
Properties from the context menu. On the left-hand side of the dialog click Libraries.
Click the Add Library button and then add the JAXX Library that was created
earlier.

Build the Project and Run It

Right-click the project's entry and choose Build Project from the
context menu. After the Build completes right-click again and choose
Run Project from the context menu. Note that you could instead choose
Debug Project if needed.

End Result

I now have a standard project with some additional features: a bit of support
for using JAXX. As shown above, I have XML editing features for my .jaxx
source files. In addition, I have a project structure that includes
.jaxx files and the generated .java files and makes reference to the JAXX runtime
library:

Also, I have support for running the jaxxc compiler and reviewing any errors
it produces. In the example shown the error message is a link so I can
click on it to open up the Components.jaxx file at the line that jaxxc reported
the error on:

One last thing to note: the .jar file created by the IDE for this project
includes the .jaxx source files. Ordinarily, this is not something I would
want. For this particular sample application, however, it is necessary because
the example code expects to be able to find the .jaxx files on the classpath at runtime (this
is so that it can display the source to the user). To prevent the inclusion of
the .jaxx source files use the Packaging entry in the Properties
dialog.

Going Further

All of the above was done after just a couple of hours of poking around with
one of the JAXX sample applications. Additional support would require
extending the IDE with a plug-in module,
but it is easy to envision the desired features: code completion
for .jaxx files, debugging at the .jaxx file level (instead of the generated
.java files), and of course: some sort of visual development tool.