org.codehaus.groovy.control

Class CompilerConfiguration

java.lang.Object

org.codehaus.groovy.control.CompilerConfiguration

public class CompilerConfiguration
extends Object

Compilation control flags and coordination stuff.

Author:

Chris Poirier, Jochen Theodorou, Jim White, Cedric Champeau

Field Summary

Fields

Modifier and Type	Field and Description
static String	currentJVMVersion
static CompilerConfiguration	DEFAULT A convenience for getting a default configuration.
static String	JDK4 This ("1.4") is the value for targetBytecode to compile for a JDK 1.4.
static String	JDK5 This ("1.5") is the value for targetBytecode to compile for a JDK 1.5.
static String	JDK6 This ("1.6") is the value for targetBytecode to compile for a JDK 1.6.
static String	JDK7 This ("1.7") is the value for targetBytecode to compile for a JDK 1.7.
static String	JDK8 This ("1.8") is the value for targetBytecode to compile for a JDK 1.8.
static String	POST_JDK5 This ("1.5") is the value for targetBytecode to compile for a JDK 1.5 or later JVM.
static String	PRE_JDK5 This ("1.4") is the value for targetBytecode to compile for a JDK 1.4 JVM.

Constructor Summary

Constructors

Constructor and Description
CompilerConfiguration() Sets the Flags to defaults.
CompilerConfiguration(CompilerConfiguration configuration) Copy constructor.
CompilerConfiguration(Properties configuration) Sets the Flags to the specified configuration, with defaults for those not supplied.

Method Summary

Methods

Modifier and Type	Method and Description
CompilerConfiguration	addCompilationCustomizers(CompilationCustomizer... customizers) Adds compilation customizers to the compilation process.
void	configure(Properties configuration) Method to configure a this CompilerConfiguration by using Properties.
List<String>	getClasspath()
List<CompilationCustomizer>	getCompilationCustomizers() Returns the list of compilation customizers.
boolean	getDebug() Returns true if debugging operation has been requested.
String	getDefaultScriptExtension()
Set<String>	getDisabledGlobalASTTransformations() Returns the list of disabled global AST transformation class names.
Map<String,Object>	getJointCompilationOptions() Gets the joint compilation options for this configuration.
int	getMinimumRecompilationInterval()
Map<String,Boolean>	getOptimizationOptions() Gets the optimization options for this configuration.
PrintWriter	getOutput() Gets the currently configured output writer.
ParserPluginFactory	getPluginFactory()
boolean	getRecompileGroovySource()
String	getScriptBaseClass() Gets the name of the base class for scripts.
Set<String>	getScriptExtensions()
String	getSourceEncoding() Gets the currently configured source file encoding.
String	getTargetBytecode() Retrieves the compiler bytecode compatibility mode.
File	getTargetDirectory() Gets the target directory for writing classes.
int	getTolerance() Returns the requested error tolerance.
boolean	getVerbose() Returns true if verbose operation has been requested.
int	getWarningLevel() Gets the currently configured warning level.
static boolean	isPostJDK5(String bytecodeVersion) Checks if the specified bytecode version string represents a JDK 1.5+ compatible bytecode version.
static boolean	isPostJDK7(String bytecodeVersion) Checks if the specified bytecode version string represents a JDK 1.7+ compatible bytecode version.
void	setClasspath(String classpath) Sets the classpath.
void	setClasspathList(List<String> parts) sets the classpath using a list of Strings
void	setDebug(boolean debug) Turns debugging operation on or off.
void	setDefaultScriptExtension(String defaultScriptExtension)
void	setDisabledGlobalASTTransformations(Set<String> disabledGlobalASTTransformations) Disables global AST transformations.
void	setJointCompilationOptions(Map<String,Object> options) Sets the joint compilation options for this configuration.
void	setMinimumRecompilationInterval(int time)
void	setOptimizationOptions(Map<String,Boolean> options) Sets the optimization options for this configuration.
void	setOutput(PrintWriter output) Sets the output writer.
void	setPluginFactory(ParserPluginFactory pluginFactory)
void	setRecompileGroovySource(boolean recompile)
void	setScriptBaseClass(String scriptBaseClass) Sets the name of the base class for scripts.
void	setScriptExtensions(Set<String> scriptExtensions)
void	setSourceEncoding(String encoding) Sets the encoding to be used when reading source files.
void	setTargetBytecode(String version) Allow setting the bytecode compatibility.
void	setTargetDirectory(File directory) Sets the target directory.
void	setTargetDirectory(String directory) Sets the target directory.
void	setTolerance(int tolerance) Sets the error tolerance, which is the number of non-fatal errors (per unit) that should be tolerated before compilation is aborted.
void	setVerbose(boolean verbose) Turns verbose operation on or off.
void	setWarningLevel(int level) Sets the warning level.

