15.2.1 Instantiating UserJvmOptionsService

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();

15.2.2 Getting Current Values of JVM Options

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.

15.2.3 Getting Default Values of JVM Options

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.

15.2.4 Setting New Values for JVM Options

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);

15.2.5 Example Using the UserJvmOptionsService API

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.

// 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});
       }