Class 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
     
    • 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".
      private static java.util.regex.Pattern OPTION_SPLIT  
      private java.util.Map<java.lang.String,​java.lang.String> options  
      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.
      private static java.util.Collection<java.lang.String> VALID_OPTIONS  
    • 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 given Properties 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 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.
      private boolean getOption​(java.lang.String key, boolean defaultValue)  
      private int getOption​(java.lang.String key, int defaultValue)  
      private java.lang.String getOption​(java.lang.String key, java.lang.String defaultValue)  
      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.
      private void setOption​(java.lang.String key, boolean value)  
      private void setOption​(java.lang.String key, int value)  
      private void setOption​(java.lang.String key, java.lang.String value)  
      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.
      private void validateAll()  
      private void validatePort​(int port)  
      • 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
      • OPTION_SPLIT

        private static final java.util.regex.Pattern OPTION_SPLIT
      • 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
      • VALID_OPTIONS

        private static final java.util.Collection<java.lang.String> VALID_OPTIONS
      • options

        private final java.util.Map<java.lang.String,​java.lang.String> options
    • 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

      • validateAll

        private void validateAll()
      • validatePort

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

        private void setOption​(java.lang.String key,
                               int value)
      • setOption

        private void setOption​(java.lang.String key,
                               boolean value)
      • setOption

        private void setOption​(java.lang.String key,
                               java.lang.String value)
      • getOption

        private java.lang.String getOption​(java.lang.String key,
                                           java.lang.String defaultValue)
      • getOption

        private boolean getOption​(java.lang.String key,
                                  boolean defaultValue)
      • getOption

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