To get you up to speed using Canyon we will be using an example to demonstrate some of the features. The sample will be based on three files being mapped to three classes. This is not mandatory but it makes your mapping files straight forward. Essentially you could think of each file as a database table.

There are 5 steps to configuring Canyon

1. Create your JAVA model. Canyon requires your model follow the Java Bean convention, i.e a default no args constructor, and getter/setter methods for the attributes.
2. Create the mapping file for each object model
3. Create the canyon.cfg.xml file to combine the mapping files with the physical files or sources. Place it in your root classpath (similar to log4j, hibernate etc)
4. Embed a CanyonSession object in your code and iterate over the objects
5. Done!

The best way to get you started with Canyon is by example. The tutorial application, which is an Eclipse project, can be found here on the downloads page.

The model for the tutorial is below

The first thing to do is to map your input files to Java objects using a Canyon mapping file. The DTD to a file is here.

The mapping for the shop and product object is below. As you can see the shop uses a delimited file, whereas the products use a fixed length field file. The other mapping files can be found in the project archive.

Canyon uses a very simple configuration file to drive its functionality. Essentially the configuration file combines a mapping configuration with a input and/or output file. One or the other is required. The configuration should be named canyon.cfg.xml and be placed in the root class path of your application. Canyon will then search for the file. Alternatively you can create an environment variable called canyon.config.file.location that specifies the file path of the configuration file.

As the diagram shows, each mapping combines a mapping document as defined in Step 2 and physical file or resource. In the case of this exmaple only resource(s) are used. Alternatively the file attribute could be used, where the value would be the full path to the input file.

With the mappings created, and Canyon configured, you are now ready to add Canyon to your code. This is done extremely simply with the following piece of code.

And that is it! Depending on your mapping to the file being accurate, there is nothing more to do other than iterate over your objects. By passing in different objects, the iterator will process differently. E.g if you were to process a shop (in the example there are only two), Canyon would automatically process all the related employees and products. Please see advance features for more information on relationships and how they work.