## xdoclet.template
Class TemplateEngine

    java.lang.Object
      xdoclet.template.TemplateEngine

Direct Known Subclasses:
  TemplateParser

public class TemplateEngine
extends Object

The default template engine used by derived SubTasks. It looks for XML-ish strings, just like JSP tag libraries. There's no support for scriptlets, because it's cleaner to use and implementing the XML-ish tags is easy, they are not heavyweight like jsp taglib implementations and there's no need for something like taglib.tld.

Version:
  $Revision: 1.39 $
Author:
  Rickard Oberg (rickard@dreambean.com), Ara Abrahamian (ara_e@email.com), Dmitri Colebatch (dim@bigpond.net.au)
See Also:
  `generate(java.lang.String)`
created
  July 14, 2001

Field Summary
`protected String` `docEncoding`
`protected PrettyPrintWriter` `out` The PrintWriter used for outputing the generated stuff.
`protected File` `output`
`static String` `TAG_MAPPINGS_FILE`
`protected static String` `XDOCLET_HEAD`
`protected static int` `XDOCLET_HEAD_LEN`
`protected static String` `XDOCLET_PREFIX`
`protected static String` `XDOCLET_TAIL`
`protected static int` `XDOCLET_TAIL_LEN`

Constructor Summary
`protected` `TemplateEngine()`

Method Summary
`void` `generate(String template)` The main template parsing/processing/running logic.
`int` `getCurrentLineNum()` Gets the CurrentLineNum attribute of the TemplateEngine object
`static TemplateEngine` `getEngineInstance()` Gets the EngineInstance attribute of the TemplateEngine class
`protected static int` `getLineNumber(String template, int tillIndex)` Loops over the `template` content till reaching `tillIndex` index and returns the number of lines it has encountered.
`Set` `getNamespaces()` Returns a Set of Strings that represent the registered namespaces
`File` `getOutput()` Gets the Output attribute of the TemplateEngine object
`TemplateTagHandler` `getTagHandlerFor(String prefix)` Get the tag handler for the prefix.
`URL` `getTemplateURL()` Returns current template URL.
`protected int` `handleTag(int index, String template)` Handle the tag that starts at `index` in the `template` provided.
`protected Object` `invoke(Method m, Object cmdImplProvider, Object[] params1)` Describe what the method does
`protected void` `invokeContentMethod(String cmd, Properties attributes, String template, int i)` Invokes content tag implementation method named `cmd` with the specified set of attributes.
`protected Object` `invokeMethod(String cmd, Object[] params1, Object[] params2, String template, int i)` Invokes content tag implementation method named `cmd`.
`String` `outputOf(String template)` Calls `generate()` of the specified template content but instead of outputing it to the generated file, it returns the generated content.
`void` `print(String output)` Describe what the method does
`void` `setCurrentLineNum(int currentLineNum)` Sets the CurrentLineNum attribute of the TemplateEngine object
`void` `setDocEncoding(String string)` set output charset;
`void` `setOutput(File output)` Sets the Output attribute of the TemplateEngine object
`void` `setTagHandlerFor(String prefix, TemplateTagHandler tagHandler)` Sets the TagHandlerFor attribute of the TemplateEngine object
`void` `setTemplateURL(URL templateURL)` A config parameter settable from Ant build file.
`void` `setWriter(PrettyPrintWriter out)` Sets the Writer attribute of the TemplateEngine object
`void` `setXJavaDoc(xjavadoc.XJavaDoc xJavaDoc)`
`static int` `skipWhitespace(String template, int i)` Skips whitespaces, starting from index `i` till the first non-whitespace character or end of `template` and returns the new index.
`void` `start()` A utility method used for generating the dest_file based on template_file template file.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### TAG_MAPPINGS_FILE

    public static final String TAG_MAPPINGS_FILE

See Also:
  Constant Field Values

### XDOCLET_PREFIX

    protected static final String XDOCLET_PREFIX

### XDOCLET_HEAD

    protected static final String XDOCLET_HEAD

### XDOCLET_TAIL

    protected static final String XDOCLET_TAIL

### XDOCLET_HEAD_LEN

    protected static final int XDOCLET_HEAD_LEN

