org.jacoco.core.runtime
Class AgentOptions

java.lang.Object
  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