xdoclet.template

Class TemplateEngine

Known Direct 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.38 $

Authors:
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

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
protected String
docEncoding
protected PrettyPrintWriter
out
The PrintWriter used for outputing the generated stuff.
protected File
output

Constructor Summary

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)
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.

Field Details

TAG_MAPPINGS_FILE

public static final String TAG_MAPPINGS_FILE


XDOCLET_HEAD

protected static final String XDOCLET_HEAD


XDOCLET_HEAD_LEN

protected static final int XDOCLET_HEAD_LEN


XDOCLET_PREFIX

protected static final String XDOCLET_PREFIX


XDOCLET_TAIL

protected static final String XDOCLET_TAIL


XDOCLET_TAIL_LEN

protected static final int XDOCLET_TAIL_LEN


docEncoding

protected String docEncoding


out

protected 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 File output

Constructor Details

TemplateEngine

protected TemplateEngine()

Method Details

generate

public void generate(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. 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)


getCurrentLineNum

public int getCurrentLineNum()
Gets the CurrentLineNum attribute of the TemplateEngine object

Returns:
The CurrentLineNum value


getEngineInstance

public static TemplateEngine getEngineInstance()
Gets the EngineInstance attribute of the TemplateEngine class

Returns:
The EngineInstance 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


getNamespaces

public Set getNamespaces()
Returns a Set of Strings that represent the registered namespaces

Returns:


getOutput

public File getOutput()
Gets the Output attribute of the TemplateEngine object

Returns:
The Output 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.


getTemplateURL

public URL getTemplateURL()
Returns current template URL.

Returns:
The TemplateURL value

See Also:
setTemplateURL(java.net.URL)


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


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:
TemplateException - Describe the exception


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)


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, 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)


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: 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 final void print(String output)
Describe what the method does

Parameters:
output - Describe what the parameter does


setCurrentLineNum

public void setCurrentLineNum(int currentLineNum)
Sets the CurrentLineNum attribute of the TemplateEngine object

Parameters:
currentLineNum - The new CurrentLineNum value


setDocEncoding

public void setDocEncoding(String string)
set output charset;

Parameters:
string -


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


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()


setWriter

public void setWriter(PrettyPrintWriter out)
Sets the Writer attribute of the TemplateEngine object

Parameters:
out - The new Writer value


setXJavaDoc

public void setXJavaDoc(XJavaDoc xJavaDoc)


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


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