### XDOCLET_TAIL_LEN

    protected static final int XDOCLET_TAIL_LEN

### out

    protected transient PrettyPrintWriter out

  The PrintWriter used for outputing the generated stuff. `PrettyPrintWriter` tries to pretty format the generated file by removing redundant spaces/lines.

  See Also:
    `PrettyPrintWriter`

### output

    protected transient File output

### docEncoding

    protected transient String docEncoding

Constructor Detail

### TemplateEngine

    protected TemplateEngine()

Method Detail

### getEngineInstance

    public static TemplateEngine getEngineInstance()

  Gets the EngineInstance attribute of the TemplateEngine class

  Returns:
    The EngineInstance value

### skipWhitespace

    public static int skipWhitespace(String template,
                                     int i)

  Skips whitespaces, starting from index `i` till the first non-whitespace character or end of `template` and returns the new index.

  Parameters:
    `template` - Description of Parameter
    `i` - Description of Parameter
  Returns:
    Description of the Returned Value

### getLineNumber

    protected static int getLineNumber(String template,
                                       int tillIndex)

  Loops over the `template` content till reaching `tillIndex` index and returns the number of lines it has encountered.

  Parameters:
    `template` - Description of Parameter
    `tillIndex` - Description of Parameter
  Returns:
    The LineNumber value

### getTemplateURL

    public URL getTemplateURL()

  Returns current template URL.

  Returns:
    The TemplateURL value
  See Also:
    `setTemplateURL(java.net.URL)`

### getOutput

    public File getOutput()

  Gets the Output attribute of the TemplateEngine object

  Returns:
    The Output value

### getCurrentLineNum

    public int getCurrentLineNum()

  Gets the CurrentLineNum attribute of the TemplateEngine object

  Returns:
    The CurrentLineNum value

### getTagHandlerFor

    public TemplateTagHandler getTagHandlerFor(String prefix)
                                        throws TemplateException

  Get the tag handler for the prefix.

  Parameters:
    `prefix` - The prefix that the tag handler is mapped to
  Returns:
    The TemplateTagHandler for the specified prefix. ALways non-null.
  Throws:
    `TemplateException` - If there is no tag handler class for the prefix specified.

### getNamespaces

    public Set getNamespaces()

  Returns a Set of Strings that represent the registered namespaces

  Returns:

### setXJavaDoc

    public void setXJavaDoc(xjavadoc.XJavaDoc xJavaDoc)

### setWriter

    public void setWriter(PrettyPrintWriter out)

  Sets the Writer attribute of the TemplateEngine object

  Parameters:
    `out` - The new Writer value

### setCurrentLineNum

    public void setCurrentLineNum(int currentLineNum)

  Sets the CurrentLineNum attribute of the TemplateEngine object

  Parameters:
    `currentLineNum` - The new CurrentLineNum value

### setTemplateURL

    public void setTemplateURL(URL templateURL)

  A config parameter settable from Ant build file. It sets the current template file to `templateURL`, so thereafter the new template file is used.

  Parameters:
    `templateURL` - The new TemplateFile value
  See Also:
    `getTemplateURL()`

### setOutput

    public void setOutput(File output)

  Sets the Output attribute of the TemplateEngine object

  Parameters:
    `output` - The new Output value

### setTagHandlerFor

    public void setTagHandlerFor(String prefix,
                                 TemplateTagHandler tagHandler)
                          throws TemplateException

  Sets the TagHandlerFor attribute of the TemplateEngine object

  Parameters:
    `prefix` - The new TagHandlerFor value
    `tagHandler` - The new TagHandlerFor value
  Throws:
    `TemplateException` - Describe the exception

### setDocEncoding

    public void setDocEncoding(String string)

  set output charset;

  Parameters:
    `string` -

### print

    public final void print(String output)

  Describe what the method does

  Parameters:
    `output` - Describe what the parameter does

