Once you begin to use Jostraca in your projects you will quickly get tired of running Jostraca from the command line. Assuming that you are using the ant build tool, you can integrate Jostraca into your build process using the predefined Jostraca task: org.jostraca.JostracaTask. If you are not familiar with ant or the build.xml file, you should review the documentation for ant before reading this tutorial. In any case, you should also review the description of the taskdef task in the ant documentation

Introduce the predefined jostraca task like this:

 <taskdef name="jostraca" classname="org.jostraca.JostracaTask"/>
 

Then use it like this:

 <jostraca template        = "my-template.jtm"      
           templateOptions = "data-model.xml"       
           outputFolder    = "my-project-folder" />
 

This is equivalent to running the command:

 jostraca -o my-project-folder my-template.jtm data-model.xml
 

Note that you will need to include jostraca.jar in your CLASSPATH.

In addition to the main template attribute, you can also specify the template or list of templates to build by using one or more template sub-elements. Inside this template sub-element you can specify additional template properties in the standard name=value format.

    <jostraca outputFolder = "my-project-folder" >
      <template name="my-template.jtm">
        property-name = property-value
      </template>
    </jostraca>

These properties can be accessed inside the template with _getProperty(String pPropertyName).

The predefined Jostraca task provides access to all of the command line options. You can get a full list of the attributes in the reference documentation. We'll cover the most important ones here. The template attribute names a single template to execute. You will probably have to define the path to the template using the ant syntax for predefined paths: template="${src}/foo/bar.jtm".

If you want to execute more than one template, use the templateList attribute. This allows you to specify a comma and/or space separated list of template names. Use it like this:

 ... templateList="foo.jtm, bar.jtm" ...
 

Most of the time, you'll need to specify options for your templates so that they can access external meta-data. This is done with the templateOptions attribute.

You will also need to tell Jostraca where to place the resulting generated code. This is done by specifying the output folder using the the outputFolder attribute. You can also specify the work folder and the backup folder with the attributes workFolder and backupFolder respectively. Normally you do not need to worry about these other folders, and specifying the output folder is sufficient. The work folder is used for storing the CodeWriters, the backup folder is used for storing previously generated files.

There are also a number of boolean attributes that are used to control template execution. The boolean attributes accept values of "yes" and "no". The attribute compile determines whether the template is recompiled before it is executed. The attribute generate determines whether the template is executed. The defaults are to compile and execute. The attribute backup determines whether backups of previously generated files are made. The default is to create backups.

The configuration files for Jostraca are stored in the conf folder of the Jostraca distribution. Jostraca needs to access these files to function normally. If you have customised Jostraca using the local.conf file, then you will need to tell the Jostraca task where to find your configuration. This is done using the homeFolder attribute. Use this attribute to specify the location of the home folder of the Jostraca distribution (it was called something like jostraca-x-y-z when you installed Jostraca, although it may have been changed manually).

It is not necessary to specify the home folder for the Jostraca task. Jostraca contains an internal backup configuration (which is the same as the standard configuration), that allows it to function without configuration files. In this case you can provide customised configuration using either the conf directive of your templates, or by using the define attribute. The define attribute accepts a comma or space separated list of name=value pairs and can be used like this:

 define = "main.ExternalCompiler=jikes, "main.ExternalControllerOptions= +E -depend""
 

Notice that you need to quote name=value pairs that include spaces with ".

Although the Jostraca task makes using Jostraca much easier in an integrated build environment, it does introduce an extra layer that makes debugging more difficult. If you are having difficulties here are some things to try:

• Use the verbose attribute to get more detailed output: verbose="yes"

• Try running Jostraca from the command line first, and make sure that the template works as expected.

• Use the dump attribute to check your settings, for example: dump="template,settings"

• Use the -verbose option to ant to get more detail from ant itself.

You may also run into problems with the class path. In order for ant to use the Jostraca Task, you either have to include jostraca.jar into the class path used to run ant, or you must define a class path including it within build.xml. This can be done like so:

 <path id="tasks.classpath">                                         
   <fileset dir="lib">                                               
     <include name="**/*.jar"/>                                      
   </fileset>                                                        
 </path>                                                             
                                                                     
 <taskdef name="jostraca" classname    = "org.jostraca.JostracaTask"                               
                          classpathref = "tasks.classpath"/>         
 

Here we assume that the folder lib contains jostraca.jar.