Package org.codehaus.commons.compiler

# Interface ICompiler

All Known Implementing Classes:
  `AbstractCompiler`, `Compiler`, `Compiler`

public interface ICompiler
A simplified substitute for the `javac` tool.

## Field Summary

Fields
Modifier and Type
Field
Description
`static final ResourceCreator`
`CREATE_NEXT_TO_SOURCE_FILE`
Special value for `setClassFileCreator(ResourceCreator)`: Indicates that .class resources are to be created in the directory of the .java resource from which they are generated.
`static final ResourceFinder`
`FIND_NEXT_TO_SOURCE_FILE`
Special value for `setClassFileFinder(ResourceFinder)`.
`static final File`
`NO_DESTINATION_DIRECTORY`
Special value for `setDestinationDirectory(File, boolean)`'s first parameter: Indicates that .class files are to be created in the directory of the .java file from which they are generated.

## Method Summary

Modifier and Type
Method
Description
`boolean`
`compile(File[] sourceFiles)`
Reads a set of Java compilation units (a.k.a.
`void`
`compile(Resource[] sourceResources)`
See `compile(File[])`.
`void`
`setBootClassPath(File[] directoriesAndArchives)`
Equivalent of `--boot-class-path`.
`void`
`setCharacterEncoding(String characterEncoding)`
Deprecated.
Use `setSourceCharset(Charset)` instead
`void`
`setClassFileCreator(ResourceCreator classFileCreator)`
This `ResourceCreator` is used to store generated `.class` files.
`void`
`setClassFileFinder(ResourceFinder classFileFinder)`
This `ResourceFinder` is used to check whether a `.class` resource already exists and is younger than the `.java` resource from which it was generated.
`void`
`setClassFileFinder(ResourceFinder classFileFinder, boolean rebuild)`
Equivalent with `setClassFileFinder(rebuild ? ResourceFinder.EMPTY_RESOURCE_FINDER : classFileFinder)`.
`void`
`setClassPath(File[] directoriesAndArchives)`
Equivalent of --class-path.
`void`
`setCompileErrorHandler(ErrorHandler errorHandler)`
Installs an `ErrorHandler` which is invoked during compilation on each error.
`void`
`setDebugLines(boolean value)`
Equivalent of `-g:lines`.
`void`
`setDebugSource(boolean value)`
Equivalent of `-g:source`.
`void`
`setDebugVars(boolean value)`
Equivalent of `-g:vars`.
`void`
`setDestinationDirectory(File destinationDirectory, boolean rebuild)`
Equivalent of -d and `-rebuild`.
`void`
`setEncoding(Charset encoding)`
The equivalent of JAVA's "`-encoding`" command line option.
`void`
`setExtensionDirectories(File[] directories)`
Equivalent of `-extdirs`.
`void`
`setSourceCharset(Charset charset)`
Same as `setEncoding(Charset)`, but with a more precise name.
`void`
`setSourceFinder(ResourceFinder sourceFinder)`
Finds more `.java` resources that need to be compiled, i.e.
`void`
`setSourcePath(File[] directoriesAndArchives)`
Equivalent of `--source-path`.
`void`
`setSourceVersion(int version)`
Specifies the version of source code accepted, in analogy with JAVAC's `-source` command line option.
`void`
`setTargetVersion(int version)`
Generates class files that target a specified release of the virtual machine, in analogy with JAVAC's `-target` command line option.
`void`
`setVerbose(boolean verbose)`
Equivalent of `-verbose`.
`void`
`setWarningHandler(WarningHandler warningHandler)`
By default, warnings are discarded, but an application my install a custom `WarningHandler`.

## Field Details

### NO_DESTINATION_DIRECTORY

@Nullable static final File NO_DESTINATION_DIRECTORY
Special value for `setDestinationDirectory(File, boolean)`'s first parameter: Indicates that .class files are to be created in the directory of the .java file from which they are generated.

### FIND_NEXT_TO_SOURCE_FILE

static final ResourceFinder FIND_NEXT_TO_SOURCE_FILE
Special value for `setClassFileFinder(ResourceFinder)`.

See Also:
  - `setClassFileFinder(ResourceFinder)`

### CREATE_NEXT_TO_SOURCE_FILE

static final ResourceCreator CREATE_NEXT_TO_SOURCE_FILE
Special value for `setClassFileCreator(ResourceCreator)`: Indicates that .class resources are to be created in the directory of the .java resource from which they are generated.

## Method Details

### setEncoding

void setEncoding(Charset encoding)
The equivalent of JAVA's "`-encoding`" command line option.

See Also:
  - `setSourceCharset(Charset)`

### setSourceCharset

void setSourceCharset(Charset charset)
Same as `setEncoding(Charset)`, but with a more precise name.

### setCharacterEncoding

@Deprecated void setCharacterEncoding(@Nullable String characterEncoding)
Deprecated.
Use `setSourceCharset(Charset)` instead

### setDebugLines

void setDebugLines(boolean value)
Equivalent of `-g:lines`.

### setDebugVars

void setDebugVars(boolean value)
Equivalent of `-g:vars`.

### setDebugSource

void setDebugSource(boolean value)
Equivalent of `-g:source`.

### setSourceVersion

void setSourceVersion(int version)
Specifies the version of source code accepted, in analogy with JAVAC's `-source` command line option. May be ignored by an implementation (e.g. the `janino` implementation always accepts the language features as described on the home page). Allowed values, and the default value, depend on the implementation. `-1` means to use a default version.

### setTargetVersion

void setTargetVersion(int version)
Generates class files that target a specified release of the virtual machine, in analogy with JAVAC's `-target` command line option. Allowed values depend on the implementation. The default value also depends on the implementation. The only invariant is that the generated class files are suitable for the currently executing JVM. `-1` means to use a default version.

### setSourceFinder

void setSourceFinder(ResourceFinder sourceFinder)
Finds more `.java` resources that need to be compiled, i.e. implements JAVAC's `-sourcepath` option.

### setSourcePath

void setSourcePath(File[] directoriesAndArchives)
Equivalent of `--source-path`.

Equivalent with `setSourceFinder(new PathResourceFinder(directoriesAndArchives))`.

### setBootClassPath

void setBootClassPath(File[] directoriesAndArchives)
Equivalent of `--boot-class-path`.

### setExtensionDirectories

void setExtensionDirectories(File[] directories)
Equivalent of `-extdirs`.

### setClassPath

void setClassPath(File[] directoriesAndArchives)
Equivalent of --class-path.

### setDestinationDirectory

void setDestinationDirectory(@Nullable File destinationDirectory, boolean rebuild)
Equivalent of -d and `-rebuild`.

Overrides any previously configured `class file finder` and `class file creator`.

Parameters:
  `destinationDirectory` - `NO_DESTINATION_DIRECTORY` means "create .class resources in the directory of the .java resource from which they are generated"
See Also:
  - `NO_DESTINATION_DIRECTORY`
  - `setClassFileFinder(ResourceFinder)`
  - `setClassFileCreator(ResourceCreator)`

### setClassFileFinder

void setClassFileFinder(ResourceFinder classFileFinder, boolean rebuild)
Equivalent with `setClassFileFinder(rebuild ? ResourceFinder.EMPTY_RESOURCE_FINDER : classFileFinder)`.

### setClassFileFinder

void setClassFileFinder(ResourceFinder classFileFinder)
This `ResourceFinder` is used to check whether a `.class` resource already exists and is younger than the `.java` resource from which it was generated.

If it is impossible to check whether an already-compiled class file exists, or if you want to enforce recompilation, pass `ResourceFinder.EMPTY_RESOURCE_FINDER` as the classFileFinder.

The default is, as for JAVAC, `FIND_NEXT_TO_SOURCE_FILE`.

Parameters:
  `classFileFinder` - Special value `FIND_NEXT_TO_SOURCE_FILE` means ".class file is next to its source file, not in the destination directory"
See Also:
  - `FIND_NEXT_TO_SOURCE_FILE`

### setClassFileCreator

void setClassFileCreator(ResourceCreator classFileCreator)
This `ResourceCreator` is used to store generated `.class` files.

The default is, as for JAVAC, `CREATE_NEXT_TO_SOURCE_FILE`.

Parameters:
  `classFileCreator` - Special value `CREATE_NEXT_TO_SOURCE_FILE` means "create .class file next to its source file, not in the destination directory"
See Also:
  - `CREATE_NEXT_TO_SOURCE_FILE`

### setVerbose

void setVerbose(boolean verbose)
Equivalent of `-verbose`.

### compile

boolean compile(File[] sourceFiles) throws CompileException, IOException
Reads a set of Java compilation units (a.k.a. "source files") from the file system, compiles them into a set of "class files" and stores these in the file system. Additional source files are parsed and compiled on demand through the "source path" set of directories.

For example, if the source path comprises the directories "A/B" and "../C", then the source file for class "com.acme.Main" is searched in

  A/B/com/acme/Main.java
  ../C/com/acme/Main.java

Notice that it does make a difference whether you pass multiple source files to `compile(File[])` or if you invoke `compile(File[])` multiply: In the former case, the source files may contain arbitrary references among each other (even circular ones). In the latter case, only the source files on the source path may contain circular references, not the sourceFiles.

This method must be called exactly once after object construction.

Compile errors are reported as described at `setCompileErrorHandler(ErrorHandler)`.

Parameters:
  `sourceFiles` - Contain the compilation units to compile
Returns:
  `true` for backwards compatibility (return value can safely be ignored)
Throws:
  `CompileException` - Fatal compilation error, or the `CompileException` thrown be the installed compile error handler
  `IOException` - Occurred when reading from the sourceFiles

### compile

void compile(Resource[] sourceResources) throws CompileException, IOException
See `compile(File[])`.

Parameters:
  `sourceResources` - Contain the compilation units to compile
Throws:
  `CompileException`
  `IOException`

### setCompileErrorHandler

void setCompileErrorHandler(@Nullable ErrorHandler errorHandler)
Installs an `ErrorHandler` which is invoked during compilation on each error. (By default, the compilation throws a `CompileException` on the first error and terminates.)

If the given `ErrorHandler` throws a `CompileException`, then the compilation terminates and the exception is propagated.

If the given `ErrorHandler` does not throw a `CompileException` but completes normally, then the compilation may or may not continue, depending on the error. Iff the compilation of a compilation unit completes normally but errors were reported, then it will throw a `CompileException` indicating the number of errors.

In other words: The `ErrorHandler` may throw a `CompileException` or not, but the compilation will definitely throw a `CompileException` if one or more compile errors have occurred.

Parameters:
  `errorHandler` - `null` to restore the default behavior (throwing a `CompileException`)

### setWarningHandler

void setWarningHandler(WarningHandler warningHandler)
By default, warnings are discarded, but an application my install a custom `WarningHandler`.

Parameters:
  `warningHandler` - `null` to indicate that no warnings be issued