org.teatrove.tea.compiler
Class Compiler

java.lang.Object
  org.teatrove.tea.compiler.Compiler

Direct Known Subclasses:

AbstractCompiler

public abstract class Compiler
extends Object

The Tea compiler. This class is abstract, and a few concrete implementations can be found in the org.teatrove.tea.util package.

A Compiler instance should be used for only one "build" because some information is cached internally like parse trees and error count.

Author:

Brian S O'Neill

See Also:

FileCompiler, ResourceCompiler

Constructor Summary

Compiler()

Compiler(Map<String,Template> parseTreeMap)
This constructor allows template signatures to be shared among compiler instances.

Method Summary

void	addErrorListener(ErrorListener listener) Add an ErrorListener in order receive events of compile-time errors.
void	addImportedPackage(String imported) Add an imported package that all templates will have.
void	addImportedPackages(String[] imports) Add all imported packages that all templates will have.
void	addStatusListener(StatusListener listener) Add a StatusListener in order to receive events of compilation progress.
String[]	compile(String name) Compile a single compilation unit.
String[]	compile(String[] names) Compile a list of compilation units.
protected CodeGenerator	createCodeGenerator(CompilationUnit unit) Default implementation returns a new JavaClassGenerator.
protected abstract CompilationUnit	createCompilationUnit(String name)
protected Parser	createParser(Scanner scanner, CompilationUnit unit)
protected Scanner	createScanner(SourceReader reader, CompilationUnit unit)
protected SourceReader	createSourceReader(CompilationUnit unit) Default implementation returns a SourceReader that uses "<%" and "%>" as code delimiters.
protected TypeChecker	createTypeChecker(CompilationUnit unit)
ClassLoader	getClassLoader() Returns the ClassLoader used by the Compiler, or null if none set.
CompilationUnit	getCompilationUnit(String name, CompilationUnit from) Returns a compilation unit associated with the given name, or null if not found or the compilation unit is .
int	getErrorCount()
String[]	getImportedPackages() Returns the list of imported packages that all templates have.
Template	getParseTree(CompilationUnit unit) Called by the Compiler or by a CompilationUnit when its parse tree is requested.
Class<?>	getRuntimeContext() Return a class that defines a template's runtime context.
Method[]	getRuntimeContextMethods() Returns all the methods available in the runtime context.
String	getRuntimeReceiver() Return the name of a method in the runtime context to bind to for receiving objects emitted by templates.
String	getRuntimeStringConverter() Return the name of a method in the runtime context to bind to for converting objects and primitives to strings.
Method[]	getStringConverterMethods() Returns the set of methods that are used to perform conversion to strings.
boolean	isCodeGenerationEnabled() Returns true if code generation is enabled.
boolean	isExceptionGuardianEnabled() Returns true if the exception guardian is enabled.
Class<?>	loadClass(String name) Loads and returns a class by the fully qualified name given.
void	preserveParseTree(String name) After a template is compiled, all but the root node of its parse tree is clipped, in order to save memory.
void	removeErrorListener(ErrorListener listener)
void	removeStatusListener(StatusListener listener)
void	setClassLoader(ClassLoader loader) Sets the ClassLoader to use to load classes with.
void	setCodeGenerationEnabled(boolean flag) By default, code generation is enabled.
void	setExceptionGuardianEnabled(boolean flag)
void	setRuntimeContext(Class<?> contextClass) Call to override the default runtime context class that a template is compiled to use.
abstract boolean	sourceExists(String name)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Compiler

public Compiler()

Compiler

public Compiler(Map<String,Template> parseTreeMap)

This constructor allows template signatures to be shared among compiler instances. This is useful in interactive environments, where compilation is occurring on a regular basis, but most called templates are not being modified. The Compiler will map qualified template names to ParseTree objects that have their code removed. Removing a template entry from the map will force the compiler to re-parse the template if it is called. Any template passed into the compile method will always be re-parsed, even if its parse tree is already present in the map.

Parameters:

parseTreeMap - map should be thread-safe

Method Detail

addErrorListener

public void addErrorListener(ErrorListener listener)

Add an ErrorListener in order receive events of compile-time errors.

See Also:

ConsoleErrorReporter

removeErrorListener

public void removeErrorListener(ErrorListener listener)

addStatusListener

public void addStatusListener(StatusListener listener)

Add a StatusListener in order to receive events of compilation progress.

removeStatusListener

public void removeStatusListener(StatusListener listener)

setCodeGenerationEnabled

public void setCodeGenerationEnabled(boolean flag)

By default, code generation is enabled. Passing false disables the code generation phase of the compiler.

isCodeGenerationEnabled

public boolean isCodeGenerationEnabled()

Returns true if code generation is enabled. The default setting is true.

setExceptionGuardianEnabled

public void setExceptionGuardianEnabled(boolean flag)

isExceptionGuardianEnabled

