xdoclet.template
Class TemplateEngine

java.lang.Object
  extended by 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.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  java.lang.String docEncoding
           
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
protected TemplateEngine()
           
 
Method Summary
 void generate(java.lang.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(java.lang.String template, int tillIndex)
          Loops over the template content till reaching tillIndex index and returns the number of lines it has encountered.
 java.util.Set getNamespaces()
          Returns a Set of Strings that represent the registered namespaces
 java.io.File getOutput()
          Gets the Output attribute of the TemplateEngine object
 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.
protected  java.lang.Object invoke(java.lang.reflect.Method m, java.lang.Object cmdImplProvider, java.lang.Object[] params1)
          Describe what the method does
protected  void invokeContentMethod(java.lang.String cmd, java.util.Properties attributes, java.lang.String template, int i)
          Invokes content tag implementation method named cmd with the specified set of attributes.
protected  java.lang.Object invokeMethod(java.lang.String cmd, java.lang.Object[] params1, java.lang.Object[] params2, java.lang.String template, int i)
          Invokes content tag implementation method named cmd.
 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)
          Describe what the method does
 void setCurrentLineNum(int currentLineNum)
          Sets the CurrentLineNum attribute of the TemplateEngine object
 void setDocEncoding(java.lang.String string)
          set output charset;
 void setOutput(java.io.File output)
          Sets the Output attribute of the TemplateEngine object
 void setTagHandlerFor(java.lang.String prefix, TemplateTagHandler tagHandler)
          Sets the TagHandlerFor attribute of the TemplateEngine object
 void setTemplateURL(java.net.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(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
See Also:
Constant Field Values

XDOCLET_PREFIX

protected static final java.lang.String XDOCLET_PREFIX

XDOCLET_HEAD

protected static final java.lang.String XDOCLET_HEAD

XDOCLET_TAIL

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

docEncoding

protected transient java.lang.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(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 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 java.net.URL getTemplateURL()
Returns current template URL.

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

getOutput

public java.io.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(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.

getNamespaces

public java.util.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(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)
Sets the Output attribute of the TemplateEngine object

Parameters:
output - The new Output value

setTagHandlerFor

public void setTagHandlerFor(java.lang.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(java.lang.String string)
set output charset;

Parameters:
string -

print

public final void print(java.lang.String output)
Describe what the method does

Parameters:
output - Describe what the parameter does

generate

public void generate(java.lang.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 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: <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,
                        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

invokeMethod

protected java.lang.Object invokeMethod(java.lang.String cmd,
                                        java.lang.Object[] params1,
                                        java.lang.Object[] params2,
                                        java.lang.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(java.lang.String cmd,
                                   java.util.Properties attributes,
                                   java.lang.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 java.lang.Object invoke(java.lang.reflect.Method m,
                                  java.lang.Object cmdImplProvider,
                                  java.lang.Object[] params1)
                           throws java.lang.reflect.InvocationTargetException,
                                  java.lang.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:
java.lang.reflect.InvocationTargetException - Describe the exception
java.lang.IllegalAccessException - Describe the exception
TemplateException - Describe the exception

http://xdoclet.sourceforge.net/