xdoclet.template
Class TemplateEngine

java.lang.Object
  |
  +--xdoclet.template.TemplateEngine

Direct Known Subclasses:

TemplateParser

public class TemplateEngine

extends java.lang.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.19 $

Author:

Rickard Oberg (rickard@dreambean.com), Ara Abrahamian (ara_e@email.com), Dmitri Colebatch (dim@bigpond.net.au)

See Also:

generate(java.lang.String)

Field Summary

protected PrettyPrintWriter	out The PrintWriter used for outputing the generated stuff.
protected java.io.File	output
static java.lang.String	TAG_MAPPINGS_FILE
protected static java.lang.String	XDOCLET_HEAD
protected static int	XDOCLET_HEAD_LEN
protected static java.lang.String	XDOCLET_PREFIX
protected static java.lang.String	XDOCLET_TAIL
protected static int	XDOCLET_TAIL_LEN

Constructor Summary

TemplateEngine(TemplateContext context)
Initialize the Template Engine.

Method Summary

void	generate(java.lang.String template) The main template parsing/processing/running logic.
int	getCurrentLineNum()
protected static int	getLineNumber(java.lang.String template, int till_index) Loops over the template content till reaching till_index index and returns the number of lines it has encountered.
java.io.File	getOutput()
TemplateTagHandler	getTagHandlerFor(java.lang.String prefix) Get the tag handler for the prefix.
java.net.URL	getTemplateURL() Returns current template URL.
protected int	handleTag(int index, java.lang.String template) Handle the tag that starts at index in the template provided.
java.lang.String	outputOf(java.lang.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(java.lang.String output)
void	setCurrentLineNum(int currentLineNum)
void	setOutput(java.io.File output)
void	setTagHandlerFor(java.lang.String prefix, TemplateTagHandler tag_handler)
void	setTemplateURL(java.net.URL templateURL) A config parameter settable from Ant build file.
void	setWriter(PrettyPrintWriter out)
static int	skipWhitespace(java.lang.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 java.lang.String TAG_MAPPINGS_FILE

XDOCLET_PREFIX

protected static java.lang.String XDOCLET_PREFIX

XDOCLET_HEAD

protected static java.lang.String XDOCLET_HEAD

XDOCLET_TAIL

protected static java.lang.String XDOCLET_TAIL

XDOCLET_HEAD_LEN

protected static int XDOCLET_HEAD_LEN

XDOCLET_TAIL_LEN

protected static 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 java.io.File output

Constructor Detail

TemplateEngine

public TemplateEngine(TemplateContext context)
               throws TemplateException

Initialize the Template Engine. Reads the XDoclet properties file, and loads any Tag handler classes specified.

Parameters:

context - The context for the build.

Throws:

TemplateException - Description of Exception

Method Detail

skipWhitespace

public static int skipWhitespace(java.lang.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(java.lang.String template,
                                   int till_index)

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

Parameters:

template - Description of Parameter

till_index - Description of Parameter

Returns:

The LineNumber value

getTemplateURL

public java.net.URL getTemplateURL()

Returns current template URL.

Returns:

The TemplateURL value

See Also:

setTemplateURL(java.net.URL)

getOutput

public java.io.File getOutput()

getCurrentLineNum

public int getCurrentLineNum()

getTagHandlerFor

public TemplateTagHandler getTagHandlerFor(java.lang.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.

setWriter

public void setWriter(PrettyPrintWriter out)

setCurrentLineNum

public void setCurrentLineNum(int currentLineNum)

setTemplateURL

public void setTemplateURL(java.net.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(java.io.File output)

setTagHandlerFor

public void setTagHandlerFor(java.lang.String prefix,
                             TemplateTagHandler tag_handler)
                      throws TemplateException

generate

public void generate(java.lang.String template)
              throws TemplateException

The main template parsing/processing/running logic. It searches for 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. Tag 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 java.lang.String outputOf(java.lang.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: 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)

print

public void print(java.lang.String output)

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,
                        java.lang.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