-Xshareclasses
Use the -Xshareclasses
option to enable, disable, or modify class sharing behavior.
This option can take a number of parameters, some of which are cache utilities. Cache utilities carry out specific operations on a specified cache without starting the Java virtual machine (VM). Although you can combine multiple suboptions, which are separated by commas, the cache utilities are mutually exclusive.
Some cache utilities can work with caches from previous Java™ versions or caches that are created by VMs with different bit-widths. These caches are referred to as "incompatible" caches.
See also the Class data sharing topic, which includes some best practices for using -Xshareclasses
.
Syntax
-Xshareclasses:<parameter>
When you specify -Xshareclasses
without any parameters and without specifying either the -Xscmx
or -XX:SharedCacheHardLimit
options, a shared classes cache is created with a default size, as follows:
- For 64-bit platforms, the default size is 300 MB, with a "soft" maximum limit for the initial size of the cache (
-Xscmx
) of 64 MB, with the following exceptions:- For a persistent cache, if the free disk space is less than 6 GB, the default size is set to 64 MB and an
-Xscmx
size is not set. - For a non-persistent cache on Linux® or macOS® systems, the cache size is limited by the maximum amount of memory that can be reserved by a process (
SHMMAX
). IfSHMMAX
is less than 300 MB, the default shared cache size is set to equalSHMMAX
. IfSHMMAX
is greater than 80 MB,-Xscmx
is set to 64 MB. IfSHMMAX
is less than 80 MB an-Xscmx
size is not set.
- For a persistent cache, if the free disk space is less than 6 GB, the default size is set to 64 MB and an
- For other platforms, the default size is 16 MB.
Parameters
adjustmaxaot
(Cache utility)
-Xshareclasses:adjustmaxaot=<size>
- Adjusts the maximum shared classes cache space that is allowed for AOT data. When you use the
-Xshareclasses:verbose
option, the VM writes to the console the number of bytes that are not stored due to the current setting of the-Xscmaxaot
option.
adjustminaot
(Cache utility)
-Xshareclasses:adjustminaot=<size>
- Adjusts the minimum shared classes cache space that is reserved for AOT data. Use the
-Xscminaot
option to set the initial minimum size.
adjustmaxjitdata
(Cache utility)
-Xshareclasses:adjustmaxjitdata=<size>
- Adjusts the maximum shared classes cache space that is allowed for JIT data. When you use the
-Xshareclasses:verbose
option, the VM writes to the console the number of bytes that are not stored due to the current setting of the-Xscmaxjitdata
option.
adjustminjitdata
(Cache utility)
-Xshareclasses:adjustminjitdata=<size>
- Adjusts the minimum shared classes cache space that is reserved for JIT data. Use the
-Xscminjitdata
option to set the initial minimum size.
adjustsoftmx
(Cache utility)
-Xshareclasses:adjustsoftmx=<size>
- Adjusts the soft maximum size of the cache. When you use the
-Xshareclasses:verbose
option, the VM writes to the console the number of bytes that are not stored due to the current setting of the soft maximum size. For more information about the soft maximum size, see -Xscmx.
allowClasspaths
-Xshareclasses:allowClasspaths
- Allows a VM to store classpaths into an existing shared cache that was created by using the
restrictClasspaths
option.
bootClassesOnly
-Xshareclasses:bootClassesOnly
- Disables caching of classes that are loaded by class loaders other than the bootstrap class loader. If you use this suboption, the
nonfatal
suboption is also set, so this suboption is the equivalent of specifying-Xshareclasses:bootClassesOnly,nonfatal
.
cacheDir
-Xshareclasses:cacheDir=<directory>
-
Sets the directory in which cache data is read and written. Do not set the cache directory on an NFS mount or a shared mount across systems or LPARs. The following defaults apply:
- On Windows™ systems,
<directory>
is the user'sC:\Users\<username>\AppData\Local\javasharedresources
directory. - On z/OS® systems,
<directory>
is the/tmp/javasharedresources
directory. - On other operating systems,
<directory>
is.cache/javasharedresources
in the user's home directory, unless thegroupAccess
parameter is specified, in which case it is/tmp/javasharedresources
, because some members of the group might not have access to the user's home directory. You must have sufficient permissions in<directory>
. Do not set user's home directory on a NFS or shared mount.
- On Windows™ systems,
-
On all operating systems, the VM writes persistent cache files directly into the directory specified. Persistent cache files can be safely moved and deleted from the file system.
-
Non-persistent caches are stored in shared memory and have control files that describe the location of the memory. Control files are stored in a
javasharedresources
subdirectory of thecacheDir
specified. Do not move or delete control files in this directory. ThelistAllCaches
utility, thedestroyAll
utility, and theexpire
suboption work only in the scope of a givencacheDir
. -
On AIX, Linux, and macOS systems, if you specify the
cacheDir=<directory>
option, persistent caches are created with the following permissions (-rw-r--r--
):- User: read/write
- Group: read (read/write if you also specify
-Xshareclasses:groupAccess
) - Other: read only
-
Otherwise, persistent caches are created with the same permissions as non-persistent caches. The permissions for non-persistent caches are
-rw-r-----
, or-rw-rw----
if you also specify-Xshareclasses:groupAccess
. -
Note: It is good practice to set an application-specific cache directory to avoid sharing the default cache directory with the default cache, or other application caches that don't set a cache directory, and means that your application is therefore unaffected by a user runningjava -Xshareclasses:destroyAll
. See Class data sharing: Best practices for using-Xshareclasses
.
cacheDirPerm
- (Not Windows)
-Xshareclasses:cacheDirPerm=<permission>
-
Sets Unix-style permissions when you are creating a cache directory.
<permission>
must be an octal number in the ranges 0700 - 0777 or 1700 - 1777. If<permission>
is not valid, the VM ends with an appropriate error message. -
The permissions that are specified by this suboption are used only when you are creating a new cache directory. If the cache directory already exists, this suboption is ignored and the cache directory permissions are not changed.
-
If you set this suboption to 0000, the default directory permissions are used. If you set this suboption to 1000, the machine default directory permissions are used, but the sticky bit is enabled.
-
If the cache directory is the platform default directory, this suboption is ignored. The permission is set as specified in the following conditions and permissions table.
-
If you do not set this suboption, the default permissions are used according to the following conditions:
Condition | Permissions |
---|---|
The cache directory is /tmp/javasharedresources . If this directory already exists with different permissions, the permissions are changed when the cache is opened.† |
0777 |
The cache directory already exists and is not /tmp/javasharedresources |
Unchanged |
The cache directory is a new directory and you also specify the groupAcess suboption |
0770 |
The cache directory is a new directory and you do not specify the groupAccess suboption |
0700 |
- †On z/OS systems, permissions for existing cache directories are unchanged, to avoid generating RACF® errors, which generate log messages.
- Class data sharing: Best practices for using
-Xshareclasses
.
Note: It is good practice to explicitly set permissions for the cache directory when the defaults are not appropriate. See
cacheRetransformed
-Xshareclasses:cacheRetransformed
- Enables caching of classes that are transformed by using the JVMTI
RetransformClasses
function. For more information, see Redefined and retransformed classes.
The option enableBCI
is enabled by default. However, if you use the cacheRetransformed
option, this option forces cache creation into -Xshareclasses:disableBCI
mode.
createLayer
(64-bit only)
-Xshareclasses:createLayer
- Creates layered caches.
- If there are multiple VMs in a race condition while creating a layered cache, more than one new layered cache can be created. To avoid this situation, use the
-Xshareclasses:layer=<number>
suboption to create a new layered cache with a specific layer number. Seelayer
for more information about layered caches.
destroy
(Cache utility)
-Xshareclasses:destroy
- Destroys a cache that is specified by the
name
,cacheDir
, andnonpersistent
suboptions. A cache can be destroyed only if all VMs that are using it have ended and the user has sufficient permissions.
destroyAll
(Cache utility)
-Xshareclasses:destroyAll
- Tries to destroy all the caches that are specified by the
cacheDir
andnonpersistent
suboptions. - On Windows and z/OS systems, a cache can be destroyed only if all VMs that are using it have shut down and the user has sufficient permissions.
destroyAll
option is invoked from a 31-bit VM, 64-bit caches are not destroyed. Similarly, when thedestroyAll
option is invoked from a 64-bit VM, 31-bit caches are not destroyed. The following message is displayed:JVMSHRC735I: Use a nn-bit VM to perform the requested operation on the nn-bit shared cache "cachename" as the nn-bit VM cannot verify that the shared memory was created by the VM.
Note: On z/OS, when the -
On AIX, Linux, and macOS systems:
-
Non-persistent caches can be destroyed only if all VMs that are using it have shut down and the user has sufficient permissions.
-
Persistent caches that are still in use continue to exist even when you use this option, but they are unlinked from the file system so they are not visible to new VM invocations. If you update the VM then restart an application for which a persistent shared cache already exists, the VM unlinks the existing cache and creates a new cache. Because the unlinked caches are not visible to new VMs, you cannot find them by using the
-Xshareclasses:listAllCaches
option, and you cannot use the-Xshareclasses:printStats
option on them. You can therefore have multiple unlinked caches that consume file system space until they are no longer in use.
destroyAllLayers
(Cache utility)
(64-bit only)
-Xshareclasses:destroyAllLayers
- Destroys all shared cache layers that are specified by the
name
suboption. For example,-Xshareclasses:name=Cache1,destroyAllLayers
destroys all layers of the cache calledCache1
. If you use thedestroy
suboption on a layered cache, for example-Xshareclasses:name=Cache1,destroy
, only the top layer of the cache is destroyed. - For more information about layered caches, see Creating layer caches.
destroyAllSnapshots
(Cache utility)
- (Not Windows)
-Xshareclasses:destroyAllSnapshots
-
Destroys all shared cache snapshots that are available as a result of the specified
cacheDir
suboption.
destroySnapshot
(Cache utility)
- (Not Windows)
-Xshareclasses:destroySnapshot
-
Destroys a snapshot that is specified by the
name
andcacheDir
suboptions.
disableBCI
-Xshareclasses:disableBCI
- Turns off BCI support. This option can be used to override
-XXShareClassesEnableBCI
.
enableBCI
-Xshareclasses:enableBCI
- This option is enabled by default.
- Allows a JVMTI
ClassFileLoadHook
event to be triggered every time, for classes that are loaded from the cache. This mode also prevents caching of classes that are modified by JVMTI agents. For more information about bytecode modification, see Support for bytecode instrumentation. This option is incompatible with thecacheRetransformed
option. Using the two options together causes the VM to end with an error message, unless-Xshareclasses:nonfatal
is specified. In this case, the VM continues without using shared classes. - A cache that is created without the
enableBCI
suboption cannot be reused with theenableBCI
suboption. Attempting to do so causes the VM to end with an error message, unless-Xshareclasses:nonfatal
is specified. In this case, the VM continues without using shared classes. A cache that is created with theenableBCI
suboption can be reused without specifying this suboption. In this case, the VM detects that the cache was created with theenableBCI
suboption and uses the cache in this mode.
expire
(Cache utility)
-Xshareclasses:expire=<time_in_minutes>
- Destroys all caches that are unused for the time that is specified before loading shared classes. This option is not a utility option because it does not cause the VM to exit. On Windows systems, which have NTFS file systems, the
expire
option is accurate to the nearest hour.
fatal
-Xshareclasses:fatal
- The VM does not start if class data sharing fails, for example because there was an error when accessing the cache directory. An error message is generated. This suboption is specified by default unless you use the
bootClassesOnly
suboption, which is equivalent to-Xshareclasses:bootClassesOnly,nonfatal
. You can override this behavior by specifying-Xshareclasses:bootClassesOnly,fatal
. See alsononfatal
.
findAotMethods
(Cache utility)
-Xshareclasses:findAotMethods=<method_specification>
-Xshareclasses:findAotMethods=help
- Print the AOT methods in the shared classes cache that match the method specifications. Methods that are already invalidated are indicated in the output. Use this suboption to check which AOT methods in the shared classes cache would be invalidated by using the same method specifications with the
invalidateAotMethods
suboption. To learn more about the syntax to use for<method_specification>
, including how to specify more than one method, see Method specification syntax.
groupAccess
- (Not Windows)
-Xshareclasses:groupAccess
-
Sets operating system permissions on a new cache to allow group access to the cache. Group access can be set only when permitted by the operating system
umask
setting. The default is user access only. -
On AIX, Linux, and macOS systems, if a user creates a cache by specifying the
groupAccess
suboption, other users in the same group must also specify this suboption to be granted access to the same cache. -
When
groupAccess
is specified, the default directory for a cache is/tmp/javasharedresources
. Some systems might clear the content of the/tmp
directory on a reboot, removing the shared cache. To avoid that problem, you are therefore recommended to usecacheDir
to set a different location for the cache. If necessary, usecacheDirPerm
to ensure that the cache directory permissions are set appropriately. -
In certain situations, warning messages might be generated when the
groupAccess
suboption is used. -
This message can occur when persistent caches are used:
JVMSHRC756W Failed to set group access permission on the shared cache file as requested by the 'groupAccess' sub-option
-
These messages can occur when non-persistent caches are used:
JVMSHRC759W Failed to set group access permission as requested by the 'groupAccess' sub-option on the semaphore control file associated with shared classes cache. JVMSHRC760W Failed to set group access permission as requested by the 'groupAccess' sub-option on the shared memory control file associated with shared classes cache.
-
This message can occur in combination with the
snapshotCache
suboption:JVMSHRC761W Failed to set group access permission as requested by the 'groupAccess' sub-option on the shared cache snapshot file.
-
All of these warning messages mean that the user's umask setting does not allow either, or both, of the group
read
andwrite
permission to be set on the file. The typical umask setting restricts only thewrite
permission. To resolve the warning, either change the umask setting or remove thegroupAccess
suboption.
help
-Xshareclasses:help
- Lists all the command-line options.
invalidateAotMethods
(Cache utility)
-Xshareclasses:invalidateAotMethods=<method_specification>
-Xshareclasses:invalidateAotMethods=help
- Modify the existing shared cache to invalidate the AOT methods that match the method specifications. Use this suboption to invalidate AOT methods that cause a failure in the application, without having to destroy the shared cache. Invalidated AOT methods remain in the shared cache, but are then excluded from being loaded. VMs that have not processed the methods, or new VMs that use the cache are not affected by the invalidated methods. The AOT methods are invalidated for the lifetime of the cache, but do not prevent the AOT methods from being compiled again if a new shared cache is created. To prevent AOT method compilation into a new shared cache, use the
-Xaot:exclude
option. For more information, see -Xaot. - To identify AOT problems, see Diagnosing a JIT or AOT problem.
- To revalidate an AOT method, see the
revalidateAotMethods
suboption. Use thefindAotMethod
suboption to determine which AOT methods match the method specifications. To learn more about the syntax to use for<method_specification>
, including how to specify more than one method, see Method specification syntax.
layer
(64-bit only)
-Xshareclasses:layer=<number>
- Creates layered caches.
- This suboption has the same effect as the
createLayer
suboption, but with the added ability to specify the layer number. - For more information about creating a shared classes cache with layers, see Creating layer caches.
listAllCaches
(Cache utility)
-Xshareclasses:listAllCaches
- Lists all the compatible and incompatible caches, and snapshots that exist in the specified cache directory. If you do not specify
cacheDir
, the default directory is used. - Summary information, such as Java version and current usage, is displayed for each cache. Output includes
cache-type
(persistent or non-persistent) andfeature
(compressed references (cr
) or non-compressed references (non-cr
)).
mprotect
- AIX, z/OS 31-bit:
-Xshareclasses:mprotect=[default|all|none]
-
Linux, Windows, macOS:
-Xshareclasses:mprotect=[default|all|partialpagesonstartup|onfind|nopartialpages|none]
-
where:
default
: By default, the memory pages that contain the cache are always protected, unless a specific page is being updated. This protection helps prevent accidental or deliberate corruption to the cache. The cache header is not protected by default because this protection has a performance cost. On Linux, macOS, and Windows systems, after the startup phase, the Java virtual machine (VM) protects partially filled pages whenever new data is added to the shared classes cache in the following sequence:- The VM changes the memory protection of any partially filled pages to read/write.
- The VM adds the data to the cache.
- The VM changes the memory protection of any partially filled pages to read only.
all
: This value ensures that all the cache pages are protected, including the header. See Note.partialpagesonstartup
: This value causes the VM to protect partially filled pages during startup as well as after the startup phase. This value is available only on Linux, macOS, and Windows systems.onfind
: When this option is specified, the VM protects partially filled pages when it reads new data in the cache that is added by another VM. This option is available only on Linux, macOS, and Windows systems.nopartialpages
: Use this value to turn off the protection of partially filled pages. This value is available only on Linux, macOS, and Windows systems.none
: Specifying this value disables the page protection.
-
Note: Specifyingall
has a negative impact on performance. You should specifyall
only for problem diagnosis and not for production. Specifying valuespartialpagesonstartup
oronfind
can also have a negative impact on performance when the cache is being populated. There is no further impact when the cache is full or no longer being modified.
modified
-Xshareclasses:modified=<modified_context>
- Used when a JVMTI agent is installed that might modify bytecode at run time. If you do not specify this suboption and a bytecode modification agent is installed, classes are safely shared with an extra performance cost. The
<modified context>
is a descriptor that is chosen by the user; for example, myModification1. This option partitions the cache so that only VMs that are using context myModification1 can share the same classes. So if, for example, you run an application with a modification context and then run it again with a different modification context, all classes are stored twice in the cache. - For more information, see Sharing modified bytecode.
- If you are migrating from IBM® SDK, Java Technology Edition, Version 7, or earlier releases, you must set
-Xshareclasses:disableBCI
when you use this option to retain the same behavior.
name
-Xshareclasses:name=<name>
- Connects to a cache of a given name, creating the cache if it does not exist. This option is also used to indicate the cache that is to be modified by cache utilities; for example,
destroy
. Use thelistAllCaches
utility to show which named caches are currently available. If you do not specify a name, the default name "sharedcc_%u" is used. "%u" in the cache name inserts the current user name. On operating systems other than Windows, you can specify "%g" in the cache name to insert the current group name. -Xscmx
option, as that option has no effect on a pre-existing cache. See Class data sharing: Best practices for using-Xshareclasses
.
Note: It is good practice to explicitly specify a cache for your application. This avoids the application sharing a cache that is enabled by default or with another application that doesn't set a name, and ensures that the size of your application cache can be set appropriately and that cache space is used exclusively for your application. Note that you cannot change the size of a default cache that already exists by using the
noaot
-Xshareclasses:noaot
- Disables caching and loading of AOT code. AOT code already in the shared data cache can be loaded.
noBootclasspath
-Xshareclasses:noBootclasspath
- Disables the storage of classes that are loaded by the bootstrap class loader in the shared classes cache. Often used with the
SharedClassURLFilter
API to control exactly which classes are cached. For more information about shared class filtering, see The Java shared classes Helper API.
noTimestampChecks
-Xshareclasses:noTimestampChecks
- Turns off timestamp checking when finding classes in the shared cache. Use this option only when you know there are no updates to the classes from the class paths or module paths in your application. Otherwise, obsolete classes might be loaded from the shared cache. If this happens, remove the
noTimestampChecks
option.
nojitdata
-Xshareclasses:nojitdata
- Disables caching of JIT data. JIT data already in the shared data cache can be loaded.
none
-Xshareclasses:none
- Added to the end of a command line, disables class data sharing. This suboption overrides class sharing arguments found earlier on the command line. This suboption disables the shared class utility APIs. To disable class data sharing without disabling the utility APIs, use the
utilities
suboption. For more information about the shared class utility APIs, see The Java shared classes utility API.
nonfatal
-Xshareclasses:nonfatal
- Allows the VM to start, in most cases, even if class data sharing fails. Normal behavior for the VM is to refuse to start if class data sharing fails. If you select
nonfatal
and the shared classes cache fails to initialize, the VM attempts to connect to the cache in read-only mode. If this attempt fails, the VM starts without class data sharing. See alsofatal
. - Creating a shared classes cache. However, cache corruption as a result of a bug in the operating system, VM, or user code might not be detected when opening the cache. In this situation, the cache is used and the application might crash. Note: Unless it is important that your application runs with class data sharing, it is good practice to set this parameter. See
nonpersistent
-Xshareclasses:nonpersistent
- Uses a non-persistent cache. The cache is lost when the operating system shuts down. Non-persistent and persistent caches can have the same name. On Linux, macOS, and Windows systems, you must always use the
nonpersistent
suboption when you run utilities such asdestroy
on a non-persistent cache. kern.sysv.shmmax
andkern.sysv.shmall
when using a non-persistent cache.
Note: On macOS systems, you must set
noPersistentDiskSpaceCheck
-Xshareclasses:noPersistentDiskSpaceCheck
- Instructs the VM not to check for available storage on the file system before creating a persistent shared classes cache. This option prevents an error on file systems that do not support the checking of free space, where a value of 0 is returned and a shared cache cannot be created. Regardless of whether you choose to set this option, if there isn't enough disk space available when the VM writes to the shared cache memory, a SIGBUS or SIGSEGV signal occurs and the VM ends.
- If you are using the
readonly
suboption, the VM does not check the available disk space, so you do not need to set thenoPersistentDiskSpaceCheck
suboption.
persistent
-Xshareclasses:persistent
- Uses a persistent cache. The cache is created on disk, which persists beyond operating system restarts. Non-persistent and persistent caches can have the same name. On z/OS, you must always use the
persistent
suboption when you run utilities such asdestroy
on a persistent cache. - Notes:
-
- With the 31-bit VM on all versions of z/OS, the shared cache is memory mapped within the 0-2 GB address range. The maximum size of the persistent shared classes cache is limited by the system limit
MAXMMAPAREA
. For more information about the suggested value for theMAXMMAPAREA
limit, see Setting resource limits (z/OS). -
With the 64-bit VM, the shared cache is mapped as follows:
- On z/OS version 2.3 and earlier, the persistent shared cache is memory mapped within the 0-2 GB address range. The maximum size of the persistent shared classes cache is limited by the system limit
MAXMMAPAREA
. -
On z/OS version 2.4 and later, the persistent shared cache is mapped above the 2 GB address range. The maximum size of persistent shared classes cache is limited by the
MAXSHARE
value within theSMFLIMxx
member ofSYS1.PARMLIB
. The default persistent shared cache size is 300MB, and the following machine configuration settings will allow a shared cache up to that size.- Add the following line in the
SMFLIMxx
member ofSYS1.PARMLIB
.MAXSHARE
value is defined in number of 4K pages. TheJOBNAME(*)
filter should be customized to apply the setting to the relevant Java address spaces. TheJOBMSG(SUPPRESS)
parameter can be used to optionally suppressIEF043I
diagnostic messages.
REGION JOBNAME(*) JOBMSG(SUPPRESS) MAXSHARE(76800)
- Load the change with the following command in the SDSF panel.
/SET SMFLIM=xx
- Add the following line in the
For more information about the SMFLIMxx member of SYS1.PARMLIB, see Statements and parameters for SMFLIMxx.
On z/OS version 2.4, fixes for APARs OA60306 and PH32235 must be installed for the support of this memory mapping. On z/OS version 2.5 and later, the fixes for APARs OA60306 and PH32235 are included by default.
- On z/OS version 2.3 and earlier, the persistent shared cache is memory mapped within the 0-2 GB address range. The maximum size of the persistent shared classes cache is limited by the system limit
- With the 31-bit VM on all versions of z/OS, the shared cache is memory mapped within the 0-2 GB address range. The maximum size of the persistent shared classes cache is limited by the system limit
printAllStats
(Cache utility)
-Xshareclasses:printAllStats
- Displays detailed information about the contents of the cache that is specified in the
name
suboption. If the name is not specified, statistics are displayed about the default cache. For layered caches, information is shown for all layers (to see information for the top layer cache only, useprintTopLayerStats=all
). Every class is listed in chronological order with a reference to the location from which it was loaded. For more information, see Shared classes cache diagnostic utilities.
printStats
(Cache utility)
-Xshareclasses:printStats=<data_type>[+<data_type>]
- Displays summary information for the cache that is specified by the
name
,cacheDir
, andnonpersistent
suboptions. For layered caches, information is shown for all layers (to see information for the top layer cache only, useprintTopLayerStats
). The most useful information that is displayed is how full the cache is and how many classes it contains. Stale classes are classes that are updated on the file system and which the cache has therefore marked as "stale". Stale classes are not purged from the cache and can be reused. Use theprintStats=stale
option to list all the stale entries and stale bytes. - Specify one or more data types, which are separated by a plus symbol (+), to see more detailed information about the cache content. Data types include AOT data, class paths, and ROMMethods.
- For more information and for a full list of data types, see Shared classes cache diagnostic utilities.
printTopLayerStats
(Cache utility)
-Xshareclasses:printTopLayerStats=<data_type>[+<data_type>]
- Equivalent to
printStats
but for the top layer cache only. For more information about layered caches, see Creating a layer cache.
readonly
-Xshareclasses:readonly
- By default, a shared classes cache is created with read/write access. Use the
readonly
suboption to open an existing cache with read-only permissions. Opening a cache read-only prevents the VM from making any updates to the cache. If you specify this suboption, the VM can connect to caches that were created by other users or groups without requiring write access. - On AIX, Linux, and macOS systems, this access is permitted only if the cache was created by using the
-Xshareclasses:cacheDir
option to specify a directory with appropriate permissions. If you do not use the-Xshareclasses:cacheDir
option, the cache is created with default permissions, which do not permit access by other users or groups. - By default, this suboption is not specified.
reset
-Xshareclasses:reset
- Causes a cache to be destroyed and then re-created when the VM starts up. This option can be added to the end of a command line as
-Xshareclasses:reset
.
restoreFromSnapshot
(Cache utility)
- (Not Windows)
-Xshareclasses:restoreFromSnapshot
-
Restores a new non-persistent shared cache from a snapshot file. The snapshot and shared cache have the same name and location, as specified by the
name
andcacheDir
suboptions. The non-persistent cache cannot already exist when the snapshot is restored. Restoring a snapshot does not remove the snapshot file; it can be restored multiple times. On platforms that support persistent caches, thenonpersistent
suboption must be specified in order to restore a snapshot.
restrictClasspaths
-Xshareclasses:restrictClasspaths
- Allows only the first VM that is initializing a shared cache to store classpaths in the cache. Subsequent VMs are not allowed to store classpaths in the cache unless the
allowClasspaths
option is specified. - Use the
restrictClasspaths
option only if the application is designed to create class loaders of typejava.net.URLClassloader
or its subclass, such that their classpaths are unique to the instance of the application, but the classes that are loaded from these classpaths are the same. In such cases application classpaths that are stored by one VM cannot be used by another VM. -
For example, consider two VMs, VM1 and VM2, that are using class paths CP1 and CP2 respectively, where:
- CP1:
url1;url2;url3;tempurl1;url4;url5
- CP2:
url1;url2;url3;tempurl2;url4;url5
- CP1:
-
These class paths differ only by one entry, which is the
tempurl
. Theurl1
,url2
,url3
,url4
, andurl5
entries never change from run to run, whereas thetempurl
entry is always different. This difference means that a class that is loaded fromurl4
orurl5
, and stored into the shared cache by VM1, cannot be located by VM2. Therefore, an attempt by VM2 to load a class fromurl4
orurl5
would cause it to store its own classpathCP2
into the shared cache, and also add new metadata for classes that are loaded fromurl4
orurl5
. Addition of such unique class paths into the shared cache is not useful. Moreover, the additional metadata might adversely affect the performance of other VMs that connect to the shared cache. Because classes loaded fromurl4
orurl5
are not loaded from the shared cache when thetempurl
differs from the original, it is good practice to put thetempurl
as the last entry in the class path. -
In situations such as that described in the example, the
restrictClasspaths
option can be used to restrict the addition of classpaths by ensuring that the first VM initializes the shared cache, and then prevents the addition of unique classpaths by subsequent VMs that attach to the shared cache. Note that use of therestrictClasspaths
option in any other scenario is likely to negatively impact a VM's performance when it is using an existing cache.
revalidateAotMethods
(Cache utility)
-Xshareclasses:revalidateAotMethods=<method_specification>
-Xshareclasses:revalidateAotMethods=help
- Modify the shared cache to revalidate the AOT methods that match the method specifications. Use this suboption to revalidate AOT methods that were invalidated by using the
invalidateAotMethods
suboption. Revalidated AOT methods are then eligible for loading into a VM, but do not affect VMs where the methods have already been processed. To learn more about the syntax to use for<method_specification>
, including how to specify more than one method, see Method specification syntax.
silent
-Xshareclasses:silent
- Disables all shared class messages, including error messages. Unrecoverable error messages, which prevent the VM from initializing, are displayed.
snapshotCache
(Cache utility)
- (Not Windows)
-Xshareclasses:snapshotCache
-
Creates a snapshot file of an existing non-persistent shared cache. The snapshot has the same name and location as the shared cache, as specified by the
name
andcacheDir
suboptions. The shared cache can be in use when the snapshot is taken, but VMs are blocked when they try to write to the shared cache, while the cache data is copied to the file. -
Typically, after a system is reinitialized, the snapshot file is used to restore the copy of the non-persistent cache into shared memory, via the
restoreFromSnapshot
suboption. Since this process removes all non-persistent caches from shared memory, restoring the cache from the snapshot file can result in better VM startup performance, because the contents of the shared cache, including classes and AOT code, do not have to be re-created. -
A snapshot can be created only if the user has sufficient permissions to create the destination snapshot file. If a snapshot of the same name exists already, it is overwritten. On platforms that support persistent caches, the
nonpersistent
suboption must be specified in order to create a snapshot. For information about removing snapshot files, see thedestroySnapshot
anddestroyAllSnapshots
suboptions.
utilities
-Xshareclasses:utilities
- Can be added to the end of a command line to disable class data sharing. This suboption overrides class sharing arguments found earlier on the command line. This suboption is like
none
, but does not disable the shared class utility APIs. For more information, see The Java shared classes utility API.
verbose
-Xshareclasses:verbose
- Gives detailed output on the cache I/O activity, listing information about classes that are stored and found. Each class loader is given a unique ID (the bootstrap loader is always 0) and the output shows the class loader hierarchy at work, where class loaders ask their parents for a class if they can't find it themselves. It is typical to see many failed requests; this behavior is expected for the class loader hierarchy. The standard option
-verbose:class
also enables class sharing verbose output if class sharing is enabled.
verboseAOT
-Xshareclasses:verboseAOT
- Enables verbose output when compiled AOT code is being found or stored in the cache. AOT code is generated heuristically. You might not see any AOT code that is generated at all for a small application. You can disable AOT caching by using the
noaot
suboption. See the VM Messages Guide for a list of the messages produced.
verboseHelper
-Xshareclasses:verboseHelper
- Enables verbose output for the Java Helper API. This output shows you how the Helper API is used by your class loader.
verboseIO
-Xshareclasses:verboseIO
- Gives detailed output on the cache I/O activity, listing information about classes that are stored and found. Each class loader is given a unique ID (the bootstrap loader is always 0) and the output shows the class loader hierarchy at work, where class loaders must ask their parents for a class before they can load it themselves. It is typical to see many failed requests; this behavior is expected for the class loader hierarchy.
Method specification syntax
The following examples show how to specify more than one method specification when you are using the findAotMethods
, invalidateAotMethods
, or revalidateAotMethods
suboptions.
Each method specification is defined as follows:
<packagename>/<classname>[.<methodname>[(<parameters>)]]
If you want to include more than one method specification in a single option, separate the specifications with a comma and enclose all the specifications in {braces}. For example:
{<packagename/classname>}[.{<methodname>}[({<parameters>})]]
- You can use an asterisk (*) in most places as a wildcard.
- You can use an exclamation point (!) before the specification to mean "everything except this".
- Parameters are optional, but if specified, should be enclosed in parentheses and the following native signature formats must be used:
B
for byteC
for charD
for doubleF
for floatI
for intJ
for longS
for shortZ
for BooleanL<classname>;
for objects[
before the signature means array
If you want to specify parameters to distinguish between methods, you can use -Xshareclasses:findAotMethods=*
(with a wildcard) to list all the parameter variations. Copy the signature for the method that you want from the output. For example, the signature for the parameters
(byte[] bytes, int offset, int length, Charset charset)
is
([BIILjava/nio/charset/Charset;)
Here are some examples:
Method signature | Matches... |
---|---|
* |
All AOT methods. |
java/lang/Object |
All AOT methods in the java.lang.Object class |
java/util/* |
All AOT classes and methods in the java.util package |
java/util/HashMap.putVal |
All putVal methods in the java.util.HashMap class |
java/util/HashMap.hash(Ljava/lang/Object;) |
The private java.util.HashMap.hash(java.lang.Object) method |
*.equals |
All equals methods in all classes |
{java/lang/Object,!java/lang/Object.clone} |
All methods in java.lang.Object except clone |
{java/util/*.*(),java/lang/Object.*(*)} |
All classes or methods with no input parameter in the java.util package, and all methods in java.lang.Object |
{java/util/*.*(),!java/util/*.*()} |
Nothing. |