org.jacoco.core.runtime
Class AgentOptions

java.lang.Object
  extended by org.jacoco.core.runtime.AgentOptions

public final class AgentOptions
extends 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
static class AgentOptions.OutputMode
          Possible values for OUTPUT.
 
Field Summary
static String ADDRESS
          The IP address or DNS name the tcpserver binds to or the tcpclient connects to.
static String APPEND
          Specifies whether execution data should be appended to the output file.
static String CLASSDUMPDIR
          Specifies where the agent dumps all class files it encounters.
static String DEFAULT_ADDRESS
          Default value for the "address" agent option.
static String DEFAULT_DESTFILE
          Default value for the "destfile" agent option.
static int DEFAULT_PORT
          Default value for the "port" agent option.
static String DESTFILE
          Specifies the output file for execution data.
static String DUMPONEXIT
          Specifies whether the agent will automatically dump coverage data on VM exit.
static String EXCLCLASSLOADER
          Wildcard expression for class loaders names for classes that should be excluded from code coverage.
static String EXCLUDES
          Wildcard expression for class names that should be excluded from code coverage.
static String INCLBOOTSTRAPCLASSES
          Specifies whether also classes from the bootstrap classloader should be instrumented.
static String INCLNOLOCATIONCLASSES
          Specifies whether also classes without a source location should be instrumented.
static String INCLUDES
          Wildcard expression for class names that should be included for code coverage.
static String JMX
          Specifies whether the agent should expose functionality via JMX under the name "org.jacoco:type=Runtime".
static String OUTPUT
          Specifies the output mode.
static String PORT
          The port the tcpserver binds to or the tcpclient connects to.
static String SESSIONID
          Specifies a session identifier that is written with the execution data.
 
Constructor Summary
AgentOptions()
          New instance with all values set to default.
AgentOptions(Properties properties)
          New instance read from the given Properties object.
AgentOptions(String optionstr)
          New instance parsed from the given option string.
 
Method Summary
 String getAddress()
          Gets the hostname or IP address to listen to when output is tcpserver or connect to when output is tcpclient
 boolean getAppend()
          Returns whether the output should be appended to an existing file.
 String getClassDumpDir()
          Returns the location of the directory where class files should be dumped to.
 String getDestfile()
          Returns the output file location.
 boolean getDumpOnExit()
          Returns whether coverage data should be dumped on exit.
 String getExclClassloader()
          Returns the wildcard expression for excluded class loaders.
 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.
 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 mode
 int getPort()
          Returns the port on which to listen to when the output is tcpserver or the port to connect to when output is tcpclient.
 String getQuotedVMArgument(File agentJarFile)
          Generate required quoted JVM argument based on current configuration and supplied agent jar location.
 String getSessionId()
          Returns the session identifier.
 String getVMArgument(File agentJarFile)
          Generate required JVM argument based on current configuration and supplied agent jar location.
 String 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 is tcpserver or connect to when output is tcpclient
 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.
 void setOutput(AgentOptions.OutputMode output)
          Sets the output mode
 void setOutput(String output)
          Sets the output mode
 void setPort(int port)
          Sets the port on which to listen to when output is tcpserver or the port to connect to when output is tcpclient
 void setSessionId(String id)
          Sets the session identifier.
 String toString()
          Creates a string representation that can be passed to the agent via the command line.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

DESTFILE

public static final String DESTFILE
Specifies the output file for execution data. Default is jacoco.exec in the working directory.

See Also:
Constant Field Values

DEFAULT_DESTFILE

public static final String DEFAULT_DESTFILE
Default value for the "destfile" agent option.

See Also:
Constant Field Values

APPEND

public static final String APPEND
Specifies whether execution data should be appended to the output file. Default is true.

See Also:
Constant Field Values

INCLUDES

public static final 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 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 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 is sun.reflect.DelegatingClassLoader.

See Also:
WildcardMatcher, Constant Field Values

INCLBOOTSTRAPCLASSES

