            -----
            Usage
            -----

Usage

  The StringTemplate Plugin uses the {{{http://www.stringtemplate.org}StringTemplate}} template engine to generate files
  during your build.

* Configuration

  The configuration looks like the following:

+-----+

    <build>
        <plugins>
            <plugin>
                <groupId>com.webguys</groupId>
                <artifactId>string-template-maven-plugin</artifactId>
                <version>1.1</version>
                <configuration>
                    <templates>
                        <template>
                            <directory>path-to-template-directory</directory>
                            <name>template-name</name>
                            <target>path-to-output-filename</target>
                            <controller>
                                <className>fully-qualified-class-name</className>
                                <method>method-to-invoke</method>
                                <properties>
                                    <key>value</key>
                                </properties>
                            </controller>
                            <properties>
                                <name1>value1</name1>
                                <name2>value2</name2>
                            </properties>
                        </template>
                    </templates>
                </configuration>
                <executions>
                    <execution>
                        <phase>generate-sources</phase>
                        <goals>
                            <goal>render</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>

+-----+

  The execution of the plugin can be under any phase, but it is recommended to use the <<<generate-sources>>> phase.

  The configuration consists of a set of <<<\<template\>>>> elements that <<must>> contain:

  [[1]] <<<\<directory\>>>> - The absolute or relative path to the directory where the template files to be processed
  reside.

  [[2]] <<<\<name\>>>> - The name of the template to process.

  [[3]] <<<\<target\>>>> - The absolute or relative path to the file to write the template processing results to.

  []

  The <<<\<template\>>>> element also <<may>> contain:

  * <<<\<controller\>>>> - This element specifies a class and method to invoke to provide computed attributes to the
  template.  The children elements are <<<\<className\>>>> for the fully qualified classname and <<<\<method\>>>> for
  the name of the method to invoke.  The method can be a static <or> instance method, the type will be automatically
  detected at invocation time.  The return type of the specified method <<must>> be of the type
  <<<Map\<String, Object\>>>>.  The keys of this map will be treated as template parameter names and added to the
  template's invocation.  Properties can also be passed to the controller using a <<<\<properties\>>>> section, see
  below for more details.

  * <<<\<properties\>>>> - Ths element specifies a set of static name-value pairs to provide to the template.  Keys are
  element names and values are the text child of the element.  <<N.B.>> The properties are installed into the template
  after the results of the controller, so if there are any name collisions then the value type will be automatically
  converted into a list type by StringTemplate.

  []

  Generally, at least one of <<<\<controller\>>>> or <<<\<properties\>>>> will be needed for each template definition.

* Passing Properties to the Controller

  The <<<\<controller\>>>> element can have an optional <<<\<properties\>>>> child element to pass properties from the 
  POM file to the controller.  The format of this section is the same as any other <<<\<properties\>>>> section: 
  element names are keys and the text children of them are values.  In order to support this, the controller <<must>> 
  have a (class <or> instance) method with the following signature:

+-----+
public void setProperties(java.util.Map)
+-----+

  If properties are configured in the POM and this method exists (either as a class <or> instance method), it will be
  invoked <<before>> the method specified in the <<<\<method\>>>> element.  The keys and the values of the <<<Map>>>
  parameter will both be strings.

* Automatic Inclusion of Generated Source Paths

  If the output of a template is a Java file (ends with '.java') and it is written to a subdirectory of
  <<<target/generated-sources>>>, then that subdirectory will be automatically added to the Maven project's compile
  source path for that lifecycle execution.  This behavior is applied for all templates, so multiple directories
  could be added to the compile source path.

* Automatic Compilation of the Controller Class

  If the class file for the controller is not available when the plugin is run, the plugin will attempt to be
  compile it.  It is assumed that the source for the specified controller is in the current project.  If the class is
  not available on the classpath, and either the source file cannot be found or cannot be compiled the build will fail.

* Controlling the Compiler Used for Automatic Compilation of the Controller Class

  You can set the source and target Java versions that are used to automatically compile the controller class.  You can
  also set the version of the Maven compiler plugin that will be used.  Custom values for these parameters must be
  valid for their context: the source and target version must be valid for the Java compiler and the plugin version
  must be a valid Maven compiler plugin version.

  The default values are:

  * Source Version - 1.6

  * Target Version - 1.6

  * Maven Compiler Plugin Version - 3.0

  []

  The following is an example of using custom settings for these parameters:

+-----+

    <build>
        <plugins>
            <plugin>
                <groupId>com.webguys</groupId>
                <artifactId>string-template-maven-plugin</artifactId>
                <version>1.1</version>
                <configuration>
                    <templates>
                        <template>
                            <directory>path-to-template-directory</directory>
                            <name>template-name</name>
                            <target>path-to-output-filename</target>
                            <controller>
                                <className>fully-qualified-class-name</className>
                                <method>method-to-invoke</method>
                                <sourceVersion>1.5</sourceVersion>
                                <targetVersion>1.5</targetVersion>
                                <compilerVersion>2.3.2</compilerVersion>
                            </controller>
                        </template>
                    </templates>
                </configuration>
                <executions>
                    <execution>
                        <phase>generate-sources</phase>
                        <goals>
                            <goal>render</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>

+-----+

* Disabling Automatic Compilation of Controller Classes

  You can disable this on a per-controller basis by setting the <<<\<compile\>>>> attribute to <<false>>.  If the
  controller class is not available on the classpath and this setting is false, and exception will be thrown by the
  plugin and the build will fail.

+-----+

    <build>
        <plugins>
            <plugin>
                <groupId>com.webguys</groupId>
                <artifactId>string-template-maven-plugin</artifactId>
                <version>1.1</version>
                <configuration>
                    <templates>
                        <template>
                            <directory>path-to-template-directory</directory>
                            <name>template-name</name>
                            <target>path-to-output-filename</target>
                            <controller>
                                <className>fully-qualified-class-name</className>
                                <method>method-to-invoke</method>
                                <compile>false</compile>
                            </controller>
                        </template>
                    </templates>
                </configuration>
                <executions>
                    <execution>
                        <phase>generate-sources</phase>
                        <goals>
                            <goal>render</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>

+-----+
