Package org.jacoco.core.runtime
Class AgentOptions
- java.lang.Object
-
- org.jacoco.core.runtime.AgentOptions
-
public final class AgentOptions extends java.lang.Object
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 Modifier and Type Class Description static class
AgentOptions.OutputMode
Possible values forOUTPUT
.
-
Field Summary
Fields Modifier and Type Field Description static java.lang.String
ADDRESS
The IP address or DNS name the tcpserver binds to or the tcpclient connects to.static java.lang.String
APPEND
Specifies whether execution data should be appended to the output file.static java.lang.String
CLASSDUMPDIR
Specifies where the agent dumps all class files it encounters.static java.lang.String
DEFAULT_ADDRESS
Default value for the "address" agent option.static java.lang.String
DEFAULT_DESTFILE
Default value for the "destfile" agent option.static int
DEFAULT_PORT
Default value for the "port" agent option.static java.lang.String
DESTFILE
Specifies the output file for execution data.static java.lang.String
DUMPONEXIT
Specifies whether the agent will automatically dump coverage data on VM exit.static java.lang.String
EXCLCLASSLOADER
Wildcard expression for class loaders names for classes that should be excluded from code coverage.static java.lang.String
EXCLUDES
Wildcard expression for class names that should be excluded from code coverage.static java.lang.String
INCLBOOTSTRAPCLASSES
Specifies whether also classes from the bootstrap classloader should be instrumented.static java.lang.String
INCLNOLOCATIONCLASSES
Specifies whether also classes without a source location should be instrumented.static java.lang.String
INCLUDES
Wildcard expression for class names that should be included for code coverage.static java.lang.String
JMX
Specifies whether the agent should expose functionality via JMX under the name "org.jacoco:type=Runtime".static java.lang.String
OUTPUT
Specifies the output mode.static java.lang.String
PORT
The port the tcpserver binds to or the tcpclient connects to.static java.lang.String
SESSIONID
Specifies a session identifier that is written with the execution data.
-
Constructor Summary
Constructors Constructor Description AgentOptions()
New instance with all values set to default.AgentOptions(java.lang.String optionstr)
New instance parsed from the given option string.AgentOptions(java.util.Properties properties)
New instance read from the givenProperties
object.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description java.lang.String
getAddress()
Gets the hostname or IP address to listen to when output istcpserver
or connect to when output istcpclient
boolean
getAppend()
Returns whether the output should be appended to an existing file.java.lang.String
getClassDumpDir()
Returns the location of the directory where class files should be dumped to.java.lang.String
getDestfile()
Returns the output file location.boolean
getDumpOnExit()
Returns whether coverage data should be dumped on exit.java.lang.String
getExclClassloader()
Returns the wildcard expression for excluded class loaders.java.lang.String
getExcludes()
Returns the wildcard expression for classes to exclude.boolean
getInclBootstrapClasses()
Returns whether classes from the bootstrap classloader should be instrumented.boolean
getInclNoLocationClasses()
Returns whether classes without source location should be instrumented.java.lang.String
getIncludes()
Returns the wildcard expression for classes to include.boolean
getJmx()
Returns whether the agent exposes functionality via JMX.AgentOptions.OutputMode
getOutput()
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
.java.lang.String
getQuotedVMArgument(java.io.File agentJarFile)
Generate required quoted JVM argument based on current configuration and supplied agent jar location.java.lang.String
getSessionId()
Returns the session identifier.java.lang.String
getVMArgument(java.io.File agentJarFile)
Generate required JVM argument based on current configuration and supplied agent jar location.java.lang.String
prependVMArguments(java.lang.String arguments, java.io.File agentJarFile)
Generate required quotes JVM argument based on current configuration and prepends it to the given argument command line.void
setAddress(java.lang.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(java.lang.String location)
Sets the directory where class files should be dumped to.void
setDestfile(java.lang.String destfile)
Sets the output file location.void
setDumpOnExit(boolean dumpOnExit)
Sets whether coverage data should be dumped on exit.void
setExclClassloader(java.lang.String expression)
Sets the wildcard expression for excluded class loaders.void
setExcludes(java.lang.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(java.lang.String includes)
Sets the wildcard expression for classes to include.void
setJmx(boolean jmx)
Sets whether the agent should expose functionality via JMX.void
setOutput(java.lang.String output)
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(java.lang.String id)
Sets the session identifier.java.lang.String
toString()
Creates a string representation that can be passed to the agent via the command line.
-
-
-
Field Detail
-
DESTFILE
public static final java.lang.String DESTFILE
Specifies the output file for execution data. Default isjacoco.exec
in the working directory.- See Also:
- Constant Field Values
-
DEFAULT_DESTFILE
public static final java.lang.String DEFAULT_DESTFILE
Default value for the "destfile" agent option.- See Also:
- Constant Field Values
-
APPEND
public static final java.lang.String APPEND
Specifies whether execution data should be appended to the output file. Default istrue
.- See Also:
- Constant Field Values
-
INCLUDES
public static final java.lang.String INCLUDES
Wildcard expression for class names that should be included for code coverage. Default is*
(all classes included).- See Also:
WildcardMatcher
, Constant Field Values
-
EXCLUDES
public static final java.lang.String EXCLUDES
Wildcard expression for class names that should be excluded from code coverage. Default is the empty string (no exclusions).- See Also:
WildcardMatcher
, Constant Field Values
-
EXCLCLASSLOADER
public static final java.lang.String 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:
WildcardMatcher
, Constant Field Values
-
INCLBOOTSTRAPCLASSES
public static final java.lang.String 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:
- Constant Field Values
-
INCLNOLOCATIONCLASSES
public static final java.lang.String 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:
- Constant Field Values
-
SESSIONID
public static final java.lang.String 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:
- Constant Field Values
-
DUMPONEXIT
public static final java.lang.String DUMPONEXIT
Specifies whether the agent will automatically dump coverage data on VM exit. Default istrue
.- See Also:
- Constant Field Values
-
OUTPUT
public static final java.lang.String OUTPUT
Specifies the output mode. Default isAgentOptions.OutputMode.file
.
-
ADDRESS
public static final java.lang.String ADDRESS
The IP address or DNS name the tcpserver binds to or the tcpclient connects to. Default is defined byDEFAULT_ADDRESS
.- See Also:
- Constant Field Values
-
DEFAULT_ADDRESS
public static final java.lang.String DEFAULT_ADDRESS
Default value for the "address" agent option.
-
PORT
public static final java.lang.String 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:
- Constant Field Values
-
DEFAULT_PORT
public static final int DEFAULT_PORT
Default value for the "port" agent option.- See Also:
- Constant Field Values
-
CLASSDUMPDIR
public static final java.lang.String 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:
- Constant Field Values
-
JMX
public static final java.lang.String JMX
Specifies whether the agent should expose functionality via JMX under the name "org.jacoco:type=Runtime". Default isfalse
.- See Also:
- Constant Field Values
-
-
Constructor Detail
-
AgentOptions
public AgentOptions()
New instance with all values set to default.
-
AgentOptions
public AgentOptions(java.lang.String optionstr)
New instance parsed from the given option string.- Parameters:
optionstr
- string to parse ornull
-
AgentOptions
public AgentOptions(java.util.Properties properties)
New instance read from the givenProperties
object.- Parameters:
properties
-Properties
object to read configuration options from
-
-
Method Detail
-
getDestfile
public java.lang.String getDestfile()
Returns the output file location.- Returns:
- output file location
-
setDestfile
public void setDestfile(java.lang.String destfile)
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
public java.lang.String getIncludes()
Returns the wildcard expression for classes to include.- Returns:
- wildcard expression for classes to include
- See Also:
WildcardMatcher
-
setIncludes
public void setIncludes(java.lang.String includes)
Sets the wildcard expression for classes to include.- Parameters:
includes
- wildcard expression for classes to include- See Also:
WildcardMatcher
-
getExcludes
public java.lang.String getExcludes()
Returns the wildcard expression for classes to exclude.- Returns:
- wildcard expression for classes to exclude
- See Also:
WildcardMatcher
-
setExcludes
public void setExcludes(java.lang.String excludes)
Sets the wildcard expression for classes to exclude.- Parameters:
excludes
- wildcard expression for classes to exclude- See Also:
WildcardMatcher
-
getExclClassloader
public java.lang.String getExclClassloader()
Returns the wildcard expression for excluded class loaders.- Returns:
- expression for excluded class loaders
- See Also:
WildcardMatcher
-
setExclClassloader
public void setExclClassloader(java.lang.String expression)
Sets the wildcard expression for excluded class loaders.- Parameters:
expression
- expression for excluded class loaders- See Also:
WildcardMatcher
-
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
public java.lang.String getSessionId()
Returns the session identifier.- Returns:
- session identifier
-
setSessionId
public void setSessionId(java.lang.String id)
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
public java.lang.String 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
public void setAddress(java.lang.String address)
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
public AgentOptions.OutputMode getOutput()
Returns the output mode- Returns:
- current output mode
-
setOutput
public void setOutput(java.lang.String output)
Sets the output mode- Parameters:
output
- Output mode
-
setOutput
public void setOutput(AgentOptions.OutputMode output)
Sets the output mode- Parameters:
output
- Output mode
-
getClassDumpDir
public java.lang.String getClassDumpDir()
Returns the location of the directory where class files should be dumped to.- Returns:
- dump location or
null
(no dumps)
-
setClassDumpDir
public void setClassDumpDir(java.lang.String location)
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
-
getVMArgument
public java.lang.String getVMArgument(java.io.File agentJarFile)
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
public java.lang.String getQuotedVMArgument(java.io.File agentJarFile)
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
public java.lang.String prependVMArguments(java.lang.String arguments, java.io.File agentJarFile)
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
public java.lang.String 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.- Overrides:
toString
in classjava.lang.Object
-
-