How to Create a New Example

Note: this page is addressed to our helpers.

Requirements:

  • Java (1.5 or higher)
  • Ant (or ant-enabled IDE for Java)
  1. Each example will have its own directory. Suppose that we are creating a new example called "nice". Let us start by creating its own directory called ... (you guessed correctly) "nice".
  2. Each example will have the following directory structure:
    • src/ folder contains example source files (*.java files).
    • test/ folder contains classes that test the example.
    • lib/ folder contains additional libraries required by the example (*.jar files).
    So, we shall create nice/src, nice/test and nice/lib folders for our "nice" example.
  3. The next step is to populate the folders with appropriate content. For the "nice" example, we shall put Nice.java class under src/nice/Nice.java (since Nice class happens to be in the nice package). NiceTest.java goes under test/nice/NiceTest.java. We shall leave the lib/ folder empty, since our "nice" example does not require additional libraries.
  4. To compile the example, download build.xml file which contains most of the configuration that you need to compile and run your example. Place it in the example's directory, at the same level as the src/ folder. We shall place build.xml under the nice/ folder of our "nice" example.
    Ant is a build tool for Java, which makes it easy to manage your project. Most of the Java IDEs (such as Eclipse) are capable of running Ant's build files as well. Ant depends on a configuration file called build.xml which defines the targets for a particular project. Targets may include the tasks of compiling and running Java programs, which will be our use for Ant.
    If you have structured your project according to the instructions above, the supplied build.xml contains almost complete configuration for Ant to be able to run your example, create data trace files and run ContExt. There are a few "blanks" in the build.xml that you need to fill in with specific information about the current example. Comments in the build.xml identify such "blanks". For instance, you need to set the "context.release.dir" property to the directory in which context-x.y.jar resides.
    The supplied build.xml specifies the following targets:
    • run - runs the tests on the example (e.g. runs NiceTest which tests the Nice class).
    • chicory - collects the runtime state of the example classes in a data trace file.
    • context - runs ContExt on the data trace file obtained after executing the chicory target.
  5. Now you should be able to experiment with your example :) Enjoy! Please, collect the output into a file called results.txt which is to be located right under the example's top directory (in the same folder as build.xml).

Note: Eventually you will be required to commit each example into a CVS repository, but we shall get to it a little later.


Page last modified on November 04, 2007, at 07:30 PM