This topic describes the UserJvmOptionsService API, which can be used in self-contained Java and JavaFX applications to alter the settings for the Java Virtual Machine (JVM). The new settings are used the next time that the application is started.
This topic contains the following sections:
JVM options are used to configure the JVM. For example, options are available for managing memory, setting the class path, and turning on debugging. When you use the Java Packaging tools to package your self-contained application, you can pass in the JVM options that you want your application to use (-BjvmOptions), and provide default values for options that the user can set (-BuserJvmOptions).
The UserJvmOptionsService API enables you to provide a way to manage JVM options through the application, for example, by providing a preferences or settings feature. The settings specified by the user are used each time the application is started. If a user changes the settings, the application must be restarted to use the new settings.
When an application is launched, the values for JVM options are determined in the following order:
Options set through the UserJvmOptionsService API take precedence.
For options that are not set through the API, values from the -BuserJvmOptions arguments that were specified when the application package was created are used.
For options that are not set through the API or the -BuserJvmOptions arguments, values from the -BjvmOptions arguments that were specified when the application package was created are used.
For options that are not specified in any of the above locations, system values are used.
The UserJvmOptionsService API is available in the packager.jar file, which is in the java-home/lib directory. To use the UserJvmOptionsService API, include the packager.jar file in the bundle for your self-contained application.
The UserJvmOptionsService API includes the following methods:
getUserJVMDefaults. See Section 15.2.1, "Instantiating UserJvmOptionsService" for details.
getUserJVMOptions. See Section 15.2.2, "Getting Current Values of JVM Options" for details.
getUserJVMOptionDefaults. See Section 15.2.3, "Getting Default Values of JVM Options" for details.
setUserJVMOptions. See Section 15.2.4, "Setting New Values for JVM Options" for details.
The first step in using the UserJvmOptionsService API is to get an instance of the service to use. The instance is determined by the packager and the launcher. To get the correct instance, call UserJvmOptionsService.getUserJVMDefaults() in a command similar to the following example:
UserJvmOptionsService ujo=UserJvmOptionsService.getUserJVMDefaults();
|
Note: Do not attempt to directly instantiate an instance ofUserJvmOptions. Use only what is provided by the UserJvmOptions.getUserJVMDefaults() method. |
Use the getUserJVMOptions() method to get the current JVM options for the application. This method returns the JVM options and values that were set either using the setUserJVMOptions() method or using the -BuserJvmOptions arguments when the application package was created. If changes have been made to the settings since the application was started, the values returned show the latest settings, not the settings used when the application was started.
The following example shows a sample call to the getUserJVMOptions() method using the instance of the UserJvmOptionsService that was obtained in Section 15.2.1, "Instantiating UserJvmOptionsService":
Map<String, String> userOptions = ujo.getUserJVMOptions();
JVM options are returned as key-value pairs. Each key starts with a dash(-). The key ends with an equals sign (=) if one is needed between the key and value.
Use the getUserJVMOptionDefaults() method to get the default JVM options for the application. This method returns the JVM options and values that were set using the -BuserJvmOptions arguments when the application package was created.
The following example shows a sample call to the getUserJVMOptionDefaults() method using the instance of the UserJvmOptionsService that was obtained in Section 15.2.1, "Instantiating UserJvmOptionsService":
Map<String, String> defaults = ujo.getUserJVMOptionsDefaults();
JVM options are returned as key-value pairs. Each key starts with a dash(-). The key ends with an equals sign (=) if one is needed between the key and value.
Use the setUserJVMOptions() method to store changes that the user makes to the JVM options. The application must be restarted to use the new values. If the user does not set a value for an option that was specified in a -BuserJvmOptions argument when the application package was created, the value from the -BuserJvmOptions argument is used when the application is started.
JVM options are passed as key-value pairs, which are concatenated when passed to the JVM. Start the key with a dash(-). If an equals sign (=) is needed between the key and value, it must be the last character in the key. For example, to set the system property applicationName to SampleApp, use the key -DapplicationName= and the value SampleApp. To set the maximum size of the memory allocation pool to 80 megabytes, use the key -Xmx and the value 80M.
The following example shows a sample call to the setUserJVMOptions() methid using the instance of the UserJvmOptionsService that was obtained in Section 15.2.1, "Instantiating UserJvmOptionsService" and a set of options contained in the userOptions variable:
ujo.setUserJVMOptions(userOptions);
|
Note: No validation or error checking is performed. If invalid values are provided, your application might not start. |
The following sample code shows how the UserJvmOptionsService API can be used to track the first and last time an application is run. The sample also generates a table to show the current value and default value for the options.
Example 15-1
// get the helper instance
UserJvmOptionsService ujo = UserJvmOptionsService.getUserJVMDefaults();
Map<String, String> userOptions = ujo.getUserJVMOptions();
// print out all the options currently set
for (Map.Entry <String, String> entry : userOptions.entrySet()) {
System.out.println("key:" + entry.getKey() + " value:" + entry.getValue());
}
// if we haven't marked the first run, do so now
if (!userOptions.containsKey("-DfirstRunMs=")) {
userOptions.put("-DfirstRunMs=", Long.toString(System.currentTimeMillis()));
}
// add the last run
userOptions.put("-DlastRunMs=", Long.toString(System.currentTimeMillis()));
// save the changes
ujo.setUserJVMOptions(userOptions);
...
// create a table row with Key, Current Value, and Default Value
DefaultTableModel model = new DefaultTableModel();
model.addColumn("Key");
model.addColumn("Effective");
model.addColumn("Default");
Map<String, String> defaults = ujo.getUserJVMOptionDefaults();
for (Map.Entry <String, String> entry : userOptions.entrySet()) {
// get the default, it may be null
String def = defaults.get(entry.getKey());
model.addRow(new Object[] {entry.getKey(), entry.getValue(),
def == null ? "<no default>" : def});
}