Methods inherited from class java.lang.Object

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

Field Detail

JDK4

public static final String JDK4

This ("1.4") is the value for targetBytecode to compile for a JDK 1.4.

See Also:

Constant Field Values

JDK5

public static final String JDK5

This ("1.5") is the value for targetBytecode to compile for a JDK 1.5.

See Also:

Constant Field Values

JDK6

public static final String JDK6

This ("1.6") is the value for targetBytecode to compile for a JDK 1.6.

See Also:

Constant Field Values

JDK7

public static final String JDK7

This ("1.7") is the value for targetBytecode to compile for a JDK 1.7.

See Also:

Constant Field Values

JDK8

public static final String JDK8

This ("1.8") is the value for targetBytecode to compile for a JDK 1.8.

See Also:

Constant Field Values

POST_JDK5

public static final String POST_JDK5

This ("1.5") is the value for targetBytecode to compile for a JDK 1.5 or later JVM.

See Also:

Constant Field Values

PRE_JDK5

public static final String PRE_JDK5

This ("1.4") is the value for targetBytecode to compile for a JDK 1.4 JVM.

See Also:

Constant Field Values

currentJVMVersion

public static final String currentJVMVersion

DEFAULT

public static final CompilerConfiguration DEFAULT

A convenience for getting a default configuration. Do not modify it! See CompilerConfiguration(Properties) for an example on how to make a suitable copy to modify. But if you're really starting from a default context, then you probably just want new CompilerConfiguration().

Constructor Detail

CompilerConfiguration

public CompilerConfiguration()

Sets the Flags to defaults.

CompilerConfiguration

public CompilerConfiguration(CompilerConfiguration configuration)

Copy constructor. Use this if you have a mostly correct configuration for your compilation but you want to make a some changes programatically. An important reason to prefer this approach is that your code will most likely be forward compatible with future changes to this configuration API.

An example of this copy constructor at work:

    // In all likelihood there is already a configuration in your code's context
    // for you to copy, but for the sake of this example we'll use the global default.
    CompilerConfiguration myConfiguration = new CompilerConfiguration(CompilerConfiguration.DEFAULT);
    myConfiguration.setDebug(true);

Parameters:

configuration - The configuration to copy.

CompilerConfiguration

public CompilerConfiguration(Properties configuration)
                      throws ConfigurationException

Sets the Flags to the specified configuration, with defaults for those not supplied. Note that those "defaults" here do not include checking the settings in System.getProperties() in general, only file.encoding, groovy.target.directory and groovy.source.encoding are.

If you want to set a few flags but keep Groovy's default configuration behavior then be sure to make your settings in a Properties that is backed by System.getProperties() (which is done using this constructor). That might be done like this:

 Properties myProperties = new Properties(System.getProperties());
 myProperties.setProperty("groovy.output.debug", "true");
 myConfiguration = new CompilerConfiguration(myProperties);
 

