Package: org.codehaus.groovy.control

## [Java] Class CompilationUnit

- org.codehaus.groovy.control.CompilationUnit

-     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
    Modifiers | Name | Description
    --- | --- | ---
    `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` | Compatibility base type for deprecated Groovy-class operations.
    `interface` | `CompilationUnit.IGroovyClassOperation` | Performs an operation for each generated GroovyClass.
    `interface` | `CompilationUnit.IPrimaryClassNodeOperation` | Performs an operation for each primary class node in the compilation.
    `interface` | `CompilationUnit.ISourceUnitOperation` | Performs an operation for each source unit in the compilation.
    `static class` | `CompilationUnit.PrimaryClassNodeOperation` | Compatibility base type for deprecated primary-class operations.
    `interface` | `CompilationUnit.ProgressCallback` | A callback interface you can use to get a callback after every unit of the compile process.
    `static class` | `CompilationUnit.SourceUnitOperation` | Compatibility base type for deprecated source-unit operations.

  - ### Field Summary

    Fields
    Modifiers | Name | Description
    --- | --- | ---
    `protected CompileUnit` | `ast` |
    `protected ASTTransformationsContext` | `astTransformationsContext` | The AST transformations state data.
    `protected ClassNodeResolver` | `classNodeResolver` |
    `protected CompilationUnit.ClassgenCallback` | `classgenCallback` | A callback called during the `classgen` phase of compilation
    `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.

  - Inherited fields
    Fields inherited from class | Fields
    --- | ---
    `class ProcessingUnit` | `classLoader, configuration, errorCollector, phase, phaseComplete`

  - ### Constructor Summary

    Constructors
    Constructor and 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.

  - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `` | `public void` | `addClassNode(ClassNode node)` Adds a ClassNode directly to the unit (i.e. without source).
    `` | `public void` | `addFirstPhaseOperation(CompilationUnit.IPrimaryClassNodeOperation op, int phase)` Adds a primary-class operation at the front of the supplied phase queue.
    `` | `public void` | `addFirstPhaseOperation(CompilationUnit.PrimaryClassNodeOperation op, int phase)` Adapts a deprecated primary-class operation to the front of a phase queue.
    `` | `public void` | `addJavaCompilationUnits(Set<JavaFileObject> javaCompilationUnitSet)` Adds Java compilation units to the joint-compilation set.
    `` | `public void` | `addNewPhaseOperation(CompilationUnit.ISourceUnitOperation op, int phase)` Adds a source-unit operation that becomes active only after the current phase queue drains.
    `` | `public void` | `addNewPhaseOperation(CompilationUnit.SourceUnitOperation op, int phase)` Adapts a deprecated source-unit operation to the delayed phase queue.
    `` | `public void` | `addPhaseOperation(CompilationUnit.IGroovyClassOperation op)` Adds a Groovy class operation to the output phase.
    `` | `public void` | `addPhaseOperation(CompilationUnit.ISourceUnitOperation op, int phase)` Adds a source-unit operation to the supplied phase.
    `` | `public void` | `addPhaseOperation(CompilationUnit.IPrimaryClassNodeOperation op, int phase)` Adds a primary-class operation to the supplied phase.
    `` | `public void` | `addPhaseOperation(CompilationUnit.GroovyClassOperation op)` Adapts a deprecated groovy-class operation to the current API.
    `` | `public void` | `addPhaseOperation(CompilationUnit.SourceUnitOperation op, int phase)` Adapts a deprecated source-unit operation to the current API.
    `` | `public void` | `addPhaseOperation(CompilationUnit.PrimaryClassNodeOperation op, int phase)` Adapts a deprecated primary-class operation to the current API.
    `` | `public SourceUnit` | `addSource(File file)` Adds a source file to the unit.
    `` | `public SourceUnit` | `addSource(URL url)` Adds a source file to the unit.
    `` | `public SourceUnit` | `addSource(String name, InputStream stream)` Adds a InputStream source to the unit.
    `` | `public SourceUnit` | `addSource(String name, String scriptText)` Adds an in-memory script source to this compilation unit.
    `` | `public SourceUnit` | `addSource(SourceUnit source)` Adds a SourceUnit to the unit.
    `` | `public void` | `addSources(String[] paths)` Adds a set of file paths to the unit.
    `` | `public void` | `addSources(File[] files)` Adds a set of source files to the unit.
    `` | `public void` | `applyToPrimaryClassNodes(CompilationUnit.PrimaryClassNodeOperation op)` Applies a deprecated primary-class operation to all primary class nodes.
    `` | `public void` | `applyToSourceUnits(CompilationUnit.SourceUnitOperation op)` Applies a deprecated source-unit operation to all source units.
    `` | `public 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 (GROOVY-12204).
    `` | `public void` | `compile(int throughPhase)` Compiles the compilation unit from sources.
    `` | `public 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.
    `` | `public CompileUnit` | `getAST()` Returns the CompileUnit that roots our AST.
    `` | `public ASTTransformationsContext` | `getASTTransformationsContext()` Returns: the AST transformations current context
    `` | `public ClassNode` | `getClassNode(String name)` Convenience routine to get the named ClassNode.
    `` | `public ClassNodeResolver` | `getClassNodeResolver()` Returns the resolver used for on-demand class lookup.
    `` | `public List<GroovyClass>` | `getClasses()` Get the GroovyClasses generated by compile().
    `` | `public CompilationUnit.ClassgenCallback` | `getClassgenCallback()` Returns the callback invoked after class generation.
    `` | `public ClassNode` | `getFirstClassNode()` Convenience routine to get the first ClassNode, for when you are sure there is only one.
    `` | `public Set<JavaFileObject>` | `getJavaCompilationUnitSet()` Returns the queued Java compilation units used for joint compilation.
    `` | `public CompilationUnit.ProgressCallback` | `getProgressCallback()` Returns the callback invoked after each phase transition.
    `` | `public GroovyClassLoader` | `getTransformLoader()` Returns the class loader for loading AST transformations.
    `` | `public Iterator<SourceUnit>` | `iterator()` Returns an iterator on the unit's SourceUnits.
    `` | `protected void` | `mark()` Updates the phase marker on all sources.
    `` | `public void` | `setClassNodeResolver(ClassNodeResolver classNodeResolver)` Replaces the resolver used for on-demand class lookup.
    `` | `public void` | `setClassgenCallback(CompilationUnit.ClassgenCallback visitor)` Sets a ClassgenCallback.
    `` | `public void` | `setProgressCallback(CompilationUnit.ProgressCallback callback)` Sets a ProgressCallback.

  - ### Inherited Methods Summary

    Inherited Methods
    Methods inherited from class | Name
    --- | ---
    `class ProcessingUnit` | `completePhase, configure, getClassLoader, getConfiguration, getErrorCollector, getPhase, getPhaseDescription, gotoPhase, isPhaseComplete, nextPhase, setClassLoader, setConfiguration`

- - ### Field Detail

    - #### protected CompileUnit ast

    - #### protected ASTTransformationsContext astTransformationsContext

      The AST transformations state data.

    - #### protected ClassNodeResolver classNodeResolver

    - #### protected CompilationUnit.ClassgenCallback classgenCallback

      A callback called during the `classgen` phase of compilation

    - #### 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.

  - ### Constructor Detail

    - #### public CompilationUnit()

      Initializes the CompilationUnit with defaults.

    - #### public CompilationUnit(GroovyClassLoader loader)

      Initializes the CompilationUnit with defaults except for class loader.

    - #### public CompilationUnit(CompilerConfiguration configuration)

      Initializes the CompilationUnit with no security considerations.

    - #### 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.

    - #### 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 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 Detail

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

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

    - #### @Deprecated
      public void addFirstPhaseOperation(CompilationUnit.PrimaryClassNodeOperation op, int phase)

      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

    - #### public void addJavaCompilationUnits(Set<JavaFileObject> javaCompilationUnitSet)

      Adds Java compilation units to the joint-compilation set.

      Parameters:
        `javaCompilationUnitSet` - the Java units to add

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

    - #### @Deprecated
      public void addNewPhaseOperation(CompilationUnit.SourceUnitOperation op, int phase)

      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

    - #### public void addPhaseOperation(CompilationUnit.IGroovyClassOperation op)

      Adds a Groovy class operation to the output phase.

      Parameters:
        `op` - the operation to run for generated classes

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

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

    - #### @Deprecated
      public void addPhaseOperation(CompilationUnit.GroovyClassOperation op)

      Adapts a deprecated groovy-class operation to the current API.

      Parameters:
        `op` - the operation to add

    - #### @Deprecated
      public void addPhaseOperation(CompilationUnit.SourceUnitOperation op, int phase)

      Adapts a deprecated source-unit operation to the current API.

      Parameters:
        `op` - the operation to add
        `phase` - the phase in which to run it

    - #### @Deprecated
      public void addPhaseOperation(CompilationUnit.PrimaryClassNodeOperation op, int phase)

      Adapts a deprecated primary-class operation to the current API.

      Parameters:
        `op` - the operation to add
        `phase` - the phase in which to run it

    - #### public SourceUnit addSource(File file)

      Adds a source file to the unit.

    - #### public SourceUnit addSource(URL url)

      Adds a source file to the unit.

    - #### public SourceUnit addSource(String name, InputStream stream)

      Adds a InputStream source to the unit.

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

    - #### public SourceUnit addSource(SourceUnit source)

      Adds a SourceUnit to the unit.

    - #### public void addSources(String[] paths)

      Adds a set of file paths to the unit.

    - #### public void addSources(File[] files)

      Adds a set of source files to the unit.

    - #### @Deprecated
      public void applyToPrimaryClassNodes(CompilationUnit.PrimaryClassNodeOperation op)

      Applies a deprecated primary-class operation to all primary class nodes.

      throws:
        CompilationFailedException if processing fails
      Parameters:
        `op` - the operation to run

    - #### @Deprecated
      public void applyToSourceUnits(CompilationUnit.SourceUnitOperation op)

      Applies a deprecated source-unit operation to all source units.

      throws:
        CompilationFailedException if processing fails
      Parameters:
        `op` - the operation to run

    - #### public 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 (GROOVY-12204).

    - #### public void compile(int throughPhase)

      Compiles the compilation unit from sources.

    - #### 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.

    - #### protected org.objectweb.asm.ClassVisitor createClassVisitor()

      Creates the ASM class visitor used for bytecode generation.

      Returns:
        the class visitor used to emit bytecode

    - #### protected boolean dequeued()

      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.

      throws:
        CompilationFailedException
      Returns:
        true if there was a queued source

    - #### public CompileUnit getAST()

      Returns the CompileUnit that roots our AST.

    - #### public ASTTransformationsContext getASTTransformationsContext()

      Returns:
        the AST transformations current context

    - #### public ClassNode getClassNode(String name)

      Convenience routine to get the named ClassNode.

    - #### public ClassNodeResolver getClassNodeResolver()

      Returns the resolver used for on-demand class lookup.

      Returns:
        the active class-node resolver

    - #### public List<GroovyClass> getClasses()

      Get the GroovyClasses generated by compile().

    - #### public CompilationUnit.ClassgenCallback getClassgenCallback()

      Returns the callback invoked after class generation.

      Returns:
        the class-generation callback, or `null`

    - #### public ClassNode getFirstClassNode()

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

    - #### public Set<JavaFileObject> getJavaCompilationUnitSet()

      Returns the queued Java compilation units used for joint compilation.

      Returns:
        the tracked Java compilation units

    - #### public CompilationUnit.ProgressCallback getProgressCallback()

      Returns the callback invoked after each phase transition.

      Returns:
        the progress callback, or `null`

    - #### public GroovyClassLoader getTransformLoader()

      Returns the class loader for loading AST transformations.

    - #### public Iterator<SourceUnit> iterator()

      Returns an iterator on the unit's SourceUnits.

    - #### protected void mark()

      Updates the phase marker on all sources.

    - #### public void setClassNodeResolver(ClassNodeResolver classNodeResolver)

      Replaces the resolver used for on-demand class lookup.

      Parameters:
        `classNodeResolver` - the resolver to install

    - #### public void setClassgenCallback(CompilationUnit.ClassgenCallback visitor)

      Sets a ClassgenCallback. You can have only one, and setting it to `null` removes any existing setting.

    - #### public void setProgressCallback(CompilationUnit.ProgressCallback callback)

      Sets a ProgressCallback. You can have only one, and setting it to `null` removes any existing setting.