IBM 64-bit SDK for AIX platforms, Java Technology Edition
SDK Guide
Version 5 Release 0This documentation applies to IBM 64-bit SDK for AIX, v5.0 releases before SR 13. For new or changed information about IBM 64-bit SDK for AIX, v5.0 SR 13 and newer, see IBM 64-bit SDK for AIX, v5.0: Current news.
Before using this information and the product it supports, read the information in Notices.
This edition of the user guide applies to the IBM 64-bit SDK for AIX, Java 2 Technology Edition, Version 5.0, and to all subsequent releases, modifications, and Service Refreshes, until otherwise indicated in new editions.
© Copyright 1997, 2011, Oracle and/or its affiliates. All rights reserved.
US Government Users Restricted Rights -- Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
Contents
Preface
This user guide provides general information about the IBM® 64-bit SDK for AIX®, Java 2 Technology Edition, Version 5.0. The user guide gives specific information about any differences in the IBM implementation compared with the Oracle implementation.
Read this user guide with the more extensive documentation on the Oracle Web site: http://www.oracle.com/technetwork/java/index.html.
Useful Web sites include:
The Diagnostics Guide provides more detailed information about the IBM Virtual Machine for Java.
This user guide is part of a release and is applicable only to that particular release. Make sure that you have the user guide appropriate to the release you are using.
The terms "Runtime Environment" and "Java Virtual Machine" are used interchangeably throughout this user guide.
Technical changes made for this version
of the user guide, other than minor or obvious
ones, are indicated by blue chevrons when viewing in an Information
Center, by blue chevrons and in red when viewing in HTML, or by vertical
bars to the left of the changes when viewing as a PDF file.
The Program Code is not designed or intended for use in real-time applications such as (but not limited to) the online control of aircraft, air traffic, aircraft navigation, or aircraft communications; or in the design, construction, operation, or maintenance of any nuclear facility.
Overview
The IBM SDK is a development environment for writing and running applets and applications that conform to the Java 5.0 Core Application Program Interface (API).
Version compatibility
In general, any applet or application that ran with a previous version of the SDK should run correctly with the IBM 64-bit SDK for AIX, v5.0. Classes compiled with this release are not guaranteed to work on previous releases.
For information about compatibility issues between releases, see the Oracle Web site at:
http://www.oracle.com/technetwork/java/javase/compatibility-137462.html
http://www.oracle.com/technetwork/java/javase/compatibility-j2se1-141394.html
http://www.oracle.com/technetwork/java/javase/compatibility-135119.html
If you are using the SDK as part of another product (for example, IBM WebSphere® Application Server), and you upgrade from a previous level of the SDK, perhaps v1.4.2, serialized classes might not be compatible. However, classes are compatible between service refreshes.
Migrating from other IBM JVMs
From Version 5.0, the IBM Runtime Environment for AIX contains a new version of the IBM Virtual Machine for Java and the Just-In-Time (JIT) compiler.
If you are migrating from an older IBM Runtime Environment, note that:
- To remain compatible with Version 1.4.2, the JVM shared library libjvm.a is installed in both jre/bin/j9vm and jre/bin/classic. Set the LIBPATH environment variable to use the JVM shared library in jre/bin/classic when writing native applications using the JNI invocation interface.
- The JVM Monitoring Interface (JVMMI) is no longer available. You must rewrite applications that used that API. You are recommended to use the JVM Tool Interface (JVMTI) instead. The JVMTI is not functionally the equivalent of JVMMI. For information about JVMTI, see http://download.oracle.com/javase/1.5.0/docs/guide/jvmti/ and the Diagnostics Guide.
- The new implementation of JNI conforms to the JNI specification, but differs from the old implementation. It returns copies of objects rather than pinning the objects. This difference can expose errors in JNI application code. For information about debugging JNI code, see -Xcheck:jni in JVM command-line options.
- The format and content of garbage collector verbose logs obtained using -verbose:gc have changed. The data is now formatted as XML. The data content reflects the changes to the implementation of garbage collection in the JVM, and most of the statistics that are produced have changed. You must change any programs that process the verbose GC data to make them work with the new format and data. See the Diagnostics Guide for an example of the new verbose GC data.
- SDK 1.4 versions of the IBM JRE included JVM specific classes in a file called core.jar. From Java 5.0 onwards, these are included in a file called vm.jar.
- Earlier versions of the IBM JRE included a file called rt.jar in the jre/lib directory. From Java v1.4 onwards, this file has been replaced by multiple JAR files in the jre/lib directory.
- For additional industry compatibility information, see Oracle's Java 5 Compatibility Documentation: http://www.oracle.com/technetwork/java/javase/compatibility-137462.html
- For additional deprecated API information, see Oracle's Java 5 Deprecated API List: http://download.oracle.com/javase/1.5.0/docs/api/deprecated-list.html
- Tracing class dependencies, started using -verbose:Xclassdep, is not supported. If you specify -verbose:Xclassdep, the JVM will issue an error message and will not start.
- The JVM detects the operating system locale and sets the language preferences accordingly. For example, if the locale is set to fr_FR, JVM messages will be printed in French. To avoid seeing JVM messages in the language of the detected locale, remove the file $SDK/jre/bin/java_xx.properties where xx is the locale, such as fr, and the JVM will print messages in English.
Supported environments
The IBM 64-bit SDK for AIX, v5.0 is supported on certain hardware platforms and operating systems, and is tested on specific virtualization environments.
Hardware platform
The SDK runs on hardware that supports the IBM POWER® architecture. For specific information about IBM POWER 7 support, see https://www.ibm.com/developerworks/java/jdk/power7/index.html.
The SDK also runs on older System p® systems that have a Common Hardware Reference Platform (CHRP) architecture. To test whether the SDK is supported on a specific System p system, at the system prompt type:
lscfg -p | fgrep Architecture
The output for a supported platform reads:
Model Architecture: chrp
Operating system
The following table details the operating system supported for the IBM 64-bit SDK for AIX, v5.0. The table indicates whether support for an operating system release was included at the "general availability" (GA) date for the SDK, or at a specific service refresh (SR) level.
Operating system | SDK release supported | Comments |
---|---|---|
AIX 5.2.0.75 | GA | Operating system no longer supported. |
AIX 5.3.0.30 | GA | |
AIX 6.1.0.0 | SR6 | |
AIX 7.1.0.0 |
The latest service details and resources can be found here:http://www.ibm.com/developerworks/java/jdk/aix/service.html.
Virtualization software
For information about the virtualization software tested for IBM 64-bit SDK for AIX, v5.0, see Appendix D. Support for virtualization software.
Additional information for AIX
Important information for IBM 64-bit SDK for AIX, Java 2 Technology Edition, Version 5.0.
AIX APARs required for IBM 64-bit SDK for AIX, v5.0.
To avoid problems when using Java, ensure that you have these AIX APARs installed:
AIX version | APAR number |
---|---|
5.3.8.0 | IZ69616, IZ70703 |
5.3.9.0 | IZ66710, IZ69194 |
5.3.10.0 | IZ66709, IZ68763 |
5.3.11.0 | IZ65427, IZ68372 |
5.3.12.0 | IZ73928 |
6.1.2.10 | IZ84087 |
6.1.3.7 | IZ83815 |
6.1.4.0 | IZ65501 |
6.1.4.7 | IZ84055 |
6.1.5.0 | IZ73931 |
6.1.5.4 | IZ83856 |
6.1.6.0 | IZ81170 |
6.1.6.15 | IZ81962 |
7.1.0.15 | IZ86109 |
Environment variables
The environment variable LDR_CNTRL=MAXDATA is not supported for 64-bit processes. Use LDR_CNTRL=MAXDATA only on 32-bit processes.
Use of non-UTF8 CJK locales
If you are using one of the supported non-UTF8 CJK locales, you must install one of these file sets.
X11.fnt.ucs.ttf (for ja_JP or Ja_JP) X11.fnt.ucs.ttf_CN (for zh_CN or Zh_CN) X11.fnt.ucs.ttf_KR (for ko_KR) X11.fnt.ucs.ttf_TW (for zh_TW or Zh_TW)
Contents of the SDK and Runtime Environment
The SDK contains several development tools and a Java Runtime Environment (JRE). This section describes the contents of the SDK tools and the Runtime Environment.
Applications written entirely in Java must have no dependencies on the IBM SDK's directory structure (or files in those directories). Any dependency on the SDK's directory structure (or the files in those directories) might result in application portability problems.
The documentation package is designed to be extracted into the SDK software installation directory. If you download the compressed version, be sure to preserve the path names when you extract the files from the archive.
Contents of the Runtime Environment
A list of classes, tools, and other files that you can use with the standard Runtime Environment.
- Core Classes - These classes are the compiled class files for the platform and must remain compressed for the compiler and interpreter to access them. Do not modify these classes; instead, create subclasses and override where you need to.
- Trusted root certificates from certificate signing authorities - These certificates are used to validate the identity of signed material.
- JRE tools - The following tools are part of the Runtime Environment and are in the /usr/java5_64/jre/bin directory unless
otherwise specified.
- ControlPanel (Java Control Panel)
- Configures your Runtime Environment.
- ikeyman (iKeyman GUI utility)
- Allows you to manage keys, certificates, and certificate requests. For more information see the accompanying Security Guide and http://public.dhe.ibm.com/software/dw/jdk/security/50/GSK7c_SSL_IKM_Guide.pdf. The SDK also provides a command-line version of this utility.
- java (Java Interpreter)
- Runs Java classes. The Java Interpreter runs programs that are written in the Java programming language.
- javaw (Java Interpreter)
- Runs Java classes in the same way as the java command does, but does not use a console window.
- jextract (Dump extractor)
- Converts a system-produced dump into a common format that can be used by jdmpview. For more information, see jdmpview.
- keytool (Key and Certificate Management Tool)
- Manages a keystore (database) of private keys and their associated X.509 certificate chains that authenticate the corresponding public keys.
- policytool (Policy File Creation and Management Tool)
- Creates and modifies the external policy configuration files that define your installation's Java security policy.
- rmid (RMI activation system daemon)
- Starts the activation system daemon so that objects can be registered and activated in a Java virtual machine (JVM).
- rmiregistry (Java remote object registry)
- Creates and starts a remote object registry on the specified port of the current host.
- tnameserv (Common Object Request Broker Architecture (CORBA) transient naming service)
- Starts the CORBA transient naming service.
Contents of the SDK
A list of tools and reference information that is included with the standard SDK.
- The following tools are part of the SDK and are located in the /usr/java5_64/bin directory:
-
- appletviewer (Java Applet Viewer)
- Tests and runs applets outside a Web browser.
- apt (Annotation Processing Tool)
- Finds and executes annotation processors based on the annotations present in the set of specified source files being examined.
- extcheck (Extcheck utility)
- Detects version conflicts between a target jar file and currently-installed extension jar files.
- idlj (IDL to Java Compiler)
- Generates Java bindings from a given IDL file.
- jar (Java Archive Tool)
- Combines multiple files into a single Java Archive (JAR) file.
- jarsigner (JAR Signing and Verification Tool)
- Generates signatures for JAR files and verifies the signatures of signed JAR files.
- javac (Java Compiler)
- Compiles programs that are written in the Java programming language into bytecodes (compiled Java code).
- javadoc (Java Documentation Generator)
- Generates HTML pages of API documentation from Java source files.
- javah (C Header and Stub File Generator)
- Enables you to associate native methods with code written in the Java programming language.
- javap (Class File Disassembler)
- Disassembles compiled files and can print a representation of the bytecodes.
- jconsole (JConsole Monitoring and Management Tool)
- Experimental (unsupported). Monitors local and remote JVMs using a GUI. JMX-compliant.
- jdb (Java Debugger)
- Helps debug your Java programs.
- jdmpview (Cross-platform dump formatter)
- Analyzes dumps. For more information, see the Diagnostics Guide.
- native2ascii (Native-To-ASCII Converter)
- Converts a native encoding file to an ASCII file that contains characters encoded in either Latin-1 or Unicode, or both.
- rmic (Java Remote Method Invocation (RMI) Stub Converter)
- Generates stubs, skeletons, and ties for remote objects. Includes RMI over Internet Inter-ORB Protocol (RMI-IIOP) support.
- serialver (Serial Version Command)
- Returns the serialVersionUID for one or more classes in a format that is suitable for copying into an evolving class.
- Include Files
- C headers for JNI programs.
- User Guide
- This file.
- copyright
- The copyright notice for the SDK for AIX software.
- License
-
The License file, /usr/swlag/<locale>/Java5_64.la, contains the license agreement for the SDK for AIX software (where <locale> is the name of your locale, for example en). To view or print the license agreement, open the file in a Web browser.
- fixes.lst
- A text file that describes any defects that are fixed after the initial release of this version.
Installing and configuring the SDK and Runtime Environment
The IBM 64-bit SDK for AIX, v5.0 complete release consists of several installp image files (packages). Each installp image file or package contains one or more related filesets. You can install the packages using the smit or smitty system management tools. Alternatively, you can use the installp command.
This package is required:
- Java5_64.sdk (license, base SDK and dt.jar)
These packages are optional:
- Java5_64.ext (Comm API)
- Java5_64.samples (demos)
- Java5_64.source (src.jar)
- Java5_64.msg.$LANG (Localized messages)
$LANG is one of the following locales. These packages do not include any files but pull in required Unicode TrueType fonts, if not already installed, for these locales:
- Zh_CN
- zh_CN
- ko_KR
- Ja_JP
- ja_JP
- Zh_TW
- zh_TW
The SDK is installed in the directory:
/usr/java5_64/
The following user-configurable files are installed to /etc/java5_64/ to support a configuration where the files are not shared:
- jre/lib/jaxp.properties
- jre/lib/logging.properties
- jre/lib/management/jmxremote.access
- jre/lib/management/jmxremote.password.template
- jre/lib/management/management.properties
- jre/lib/management/snmp.acl
- jre/lib/management/snmp.acl.template
- jre/lib/security/java.policy
- jre/lib/security/java.security
- jre/lib/xalan.properties
- jre/lib/xerces.properties
There are symbolic links in /usr/java5_64/ pointing to the files in /etc/java5_64/.
Relocating an installp package
By default, the SDK is installed in /usr/java5_64/. To install the SDK in another directory, use the AIX relocation commands. This feature is supported from IBM SDK for Java Version 5, SR 7 onwards.
Delete any .toc files in the directory containing your installp images or PTFs before using the AIX relocation commands.
Commands
See the AIX man pages for more information about the command-line options for these commands.
- installp_r
- Install the SDK:
installp_r -a -Y -R /<Install Path>/ -d '.' Java5_64.sdk
Remove the SDK:installp_r -u -R /<Install Path>/ Java5_64.sdk
- lsusil
- List the user-defined installation paths.
lsusil
- lslpp_r
- Find details of installed products.
lslpp_r -R /<Install Path>/ -S [A|O]
- rmusil
- Remove existing user-defined installation paths.
rmusil -R /<Install Path>/
Upgrading the SDK
If you are upgrading the SDK from a previous release, back up all the configuration files and security policy files before you start the upgrade.
What to do next
After the upgrade, you might have to restore or reconfigure these files because they might have been overwritten during the upgrade process. Check the syntax of the new files before restoring the original files because the format or options for the files might have changed.
Verification
Before you begin
To help ensure that the verification process behaves consistently, first:
unset LIBPATH unset CLASSPATH unset JAVA_COMPILER unset JAVA_HOME export PATH=/usr/java5_64/jre/bin:/usr/java5_64/bin:$PATH
About this task
When you issue the command:
java -version
you see output like the following messages:
java version "1.5.0" Java(TM) 2 Runtime Environment, Standard Edition (build pap64dev-20051104)
where dates, times, and specific build numbers might be different.
What to do next
When verification is complete, log on again and review for possible conflicts arising from values that you assigned to these variables.
Setting the path
If you alter the PATH environment variable, you will override any existing Java launchers in your path.
About this task
The PATH environment variable enables AIX to find programs and utilities, such as javac, java, and javadoc tool, from any current directory. To display the current value of your PATH, type the following at a command prompt:
echo $PATH
To add the Java launchers to your path:
- Edit the shell startup file in your home directory (typically
.bashrc, depending on your shell) and add the absolute paths to the PATH environment
variable; for example:
export PATH=/usr/java5_64/bin: /usr/java5_64/jre/bin:$PATH
- Log on again or run the updated shell script to activate the new PATH environment variable.
Results
After setting the path, you can run a tool by typing its name at a command prompt from any directory. For example, to compile the file Myfile.Java, at a command prompt, type:
javac Myfile.Java
Setting the class path
The class path tells the SDK tools, such as java, javac, and the javadoc tool, where to find the Java class libraries.
About this task
You should set the class path explicitly only if:
- You require a different library or class file, such as one that you develop, and it is not in the current directory.
- You change the location of the bin and lib directories and they no longer have the same parent directory.
- You plan to develop or run applications using different runtime environments on the same system.
To display the current value of your CLASSPATH environment variable, type the following command at a shell prompt:
echo $CLASSPATH
If you develop and run applications that use different runtime environments, including other versions that you have installed separately, you must set the CLASSPATH and PATH explicitly for each application. If you run multiple applications simultaneously and use different runtime environments, each application must run in its own shell prompt.
Updating your SDK or JRE for daylight saving time changes
You can apply recent changes to daylight saving time using the IBM Time Zone Update Utility for Java (JTZU).
About this task
Many countries around the world use a daylight saving time (DST) convention. Typically, clocks move forward by one hour during the summer months to create more daylight hours during the afternoon and less during the morning. This practice has many implications, including the need to adjust system clocks in computer systems. Occasionally, countries change their DST start and end dates. These changes can affect the date and time functions in applications, because the original start and end dates are programmed into the operating system and in Java software. To avoid this problem you must update operating systems and Java installations with the new DST information.
The Olson time zone database is an external resource that compiles information about the time zones around the world. This database establishes standard names for time zones, such as "America/New_York", and provides regular updates to time zone information that can be used as reference data. To ensure that Java JREs and SDKs contain up to date DST information, IBM incorporates the latest Olson update into each Java service refresh. To find out which Olson time zone update is included for a particular service refresh, see https://www.ibm.com/developerworks/java/jdk/dst/olson_table.html.
If a DST change has been introduced since the last service refresh, you can use JTZU to directly update your Java installation. You can also use this tool to update your installation if you are unable to move straight to the latest service refresh. JTZU is available from IBM developerWorks® using the following link: https://www.ibm.com/developerworks/java/jdk/dst/jtzu.html.
Results
After updating your Java installation with any recent DST changes, your application can handle time and date calculations correctly.
Running Java applications
Java applications can be started using the java launcher or through JNI. Settings are passed to a Java application using command-line arguments, environment variables, and properties files.
The java and javaw commands
An overview of the java and javaw commands.
Purpose
The java and javaw tools start a Java application by starting a Java Runtime Environment and loading a specified class.
The javaw command is identical to java, except that javaw has no associated console window. Use javaw when you do not want a command prompt window to be displayed. The javaw launcher displays a window with error information if it fails.
Usage
The JVM searches for the initial class (and other classes that are used) in three sets of locations: the bootstrap class path, the installed extensions, and the user class path. The arguments that you specify after the class name or jar file name are passed to the main function.
The java and javaw commands have the following syntax:
java [ options ] <class> [ arguments ... ] java [ options ] -jar <file.jar> [ arguments ... ] javaw [ options ] <class> [ arguments ... ] javaw [ options ] -jar <file.jar> [ arguments ... ]
Parameters
- [options]
- Command-line options to be passed to the runtime environment.
- <class>
- Startup class. The class must contain a main() method.
- <file.jar>
- Name of the jar file to start. It is used only with the -jar option. The named jar file must contain class and resource files for the application, with the startup class indicated by the Main-Class manifest header.
- [arguments ...]
- Command-line arguments to be passed to the main() function of the startup class.
Obtaining version information
You obtain the IBM build and version number for your Java installation using the -version option.
Procedure
- Open a shell prompt.
- Type the following command:
java -version
You will see information similar to:java version "1.5.0" Java(TM) 2 Runtime Environment, Standard Edition (build pxi32dev-20051104) IBM J9 VM (build 2.3, J2RE 1.5.0 IBM J9 2.3 Linux x86-32 j9vmxi3223-20051103 (JIT enabled) J9VM - 20051027_03723_lHdSMR JIT - 20051027_1437_r8 GC - 20051020_AA) JCL - 20051102
Exact build dates and versions will change.
Specifying Java options and system properties
You can specify Java options and system properties on the command line, by using an options file, or by using an environment variable.
About this task
These methods of specifying Java options are listed in order of precedence. Rightmost options on the command line have precedence over leftmost options; for example, if you specify:
java -Xint -Xjit myClass
The -Xjit option takes precedence.
Procedure
- By specifying the option or property on the command line. For example:
java -Dmysysprop1=tcpip -Dmysysprop2=wait -Xdisablejavadump MyJavaClass
- By creating a file that contains the options, and specifying it on the command line using -Xoptionsfile=<file>.
- By creating an environment variable called IBM_JAVA_OPTIONS containing
the options. For example:
export IBM_JAVA_OPTIONS="-Dmysysprop1=tcpip -Dmysysprop2=wait -Xdisablejavadump"
Standard options
The definitions for the standard options.
See JVM command-line options for information about nonstandard (-X) options.
- -agentlib:<libname>[=<options>]
- Loads a native agent library <libname>; for example -agentlib:hprof. For more information, specify -agentlib:jdwp=help and -agentlib:hprof=help on the command line.
- -agentpath:libname[=<options>]
- Loads a native agent library by full path name.
- -assert
- Prints help on assert-related options.
- -cp <directories and .zip or .jar files separated by :>
- Sets the search path for application classes and resources. If -classpath and -cp are not used and the CLASSPATH environment variable is not set, the user class path is, by default, the current directory (.).
- -classpath <directories and .zip or .jar files separated by :>
- Sets the search path for application classes and resources. If -classpath and -cp are not used and the CLASSPATH environment variable is not set, the user class path is, by default, the current directory (.).
- -D<property name>=<value>
- Sets a system property.
- -help or -?
- Prints a usage message.
- -javaagent:<jarpath>[=<options>]
- Load a Java programming language agent. For more information, see the java.lang.instrument API documentation.
- -jre-restrict-search
- Include user private JREs in the version search.
- -no-jre-restrict-search
- Exclude user private JREs in the version search.
- -showversion
- Prints product version and continues.
- -verbose:<option>[,<option>...]
- Enables verbose output. Separate multiple options using commas.
The available options are:
- class
- Writes an entry to stderr for each class that is loaded.
- gc
- Writes verbose garbage collection information to stderr. Use -Xverbosegclog (see Garbage Collector command-line options for more information) to control the output. See the Diagnostics Guide for more information.
- jni
- Writes information to stderr describing the JNI services called by the application and JVM.
- sizes
- Writes information to stderr describing the active memory usage settings.
- stack
- Writes information to stderr describing the Java and C stack usage for each thread.
- -version
- Prints product version.
- -version:<value>
- Requires the specified version to run, for example "1.5".
- -X
- Prints help on nonstandard options.
Globalization of the java command
The java and javaw launchers accept arguments and class names containing any character that is in the character set of the current locale. You can also specify any Unicode character in the class name and arguments by using Java escape sequences.
To do this, use the -Xargencoding command-line option.
- -Xargencoding
- Use argument encoding. To specify a Unicode character, use escape sequences in the form \u####, where # is a hexadecimal digit (0 to 9, A to F).
- -Xargencoding:utf8
- Use UTF8 encoding.
- -Xargencoding:latin
- Use ISO8859_1 encoding.
For example, to specify a class called HelloWorld using Unicode encoding for both capital letters, use this command:
java -Xargencoding '\u0048ello\u0057orld'
The java and javaw commands provide translated messages. These messages differ based on the locale in which Java is running. The detailed error descriptions and other debug information that is returned by java is in English.
Working with the LIBPATH environment variable
The LIBPATH environment variable tells AIX applications, such as the JVM, where to find shared libraries when they are located in a different directory from the directory that is specified in the header section of the program.
For example, the header section of the java command is as follows:
> dump -X64 -H /usr/java5_64/jre/bin/java /usr/java5_64/jre/bin/java: ***Loader Section*** Loader Header Information VERSION# #SYMtableENT #RELOCent LENidSTR 0x00000001 0x0000003f 0x0000006d 0x00000090 #IMPfilID OFFidSTR LENstrTBL OFFstrTBL 0x00000006 0x00000b24 0x00000099 0x00000bb4 ***Import File Strings*** INDEX PATH BASE MEMBER 0 /usr/lib:/lib 1 libc.a shr.o 2 libC.a shr.o 3 libpthreads.a shr_comm.o 4 libpthreads.a shr_xpg5.o 5 libbsd.a shr.o
Index 0 in the example contains the list of directories that are searched for shared objects if LIBPATH is not specified. If LIBPATH is set, the specified directories are searched for shared objects before the directories listed in Index 0 of the header.
The shared libraries for the SDK are in /usr/java5_64/jre/bin/ and /usr/java5_64/jre/bin/j9vm. The SDK launcher programs, including java, javac, and jar automatically search these directories. If Java is installed as an AIX file set, the parent directory is /usr/java5_64/, but packages that bundle Java might use different directories. This path is already set by the Java launcher programs such as java, javac, or jar.
Set the LIBPATH if either of the following conditions applies:
- You are using other shared libraries (including JNI native libraries you use or develop). Set the LIBPATH to include the directory or directories that contain your libraries.
- You are using the JNI Invocation API to call Java code from your C/C++ application. Set the LIBPATH to include the directories that contain the JVM libraries in addition to the directories that contain your own libraries.
Working with the LDR_CNTRL environment variable
The POWER4 and later PowerPC® processors support the use of 16 MB large pages in addition to the default 4 KB pages. The POWER5+ and later PowerPC processors add support for two new page sizes, 64 KB and 16 GB.
Page sizes
AIX v5.2 and later operating systems support 16 MB pages. AIX v5.3 maintenance package 5300-04 on POWER5+ processors adds support for the 64 KB and 16 GB page sizes. The 16 MB and 16 GB pages require AIX system configuration changes. For information about using 16 MB pages with AIX, see http://publib.boulder.ibm.com/infocenter/pseries/v5r3/topic/com.ibm.aix.prftungd/doc/prftungd/large_page_ovw.htm. For information about using either 64 KB or 16 GB pages with AIX, see http://publib.boulder.ibm.com/infocenter/pseries/v5r3/topic/com.ibm.aix.prftungd/doc/prftungd/multiple_page_size_support.htm. The default AIX page size is 4 KB.
The LDR_CNTRL=LARGE_PAGE_DATA environment variable can be used under the AIX v5.2 and later operating systems to control the use of 16 MB pages for the native data area and native heap of a program. You can use 16 MB large pages, if they are available, by setting LDR_CNTRL=LARGE_PAGE_DATA=Y. Using large pages might improve the performance of Java applications that require a large amount of native heap space. In particular, the native heap is used for code generated by the just-in-time compiler and also Java applications with many compiled methods. The reason is that both might benefit from using 16 MB pages for the native heap.
AIX v5.3 maintenance package 5300-04 added LDR_CNTRL variants that independently control the use of different page sizes for the text (TEXTPSIZE), stack (STACKPSIZE) and native data or heap (DATAPSIZE) areas. See the Guide to Multiple Page Size Support on AIX 5L™ Version 5.3 for general information about these variants: http://publib.boulder.ibm.com/infocenter/pseries/v5r3/topic/com.ibm.aix.prftungd/doc/prftungd/multiple_page_size_support.htm.
An example of the use of TEXTPSIZE, STACKPSIZE, and DATAPSIZE variants is:
LDR_CNTRL=TEXTPSIZE=4K@STACKPSIZE=64K@DATAPSIZE=64K
This example uses 4 KB pages for text, 64 KB pages for stack and 64 KB pages for the native data and native heap areas. A DATAPSIZE setting overrides any LARGE_PAGE_DATA setting.
The new 64 KB pages are general purpose. Most workloads see a benefit by using 64 KB pages for text, stack, native data, and the Java heap. The 16 GB pages are intended only for use in high performance environments.
The Just-In-Time (JIT) compiler
The IBM Just-In-Time (JIT) compiler dynamically generates machine code for frequently used bytecode sequences in Java applications and applets during their execution. The JIT v5.0 compiler delivers new optimizations as a result of compiler research, improves optimizations implemented in previous versions of the JIT, and provides better hardware exploitation.
The JIT is included in both the IBM SDK and Runtime Environment, which is enabled by default in user applications and SDK tools. Typically, you do not start the JIT explicitly; the compilation of Java bytecode to machine code occurs transparently. You can disable the JIT to help isolate a problem. If a problem occurs when executing a Java application or an applet, you can disable the JIT to help isolate the problem. Disabling the JIT is a temporary measure only; the JIT is required to optimize performance.
The Stack Execution Disable (SED) feature in the AIX 5300-03 Recommended Maintenance package stops code from executing in data areas (Power4 and later). For more information about this feature and how it affects the SDK, see AIX Stack Execution Disable.
For more information about the JIT, see the Diagnostics Guide.
Disabling the JIT
The JIT can be disabled in a number of different ways. Both command-line options override the JAVA_COMPILER environment variable.
About this task
Turning off the JIT is a temporary measure that can help isolate problems when debugging Java applications.
Procedure
- Set the JAVA_COMPILER environment variable
to NONE or the empty string before running the java application. Type
the following at a shell prompt:
export JAVA_COMPILER=NONE
- Use the -D option on the JVM command line
to set the java.compiler property to NONE or
the empty string. Type the following at a shell prompt:
java -Djava.compiler=NONE <class>
- Use the -Xint option on the JVM command line. Type the following at a shell prompt:
java -Xint <class>
Enabling the JIT
The JIT is enabled by default. You can explicitly enable the JIT in a number of different ways. Both command-line options override the JAVA_COMPILER environment variable.
Procedure
- Set the JAVA_COMPILER environment variable
to jitc before running the Java application. At
a shell prompt, enter:
export JAVA_COMPILER=jitc
If the JAVA_COMPILER environment variable is an empty string, the JIT remains disabled. To disable the environment variable, at the prompt, enter:unset JAVA_COMPILER
- Use the -D option on the JVM command line
to set the java.compiler property to jitc. At a prompt,
enter:
java -Djava.compiler=jitc <class>
- Use the -Xjit option on the JVM command line. Do not specify the -Xint option at the same
time. At a prompt,
enter:
java -Xjit <class>
Determining whether the JIT is enabled
You can determine the status of the JIT using the -version option.
Procedure
Run the java launcher with the -version option. Enter the following at a shell prompt:
java -version
If
the JIT is not in use, a message is displayed that includes the following:
(JIT disabled)
If
the JIT is in use, a message is displayed that includes the following:
(JIT enabled)
What to do next
For more information about the JIT, see the Diagnostics Guide.
Specifying garbage collection policy
The Garbage Collector manages the memory used by Java and by applications running in the JVM.
When the Garbage Collector receives a request for storage, unused memory in the heap is set aside in a process called "allocation". The Garbage Collector also checks for areas of memory that are no longer referenced, and releases them for reuse. This is known as "collection".
The collection phase can be triggered by a memory allocation fault, which occurs when no space is left for a storage request, or by an explicit System.gc() call.
Garbage collection can significantly affect application performance, so the IBM virtual machine provides various methods of optimizing the way garbage collection is carried out, potentially reducing the effect on your application.
For more detailed information about garbage collection, see the Diagnostics Guide.
Garbage collection options
The -Xgcpolicy options control the behavior of the Garbage Collector. They make trade-offs between throughput of the application and overall system, and the pause times that are caused by garbage collection.
The format of the option and its values is:
- -Xgcpolicy:gencon
- Requests the combined use of concurrent and generational GC to help minimize the time that is spent in any garbage collection pause.
- -Xgcpolicy:optthruput
- (Default value.) Delivers high throughput to applications, but at the cost of occasional pauses.
- -Xgcpolicy:subpool
- Uses an improved object allocation algorithm to achieve better performance when allocating objects on the heap. This option might improve performance on large SMP systems.
Pause time
If an object cannot be created from the available space in the heap, the Garbage Collector attempts to tidy the heap. The intention is that subsequent allocation requests can be satisfied quickly.
The Garbage Collector tries to returning the heap to a state in which the immediate and subsequent space requests are successful. The Garbage Collector identifies unreferenced "garbage" objects, and deletes them. This work takes place in a garbage collection cycle. These cycles might introduce occasional, unexpected pauses in the execution of application code. As applications grow in size and complexity, and heaps become correspondingly larger, the garbage collection pause time tends to grow in size and significance. Pause time can vary from a few milliseconds to many seconds. The actual time depends on the size of the heap, and the quantity of garbage.
The subpool option of -Xgcpolicy provides additional throughput optimization for large SMP systems (24- to 64-way).
Pause time reduction
The JVM uses two techniques to reduce pause times: concurrent garbage collection and generational garbage collection.
The -Xgcpolicy:optavgpause command-line option requests the use of concurrent garbage collection (GC) to reduce significantly the time that is spent in garbage collection pauses. Concurrent GC reduces the pause time by performing some garbage collection activities concurrently with normal program execution to minimize the disruption caused by the collection of the heap. The -Xgcpolicy:optavgpause option also limits the effect of increasing the heap size on the length of the garbage collection pause. The -Xgcpolicy:optavgpause option is most useful for configurations that have large heaps. With the reduced pause time, you might experience some reduction of throughput to your applications.
During concurrent GC, a significant amount of time is wasted identifying relatively long-lasting objects that cannot then be collected. If garbage collection concentrates on only the objects that are most likely to be recyclable, you can further reduce pause times for some applications. Generational GC reduces pause times by dividing the heap into two generations: the "new" and the "tenure" areas. Objects are placed in one of these areas depending on their age. The new area is the smaller of the two and contains new objects; the tenure is larger and contains older objects. Objects are first allocated to the new area; if they have active references for long enough, they are promoted to the tenure area.
Generational GC depends on most objects not lasting long. Generational GC reduces pause times by concentrating the effort to reclaim storage on the new area because it has the most recyclable space. Rather than occasional but lengthy pause times to collect the entire heap, the new area is collected more frequently and, if the new area is small enough, pause times are comparatively short. However, generational GC has the drawback that, over time, the tenure area might become full. To minimize the pause time when this situation occurs, use a combination of concurrent GC and generational GC. The -Xgcpolicy:gencon option requests the combined use of concurrent and generational GC to help minimize the time that is spent in any garbage collection pause.
Environments with very full heaps
If the Java heap becomes nearly full, and very little garbage can be reclaimed, requests for new objects might not be satisfied quickly because no space is immediately available.
If the heap is operated at near-full capacity, application performance might suffer regardless of which garbage collection options are used; and, if requests for more heap space continue to be made, the application might receive an OutOfMemoryError, which results in JVM termination if the exception is not caught and handled. At this point, the JVM produces a Javadump file for use during diagnostics. In these conditions, you are recommended either to increase the heap size by using the -Xmx option or to reduce the number of objects in use.
For more information, see the Diagnostics Guide.
Dynamic Logical Partitioning (DLPAR) support
System resources, for instance memory and CPUs, can be dynamically added to or removed from a logical partition (LPAR) running AIX. Java applications can take advantage of any new resources. Java applications can also respond to DLPAR events using extensions to the java.lang.management API.
If you run Java applications on a single CPU LPAR and never dynamically add a CPU to that LPAR while those Java applications are running, you can improve the performance by exporting the environment variable: export NO_LPAR_RECONFIGURATION=1. The results vary depending on the execution characteristics of your application. Do not export this environment variable unless all the following conditions are true:
- You are running in an LPAR
- The LPAR has 1 CPU
- The LPAR will never be dynamically reconfigured to add more CPUs while Java applications are running.
Resource changes are effective immediately, so AIX does not need to be rebooted. If an administrator decreases the number of CPUs or memory allocated to an LPAR, the performance of any running SDK application might degrade.
For more information, see http://publib.boulder.ibm.com/infocenter/pseries/v5r3/topic/com.ibm.aix.prftungd/doc/prftungd/dyn_log_part.htm and
the article: Dynamic reconfiguration: Basic building blocks
for autonomic computing on IBM pSeries® servers in the
following IBM Systems Journal
issue: http://www.research.ibm.com/journal/sj42-1.html.
To enable applications to respond to DLPAR events, the Java v5.0 SDK includes IBM-specific extensions to java.lang.management. The extensions provide a Java interface to query various LPAR-specific information, and to listen for events indicating that the logical partition of the JVM has been dynamically altered. The Javadoc tool for this API is provided with the SDK in the file docs/apidoc.zip.
The launcher option, -Xsoftmx, is also available with the Java 6 SDK. The -Xmx option specifies the maximum size (hard limit) of the Java heap. The -Xsoftmx option specifies a lower initial maximum heap size (a "soft" limit). You can change the value of -Xsoftmx at run time using the java.lang.management API. The valid range of values is between the minimum heap size (-Xms) and the hard limit (-Xmx).
For example, if the JVM is running in an LPAR with 2 GB of memory available for the heap, but the amount of memory might be changed to as low as 1 GB or as high as 8 GB during the run, a suitable set of command-line options might be:
-Xms1g -Xsoftmx2g -Xmx8g
The value of -Xms must be less than or equal the value of -Xsoftmx. If unspecified, -Xsoftmx defaults to the value of -Xmx.
Live application mobility on AIX WPAR
IBM AIX Workload Partitions (WPARs) are software-created, virtualized operating system environments in a single instance of the AIX operating system. To most applications, the workload partition appears to be a separate instance of AIX. Applications in workload partitions have a private execution environment.
Applications in workload partitions are isolated in terms of process and signal, and can be isolated in file system space. Workload partitions can have their own unique users and groups. Workload partitions have dedicated network addresses and interprocess communication (IPC) is restricted to processes running in the same workload partition.
There are two forms of workload partitions:
- System WPAR
- A System WPAR presents an environment like a stand-alone AIX system. A System WPAR runs most of the system services that are found in a stand-alone system and does not share writable file systems with any other WPAR or the global system.
- Application WPAR
- An Application WPAR has all the process isolation that a System WPAR provides, except that it shares file system namespace with the global system and any other Application WPAR defined in the system. Other than the application itself, a typical Application WPAR runs an additional lightweight init process in the WPAR.
You can configure either WPAR type for mobility, which allows you to move running WPAR instances between physical systems using the AIX Workload Manager.
From Version 5.0 Service Refresh 8, the IBM SDK for Java supports WPAR mobility. The IBM SDK for Java can also respond to WPAR mobility events and use system environment changes in the same way as when a DLPAR is reconfigured. See Dynamic Logical Partitioning (DLPAR) support for more information.
For more information about WPAR, see http://www.redbooks.ibm.com/redpieces/abstracts/SG247431.html.
Using the IPv6 extensions
The IBM 64-bit SDK for AIX, v5.0 uses the IPv6 extensions to the TCP/IP protocol by default.
On AIX v5.2, if your application uses multicast sockets or your application explicitly uses IPv6 format address, you must enable the network interfaces on your workstation to handle IPv6 addresses. The network interfaces can be configured for IPv6 with smitty or by using the autoconf6 or ifconfig commands.
If you do not want to use IPv6 protocols, you can set the property java.net.preferIPv4Stack to force the use of IPv4 protocols.
Enhanced BiDirectional support
The IBM SDK includes enhanced BiDirectional support.
For more information, see http://www.ibm.com/developerworks/java/jdk/additional/JAVABIDI.html.
The Javadoc file for the BiDirectional package is provided with the SDK in the docs/apidoc.zip file.
Euro symbol support
The IBM SDK and Runtime Environment set the Euro as the default currency for those countries in the European Monetary Union (EMU) for dates on or after 1 January, 2002. From 1 January 2008, Cyprus and Malta also have the Euro as the default currency.
To use the old national currency, specify -Duser.variant=PREEURO on the Java command line.
If you are running the UK, Danish, or Swedish locales and want to use the Euro, specify -Duser.variant=EURO on the Java command line.
Support for Serbian locale
From Service Refresh 5, the following new locale is added: Serbia (SE), with three new locale variations.
The locale variations are:
- sr_RS
- sr_Cyrl_RS
- sr_Latn_RS
The existing locale variations for the former Serbia and Montenegro are maintained as before. The 3-letter country code SRB, corresponding to the 2-letter country code RC, is also added.
Scaling support
To increase the maximum number of threads your system can support, lower the maximum native stack size using the -Xss<size> option.
The default native stack size is 1024 KB. A smaller setting allows for a larger number of threads. For example:
java -Xss<size> <other params>
To increase the maximum number of file descriptors your system can support, use the ulimit or chuser commands, for example:
ulimit -n 3000
or
chuser nofiles=3000 <user_id>
Use ulimit -a to show the current limit.
AIX Stack Execution Disable
AIX 5300-03 implements Buffer Overflow Protection (BOP) using Stack/heap Execution Disable (SED). SED prevents buffer overflow attacks by not executing code in data areas of memory. AIX system administrators control the way SED is used. Java JIT implementations generate machine code in C heap memory; therefore, Java launchers must be exempt from SED.
You make programs exempt from SED by setting the XCOFF executable file header flag DEP_EXEMPT. All Java launchers have the appropriate bit set to exempt them from the SED feature.
Applications that use their own Java launchers and create JVM instances using JNI must be explicitly patched to exempt them from SED. Use the sedmgr utility and verify the change using the dump or sedmgr utility.
The syntax for using these utilities is:
sedmgr -c exempt <launcher> dump -X64 -ov <launcher>
For more details on SED, see http://publib.boulder.ibm.com/infocenter/pseries/index.jsp.
Developing Java applications
The SDK for AIX contains many tools and libraries required for Java software development.
See Contents of the SDK for details of the tools available.
Transforming XML documents
The IBM SDK contains the XSLT4J processor and the XML4J parser. With these tools, you can parse and transform XML documents independently from any given XML processing implementation. By using "Factory Finders" to locate the SAXParserFactory, DocumentBuilderFactory and TransformerFactory implementations, your application can swap between different implementations without having to change any code.
About this task
The IBM SDK contains the XSLT4J processor and the XML4J parser that conform to the JAXP 1.3 specification.
The XML technology included with the IBM SDK is similar to Apache Xerces Java and Apache Xalan Java. See http://xml.apache.org/xerces2-j/ and http://xml.apache.org/xalan-j/ for more information.
With the XSLT4J processor, you choose between the original XSLT Interpretive processor and the XSLT Compiling processor. The Interpretive processor is for tooling and debugging environments and supports the XSLT extension functions that are not supported by the XSLT Compiling processor. The XSLT Compiling processor is for high performance runtime environments; it generates a transformation engine, or translet, from an XSL style sheet. This approach separates the interpretation of stylesheet instructions from their runtime application to XML data.
The XSLT Interpretive processor is the default processor. To use the XSLT Compiling processor:
- Change the entry in the jaxp.properties file, (located in /etc/java5_64/jre/lib) or
- Set the javax.xml.transform.TransformerFactory system property to org.apache.xalan.xsltc.trax.TransformerFactoryImpl.
To implement properties in the jaxp.properties file, copy jaxp.properties.sample to jaxp.properties in /etc/java5_64/jre/lib and create a symbolic link to this file from the /usr/java5_64/jre/lib directory. This file also contains full details about the procedure used to determine which implementations to use for the TransformerFactory, SAXParserFactory, and the DocumentBuilderFactory.
To improve the performance when you transform a StreamSource object with the XSLT Compiling processor, specify the com.ibm.xslt4j.b2b2dtm.XSLTCB2BDTMManager class as the provider of the service org.apache.xalan.xsltc.dom.XSLTCDTMManager. To determine the service provider, try each step until you find org.apache.xalan.xsltc.dom.XSLTCDTMManager:
- Check the setting of the system property org.apache.xalan.xsltc.dom.XSLTCDTMManager.
- Check the value of the property org.apache.xalan.xsltc.dom.XSLTCDTMManager in the file /etc/java5_64/jre/lib/xalan.properties.
- Check the contents of the file META-INF/services/org.apache.xalan.xsltc.dom.XSLTCDTMManager for a class name.
- Use the default service provider, org.apache.xalan.xsltc.dom.XSLTCDTMManager.
The XSLT Compiling processor detects the service provider for the org.apache.xalan.xsltc.dom.XSLTCDTMManager service when a javax.xml.transform.TransformerFactory object is created. Any javax.xml.transform.Transformer or javax.xml.transform.sax.TransformerHandler objects that are created by using that TransformerFactory object use the same service provider. You can change service providers by modifying one of the settings described above and then creating a new TransformerFactory object.
Using an older version of Xerces or Xalan
If you are using an older version of Xerces (before 2.0) or Xalan (before 2.3) in the endorsed override, you might get a NullPointerException when you start your application. This exception occurs because these older versions do not handle the jaxp.properties file correctly.
About this task
To avoid this situation, use one of the following workarounds:
- Upgrade to a newer version of the application that implements the latest Java API for XML Programming (JAXP) specification (https://jaxp.dev.java.net/).
- Remove the jaxp.properties file from /etc/java5_64/jre/lib.
- Uncomment the entries in the jaxp.properties file in /etc/java5_64/jre/lib.
- Copy the jaxp.properties.sample file to jaxp.properties in /etc/java5_64/jre/lib. Uncomment the entries in the jaxp.properties file. Create a symbolic link to the jaxp.properties file from the /usr/java5_64/jre/lib directory.
- Set the system property for javax.xml.parsers.SAXParserFactory, javax.xml.parsers.DocumentBuilderFactory, or javax.xml.transform.TransformerFactory using the -D command-line option.
- Set the system property for javax.xml.parsers.SAXParserFactory, javax.xml.parsers.DocumentBuilderFactory, or javax.xml.transform.TransformerFactory in your application. For an example, see the JAXP 1.3 specification.
- Explicitly set the SAX parser, Document builder, or Transformer
factory using the IBM_JAVA_OPTIONS environment
variable.
export IBM_JAVA_OPTIONS=-Djavax.xml.parsers.SAXParserFactory= org.apache.xerces.jaxp.SAXParserFactoryImpl
orexport IBM_JAVA_OPTIONS=-Djavax.xml.parsers.DocumentBuilderFactory= org.apache.xerces.jaxp.DocumentBuilderFactoryImpl
orexport IBM_JAVA_OPTIONS=-Djavax.xml.transform.TransformerFactory= org.apache.xalan.processor.TransformerFactoryImpl
Debugging Java applications
To debug Java programs, you can use the Java Debugger (JDB) application or other debuggers that communicate by using the Java Platform Debugger Architecture (JPDA) that is provided by the SDK for the operating system.
The SDK includes a Plug-in for the AIX debugger DBX. Although the DBX Plug-in is supplied as part of the SDK, it is not supported. However, IBM will accept bug reports.
More information about problem diagnosis using Java can be found in the Diagnostics Guide.
Java Debugger (JDB)
The Java Debugger (JDB) is included in the SDK for AIX. The debugger is started with the jdb command; it attaches to the JVM using JPDA.
To debug a Java application:
- Start the JVM with the following options:
java -agentlib:jdwp=transport=dt_socket,server=y,address=<port> <class>
The JVM starts up, but suspends execution before it starts the Java application. - In a separate session, you can attach the debugger to the JVM:
jdb -attach <port>
The debugger will attach to the JVM, and you can now issue a range of commands to examine and control the Java application; for example, type run to allow the Java application to start.
For more information about JDB options, type:
jdb -help
For more information about JDB commands:
- Type jdb
- At the jdb prompt, type help
You can also use JDB to debug Java applications running on remote workstations. JPDA uses a TCP/IP socket to connect to the remote JVM.
- Start the JVM with the following options:
java -agentlib:jdwp=transport=dt_socket,server=y,address=<port> <class>
The JVM starts up, but suspends execution before it starts the Java application. - Attach the debugger to the remote JVM:
jdb -attach <host>:<port>
The Java Virtual Machine Debugging Interface (JVMDI) is not supported in this release. It has been replaced by the Java Virtual Machine Tool Interface (JVMTI).
For more information about JDB and JPDA and their usage, see these Web sites:
- http://www.oracle.com/technetwork/java/javase/tech/jpda-141715.html
- http://download.oracle.com/javase/1.5.0/docs/guide/jpda/
- http://download.oracle.com/javase/1.5.0/docs/guide/jpda/jdb.html
Determining whether your application is running on a 32-bit or 64-bit JVM
Some Java applications must be able to determine whether they are running on a 32-bit JVM or on a 64-bit JVM. For example, if your application has a native code library, the library must be compiled separately in 32- and 64-bit forms for platforms that support both 32- and 64-bit modes of operation. In this case, your application must load the correct library at runtime, because it is not possible to mix 32- and 64-bit code.
About this task
The system property com.ibm.vm.bitmode allows applications to determine the mode in which your JVM is running. It returns the following values:
- 32 - the JVM is running in 32-bit mode
- 64 - the JVM is running in 64-bit mode
You can inspect the com.ibm.vm.bitmode property from inside your application code using the call:
System.getProperty("com.ibm.vm.bitmode");
How the JVM processes signals
When a signal is raised that is of interest to the JVM, a signal handler is called. This signal handler determines whether it has been called for a Java or non-Java thread.
If the signal is for a Java thread, the JVM takes control of the signal handling. If an application handler for this signal is installed and you did not specify the -Xnosigchain command-line option, the application handler for this signal is called after the JVM has finished processing.
If the signal is for a non-Java thread, and the application that installed the JVM had previously installed its own handler for the signal, control is given to that handler. Otherwise, if the signal is requested by the JVM or Java application, the signal is ignored or the default action is taken.
For exception and error signals, the JVM either:
- Handles the condition and recovers, or
- Enters a controlled shut down sequence where it:
- Produces dumps, to describe the JVM state at the point of failure
- Calls your application's signal handler for that signal
- Performs the necessary JVM cleanup
For interrupt signals, the JVM also enters a controlled shut down sequence, but this time it is treated as a normal termination that:
- Calls your application's signal handler for that signal
- Performs the necessary JVM cleanup
The shut down is identical to the shut down initiated by a call to the Java method System.exit().
Other signals that are used by the JVM are for internal control purposes and do not cause it to stop. The only control signal of interest is SIGQUIT, which causes a Javadump to be generated.
Signals used by the JVM
The types of signals are Exceptions, Errors, Interrupts, and Controls.
Table 3 shows the signals that are used by the JVM. The signals are grouped in the table by type or use, as follows:
- Exceptions
- The operating system synchronously raises an appropriate exception signal whenever an unrecoverable condition occurs.
- Errors
- The JVM raises a SIGABRT if it detects a condition from which it cannot recover.
- Interrupts
- Interrupt signals are raised asynchronously, from outside a JVM process, to request shut down.
- Controls
- Other signals that are used by the JVM for control purposes.
Signal Name | Signal type | Description | Disabled by -Xrs | Disabled by -Xrs:sync |
---|---|---|---|---|
SIGBUS (7) | Exception | Incorrect access to memory (data misalignment) | Yes | Yes |
SIGSEGV (11) | Exception | Incorrect access to memory (write to inaccessible memory) | Yes | Yes |
SIGILL (4) | Exception | Illegal instruction (attempt to call an unknown machine instruction) | Yes | Yes |
SIGFPE (8) | Exception | Floating point exception (divide by zero) | Yes | Yes |
SIGABRT (6) | Error | Abnormal termination. The JVM raises this signal whenever it detects a JVM fault. | Yes | Yes |
SIGINT (2) | Interrupt | Interactive attention (CTRL-C). JVM exits normally. | Yes | No |
SIGTERM (15) | Interrupt | Termination request. JVM will exit normally. | Yes | No |
SIGHUP (1) | Interrupt | Hang up. JVM exits normally. | Yes | No |
SIGQUIT (3) | Control | By default, this triggers a Javadump. | Yes | No |
No Name (40) | Control | An AIX reserved signal. Used by the AIX JVM for internal control purposes. | Yes | No |
SIGRECONFIG (58) | Control | Reserved to detect any change in the number of CPUs, processing capacity, or physical memory. | Yes | No |
SIGTRAP (5) | Control | Used by the JIT. | Yes | Yes |
SIGRTMAX (2) | Control | Used by the SDK. | No | No |
SIGCHLD (17) | Control | Used by the SDK for internal control. | No | No |
Use the -Xrs (reduce signal usage) option to prevent the JVM from handling most signals. For more information, see Oracle's Java application launcher page.
Do not use the -qflttrap C compiler setting because it provides the possibility of SIGTRAPs being generated, which might then affect the JIT. If you want to have floating point exceptions generated, include this call in your code so that it generates a SIGFPE signal:
fp_trap( FP_TRAP_SYNC)
If you install a signal handler for signal numbers 5 (SIGTRAP) or 58 (SIGRECONFIG), you affect JVM performance because these signals are used for internal control purposes.
Signals 1 (SIGHUP), 2 (SIGINT), 4 (SIGILL), 7 (SIGBUS), 8 (SIGFPE), 11 (SIGSEGV), and 15 (SIGTERM) on JVM threads cause the JVM to shut down; therefore, an application signal handler should not attempt to recover from these unless it no longer requires the JVM.
Linking a native code driver to the signal-chaining library
The Runtime Environment contains signal-chaining. Signal-chaining enables the JVM to interoperate more efficiently with native code that installs its own signal handlers.
About this task
The libjsig.a library ensures that calls such as signal(), sigset(), and sigaction() are intercepted so that their handlers do not replace the JVM's signal handlers. Instead, these calls save the new signal handlers, or "chain" them behind the handlers that are installed by the JVM. Later, when any of these signals are raised and found not to be targeted at the JVM, the preinstalled handlers are invoked.
If you install signal handlers that use sigaction() , some sa_flags are not observed when the JVM uses the signal. These are:
- SA_RESTART - This is always set.
The libjsig.a library also hides JVM signal handlers from the application. Therefore, calls such as signal(), sigset(), and sigaction() that are made after the JVM has started no longer return a reference to the JVM's signal handler, but instead return any handler that was installed before JVM startup.
The environment variable JAVA_HOME should be set to the location of the SDK, for example,/usr/java5_64/.
To use libjsig.a:
- Link it with the application that creates or embeds
a JVM:
cc_r -q64 <other compile/link parameter> -L/usr/java5_64/jre/bin -ljsig -L/usr/java5_64/jre/bin/j9vm -ljvm java_application.c
Note: Use xlc_r or xlC_r in place of cc_r if that is how you usually call the compiler or linker.
Writing JNI applications
Valid Java Native Interface (JNI) version numbers that programs can specify on the JNI_CreateJavaVM() API call are: JNI_VERSION_1_2(0x00010002) and JNI_VERSION_1_4(0x00010004).
This version number determines only the level of the JNI to use. The actual level of the JVM that is created is specified by the JSE libraries (that is, v5.0). The JNI level does not affect the language specification that is implemented by the JVM, the class library APIs, or any other area of JVM behavior. For more information, see http://download.oracle.com/javase/1.5.0/docs/guide/jni.
If your application needs two JNI libraries, one built for 32- and the other for 64-bit, use the com.ibm.vm.bitmode system property to determine if you are running with a 32- or 64-bit JVM and choose the appropriate library.
JNI compatibility
There is a readme file and example programs in the /usr/java5_64/demo/jni directory. The demos can be optionally installed with the Java6_64.samples package.
If you are writing a C or C++ program that uses the JNI Invocation API (that is, the program creates a Java Virtual Machine and calls Java code), you might want to ensure that the following variables are set appropriately. By default, all the Java launchers that are shipped with the SDK (for example, java, jar) set up these environment variables to the values that are specified as follows:
- export AIXTHREAD_SCOPE=S
- export AIXTHREAD_MUTEX_DEBUG=OFF
- export AIXTHREAD_RWLOCK_DEBUG=OFF
- export AIXTHREAD_COND_DEBUG=OFF
When you build a C or C++ program that uses the invocation API, your LIBPATH must include the directories containing the JVM's shared libraries, /usr/java5_64/jre/bin/ and /usr/java5_64/jre/bin/j9vm, as well as the directories that contain the application's shared libraries.
You must build:
- 64-bit executables and shared objects with the -qarch=ppc option
- JNI executables and shared objects for the 64-bit SDK as a 64-bit program or shared object. Use the -q64 option.
The SDK does not support runtime linking (using the -brtl loader option). Any applications that are built for use with the SDK must not rely on runtime linking functionality.
You are recommended to compile your native methods (C or C++ functions called by Java) into AIX shared objects (dynamically loaded libraries). For example, if your native methods are stored in the file nm.c, you could create the shared object with the following command:
cc_r -qmkshrobj -q64 -I /usr/java5_64/include -o libnm.a nm.cThe -qmkshrobj option disables runtime linking. For more details about shared object files, runtime linking, and the use of cc and ld command-line options, see:
- Developing and Porting C and C++ Applications on AIX at http://www.redbooks.ibm.com/abstracts/sg245674.html
- The C and C++ compiler documentation Web site at http://www.ibm.com/software/awdtools/xlcpp/library
- The AIX online documentation at http://www16.boulder.ibm.com/pseries/en_US/infocenter/base/aix.htm
Before running a Java program that uses native methods, ensure that LIBPATH contains the list of directories that are holding the native methods' shared objects. For more information about building AIX shared objects, see C and C++ Application Development on AIX. Go to http://www.ibm.com/redbooks and search for "SG245674".
If you set the setuid or setgid attribute on JNI native code programs, that setting changes the effective LIBPATH environment variable. This change might cause unexpected or incorrect behavior with those programs. For more details about this usage, see Developing and Porting C and C++ Applications on AIX at http://www.redbooks.ibm.com/abstracts/sg245674.html, section 2.3.3.
When building a C or C++ program that uses the JNI Invocation API to create a Java virtual machine and calls Java code, use the:
- -L option to add /usr/lib and /lib to the list of directories that are searched for shared objects. All programs need shared objects stored in these directories.
For example, this command builds a C program (invAPITest.c) that uses the JNI Invocation API:
cc_r -q64 -I/usr/java5_64/include -o invAPITest -L/usr/lib -L/lib -L/usr/java5_64/jre/bin/j9vm -L/usr/java5_64/jre/bin/ -ljvm invAPITest.c
When executing a C or C++ program that uses the JNI Invocation API to run Java classes, ensure that the class path is set up correctly to enable the Java Virtual Machine (JVM) to find your class files. If you modify Java's boot class path, include the SDK files that are necessary to run your applications.
To determine whether a C or C++ program that is using the JNI Invocation API was built with the -bM:UR option, use the command:
>dump -X64 -ov <program name> ***Object Module Header*** # Sections Symbol Ptr # Symbols Opt Hdr Len Flags 4 0x0001a728 1305 120 0x1002 Flags=( EXEC DYNLOAD DEP_SYSTEM ) Timestamp = "14 Oct 03:26:43 2005" Magic = 0x1f7 (64-bit XCOFF) ***Optional Header*** Tsize Dsize Bsize Tstart Dstart 0x000127f8 0x00001b80 0x00000470 0x1000001f8 0x1100009f0 SNloader SNentry SNtext SNtoc SNdata 0x0004 0x0002 0x0001 0x0002 0x0002 TXTalign DATAalign TOC vstamp entry 0x0005 0x0003 0x110002158 0x0001 0x110002040 maxSTACK maxDATA SNbss magic modtype 0x00000000 0x00000000 0x0003 0x010b UR
If the modtype is not UR, you can use the LDR_CNTRL environment variable to make programs behave as though they were compiled with the -bM:UR binder option. For example:
export LDR_CNTRL=USERREGS
If you need to specify multiple options with LDR_CNTRL, separate those options with the "@" symbol.
Java threads that are created by the SDK use the POSIX pthreads model that is supported on AIX. Currently, this is on a 1-to-1 mapping with the kernel threads. When developing a JNI program, you must run with a 1-to-1 thread model and system contention scope if creating pthreads in your own program. You can control this by using the following environment setting:
export AIXTHREAD_SCOPE=S
Another option is to preset the thread's scope attribute to PTHREAD_SCOPE_SYSTEM using the AIX pthread_attr_setscope function when the thread is created. For more details on thread model and system contention scope, see:
From Java V5.0, you can store native methods in these ways:
- Shared object
- A shared object is a single object file that has the SRE (Shared REusable) bit set in the XCOFF header. The SRE bit tells the linker that this file is linked dynamically. These files typically have a name of the form <filename>.o, but they can also be named lib<name>.a to allow the linker to search for them with the -lname option; but these are not archive library files.
- Shared library
- A shared library is an "ar" format archive library in which one or more of the archive members is a shared object. Note that this library can also contain non-shared object files that are statically linked. A shared library has the name in the form lib<name>.a. This form allows the linker to search for libraries with the -lname option.
Programs can also link dynamically to AIX shared libraries and shared objects using the dlopen() family of subroutines. The SDK links in this way when it loads native libraries (for example, System.load(), System.loadLibrary(), Runtime.getRuntime().load(), Runtime.getRuntime().loadLibrary()).
For information about dlopen, see:
For information about AIX loading and linking mechanisms, see: AIX Linking and Loading Mechanisms
To load an AIX shared library, make a call to:
System.loadLibrary("<library>(<member>)")
where <library> is the name of the shared library archive and <member> is the name of an archive member. For example:
System.loadLibrary("libShared.a(libSample.o)")
Example of using AIX shared libraries
This example takes you through the process of using native shared libraries with a Java application on AIX.
Procedure
- Create a sample application, Sample.java.
public class Sample { public native void printFromNative( ); public static void main( String[] args ) { Sample sample = new Sample( ); sample.printFromNative( ); } static { String sharedLibrary = "libShared.a(libSample.o)"; try { System.loadLibrary( sharedLibrary ); } catch ( Exception e ) { System.out.println( "ERROR: Unable to load " + sharedLibrary ); e.printStackTrace( ); } } }
- Compile Sample.java.
javac Sample.java
- Use javah to create a header file for
the native code.
javah Sample
- Create a file called Sample.c.
#include <stdio.h> #include "Sample.h" JNIEXPORT void JNICALL Java_Sample_printFromNative( JNIEnv * env, jobject obj ) { printf( "Printing from native\n" ); }
- Compile Sample.c into libSample.o.
cc_r -bM:SRE -bnoentry -bexpall -I/usr/java5_64/include Sample.c -o libSample.o -q64
- Create an archive shared library libShared.a.
ar -X64 -v -q libShared.a libSample.o
- Run the Sample class.
LIBPATH=. java Sample
The program will output:Printing from native
Results
You should now be able to use the same framework to access native shared libraries from Java applications.
Support for thread-level recovery of blocked connectors
Four new IBM-specific SDK classes have been added to the com.ibm.jvm package to support the thread-level recovery of Blocked connectors. The new classes are packaged in core.jar.
These classes allow you to unblock threads that have become blocked on networking or synchronization calls. If an application does not use these classes, it must end the whole process, rather than interrupting an individual blocked thread.
The classes are:
- public interface InterruptibleContext
- Defines two methods, isBlocked() and unblock(). The other three classes implement InterruptibleContext.
- public class InterruptibleLockContext
- A utility class for interrupting synchronization calls.
- public class InterruptibleIOContext
- A utility class for interrupting network calls.
- public class InterruptibleThread
- A utility class that extends java.lang.Thread, to allow wrapping of interruptible methods. It uses instances of InterruptibleLockContext and InterruptibleIOContext to perform the required isBlocked() and unblock() methods depending on whether a synchronization or networking operation is blocking the thread.
Both InterruptibleLockContext and InterruptibleIOContext work by referencing the current thread. Therefore if you do not use InterruptibleThread, you must provide your own class that extends java.lang.Thread, to use these new classes.
The Javadoc information for these classes is provided with the SDK in the docs/apidoc.zip file.
CORBA support
The Java Platform, Standard Edition (J2SE) supports, at a minimum, the specifications that are defined in the compliance document from Oracle. In some cases, the IBM J2SE ORB supports more recent versions of the specifications.
The minimum specifications supported are defined in the Official Specifications for CORBA support in J2SE: http://download.oracle.com/javase/1.5.0/docs/api/org/omg/CORBA/doc-files/compliance.html.
Support for GIOP 1.2
This SDK supports all versions of GIOP, as defined by chapters 13 and 15 of the CORBA 2.3.1 specification, OMG document formal/99-10-07.
http://www.omg.org/cgi-bin/doc?formal/99-10-07
Bidirectional GIOP is not supported.
Support for Portable Interceptors
This SDK supports Portable Interceptors, as defined by the OMG in the document ptc/01-03-04, which you can obtain from:
http://www.omg.org/cgi-bin/doc?ptc/01-03-04
Portable Interceptors are hooks into the ORB that ORB services can use to intercept the normal flow of execution of the ORB.
Support for Interoperable Naming Service
This SDK supports the Interoperable Naming Service, as defined by the OMG in the document ptc/00-08-07, which you can obtain from:
http://www.omg.org/cgi-bin/doc?ptc/00-08-07
The default port that is used by the Transient Name Server (the tnameserv command), when no ORBInitialPort parameter is given, has changed from 900 to 2809, which is the port number that is registered with the IANA (Internet Assigned Number Authority) for a CORBA Naming Service. Programs that depend on this default might have to be updated to work with this version.
The initial context that is returned from the Transient Name Server is now an org.omg.CosNaming.NamingContextExt. Existing programs that narrow the reference to a context org.omg.CosNaming.NamingContext still work, and do not need to be recompiled.
The ORB supports the -ORBInitRef and -ORBDefaultInitRef parameters that are defined by the Interoperable Naming Service specification, and the ORB::string_to_object operation now supports the ObjectURL string formats (corbaloc: and corbaname:) that are defined by the Interoperable Naming Service specification.
The OMG specifies a method ORB::register_initial_reference to register a service with the Interoperable Naming Service. However, this method is not available in the Oracle Java Core API at Version 5.0. Programs that have to register a service in the current version must invoke this method on the IBM internal ORB implementation class. For example, to register a service "MyService":
((com.ibm.CORBA.iiop.ORB)orb).register_initial_reference("MyService", serviceRef);
Where orb is an instance of org.omg.CORBA.ORB, which is returned from ORB.init(), and serviceRef is a CORBA Object, which is connected to the ORB. This mechanism is an interim one, and is not compatible with future versions or portable to non-IBM ORBs.
System properties for tracing the ORB
A runtime debug feature provides improved serviceability. You might find it useful for problem diagnosis or it might be requested by IBM service personnel.
Tracing Properties
- com.ibm.CORBA.Debug=true
- Turns on ORB tracing.
- com.ibm.CORBA.CommTrace=true
- Adds GIOP messages (sent and received) to the trace.
- com.ibm.CORBA.Debug.Output=<file>
- Specify the trace output file. By default, this is of the form orbtrc.DDMMYYYY.HHmm.SS.txt.
Example of ORB tracing
For example, to trace events and formatted GIOP messages from the command line, type:
java -Dcom.ibm.CORBA.Debug=true -Dcom.ibm.CORBA.CommTrace=true <myapp>
Limitations
Do not enable tracing for normal operation, because it might cause performance degradation. Even if you have switched off tracing, FFDC (First Failure Data Capture) is still working, so serious errors are reported. If a debug output file is generated, examine it to check on the problem. For example, the server might have stopped without performing an ORB.shutdown().
The content and format of the trace output might vary from version to version.
System properties for tuning the ORB
The ORB can be tuned to work well with your specific network. The properties required to tune the ORB are described here.
- com.ibm.CORBA.FragmentSize=<size in bytes>
- Used to control GIOP 1.2 fragmentation. The default size is 1024 bytes.
To disable fragmentation, set the fragment size to 0 bytes:
java -Dcom.ibm.CORBA.FragmentSize=0 <myapp>
- com.ibm.CORBA.RequestTimeout=<time in seconds>
- Sets the maximum time to wait for a CORBA Request. By default the ORB waits indefinitely. Do not set the timeout too low to avoid connections ending unnecessarily.
- com.ibm.CORBA.LocateRequestTimeout=<time in seconds>
- Set the maximum time to wait for a CORBA LocateRequest. By default the ORB waits indefinitely.
- com.ibm.CORBA.ListenerPort=<port number>
- Set the port for the ORB to read incoming requests on. If this property is set, the ORB starts listening as soon as it is initialized. Otherwise, it starts listening only when required.
Java security permissions for the ORB
When running with a Java SecurityManager, invocation of some methods in the CORBA API classes might cause permission checks to be made, which might result in a SecurityException. If your program uses any of these methods, ensure that it is granted the necessary permissions.
Class/Interface | Method | Required permission |
---|---|---|
org.omg.CORBA.ORB | init | java.net.SocketPermission resolve |
org.omg.CORBA.ORB | connect | java.net.SocketPermission listen |
org.omg.CORBA.ORB | resolve_initial_references | java.net.SocketPermission connect |
org.omg.CORBA. portable.ObjectImpl | _is_a | java.net.SocketPermission connect |
org.omg.CORBA. portable.ObjectImpl | _non_existent | java.net.SocketPermission connect |
org.omg.CORBA. portable.ObjectImpl | OutputStream _request (String, boolean) | java.net.SocketPermission connect |
org.omg.CORBA. portable.ObjectImpl | _get_interface_def | java.net.SocketPermission connect |
org.omg.CORBA. Request | invoke | java.net.SocketPermission connect |
org.omg.CORBA. Request | send_deferred | java.net.SocketPermission connect |
org.omg.CORBA. Request | send_oneway | java.net.SocketPermission connect |
javax.rmi. PortableRemoteObject | narrow | java.net.SocketPermission connect |
ORB implementation classes
A list of the ORB implementation classes.
The ORB implementation classes in this release are:
- org.omg.CORBA.ORBClass=com.ibm.CORBA.iiop.ORB
- org.omg.CORBA.ORBSingletonClass=com.ibm.rmi.corba.ORBSingleton
- javax.rmi.CORBA.UtilClass=com.ibm.CORBA.iiop.UtilDelegateImpl
- javax.rmi.CORBA.StubClass=com.ibm.rmi.javax.rmi.CORBA.StubDelegateImpl
-
javax.rmi.CORBA.PortableRemoteObjectClass
=com.ibm.rmi.javax.rmi.PortableRemoteObject
These are the default values, and you are advised not to set these properties or refer to the implementation classes directly. For portability, make references only to the CORBA API classes, and not to the implementation. These values might be changed in future releases.
RMI over IIOP
Java Remote Method Invocation (RMI) provides a simple mechanism for distributed Java programming. RMI over IIOP (RMI-IIOP) uses the Common Object Request Broker Architecture (CORBA) standard Internet Inter-ORB Protocol (IIOP) to extend the base Java RMI to perform communication. This allows direct interaction with any other CORBA Object Request Brokers (ORBs), whether they were implemented in Java or another programming language.
The following documentation is available:
- The RMI-IIOP Programmer's Guide is an introduction to writing RMI-IIOP programs.
- The demo directory (in /usr/java5_64/) contains:
- A "Hello World" example that can switch between the Java Remote Method Protocol (JRMP) and IIOP protocols (demo/rmi-iiop/hello)
- A "Hello World" example that interacts with a standard Interface Description Language (IDL) program (demo/rmi-iiop/idl)
- The Java Language to IDL Mapping document is a detailed technical specification of RMI-IIOP: http://www.omg.org/cgi-bin/doc?ptc/00-01-06.pdf.
Implementing the Connection Handler Pool for RMI
Thread pooling for RMI Connection Handlers is not enabled by default.
About this task
To enable the connection pooling implemented at the RMI TCPTransport level, set the option
-Dsun.rmi.transport.tcp.connectionPool=true
This version of the Runtime Environment does not have a setting that you can use to limit the number of threads in the connection pool.
Enhanced BigDecimal
From Java 5.0, the IBM BigDecimal class has been adopted by Oracle as java.math.BigDecimal. The com.ibm.math.BigDecimal class is reserved for possible future use by IBM and is currently deprecated. Migrate existing Java code to use java.math.BigDecimal.
The new java.math.BigDecimal uses the same methods as both the previous java.math.BigDecimal and com.ibm.math.BigDecimal. Existing code using java.math.BigDecimal continues to work correctly. The two classes do not serialize.
To migrate existing Java code to use the java.math.BigDecimal class, change the import statement at the top of your .java file from: import com.ibm.math.*; to import java.math.*;.
AIX native threads
On AIX 5.2, Java runs with system contention scope threads (AIXTHREAD_SCOPE=S). This way of running means that each Java thread is mapped one-to-one to an AIX kernel thread and that these kernel threads are scheduled against all other threads in the system. Each thread has an initial priority that is dynamically modified by the AIX scheduler, according to the thread's activity; thread execution is time-sliced. As such, the Java interfaces for setting thread priority have no effect on the thread's actual priority.
For more information about AIX dynamic thread scheduling, see:
http://publibn.boulder.ibm.com/doc_link/en_US/a_doc_lib/aixprggd/genprogc/threads_sched.htm
For more information about AIX 5.3 thread scheduling, see:
http://publib.boulder.ibm.com/infocenter/pseries/index.jsp?topic=/com.ibm.aix.doc/libs/basetrf1/pthread_setschedparam.htm and http://publib.boulder.ibm.com/infocenter/pseries/index.jsp?topic=/com.ibm.aix.doc/aixprggd/genprogc/threads_sched.htm.
JNDI
The IBM 64-bit SDK for AIX, v5.0 provides a unified interface, the Java Naming and Directory Interface (JNDI), to the naming and directory services.
These naming and directory services are supported by JNDI:
- Lightweight Directory Access Protocol (LDAP)
- Corba Object Services (COS) Naming Service
- RMI Registry
- File system
- Domain Name Service (DNS)
HPROF Performance Profiler and JVMPI
The Java Virtual Machine Profiling Interface (JVMPI) has been extended to include profiling in the IBM JIT. These additional definitions are listed in jvmpi.h.
GetCurrentThreadCpuTime
To enable the JVMPI function GetCurrentThreadCPUTime, you must enable AIX resource collection by setting the environment variable AIXTHREAD_ENRUSG.
About this task
When the resource collection is enabled, the HPROF profiling agent, started with -Xrunhprof:cpu=times provides meaningful data in the HPROF output.
Procedure
Type the following command at the shell prompt:
export AIXTHREAD_ENRUSG=ON
Results
You will get the following message when performance profiling is switched on:
Warning: Performance profiling is enabled and can cause performance degradation. Warning: You can unset AIXTHREAD_ENRUSG to disable performance profiling.
What to do next
Make sure that the resource collection is disabled after your profiling session because the added processor usage when tracking CPU time for individual threads affects performance. Resource collection should never be enabled in a production environment. To disable the resource collection, do one of the following:
unset AIXTHREAD_ENRUSG export AIXTHREAD_ENRUSG=OFF
By default, resource collection is disabled.
Known restriction
The JVMPI_EVENT_INSTRUCTION_START event is not currently supported in the IBM 64-bit SDK for AIX, v5.0. It might be added in a future release.
Java 3D for AIX
This release includes Java 3D for AIX, Version 1.3.
The file set, Java6.ext.java3d, is optionally installable. For more information, read /usr/java5_64/java3d/README.java3d.aix.txt after installing the file set.
Support for XToolkit
The IBM 64-bit SDK for AIX, v5.0 supports XToolkit from Service Refresh 4. You need XToolkit when using the SWT_AWT bridge in Eclipse to build an application that uses both SWT and Swing. XToolkit is an alternative to the existing use of MToolkit libraries, with the benefit of faster rendering.
Related links:
- An example of integrating Swing into Eclipse RCPs: http://eclipsezone.com/eclipse/forums/t45697.html
- Reference Information in the Eclipse information center: http://help.eclipse.org/help32/index.jsp?topic=/org.eclipse.platform.doc.isv/reference/api/org/eclipse/swt/awt/SWT_AWT.html
- Set up information is available on the Oracle Corporation Web site: http://download.oracle.com/javase/1.5.0/docs/guide/awt/1.5/xawt.html
Support for the Java Attach API
Your application can connect to another "target" virtual machine using the Java Attach API. Your application can then load an agent application into the target virtual machine, for example to perform tasks such as monitoring status.
Code for agent applications, such as JMX agents or JVMTI agents, is normally loaded during virtual machine startup by specifying special startup parameters. Requiring startup parameters might not be convenient for using agents on applications that are already running, such as WebSphere Application Servers. You can use the Java Attach API to load an agent at any time, by specifying the process ID of the target virtual machine. The Attach API capability is sometimes called the "late attach" capability.
The Attach API is disabled by default for Java 5 SR 11 and later.
Security considerations
Security for the Java Attach API is handled by UNIX user and group file permissions.
The Java Attach API creates files and directories in a common directory. The common directory, subdirectories, and files in it, have UNIX file permissions. To prevent "spoofing" attacks, change the ownership of the common directory to ROOT or another privileged user ID.
The key security features of the Java Attach API are:
- For Java 5 SR 11 and later, a process using the Java Attach API must be owned by the same UNIX user ID as the target process. This constraint ensures that only the target process owner can attach other applications to the target process.
- For Java 5 SR 11 and later, access to the files or directories owned by a process is controlled by user permissions only; group access (read/write) is disabled.
- The common directory uses the sticky bit to prevent a user from deleting or replacing a subdirectory belonging to another user. To preserve the security of this mechanism, set the ownership of the common directory to ROOT.
- The subdirectory for a process is accessible only by members of the same UNIX group as the owner of a process. For Java 5 SR 11 and later, read/write access is restricted to the owner only, except for the attachNotificationSync file. The attachNotificationSync file can be written to by all users. This exception does not affect security because the file is used exclusively for synchronization and is never written to or read.
- Information about the target process can be written only by the owner. Information about the target process can be read only by the owner or a member of the same group as the owner. For Java 5 SR 11 and later, read/write access is restricted to the owner only.
- For Java 5 after SR 12, processes using the default z/OS® OMVS segment cannot enable the Attach API.
You must secure access to the Java Attach API capability to ensure that only authorized users or processes can connect to another virtual machine. If you do not intend to use the Java Attach API capability, disable this feature using a Java system property. Set the com.ibm.tools.attach.enable system property to the value no; for example:
-Dcom.ibm.tools.attach.enable=no
The Attach API can be enabled by setting the com.ibm.tools.attach.enable system property to the value yes; for example:
-Dcom.ibm.tools.attach.enable=yes
Using the Java Attach API
By default, the target virtual machine is identified by its process ID. To use a different target, change the system property com.ibm.tools.attach.id; for example:
-Dcom.ibm.tools.attach.id=<process_ID>
The target process also has a human-readable "display name". By default, the display name is the process ID. To change the default display name, use the com.ibm.tools.attach.displayName system property. The ID and display name cannot be changed after the application has started.
The Attach API creates working files in a common directory called .com_ibm_tools_attach, which is created in the system temporary directory. The system property java.io.tmpdir holds the value of the system temporary directory. On non-Windows systems, the system temporary directory is typically /tmp. To modify the working directory, use the Java system property com.ibm.tools.attach.directory; for example:
-Dcom.ibm.tools.attach.directory=/working
The directory must be located on a local drive. Specifying a network mounted file system might result in incorrect behavior.
If your Java application ends abnormally, for example, following a crash or a SIGKILL signal, the process subdirectory is not deleted. The Java VM detects and removes obsolete subdirectories where possible. The subdirectory can also be deleted by the owning user ID.
On heavily loaded system, applications might experience timeouts when attempting to connect to target applications. The default timeout is 120 seconds. Use the com.ibm.tools.attach.timeout system property to specify a different timeout value in milliseconds. For example, to timeout after 60 seconds:
-Dcom.ibm.tools.attach.timeout=60000
A timeout value of zero indicates an indefinite wait.
For JMX applications, you can disable authentication by editing the <JAVA_HOME>/jre/lib/management/management.properties file. Set the following properties to disable authentication in JMX:
com.sun.management.jmxremote.authenticate=false com.sun.management.jmxremote.ssl=false
An unsuccessful attempt to start the Attach API results in one of the following exceptions:
- com.ibm.tools.attach.AgentLoadException
- com.ibm.tools.attach.AgentInitializationException
- com.ibm.tools.attach.AgentNotSupportedException
- java.io.IOException
A useful reference for information about the Attach API can be found at http://download.oracle.com/javase/6/docs/technotes/guides/attach/index.html. The IBM implementation of the Attach API corresponds approximately to the Oracle Corporation implementation. However, if your application originally used com.sun.tools.attach.* methods or classes, you must modify and recompile the application to use the com.ibm.tools.attach.* implementation.
public void loadAgent(String agent) public void loadAgent(String agent, String options)are not available.
Plug-in, Applet Viewer
The Java plug-in is used to run Java applications in the browser. The appletviewer is used to test applications designed to be run in a browser.
Using the Java plug-in
The Java plug-in is a web browser plug-in. You use the Java plug-in to run applets in the browser.
Allow enough time for applets to finish loading, otherwise your browser might seem to "stop". For example, if you click Back and then click Forward while an applet is loading, the HTML pages might be unable to load.
The Java plug-in is documented at: http://download.oracle.com/javase/1.5.0/docs/guide/plugin/developer_guide/contents.html.
Supported browsers
The Java plug-in supports the following browsers: Mozilla Firefox.
Browser | Supported Versions |
---|---|
Firefox | 1.7, 2.0, 3.5, 3.6. Available at http://www.ibm.com/servers/aix/browsers/. |
Installing the Java plug-in
To install the Java plug-in, symbolically link it to the plug-in directory for your browser.
The Java plug-in is based on the Mozilla Open JVM Integration initiative, which is used with most Mozilla products and derivatives, including Firefox.
You must symbolically link the plug-in, rather than copy it, so that the browser and plug-in can locate the JVM.
Changing the properties of the Java Plug-in
You can change the properties of the Java Plug-in from the control panel, which can be run as a stand-alone Java application.
About this task
To start this Java application, run the script:
/usr/java5_64/jre/bin/ControlPanel
Common Document Object Model (DOM) support
Because of limitations in particular browsers, you might not be able to implement all the functions of the org.w3c.dom.html package.
One of the following errors is thrown:
- sun.plugin.dom.exception.InvalidStateException
- sun.plugin.dom.exception.NotSupportedException
Using DBCS parameters
The Java plug-in supports double-byte characters (for example, Chinese Traditional BIG-5, Korean, and Japanese) as parameters for the tags <APPLET>, <OBJECT>, and <EMBED>. You must select the correct character encoding for your HTML document so that the Java plug-in can parse the parameter.
About this task
Specify character encoding for your HTML document by using the <META> tag in the <HEAD> section like this:
<meta http-equiv="Content-Type" content="text/html; charset=big5">
This example tells the browser to use the Chinese BIG-5 character encoding to parse the HTML file.
Some older versions of browsers might not understand this tag correctly. In this case, you can force the browser to ignore this tag, but you might have to change the encoding manually. To manually specify which encoding you want to use to parse the HTML file:
- Mozilla Firefox
- View Menu > Character Coding
Working with applets
With the Applet Viewer, you can run one or more applets that are called by reference in a Web page (HTML file) by using the <APPLET> tag. The Applet Viewer finds the <APPLET> tags in the HTML file and runs the applets, in separate windows, as specified by the tags.
Because the Applet Viewer is for viewing applets, it cannot display a whole Web page that contains many HTML tags. It parses only the <APPLET> tags and no other HTML on the Web page.
Running and debugging applets with the Applet Viewer
Use the following commands to run and debug an applet with the Applet Viewer.
Procedure
- To run an applet with the Applet Viewer, enter the following
command: appletviewer <name>.
<name> is one of the following:
- The file name of an HTML file that calls an applet.
- The URL of a Web page that calls an applet.
For example, to start the Applet Viewer on an HTML file that calls an applet, type at a shell prompt:
appletviewer $HOME/<filename>.html
Where filename is the name of the HTML file.
To start the Applet Viewer on a Web page, type at a shell prompt:
appletviewer http://java.sun.com/applets/jdk/1.4/demo/applets/NervousText/ example1.html
The Applet Viewer does not recognize the charset option of the <
META
> tag. If the file that the Applet Viewer loads is not encoded as the system default, an I/O exception might occur. To avoid the exception, use the -encoding option when you run appletviewer. For example:
appletviewer -encoding JISAutoDetect sample.html
- To debug an applet with the Applet Viewer, use the debug parameter
with the appletviewer command.
For example:
cd demo/applets/TicTacToe ../../bin/appletviewer -debug example1.html
You can find documentation about how to debug applets using the Applet Viewer at the Oracle Web site: http://download.oracle.com/javase/1.5.0/docs/guide/plugin/developer_guide/debugger.html.
Java Applet Viewer and the classpath
If you use the Applet Viewer to run an applet that is in the CLASSPATH, you might get an AccessControlException in Swing. Because the CLASSPATH implicitly contains the current directory ".", this exception might occur if you run the Java Plug-in in the same directory that the applet class itself is in.
To work around this problem, ensure that:
- No CLASSPATH references exist to the applet that you are attempting to run in the Java Plug-in or the appletviewer.
- You are not running the applet from the same directory that the class is in.
Distributing Java applications
Java applications typically consist of class, resource, and data files.
When you distribute a Java application, your software package probably consists of the following parts:
- Your own class, resource, and data files
- AIX Runtime Environment (optional)
- An installation procedure or program
To run your application, a user needs the Runtime Environment for AIX. The SDK for AIX software contains a Runtime Environment. However, you cannot assume that your users have the SDK for AIX software installed.
Your application can either make the SDK for AIX a prerequisite or include a version of the SDK that is specifically for the purpose of redistribution. The SDK for AIX license does not allow you to redistribute any of the SDK files installed in /usr/java5_64/ by installp. You can redistribute the SDK files in the j664redist.tar or j664redist.tar.gz files (after viewing and agreeing to the associated online license) available from the AIX Java Web site: http://www.ibm.com/developerworks/java/jdk/aix/. Click the Download and service information link near the bottom of the page and follow the links to the Java download page.
Class data sharing between JVMs
Class data sharing enables multiple JVMs to share a single space in memory.
You can share data between Java Virtual Machines (JVMs) by storing it in a cache in shared memory. Sharing reduces the overall virtual storage consumption when more than one JVM shares a cache. Sharing also reduces the startup time for a JVM after the cache has been created. The shared class cache is independent of any active JVM and persists beyond the lifetime of the JVM that created the cache.
A shared cache can contain:
- Bootstrap classes
- Application classes
- Metadata that describes the classes
Overview of class data sharing
Class data sharing provides a method of reducing memory footprint and improving JVM start-up time.
Enabling class data sharing
Enable class data sharing by using the -Xshareclasses option when starting a JVM. The JVM connects to an existing cache or creates a new cache if one does not exist.
All bootstrap and application classes loaded by the JVM are shared by default. Custom class loaders share classes automatically if they extend the application class loader. Otherwise, they must use the Java Helper API provided with the JVM to access the cache. See Adapting custom class loaders to share classes.
Cache access
Any JVM connected to a cache can update the cache. Any number of JVMs can concurrently read from the cache, even while another JVM is writing to it.
You must take care if runtime bytecode modification is being used. See Runtime bytecode modification for more information.
Dynamic updating of the cache
The shared class cache persists beyond the lifetime of any JVM. Therefore, the cache is updated dynamically to reflect any modifications that might have been made to JARs or classes on the file system. The dynamic updating makes the cache independent of the application using it.
Cache security
Access to the shared class cache is limited by operating system permissions and Java security permissions. The shared class cache is created with user access by default unless the groupAccess command-line suboption is used. Only a class loader that has registered to share class data can update the shared class cache.
If a Java SecurityManager is installed, classloaders, excluding the default bootstrap, application, and extension class loaders, must be granted permission to share classes. Grant permission by adding SharedClassPermission lines to the java.policy file. See Using SharedClassPermission for more information. The RuntimePermission createClassLoader restricts the creation of new class loaders and therefore also restricts access to the cache.
Cache lifespan
Multiple caches can exist on a system and you specify them by name as a suboption to the -Xshareclasses command. A JVM can connect to only one cache at any one time.
You can override the default cache size on startup using -Xscmx<n><size>. This size is then fixed for the lifetime of the cache. Caches exist until they are explicitly deleted using a suboption to the -Xshareclasses command or until the system is rebooted.
Cache utilities
All cache utilities are suboptions to the -Xshareclasses command. See Class data sharing command-line options or use -Xshareclasses:help to see a list of available suboptions.
Class data sharing command-line options
Class data sharing and the cache management utilities are controlled using command-line options to the Java launcher.
For options that take a <size> parameter, suffix the number with "k" or "K" to indicate kilobytes, "m" or "M" to indicate megabytes, or "g" or "G" to indicate gigabytes.
- -Xscmx<size>
- Specifies cache size. This option applies only if a cache is being created and no cache of the same name exists. The default cache size is platform-dependent. You can find out the size value being used by adding -verbose:sizes as a command-line argument. The minimum cache size is 4 KB. The maximum cache size is also platform-dependent. (See Cache size limits.)
- -Xshareclasses:<suboption>[,<suboption>...]
- Enables class data sharing. Can take a number of suboptions, some
of which are cache utilities. Cache utilities perform the required
operation on the specified cache, without starting the VM. You can
combine multiple suboptions, separated by commas, but the cache utilities
are mutually exclusive. When running cache utilities, the message Could
not create the Java virtual
machine is expected. Cache utilities do not create the virtual
machine.
You can use the following suboptions with the -Xshareclasses option:
- help
- Lists all the command-line suboptions.
- name=<name>
- Connects to a cache of a given name, creating the cache if it does not already exist. Also used to indicate the cache that is to be modified by cache utilities; for example, destroy. Use the listAllCaches 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. You can specify "%g" in the cache name to insert the current group name.
- groupAccess
- Sets operating system permissions on a new cache to allow group access to the cache. The default is user access only.
- verbose
- Enables verbose output, which provides overall status on the shared class cache and more detailed error messages.
- verboseIO
- Gives detailed output on the cache I/O activity, listing information on classes being 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 usual to see many failed requests; this behavior is expected for the class loader hierarchy.
- verboseHelper
- Enables verbose output for the Java Helper API. This output shows you how the Helper API is used by your class loader.
- silent
- Turns off all shared classes messages, including error messages. Unrecoverable error messages, which prevent the JVM from initializing, are displayed.
- nonfatal
- Allows the JVM to start even if class data sharing fails. Normal behavior for the JVM is to refuse to start if class data sharing fails. If you select nonfatal and the shared classes cache fails to initialize, the JVM starts without class data sharing.
- none
- 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.
- modified=<modified context>
- Used when a JVMTI agent is installed that might modify bytecode at runtime. 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 chosen by the user; for example, "myModification1". This option partitions the cache, so that only JVMs using context myModification1 can share the same classes. For instance, if you run HelloWorld with a modification context and then run it again with a different modification context, all classes are stored twice in the cache. See Runtime bytecode modification for more information.
- destroy (Utility option)
- Destroys a cache using the name specified in the name=<name> suboption. If the name is not specified, the default cache is destroyed. A cache can be destroyed only if all VMs using it have shut down, and the user has sufficient permissions.
- destroyAll (Utility option)
- Tries to destroy all caches available to the user. A cache can be destroyed only if all VMs using it have shut down, and the user has sufficient permissions.
- expire=<time in minutes>
- Destroys all caches that have been unused for the time specified before loading shared classes. This option is not a utility option because it does not cause the JVM to exit.
- listAllCaches (Utility option)
- Lists all the caches on the system, describing if they are in use and when they were last used.
- printStats (Utility option)
- Displays summary statistics information about the cache specified in the name=<name> suboption. If the name is not specified, statistics are displayed about the default cache. The most useful information displayed is how full the cache is and how many classes it contains. Stale classes are classes that have been updated on the file system and which the cache has therefore marked "stale". Stale classes are not purged from the cache and can be reused. See the Diagnostics Guide for more information.
- printAllStats (Utility option)
- Displays detailed information for the cache specified
by the name suboption. Every class is listed
in chronological order, with a reference to the location from which
it was loaded.
See the Diagnostics Guide for more information.
Creating, populating, monitoring, and deleting a cache
An overview of the life-cycle of a shared class data cache including examples of the cache management utilities.
To enable class data sharing, add -Xshareclasses[:name=<name>] to your application command line.
The JVM either connects to an existing cache of the given name or creates a new cache of that name. If a new cache is created, it is populated with all bootstrap and application classes being loaded until the cache becomes full. If two or more JVMs are started concurrently, they populate the cache concurrently.
To check that the cache has been created, run java -Xshareclasses:listAllCaches. To see how many classes and how much class data is being shared, run java -Xshareclasses:[name=<name>],printStats. You can run these utilities after the application JVM has terminated or in another command window.
For more feedback on cache usage while the JVM is running, use the verbose suboption. For example, java -Xshareclasses:[name=<name>],verbose.
To see classes being loaded from the cache or stored in the cache, add -Xshareclasses:[name=<name>],verboseIO to your application command line.
To delete the cache, run java -Xshareclasses:[name=<name>],destroy. You usually delete caches only if they contain many stale classes or if the cache is full and you want to create a bigger cache.
You should tune the cache size for your specific application, because the default is unlikely to be the optimum size. To determine the optimum cache size, specify a large cache, using -Xscmx, run the application, and then use printStats to determine how much class data has been stored. Add a small amount to the value shown in printStats for contingency. Because classes can be loaded at any time during the lifetime of the JVM, it is best to do this analysis after the application has terminated. However, a full cache does not have a negative affect on the performance or capability of any JVMs connected to it, so it is acceptable to decide on a cache size that is smaller than required.
If a cache becomes full, a message is displayed on the command line of any JVMs using the verbose suboption. All JVMs sharing the full cache then loads any further classes into their own process memory. Classes in a full cache can still be shared, but a full cache is read-only and cannot be updated with new classes.
Performance and memory consumption
Class data sharing is particularly useful on systems that use more than one JVM running similar code; the system benefits from reduced virtual storage consumption. It is also useful on systems that frequently start and shut down JVMs, which benefit from the improvement in startup time.
The processor and memory usage required to create and populate a new cache is minimal. The JVM startup cost in time for a single JVM is typically between 0 and 5% slower compared with a system not using class data sharing, depending on how many classes are loaded. JVM startup time improvement with a populated cache is typically between 10% and 40% faster compared with a system not using class data sharing, depending on the operating system and the number of classes loaded. Multiple JVMs running concurrently show greater overall startup time benefits.
Duplicate classes are consolidated in the shared class cache. For example, class A loaded from myClasses.jar and class A loaded from myOtherClasses.jar (with identical content) is stored only once in the cache. The printAllStats utility shows multiple entries for duplicated classes, with each entry pointing to the same class.
When you run your application with class data sharing, you can use the operating system tools to see the reduction in virtual storage consumption.
Considerations and limitations of using class data sharing
Consider these factors when deploying class data sharing in a product and using class data sharing in a development environment.
Cache size limits
The maximum theoretical cache size is 2 GB. The size of cache you can specify is limited by the amount of physical memory and paging space available to the system.
The cache for sharing classes is allocated using the System V IPC Shared memory mechanism.
Because the virtual address space of a process is shared between the shared classes cache and the Java heap, if you increase the maximum size of the Java heap you might reduce the size of the shared classes cache you can create.
The virtual address space available to the process is 1 TB on AIX 5.2, and 32 TB on AIX 5.3.
Runtime bytecode modification
Any JVM using a JVM Tool Interface (JVMTI) agent that can modify bytecode data must use the modified=<modified_context> suboption if it wants to share the modified classes with another JVM.
The modified context is a user-specified descriptor that describes the type of modification being performed. The modified context partitions the cache so that all JVMs running under the same context share a partition.
This partitioning allows JVMs that are not using modified bytecode to safely share a cache with those that are using modified bytecode. All JVMs using a given modified context must modify bytecode in a predictable, repeatable manner for each class, so that the modified classes stored in the cache have the expected modifications when they are loaded by another JVM. Any modification must be predictable because classes loaded from the shared class cache cannot be modified again by the agent.
If a JVMTI agent is used without a modification context, classes are still safely shared by the JVM, but with a small affect on performance. Using a modification context with a JVMTI agent avoids the need for extra checks and therefore has no affect on performance. A custom ClassLoader that extends java.net.URLClassLoader and modifies bytecode at load time without using JVMTI automatically stores that modified bytecode in the cache, but the cache does not treat the bytecode as modified. Any other VM sharing that cache loads the modified classes. You can use the modified=<modification_context> suboption in the same way as with JVMTI agents to partition modified bytecode in the cache. If a custom ClassLoader needs to make unpredictable load-time modifications to classes, that ClassLoader must not attempt to use class data sharing.
See the Diagnostics Guide for more detail on this topic.
Operating system limitations
You cannot share classes between 32-bit and 64-bit JVMs. Temporary disk space must be available to hold cache information. The operating system enforces cache permissions.
For operating systems that can run both 32-bit and 64-bit applications, class data sharing is not permitted between 32-bit and 64-bit JVMs. The listAllCaches suboption lists 32-bit or 64-bit caches, depending on the address mode of the JVM being used.
The shared class cache requires disk space to store identification information about the caches that exist on the system. This information is stored in /tmp/javasharedresources. If the identification information directory is deleted, the JVM cannot identify the shared classes on the system and must re-create the cache. Use the ipcs command to view the memory segments used by a JVM or application.
Users running a JVM must be in the same group to use a shared class cache. The operating system enforces the permissions for accessing a shared class cache. If you do not specify a cache name, the user name is appended to the default name so that multiple users on the same system create their own caches by default.
Using SharedClassPermission
If a SecurityManager is being used with class data sharing and the running application uses its own class loaders, you must grant these class loaders shared class permissions before they can share classes.
You add shared class permissions to the java.policy file using the ClassLoader class name (wildcards are permitted) and either "read", "write", or "read,write" to determine the access granted. For example:
permission com.ibm.oti.shared.SharedClassPermission "com.abc.customclassloaders.*", "read,write";
If a ClassLoader does not have the correct permissions, it is prevented from sharing classes. You cannot change the permissions of the default bootstrap, application, or extension class loaders.
Adapting custom class loaders to share classes
Any class loader that extends java.net.URLClassLoader can share classes without modification. You must adopt class loaders that do not extend java.net.URLClassLoader to share class data.
You must grant all custom class loaders shared class permissions if a SecurityManager is being used; see Using SharedClassPermission. IBM provides several Java interfaces for various types of custom class loaders, which allow the class loaders to find and store classes in the shared class cache. These classes are in the com.ibm.oti.shared package.
The Javadoc document for this package is provided with the SDK in the docs/apidoc.zip file.
See the Diagnostics Guide for more information about how to use these interfaces.
Java Communications API (JavaComm)
The Java Communications (API) package (JavaComm) is an optional package provided for use with the Runtime Environment for AIX. You install JavaComm independently of the SDK or Runtime Environment.
The JavaComm API gives Java applications a platform-independent way of performing serial and parallel port communications for technologies such as voice mail, fax, and smartcards.
The Java Communications API supports Electronic Industries Association (EIA)-232 (RS232) serial ports and Institute of Electrical and Electronics Engineers (IEEE) 1284 parallel ports and is supported on systems with the IBM Version 5.0 Runtime Environment.
Using the Java Communications API, you can:
- List ports on a system
- Open and claim ownership of ports
- Resolve port ownership contention among applications that use Java Communications API
- Perform asynchronous and synchronous I/O port-monitoring using event notification
- Receive bean-style events describing state changes on the port
The API is shipped in the Java5_64.ext.commapi fileset (optionally installable).
Location of the Java Communications API files
By default, the Java Communications API files are installed in the /usr/java5_64/ directory.
The files and their structure are:
- jre/lib/ext/comm.jar
- jre/bin/libibmcomm.so
- jre/lib/javax.comm.properties
Mapping serial ports
The Java communications API supports an unlimited number of tty's, with ttyn mapped to COM(n+1).
For example:
/dev/tty0 -> COM1 /dev/tty1 -> COM2 ... /dev/tty9 -> COM10 /dev/tty10 -> COM11 ...
If a tty is not available, the corresponding COM port is not available. For example, if tty0 and tty2 are available but tty1 is not, COM1 and COM3 are available but COM2 is not.
Configuring the Java Communications API
To use the Java Communications API, you must change the access mode of serial and parallel ports, and set the PATH if you did not set it when you installed Java.
About this task
See Setting the path.
Specifying devices in the javax.comm.properties file
Use the javax.comm.properties file to specify the devices and drivers that are available to the Java Communications API and whether they are parallel or serial. Do not change this file without a very clear understanding of its use.
About this task
Port numbers are allocated sequentially to all devices. For example, if you specify /dev/ttyS=PORT_SERIAL and the devices /dev/ttyS0 and /dev/ttyS1 exist, they will be allocated COM1 and COM2.
To use the USB-serial connectors, uncomment the line /dev/ttyUSB=PORT_SERIAL in the javax.comm.properties file. If the devices /dev/ttyUSB0 and /dev/ttyUSB1 exist and COM1 and COM2 have already been defined, the USB-serial devices are allocated the next sequential ports, COM3 and COM4.
Printing limitation with the Java Communications API
When printing with the Java Communications API, you might have to select "Form feed", "Continue", or a similar option on the printer.
The Java Communications API documentation
You can find API documentation and samples for the Java Communications API at the Oracle Web site.
http://www.oracle.com/technetwork/java/index-jsp-141752.html.
Service and support for independent software vendors
Contact points for service:
If you are entitled to services for the Program code pursuant to the IBM Solutions Developer Program, contact the IBM Solutions Developer Program through your usual method of access or on the Web at: http://www.ibm.com/partnerworld/.
If you have purchased a service contract (that is, the IBM Personal Systems Support Line or equivalent service by country), the terms and conditions of that service contract determine what services, if any, you are entitled to receive with respect to the Program.
Accessibility
The user guides that are supplied with this SDK and the Runtime Environment have been tested using screen readers.
To change the font sizes in the user guides, use the function that is supplied with your browser, typically found under the View menu option.
For users who require keyboard navigation, a description of useful keystrokes for Swing applications is in Swing Key Bindings at http://www.ibm.com/developerworks/java/jdk/additional/.
Keyboard traversal of JComboBox components in Swing
If you traverse the drop-down list of a JComboBox component with the cursor keys, the button or editable field of the JComboBox does not change value until an item is selected. This is the correct behavior for this release and improves accessibility and usability by ensuring that the keyboard traversal behavior is consistent with mouse traversal behavior.
Any comments on this user guide?
If you have any comments about this user guide, contact us through one of the following channels. Note that these channels are not set up to answer technical queries, but are for comments about the documentation only.
Send your comments:
- By e-mail to idrcf@hursley.ibm.com.
- By fax:
- From the UK: 01962 842327
- From elsewhere: +44 1962 842327
- By mail to:
IBM United Kingdom Ltd
User Technologies,
Mail Point 095
Hursley Park
Winchester
Hampshire
SO21 2JN
United Kingdom
The fine print. By choosing to send a message to IBM, you acknowledge that all information contained in your message, including feedback data, such as questions, comments, suggestions, or the like, shall be deemed to be non-confidential and IBM shall have no obligation of any kind with respect to such information and shall be free to reproduce, use, disclose, and distribute the information to others without limitation. Further, IBM shall be free to use any ideas, concepts, know-how or techniques contained in such information for any purpose whatsoever, including, but not limited to, developing, manufacturing and marketing products incorporating such information.
Appendix A. Command-line options
You can specify the options on the command line while you are starting Java. They override any relevant environment variables. For example, using -cp <dir1> with the Java command completely overrides setting the environment variable CLASSPATH=<dir2>.
Specifying command-line options
Although the command line is the traditional way to specify command-line options, you can pass options to the JVM in other ways.
Use only single or double quotation marks for command-line options when explicitly directed to do so for the option in question. Single and double quotation marks have different meanings on different platforms, operating systems, and shells. Do not use '-X<option>' or "-X<option>". Instead, you must use -X<option>. For example, do not use '-Xmx500m' and "-Xmx500m". Write this option as -Xmx500m.
These precedence rules (in descending order) apply to specifying options:
- Command line.
For example, java -X<option> MyClass
- A file containing a list of options, specified using the -Xoptionsfile option
on the command line. For example, java -Xoptionsfile=myoptionfile.txt
MyClass
In the options file, specify each option on a new line; you can use the '\' character as a continuation character if you want a single option to span multiple lines. Use the '#' character to define comment lines. You cannot specify -classpath in an options file. Here is an example of an options file:
#My options file -X<option1> -X<option2>=\ <value1>,\ <value2> -D<sysprop1>=<value1>
- IBM_JAVA_OPTIONS environment variable. You can set command-line
options using this environment variable. The options that you specify
with this environment variable are added to the command line when
a JVM starts in that environment.
For example, set IBM_JAVA_OPTIONS=-X<option1> -X<option2>=<value1>
General command-line options
Use these options to print help on assert-related options, set the search path for application classes and resources, print a usage method, identify memory leaks inside the JVM, print the product version and continue, enable verbose output, and print the product version.
- -assert
- Prints help on assert-related options.
- -cp, -classpath <directories and compressed or jar files separated by : (; on Windows)>
- Sets the search path for application classes and resources. If -classpath and -cp are not used, and the CLASSPATH environment variable is not set, the user classpath is, by default, the current directory (.).
- -help, -?
- Prints a usage message.
- -memorycheck[:<option>]
- Identifies memory leaks inside the JVM using strict checks that
cause the JVM to exit on failure. If no option is specified, all is
used by default. Options are:
- all
- The default if -memorycheck only is used. This option enables checking of all allocated and freed blocks on every free and allocate call. This check of the heap is the most thorough. It causes the JVM to exit on nearly all memory-related problems soon after they are caused. This option has the greatest affect on performance.
- callsite=<number of allocations>
- Prints callsite information every <number of allocations>.
Deallocations are not counted. Callsite information is presented in
a table with separate information for each callsite. Statistics include
the number and size of allocation and free requests since the last
report, and the number of the allocation request responsible for the
largest allocation from each site. Callsites are presented as sourcefile:linenumber for
C code and assembly function name for assembler code.
Callsites that do not provide callsite information are accumulated into an "unknown" entry.
- Prints callsite information every <number of allocations>.
Deallocations are not counted. Callsite information is presented in
a table with separate information for each callsite. Statistics include
the number and size of allocation and free requests since the last
report, and the number of the allocation request responsible for the
largest allocation from each site. Callsites are presented as sourcefile:linenumber for
C code and assembly function name for assembler code.
- failat=<number of allocations>
- Causes memory allocation to fail (return NULL) after <number of allocations>. Setting <number of allocations> to 13 causes the 14th allocation to return NULL. Deallocations are not counted. Use this option to ensure that JVM code reliably handles allocation failures. This option is useful for checking allocation site behavior rather than setting a specific allocation limit.
- nofree
- Keeps a list of already used blocks instead of freeing memory. This list is checked, along with currently allocated blocks, for memory corruption on every allocation and deallocation. Use this option to detect a dangling pointer (a pointer that is "dereferenced" after its target memory is freed). This option cannot be reliably used with long-running applications (such as WebSphere Application Server), because "freed" memory is never reused or released by the JVM.
- quick
- Enables block padding only. Used to detect basic heap corruption. Pads every allocated block with sentinel bytes, which are verified on every allocate and free. Block padding is faster than the default of checking every block, but is not as effective.
- skipto=<number of allocations>
- Causes the program to check only on allocations that occur after <number of allocations>. Deallocations are not counted. Used to speed up JVM startup when early allocations are not causing the memory problem. As a rough estimate, the JVM performs 250+ allocations during startup.
- zero
- Newly allocated blocks are set 0 instead of being filled with the 0xE7E7xxxxxxxxE7E7 pattern. Setting to 0 helps you to determine whether a callsite is expecting zeroed memory (in which case after the allocation request by using the instruction memset(pointer, 0, size)).
- all
- -showversion
- Prints product version and continues.
- -verbose:<option>[,<option>...]
- Enables verbose output. Separate multiple options using commas.
These options are available:
- class
- Writes an entry to stderr for each class that is loaded.
- dynload
- Provides detailed information as each bootstrap class is loaded
by the JVM:
- The class name and package
- For class files that were in a .jar file, the name and directory path of the .jar
- Details of the size of the class and the time taken to load the class
<Loaded java/lang/String from C:\sdk\jre\lib\vm.jar> <Class size 17258; ROM size 21080; debug size 0> <Read time 27368 usec; Load time 782 usec; Translate time 927 usec>
- gc
- Provide verbose garbage collection information.
- init
- Writes information to stderr describing JVM initialization and termination.
- jni
- Writes information to stderr describing the JNI services called by the application and JVM.
- sizes
- Writes information to stderr describing the active memory usage settings.
- stack
- Writes information to stderr describing the Java and C stack usage for each thread.
- -version
- Prints product version.
System property command-line options
Use the system property command-line options to set up your system.
- -D<name>=<value>
- Sets a system property.
- -DCLONE_HASHTABLE_FOR_SYNCHRONIZATION
- Deadlocks can occur when serializing multiple java.util.Hashtables that refer to each other in different threads at the same time. Using this command-line option can resolve the deadlock, by forcing the JVM to take a copy of every java.util.Hashtable before this hashtable is serialized. Because this process requires temporary storage, and uses additional processing power, the option is not enabled by default.
- -Dcom.ibm.jsse2.renegotiate=[ALL | NONE | ABBREVIATED]
- If your Java application
uses JSSE for secure communication, you can disable TLS renegotiation
by installing APAR IZ65239.
- ALL
- Allow both abbreviated and unabbreviated (full) renegotiation handshakes.
- NONE
- Allow no renegotiation handshakes. This value is the default setting.
- ABBREVIATED
- Allow only abbreviated renegotiation handshakes.
- -Dcom.ibm.lang.management.verbose
- Enables verbose information from java.lang.management operations to be written to output channel during VM operation.
-Dcom.ibm.IgnoreMalformedInput=true
From Java 5 SR12, any invalid UTF8 or malformed byte sequences are replaced with the standard unicode replacement character \uFFFD. To retain the old behavior, where invalid UTF8 or malformed byte sequences are ignored, set this system property to true.
- -Dcom.ibm.nio.DirectByteBuffer.AggressiveMemoryManagement=true
- Use this property to increase dynamically the native memory limit for Direct Byte Buffers, based on their usage. This option is applicable when a Java application uses many Direct Byte Buffer objects, but cannot predict the maximum native memory consumption of the objects. Do not use the -Xsun.nio.MaxDirectMemorySize option with this property.
-Dcom.ibm.nio.useIBMAlias=true
The IBM JVM cannot display all the Big5-HKSCS characters when using the NIO converter. By specifying the -Dcom.ibm.nio.useIBMAlias=true option, you can use the ICU4J API to display Big5-HKSCS characters without modifying the application.
- -Dcom.ibm.tools.attach.enable=yes
- Enable the Attach API for this application. The Attach API allows your application to connect to a virtual machine. Your application can then load an agent application into the virtual machine. The agent can be used to perform tasks such as monitoring the virtual machine status.
-Dcom.ibm.zipfile.closeinputstreams=true
The Java.util.zip.ZipFile class allows you to create InputStreams on files held in a compressed archive. Under some conditions, using ZipFile.close() to close all InputStreams that have been opened on the compressed archive might result in a 56-byte-per-InputStream native memory leak. Setting the -Dcom.ibm.zipfile.closeinputstreams=true forces the JVM to track and close InputStreams without the memory impact caused by retaining native-backed objects. Native-backed objects are objects that are stored in native memory, rather than the Java heap. By default, the value of this system property is false.
- -Dibm.jvm.bootclasspath
- The value of this property is used as an additional search path, which is inserted between any value that is defined by -Xbootclasspath/p: and the bootclass path. The bootclass path is either the default or the one that you defined by using the -Xbootclasspath: option.
- -Dibm.stream.nio=[true | false]
- From v1.4.1 onwards, by default the IO converters are used. This option addresses the ordering of IO and NIO converters. When this option is set to true, the NIO converters are used instead of the IO converters.
- -Djava.compiler=[NONE | j9jit23]
- Disables the Java compiler by setting to NONE. Enable JIT compilation by setting to j9jit23 (Equivalent to -Xjit).
-Dsun.awt.keepWorkingSetOnMinimize=true
When a Java application using the Abstract Windowing Toolkit (AWT) is minimized, the default behavior is to "trim" the "working set". The working set is the application memory stored in RAM. Trimming means that the working set is marked as being available for swapping out if the memory is required by another application. The advantage of trimming is that memory is available for other applications. The disadvantage is that a "trimmed" application might experience a delay as the working set memory is brought back into RAM.
The -Dsun.awt.keepWorkingSetOnMinimize=true system property stops the JVM trimming an application when it is minimized. The default behavior is to trim an application when it is minimized.
- -Dsun.net.client.defaultConnectTimeout=<value in milliseconds>
- Specifies the default value for the connect timeout for the protocol
handlers used by the java.net.URLConnection class. The default value
set by the protocol handlers is -1, which means that no timeout is
set.
When a connection is made by an applet to a server and the server does not respond properly, the applet might seem to hang. The delay might also cause the browser to hang. The apparent hang occurs because there is no network connection timeout. To avoid this problem, the Java Plug-in has added a default value to the network timeout of 2 minutes for all HTTP connections. You can override the default by setting this property.
- -Dsun.net.client.defaultReadTimeout=<value in milliseconds>
- Specifies the default value for the read timeout for the protocol handlers used by the java.net.URLConnection class when reading from an input stream when a connection is established to a resource. The default value set by the protocol handlers is -1, which means that no timeout is set.
- -Dsun.nio.MaxDirectMemorySize=<value in bytes>
- Limits the native memory size for nio Direct Byte Buffer objects to the value specified.
- -Dsun.rmi.transport.tcp.connectionPool=[true | any non-null value]
- Enables thread pooling for the RMI ConnectionHandlers in the TCP transport layer implementation.
- -Dsun.timezone.ids.oldmapping=[true | false]
- From v5.0 Service Refresh 1 onwards, the Java Virtual Machine uses new time zone identifiers. The identifiers change the definitions of Eastern Standard Time (EST) and Mountain Standard Time (MST). These new definitions do not take daylight saving time (DST) into account. If this property is set to true, the definitions for EST and MST revert to the definitions that were used before v5.0 Service Refresh 1, and DST is taken into account. By default, this property is set to true.
- -Dswing.useSystemFontSettings=[false]
- From v1.4.1 onwards, by default, Swing programs running with the Windows Look and Feel render with the system font set by the user instead of a Java-defined font. As a result, fonts for v1.4.1 differ from the fonts in earlier releases. This option addresses compatibility problems like these for programs that depend on the old behavior. By setting this option, v1.4.1 fonts and those of earlier releases are the same for Swing programs running with the Windows Look and Feel.
JVM command-line options
Use these options to configure your JVM. The options prefixed with -X are nonstandard.
For options that take a <size> parameter, suffix the number with "k" or "K" to indicate kilobytes, "m" or "M" to indicate megabytes, or "g" or "G" to indicate gigabytes.
For options that take a <percentage> parameter, use a number from 0 to 1. For example, 50% is 0.5.
Options that relate to the JIT are listed under JIT command-line options. Options that relate to the Garbage Collector are listed under Garbage Collector command-line options.
- -X
- Displays help on nonstandard options.
- -Xargencoding
- You can put Unicode escape sequences in the argument list. This option is set to off by default.
- -Xbootclasspath:<directories and compressed or Java archive files separated by : (; on Windows)>
- Sets the search path for bootstrap classes and resources. The default is to search for bootstrap classes and resources in the internal VM directories and .jar files.
- -Xbootclasspath/a:<directories and compressed or Java archive files separated by : (; on Windows)>
- Appends the specified directories, compressed files, or jar files to the end of the bootstrap class path. The default is to search for bootstrap classes and resources in the internal VM directories and .jar files.
- -Xbootclasspath/p:<directories and compressed or Java archive files separated by : (; on Windows)>
- Adds a prefix of the specified directories, compressed files, or Java archive files to the front of the bootstrap class path. Do not deploy applications that use the -Xbootclasspath: or the -Xbootclasspath/p: option to override a class in the standard API. The reason is that such a deployment contravenes the Java 2 Runtime Environment binary code license. The default is to search for bootstrap classes and resources in the internal VM directories and .jar files.
- -Xcheck:jni[:help][:<option>=<value>]
- Performs additional checks for JNI functions. This option is equivalent to -Xrunjnichk. By default, no checking is performed.
- -Xclassgc
- Enables dynamic unloading of classes by the JVM. This unloading is the default behavior. To disable dynamic class unloading, use the -Xnoclassgc option.
- -Xdbg:<options>
- Loads debugging libraries to support the remote debugging of applications. This option is equivalent to -Xrunjdwp. By default, the debugging libraries are not loaded, and the VM instance is not enabled for debug.
- -Xdbginfo:<path to symbol file>
- Loads and passes options to the debug information server. By default, the debug information server is disabled.
- -Xdebug
- This option is deprecated. Use -Xdbg for debugging.
- -Xdiagnosticscollector[:settings=<filename>]
- Enables the Diagnostics Collector. See the Diagnostics Guide (http://www.ibm.com/developerworks/java/jdk/diagnosis/50.html) section on "The Diagnostics Collector" for more information. The settings option allows you to specify a different Diagnostics Collector settings file to use instead of the default dc.properties file in the JRE.
- -Xdisablejavadump
- Turns off Javadump generation on errors and signals. By default, Javadump generation is enabled.
- -Xdump
- See the Diagnostics Guide (http://www.ibm.com/developerworks/java/jdk/diagnosis/50.html) section on "Using dump agents" for more information.
- -Xenableexplicitgc
- Signals to the VM that calls to System.gc() trigger a garbage collection. This option is enabled by default.
- -Xfuture
- Turns on strict class-file format checks. Use this flag when you are developing new code because stricter checks will become the default in future releases. By default, strict format checks are disabled.
- -Xiss<size>
- Sets the initial stack size for Java threads. By default, the stack size is set to 2 KB. Use the -verbose:sizes option to output the value that the VM is using.
- -Xjarversion
- Produces output information about the version of each jar file in the class path, the boot class path, and the extensions directory. Version information is taken from the Implementation-Version and Build-Level properties in the manifest of the jar.
- -Xjni:<suboptions>
- Sets JNI options. You can use the following suboption with the -Xjni option:
- -Xjni:arrayCacheMax=[<size in bytes>|unlimited]
- Sets the maximum size of the array cache. The default size is 8096 bytes.
- -Xlinenumbers
- Displays line numbers in stack traces for debugging. See also -Xnolinenumbers. By default, line numbers are on.
- -XlockReservation
- Enables an optimization that presumes a monitor is owned by the thread that last acquired it. The optimization minimizes the runtime cost of acquiring and releasing a monitor for a single thread if the monitor is rarely acquired by multiple threads.
- -Xlog
-
Enables message logging. To prevent message logging, use the -Xlog:none option. By default, logging is enabled. This option is available from Java 5 SR10. See Messages.
- -Xlp<size> (AIX, Windows, and Linux (x86, PPC32, PPC64, AMD64, EM64T))
- AIX: Requests the JVM to allocate the Java heap (the heap from which Java objects are allocated) with large (16 MB) pages, if a size is not specified. If large pages are not available, the Java heap is allocated with the next smaller page size that is supported by the system. AIX requires special configuration to enable large pages. For more information about configuring AIX support for large pages, see http://publib.boulder.ibm.com/infocenter/aix/v6r1/topic/com.ibm.aix.prftungd/doc/prftungd/large_page_ovw.htm. The SDK supports the use of large pages only to back the Java heap shared memory segments. The JVM uses shmget() with the SHM_LGPG and SHM_PIN flags to allocate large pages. The -Xlp option replaces the environment variable IBM_JAVA_LARGE_PAGE_SIZE, which is now ignored if set.
- -Xmso<size>
Sets the initial stack size for operating system threads. The default value can be determined by running the command:
java -verbose:sizes
The maximum value for the stack size varies according to platform and specific machine configuration. If you exceed the maximum value, a java/lang/OutOfMemoryError message is reported.- -Xmxcl<number>
- Sets the maximum number of class loaders. See the Diagnostics Guide (http://www.ibm.com/developerworks/java/jdk/diagnosis/50.html) section on "The parent-delegation model" for a description of a problem that can occur on some JVMs if this number is set too low.
- -Xnoagent
- Disables support for the old JDB debugger.
- -Xnoclassgc
- Disables dynamic class unloading. This option disables the release of native and Java heap storage associated with Java class loaders and classes that are no longer being used by the JVM. The default behavior is as defined by -Xclassgc. Enabling this option is not recommended except under the direction of the IBM Java support team. The reason is the option can cause unlimited native memory growth, leading to out-of-memory errors.
- -Xnolinenumbers
- Disables the line numbers for debugging. See also -Xlinenumbers. By default, line number are on.
- -Xnosigcatch
- Disables JVM signal handling code. See also -Xsigcatch. By default, signal handling is enabled.
- -Xnosigchain
- Disables signal handler chaining. See also -Xsigchain. By default, the signal handler chaining is enabled.
- -Xoptionsfile=<file>
-
Specifies a file that contains JVM options and definitions. By default, no option file is used.
The options file does not support these options:
- -assert
- -fullversion
- -help
- -memorycheck
- -showversion
- -version
- -Xjarversion
- -Xoptionsfile
Although you cannot use -Xoptionsfile recursively within an options file, you can use -Xoptionsfile multiple times on the same command line to load more than one options files.
<file> contains options that are processed as if they had been entered directly as command-line options. For example, the options file might contain:
-DuserString=ABC123 -Xmx256MB
Some options use quoted strings as parameters. Do not split quoted strings over multiple lines using the line continuation character '\'. The '¥' character is not supported as a line continuation character. For example, the following example is not valid in an options file:
-Xevents=vmstop,exec="cmd /c \ echo %pid has finished."
The following example is valid in an options file:
-Xevents=vmstop, \ exec="cmd /c echo %pid has finished."
- -Xoss<size>
Recognized but deprecated. Use -Xss and -Xmso. Sets the maximum Java stack size for any thread. The maximum value for the stack size varies according to platform and specific machine configuration. If you exceed the maximum value, a java/lang/OutOfMemoryError message is reported.
- -Xrdbginfo:<host>:<port>
- Loads the remote debug information server with the specified host and port. By default, the remote debug information server is disabled.
- -Xrs
- Disables
signal handling in the JVM. Setting -Xrs prevents
the Java runtime from handling
any internally or externally generated signals such as SIGSEGV and SIGABRT.
Any signals raised are handled by the default operating system handlers.
Disabling signal handling in the JVM reduces performance by approximately
2-4%, depending on the application.
Note: Linux always uses SIGUSR1.
-Xrs:sync
On UNIX systems, this option disables signal handling in the JVM for SIGSEGV, SIGFPE, SIGBUS, SIGILL, SIGTRAP, and SIGABRT signals. However, the JVM still handles the SIGQUIT and SIGTERM signals, among others. As with -Xrs, the use of -Xrs:sync reduces performance by approximately 2-4%, depending on the application.
- -Xrun<library name>[:<options>]
- This option has been superseded; use the -agentlib option
instead. For more information about -agentlib,
see http://publib.boulder.ibm.com/infocenter/javasdk/v6r0/index.jsp?topic=/com.ibm.java.doc.diagnostics.60/diag/tools/jvmti.html.
-Xrun loads helper libraries. To load multiple libraries, specify it more than once on the command line. Examples of these libraries are:
- -Xrunhprof[:help] | [:<option>=<value>, ...]
- Performs heap, CPU, or monitor profiling.
- -Xrunjdwp[:help] | [:<option>=<value>, ...]
- Loads debugging libraries to support the remote debugging of applications. This option is the same as -Xdbg.
- -Xrunjnichk[:help] | [:<option>=<value>, ...]
- Deprecated. Use -Xcheck:jni instead.
- -Xscmx<size>
- Specifies cache size. This option applies only if a cache is being created and no cache of the same name exists. The default cache size is platform-dependent. You can find out the size value being used by adding -verbose:sizes as a command-line argument. Minimum cache size is 4 KB. Maximum cache size is platform-dependent. The size of cache that you can specify is limited by the amount of physical memory and paging space available to the system. The virtual address space of a process is shared between the shared classes cache and the Java heap. Increasing the maximum size of the Java heap reduces the size of the shared classes cache that you can create.
- -Xshareclasses:<suboptions>
-
Enables class sharing. This option can take a number of suboptions, some of which are cache utilities. Cache utilities perform the required operation on the specified cache, without starting the VM. You can combine multiple suboptions, separated by commas, but the cache utilities are mutually exclusive.
You can use the following suboptions with the -Xshareclasses option:
- destroy (Utility option)
- Destroys a cache using the name specified in the name=<name> suboption. If the name is not specified, the default cache is destroyed. A cache can be destroyed only if all virtual machines using it have shut down, and the user has sufficient permissions.
- destroyAll (Utility option)
- Tries to destroy all caches available to the user. A cache can be destroyed only if all virtual machines using it have shut down, and the user has sufficient permissions.
- expire=<time in minutes> (Utility option)
- Destroys all caches that have been unused for the time specified before loading shared classes. This option is not a utility option because it does not cause the JVM to exit.
- groupAccess
- Sets operating system permissions on a new cache to allow group access to the cache. The default is user access only.
- help
- Lists all the command-line options.
- listAllCaches (Utility option)
- Lists all the caches on the system, describing if they are in use and when they were last used.
- 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 chosen by the user; for example, myModification1. This option partitions the cache, so that only JVMs using context myModification1 can share the same classes. For instance, if 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. See the Diagnostics Guide (http://www.ibm.com/developerworks/java/jdk/diagnosis/50.html) section "Dealing with runtime bytecode modification" for more information.
- 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 the listAllCaches 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. You can specify "%g" in the cache name to insert the current group name.
- 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.
- nonfatal
- Allows the JVM to start even if class data sharing fails. Normal behavior for the JVM is to refuse to start if class data sharing fails. If you select nonfatal and the shared classes cache fails to initialize, the JVM starts without class data sharing.
- printAllStats (Utility option)
- Displays detailed information about the contents of the cache specified in the name=<name> suboption. If the name is not specified, statistics are displayed about the default cache. Every class is listed in chronological order with a reference to the location from which it was loaded. See the Diagnostics Guide (http://www.ibm.com/developerworks/java/jdk/diagnosis/50.html) section on the "printAllStats utility" for more information.
- printStats (Utility option)
- Displays summary statistics information about the cache specified in the name=<name> suboption. If the name is not specified, statistics are displayed about the default cache. The most useful information displayed is how full the cache is and how many classes it contains. Stale classes are classes that have been updated on the file system and which the cache has therefore marked "stale". Stale classes are not purged from the cache. See the Diagnostics Guide (http://www.ibm.com/developerworks/java/jdk/diagnosis/50.html) section on the "printStats utility" for more information.
- safemode
- Forces the JVM to load all classes from disk and apply the modifications to those classes (if applicable). See the Diagnostics Guide (http://www.ibm.com/developerworks/java/jdk/diagnosis/50.html) section on "Using the safemode option" for more information.
- silent
- Disables all shared class messages, including error messages. Unrecoverable error messages, which prevent the JVM from initializing, are displayed.
- verbose
- Gives detailed output on the cache I/O activity, listing information about classes being 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. The standard option -verbose:class also enables class sharing verbose output if class sharing is enabled.
- verboseHelper
- Enables verbose output for the Java Helper API. This output shows you how the Helper API is used by your class loader.
- verboseIO
- Gives detailed output on the cache I/O activity, listing information about classes being 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.
- -Xsigcatch
- Enables VM signal handling code. See also -Xnosigcatch. By default, signal handling is enabled.
- -Xsigchain
- Enables signal handler chaining. See also -Xnosigchain. By default, signal handler chaining is enabled.
- -Xss<size>
- Sets the maximum stack size for Java threads. The default is 256 KB for 32-bit JVMs and 512 KB for 64-bit JVMs. The maximum value varies according to platform and specific machine configuration. If you exceed the maximum value, a java/lang/OutOfMemoryError message is reported.
- -Xssi<size>
- Sets the stack size increment for Java threads. When the stack for a Java thread becomes full it is increased in size by this value until the maximum size (-Xss) is reached. The default is 16 KB.
- -Xthr:minimizeUserCPU
- Minimizes user-mode CPU usage in thread synchronization where possible. The reduction in CPU usage might be a trade-off in exchange for lower performance.
- -XtlhPrefetch
- Speculatively prefetches bytes in the thread local heap (TLH) ahead of the current allocation pointer during object allocation. This helps reduce the performance cost of subsequent allocations.
- -Xtrace[:help] | [:<option>=<value>, ...]
- See the Diagnostics Guide (http://www.ibm.com/developerworks/java/jdk/diagnosis/50.html) section on the "Controlling the trace" for more information.
- -Xverify[:<option>]
- With no parameters, enables the verifier, which is the default.
Therefore, if used on its own with no parameters, for example, -Xverify,
this option does nothing. Optional parameters are as follows:
- all - enable maximum verification
- none - disable the verifier
- remote - enables strict class-loading checks on remotely loaded classes
-XX command-line options
JVM command-line options that are specified with -XX are not stable and are not recommended for casual use.
These options are subject to change without notice.
- -XXallowvmshutdown:[false|true]
- This option is provided as a workaround for customer applications that cannot shut down cleanly, as described in APAR IZ59734. Customers who need this workaround should use -XXallowvmshutdown:false. The default option is -XXallowvmshutdown:true for Java 5 SR10 onwards.
- -XX:-StackTraceInThrowable
- This option removes stack traces from exceptions. By default,
stack traces are available in exceptions. Including a stack trace
in exceptions requires walking the stack and that can affect performance.
Removing stack traces from exceptions can improve performance but
can also make problems harder to debug.
When this option is enabled, Throwable.getStackTrace() returns an empty array and the stack trace is displayed when an uncaught exception occurs. Thread.getStackTrace() and Thread.getAllStackTraces() are not affected by this option.
JIT command-line options
Use these JIT compiler command-line options to control code compilation.
For more information about JIT , see the Diagnostics Guide (http://www.ibm.com/developerworks/java/jdk/diagnosis/50.html).
- -Xcodecache<size>
- This option is used to tune performance. It sets the size of each
block of memory that is allocated to store the native code of compiled Java methods. By default, this size
is selected internally according to the processor architecture and
the capability of your system. If profiling tools show significant
costs in trampolines, that is a good reason to change the size until
the costs are reduced. Changing the size does not mean always increasing
the size. The option provides the mechanism to tune for the right
size until hot interblock calls are eliminated. A reasonable starting
point to tune for the optimal size is (totalNumberByteOfCompiledMethods
* 1.1).
Note: Trampolines are where reflection is used to avoid inner classes. JVMTI identifies trampolines in a methodLoad2 event.
- -Xint
- Makes the JVM use the Interpreter only, disabling the Just-In-Time (JIT) compilers. By default, the JIT compiler is enabled.
- -Xjit[:<parameter>=<value>, ...]
- With no parameters, enables the JIT compiler. The JIT compiler
is enabled by default, so using this option on its own has no effect.
Use this option to control the behavior of the JIT compiler. Useful
parameters are:
- count=<n>
Where <n> is the number of times a method is called before it is compiled. For example, setting count=0 forces the JIT compiler to compile everything on first execution.
- limitFile=(<filename>, <m>, <n>)
- Compile only the methods listed on lines <m> to <n> in the specified limit file. Methods not listed in the limit file and methods listed on lines outside the range are not compiled.
- optlevel=[ noOpt | cold | warm | hot | veryHot | scorching ]
- Forces the JIT compiler to compile all methods at a specific optimization level. Specifying optlevel might have an unexpected effect on performance, including lower overall performance.
- verbose
- Reports information about the JIT and AOT compiler configuration and method compilation.
- -Xquickstart
- Causes the JIT compiler to run with a subset of optimizations. The effect is faster compilation times that improve startup time, but longer running applications might run slower. -Xquickstart can degrade performance if it is used with long-running applications that contain hot methods. The implementation of -Xquickstart is subject to change in future releases. By default, -Xquickstart is disabled..
- -XsamplingExpirationTime<time> (from Service Refresh 5)
- Disables the JIT sampling thread after <time> seconds. When the JIT sampling thread is disabled, no processor cycles are used by an idle JVM.
Garbage Collector command-line options
Use these Garbage Collector command-line options to control garbage collection.
You might need to read the section on "Memory management" in the Diagnostics Guide (http://www.ibm.com/developerworks/java/jdk/diagnosis/50.html) to understand some of the references that are given here.
The -verbose:gc option detailed in the section on "-verbose:gc logging" in the Diagnostics Guide (http://www.ibm.com/developerworks/java/jdk/diagnosis/50.html) is the main diagnostic aid that is available for runtime analysis of the Garbage Collector. However, additional command-line options are available that affect the behavior of the Garbage Collector and might aid diagnostics.
For options that take a <size> parameter, suffix the number with "k" or "K" to indicate kilobytes, "m" or "M" to indicate megabytes, or "g" or "G" to indicate gigabytes.
For options that take a <percentage> parameter, use a number from 0 to 1, for example, 50% is 0.5.
- -Xalwaysclassgc
- Always perform dynamic class unloading checks during global collection. The default behavior is as defined by -Xclassgc.
- -Xclassgc
- Enables the collection of class objects only on class loader changes. This behavior is the default.
- -Xcompactexplicitgc
- Enables full compaction each time System.gc() is called.
- -Xcompactgc
- Compacts on all garbage collections (system and global).
The default (no compaction option specified) makes the GC compact based on a series of triggers that attempt to compact only when it is beneficial to the future performance of the JVM.
- -Xconcurrentbackground<number>
- Specifies the number of low-priority background threads attached to assist the mutator threads in concurrent mark. The default is 1.
- -Xconcurrentlevel<number>
- Specifies the allocation "tax" rate. It indicates the ratio between the amount of heap allocated and the amount of heap marked. The default is 8.
- -Xconmeter:<soa | loa | dynamic>
- This option determines the usage of which area, LOA (Large Object Area) or SOA (Small Object Area), is metered and hence which allocations are taxed during concurrent mark. Using -Xconmeter:soa (the default) applies the allocation tax to allocations from the small object area (SOA). Using -Xconmeter:loa applies the allocation tax to allocations from the large object area (LOA). If -Xconmeter:dynamic is specified, the collector dynamically determines which area to meter based on which area is exhausted first, whether it is the SOA or the LOA.
- -Xdisableexcessivegc
- Disables the throwing of an OutOfMemory exception if excessive time is spent in the GC.
- -Xdisableexplicitgc
-
Disables System.gc() calls.
Many applications still make an excessive number of explicit calls to System.gc() to request garbage collection. In many cases, these calls degrade performance through premature garbage collection and compactions. However, you cannot always remove the calls from the application.
The -Xdisableexplicitgc parameter allows the JVM to ignore these garbage collection suggestions. Typically, system administrators use this parameter in applications that show some benefit from its use.
By default, calls to System.gc() trigger a garbage collection.
- -Xdisablestringconstantgc
- Prevents strings in the string intern table from being collected.
- -Xenableexcessivegc
- If excessive time is spent in the GC, the option returns null for an allocate request and thus causes an OutOfMemory exception to be thrown. This action occurs only when the heap has been fully expanded and the time spent is making up at least 95%. This behavior is the default.
- -Xenablestringconstantgc
- Enables strings from the string intern table to be collected. This behavior is the default.
- -Xgc:<verbose | compact | nocompact >
- Options that change the behavior of the Garbage Collector.
- -Xgcpolicy:< gencon | optavgpause | optthruput | subpool (AIX, Linux and IBM i on IBM POWER architecture, Linux and z/OS on zSeries®) >
- Controls the behavior of the Garbage Collector.
The gencon option requests the combined use of concurrent and generational GC to help minimize the time that is spent in any garbage collection pause.
The optavgpause option reduces the time that is spent in these garbage collection pauses and limits the effect of increasing heap size on the length of the garbage collection pause. Use optavgpause if your configuration has a large heap. Enables concurrent mark.
The optthruput option is the default and delivers high throughput to applications, but at the cost of occasional pauses. Disables concurrent mark.
The subpool option (AIX, Linux and IBM i on IBM POWER architecture, and z/OS) uses an improved object allocation algorithm to achieve better performance when allocating objects on the heap. This option might improve performance on large SMP systems.
- -Xgcthreads<number>
- Sets the number of threads that the Garbage Collector uses for
parallel operations. This total number of GC threads
is composed of one application thread with the remainder being dedicated
GC threads. By default, the number is set to
the number of physical CPUs present. To set it to a different
number (for example 4), use -Xgcthreads4. The minimum valid value is 1, which disables parallel
operations, at the cost of performance. No advantage is gained if
you increase the number of threads above the default setting; you
are recommended not to do so.
On systems running multiple JVMs or in LPAR environments where multiple JVMs can share the same physical CPUs, you might want to restrict the number of GC threads used by each JVM. The restriction helps prevent the total number of parallel operation GC threads for all JVMs exceeding the number of physical CPUs present, when multiple JVMs perform garbage collection at the same time.
- -Xgcworkpackets<number>
- Specifies the total number of work packets available in the global collector. If not specified, the collector allocates a number of packets based on the maximum heap size.
- -Xloa
- Allocates a large object area (LOA). Objects are allocated in this LOA rather than the SOA. By default, the LOA is enabled for all GC policies except for subpool, where the LOA is not available.
- -Xloainitial<percentage>
- Specifies the initial percentage (between 0 and 0.95) of the current tenure space allocated to the large object area (LOA). The default value is 0.05, which is 5%.
- -Xloamaximum<percentage>
- Specifies the maximum percentage (between 0 and 0.95) of the current tenure space allocated to the large object area (LOA). The default value is 0.5, which is 50%.
- -Xmaxe<size>
- Sets the maximum amount by which the garbage collector expands the heap. Typically, the garbage collector expands the heap when the amount of free space falls below 30% (or by the amount specified using -Xminf), by the amount required to restore the free space to 30%. The -Xmaxe option limits the expansion to the specified value; for example -Xmaxe10M limits the expansion to 10 MB. By default, there is no maximum expansion size.
- -Xmaxf<percentage>
- Specifies the maximum percentage of heap that must be free after a garbage collection. If the free space exceeds this amount, the JVM tries to shrink the heap. The default value is 0.6 (60%).
- -Xmaxt<percentage>
- Specifies the maximum percentage of time to be spent in Garbage Collection. If the percentage of time rises above this value, the JVM tries to expand the heap. The default value is 13%.
- -Xmca<size>
- Sets the expansion step for the memory allocated to store the
RAM portion of loaded classes. Each time more memory is required to
store classes in RAM, the allocated memory is increased by this amount.
By default, the expansion step is 32 KB. Use the -verbose:sizes option
to determine the value that the VM is using.
If the expansion step size you choose is too large, OutOfMemoryError is reported. The exact value of a "too large" expansion step size varies according to the platform and the specific machine configuration.
- -Xmco<size>
- Sets the expansion step for the memory allocated to store the
ROM portion of loaded classes. Each time more memory is required to
store classes in ROM, the allocated memory is increased by this amount.
By default, the expansion step is 128 KB. Use the -verbose:sizes option
to determine the value that the VM is using.
If the expansion step size you choose is too large, OutOfMemoryError is reported. The exact value of a "too large" expansion step size varies according to the platform and the specific machine configuration.
- -Xmine<size>
- Sets the minimum amount by which the Garbage Collector expands the heap. Typically, the garbage collector expands the heap by the amount required to restore the free space to 30% (or the amount specified using -Xminf). The -Xmine option sets the expansion to be at least the specified value; for example, -Xmine50M sets the expansion size to a minimum of 50 MB. By default, the minimum expansion size is 1 MB.
- -Xminf<percentage>
- Specifies the minimum percentage of heap to be left free after a garbage collection. If the free space falls below this amount, the JVM attempts to expand the heap. The default value is 30%.
- -Xmint<percentage>
- Specifies the minimum percentage of time to spend in Garbage Collection. If the percentage of time drops below this value, the JVM tries to shrink the heap. The default value is 5%.
- -Xmn<size>
- Sets the initial and maximum size of the new area to the specified value when using -Xgcpolicy:gencon. Equivalent to setting both -Xmns and -Xmnx. If you set either -Xmns or -Xmnx, you cannot set -Xmn. If you try to set -Xmn with either -Xmns or -Xmnx, the VM does not start, returning an error. By default, -Xmn is not set. If the scavenger is disabled, this option is ignored.
- -Xmns<size>
- Sets the initial size of the new area to the specified value when using -Xgcpolicy:gencon. By default, this option is set to 25% of the value of the -Xms option or 64 MB, whichever is less. This option returns an error if you try to use it with -Xmn. You can use the -verbose:sizes option to find out the values that the VM is currently using. If the scavenger is disabled, this option is ignored.
- -Xmnx<size>
- Sets the maximum size of the new area to the specified value when using -Xgcpolicy:gencon. By default, this option is set to 25% of the value of the -Xmx option or 64 MB, whichever is less. This option returns an error if you try to use it with -Xmn. You can use the -verbose:sizes option to find out the values that the VM is currently using. If the scavenger is disabled, this option is ignored.
- -Xmo<size>
- Sets the initial and maximum size of the old (tenured) heap to the specified value when using -Xgcpolicy:gencon. Equivalent to setting both -Xmos and -Xmox. If you set either -Xmos or -Xmox, you cannot set -Xmo. If you try to set -Xmo with either -Xmos or -Xmox, the VM does not start, returning an error. By default, -Xmo is not set.
- -Xmoi<size>
- Sets the amount the Java heap is incremented when using -Xgcpolicy:gencon. If set to zero, no expansion is allowed. By default, the increment size is calculated on the expansion size, set by -Xmine and -Xminf.
- -Xmos<size>
- Sets the initial size of the old (tenure) heap to the specified value when using -Xgcpolicy:gencon. By default, this option is set to the value of the -Xms option minus the value of the -Xmns option. This option returns an error if you try to use it with -Xmo. You can use the -verbose:sizes option to find out the values that the VM is currently using.
- -Xmox<size>
- Sets the maximum size of the old (tenure) heap to the specified value when using -Xgcpolicy:gencon. By default, this option is set to the same value as the -Xmx option. This option returns an error if you try to use it with -Xmo. You can use the -verbose:sizes option to find out the values that the VM is currently using.
- -Xmr<size>
- Sets the size of the Garbage Collection "remembered set". This set is a list of objects in the old (tenured) heap that have references to objects in the new area. By default, this option is set to 16 K.
- -Xmrx<size>
- Sets the remembered maximum size setting.
- -Xms<size>
- Sets the initial Java heap
size. You can also use the -Xmo option. The minimum
size is 8 KB.
If scavenger is enabled, -Xms >= -Xmn + -Xmo.
If scavenger is disabled, -Xms >= -Xmo.
- -Xmx<size>
- Sets the maximum memory size (-Xmx >= -Xms)
Examples of the use of -Xms and -Xmx:
- -Xms2m -Xmx64m
- Heap starts at 2 MB and grows to a maximum of 64 MB.
- -Xms100m -Xmx100m
- Heap starts at 100 MB and never grows.
- -Xms20m -Xmx1024m
- Heap starts at 20 MB and grows to a maximum of 1 GB.
- -Xms50m
- Heap starts at 50 MB and grows to the default maximum.
- -Xmx256m
- Heap starts at default initial value and grows to a maximum of 256 MB.
- -Xnoclassgc
- Disables class garbage collection. This option switches off garbage collection of storage associated with Java classes that are no longer being used by the JVM. The default behavior is as defined by -Xclassgc. By default, class garbage collection is performed.
- -Xnocompactexplicitgc
- Disables compaction on System.gc() calls. Compaction takes place on global garbage collections if you specify -Xcompactgc or if compaction triggers are met. By default, compaction is enabled on calls to System.gc().
- -Xnocompactgc
- Disables compaction on all garbage collections (system or global). By default, compaction is enabled.
- -Xnoloa
- Prevents allocation of a large object area; all objects are allocated in the SOA. See also -Xloa.
- -Xnopartialcompactgc
- Disables incremental compaction. See also -Xpartialcompactgc.
- -Xpartialcompactgc
- Enables incremental compaction. See also -Xnopartialcompactgc. By default, this option is not set, so all compactions are full.
- -Xsoftmx<size> (AIX only)
- This option sets the initial maximum size of the Java heap. Use the -Xmx option to set the maximum heap size. Use the AIX DLPAR API in your application to alter the heap size limit between -Xms and -Xmx at run time. By default, this option is set to the same value as -Xmx.
- -Xsoftrefthreshold<number>
- Sets the number of GCs after which a soft reference is cleared if its referent has not been marked. The default is 32, meaning that on the 32nd GC where the referent is not marked the soft reference is cleared.
- -Xtgc:<arguments>
- Provides GC tracing options, where <arguments> is
a comma-separated list containing one or more of the following arguments:
- backtrace
- Before a garbage collection, a single line is printed containing the name of the master thread for garbage collection, as well as the value of the osThread slot in the J9VMThread structure.
- compaction
- Prints extra information showing the relative time spent by threads in the "move" and "fixup" phases of compaction
- concurrent
- Prints extra information showing the activity of the concurrent mark background thread
- dump
- Prints a line of output for every free chunk of memory in the system, including "dark matter" (free chunks that are not on the free list for some reason, typically because they are too small). Each line contains the base address and the size in bytes of the chunk. If the chunk is followed in the heap by an object, the size and class name of the object is also printed. This argument has a similar effect to the terse argument.
- freeList
- Before a garbage collection, prints information about the free list and allocation statistics since the last GC. Prints the number of items on the free list, including "deferred" entries (with the scavenger, the unused space is a deferred free list entry). For TLH and non-TLH allocations, prints the total number of allocations, the average allocation size, and the total number of bytes discarded during allocation. For non-TLH allocations, also included is the average number of entries that were searched before a sufficiently large entry was found.
- parallel
- Produces statistics on the activity of the parallel threads during the mark and sweep phases of a global GC.
- references
- Prints extra information every time that a reference object is enqueued for finalization, showing the reference type, reference address, and referent address.
- scavenger
- Prints extra information after each scavenger collection. A histogram is produced showing the number of instances of each class, and their relative ages, present in the survivor space. The information is obtained by performing a linear walk-through of the space.
- terse
- Dumps the contents of the entire heap before and after a garbage collection. For each object or free chunk in the heap, a line of trace output is produced. Each line contains the base address, "a" if it is an allocated object, and "f" if it is a free chunk, the size of the chunk in bytes, and, if it is an object, its class name.
- -Xverbosegclog[:<file>[,<X>,<Y>]]
-
Causes -verbose:gc output to be written to the specified file. If the file cannot be found, -verbose:gc tries to create the file, and then continues as normal if it is successful. If it cannot create the file (for example, if an invalid filename is passed into the command), it redirects the output to stderr.
If you specify <X> and <Y> the -verbose:gc output is redirected to X files, each containing Y GC cycles.
The dump agent tokens can be used in the filename. See the Diagnostics Guide (http://www.ibm.com/developerworks/java/jdk/diagnosis/50.html) section on the "Dump agent tokens" for more information. If you do not specify <file>, verbosegc.m%d.2/15/14M%S.%pid.txt is used.
By default, no verbose GC logging occurs.
Appendix B. Default settings for the JVM
This appendix shows the default settings that the JVM uses. These settings affect how the JVM operates if you do not apply any changes to its environment. The tables show the JVM operation and the default setting.
These tables are a quick reference to the state of the JVM when it is first installed. The last column shows how the default setting can be changed:
- c
- The setting is controlled by a command-line parameter only.
- e
- The setting is controlled by an environment variable only.
- ec
- The setting is controlled by a command-line parameter or an environment variable. The command-line parameter always takes precedence.
JVM setting | Default | Setting affected by |
---|---|---|
Javadumps | Enabled | ec |
Javadumps on out of memory | Enabled | ec |
Heapdumps | Disabled | ec |
Heapdumps on out of memory | Enabled | ec |
Sysdumps | Enabled | ec |
Where dump files are produced | Current® directory | ec |
Verbose output | Disabled | c |
Boot classpath search | Disabled | c |
JNI checks | Disabled | c |
Remote debugging | Disabled | c |
Strict conformance checks | Disabled | c |
Quickstart | Disabled | c |
Remote debug info server | Disabled | c |
Reduced signaling | Disabled | c |
Signal handler chaining | Enabled | c |
Classpath | Not set | ec |
Class data sharing | Disabled | c |
Accessibility support | Enabled | e |
JIT compiler | Enabled | ec |
JIT debug options | Disabled | c |
Java2D max size of fonts with algorithmic bold | 14 point | e |
Java2D use rendered bitmaps in scalable fonts | Enabled | e |
Java2D freetype font rasterizing | Enabled | e |
Java2D use AWT fonts | Disabled | e |
JVM setting | AIX | IBM i | Linux | Windows | z/OS | Setting affected by |
---|---|---|---|---|---|---|
Default locale | None | None | None | N/A | None | e |
Time to wait before starting plug-in | N/A | N/A | Zero | N/A | N/A | e |
Temporary directory | /tmp | /tmp | /tmp | c:\temp | /tmp | e |
Plug-in redirection | None | None | None | N/A | None | e |
IM switching | Disabled | Disabled | Disabled | N/A | Disabled | e |
IM modifiers | Disabled | Disabled | Disabled | N/A | Disabled | e |
Thread model | N/A | N/A | N/A | N/A | Native | e |
Initial stack size for Java Threads 32-bit. Use: -Xiss<size> | 2 KB | 2 KB | 2 KB | 2 KB | 2 KB | c |
Maximum stack size for Java Threads 32-bit. Use: -Xss<size> | 256 KB | 256 KB | 256 KB | 256 KB | 256 KB | c |
Stack size for OS Threads 32-bit. Use -Xmso<size> | 256 KB | 256 KB | 256 KB | 32 KB | 256 KB | c |
Initial stack size for Java Threads 64-bit. Use: -Xiss<size> | 2 KB | N/A | 2 KB | 2 KB | 2 KB | c |
Maximum stack size for Java Threads 64-bit. Use: -Xss<size> | 512 KB | N/A | 512 KB | 512 KB | 512 KB | c |
Stack size for OS Threads 64-bit. Use -Xmso<size> | 256 KB | N/A | 256 KB | 256 KB | 256 KB | c |
Initial heap size. Use -Xms<size> | 4 MB | 4 MB | 4 MB | 4 MB | 1 MB | c |
Maximum Java heap size. Use -Xmx<size> | 64 MB | 2 GB | Half the real memory with a minimum of 16 MB and a maximum of 512 MB | Half the real memory with a minimum of 16 MB and a maximum of 2 GB | 64 MB | c |
Appendix C. Known limitations
Known limitations on the SDK and Runtime Environment for AIX.
You can find more help with problem diagnosis in the Diagnostics Guide at http://www.ibm.com/developerworks/java/jdk/diagnosis/50.html.
CUPS support
The SDK and Runtime Environment for AIX does not support printing using the CUPS interface.
XSLT namespace and Netbeans 5.0 problems
If the data provided to your transformation is a DOM that you have created programmatically, the XSLT interpreter processor might have problems with implicit namespaces. The problems are incorrect namespace declarations, or the omission of namespace declarations from the resulting document. An example Java fragment follows:
// Example of an explicit namespace - an attribute node will be created in the DOM // for xmlns='ht tp://my.org/project' String data = "<projectxmins='http://my.org/project/>"; Document doc = DocumentBuilderFactory.newInstance().newDocumentBuilder().parse (new InputSource(n ew StringReader(data))); // Example of an implicit namespace - no attribute node is created for the // implicit namespace xm lns='http://your.org/project Element typeElem = doc.createElementNS("http://your.org/project", "type"); doc.getDocumentElement().appendChild(typeElem);
To work around this limitation you can use the XSLT compiler processor, XSLTC. You can specify the compiler processor by using the -XSLTC option with the Process command or by setting the javax.xml.transform.TransformerFactory service provider to org.apache.xalan.xsltc.trax.TransformerFactoryImpl.
Netbeans 5.0 does not run under the JVM with default settings. To enable Netbeans to run, set the
=org.apache.xalan.xsltc.trax.TransformerFactoryImpl
property in jre/lib/jaxp.properties.
JDI problem with AIX 5.3
On AIX 5.3, if a class is run using JDI, either directly or through JDB, the class does not return to the starting class.
JConsole monitoring tool Local tab
In the IBM JConsole tool, the Local tab, which allows you to connect to other Virtual Machines on the same system, is not available. Also, the corresponding command line pid option is not supported. Instead, use the Remote tab in JConsole to connect to the Virtual Machine that you want to monitor. Alternatively, use the connection command-line option, specifying a host of localhost and a port number. When you start the application that you want to monitor, set these command-line options:
- -Dcom.sun.management.jmxremote.port=<value>
- Specifies the port the management agent listens on.
- -Dcom.sun.management.jmxremote.authenticate=false
- Disables authentication unless you have created a user name file.
- -Dcom.sun.management.jmxremote.ssl=false
- Disables SSL encryption.
JConsole monitoring tool when the JIT is not enabled
The IBM JConsole tool has the following limitations when the JIT is not enabled:
- The Summary tab is not available.
- The VM tab is not available.
- The chart accessed from the Memory tab is not updated.
- The chart accessed from the Threads tab is not updated.
- You cannot determine if the Perform GC button has an effect when accessed from the Memory tab.
Connection failed message when using the JConsole monitoring tool with security enabled
When using the JConsole monitoring tool with security enabled, there is no error message if you specify an incorrect path to a keystore in the Java launcher options. You cannot connect to the JConsole monitoring tool, and a connection failed message is displayed.
Plug-in load failure when using Mozilla
If you use the Mozilla browser there might be error messages when loading plug-ins. For example:
# mozilla LoadPlugin: failed to initialize shared library /jdk/java5/32bit/20071217/sdk/jre/ bin/libjavaplugin_oji.so [ 0509-022 Cannot load module /jdk/java5/32bit/ 20071217/sdk/jre/bin/libjavaplugin_oji.so. 0509-150 Dependent module /lib/libgmodule.so could not be loaded. 0509-103 The module has an invalid magic number. 0509-026 System error: Cannot run a file that does not have a valid format. 0509-022 Cannot load module /lib/libgmodule.so. 0509-150 Dependent module /lib/libgmodule.so could not be loaded.]
The plug-in files must be in shared object format, and not in archive format. The reason is that the plug-in library looks for shared objects by default. Check the format of the files that are failing to load and change the format of archive (.a) files to shared object (.so). You can use the ar command to change the format.
Follow these steps to change the format of the libraries:
- Add /lib and /usr/lib to the LIBPATH.
- Enter export LIBPATH=$LIBPATH:/usr/lib:/lib
- Change to /opt/freeware/lib
- Enter
ar -x libgmodule-2.0.a ar -x libgtk-x11-2.0.a ar -x libgdk-x11-2.0.a
- Enter
mv libgdk-x11-2.0.so.0 /usr/lib/libgdk.so mv libgmodule-2.0.so.0 /usr/lib/libgmodule.so mv libgtk-x11-2.0.so.0 /usr/lib/libgtk.so
- Start the Mozilla browser.
Incorrect stack traces when loading new classes after an Exception is caught
If new classes are loaded after an Exception has been caught, the stack trace contained in the Exception might become incorrect. The stack trace becomes incorrect if classes in the stack trace are unloaded, and new classes are loaded into their memory segments.
Creating a JVM using JNI
Native programs cannot create a VM with JNI_VERSION_1_1(0x00010001) interfaces. You cannot call JNI_CreateJavaVM() and pass it a version of JNI_VERSION_1_1(0x00010001). The versions that can be passed are:
- JNI_VERSION_1_2(0x00010002)
- JNI_VERSION_1_4(0x00010004)
The VM created is determined by the Java libraries present (that is, 1.2.2, 1.3.x, 1.4.x, 5.x), not the one that is implied by the JNI interface version passed.
The interface version does not affect any area of VM behavior other than the functions available to native code.
ThreadMXBean Thread User CPU Time limitation
In package java.lang.management, the methods ThreadMXBean.getThreadUserTime() and ThreadMXBean.getCurrentThreadUserTime() are not supported. These methods always return -1. These methods are not supported even when ThreadMXBean.isThreadCpuTimeSupported() and ThreadMXBean.isCurrentThreadCpuTimeSupported() return true. This limitation does not affect ThreadMXBean.getThreadCpuTime() or ThreadMXBean.getCurrentThreadCpuTime()
XIM and the Java Plug-in
AIX 5.2 and AIX 5.3 only
For Japanese, Chinese, and Korean language users, you cannot use XIM to enter your own characters into text components on a Java applet in a Web browser. To work around this situation, specify the -Dsun.awt.noxembed=true system parameter to disable XEmbed. You can set this option by using the control panel:
- Open the Java Plug-in control panel and go to the Java tab.
- Click the View button in the Java Applet Runtime Settings.
- Enter -Dsun.awt.noxembed=true in the Java Runtime Parameters and click OK.
- Click Apply.
- Start a browser.
This limitation is resolved in APAR IY77834 (AIX5.3) or APAR IY77820 (AIX5.2).
Printing
If you have difficulty with print operations, try increasing the size of the default file system that is used for print spooling to be larger than the printed PostScript file size.
Font quality in AWT
Text rendering for Java AWT TextField and TextArea components is performed by the AIX rasterizer for X/Motif text widgets. Currently, you might experience text dropouts at small font sizes for some fonts. To avoid the problem, use a font size that is greater than 12 points for AWT TextField and TextArea components.
Displaying AWT text components in Japanese
If your system runs slowly when displaying AWT text components on AIX 5.2 in a Japanese environment (non-UTF-8 locale), apply APAR IY75960.
NullPointerException with the GTK Look and Feel
DBCS environments only
If your application fails with a NullPointerException using the GTK Look and Feel, unset the GNOME_DESKTOP_SESSION_ID environment variable.
Switching input methods
You must close the candidate window and commit pre-edited strings before you switch the Input Method (IM) using the IM selection menu. If you open the IM selection menu without either closing the candidate window or committing a pre-edited string, cancel the menu, close the candidate window, and commit the pre-edited string, then try to switch the IM again.
Displaying DBCS characters in a JFrame
DBCS characters might not display correctly in the title of a JFrame. To avoid this problem, set the language in the terminal login screen instead of in a prompt after you have logged in.
C++ Runtime Environment version 8.0.0.3
The C++ Runtime Environment (file set xlC.aix50.rte) version 8.0.0.3 contains an error that causes Java to stop (see http://www.ibm.com/support/docview.wss?uid=swg24012187). If you have this version of the C++ Runtime Environment installed, upgrade to version 8.0.0.4 or later.
Using -Xshareclasses:destroy during JVM startup
When running the command java -Xshareclasses:destroy on a shared cache that is being used by a second JVM during startup, you might have the following issues:
- The second JVM fails.
- The shared cache is deleted.
Appendix D. Support for virtualization software
The IBM SDK for Java is supported on a number of virtualized environments.
The virtualization capabilities of the AIX POWER hypervisor, provided as part of the IBM POWER platform, have been fully tested with all SDK supported releases of AIX.
The virtualization capabilities of the Processor Resource/System Manager (PR/SM™) provided as part of the IBM z-31 and IBM z-64 platforms have been fully tested with all SDK supported releases of z/OS.
In addition, the following virtualization software has been tested for the IBM SDK for Java:
Virtualization software | SDK release tested |
---|---|
z/VM® v6.1 | SR12 |
VMWare ESXi Server 4 | SR5 |
Kernel-based Virtual Machine (KVM) on Red Hat Enterprise Virtualization V5 | SR12 |
Microsoft Hyper-V R2 | SR5 |
Notices
This information was developed for products and services offered in the U.S.A.
IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not grant you any license to these patents. You can send license inquiries, in writing, to:
- IBM Director of Licensing
- IBM Corporation
- North Castle Drive
- Armonk, NY 10504-1758
- U.S.A.
For license inquiries regarding double-byte character set (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to:
- Intellectual Property Licensing
- Legal and Intellectual Property Law
- IBM Japan Ltd.
- 1623-14, Shimotsuruma, Yamato-shi
- Kanagawa 242-8502 Japan
The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law:
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.
This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice.
Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk.
IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you.
Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact:
- JIMMAIL@uk.ibm.com
- [Hursley Java Technology Center (JTC) contact]
Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee.
The licensed program described in this document and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement or any equivalent agreement between us.
Any performance data contained herein was determined in a controlled environment. Therefore, the results obtained in other operating environments may vary significantly. Some measurements may have been made on development-level systems and there is no guarantee that these measurements will be the same on generally available systems. Furthermore, some measurements may have been estimated through extrapolation. Actual results may vary. Users of this document should verify the applicable data for their specific environment.
Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products.
All statements regarding IBM's future direction or intent are subject to change or withdrawal without notice, and represent goals and objectives only.
COPYRIGHT LICENSE:
This information contains sample application programs in source language, which illustrate programming techniques on various operating platforms. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample programs are written. These examples have not been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these programs. The sample programs are provided "AS IS", without warranty of any kind. IBM shall not be liable for any damages arising out of your use of the sample programs.
Each copy or any portion of these sample programs or any derivative work, must include a copyright notice as follows:
© (your company name) (year). Portions of this code are derived from IBM Corp. Sample Programs. © Copyright IBM Corp. _enter the year or years_.
If you are viewing this information softcopy, the photographs and color illustrations may not appear.
Trademarks
IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of International Business Machines Corporation in the United States, other countries, or both. If these and other IBM trademarked terms are marked on their first occurrence in this information with a trademark symbol (® or ™), these symbols indicate U.S. registered or common law trademarks owned by IBM at the time this information was published. Such trademarks may also be registered or common law trademarks in other countries. A current list of IBM trademarks is available on the Web at "Copyright and trademark information" at http://www.ibm.com/legal/copytrade.shtml.
UNIX is a registered trademark of The Open Group in the United States and other countries.
Java and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle and/or its affiliates.
Other company, product, or service names may be trademarks or service marks of others.