Running Abator

Abator can be run in the following ways:

• From the command line with an XML configuration
• As an Ant task with an XML configuration
• From another Java program with an XML configuration
• From another Java program with a Java based configuration

Each method is described in detail below. Note that there is also an Eclipse plugin for Abator that adds extra function - namely good integration into Eclipse, an Eclipse enabled Ant task, and support for automatic merging of Java files. See the Abator home page for information on installing the Eclipse plugin.

Important: When running outside of an IDE environment like Eclipse, Abator interprets the targetProject and targetPackage attributes in all XML configurations as follows:

• targetProject is assumed to be an existing directory structure. Abator will fail if this directory structure does not exist.
• targetPackage will be translated to a suitable subdirectory structure of the targetProject directory structure. Abator will create these subdirectories if necessary.

Running Abator from the Command Line

Abator can be run directly from the command line. The JAR manifest includes the name of the default class (org.apache.ibatis.abator.api.AbatorRunner) or you can specify it yourself. The AbatorRunner class takes two arguments: the name of the configuration file, and a flag (true or false) specifying whether existing Java files should be overwritten. If the flag is false, and an Java file already exists with the same name as a newly generated file, then Abator will write the newly generated Java file to the proper directory with a unique name (e.g. MyClass.java.1, MyClass.java.2, etc.).

You must still create an Abator XML configuration file. If the file is named "abatorConfig.xml", then any of the following command lines will run Abator:

   java -jar abator.jar abatorConfig.xml false
   java -jar abator.jar abatorConfig.xml true
   java -cp abator.jar org.apache.ibatis.abator.api.AbatorRunner abatorConfig.xml false
   java -cp abator.jar org.apache.ibatis.abator.api.AbatorRunner abatorConfig.xml true

Running Abator from Ant

Abator includes a simple Ant task. The task must be defined in your build.xml file, and the task has two parameters. Here is an example build.xml file:

   <project default="genfiles" basedir=".">
     <property name="generated.source.dir" value="${basedir}" />

     <target name="genfiles" description="Generate the files">
       <taskdef name="abator"
                classname="org.apache.ibatis.abator.ant.AbatorAntTask"
                classpath="abator.jar" />
       <abator overwrite="true" configfile="abatorConfig.xml" verbose="false" >
         <propertyset>
           <propertyref name="generated.source.dir"/>
         </propertyset>
       </abator>
     </target>
   </project>

Notes:

• The classpath on the <taskdef> is used to tell Ant where the implementing code is. This is optional if you add Abator to the Ant classpath in one of the other ways described in the Ant manual
• The name of the task can be anything you desire, "abator.genfiles" is simply an example
• The "overwrite" attribute is optional. If "true", "yes", etc. then Abator will overwrite any existing Java files. If "false", "no", etc. then Abator will not touch existing Java files - the newly generated Java file will be saved with a unique filename instead. The default is "false".
• The "configfile" attribute is required - it must specify a valid Abator configuration XML file.
• The "verbose" attribute is optional. If "true", "yes", etc then the task will log Abator progress messages to the Ant console. The default is "false".
• The task supports an optional nested <propertyset> element which is the standard Ant property set type. This can be used to pass parameters into a configuration file. For example, the above property generated.source.dir can be accessed in the Abator configuration file with the escape sequence ${generated.source.dir}

Running Abator from Java with an XML Configuration File

The following code sample shows how to call Abator from Java. It does not show exception handling, but that should be obvious from the compiler errors :)

   List warnings = new ArrayList();  // Abator will add Strings to this list
   boolean overwrite = true;
   File configFile = new File("abatorConfig.xml");
   AbatorConfigurationParser cp = new AbatorConfigurationParser(warnings);
   AbatorConfiguration config = cp.parseAbatorConfiguration(configFile);
   DefaultShellCallback callback = new DefaultShellCallback(overwrite);
   Abator abator = new Abator(config, callback, warnings);
   abator.generate(null);

Running Abator from Java with a Java Based Configuration

The following code sample shows how to call Abator from Java only. It does not show exception handling, but that should be obvious from the compiler errors :)

   List warnings = new ArrayList();  // Abator will add Strings to this list
   boolean overwrite = true;
   AbatorConfiguration config = new AbatorConfiguration();

   //   ... fill out the config object as appropriate...

   DefaultShellCallback callback = new DefaultShellCallback(overwrite);
   Abator abator = new Abator(config, callback, warnings);
   abator.generate(null);