And you also have to contend with a possible SecurityException when getting the system properties (See System.getProperties()). A safer approach would be to copy a default CompilerConfiguration and make your changes there using the setter:

 // In all likelihood there is already a configuration for you to copy,
 // but for the sake of this example we'll use the global default.
 CompilerConfiguration myConfiguration = new CompilerConfiguration(CompilerConfiguration.DEFAULT);
 myConfiguration.setDebug(true);
 

Another reason to use the copy constructor rather than this one is that you must call setOutput(java.io.PrintWriter). Calling setOutput(null) is valid and will set up a PrintWriter to a bit bucket. The copy constructor will of course set the same one as the original.

Property Key	Get/Set Property Name
"groovy.warnings"	getWarningLevel()
"groovy.source.encoding"	getSourceEncoding()
"groovy.target.directory"	getTargetDirectory()
"groovy.target.bytecode"	getTargetBytecode()
"groovy.classpath"	getClasspath()
"groovy.output.verbose"	getVerbose()
"groovy.output.debug"	getDebug()
"groovy.errors.tolerance"	getTolerance()
"groovy.script.extension"	getDefaultScriptExtension()
"groovy.script.base"	getScriptBaseClass()
"groovy.recompile"	getRecompileGroovySource()
"groovy.recompile.minimumInterval"	getMinimumRecompilationInterval()

Parameters:

configuration - The properties to get flag values from.

Throws:

ConfigurationException

Method Detail

isPostJDK5

public static boolean isPostJDK5(String bytecodeVersion)

Checks if the specified bytecode version string represents a JDK 1.5+ compatible bytecode version.

Parameters:

bytecodeVersion - the bytecode version string (1.4, 1.5, 1.6, 1.7 or 1.8)

Returns:

true if the bytecode version is JDK 1.5+

isPostJDK7

public static boolean isPostJDK7(String bytecodeVersion)

Checks if the specified bytecode version string represents a JDK 1.7+ compatible bytecode version.

Parameters:

bytecodeVersion - the bytecode version string (1.4, 1.5, 1.6, 1.7 or 1.8)

Returns:

true if the bytecode version is JDK 1.7+

configure

public void configure(Properties configuration)
               throws ConfigurationException