public static final 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 is false.

See Also:
Constant Field Values

INCLNOLOCATIONCLASSES

public static final 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 is false.

See Also:
Constant Field Values

SESSIONID

public static final 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 String DUMPONEXIT
Specifies whether the agent will automatically dump coverage data on VM exit. Default is true.

See Also:
Constant Field Values

OUTPUT

public static final String OUTPUT
Specifies the output mode. Default is AgentOptions.OutputMode.file.

See Also:
AgentOptions.OutputMode.file, AgentOptions.OutputMode.tcpserver, AgentOptions.OutputMode.tcpclient, AgentOptions.OutputMode.none, Constant Field Values

ADDRESS

public static final String ADDRESS
The IP address or DNS name the tcpserver binds to or the tcpclient connects to. Default is defined by DEFAULT_ADDRESS.

See Also:
Constant Field Values

DEFAULT_ADDRESS

public static final String DEFAULT_ADDRESS
Default value for the "address" agent option.


PORT

public static final 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 by DEFAULT_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 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 is null (no dumps).

See Also:
Constant Field Values

JMX

public static final String JMX
Specifies whether the agent should expose functionality via JMX under the name "org.jacoco:type=Runtime". Default is false.

See Also:
Constant Field Values
Constructor Detail

AgentOptions

public AgentOptions()
New instance with all values set to default.


AgentOptions

public AgentOptions(String optionstr)
New instance parsed from the given option string.

Parameters:
optionstr - string to parse or null

AgentOptions

public AgentOptions(Properties properties)
New instance read from the given Properties object.

Parameters:
properties - Properties object to read configuration options from
Method Detail

getDestfile

public String getDestfile()
Returns the output file location.

Returns:
output file location

setDestfile

public void setDestfile(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 String getIncludes()
Returns the wildcard expression for classes to include.

Returns:
wildcard expression for classes to include
See Also:
WildcardMatcher

setIncludes

public void setIncludes(String includes)
Sets the wildcard expression for classes to include.

Parameters:
includes - wildcard expression for classes to include
See Also:
WildcardMatcher

getExcludes

public String getExcludes()
Returns the wildcard expression for classes to exclude.

Returns:
wildcard expression for classes to exclude
See Also:
WildcardMatcher

setExcludes

public void setExcludes(String excludes)
Sets the wildcard expression for classes to exclude.

Parameters:
excludes - wildcard expression for classes to exclude
See Also:
WildcardMatcher

getExclClassloader

public String getExclClassloader()
Returns the wildcard expression for excluded class loaders.

Returns:
expression for excluded class loaders
See Also:
WildcardMatcher

setExclClassloader

public void setExclClassloader(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 String getSessionId()
Returns the session identifier.

Returns:
session identifier

setSessionId

public void setSessionId(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 is tcpserver or the port to connect to when output is tcpclient.

Returns:
port to listen on or connect to

setPort

public void setPort(int port)
Sets the port on which to listen to when output is tcpserver or the port to connect to when output is tcpclient

Parameters:
port - port to listen on or connect to

getAddress

public String getAddress()
Gets the hostname or IP address to listen to when output is tcpserver or connect to when output is tcpclient

Returns:
Hostname or IP address

setAddress

public void setAddress(String address)
Sets the hostname or IP address to listen to when output is tcpserver or connect to when output is tcpclient

Parameters:
address - Hostname or IP address

getOutput

public AgentOptions.OutputMode getOutput()
Returns the output mode

Returns:
current output mode

setOutput

public void setOutput(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 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(String location)
Sets the directory where class files should be dumped to.

Parameters:
location - dump location or null (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 String getVMArgument(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 String getQuotedVMArgument(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 String prependVMArguments(String arguments,
                                 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 or null
agentJarFile - location of the JaCoCo Agent Jar
Returns:
VM command line arguments prepended with configured JaCoCo agent

toString

public 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 class Object


Copyright © 2009–2023 Mountainminds GmbH & Co. KG. All rights reserved.