Summary

Support dynamic archiving at application runtime when enabled by command line option. The user can then use the dynamic archive in subsequent application run by using an existing command line option.

Problem

With the existing application class-data sharing (AppCDS) feature, the user needs to generate a classlist and then using the classlist to generate a shared archive. Dynamic CDS archive enhances the usability of AppCDS by eliminating the classlist generation step.

Solution

To create a dynamic CDS archive, the user can just run the java application with the following vm option: -XX:ArchiveClassesAtExit=<archive name>

To run the same application using the dynamic CDS archive, the user can make use of the existing -XX:SharedArchiveFile=<archive name> vm option.

Specification

To create a dynamic CDS archive:

java -XX:ArchiveClassesAtExit=<dynamic archive> -cp <app jar> MyApp

The above command creates a dynamic CDS archive with the default CDS archive as the base archive. If the default CDS archive does not exist. VM will exit with the following error:

ArchiveClassesAtExit not supported when base CDS archive is not loaded

The user could also create a dynamic CDS archive with a specific base archive as follows:

java -XX:SharedArchiveFile=<base archive> -XX:ArchiveClassesAtExit=<dynamic archive> -cp <app jar> MyApp

Error checks:

• -Xshare:dump specified with -XX:ArchiveClassesAtExit will result in the following VM error:

Error occurred during initialization of VM
  -XX:ArchiveClassesAtExit cannot be used with -Xshare:dump

• more than one base archive in the -XX:SharedArchiveFile will result in the following VM error:

Error occurred during initialization of VM
  Cannot have more than 1 archive file specified in -XX:SharedArchiveFile during CDS dumping

• same archive file specified in -XX:SharedArchiveFile and -XX:ArchiveClassesAtExit will result in the following VM error:

Error occurred during initialization of VM
  Cannot have the same archive file specified for -XX:SharedArchiveFile and -XX:ArchiveClassesAtExit:<archive name>

• If the base archive does not exist, VM will exit with an error.

If the base archive contains additional path component besides the runtime image and the classpath (-cp), dynamic archive dumping is disabled. Specifically, if the base archive has appended boot classpath, VM will issue the following warning:

Dynamic archiving is disabled because base layer archive has appended boot classpath

If the base archive has module path, VM will issue the following warning:

Dynamic archiving is disabled because base layer archive has module path

To run the application using the dynamic CDS archive and the default CDS (base) archive:

java -XX:SharedArchiveFile=<dynamic archive> -cp <app jar> MyApp

The above command doesn't specify a base archive. The base archive info, including its name and full path, will be retrieved from the dynamic archive header.

Note that the user could also use the -XX:SharedArchiveFile option for specifying a regular (non-dynamic) CDS archive. Therefore, the specified archive in the -XX:SharedArchiveFile option could be of a regular or a dynamic type. During VM starts up, the specified archive header will be read. If it is of dynamic archive type, the base archive location will be retrieved from the header. It also checks if the default CDS archive flag is set in the header. If the flag is set, it will then obtain the default CDS archive location based on the current run time environment. This is to account for if the default CDS archive file has been moved to a different location after the creation of the dynamic archive. If it is of the regular archive type, then it will work as before as in the existing AppCDS case when the archive is specified at a location.

To run the application using the dynamic CDS archive and a specific base CDS archive:

java -XX:SharedArchiveFile=<base archive>:<dynamic archive> -cp <app jar> MyApp

The above command is useful if the base archive used for creating the dynamic archive has been moved. Normally, just specifying the dynamic archive should be sufficient since the base archive info can be retrieved from the dynamic archive header.

Error checks:

• if base archive is specified in the dynamic archive location, VM will issue the following error:

Error occurred during initialization of VM       
  Not a base shared archive:<archive name>

• if dynamic archive is specified in the dynamic archive location, VM will issue the following error:

Error occurred during initialization of VM       
  Not a top shared archive:<archive name>

• if base archive not specified, i.e. -XX:SharedArchiveFile=:<dynamic archive>, VM will issue the following error:

Error occurred during initialization of VM       
  Base archive was not specified:<archive name>

• if dynamic archive not specified, i.e. -XX:SharedArchiveFile=<base archive>:, VM will issue the following error:

Error occurred during initialization of VM       
  Top archive was not specified:<archive name>

• if more than 2 archive files are specified, VM will issue the following error:

Error occurred during initialization of VM       
  Cannot have more than 2 archive files specified in the -XX:SharedArchiveFile option

If the content of the specified base archive is different from the one used during dynamic archive dump time, VM will report errors such as CRC checksum mismatch.