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
`static class` `AgentOptions.OutputMode` Possible values for `OUTPUT`.

### Field Summary

Fields
`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
`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 given `Properties` object.

### Method Summary

All Methods Instance Methods Concrete Methods
`java.lang.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.
`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 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`.
`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 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​(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 mode
`void` `setOutput​(AgentOptions.OutputMode 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​(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.

### Methods inherited from class java.lang.Object

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

### Field Detail

#### DESTFILE

    public static final java.lang.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 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 is `true`.

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 is `sun.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 is `false`.

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 is `false`.

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 is `true`.

See Also:
  Constant Field Values

#### OUTPUT

    public static final java.lang.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 java.lang.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 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 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 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 is `null` (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 is `false`.

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 or `null`

#### AgentOptions

    public AgentOptions​(java.util.Properties properties)

New instance read from the given `Properties` 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 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 java.lang.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​(java.lang.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​(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 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 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 or `null`
  `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 class `java.lang.Object`