Package org.jacoco.core.runtime
Class AgentOptions
java.lang.Object
org.jacoco.core.runtime.AgentOptions
Utility to create and parse options for the runtime agent. Options are
represented as a string in the following format:
key1=value1,key2=value2,key3=value3
-
Nested Class Summary
Nested Classes -
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final String
The IP address or DNS name the tcpserver binds to or the tcpclient connects to.static final String
Specifies whether execution data should be appended to the output file.static final String
Specifies where the agent dumps all class files it encounters.static final String
Default value for the "address" agent option.static final String
Default value for the "destfile" agent option.static final int
Default value for the "port" agent option.static final String
Specifies the output file for execution data.static final String
Specifies whether the agent will automatically dump coverage data on VM exit.static final String
Wildcard expression for class loaders names for classes that should be excluded from code coverage.static final String
Wildcard expression for class names that should be excluded from code coverage.static final String
Specifies whether also classes from the bootstrap classloader should be instrumented.static final String
Specifies whether also classes without a source location should be instrumented.static final String
Wildcard expression for class names that should be included for code coverage.static final String
Specifies whether the agent should expose functionality via JMX under the name "org.jacoco:type=Runtime".private static final Pattern
static final String
Specifies the output mode.static final String
The port the tcpserver binds to or the tcpclient connects to.static final String
Specifies a session identifier that is written with the execution data.private static final Collection<String>
-
Constructor Summary
ConstructorsConstructorDescriptionNew instance with all values set to default.AgentOptions
(String optionstr) New instance parsed from the given option string.AgentOptions
(Properties properties) New instance read from the givenProperties
object. -
Method Summary
Modifier and TypeMethodDescriptionGets the hostname or IP address to listen to when output istcpserver
or connect to when output istcpclient
boolean
Returns whether the output should be appended to an existing file.Returns the location of the directory where class files should be dumped to.Returns the output file location.boolean
Returns whether coverage data should be dumped on exit.Returns the wildcard expression for excluded class loaders.Returns the wildcard expression for classes to exclude.boolean
Returns whether classes from the bootstrap classloader should be instrumented.boolean
Returns whether classes without source location should be instrumented.Returns the wildcard expression for classes to include.boolean
getJmx()
Returns whether the agent exposes functionality via JMX.private boolean
private int
private String
Returns the output modeint
getPort()
Returns the port on which to listen to when the output istcpserver
or the port to connect to when output istcpclient
.getQuotedVMArgument
(File agentJarFile) Generate required quoted JVM argument based on current configuration and supplied agent jar location.Returns the session identifier.getVMArgument
(File agentJarFile) Generate required JVM argument based on current configuration and supplied agent jar location.prependVMArguments
(String arguments, File agentJarFile) Generate required quotes JVM argument based on current configuration and prepends it to the given argument command line.void
setAddress
(String address) Sets the hostname or IP address to listen to when output istcpserver
or connect to when output istcpclient
void
setAppend
(boolean append) Sets whether the output should be appended to an existing file.void
setClassDumpDir
(String location) Sets the directory where class files should be dumped to.void
setDestfile
(String destfile) Sets the output file location.void
setDumpOnExit
(boolean dumpOnExit) Sets whether coverage data should be dumped on exit.void
setExclClassloader
(String expression) Sets the wildcard expression for excluded class loaders.void
setExcludes
(String excludes) Sets the wildcard expression for classes to exclude.void
setInclBootstrapClasses
(boolean include) Sets whether classes from the bootstrap classloader should be instrumented.void
setInclNoLocationClasses
(boolean include) Sets whether classes without source location should be instrumented.void
setIncludes
(String includes) Sets the wildcard expression for classes to include.void
setJmx
(boolean jmx) Sets whether the agent should expose functionality via JMX.private void
private void
private void
void
Sets the output modevoid
setOutput
(AgentOptions.OutputMode output) Sets the output modevoid
setPort
(int port) Sets the port on which to listen to when output istcpserver
or the port to connect to when output istcpclient
void
setSessionId
(String id) Sets the session identifier.toString()
Creates a string representation that can be passed to the agent via the command line.private void
private void
validatePort
(int port)
-
Field Details
-
DESTFILE
Specifies the output file for execution data. Default isjacoco.exec
in the working directory.- See Also:
-
DEFAULT_DESTFILE
Default value for the "destfile" agent option.- See Also:
-
APPEND
Specifies whether execution data should be appended to the output file. Default istrue
.- See Also:
-
INCLUDES
Wildcard expression for class names that should be included for code coverage. Default is*
(all classes included).- See Also:
-
EXCLUDES
Wildcard expression for class names that should be excluded from code coverage. Default is the empty string (no exclusions).- See Also:
-
EXCLCLASSLOADER
Wildcard expression for class loaders names for classes that should be excluded from code coverage. This means all classes loaded by a class loader which full qualified name matches this expression will be ignored for code coverage regardless of all other filtering settings. Default issun.reflect.DelegatingClassLoader
.- See Also:
-
INCLBOOTSTRAPCLASSES
Specifies whether also classes from the bootstrap classloader should be instrumented. Use this feature with caution, it needs heavy includes/excludes tuning. Default isfalse
.- See Also:
-
INCLNOLOCATIONCLASSES
Specifies whether also classes without a source location should be instrumented. Normally such classes are generated at runtime e.g. by mocking frameworks and are therefore excluded by default. Default isfalse
.- See Also:
-
SESSIONID
Specifies a session identifier that is written with the execution data. Without this parameter a random identifier is created by the agent.- See Also:
-
DUMPONEXIT
Specifies whether the agent will automatically dump coverage data on VM exit. Default istrue
.- See Also:
-
OUTPUT
Specifies the output mode. Default isAgentOptions.OutputMode.file
. -
OPTION_SPLIT
-
ADDRESS
The IP address or DNS name the tcpserver binds to or the tcpclient connects to. Default is defined byDEFAULT_ADDRESS
.- See Also:
-
DEFAULT_ADDRESS
Default value for the "address" agent option. -
PORT
The port the tcpserver binds to or the tcpclient connects to. In tcpserver mode the port must be available, which means that if multiple JaCoCo agents should run on the same machine, different ports have to be specified. Default is defined byDEFAULT_PORT
.- See Also:
-
DEFAULT_PORT
public static final int DEFAULT_PORTDefault value for the "port" agent option.- See Also:
-
CLASSDUMPDIR
Specifies where the agent dumps all class files it encounters. The location is specified as a relative path to the working directory. Default isnull
(no dumps).- See Also:
-
JMX
Specifies whether the agent should expose functionality via JMX under the name "org.jacoco:type=Runtime". Default isfalse
.- See Also:
-
VALID_OPTIONS
-
options
-
-
Constructor Details
-
AgentOptions
public AgentOptions()New instance with all values set to default. -
AgentOptions
New instance parsed from the given option string.- Parameters:
optionstr
- string to parse ornull
-
AgentOptions
New instance read from the givenProperties
object.- Parameters:
properties
-Properties
object to read configuration options from
-
-
Method Details
-
validateAll
private void validateAll() -
validatePort
private void validatePort(int port) -
getDestfile
Returns the output file location.- Returns:
- output file location
-
setDestfile
Sets the output file location.- Parameters:
destfile
- output file location
-
getAppend
public boolean getAppend()Returns whether the output should be appended to an existing file.- Returns:
true
, when the output should be appended
-
setAppend
public void setAppend(boolean append) Sets whether the output should be appended to an existing file.- Parameters:
append
-true
, when the output should be appended
-
getIncludes
Returns the wildcard expression for classes to include.- Returns:
- wildcard expression for classes to include
- See Also:
-
setIncludes
Sets the wildcard expression for classes to include.- Parameters:
includes
- wildcard expression for classes to include- See Also:
-
getExcludes
Returns the wildcard expression for classes to exclude.- Returns:
- wildcard expression for classes to exclude
- See Also:
-
setExcludes
Sets the wildcard expression for classes to exclude.- Parameters:
excludes
- wildcard expression for classes to exclude- See Also:
-
getExclClassloader
Returns the wildcard expression for excluded class loaders.- Returns:
- expression for excluded class loaders
- See Also:
-
setExclClassloader
Sets the wildcard expression for excluded class loaders.- Parameters:
expression
- expression for excluded class loaders- See Also:
-
getInclBootstrapClasses
public boolean getInclBootstrapClasses()Returns whether classes from the bootstrap classloader should be instrumented.- Returns:
true
if classes from the bootstrap classloader should be instrumented
-
setInclBootstrapClasses
public void setInclBootstrapClasses(boolean include) Sets whether classes from the bootstrap classloader should be instrumented.- Parameters:
include
-true
if bootstrap classes should be instrumented
-
getInclNoLocationClasses
public boolean getInclNoLocationClasses()Returns whether classes without source location should be instrumented.- Returns:
true
if classes without source location should be instrumented
-
setInclNoLocationClasses
public void setInclNoLocationClasses(boolean include) Sets whether classes without source location should be instrumented.- Parameters:
include
-true
if classes without source location should be instrumented
-
getSessionId
Returns the session identifier.- Returns:
- session identifier
-
setSessionId
Sets the session identifier.- Parameters:
id
- session identifier
-
getDumpOnExit
public boolean getDumpOnExit()Returns whether coverage data should be dumped on exit.- Returns:
true
if coverage data will be written on VM exit
-
setDumpOnExit
public void setDumpOnExit(boolean dumpOnExit) Sets whether coverage data should be dumped on exit.- Parameters:
dumpOnExit
-true
if coverage data should be written on VM exit
-
getPort
public int getPort()Returns the port on which to listen to when the output istcpserver
or the port to connect to when output istcpclient
.- Returns:
- port to listen on or connect to
-
setPort
public void setPort(int port) Sets the port on which to listen to when output istcpserver
or the port to connect to when output istcpclient
- Parameters:
port
- port to listen on or connect to
-
getAddress
Gets the hostname or IP address to listen to when output istcpserver
or connect to when output istcpclient
- Returns:
- Hostname or IP address
-
setAddress
Sets the hostname or IP address to listen to when output istcpserver
or connect to when output istcpclient
- Parameters:
address
- Hostname or IP address
-
getOutput
Returns the output mode- Returns:
- current output mode
-
setOutput
Sets the output mode- Parameters:
output
- Output mode
-
setOutput
Sets the output mode- Parameters:
output
- Output mode
-
getClassDumpDir
Returns the location of the directory where class files should be dumped to.- Returns:
- dump location or
null
(no dumps)
-
setClassDumpDir
Sets the directory where class files should be dumped to.- Parameters:
location
- dump location ornull
(no dumps)
-
getJmx
public boolean getJmx()Returns whether the agent exposes functionality via JMX.- Returns:
true
, when JMX is enabled
-
setJmx
public void setJmx(boolean jmx) Sets whether the agent should expose functionality via JMX.- Parameters:
jmx
-true
if JMX should be enabled
-
setOption
-
setOption
-
setOption
-
getOption
-
getOption
-
getOption
-
getVMArgument
Generate required JVM argument based on current configuration and supplied agent jar location.- Parameters:
agentJarFile
- location of the JaCoCo Agent Jar- Returns:
- Argument to pass to create new VM with coverage enabled
-
getQuotedVMArgument
Generate required quoted JVM argument based on current configuration and supplied agent jar location.- Parameters:
agentJarFile
- location of the JaCoCo Agent Jar- Returns:
- Quoted argument to pass to create new VM with coverage enabled
-
prependVMArguments
Generate required quotes JVM argument based on current configuration and prepends it to the given argument command line. If a agent with the same JAR file is already specified this parameter is removed from the existing command line.- Parameters:
arguments
- existing command line arguments ornull
agentJarFile
- location of the JaCoCo Agent Jar- Returns:
- VM command line arguments prepended with configured JaCoCo agent
-
toString
Creates a string representation that can be passed to the agent via the command line. Might be the empty string, if no options are set.
-