com.go.tea.compiler
Class Compiler

java.lang.Object
  |
  +--com.go.tea.compiler.Compiler
Direct Known Subclasses:
AbstractFileCompiler, ResourceCompiler, StringCompiler

public abstract class Compiler
extends java.lang.Object

The Tea compiler. This class is abstract, and a few concrete implementations can be found in the com.go.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.

Version:
58 , 7/26/01
Author:
Brian S O'Neill
See Also:
FileCompiler, ResourceCompiler

Constructor Summary
Compiler()
           
Compiler(java.util.Map 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 addStatusListener(StatusListener listener)
          Add a StatusListener in order to receive events of compilation progress.
 java.lang.String[] compile(java.lang.String name)
          Compile a single compilation unit.
 java.lang.String[] compile(java.lang.String[] names)
          Compile a list of compilation units.
protected  CodeGenerator createCodeGenerator(CompilationUnit unit)
          Default implementation returns a new JavaClassGenerator.
protected abstract  CompilationUnit createCompilationUnit(java.lang.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)
           
 java.lang.ClassLoader getClassLoader()
          Returns the ClassLoader used by the Compiler, or null if none set.
 CompilationUnit getCompilationUnit(java.lang.String name, CompilationUnit from)
          Returns a compilation unit associated with the given name, or null if not found.
 int getErrorCount()
           
static java.lang.String[] getImportedPackages()
          Returns the list of imported packages that all templates have.
 java.lang.Class getRuntimeContext()
          Return a class that defines a template's runtime context.
 java.lang.reflect.Method[] getRuntimeContextMethods()
          Returns all the methods available in the runtime context.
 java.lang.String getRuntimeReceiver()
          Return the name of a method in the runtime context to bind to for receiving objects emitted by templates.
 java.lang.String getRuntimeStringConverter()
          Return the name of a method in the runtime context to bind to for converting objects and primitives to strings.
 java.lang.reflect.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.
 java.lang.Class loadClass(java.lang.String name)
          Loads and returns a class by the fully qualified name given.
 void preserveParseTree(java.lang.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(java.lang.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(java.lang.Class contextClass)
          Call to override the default runtime context class that a template is compiled to use.
abstract  boolean sourceExists(java.lang.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(java.util.Map 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(java.lang.ClassLoader loader)
Sets the ClassLoader to use to load classes with. If set to null, then classes are loaded using Class.forName.

getClassLoader

public java.lang.ClassLoader getClassLoader()
Returns the ClassLoader used by the Compiler, or null if none set.

loadClass

public java.lang.Class loadClass(java.lang.String name)
                          throws java.lang.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.
See Also:
setClassLoader(ClassLoader)

preserveParseTree

public void preserveParseTree(java.lang.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 java.lang.String[] compile(java.lang.String name)
                           throws java.io.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:
java.io.IOException -  

compile

public java.lang.String[] compile(java.lang.String[] names)
                           throws java.io.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:
java.io.IOException -  

getErrorCount

public int getErrorCount()

getCompilationUnit

public CompilationUnit getCompilationUnit(java.lang.String name,
                                          CompilationUnit from)
Returns a compilation unit associated with the given name, or null if not found.
Parameters:
name - the requested name
from - optional CompilationUnit is passed because requested name should be found relative to it.

getImportedPackages

public static final java.lang.String[] getImportedPackages()
Returns the list of imported packages that all templates have. This always returns "java.lang" and "java.util". Template parameters can abbreviate the names of all classes in java.lang and java.util.

getRuntimeContext

public java.lang.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 com.go.tea.runtime.UtilityContext.

See Also:
UtilityContext

setRuntimeContext

public void setRuntimeContext(java.lang.Class contextClass)
Call to override the default runtime context class that a template is compiled to use.
See Also:
Context

getRuntimeContextMethods

public final java.lang.reflect.Method[] getRuntimeContextMethods()
Returns all the methods available in the runtime context.

getRuntimeReceiver

public java.lang.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 java.lang.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 java.lang.reflect.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(java.lang.String name)
Returns:
true if source exists for the given qualified name

createCompilationUnit

protected abstract CompilationUnit createCompilationUnit(java.lang.String name)

createSourceReader

protected SourceReader createSourceReader(CompilationUnit unit)
                                   throws java.io.IOException
Default implementation returns a SourceReader that uses "<%" and "%>" as code delimiters.

createScanner

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

createParser

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

createTypeChecker

protected TypeChecker createTypeChecker(CompilationUnit unit)

createCodeGenerator

protected CodeGenerator createCodeGenerator(CompilationUnit unit)
                                     throws java.io.IOException
Default implementation returns a new JavaClassGenerator.
See Also:
JavaClassGenerator