<?xml version="1.0" encoding="UTF-8"?>
<!--
 Licensed to the Apache Software Foundation (ASF) under one
 or more contributor license agreements.  See the NOTICE file
 distributed with this work for additional information
 regarding copyright ownership.  The ASF licenses this file
 to you under the Apache License, Version 2.0 (the
 "License"); you may not use this file except in compliance
 with the License.  You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing,
 software distributed under the License is distributed on an
 "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 KIND, either express or implied.  See the License for the
 specific language governing permissions and limitations
 under the License.
-->

<document>

 <properties>
  <title>Extending the Torque generator</title>
 </properties>

 <body>
  <section name="Using other template languages inside the Torque generator">
    <p>
      If you want to extend the Torque generator in order to use another
      template language, the following steps need to be done:
    </p>
    
    <subsection name="Define a new outlet type in the configuration XML schema">
      <p>
        The outlets which use the new template engine need to be distinguished
        from the existing outlets. This is done by defining a new outlet type
        for the new template language. The outlet type is a simple string,
        e.g. if the new template language is 
        <a href="http://groovy.codehaus.org/">groovy</a>, a good name for the
        outlet type would be <code>groovy</code>.
      </p>
      <p>
        Before the new outlet type can be used in the configuration XML,
        the configuration XML schema must be extended in order
        to make the new template type definition known to the schema validator.
        To do this, create a new schema where the standard generator XML schema
        is included. In this schema, define a new type named ${type}Outlet
        which extends the type baseOutlet. This type should have all
        necessary attributes which are needed to configure the new template
        engine.
      </p>
      <p>
        An example for extending the configuration XML schema can be found
        in the file
        <code>src/test/otherTemplateLanguages/groovyOutlet.xsd</code>
        in the torque generator project.
      </p>
    </subsection>
    <subsection name="Write a SAX handler for configuration">
      <p>
        A SAX Handler needs to be written which can create and configure
        the outlet implementation containing the new template engine.
        The SAX handler gets called on each snippet containing an outlet
        definition of the newly defined type.
      </p>
      <p>
        The new SAX Handler must have the package
        <code>org.apache.torque.generator.configuration.outlet</code>
        and its name must be ${Type}OutletSaxHandler, where ${Type} is the
        new outlet type with the first letter capitalized. For example, if
        the new outlet type is <code>groovy</code>,
        then the SAX Handler's class qualified name must be
        <code>org.apache.torque.generator.configuration.outlet.GroovyOutletSaxHandler</code>.
        You can use the class 
        <code>org.apache.torque.generator.configuration.outlet.GroovyOutletSaxHandler</code>
        in the generator's test classes as a starting point for your own
        Sax Handler.
      </p>
      <p>
        Conditions for the new SAX Handler are that it must not be abstract,
        it must inherit from
        <code>org.apache.torque.generator.configuration.outlet.OutletSaxHandler</code>.
        The new SAX Handler must have a public constructor with four arguments
        and the argument types
        <code>org.apache.torque.generator.qname.QualifiedName</code>,
        <code>org.apache.torque.generator.configuration.ConfigurationProvider</code>,
        <code>org.apache.torque.generator.configuration.paths.ProjectPaths</code>,
        <code>org.apache.torque.generator.configuration.ConfigurationHandlers</code>
        which should simply be passed to the constructor of the parent class.
      </p>
      <p>
        It is the SAX Handler's job to create an instance of an outlet
        which can handle the new template language (
        in the method <code>createOutlet</code> which needs to be implemented).
        The outlet class itself (which then can handle templates 
        of the new type) must also be implemented. See the class
        <code>org.apache.torque.generator.template.groovy.GroovyOutlet.java</code>
        in the generator's test sources as an example.
      </p>
    </subsection>
    <subsection name="Referencing the extended schema">
      <p>
        You must reference your own schema for the 
        <code>http://db.apache.org/torque/4.0/generator/configuration</code>
        XML namespace wherever you use the new template type definion.
        As an example, see the file
        <code>src/test/otherTemplateLanguages/src/main/torque-gen/outlets/outlets.xml</code>
        in the torque generator project.
      </p>
    </subsection>
    <subsection name="Using the new template type">
      <p>
        And then, of course, you need to define and use the outlets with your
        new template type. See the directory
        <code>src/test/otherTemplateLanguages</code> and its subdirectories 
        in the torque generator project for a simple example using groovy.
      </p>
    </subsection>
  </section>
 </body>
</document>