### generate

    public void generate(String template)
                  throws TemplateException

  The main template parsing/processing/running logic. It searches for <XDoclet: string, parses what is found after it till a matching </XDoclet: is found in case of a block tag, or till a /> is found in case of a content tag. It automatically calls the relevent tag implementation method with the correct parameters. If a block tag, then the tag implementation accepts two parameters, the body of the block tag as a string and a Properties object containing all attributes. Note that if the tag doesn't have any attributes the corresponding tag implementation typically only accepts a single string value denoting the block body, though it can also accept a Properties as the second parameter. Tags that may or may not have attributes can safely accept the second Properties object, which will be filled either by nothing or by all the given attributes. Content tag implementation methods have no parameter but should return a String containing the result that should be printed to the generated file. XTag implementation methods should define and throw org.apache.tools.ant.TemplateException if any serious error occurs.

  Parameters:
    `template` - Description of Parameter
  Throws:
    `TemplateException` - Description of Exception
  See Also:
    `outputOf(java.lang.String)`

### outputOf

    public String outputOf(String template)
                    throws TemplateException

  Calls `generate()` of the specified template content but instead of outputing it to the generated file, it returns the generated content. It's useful for cases where you want to synthesize the result but use it instead of roughly outputing it, for example it's used for the content tags nested inside an attribute value such as: `<XDoclet:blabla param1="<XDoclet:aContentTag/>"/>` where we obviously don't want to output the result of `aContentTag` but use it as the value of the `param1` parameter.

  Parameters:
    `template` - Description of Parameter
  Returns:
    Description of the Returned Value
  Throws:
    `TemplateException` - Description of Exception
  See Also:
    `generate(java.lang.String)`

### start

    public void start()
               throws TemplateException

  A utility method used for generating the dest_file based on template_file template file.

  Throws:
    `TemplateException` - Description of Exception

### handleTag

    protected int handleTag(int index,
                            String template)
                     throws TemplateException

  Handle the tag that starts at `index` in the `template` provided.

  Parameters:
    `index` - The index that the tag to handle starts at.
    `template` - The template the tag is in.
  Returns:
    The index where the tag finished.
  Throws:
    `TemplateException` - Description of Exception

### invokeMethod

    protected Object invokeMethod(String cmd,
                                  Object[] params1,
                                  Object[] params2,
                                  String template,
                                  int i)
                           throws TemplateException

  Invokes content tag implementation method named `cmd`. It first tries with parameters `params1` then if not successful tries `param2`. This is used for cases where it's not obvious whether the tag implementation method expects a Properties object or no parameter at all (the tag takes no attributes).

  Parameters:
    `cmd` - The command to be executed. Everything after the `<XDoclet:` in the template.
    `params1` - Description of Parameter
    `params2` - Description of Parameter
    `template` - Description of Parameter
    `i` - Description of Parameter
  Returns:
    Description of the Returned Value
  Throws:
    `TemplateException` - Description of Exception
  See Also:
    `#invokeBlockMethod(java.lang.String,java.lang.String,java.util.Properties,java.lang.String,int)`, `invokeContentMethod(java.lang.String,java.util.Properties,java.lang.String,int)`

### invokeContentMethod

    protected void invokeContentMethod(String cmd,
                                       Properties attributes,
                                       String template,
                                       int i)
                                throws TemplateException

  Invokes content tag implementation method named `cmd` with the specified set of attributes. If `attributes` Properties object is not empty it tries to find a method taking one parameter (Properties attributes), otherwise a method with no parameter.

  Parameters:
    `cmd` - Description of Parameter
    `attributes` - Description of Parameter
    `template` - Description of Parameter
    `i` - Description of Parameter
  Throws:
    `TemplateException` - Description of Exception
  See Also:
    `invokeMethod(java.lang.String,java.lang.Object[],java.lang.Object[],java.lang.String,int)`

### invoke

    protected Object invoke(Method m,
                            Object cmdImplProvider,
                            Object[] params1)
                     throws InvocationTargetException,
                            IllegalAccessException,
                            TemplateException

  Describe what the method does

  Parameters:
    `m` - Describe what the parameter does
    `cmdImplProvider` - Describe what the parameter does
    `params1` - Describe what the parameter does
  Returns:
    Describe the return value
  Throws:
    `InvocationTargetException` - Describe the exception
    `IllegalAccessException` - Describe the exception
    `TemplateException` - Describe the exception

http://xdoclet.sourceforge.net/