public boolean isExceptionGuardianEnabled()

Returns true if the exception guardian is enabled. The default setting is false.

setClassLoader

public void setClassLoader(ClassLoader loader)

Sets the ClassLoader to use to load classes with. If set to null, then classes are loaded using Class.forName.

getClassLoader

public ClassLoader getClassLoader()

Returns the ClassLoader used by the Compiler, or null if none set.

loadClass

public Class<?> loadClass(String name)
                   throws ClassNotFoundException

Loads and returns a class by the fully qualified name given. If a ClassLoader is specified, it is used to load the class. Otherwise, the class is loaded via Class.forName.

Throws:

ClassNotFoundException

See Also:

setClassLoader(ClassLoader)

preserveParseTree

public void preserveParseTree(String name)

After a template is compiled, all but the root node of its parse tree is clipped, in order to save memory. Applications that wish to traverse CompilationUnit parse trees should call this method to preserve them. This method must be called prior to compilation and prior to requesting a parse tree from a CompilationUnit.

Parameters:

name - fully qualified name of template whose parse tree is to be preserved.

compile

public String[] compile(String name)
                 throws IOException

Compile a single compilation unit. This method can be called multiple times, but it will not compile compilation units that have already been compiled.

Parameters:

name - the fully qualified template name

Returns:

The names of all the sources compiled by this compiler

Throws:

IOException

compile

public String[] compile(String[] names)
                 throws IOException

Compile a list of compilation units. This method can be called multiple times, but it will not compile compilation units that have already been compiled.

Parameters:

names - an array of fully qualified template names

Returns:

The names of all the sources compiled by this compiler

Throws:

IOException

getErrorCount

public int getErrorCount()

getCompilationUnit

public CompilationUnit getCompilationUnit(String name,
                                          CompilationUnit from)

Returns a compilation unit associated with the given name, or null if not found or the compilation unit is .

Parameters:

name - the requested name

from - optional CompilationUnit is passed because requested name should be found relative to it.

getImportedPackages

public String[] getImportedPackages()

Returns the list of imported packages that all templates have. Template parameters can abbreviate the names of all classes in these packages.

addImportedPackage

public void addImportedPackage(String imported)

Add an imported package that all templates will have.

Parameters:

imported - The fully-qualified package name

addImportedPackages

public void addImportedPackages(String[] imports)

Add all imported packages that all templates will have.

Parameters:

imports - The fully-qualified package name

getRuntimeContext

public Class<?> getRuntimeContext()

Return a class that defines a template's runtime context. The runtime context contains methods that are callable by templates. A template is compiled such that the first parameter of its execute method must be an instance of the runtime context.

Default implementation returns org.teatrove.tea.runtime.UtilityContext.

See Also:

UtilityContext

setRuntimeContext

public void setRuntimeContext(Class<?> contextClass)

Call to override the default runtime context class that a template is compiled to use.

See Also:

Context

getRuntimeContextMethods

public final Method[] getRuntimeContextMethods()

Returns all the methods available in the runtime context.

getRuntimeReceiver

public String getRuntimeReceiver()

Return the name of a method in the runtime context to bind to for receiving objects emitted by templates. The compiler will bind to the closest matching public method based on the type of its single parameter.

Default implementation returns "print".

getRuntimeStringConverter

public String getRuntimeStringConverter()

Return the name of a method in the runtime context to bind to for converting objects and primitives to strings. The compiler will bind to the closest matching public method based on the type of its single parameter.

Default implementation returns "toString". Returning null indicates that a static String.valueOf method should be invoked.

getStringConverterMethods

public final Method[] getStringConverterMethods()

Returns the set of methods that are used to perform conversion to strings. The compiler will bind to the closest matching method based on its parameter type.

sourceExists

public abstract boolean sourceExists(String name)

Returns:

true if source exists for the given qualified name

createCompilationUnit

protected abstract CompilationUnit createCompilationUnit(String name)

createSourceReader

protected SourceReader createSourceReader(CompilationUnit unit)
                                   throws IOException

Default implementation returns a SourceReader that uses "<%" and "%>" as code delimiters.

Throws:

IOException

createScanner

protected Scanner createScanner(SourceReader reader,
                                CompilationUnit unit)
                         throws IOException

Throws:

IOException

createParser

protected Parser createParser(Scanner scanner,
                              CompilationUnit unit)
                       throws IOException

Throws:

IOException

createTypeChecker

protected TypeChecker createTypeChecker(CompilationUnit unit)

createCodeGenerator

protected CodeGenerator createCodeGenerator(CompilationUnit unit)
                                     throws IOException

Default implementation returns a new JavaClassGenerator.

Throws:

IOException

See Also:

JavaClassGenerator

getParseTree

public Template getParseTree(CompilationUnit unit)

Called by the Compiler or by a CompilationUnit when its parse tree is requested. Requesting a parse tree may cause template code to be generated.