Method to configure a this CompilerConfiguration by using Properties. For a list of available properties look at {link CompilerConfiguration(Properties).

Parameters:

configuration - The properties to get flag values from.

Throws:

ConfigurationException

getWarningLevel

public int getWarningLevel()

Gets the currently configured warning level. See WarningMessage for level details.

setWarningLevel

public void setWarningLevel(int level)

Sets the warning level. See WarningMessage for level details.

getSourceEncoding

public String getSourceEncoding()

Gets the currently configured source file encoding.

setSourceEncoding

public void setSourceEncoding(String encoding)

Sets the encoding to be used when reading source files.

getOutput

public PrintWriter getOutput()

Gets the currently configured output writer.

setOutput

public void setOutput(PrintWriter output)

Sets the output writer.

getTargetDirectory

public File getTargetDirectory()

Gets the target directory for writing classes.

setTargetDirectory

public void setTargetDirectory(String directory)

Sets the target directory.

setTargetDirectory

public void setTargetDirectory(File directory)

Sets the target directory.

getClasspath

public List<String> getClasspath()

Returns:

the classpath

setClasspath

public void setClasspath(String classpath)

Sets the classpath.

setClasspathList

public void setClasspathList(List<String> parts)

sets the classpath using a list of Strings

Parameters:

parts - list of strings containing the classpath parts

getVerbose

public boolean getVerbose()

Returns true if verbose operation has been requested.

setVerbose

public void setVerbose(boolean verbose)

Turns verbose operation on or off.

getDebug

public boolean getDebug()

Returns true if debugging operation has been requested.

setDebug

public void setDebug(boolean debug)

Turns debugging operation on or off.

getTolerance

public int getTolerance()

Returns the requested error tolerance.

setTolerance

public void setTolerance(int tolerance)

Sets the error tolerance, which is the number of non-fatal errors (per unit) that should be tolerated before compilation is aborted.

getScriptBaseClass

public String getScriptBaseClass()

Gets the name of the base class for scripts. It must be a subclass of Script.

setScriptBaseClass

public void setScriptBaseClass(String scriptBaseClass)

Sets the name of the base class for scripts. It must be a subclass of Script.

getPluginFactory

public ParserPluginFactory getPluginFactory()

setPluginFactory

public void setPluginFactory(ParserPluginFactory pluginFactory)

setScriptExtensions

public void setScriptExtensions(Set<String> scriptExtensions)

getScriptExtensions

public Set<String> getScriptExtensions()

getDefaultScriptExtension

public String getDefaultScriptExtension()

setDefaultScriptExtension

public void setDefaultScriptExtension(String defaultScriptExtension)

setRecompileGroovySource

public void setRecompileGroovySource(boolean recompile)

getRecompileGroovySource

public boolean getRecompileGroovySource()

setMinimumRecompilationInterval

public void setMinimumRecompilationInterval(int time)

getMinimumRecompilationInterval

public int getMinimumRecompilationInterval()

setTargetBytecode

public void setTargetBytecode(String version)

Allow setting the bytecode compatibility. The parameter can take one of the values 1.7, 1.6, 1.5 or 1.4. If wrong parameter then the value will default to VM determined version.

Parameters:

version - the bytecode compatibility mode

getTargetBytecode

public String getTargetBytecode()

Retrieves the compiler bytecode compatibility mode.

Returns:

bytecode compatibility mode. Can be either 1.5 or 1.4.

getJointCompilationOptions

public Map<String,Object> getJointCompilationOptions()

Gets the joint compilation options for this configuration.

Returns:

the options

setJointCompilationOptions

public void setJointCompilationOptions(Map<String,Object> options)

Sets the joint compilation options for this configuration. Using null will disable joint compilation.

Parameters:

options - the options

getOptimizationOptions

public Map<String,Boolean> getOptimizationOptions()

Gets the optimization options for this configuration.

Returns:

the options (always not null)

setOptimizationOptions

public void setOptimizationOptions(Map<String,Boolean> options)

Sets the optimization options for this configuration. No entry or a true for that entry means to enable that optimization, a false means the optimization is disabled. Valid keys are "all" and "int".

Parameters:

options - the options.

Throws:

IllegalArgumentException - if the options are null

addCompilationCustomizers

public CompilerConfiguration addCompilationCustomizers(CompilationCustomizer... customizers)

Adds compilation customizers to the compilation process. A compilation customizer is a class node operation which performs various operations going from adding imports to access control.

Parameters:

customizers - the list of customizers to be added

Returns:

this configuration instance

getCompilationCustomizers

public List<CompilationCustomizer> getCompilationCustomizers()

Returns the list of compilation customizers.

Returns:

the customizers (always not null)

getDisabledGlobalASTTransformations

public Set<String> getDisabledGlobalASTTransformations()

Returns the list of disabled global AST transformation class names.

Returns:

a list of global AST transformation fully qualified class names

setDisabledGlobalASTTransformations

public void setDisabledGlobalASTTransformations(Set<String> disabledGlobalASTTransformations)

Disables global AST transformations. In order to avoid classloading side effects, it is not recommended to use MyASTTransformation.class.getName() by directly use the class name as a string. Disabled AST transformations only apply to automatically loaded global AST transformations, that is to say transformations defined in a META-INF/org.codehaus.groovy.transform.ASTTransformation file. If you explicitly add a global AST transformation in your compilation process, for example using the ASTTransformationCustomizer or using a CompilationUnit.PrimaryClassNodeOperation, then nothing will prevent the transformation from being loaded.

Parameters:

disabledGlobalASTTransformations - a set of fully qualified class names of global AST transformations which should not be loaded.