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

    Nested Classes
    Modifier and Type
    Class
    Description
    static enum 
    Possible values for OUTPUT.
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static 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
     
    private final Map<String,String>
     
    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

    Constructors
    Constructor
    Description
    New instance with all values set to default.
    AgentOptions(String optionstr)
    New instance parsed from the given option string.
    New instance read from the given Properties object.
  • Method Summary

    Modifier and Type
    Method
    Description
    Gets the hostname or IP address to listen to when output is tcpserver or connect to when output is tcpclient
    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
    Returns whether the agent exposes functionality via JMX.
    private boolean
    getOption(String key, boolean defaultValue)
     
    private int
    getOption(String key, int defaultValue)
     
    private String
    getOption(String key, String defaultValue)
     
    Returns the output mode
    int
    Returns the port on which to listen to when the output is tcpserver or the port to connect to when output is tcpclient.
    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 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
    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
    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
    setOption(String key, boolean value)
     
    private void
    setOption(String key, int value)
     
    private void
    setOption(String key, String value)
     
    void
    setOutput(String output)
    Sets the output mode
    void
    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
    Sets the session identifier.
    Creates a string representation that can be passed to the agent via the command line.
    private void
     
    private void
    validatePort(int port)
     

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
  • Field Details

    • DESTFILE

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

      public static final String DEFAULT_DESTFILE
      Default value for the "destfile" agent option.
      See Also:
    • APPEND

      public static final String APPEND
      Specifies whether execution data should be appended to the output file. Default is true.
      See Also:
    • 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:
    • 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:
    • 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:
    • 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:
    • 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:
    • 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:
    • DUMPONEXIT

      public static final String DUMPONEXIT
      Specifies whether the agent will automatically dump coverage data on VM exit. Default is true.
      See Also:
    • OUTPUT

      public static final String OUTPUT
      Specifies the output mode. Default is AgentOptions.OutputMode.file.
      See Also:
    • OPTION_SPLIT

      private static final Pattern OPTION_SPLIT
    • 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:
    • 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:
    • DEFAULT_PORT

      public static final int DEFAULT_PORT
      Default value for the "port" agent option.
      See Also:
    • 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:
    • 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:
    • VALID_OPTIONS

      private static final Collection<String> VALID_OPTIONS
    • options

      private final Map<String,String> options
  • Constructor Details

    • 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 Details

    • validateAll

      private void validateAll()
    • validatePort

      private void validatePort(int port)
    • 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:
    • setIncludes

      public void setIncludes(String includes)
      Sets the wildcard expression for classes to include.
      Parameters:
      includes - wildcard expression for classes to include
      See Also:
    • getExcludes

      public String getExcludes()
      Returns the wildcard expression for classes to exclude.
      Returns:
      wildcard expression for classes to exclude
      See Also:
    • setExcludes

      public void setExcludes(String excludes)
      Sets the wildcard expression for classes to exclude.
      Parameters:
      excludes - wildcard expression for classes to exclude
      See Also:
    • getExclClassloader

      public String getExclClassloader()
      Returns the wildcard expression for excluded class loaders.
      Returns:
      expression for excluded class loaders
      See Also:
    • setExclClassloader

      public void setExclClassloader(String expression)
      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

      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
    • setOption

      private void setOption(String key, int value)
    • setOption

      private void setOption(String key, boolean value)
    • setOption

      private void setOption(String key, String value)
    • getOption

      private String getOption(String key, String defaultValue)
    • getOption

      private boolean getOption(String key, boolean defaultValue)
    • getOption

      private int getOption(String key, int defaultValue)
    • 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