java.1

Logs messages tagged either with the \f[CB]gc\f[R] or \f[CB]safepoint\f[R]
tags, both using the \f[CB]info\f[R] level, to \f[CB]stdout\f[R], with
default decorations.
Messages tagged with both \f[CB]gc\f[R] and \f[CB]safepoint\f[R] won\[aq]t
be logged.
.RS
.RE
.TP
.B \f[CB]\-Xlog:gc+ref=debug\f[R]
Logs messages tagged with both \f[CB]gc\f[R] and \f[CB]ref\f[R] tags, using
the \f[CB]debug\f[R] level to \f[CB]stdout\f[R], with default decorations.
Messages tagged only with one of the two tags won\[aq]t be logged.
.RS
.RE
.TP
.B \f[CB]\-Xlog:gc=debug:file=gc.txt:none\f[R]
Logs messages tagged with the \f[CB]gc\f[R] tag using the \f[CB]debug\f[R]
level to a file called \f[CB]gc.txt\f[R] with no decorations.
The default configuration for all other messages at level
\f[CB]warning\f[R] is still in effect.
.RS
.RE
.TP
.B \f[CB]\-Xlog:gc=trace:file=gctrace.txt:uptimemillis,pids:filecount=5,filesize=1024\f[R]
Logs messages tagged with the \f[CB]gc\f[R] tag using the \f[CB]trace\f[R]
level to a rotating file set with 5 files with size 1 MB with the base
name \f[CB]gctrace.txt\f[R] and uses decorations \f[CB]uptimemillis\f[R] and
\f[CB]pid\f[R].
.RS
.PP
The default configuration for all other messages at level
\f[CB]warning\f[R] is still in effect.
.RE
.TP
.B \f[CB]\-Xlog:gc::uptime,tid\f[R]
Logs messages tagged with the \f[CB]gc\f[R] tag using the default
\[aq]info\[aq] level to default the output \f[CB]stdout\f[R] and uses
decorations \f[CB]uptime\f[R] and \f[CB]tid\f[R].
The default configuration for all other messages at level
\f[CB]warning\f[R] is still in effect.
.RS
.RE
.TP
.B \f[CB]\-Xlog:gc*=info,safepoint*=off\f[R]
Logs messages tagged with at least \f[CB]gc\f[R] using the \f[CB]info\f[R]
level, but turns off logging of messages tagged with \f[CB]safepoint\f[R].
Messages tagged with both \f[CB]gc\f[R] and \f[CB]safepoint\f[R] won\[aq]t
be logged.
.RS
.RE
.TP
.B \f[CB]\-Xlog:disable\ \-Xlog:safepoint=trace:safepointtrace.txt\f[R]
Turns off all logging, including warnings and errors, and then enables
messages tagged with \f[CB]safepoint\f[R]using \f[CB]trace\f[R]level to the
file \f[CB]safepointtrace.txt\f[R].
The default configuration doesn\[aq]t apply, because the command line
started with \f[CB]\-Xlog:disable\f[R].
.RS
.RE
.SS Complex \-Xlog Usage Examples
.PP
The following describes a few complex examples of using the
\f[CB]\-Xlog\f[R] option.
.TP
.B \f[CB]\-Xlog:gc+class*=debug\f[R]
Logs messages tagged with at least \f[CB]gc\f[R] and \f[CB]class\f[R] tags
using the \f[CB]debug\f[R] level to \f[CB]stdout\f[R].
The default configuration for all other messages at the level
\f[CB]warning\f[R] is still in effect
.RS
.RE
.TP
.B \f[CB]\-Xlog:gc+meta*=trace,class*=off:file=gcmetatrace.txt\f[R]
Logs messages tagged with at least the \f[CB]gc\f[R] and \f[CB]meta\f[R]
tags using the \f[CB]trace\f[R] level to the file \f[CB]metatrace.txt\f[R]
but turns off all messages tagged with \f[CB]class\f[R].
Messages tagged with \f[CB]gc\f[R], \f[CB]meta\f[R], and \f[CB]class\f[R]
aren\[aq]t be logged as \f[CB]class*\f[R] is set to off.
The default configuration for all other messages at level
\f[CB]warning\f[R] is in effect except for those that include
\f[CB]class\f[R].
.RS
.RE
.TP
.B \f[CB]\-Xlog:gc+meta=trace\f[R]
Logs messages tagged with exactly the \f[CB]gc\f[R] and \f[CB]meta\f[R] tags
using the \f[CB]trace\f[R] level to \f[CB]stdout\f[R].
The default configuration for all other messages at level
\f[CB]warning\f[R] is still be in effect.
.RS
.RE
.TP
.B \f[CB]\-Xlog:gc+class+heap*=debug,meta*=warning,threads*=off\f[R]
Logs messages tagged with at least \f[CB]gc\f[R], \f[CB]class\f[R], and
\f[CB]heap\f[R] tags using the \f[CB]trace\f[R] level to \f[CB]stdout\f[R] but
only log messages tagged with \f[CB]meta\f[R] with level.
The default configuration for all other messages at the level
\f[CB]warning\f[R] is in effect except for those that include
\f[CB]threads\f[R].
.RS
.RE
.SH VALIDATE JAVA VIRTUAL MACHINE FLAG ARGUMENTS
.PP
You use values provided to all Java Virtual Machine (JVM) command\-line
flags for validation and, if the input value is invalid or
out\-of\-range, then an appropriate error message is displayed.
.PP
Whether they\[aq]re set ergonomically, in a command line, by an input
tool, or through the APIs (for example, classes contained in the package
\f[CB]java.lang.management\f[R]) the values provided to all Java Virtual
Machine (JVM) command\-line flags are validated.
Ergonomics are described in Java Platform, Standard Edition HotSpot
Virtual Machine Garbage Collection Tuning Guide.
.PP
Range and constraints are validated either when all flags have their
values set during JVM initialization or a flag\[aq]s value is changed
during runtime (for example using the \f[CB]jcmd\f[R] tool).
The JVM is terminated if a value violates either the range or constraint
check and an appropriate error message is printed on the error stream.
.PP
For example, if a flag violates a range or a constraint check, then the
JVM exits with an error:
.IP
.nf
\f[CB]
java\ \-XX:AllocatePrefetchStyle=5\ \-version
intx\ AllocatePrefetchStyle=5\ is\ outside\ the\ allowed\ range\ [\ 0\ ...\ 3\ ]
Improperly\ specified\ VM\ option\ \[aq]AllocatePrefetchStyle=5\[aq]
Error:\ Could\ not\ create\ the\ Java\ Virtual\ Machine.
Error:\ A\ fatal\ exception\ has\ occurred.\ Program\ will\ exit.
\f[R]
.fi
.PP
The flag \f[CB]\-XX:+PrintFlagsRanges\f[R] prints the range of all the
flags.
This flag allows automatic testing of the flags by the values provided
by the ranges.
For the flags that have the ranges specified, the type, name, and the
actual range is printed in the output.
.PP
For example,
.IP
.nf
\f[CB]
intx\ \ \ ThreadStackSize\ [\ 0\ ...\ 9007199254740987\ ]\ {pd\ product}
\f[R]
.fi
.PP
For the flags that don\[aq]t have the range specified, the values
aren\[aq]t displayed in the print out.
For example:
.IP
.nf
\f[CB]
size_t\ NewSize\ \ \ \ \ \ \ \ \ [\ \ \ ...\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ]\ {product}
\f[R]
.fi
.PP
This helps to identify the flags that need to be implemented.
The automatic testing framework can skip those flags that don\[aq]t have
values and aren\[aq]t implemented.
.SH LARGE PAGES
.PP
You use large pages, also known as huge pages, as memory pages that are
significantly larger than the standard memory page size (which varies
depending on the processor and operating system).
Large pages optimize processor Translation\-Lookaside Buffers.
.PP
A Translation\-Lookaside Buffer (TLB) is a page translation cache that
holds the most\-recently used virtual\-to\-physical address
translations.
A TLB is a scarce system resource.
A TLB miss can be costly because the processor must then read from the
hierarchical page table, which may require multiple memory accesses.
By using a larger memory page size, a single TLB entry can represent a
larger memory range.
This results in less pressure on a TLB, and memory\-intensive
applications may have better performance.
.PP
However, using large pages can negatively affect system performance.
For example, when a large amount of memory is pinned by an application,
it may create a shortage of regular memory and cause excessive paging in
other applications and slow down the entire system.
Also, a system that has been up for a long time could produce excessive
fragmentation, which could make it impossible to reserve enough large
page memory.
When this happens, either the OS or JVM reverts to using regular pages.
.PP
Linux and Windows support large pages.
.SS Large Pages Support for Linux
.PP
Linux supports large pages since version 2.6.
To check if your environment supports large pages, try the following:
.IP
.nf
\f[CB]
#\ cat\ /proc/meminfo\ |\ grep\ Huge
HugePages_Total:\ 0
HugePages_Free:\ 0
\&...
Hugepagesize:\ 2048\ kB
\f[R]
.fi
.PP
If the output contains items prefixed with "Huge", then your system
supports large pages.
The values may vary depending on environment.
The \f[CB]Hugepagesize\f[R] field shows the default large page size in
your environment, and the other fields show details for large pages of
this size.
Newer kernels have support for multiple large page sizes.
To list the supported page sizes, run this:
.IP
.nf
\f[CB]
#\ ls\ /sys/kernel/mm/hugepages/
hugepages\-1048576kB\ \ hugepages\-2048kB
\f[R]
.fi
.PP
The above environment supports 2 MB and 1 GB large pages, but they need
to be configured so that the JVM can use them.
When using large pages and not enabling transparent huge pages (option
\f[CB]\-XX:+UseTransparentHugePages\f[R]), the number of large pages must
be pre\-allocated.
For example, to enable 8 GB of memory to be backed by 2 MB large pages,
login as \f[CB]root\f[R] and run:
.RS
.PP
\f[CB]#\ echo\ 4096\ >\ /sys/kernel/mm/hugepages/hugepages\-2048kB/nr_hugepages\f[R]
.RE
.PP
It is always recommended to check the value of \f[CB]nr_hugepages\f[R]
after the request to make sure the kernel was able to allocate the
requested number of large pages.
.PP
When using the option \f[CB]\-XX:+UseSHM\f[R] to enable large pages you
also need to make sure the \f[CB]SHMMAX\f[R] parameter is configured to
allow large enough shared memory segments to be allocated.
To allow a maximum shared segment of 8 GB, login as \f[CB]root\f[R] and
run:
.RS
.PP
\f[CB]#\ echo\ 8589934592\ >\ /proc/sys/kernel/shmmax\f[R]
.RE
.PP
In some environments this is not needed since the default value is large
enough, but it is important to make sure the value is large enough to
fit the amount of memory intended to be backed by large pages.
.RS
.PP
\f[B]Note:\f[R] The values contained in \f[CB]/proc\f[R] and \f[CB]/sys\f[R]
reset after you reboot your system, so may want to set them in an
initialization script (for example, \f[CB]rc.local\f[R] or
\f[CB]sysctl.conf\f[R]).
.RE
.PP
If you configure the OS kernel parameters to enable use of large pages,
the Java processes may allocate large pages for the Java heap as well as
other internal areas, for example:
.IP \[bu] 2
Code cache
.IP \[bu] 2
Marking bitmaps
.PP
Consequently, if you configure the \f[CB]nr_hugepages\f[R] parameter to
the size of the Java heap, then the JVM can still fail to allocate the
heap using large pages because other areas such as the code cache might
already have used some of the configured large pages.
.SS Large Pages Support for Windows
.PP
To use large pages support on Windows, the administrator must first
assign additional privileges to the user who is running the application:
.IP "1." 3
Select \f[B]Control Panel\f[R], \f[B]Administrative Tools\f[R], and then
\f[B]Local Security Policy\f[R].
.IP "2." 3
Select \f[B]Local Policies\f[R] and then \f[B]User Rights Assignment\f[R].
.IP "3." 3
Double\-click \f[B]Lock pages in memory\f[R], then add users and/or
groups.
.IP "4." 3
Reboot your system.
.PP
Note that these steps are required even if it\[aq]s the administrator
who\[aq]s running the application, because administrators by default
don\[aq]t have the privilege to lock pages in memory.
.SH APPLICATION CLASS DATA SHARING
.PP
Application Class Data Sharing (AppCDS) extends class data sharing (CDS)
to enable application classes to be placed in a shared archive.
.PP
In addition to the core library classes, AppCDS supports \f[B]Class Data
Sharing\f[R]
[https://docs.oracle.com/en/java/javase/12/vm/class\-data\-sharing.html#GUID\-7EAA3411\-8CF0\-4D19\-BD05\-DF5E1780AA91]
from the following locations:
.IP \[bu] 2
Platform classes from the runtime image
.IP \[bu] 2
Application classes from the runtime image
.IP \[bu] 2
Application classes from the class path
.IP \[bu] 2
Application classes from the module path
.PP
Archiving application classes provides better start up time at runtime.
When running multiple JVM processes, AppCDS also reduces the runtime
footprint with memory sharing for read\-only metadata.
.PP
CDS/AppCDS supports archiving classes from JAR files only.
.PP
Prior to JDK 11, a non\-empty directory was reported as a fatal error in
the following conditions:
.IP \[bu] 2
For base CDS, a non\-empty directory cannot exist in the
\f[CB]\-Xbootclasspath/a\f[R] path
.IP \[bu] 2
With \f[CB]\-XX:+UseAppCDS\f[R], a non\-empty directory could not exist in
the \f[CB]\-Xbootclasspath/a\f[R] path, class path, and module path.
.PP
In JDK 11 and later, \f[CB]\-XX:+UseAppCDS\f[R] is obsolete and the
behavior for a non\-empty directory is based on the class types in the
classlist.
A non\-empty directory is reported as a fatal error in the following
conditions:
.IP \[bu] 2
If application classes or platform classes are not loaded, dump time
only reports an error if a non\-empty directory exists in
\f[CB]\-Xbootclasspath/a\f[R] path
.IP \[bu] 2
If application classes or platform classes are loaded, dump time reports
an error for a non\-empty directory that exists in
\f[CB]\-Xbootclasspath/a\f[R] path, class path, or module path
.PP
In JDK 11 and later, using
\f[CB]\-XX:DumpLoadedClassList=\f[R]\f[I]class_list_file\f[R] results a
generated classlist with all classes (both system library classes and
application classes) included.
You no longer have to specify \f[CB]\-XX:+UseAppCDS\f[R] with
\f[CB]\-XX:DumpLoadedClassList\f[R] to produce a complete class list.
.PP
In JDK 11 and later, because \f[CB]UseAppCDS\f[R] is obsolete,
\f[CB]SharedArchiveFile\f[R] becomes a product flag by default.
Specifying \f[CB]+UnlockDiagnosticVMOptions\f[R] for
\f[CB]SharedArchiveFile\f[R] is no longer needed in any configuration.
.PP
Class Data Sharing (CDS)/AppCDS does not support archiving array classes
in a class list.
When an array in the class list is encountered, CDS dump time gives the
explicit error message:
.RS
.PP
\f[CB]Preload\ Warning:\ Cannot\ find\f[R] \f[I]array_name\f[R]
.RE
.PP
Although an array in the class list is not allowed, some array classes
can still be created at CDS/AppCDS dump time.
Those arrays are created during the execution of the Java code used by
the Java class loaders (\f[CB]PlatformClassLoader\f[R] and the system
class loader) to load classes at dump time.
The created arrays are archived with the rest of the loaded classes.
.SS Extending Class Data Sharing to Support the Module Path
.PP
In JDK 11, Class Data Sharing (CDS) has been improved to support
archiving classes from the module path.
.IP \[bu] 2
To create a CDS archive using the \f[CB]\-\-module\-path\f[R] VM option,
use the following command line syntax:
.RS 2
.RS
.PP
\f[CB]java\ \-Xshare:dump\ \-XX:SharedClassListFile=\f[R]\f[I]class_list_file\f[R]
\f[CB]\-XX:SharedArchiveFile=\f[R]\f[I]shared_archive_file\f[R]
\f[CB]\-\-module\-path=\f[R]\f[I]path_to_modular_jar\f[R] \f[CB]\-m\f[R]
\f[I]module_name\f[R]
.RE
.RE
.IP \[bu] 2
To run with a CDS archive using the \f[CB]\-\-module\-path\f[R] VM option,
use the following the command line syntax:
.RS 2
.RS
.PP
\f[CB]java\ \-XX:SharedArchiveFile=\f[R]\f[I]shared_archive_file\f[R]
\f[CB]\-\-module\-path=\f[R]\f[I]path_to_modular_jar\f[R] \f[CB]\-m\f[R]
\f[I]module_name\f[R]
.RE
.RE
.PP
The following table describes how the VM options related to module paths
can be used along with the \f[CB]\-Xshare\f[R] option.
.PP
.TS
tab(@);
l l l.
T{
Option
T}@T{
\-Xshare:dump
T}@T{
\-Xshare:{on,auto}
T}
_
T{
\f[CB]\-\-module\-path\f[R][1] \f[I]mp\f[R]
T}@T{
Allowed
T}@T{
Allowed[2]
T}
T{
\f[CB]\-\-module\f[R]
T}@T{
Allowed
T}@T{
Allowed
T}
T{
\f[CB]\-\-add\-module\f[R]
T}@T{
Allowed
T}@T{
Allowed
T}
T{
\f[CB]\-\-upgrade\-module\-path\f[R][3]
T}@T{
Disallowed (exits if specified)
T}@T{
Allowed (disables CDS)
T}
T{
\f[CB]\-\-patch\-module\f[R][4]
T}@T{
Disallowed (exits if specified)
T}@T{
Allowed (disables CDS)
T}
T{
\f[CB]\-\-limit\-modules\f[R][5]
T}@T{
Disallowed (exits if specified)
T}@T{
Allowed (disables CDS)
T}
.TE
.PP
[1] Although there are two ways of specifying a module in a
\f[CB]\-\-module\-path\f[R], that is, modular JAR or exploded module, only
modular JARs are supported.
.PP
[2] Different \f[I]mp\f[R] can be specified during dump time versus run
time.
If an archived class K was loaded from \f[CB]mp1.jar\f[R] at dump time,
but changes in \f[I]mp\f[R] cause it to be available from a different
\f[CB]mp2.jar\f[R] at run time, then the archived version of K will be
disregarded at run time; K will be loaded dynamically.
.PP
[3] Currently, only two system modules are upgradeable
(\f[CB]java.compiler\f[R] and \f[CB]jdk.internal.vm.compiler\f[R]).
However, these modules are seldom upgraded in production software.
.PP
[4] As documented in JEP 261, using \f[CB]\-\-patch\-module\f[R] is
strongly discouraged for production use.
.PP
[5] \f[CB]\-\-limit\-modules\f[R] is intended for testing purposes.
It is seldom used in production software.
.PP
If \f[CB]\-\-upgrade\-module\-path\f[R], \f[CB]\-\-patch\-module\f[R], or
\f[CB]\-\-limit\-modules\f[R] is specified at dump time, an error will be
printed and the JVM will exit.
For example, if the \f[CB]\-\-limit\-modules\f[R] option is specified at
dump time, the user will see the following error:
.IP
.nf
\f[CB]
Error\ occurred\ during\ initialization\ of\ VM
Cannot\ use\ the\ following\ option\ when\ dumping\ the\ shared\ archive:\ \-\-limit\-modules
\f[R]
.fi
.PP
If \f[CB]\-\-upgrade\-module\-path\f[R], \f[CB]\-\-patch\-module\f[R], or
\f[CB]\-\-limit\-modules\f[R] is specified at run time, a warning message
will be printed indicating that CDS is disabled.
For example, if the \f[CB]\-\-limit\-modules\f[R] options is specified at
run time, the user will see the following warning:
.IP
.nf
\f[CB]
Java\ HotSpot(TM)\ 64\-Bit\ Server\ VM\ warning:\ CDS\ is\ disabled\ when\ the\ \-\-limit\-modules\ option\ is\ specified.
\f[R]
.fi
.PP
Several other noteworthy things include:
.IP \[bu] 2
Any valid combinations of \f[CB]\-cp\f[R] and \f[CB]\-\-module\-path\f[R]
are supported.
.IP \[bu] 2
A non\-empty directory in the module path causes a fatal error.
The user will see the following error messages:
.RS 2
.IP
.nf
\f[CB]
Error:\ non\-empty\ directory\ <directory>\ Hint:\ enable\ \-Xlog:class+path=info\ to\ diagnose\ the\ failure\ Error\ occurred\ during\ initialization\ of\ VM\ Cannot\ have\ non\-empty\ directory\ in\ paths
\f[R]
.fi
.RE
.IP \[bu] 2
Unlike the class path, there\[aq]s no restriction that the module path
at dump time must be equal to or be a prefix of the module path at run
time.
.IP \[bu] 2
The archive is invalidated if an existing JAR in the module path is
updated after archive generation.
.IP \[bu] 2
Removing a JAR from the module path does not invalidate the shared
archive.
Archived classes from the removed JAR are not used at runtime.
.SS Dynamic CDS archive
.PP
Dynamic CDS archive extends AppCDS to allow archiving of classes when a
Java application exits.
It improves the usability of AppCDS by eliminating the trial run step
for creating a class list for each application.
The archived classes include all loaded application classes and library
classes that are not present in the default CDS archive which is
included in the JDK.
.PP
A base archive is required when creating a dynamic archive.
If the base archive is not specified, the default CDS archive is used as
the base archive.
.PP
To create a dynamic CDS archive with the default CDS archive as the base
archive, just add the
\f[CB]\-XX:ArchiveClassesAtExit=<dynamic\ archive>\f[R] option to the
command line for running the Java application.
.PP
If the default CDS archive does not exist, the VM will exit with the
following error:
.IP
.nf
\f[CB]
ArchiveClassesAtExit\ not\ supported\ when\ base\ CDS\ archive\ is\ not\ loaded
\f[R]
.fi
.PP
To run the Java application using a dynamic CDS archive, just add the
\f[CB]\-XX:SharedArchiveFile=<dynamic\ archive>\f[R] option to the command
line for running the Java application.
.PP
The base archive is not required to be specified in the command line.
The base archive information, including its name and full path, will be
retrieved from the dynamic archive header.
Note that the user could also use the \f[CB]\-XX:SharedArchiveFile\f[R]
option for specifying a regular AppCDS archive.
Therefore, the specified archive in the \f[CB]\-XX:SharedArchiveFile\f[R]
option could be either a regular or dynamic archive.
During VM start up the specified archive header will be read.
If \f[CB]\-XX:SharedArchiveFile\f[R] refers to a regular archive, then the
behavior will be unchanged.
If \f[CB]\-XX:SharedArchiveFile\f[R] refers to a dynamic archive, the VM
will retrieve the base archive location from the dynamic archive.
If the dynamic archive was created with the default CDS archive, then
the current default CDS archive will be used, and will be found relative
to the current run time environment.
.PP
Please refer to \f[B]JDK\-8221706\f[R]
[https://bugs.openjdk.java.net/browse/JDK\-8221706] for details on error
checking during dynamic CDS archive dump time and run time.
.SS Creating a Shared Archive File and Using It to Run an Application
.SS AppCDS archive
.PP
The following steps create a shared archive file that contains all the
classes used by the \f[CB]test.Hello\f[R] application.
The last step runs the application with the shared archive file.
.IP "1." 3
Create a list of all classes used by the \f[CB]test.Hello\f[R]
application.
The following command creates a file named \f[CB]hello.classlist\f[R] that
contains a list of all classes used by this application:
.RS 4
.RS
.PP
\f[CB]java\ \-Xshare:off\ \-XX:DumpLoadedClassList=hello.classlist\ \-cp\ hello.jar\ test.Hello\f[R]
.RE
.PP
Note that the classpath specified by the \f[CB]\-cp\f[R] parameter must
contain only JAR files.
.RE
.IP "2." 3
Create a shared archive, named \f[CB]hello.jsa\f[R], that contains all the
classes in \f[CB]hello.classlist\f[R]:
.RS 4
.RS
.PP
\f[CB]java\ \-Xshare:dump\ \-XX:SharedArchiveFile=hello.jsa\ \-XX:SharedClassListFile=hello.classlist\ \-cp\ hello.jar\f[R]
.RE
.PP
Note that the classpath used at archive creation time must be the same
as (or a prefix of) the classpath used at run time.
.RE
.IP "3." 3
Run the application \f[CB]test.Hello\f[R] with the shared archive
\f[CB]hello.jsa\f[R]:
.RS 4
.RS
.PP
\f[CB]java\ \-XX:SharedArchiveFile=hello.jsa\ \-cp\ hello.jar\ test.Hello\f[R]
.RE
.RE
.IP "4." 3
\f[B]Optional\f[R] Verify that the \f[CB]test.Hello\f[R] application is
using the class contained in the \f[CB]hello.jsa\f[R] shared archive:
.RS 4
.RS
.PP
\f[CB]java\ \-XX:SharedArchiveFile=hello.jsa\ \-cp\ hello.jar\ \-verbose:class\ test.Hello\f[R]
.RE
.PP
The output of this command should contain the following text:
.IP
.nf
\f[CB]
Loaded\ test.Hello\ from\ shared\ objects\ file\ by\ sun/misc/Launcher$AppClassLoader
\f[R]
.fi
.RE
.SS Dynamic CDS archive
.PP
The following steps create a dynamic CDS archive file that contains the
classes used by the \f[CB]test.Hello\f[R] application and are not included
in the default CDS archive.
The second step runs the application with the dynamic CDS archive.
.IP "1." 3
Create a dynamic CDS archive, named \f[CB]hello.jsa\f[R], that contains
all the classes in \f[CB]hello.jar\f[R] loaded by the application
\f[CB]test.Hello\f[R]:
.RS 4
.RS
.PP
\f[CB]java\ \-XX:ArchiveClassesAtExit=hello.jsa\ \-cp\ hello.jar\ Hello\f[R]
.RE
.PP
Note that the classpath used at archive creation time must be the same
as (or a prefix of) the classpath used at run time.
.RE
.IP "2." 3
Run the application \f[CB]test.Hello\f[R] with the shared archive
\f[CB]hello.jsa\f[R]:
.RS 4
.RS
.PP
\f[CB]java\ \-XX:SharedArchiveFile=hello.jsa\ \-cp\ hello.jar\ test.Hello\f[R]
.RE
.RE
.IP "3." 3
\f[B]Optional\f[R] Repeat step 4 of the previous section to verify that
the \f[CB]test.Hello\f[R] application is using the class contained in the
\f[CB]hello.jsa\f[R] shared archive.
.PP
To automate the above steps 1 and 2, one can write a script such as the
following:
.IP
.nf
\f[CB]
\ \ \ \ ARCHIVE=hello.jsa
\ \ \ \ if\ test\ \-f\ $ARCHIVE;\ then
\ \ \ \ \ \ \ \ FLAG="\-XX:SharedArchiveFile=$ARCHIVE"
\ \ \ \ else
\ \ \ \ \ \ \ \ FLAG="\-XX:ArchiveClassesAtExit=$ARCHIVE"
\ \ \ \ fi
\ \ \ \ $JAVA_HOME/bin/java\ \-cp\ hello.jar\ $FLAG\ test.Hello
\f[R]
.fi
.PP
Like an AppCDS archive, the archive needs to be re\-generated if the
Java version has changed.
The above script could be adjusted to account for the Java version as
follows:
.IP
.nf
\f[CB]
\ \ \ \ ARCHIVE=hello.jsa
\ \ \ \ VERSION=foo.version
\ \ \ \ if\ test\ \-f\ $ARCHIVE\ \-a\ \-f\ $VERSION\ &&\ cmp\ \-s\ $VERSION\ $JAVA_HOME/release;\ then
\ \ \ \ \ \ \ \ FLAG="\-XX:SharedArchiveFile=$ARCHIVE"
\ \ \ \ else
\ \ \ \ \ \ \ \ FLAG="\-XX:ArchiveClassesAtExit=$ARCHIVE"
\ \ \ \ \ \ \ \ cp\ \-f\ $JAVA_HOME/release\ $VERSION
\ \ \ \ fi
\ \ \ \ $JAVA_HOME/bin/java\ \-cp\ hello.jar\ $FLAG\ test.Hello
\f[R]
.fi
.PP
Currently, we don\[aq]t support concurrent dumping operations to the
same CDS archive.
Care should be taken to avoid multiple writers to the same CDS archive.
.PP
The user could also create a dynamic CDS archive with a specific base
archive, e.g.
named as \f[CB]base.jsa\f[R] as follows:
.RS
.PP
\f[CB]java\ \-XX:SharedArchiveFile=base.jsa\ \-XX:ArchiveClassesAtExit=hello.jsa\ \-cp\ hello.jar\ Hello\f[R]
.RE
.PP
To run the application using the dynamic CDS archive \f[CB]hello.jsa\f[R]
and a specific base CDS archive \f[CB]base.jsa\f[R]:
.RS
.PP
\f[CB]java\ \-XX:SharedArchiveFile=base.jsa:hello.jsa\ \-cp\ hello.jar\ Hello\f[R]
.RE
.PP
Note that on Windows, the above path delimiter \f[CB]:\f[R] should be
replaced with \f[CB];\f[R].
.PP
The above command for specifying a base archive 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.
.SS Sharing a Shared Archive Across Multiple Application Processes
.PP
You can share the same archive file across multiple applications
processes.
This reduces memory usage because the archive is memory\-mapped into the
address space of the processes.
The operating system automatically shares the read\-only pages across
these processes.
.PP
The following steps demonstrate how to create a common archive that can
be shared by different applications.
Classes from \f[CB]common.jar\f[R], \f[CB]hello.jar\f[R] and \f[CB]hi.jar\f[R]
are archived in the \f[CB]common.jsa\f[R] because they are all in the
classpath during the archiving step (step 3).
.PP
To include classes from \f[CB]hello.jar\f[R] and \f[CB]hi.jar\f[R], the
\f[CB]\&.jar\f[R] files must be added to the classpath specified by the
\f[CB]\-cp\f[R] parameter.
.IP "1." 3
Create a list of all classes used by the \f[CB]Hello\f[R] application and
another list for the \f[CB]Hi\f[R] application:
.RS 4
.RS
.PP
\f[CB]java\ \-XX:DumpLoadedClassList=hello.classlist\ \-cp\ common.jar:hello.jar\ Hello\f[R]
.RE
.RS
.PP
\f[CB]java\ \-XX:DumpLoadedClassList=hi.classlist\ \-cp\ common.jar:hi.jar\ Hi\f[R]
.RE
.RE
.IP "2." 3
Create a single list of classes used by all the applications that will
share the shared archive file.
.RS 4
.PP
\f[B]Linux and macOS\f[R] The following commands combine the files
\f[CB]hello.classlist\f[R] and \f[CB]hi.classlist\f[R] into one file,
\f[CB]common.classlist\f[R]:
.RS
.PP
\f[CB]cat\ hello.classlist\ hi.classlist\ >\ common.classlist\f[R]
.RE
.PP
\f[B]Windows\f[R] The following commands combine the files
\f[CB]hello.classlist\f[R] and \f[CB]hi.classlist\f[R] into one file,
\f[CB]common.classlist\f[R]:
.RS
.PP
\f[CB]type\ hello.classlist\ hi.classlist\ >\ common.classlist\f[R]
.RE
.RE
.IP "3." 3
Create a shared archive named \f[CB]common.jsa\f[R] that contains all the
classes in \f[CB]common.classlist\f[R]:
.RS 4
.RS
.PP
\f[CB]java\ \-Xshare:dump\ \-XX:SharedArchiveFile=common.jsa\ \-XX:SharedClassListFile=common.classlist\ \-cp\ common.jar:hello.jar:hi.jar\f[R]
.RE
.PP
The classpath parameter used is the common class path prefix shared by
the \f[CB]Hello\f[R] and \f[CB]Hi\f[R] applications.
.RE
.IP "4." 3
Run the \f[CB]Hello\f[R] and \f[CB]Hi\f[R] applications with the same shared
archive:
.RS 4
.RS
.PP
\f[CB]java\ \-XX:SharedArchiveFile=common.jsa\ \-cp\ common.jar:hello.jar:hi.jar\ Hello\f[R]
.RE
.RS
.PP
\f[CB]java\ \-XX:SharedArchiveFile=common.jsa\ \-cp\ common.jar:hello.jar:hi.jar\ Hi\f[R]
.RE
.RE
.SS Specifying Additional Shared Data Added to an Archive File
.PP
The \f[CB]SharedArchiveConfigFile\f[R] option is used to specify
additional shared data to add to the archive file.
.RS
.PP
\f[CB]\-XX:SharedArchiveConfigFile=\f[R]\f[I]shared_config_file\f[R]
.RE
.PP
JDK 9 and later supports adding both symbols and string objects to an
archive for memory sharing when you have multiple JVM processes running
on the same host.
An example of this is having multiple JVM processes that use the same
set of Java EE classes.
When these common classes are loaded and used, new symbols and strings
may be created and added to the JVM\[aq]s internal "symbol" and "string"
tables.
At runtime, the symbols or string objects mapped from the archive file
can be shared across multiple JVM processes, resulting in a reduction of
overall memory usage.
In addition, archiving strings also provides added performance benefits
in both startup time and runtime execution.
.PP
In JDK 10 and later, CONSTANT_String entries in archived classes are
resolved to interned String objects at dump time, and all interned
String objects are archived.
However, even though all CONSTANT_String literals in all archived
classes are resolved, it might still beneficial to add additional
strings that are not string literals in class files, but are likely to
be used by your application at run time.
.PP
Symbol data should be generated by the \f[CB]jcmd\f[R] tool attaching to a
running JVM process.
See \f[B]jcmd\f[R].
.PP
The following is an example of the symbol dumping command in
\f[CB]jcmd\f[R]:
.RS
.PP
\f[CB]jcmd\f[R] \f[I]pid\f[R] \f[CB]VM.symboltable\ \-verbose\f[R]
.RE
.RS
.PP
\f[B]Note:\f[R] The first line (process ID) and the second line
(\f[CB]\@VERSION\ ...\f[R]) of this \f[CB]jcmd\f[R] output should be
excluded from the configuration file.
.RE
.SS Example of a Configuration File
.PP
The following is an example of a configuration file:
.IP
.nf
\f[CB]
VERSION:\ 1.0
\@SECTION:\ Symbol
10\ \-1:\ linkMethod
\f[R]
.fi
.PP
In the configuration file example, the \f[CB]\@SECTION:\ Symbol\f[R] entry
uses the following format:
.RS
.PP
\f[I]length\f[R] \f[I]refcount\f[R]\f[CB]:\f[R] \f[I]symbol\f[R]
.RE
.PP
The \f[I]refcount\f[R] for a shared symbol is always \f[CB]\-1\f[R].
.PP
\f[CB]\@SECTION\f[R] specifies the type of the section that follows it.
All data within the section must be the same type that\[aq]s specified
by \f[CB]\@SECTION\f[R].
Different types of data can\[aq]t be mixed.
Multiple separated data sections for the same type specified by
different \f[CB]\@SECTION\f[R] are allowed within one
\f[CB]shared_config_file\f[R] .
.SH PERFORMANCE TUNING EXAMPLES
.PP
You can use the Java advanced runtime options to optimize the
performance of your applications.
.SS Tuning for Higher Throughput
.PP
Use the following commands and advanced options to achieve higher
throughput performance for your application:
.RS
.PP
\f[CB]java\ \-server\ \-XX:+UseParallelGC\ \-XX:+UseLargePages\ \-Xmn10g\ \ \-Xms26g\ \-Xmx26g\f[R]
.RE
.SS Tuning for Lower Response Time
.PP
Use the following commands and advanced options to achieve lower
response times for your application:
.RS
.PP
\f[CB]java\ \-XX:+UseG1GC\ \-XX:MaxGCPauseMillis=100\f[R]
.RE
.SS Keeping the Java Heap Small and Reducing the Dynamic Footprint of
Embedded Applications
.PP
Use the following advanced runtime options to keep the Java heap small
and reduce the dynamic footprint of embedded applications:
.RS
.PP
\f[CB]\-XX:MaxHeapFreeRatio=10\ \-XX:MinHeapFreeRatio=5\f[R]
.RE
.RS
.PP
\f[B]Note:\f[R] The defaults for these two options are 70% and 40%
respectively.
Because performance sacrifices can occur when using these small
settings, you should optimize for a small footprint by reducing these
settings as much as possible without introducing unacceptable
performance degradation.
.RE
.SH EXIT STATUS
.PP
The following exit values are typically returned by the launcher when
the launcher is called with the wrong arguments, serious errors, or
exceptions thrown by the JVM.
However, a Java application may choose to return any value by using the
API call \f[CB]System.exit(exitValue)\f[R].
The values are:
.IP \[bu] 2
\f[CB]0\f[R]: Successful completion
.IP \[bu] 2
\f[CB]>0\f[R]: An error occurred