Summary

This change introduces a short-hand alternative to -Dcom.sun.management.jmxremote.* flags used to start the default management agent.

Problem

The -D command line options for starting the management agent are long and complicated to type, and are not syntax checked and provide no error messages when used incorrectly. Hence there is a need for short-hand alternative flags that are compact and easy to use.

Solution

Provide a new option --start-management-agent option that allows validating the specified parameters and values. A set of flags starting with --start-management-agent will be introduced that will follow the GNU long form argument syntax and will work as a syntactic alternative to original -D flags. The -D flags will continue to work as before if --start-management-agent is not specified.

Specification

The new flags will follow the format below.

--start-management-agent parameter1=value1[,value2]*[:parameter2=value1[,value2]*]*

OR

--start-management-agent=parameter1=value1[,value2]*[:parameter2=value1[,value2]*]*

Multiple parameter value pairs are separated by ' : ' and multiple values for a parameter are separated by ' , '

Example: To start the management agent with SSL enabled and authentication disabled, the new flags will be

--start-management-agent ssl=true:authenticate=false 

or

--start-management-agent=ssl=true:authenticate=false

java -help will print out the below help message for this flag.

Starts the default management agent with colon-seperated list of options. Multiple values for an option should be separated by comma. See the java tool guide for more information

See the management guide https://docs.oracle.com/javase/10/management/monitoring-and-management-using-jmx-technology.htm for a description of each of the -D flags

The set of -D flags that will be provided with syntactic alternative, are as follows:

The values for parameters are case sensitive and must conform with the allowed values as listed in the table above. An error will be reported if invalid parameter name or value is specified.

With the --start-management-agent option, a management property can be assigned a value only once. The management agent will report an error if values are assigned to the same management property more than once. Multiple values to a management property can be assigned as ' , ' seperated list of values.

When --start-management-agent is specified, setting management property via -D option on the command line is not allowed. The management agent will report an error if any management property is set via -D option and also configured through the --start-management-agent option.

If --start-management-agent is specified multiple times, the last instance will be used.

If a management property is specified via --start-management-agent and is also configured via config file specified on the command line via --start-management-agent, then the value specified via the command line takes precedence over the value specified in the config file. For example, with the below command line,

--start-management-agent port=1234:configFile=management.properties:ssl=true:authenticate=false 

and below configuration for management.properties file ,

com.sun.management.jmxremote.ssl=false

com.sun.management.jmxremote.port=5678

the final value for repeated management properties would be,

com.sun.management.jmxremote.ssl=true

com.sun.management.jmxremote.port=1234

The above set of alternative flags will only work when the management agent is started via the command line. Options to start management agent via dynamic attach or jcmd will remain unaffected.