This is a brief guide in lieu of having real on-line documentation.  One of these days...

What is Jass?

Jass is a pre-processor for Java that implements Design By Contract (DBC). See the Jass Home page for details on Jass and useful Design By Contract links.

This Jass has nothing to do with the Java Audio Synthesis System.

What does this plug-in do?

This plug-in allows Jass to be run from within Eclipse 2.0.  It wraps the Jass pre-processor in an Incremental Builder which is installed to run before the Java Builder.  It also provides a property page for Java projects to allow Jass to be turned on and off and the pre-processor to be controlled.

Installation

1. Delete any previous versions.
2. Unzip the archive into your plug-ins directory.
3. Restart Eclipse

Configuration

Bring up the Properties pages for your project.  You will see a new property page, Jass Property Page:

Activate Contracts

This item could also be entitled, "Activate Jass".

When the contracts are activated here is what happens:

• The Jass Nature is added to the project.
• The Jass Builder is added to the project. It is added immediately before the Java Builder if it is on the project, or as the first Builder if it does not.
• An exclusion pattern of **/*.java is added to all the source folder to exclude the files which Jass processes from being processed by the Java Builder.
• The Jass output folder is added as a source folder. This is where the Java Builder will take the source files from.

When the contracts are activated here is what happens:

• The Jass Nature is removed from the project.
• The Jass Builder is removed from the project.
• The exclusion pattern of **/*.java is removed from any source folders where it is found.
• The Jass output folder is removed from the list of source folders.

Add Jass Runtime Jar to Build Path

In order for your contracted program to run some of the Jass classes must be available.  The Jass runtime jar contains the smallest subset of classes that will allow your code to run.  As a convenience, checking this option adds the Jass runtime jar contained within the plug-in to your build path.  While this is convenient, it does have a couple of drawbacks.  The most serious is that the path is hard coded for the particular machine this option was checked off on.  Thus the path from one machine may not work on another.  The second, related, problem is that this will only work on machines with an Eclipse installation.

As an alternative to including the Jass runtime in this manner, it can manually be added via the Java Build Path property page.  When done as a variable relative path this is much more flexible.

Activating or Deactivating the contracts has no effect on whether the plug-ins's jar is added to your build path. Only this setting affects that.

Show Debug Output

Checking this displays additional output when Jass is building.  This is mostly useful for debugging.

Jass Output Goes to Folder

Jass can compile source code from either *.jass or *.java files.  As the JDT does not recognize .jass files as Java source files the easier course of action is to use the .java extension for source files.  The problem then is that the processed files will have the same name as the original files.  If they are placed in the same directory, Jass will overwrite the original files with the processed ones.  To get around this the plug-in creates a new source folder in your project and directs Jass to send the processed Java files that it creates there.  You can use this option to change where the generated Java files go.  Changing the Jass Output folder does not delete the original folder nor does it move the previously generated classes to the new folder.

DO NOT change this to one of the original source directories or your files will be overwritten.

Output Mode, Compiler Mode, and Compiler Options

Consult the Jass Handbook for details on what these do.

Using the Jass Plug-in

Once the plug-in is configured there is little else to do. Whenever a build is done, Jass runs before the Java compilation step. If there are problems while generating the contracted files the error will appear in the Console window and a dialog will appear informing you of a build problem.

Jass does not respect the Build All command as it is seldom needed for Jass and Jass pre-processing is rather slow. Source files are always selected for processing based on being newer than the corresponding file in the Jass output folder. If you want all the source files to be processed by Jass again then simply delete the contents of the Jass output folder.

Running Contracted Applications

Running programs with DBC works as usual. When debugging programs with DBC add the Jass output folder to the source path as the first (that's important!) entry. Breakpoints can then be set as usual in the contracted source files, they can be stepped through, etc.

Using the Jass Plug-in with WOLips

This plug-in was originally written to be used with the WOLips plug-in that supports WebObjects development. There are a couple of things to be aware of. First, see the list of bugs. :-) There isn't really much else. Just be aware that when you are building with the IncrementalBuilder that you want to launch the app with a working directory of build/Application.woa and not just Application.woa (which is what the Ant build creates).

Frequently Asked Questions

Q: I get a NoClassDefFound error when I run my Application for Jass blah blah.
A: The Jass runtime jar is not on the classpath. Add it manually, or using the Jass Property page.

Q: I can't set breakpoints and step through the source when debugging.
A: See Running Contracted Applications.

Q: Can I replace the jass.jar in the plug-in with a newer version?
A: No. Changes were made to Jass so that it would accept OuterClass.InnerClass for inner classes instead of OuterClass$InnerClass which the Java Builder in Eclipse does not understand.

Q: Can I replace the jass-rt.jar in the plug-in with a newer version?
A: Yes.

Q: Sometimes my changes to the Jass Properties don't stick.
A: This is a conflict between the Jass property page and the Build Path property page. Both set the build path. To avoid this go directly to the Jass property page and do not view the Build Path property page before clicking OK. If the Build Path property page is displayed first, then select Jass property page and click OK without making any changes. When you open the properties again the Jass property page will be displayed first.

Q: How do I add more source paths to the project after Jass has been activated.
A: The easiest way is to deactivate Jass, add the folders, and activate Jass again. Alternatively, just add them as usual and then add an exclusion filter of **/*.java.

Known Bugs and Limitations

• Hangs IDE when used with WOLips plugin when WOLips runs Ant as external tool.
• Properties page sometimes conflicts with Build Paths property page causing loss of settings. Try to avoid using these property pages together each time you open the Properties panel.
• May be subject to Win2K 2048 command line length limit (untested).
• Sometimes, activating or deactivating contracts on a project does not take full effect. Usually, toggling the state (enable/disable), hitting apply, then once again toggling (disable/enable) and hitting apply does the right thing.

Future Plans (in no particular order)

• Comment the source!
• Change Jass to use the instead of reflection to analyze .class files. This will allow Jass to be run in the Eclipse JVM making things a lot faster, enable adding markers to source files for Jass processing problems, and enable progress reporting while the Jass Builder is running.
• Consider adding / removing the Jass runtime Jar when contracts are activated / deactivated instead of separately.
• Add a progress dialog to property page as it is slow.
• Add a launch configuration to automatically setup the source path correctly.
• Fix conflict between the Jass property page and the Build Path property page.
• Release source to Jass changes or have them integrated with the master.
• Add a preferences page.
• Fix bug / conflict with WOLips and running Ant as external tool.
• Add rest of Jass options to property page.
• Add on-line help.
• Add external strings.
• endorsement support.
• Figure out where the debug output is going to.

Disclaimer

No liability for the contents of this package and document can be accepted. Use the concepts, examples and information at your own risk. There may be errors and inaccuracies, that could be damaging to your system. Proceed with caution, and although this is highly unlikely, the author(s) do not take any responsibility.

All copyrights are held by their by their respective owners, unless specifically noted otherwise. Use of a term in this document should not be regarded as affecting the validity of any trademark or service mark. Naming of particular products or brands should not be seen as endorsements.

Copyright and License

Source code is released under GNU GENERAL PUBLIC LICENSE Version 2. As usual no warranty, responsibility or support should be expected.

Credits / Contributors

As usual, this is make possible by lots of other free software that are used directly or indirectly which includes Ant and facilities provided by Eclipse.

Feedback

Feedback is most certainly welcome. Send your requests, bug reports, comments and criticisms to chill@global-village.net.