java.1

.TP
.B \f[CB]\-Xlog:gc,safepoint\f[R]
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) stores classes used by your
applications in an archive file.
Since these classes are stored in a format that can be loaded very
quickly (compared to classes stored in a JAR file), AppCDS can improve
the start\-up time of your applications.
In addition, AppCDS can reduce the runtime memory footprint by sharing
parts of these classes across multiple processes.
.PP
Classes in the CDS archive are stored in an optimized format that\[aq]s
about 2 to 5 times larger than classes stored in JAR files or the JDK
runtime image.
Therefore, it\[aq]s a good idea to archive only those classes that are
actually used by your application.
These usually are just a small portion of all available classes.
For example, your application may use only a few APIs provided by a
large library.
.SS Using CDS Archives
.PP
By default, in most JDK distributions, unless \f[CB]\-Xshare:off\f[R] is
specified, the JVM starts up with a default CDS archive, which is
usually located in \f[CB]JAVA_HOME/lib/server/classes.jsa\f[R] (or
\f[CB]JAVA_HOME\\bin\\server\\classes.jsa\f[R] on Windows).
This archive contains about 1300 core library classes that are used by
most applications.
.PP
To use CDS for the exact set of classes used by your application, you
can use the \f[CB]\-XX:SharedArchiveFile\f[R] option, which has the
general form:
.RS
.PP
\f[CB]\-XX:SharedArchiveFile=<static_archive>:<dynamic_archive>\f[R]
.RE
.IP \[bu] 2
The \f[CB]<static_archive>\f[R] overrides the default CDS archive.
.IP \[bu] 2
The \f[CB]<dynamic_archive>\f[R] provides additional classes that can be
loaded on top of those in the \f[CB]<static_archive>\f[R].
.IP \[bu] 2
On Windows, the above path delimiter \f[CB]:\f[R] should be replaced with
\f[CB];\f[R]
.PP
(The names "static" and "dyanmic" are used for historical reasons.
The only significance is that the "static" archive is loaded first and
the "dynamic" archive is loaded second).
.PP
The JVM can use up to two archives.
To use only a single \f[CB]<static_archive>\f[R], you can omit the
\f[CB]<dynamic_archive>\f[R] portion:
.RS
.PP
\f[CB]\-XX:SharedArchiveFile=<static_archive>\f[R]
.RE
.PP
For convenience, the \f[CB]<dynamic_archive>\f[R] records the location of
the \f[CB]<static_archive>\f[R].
Therefore, you can omit the \f[CB]<static_archive>\f[R] by saying only:
.RS
.PP
\f[CB]\-XX:SharedArchiveFile=<dynamic_archive>\f[R]
.RE
.SS Creating CDS Archives
.PP
CDS archives can be created with several methods:
.IP \[bu] 2
\f[CB]\-Xshare:dump\f[R]
.IP \[bu] 2
\f[CB]\-XX:ArchiveClassesAtExit\f[R]
.IP \[bu] 2
\f[CB]jcmd\ VM.cds\f[R]
.PP
One common operation in all these methods is a "trial run", where you
run the application once to determine the classes that should be stored
in the archive.
.SS Creating a Static CDS Archive File with \-Xshare:dump
.PP
The following steps create a static CDS archive file that contains all
the classes used by the \f[CB]test.Hello\f[R] application.
.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
The classpath specified by the \f[CB]\-cp\f[R] parameter must contain only
JAR files.
.RE
.IP "2." 3
Create a static 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
.RE
.IP "3." 3
Run the application \f[CB]test.Hello\f[R] with the 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\ \-Xlog:class+load\ test.Hello\f[R]
.RE
.PP
The output of this command should contain the following text:
.RS
.PP
\f[CB][info][class,load]\ test.Hello\ source:\ shared\ objects\ file\f[R]
.RE
.RE
.SS Creating a Dynamic CDS Archive File with \-XX:SharedArchiveFile
.PP
Advantages of dynamic CDS archives are:
.IP \[bu] 2
They usually use less disk space, since they don\[aq]t need to store the
classes that are already in the static archive.
.IP \[bu] 2
They are created with one fewer step than the comparable static archive.
.PP
The following steps create a dynamic CDS archive file that contains the
classes that are used by the \f[CB]test.Hello\f[R] application, excluding
those that are already in the default 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
.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
It\[aq]s also possible to create a dynamic CDS archive with a
non\-default static CDS archive.
E.g.,
.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 this dynamic CDS archive:
.RS
.PP
\f[CB]java\ \-XX:SharedArchiveFile=base.jsa:hello.jsa\ \-cp\ hello.jar\ Hello\f[R]
.RE
.PP
(On Windows, the above path delimiter \f[CB]:\f[R] should be replaced with
\f[CB];\f[R])
.PP
As mention above, the name of the static archive can be skipped:
.RS
.PP
\f[CB]java\ \-XX:SharedArchiveFile=hello.jsa\ \-cp\ hello.jar\ Hello\f[R]
.RE
.SS Creating CDS Archive Files with jcmd
.PP
The previous two sections require you to modify the application\[aq]s
start\-up script in order to create a CDS archive.
Sometimes this could be difficult, for example, if the application\[aq]s
class path is set up by complex routines.
.PP
The \f[CB]jcmd\ VM.cds\f[R] command provides a less intrusive way for
creating a CDS archive by connecting to a running JVM process.
You can create either a static:
.RS
.PP
\f[CB]jcmd\ <pid>\ VM.cds\ static_dump\ my_static_archive.jsa\f[R]
.RE
.PP
or a dynamic archive:
.RS
.PP
\f[CB]jcmd\ <pid>\ VM.cds\ dynamic_dump\ my_dynamic_archive.jsa\f[R]
.RE
.PP
To use the resulting archive file in a subsequent run of the application
without modifying the application\[aq]s start\-up script, you can use
the following technique:
.RS
.PP
\f[CB]env\ JAVA_TOOL_OPTIONS=\-XX:SharedArchiveFile=my_static_archive.jsa\ bash\ app_start.sh\f[R]
.RE
.PP
Note: to use \f[CB]jcmd\ <pid>\ VM.cds\ dynamic_dump\f[R], the JVM process
identified by \f[CB]<pid>\f[R] must be started with
\f[CB]\-XX:+RecordDynamicDumpInfo\f[R], which can also be passed to the
application start\-up script with the same technique:
.RS
.PP
\f[CB]env\ JAVA_TOOL_OPTIONS=\-XX:+RecordDynamicDumpInfo\ bash\ app_start.sh\f[R]
.RE
.SS Restrictions on Class Path and Module Path
.IP \[bu] 2
Neither the class path (\f[CB]\-classpath\f[R] and
\f[CB]\-Xbootclasspath/a\f[R]) nor the module path
(\f[CB]\-\-module\-path\f[R]) can contain non\-empty directories.
.IP \[bu] 2
Only modular JAR files are supported in \f[CB]\-\-module\-path\f[R].
Exploded modules are not supported.
.IP \[bu] 2
The class path used at archive creation time must be the same as (or a
prefix of) the class path used at run time.
(There\[aq]s no such requirement for the module path.)
.IP \[bu] 2
The CDS archive cannot be loaded if any JAR files in the class path or
module path are modified after the archive is generated.
.IP \[bu] 2
If any of the VM options \f[CB]\-\-upgrade\-module\-path\f[R],
\f[CB]\-\-patch\-module\f[R] or \f[CB]\-\-limit\-modules\f[R] are specified,
CDS is disabled.
This means that the JVM will execute without loading any CDS archives.
In addition, if you try to create a CDS archive with any of these 3
options specified, the JVM will report an error.
.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