xdoclet.template

Class TemplateEngine

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

UNKNOWN: July 14, 2001

Field Summary
protected StringdocEncoding
protected PrettyPrintWriterout
The PrintWriter used for outputing the generated stuff.
protected Fileoutput
static StringTAG_MAPPINGS_FILE
protected static StringXDOCLET_HEAD
protected static intXDOCLET_HEAD_LEN
protected static StringXDOCLET_PREFIX
protected static StringXDOCLET_TAIL
protected static intXDOCLET_TAIL_LEN
Constructor Summary
protected TemplateEngine()
Method Summary
voidgenerate(String template)
The main template parsing/processing/running logic.
intgetCurrentLineNum()
Gets the CurrentLineNum attribute of the TemplateEngine object
static TemplateEnginegetEngineInstance()
Gets the EngineInstance attribute of the TemplateEngine class
protected static intgetLineNumber(String template, int tillIndex)
Loops over the template content till reaching tillIndex index and returns the number of lines it has encountered.
SetgetNamespaces()
Returns a Set of Strings that represent the registered namespaces
FilegetOutput()
Gets the Output attribute of the TemplateEngine object
TemplateTagHandlergetTagHandlerFor(String prefix)
Get the tag handler for the prefix.
URLgetTemplateURL()
Returns current template URL.
protected inthandleTag(int index, String template)
Handle the tag that starts at index in the template provided.
protected Objectinvoke(Method m, Object cmdImplProvider, Object[] params1)
Describe what the method does
protected voidinvokeContentMethod(String cmd, Properties attributes, String template, int i)
Invokes content tag implementation method named cmd with the specified set of attributes.
protected ObjectinvokeMethod(String cmd, Object[] params1, Object[] params2, String template, int i)
Invokes content tag implementation method named cmd.
StringoutputOf(String template)
Calls generate() of the specified template content but instead of outputing it to the generated file, it returns the generated content.
voidprint(String output)
Describe what the method does
voidsetCurrentLineNum(int currentLineNum)
Sets the CurrentLineNum attribute of the TemplateEngine object
voidsetDocEncoding(String string)
set output charset;
voidsetOutput(File output)
Sets the Output attribute of the TemplateEngine object
voidsetTagHandlerFor(String prefix, TemplateTagHandler tagHandler)
Sets the TagHandlerFor attribute of the TemplateEngine object
voidsetTemplateURL(URL templateURL)
A config parameter settable from Ant build file.
voidsetWriter(PrettyPrintWriter out)
Sets the Writer attribute of the TemplateEngine object
voidsetXJavaDoc(XJavaDoc xJavaDoc)
static intskipWhitespace(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.
voidstart()
A utility method used for generating the dest_file based on template_file template file.

Field Detail

docEncoding

protected transient String docEncoding

out

protected transient PrettyPrintWriter out
The PrintWriter used for outputing the generated stuff. {@link xdoclet.template.PrettyPrintWriter} tries to pretty format the generated file by removing redundant spaces/lines.

See Also: PrettyPrintWriter

output

protected transient File output

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

Constructor Detail

TemplateEngine

protected TemplateEngine()

Method Detail

generate

public void generate(String template)
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: TemplateEngine

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

handleTag

protected int handleTag(int index, String template)
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)
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

invokeContentMethod

protected void invokeContentMethod(String cmd, Properties attributes, String template, int i)
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: (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)
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: TemplateEngine TemplateEngine

outputOf

public 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. 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: TemplateEngine

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)
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()
A utility method used for generating the dest_file based on template_file template file.

Throws: TemplateException Description of Exception