Package org.codehaus.groovy.control

# Class CompilationUnit

java.lang.Object
org.codehaus.groovy.control.ProcessingUnit
org.codehaus.groovy.control.CompilationUnit

Direct Known Subclasses:
  `JavaAwareCompilationUnit`, `JavaStubCompilationUnit`

public class CompilationUnit extends ProcessingUnit
The CompilationUnit collects all compilation data as it is generated by the compiler system. You can use this object to add additional source units to the compilation, or force the compilation to be run again (to affect only the deltas).

You can also add PhaseOperations to this compilation using the addPhaseOperation method. This is commonly used when you want to wire a new AST Transformation into the compilation.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static interface`
  `CompilationUnit.ClassgenCallback`
  A callback interface you can use during the `classgen` phase of compilation as the compiler traverses the ClassNode tree.
  `static class`
  `CompilationUnit.GroovyClassOperation`
  Deprecated.
  `static interface`
  `CompilationUnit.IGroovyClassOperation`
  Performs an operation for each generated `GroovyClass`.
  `static interface`
  `CompilationUnit.IPrimaryClassNodeOperation`
  Performs an operation for each primary class node in the compilation.
  `static interface`
  `CompilationUnit.ISourceUnitOperation`
  Performs an operation for each source unit in the compilation.
  `static class`
  `CompilationUnit.PrimaryClassNodeOperation`
  Deprecated.
  `static interface`
  `CompilationUnit.ProgressCallback`
  A callback interface you can use to get a callback after every unit of the compile process.
  `static class`
  `CompilationUnit.SourceUnitOperation`
  Deprecated.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected CompileUnit`
  `ast`
  The overall AST for this CompilationUnit.
  `protected ASTTransformationsContext`
  `astTransformationsContext`
  The AST transformations state data.
  `protected CompilationUnit.ClassgenCallback`
  `classgenCallback`
  A callback called during the `classgen` phase of compilation
  `protected ClassNodeResolver`
  `classNodeResolver`
  `protected boolean`
  `configured`
  True after the first `configure(CompilerConfiguration)` operation.
  `protected boolean`
  `debug`
  If set, outputs a little more information during compilation when errors occur.
  `protected CompilationUnit.ProgressCallback`
  `progressCallback`
  A callback for use during `compile()`
  `protected Queue<SourceUnit>`
  `queuedSources`
  `protected ResolveVisitor`
  `resolveVisitor`
  `protected Map<String,SourceUnit>`
  `sources`
  The source units from which this unit is built.

  ### Fields inherited from class org.codehaus.groovy.control.ProcessingUnit

  `classLoader, configuration, errorCollector, phase, phaseComplete`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `CompilationUnit()`
  Initializes the CompilationUnit with defaults.
  `CompilationUnit(GroovyClassLoader loader)`
  Initializes the CompilationUnit with defaults except for class loader.
  `CompilationUnit(CompilerConfiguration configuration)`
  Initializes the CompilationUnit with no security considerations.
  `CompilationUnit(CompilerConfiguration configuration, CodeSource codeSource, GroovyClassLoader loader)`
  Initializes the CompilationUnit with a CodeSource for controlling security stuff and a class loader for loading classes.
  `CompilationUnit(CompilerConfiguration configuration, CodeSource codeSource, GroovyClassLoader loader, GroovyClassLoader transformLoader)`
  Initializes the CompilationUnit with a CodeSource for controlling security stuff, a class loader for loading classes, and a class loader for loading AST transformations.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addClassNode(ClassNode node)`
  Adds a ClassNode directly to the unit (i.e.
  `void`
  `addFirstPhaseOperation(CompilationUnit.IPrimaryClassNodeOperation op, int phase)`
  Adds a primary-class operation at the front of the supplied phase queue.
  `void`
  `addFirstPhaseOperation(CompilationUnit.PrimaryClassNodeOperation op, int phase)`
  Deprecated.
  `void`
  `addJavaCompilationUnits(Set<JavaFileObject> javaCompilationUnitSet)`
  Adds Java compilation units to the joint-compilation set.
  `void`
  `addNewPhaseOperation(CompilationUnit.ISourceUnitOperation op, int phase)`
  Adds a source-unit operation that becomes active only after the current phase queue drains.
  `void`
  `addNewPhaseOperation(CompilationUnit.SourceUnitOperation op, int phase)`
  Deprecated.
  `void`
  `addPhaseOperation(CompilationUnit.GroovyClassOperation op)`
  Deprecated.
  `void`
  `addPhaseOperation(CompilationUnit.IGroovyClassOperation op)`
  Adds a Groovy class operation to the output phase.
  `void`
  `addPhaseOperation(CompilationUnit.IPrimaryClassNodeOperation op, int phase)`
  Adds a primary-class operation to the supplied phase.
  `void`
  `addPhaseOperation(CompilationUnit.ISourceUnitOperation op, int phase)`
  Adds a source-unit operation to the supplied phase.
  `void`
  `addPhaseOperation(CompilationUnit.PrimaryClassNodeOperation op, int phase)`
  Deprecated.
  `void`
  `addPhaseOperation(CompilationUnit.SourceUnitOperation op, int phase)`
  Deprecated.
  `SourceUnit`
  `addSource(File file)`
  Adds a source file to the unit.
  `SourceUnit`
  `addSource(String name, InputStream stream)`
  Adds a InputStream source to the unit.
  `SourceUnit`
  `addSource(String name, String scriptText)`
  Adds an in-memory script source to this compilation unit.
  `SourceUnit`
  `addSource(URL url)`
  Adds a source file to the unit.
  `SourceUnit`
  `addSource(SourceUnit source)`
  Adds a SourceUnit to the unit.
  `void`
  `addSources(File[] files)`
  Adds a set of source files to the unit.
  `void`
  `addSources(String[] paths)`
  Adds a set of file paths to the unit.
  `void`
  `applyToPrimaryClassNodes(CompilationUnit.PrimaryClassNodeOperation op)`
  Deprecated.
  `void`
  `applyToSourceUnits(CompilationUnit.SourceUnitOperation op)`
  Deprecated.
  `void`
  `compile()`
  Compiles the compilation unit from sources through the configured target phase; a synonym for `compile(Phases.ALL)` unless an earlier phase is set via `CompilerConfiguration.setTargetPhase(int)` (GROOVY-12204).
  `void`
  `compile(int throughPhase)`
  Compiles the compilation unit from sources.
  `void`
  `configure(CompilerConfiguration configuration)`
  Configures its debugging mode and classloader classpath from a given compiler configuration.
  `protected org.objectweb.asm.ClassVisitor`
  `createClassVisitor()`
  Creates the ASM class visitor used for bytecode generation.
  `protected boolean`
  `dequeued()`
  Dequeues any source units added through addSource and resets the compiler phase to initialization.
  `CompileUnit`
  `getAST()`
  Returns the CompileUnit that roots our AST.
  `ASTTransformationsContext`
  `getASTTransformationsContext()`
  `List<GroovyClass>`
  `getClasses()`
  Get the GroovyClasses generated by compile().
  `CompilationUnit.ClassgenCallback`
  `getClassgenCallback()`
  Returns the callback invoked after class generation.
  `ClassNode`
  `getClassNode(String name)`
  Convenience routine to get the named ClassNode.
  `ClassNodeResolver`
  `getClassNodeResolver()`
  Returns the resolver used for on-demand class lookup.
  `ClassNode`
  `getFirstClassNode()`
  Convenience routine to get the first ClassNode, for when you are sure there is only one.
  `Set<JavaFileObject>`
  `getJavaCompilationUnitSet()`
  Returns the queued Java compilation units used for joint compilation.
  `CompilationUnit.ProgressCallback`
  `getProgressCallback()`
  Returns the callback invoked after each phase transition.
  `GroovyClassLoader`
  `getTransformLoader()`
  Returns the class loader for loading AST transformations.
  `Iterator<SourceUnit>`
  `iterator()`
  Returns an iterator on the unit's SourceUnits.
  `protected void`
  `mark()`
  Updates the phase marker on all sources.
  `void`
  `setClassgenCallback(CompilationUnit.ClassgenCallback visitor)`
  Sets a ClassgenCallback.
  `void`
  `setClassNodeResolver(ClassNodeResolver classNodeResolver)`
  Replaces the resolver used for on-demand class lookup.
  `void`
  `setProgressCallback(CompilationUnit.ProgressCallback callback)`
  Sets a ProgressCallback.

  ### Methods inherited from class org.codehaus.groovy.control.ProcessingUnit

  `completePhase, getClassLoader, getConfiguration, getErrorCollector, getPhase, getPhaseDescription, gotoPhase, isPhaseComplete, nextPhase, setClassLoader, setConfiguration`

  ### Methods inherited from class java.lang.Object

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

- ## Field Details

  - ### ast

    protected CompileUnit ast
    The overall AST for this CompilationUnit.

  - ### sources

    protected Map<String,SourceUnit> sources
    The source units from which this unit is built.

  - ### queuedSources

    protected Queue<SourceUnit> queuedSources

  - ### debug

    protected boolean debug
    If set, outputs a little more information during compilation when errors occur.

  - ### configured

    protected boolean configured
    True after the first `configure(CompilerConfiguration)` operation.

  - ### classgenCallback

    protected CompilationUnit.ClassgenCallback classgenCallback
    A callback called during the `classgen` phase of compilation

  - ### progressCallback

    protected CompilationUnit.ProgressCallback progressCallback
    A callback for use during `compile()`

  - ### classNodeResolver

    protected ClassNodeResolver classNodeResolver

  - ### resolveVisitor

    protected ResolveVisitor resolveVisitor

  - ### astTransformationsContext

    protected ASTTransformationsContext astTransformationsContext
    The AST transformations state data.

- ## Constructor Details

  - ### CompilationUnit

    public CompilationUnit()
    Initializes the CompilationUnit with defaults.

  - ### CompilationUnit

    public CompilationUnit(GroovyClassLoader loader)
    Initializes the CompilationUnit with defaults except for class loader.

  - ### CompilationUnit

    public CompilationUnit(CompilerConfiguration configuration)
    Initializes the CompilationUnit with no security considerations.

  - ### CompilationUnit

    public CompilationUnit(CompilerConfiguration configuration, CodeSource codeSource, GroovyClassLoader loader)
    Initializes the CompilationUnit with a CodeSource for controlling security stuff and a class loader for loading classes.

  - ### CompilationUnit

    public CompilationUnit(CompilerConfiguration configuration, CodeSource codeSource, GroovyClassLoader loader, GroovyClassLoader transformLoader)
    Initializes the CompilationUnit with a CodeSource for controlling security stuff, a class loader for loading classes, and a class loader for loading AST transformations.

    Note: The transform loader must be able to load compiler classes. That means `ProcessingUnit.classLoader` must be at last a parent to `transformLoader`. The other loader has no such constraint.

    Parameters:
      `transformLoader` - - the loader for transforms
      `loader` - - loader used to resolve classes against during compilation
      `codeSource` - - security setting for the compilation
      `configuration` - - compilation configuration

- ## Method Details

  - ### addPhaseOperation

    public void addPhaseOperation(CompilationUnit.IGroovyClassOperation op)
    Adds a Groovy class operation to the output phase.
    Parameters:
      `op` - the operation to run for generated classes

  - ### addPhaseOperation

    public void addPhaseOperation(CompilationUnit.ISourceUnitOperation op, int phase)
    Adds a source-unit operation to the supplied phase.
    Parameters:
      `op` - the operation to add
      `phase` - the phase in which to run it

  - ### addPhaseOperation

    public void addPhaseOperation(CompilationUnit.IPrimaryClassNodeOperation op, int phase)
    Adds a primary-class operation to the supplied phase.
    Parameters:
      `op` - the operation to add
      `phase` - the phase in which to run it

  - ### addFirstPhaseOperation

    public void addFirstPhaseOperation(CompilationUnit.IPrimaryClassNodeOperation op, int phase)
    Adds a primary-class operation at the front of the supplied phase queue.
    Parameters:
      `op` - the operation to add
      `phase` - the phase in which to run it

  - ### addNewPhaseOperation

    public void addNewPhaseOperation(CompilationUnit.ISourceUnitOperation op, int phase)
    Adds a source-unit operation that becomes active only after the current phase queue drains.
    Parameters:
      `op` - the operation to add
      `phase` - the phase in which to run it

  - ### configure

    public void configure(CompilerConfiguration configuration)
    Configures its debugging mode and classloader classpath from a given compiler configuration. This cannot be done more than once due to limitations in `URLClassLoader`.
    Overrides:
      `configure` in class `ProcessingUnit`

  - ### getAST

    public CompileUnit getAST()
    Returns the CompileUnit that roots our AST.

  - ### getClasses

    public List<GroovyClass> getClasses()
    Get the GroovyClasses generated by compile().

  - ### getFirstClassNode

    public ClassNode getFirstClassNode()
    Convenience routine to get the first ClassNode, for when you are sure there is only one.

  - ### getClassNode

    public ClassNode getClassNode(String name)
    Convenience routine to get the named ClassNode.

  - ### getASTTransformationsContext

    public ASTTransformationsContext getASTTransformationsContext()
    Returns:
      the AST transformations current context

  - ### getClassNodeResolver

    public ClassNodeResolver getClassNodeResolver()
    Returns the resolver used for on-demand class lookup.
    Returns:
      the active class-node resolver

  - ### setClassNodeResolver

    public void setClassNodeResolver(ClassNodeResolver classNodeResolver)
    Replaces the resolver used for on-demand class lookup.
    Parameters:
      `classNodeResolver` - the resolver to install

  - ### getJavaCompilationUnitSet

    public Set<JavaFileObject> getJavaCompilationUnitSet()
    Returns the queued Java compilation units used for joint compilation.
    Returns:
      the tracked Java compilation units

  - ### addJavaCompilationUnits

    public void addJavaCompilationUnits(Set<JavaFileObject> javaCompilationUnitSet)
    Adds Java compilation units to the joint-compilation set.
    Parameters:
      `javaCompilationUnitSet` - the Java units to add

  - ### getTransformLoader

    public GroovyClassLoader getTransformLoader()
    Returns the class loader for loading AST transformations.

  - ### addSources

    public void addSources(String[] paths)
    Adds a set of file paths to the unit.

  - ### addSources

    public void addSources(File[] files)
    Adds a set of source files to the unit.

  - ### addSource

    public SourceUnit addSource(File file)
    Adds a source file to the unit.

  - ### addSource

    public SourceUnit addSource(URL url)
    Adds a source file to the unit.

  - ### addSource

    public SourceUnit addSource(String name, InputStream stream)
    Adds a InputStream source to the unit.

  - ### addSource

    public SourceUnit addSource(String name, String scriptText)
    Adds an in-memory script source to this compilation unit.
    Parameters:
      `name` - the source name
      `scriptText` - the script text
    Returns:
      the created source unit

  - ### addSource

    public SourceUnit addSource(SourceUnit source)
    Adds a SourceUnit to the unit.

  - ### iterator

    public Iterator<SourceUnit> iterator()
    Returns an iterator on the unit's SourceUnits.

  - ### addClassNode

    public void addClassNode(ClassNode node)
    Adds a ClassNode directly to the unit (i.e. without source). WARNING: the source is needed for error reporting, using this method without setting a SourceUnit will cause NullPointerExceptions

  - ### getClassgenCallback

    public CompilationUnit.ClassgenCallback getClassgenCallback()
    Returns the callback invoked after class generation.
    Returns:
      the class-generation callback, or `null`

  - ### setClassgenCallback

    public void setClassgenCallback(CompilationUnit.ClassgenCallback visitor)
    Sets a ClassgenCallback. You can have only one, and setting it to `null` removes any existing setting.

  - ### getProgressCallback

    public CompilationUnit.ProgressCallback getProgressCallback()
    Returns the callback invoked after each phase transition.
    Returns:
      the progress callback, or `null`

  - ### setProgressCallback

    public void setProgressCallback(CompilationUnit.ProgressCallback callback)
    Sets a ProgressCallback. You can have only one, and setting it to `null` removes any existing setting.

  - ### compile

    public void compile() throws CompilationFailedException
    Compiles the compilation unit from sources through the configured target phase; a synonym for `compile(Phases.ALL)` unless an earlier phase is set via `CompilerConfiguration.setTargetPhase(int)` (GROOVY-12204).
    Throws:
      `CompilationFailedException`

  - ### compile

    public void compile(int throughPhase) throws CompilationFailedException
    Compiles the compilation unit from sources.
    Throws:
      `CompilationFailedException`

  - ### dequeued

    protected boolean dequeued() throws CompilationFailedException
    Dequeues any source units added through addSource and resets the compiler phase to initialization.

    Note: this does not mean a file is recompiled. If a SourceUnit has already passed a phase it is skipped until a higher phase is reached.

    Returns:
      true if there was a queued source
    Throws:
      `CompilationFailedException`

  - ### createClassVisitor

    protected org.objectweb.asm.ClassVisitor createClassVisitor()
    Creates the ASM class visitor used for bytecode generation.
    Returns:
      the class visitor used to emit bytecode

  - ### mark

    protected void mark() throws CompilationFailedException
    Updates the phase marker on all sources.
    Throws:
      `CompilationFailedException`

  - ### addPhaseOperation

    @Deprecated public void addPhaseOperation(CompilationUnit.GroovyClassOperation op)
    Deprecated.
    Adapts a deprecated groovy-class operation to the current API.
    Parameters:
      `op` - the operation to add

  - ### addPhaseOperation

    @Deprecated public void addPhaseOperation(CompilationUnit.SourceUnitOperation op, int phase)
    Deprecated.
    Adapts a deprecated source-unit operation to the current API.
    Parameters:
      `op` - the operation to add
      `phase` - the phase in which to run it

  - ### addPhaseOperation

    @Deprecated public void addPhaseOperation(CompilationUnit.PrimaryClassNodeOperation op, int phase)
    Deprecated.
    Adapts a deprecated primary-class operation to the current API.
    Parameters:
      `op` - the operation to add
      `phase` - the phase in which to run it

  - ### addFirstPhaseOperation

    @Deprecated public void addFirstPhaseOperation(CompilationUnit.PrimaryClassNodeOperation op, int phase)
    Deprecated.
    Adapts a deprecated primary-class operation to the front of a phase queue.
    Parameters:
      `op` - the operation to add
      `phase` - the phase in which to run it

  - ### addNewPhaseOperation

    @Deprecated public void addNewPhaseOperation(CompilationUnit.SourceUnitOperation op, int phase)
    Deprecated.
    Adapts a deprecated source-unit operation to the delayed phase queue.
    Parameters:
      `op` - the operation to add
      `phase` - the phase in which to run it

  - ### applyToSourceUnits

    @Deprecated public void applyToSourceUnits(CompilationUnit.SourceUnitOperation op) throws CompilationFailedException
    Deprecated.
    Applies a deprecated source-unit operation to all source units.
    Parameters:
      `op` - the operation to run
    Throws:
      `CompilationFailedException` - if processing fails

  - ### applyToPrimaryClassNodes

    @Deprecated public void applyToPrimaryClassNodes(CompilationUnit.PrimaryClassNodeOperation op) throws CompilationFailedException
    Deprecated.
    Applies a deprecated primary-class operation to all primary class nodes.
    Parameters:
      `op` - the operation to run
    Throws:
      `CompilationFailedException` - if processing fails