|
IBM 32-bit SDK for AIX, Java 2 Technology Edition, Version 1.4
User Guide
Note: Before using this information and the product it supports, be sure to read the general information under Notices.
This edition of the User Guide applies to the IBM 32-bit SDK for AIX, Java 2 Technology Edition, Version 1.4, and to all subsequent releases, modifications, and service refreshes, until otherwise indicated in new editions.
(C) Copyright Sun Microsystems, Inc. 1997, 2003, 901 San Antonio Rd., Palo Alto, CA 94303 USA. All rights reserved.
(C) Copyright International Business Machines Corporation, 1999, 2008. All rights reserved.
U.S. Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
Read this User Guide if you want to use the IBM(R) SDK to write Java(TM) applications and applets or if you want to use the Runtime Environment to run them.
Read this User Guide in conjunction with the more extensive documentation on the Sun Web site,  http://java.sun.com, and the AIX(R) download site, http://www.ibm.com/developerworks/java/jdk/aix.
Read Loading JVM libraries for JNI applications for important information about a security fix that impacts native C/C+ applications that use the Java Native Interface (JNI) invocation API to imbed a Java virtual machine. The AIX web browsers are an example of applications that were impacted by this change. After installing Java 1.4.2 SR2 (service refresh 2) or a subsequent service refresh, you will probably receive the following error message when viewing a Java applet in the browser: # mozilla
Error: could not find libjavaplugin_oji.so
Plugin: can't find plugins/../java directory
INTERNAL ERROR on Browser End: Could not start JavaVM!
System error?:: A file or directory in the path name does not exist. To correct this problem, export LIBPATH=/usr/java14/jre/bin:/usr/java14/jre/bin/classic before running the Web browser.
The software that is contained in this release can be used only on AIX(R) Version 5.1 or later. It is not supported, and does not work, on earlier versions of the AIX operating system. See AIX Environment for further details of requirements on the AIX operating system for this release.
This User Guide is part of a release and is applicable only to that particular release. Ensure 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.
Note that the Java14.debug fileset which contained the debug builds (such as java_g, jdb_g, and so on) is not provided in this release.
Technical changes for this Version 1.4.2 User Guide, other than minor or obvious ones such as updating "1.4.1" to "1.4.2", are indicated in red when viewing in HTML or in a color-printed copy and by vertical bars to the left of the changes.
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.
The SDK is a development environment for writing applets and applications that conform to the Java 1.4 Core Application Program Interface (API).
An applet or application that ran with earlier versions of the SDK should run with this version, except for the incompatibilities listed in:
http://java.sun.com/j2se/1.4/compatibility.html
http://java.sun.com/j2se/1.3/compatibility.html
There is no guarantee that v1.4.2-compiled classes work on pre-1.4.0 SDK releases.
Applets that depend on the Java v1.4 (or later) APIs will not work with browsers that do not support these APIs unless you install the Java Plug-in.
There is a possible compatibility consideration if you are using the SDK as part of another product, for example WAS, and you upgrade from a previous level of the SDK, perhaps v1.4.1, to v1.4.2. If you serialized the classes with a previous level of the SDK, the classes might not be compatible. However, within v1.4.2, classes are compatible from service refresh to service refresh.
The IBM 32-bit SDK for AIX, v1.4, runs on AIX V5.1 and up. The minimum AIX levels supported are: AIX 5100-08, 5200-06 and 5300-02.
To test whether this Java v1.4.2 SDK is supported on a specific pSeries(R) system, at the system prompt type: lscfg -p | fgrep Architecture You should receive the reply: Model Architecture: chrp Only "Common Hardware Reference Platform" (chrp) systems are supported by this SDK.
If you are using one of the supported non-UTF8 CKJ locales, you must install one of the following filesets (the install images are available on AIX base CDs; updates are available from the AIX fix distribution Web site, http://www.ibm.com/servers/eserver/support/unixservers/aixfixes.html): 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)
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 should 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) could result in application portability problems.
- Core Classes -- These are the compiled class files for the platform and must remain zipped for the compiler and interpreter to access them. Do not modify these classes; instead, create subclasses and override where you need to.
- JRE tools -- The following tools are part of the Runtime Environment and are in the /usr/java14/jre/bin directory.
- Java Interpreter (java)
- Executes Java bytecodes. The Java Interpreter runs programs that are written in the Java programming language.
- Java Interpreter (javaw)
- Executes Java bytecodes in the same way as the java command does, but does not use a console window.
- Key and Certificate Management Tool (keytool)
- Manages a keystore (database) of private keys and their associated X.509 certificate chains that authenticate the corresponding public keys.
- Policy File Creation and Management Tool (policytool)
- Creates and modifies the external policy configuration files that define your installation's Java security policy.
- RMI activation system daemon (rmid)
- Starts the activation system daemon so that objects can be registered and activated in a Java virtual machine (JVM).
- Common Object Request Broker Architecture (CORBA) Naming Service (tnameserv)
- Starts the CORBA transient naming service.
- Java Remote Object Registry (rmiregistry)
- Creates and starts a remote object registry on the specified port of the current host.
- iKeyman GUI utility.
- Dump extractor (jextract)
Earlier versions of the IBM JRE shipped with a file called rt.jar in the jre/lib directory. From Java V1.4 onwards, this file has been replaced by multiple JAR files that reside in the jre/lib directory. Examples of these JAR files are:
- core.jar, which contains the majority of the class libraries, including the system, IO, and net class libraries
- graphics.jar, which contains the awt and swing class libraries
- security.jar, which contains the security framework code. For maintenance reasons, security.jar has been split up into smaller JAR files from v1.4.2 onwards.
- server.jar, which contains the RMI class libraries
- xml.jar, which contains the xml and html class libraries
This change should be completely transparent to the application. If an error is received about a missing rt.jar file in CLASSPATH, this error points to a setting that was used in Java V1.1.8 and was made obsolete in subsequent versions of Java. You can safely remove references to rt.jar in CLASSPATH.
- The following tools are part of the SDK and are located in the /usr/java14/bin directory:
- Java Compiler (javac)
- Compiles programs that are written in the Java programming language into bytecodes (compiled Java code).
- Java Applet Viewer (appletviewer)
- Tests and runs applets outside a Web browser.
- Java Debugger (jdb)
- Helps debug your Java programs.
- Class File Disassembler (javap)
- Disassembles compiled files and can print a representation of the bytecodes.
- Java Documentation Generator (javadoc)
- Generates HTML pages of API documentation from Java source files.
- C Header and Stub File Generator (javah)
- Enables you to associate native methods with code written in the Java programming language.
- Java Archive Tool (jar)
- Combines multiple files into a single Java Archive (JAR) file.
- JAR Signing and Verification Tool (jarsigner)
- Generates signatures for JAR files, and verifies the signatures of signed JAR files.
- Native-To-ASCII Converter (native2ascii)
- Converts a native encoding file to an ASCII file that contains characters encoded in either Latin-1 or Unicode, or both.
- Java Remote Method Invocation (RMI) Stub Converter (rmic)
- Generates stubs, skeletons, and ties for remote objects. Includes RMI over Internet Inter-ORB Protocol (RMI-IIOP) support.
- IDL to Java Compiler (idlj)
- Generates Java bindings from a given IDL file.
- Serial Version Command (serialver)
- Returns the serialVersionUID for one or more classes in a format that is suitable for copying into an evolving class.
- Extcheck utility (extcheck)
- Detects version conflicts between a target jar file and currently-installed extension jar files.
- Cross-platform dump formatter (jformat)
- Java Plug-in HTML Converter (HtmlConverter)
- Converts an HTML page that contains applets to a format that can use the Java Plug-in.
- Java Web Start (webstart_update_sdk.sh)
- Enables the deployment and automatic maintenance of Java applications. For more information, see Installing Web Start.
- INCLUDE FILES
- C headers for JNI programs.
- USER GUIDE
- COPYRIGHT
- Copyright notice for the SDK for AIX software.
- LICENSE
- The LICENSE file, /usr/swlag/<locale>/Java14.la, contains the license agreement for the SDK for AIX software (where <locale> is the name of your locale, for example En_US). 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.
The documentation package is designed to be extracted into the SDK software installation directory. If you download the ZIP file archive version, be sure to preserve the path names when you extract the files from the archive.
The following tools are not included in the IBM SDK:
- MIF doclet
- orbd
- servertool
The IBM 32-bit SDK for AIX, v1.4 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.
These packages are required:
- Java14.license (license)
- Java14.sdk (base SDK, WebStart, and dt.jar)
These packages are optional:
- Java14.ext (Comm API, Java 3D, and JavaHelp)
- Java14.samples (demos)
- Java14.source (src.jar)
- Java14.msg.$LANG
$LANG is one of the following locales. These packages do not ship 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/java14/ Set up your PATH environment variable to refer to the new installation: export PATH=/usr/java14/jre/bin:/usr/java14/bin:$PATH Note: These elements of PATH changed, at Version 1.3.0, from the previous SDK releases. The v1.4.2 SDK does not use a java wrapper as Version 1.1.x and 1.2.2 did. When you install the v1.4.2 SDK in the /usr/java14/ directory, if you have symbolic links created by the V1.1.8 SDK and you don't set up the PATH environment variable, the V1.1.8 SDK is picked up as the default. You are not recommended to remove the old links in case you have applications that require the V1.1.8 SDK.
The following user-configurable files are installed to /etc/java14/ to support a machine configuration where the files are not shared:
- jre/javaws/javaws.policy
- jre/lib/jaxp.properties
- jre/lib/jaxp.properties.sample
- jre/lib/logging.properties
- jre/lib/security/java.policy
- jre/lib/security/java.security
- jre/lib/xalan.properties
- jre/lib/xerces.properties
There are symbolic links in /usr/java14/ pointing to the above files in /etc/java14/. | | ||By default, the SDK is installed in /usr/java14/. To install the SDK in |another directory, use the AIX relocation commands. |Delete any .toc files in the directory containing your installp images |or PTFs before using the AIX relocation commands. |See the AIX man pages for more information about the command-line options |for these commands. ||- installp_r
|- Install command. To install the SDK: |
installp_r -a -Y -R /<Install Path>/ -d '.' Java14.sdk To |remove the SDK: |installp_r -u -R /<Install Path>/ Java14.sdk | |- lsutil
|- List the user-defined installation paths. |
lsutil | |- 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>/ | |
If you are upgrading the SDK from a previous release, back up all the configuration files and security policy files before you go ahead with the upgrade.
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.
To help ensure that the verification process behaves consistently, first:
*JAVA_HOME is used in V1.1.x releases. It is not required to set JAVA_HOME in this release.
If you issue the command:
you should see:
When verification is complete, log on again and review any values that you might have assigned to these variables with the new installation for possible conflicts. Unless .hotjava already existed, executing the applet viewer creates a directory called .hotjava in your home directory. Issuing the command:
should confirm this.
The IBM JIT compiler (libjitc.a) dynamically generates machine code for frequently-used bytecode sequences in a Java application or applet during execution. The JIT V5.0 compiler delivers dynamic compiler technology, including:
- Improvements to optimizations that were implemented in previous versions of the JIT
- Optimizations that were added to JIT v5.0
- Stack allocation of objects
- Improved hardware exploitation
The JIT is enabled by default. To explicitly enable the JIT, set the JAVA_COMPILER environment variable to the value "jitc".
All SDK tools use the JIT by default. After installation, you can specify whether or not the JIT will be used. You can disable the JIT to help in the isolation of a problem with a Java application, an applet, or the compiler itself.
There are two ways to disable the JIT:
- Type the following at a command prompt:
- For the Korn shell:
- For the Bourne shell:
JAVA_COMPILER=NONE export JAVA_COMPILER
- For the C shell:
To enable the JIT, set the JAVA_COMPILER environment variable to "jitc" or switch on the JIT compiler through the command line:
java -Djava.compiler=jitc <myapp>
To determine whether the JIT is enabled, type the following at a command 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: jitc
Note:
If JAVA_COMPILER="" or -Djava.compiler="" , the JIT compiler is disabled. If JAVA_COMPILER is unset, as in: unset JAVA_COMPILER the default JIT compiler is enabled. The default JIT compiler is always the latest version.
The following sections provide information about using the SDK.
To obtain the IBM build and version number, at a command prompt type:
java -version
The main SDK tools are programs that are run from a command prompt. After installing the SDK software, you run a tool by typing its name at a command prompt with a filename as an argument.
You can specify the path to a tool by typing the path in front of the tool each time. For example, if the javac compiler is in /usr/java14/bin, you can compile a file named myfile.java by typing the following at a command prompt: /usr/java14/bin/javac myfile.java Alternatively, you can add the string /usr/java14/bin to your PATH environment variable. Then you can compile the myfile.java file by typing the following at a command prompt: javac myfile.java The PATH environment variable enables AIX to find the executable files (such as javac, java, and javadoc) from any directory. To find the current value of your PATH, at a command prompt type: echo $PATH Note:
Like the 1.3.0 and 1.3.1 versions, the IBM 32-bit SDK for AIX, v1.4 ships the java tools as binary executables instead of the shell scripts that were shipped in previous versions up to Version 1.2.2. The PATH environment variable must point to the bin directories instead of sh directories as follows: export PATH=/usr/java14/bin:/usr/java14/jre/bin:$PATH
The java tool launches a Java application.
It does this by starting a Java Runtime Environment, loading a specified class, and invoking that class's main method. The method declaration must have the signature: public static void main(String args[]) The method must be declared public and static, it must not return any value, and it must accept a String array as a parameter. By default, the first non-option argument is the name of the class to be invoked. Use a fully-qualified class name.
The JVM searches for the startup class, and other classes that are used, in three sets of locations: the bootstrap classpath, the installed extensions, and the user classpath. Arguments after the class name or JAR file name are passed to the main function.
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 appear. The javaw launcher displays a dialog box with error information if a launch fails.
The java and javaw command have the following syntax: java [ options ] class [ arguments ... ]
java [ options ] -jar file.jar [ arguments ... ]
javaw [ options ] class [ arguments ... ]
javaw [ options ] -jar file.jar [ arguments ... ]
Items that are within brackets are optional.
- options
- Command-line options.
- class
- Name of the class to invoke.
- file.jar
- Name of the jar file to invoke. It is used only with -jar.
- argument
- Argument passed to the main function.
If the -jar option is specified, the named .jar file contains class and resource files for the application, with the startup class indicated by the Main-Class manifest header.
From Version 1.4.2 Service Refresh 4, using the -jar command-line option will make the .jar file the source of all user classes; all other user CLASSPATH settings will be ignored.
To be able to use a .jar file with other CLASSPATH settings, add the .jar file to the CLASSPATH as above, and specify the startup class manually.
The launcher has a set of standard options that are supported on the current runtime environment and will be supported in future releases. In addition, there is a set of nonstandard options. Standard options
- -D<property_name>=<value>
- -assert
- Prints help on assert-related options.
- -cp or -classpath <directories and zip or jar files separated by :>
- Set search path for application classes and resources. If -classpath and -cp are not used, and CLASSPATH is not set, the user classpath is, by default, the current directory (.). Also see Working with classpaths.
- -help or -?
- -showversion
- Prints product version and continues.
- -verbose:[class | gc | jni]
- -version
- -X
- Prints help on non-standard options.
Non-standard options
The -X options listed below are a subset of the available ones. They are nonstandard and subject to change without notice.
- -Xargencoding
- Allows the options on the java command to use Unicode escape sequences to represent characters that are not in the character set of the locale. Unicode escape sequences are of the form \u#### where # is a hexadecimal digit.
- -Xbootclasspath:<directories and zip or jar files separated by ;>
- -Xbootclasspath/a:<directories and zip or jar files separated by ;>
- Appends to end of bootstrap class path.
- -Xbootclasspath/p:<directories and zip or jar files separated by ;>
- -Xcheck:jni
- Performs additional checks for JNI functions.
- -Xcheck:nabounds
- Performs additional checks for JNI array operations.
- -Xdebug
- -Xdisableexplicitgc
- Changes calls to System.gc() into no-ops.
- -Xdisablejavadump
- Disables the java dump facility for abnormal process termination. When the java dump is disabled, the system process termination dump is run. The java dump is useful when the problem occurs within the java code.
- -Xgcpolicy:{optthruput | optavgpause | subpool}
- -Xlp
- Requests the SDK to allocate the Java heap (the heap from which Java objects are allocated) with 16 MB large pages. If large pages are not available, the Java heap will be allocated with AIX's standard 4 KB pages. AIX requires special configuration to enable large pages. For more information on configuring AIX support for large pages, see http://www.ibm.com/servers/aix/whitepapers/large_page.html. The SDK supports the use of large pages only to back the Java heap's share memory segments (the SDK uses shmget() with the SHM_LGPG and SHM_PIN flags to allocate large pages). The use of the LDR_CNTRL=LARGE_PAGE_DATA environment variable is not supported. The -Xlp option replaces the environment variable IBM_JAVA_LARGE_PAGE_SIZE, which is now ignored if set.
- -Xms<size>
- Sets initial Java heap size. The default is 4 MB.
- -Xmx<size>
- Sets maximum Java heap size. The default is 64 MB.
- -Xnoclassgc
- Disables class garbage collection.
- -Xoss<size>
- Sets maximum Java stack size for any thread. The default is 400(R) KB.
- -Xpd
- Loads the Problem Determination (PD) runtime libraries. Use this option only when IBM service requests it. The PD libraries are for use under the guidance of IBM Service. They are not shipped, so you would expect this option to fail. The -Xpd option must be specified before any other parameter; if it is not placed first, the JVM might report an unrecognized option error. For more information about the PD builds, see the Diagnostics Guide for v1.4.2.
- -Xquickstart
- Improves the startup time of applications. If you do not specify this option, the initial compilation of methods is done at high optmization (that is, the JIT does not recompile "hot" methods because the methods are initially compiled with high optimization).
- -Xrs
- Reduces the use of operating system signals.
- -Xrunlibrary_name[:options]
- 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.
- -Xss<size>
- Sets maximum native stack size for any thread. The default is 512 KB.
- -Xverbosegclog:<path to file><filename>[X, Y]
- Causes verboseGC output to be written to the specified file. If the file exists, it is overwritten. Otherwise, if an existing file cannot be opened or a new file cannot be created, the output is redirected to stderr.
If you specify the arguments X and Y (both are integers), the verboseGC output is redirected to X number of files, each containing Y number of GC cycles worth of verboseGC output. Filename must contain a "#" (hash symbol), which is substituted with a generation identifier, starting at 1. These files have the form filename1, filename2, and so on. Note:
The environment variable IBM_JVM_ST_VERBOSEGC_LOG has been removed.
- -Xverify
- Enables strictest checks, anticipating future default.
The java command and other java launcher commands (such as javaw) allow a class name to be specified as any character that is in the character set of the current locale.
You can specify any Unicode character in the class name and arguments by using java escape sequences. To do this, you must specify -Xargencoding. To specify a Unicode character, use escape sequences in the form \u####, where # is a hexadecimal digit (0 through 9, A through F).
To specify that the class name and command arguments are in UTF8 or ISO8859_1 encoding, use -Xargencoding:utf8 and -Xargencoding:latin.
In the Runtime Environment, if you are using a non-English locale, the java and javaw commands give translated output messages. These messages are different from those that were in the 1.3.1 version and also 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. Debug information that is returned during initialization is shown in brackets.
In the Runtime Environment, you can specify a class name as a complete file name including a full path and the .class extension. In previous versions of the SDK, you could specify only the class that was relative to the CLASSPATH, and the .class extension was not allowed. Use of the complete file name permits you to launch a java application from your desktop or file launcher. If you specify a .class file with path and extension, the specified path is put into the CLASSPATH. For example, the command java ~/myapp/thisapp.class is equivalent to specifying java -classpath ~/myapp thisapp.
From Version 1.4.2 Service Refresh 4, using the -jar command-line option will disable the use of a CLASSPATH.
The environment variable LIBPATH 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 executable. For example, the header section of the java command is. >dump -H /usr/java14/jre/bin/java
/usr/java14/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 bold above) 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 those listed in Index 0 of the header.
The shared libraries for the SDK are located in /usr/java14/jre/bin and/usr/java14/jre/bin/classic. These directories are automatically searched by the SDK's java launcher programs (for example, java, javac, jar). If Java is installed as an AIX fileset, the parent directory is /usr/java14/, 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:
- 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 those that contain your own libraries. For more information, see Loading JVM libraries for JNI applications.
The LD_LIBRARY_PATH environment variable is not used by Java. If your application needs to search specific directories when looking for shared libraries, the only variable to set is LIBPATH.
The LDR_CNTRL=MAXDATA environment variable controls Java's memory model (for more information, see AIX Large Address-Space Model support and AIX Very Large Address-Space Model support). If you do not set LDR_CNTRL=MAXDATA explicitly to a value, the SDK selects an appropriate value automatically. This value is based on the maximum size of the Java heap. For more information, see Default LDR_CNTRL=MAXDATA values.
You can set the system property ibm.jvm.bootclasspath by using the -D option that is described in Launching a Java application. 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 bootstrap classpath. The bootstrap classpath is either the default, or that is defined using the -Xbootclasspath: option.
Do not deploy applications that use the -Xbootclasspath: or -Xbootclasspath/p: option to override a class in core.jar, graphics.jar, server.jar, security.jar, xml.jar, tools.jar, or charsets.jar, because such a deployment would contravene the Java 2 Runtime Environment binary code license.
The -Xgcpolicy JVM runtime option specifies garbage collection policy.
-Xgcpolicy takes the values optthruput (the default), optavgpause, or subpool. The option controls garbage collector behavior, making tradeoffs 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:optthruput
-Xgcpolicy:optavgpause
-Xgcpolicy:subpool Pause time
When an application's attempt to create an object cannot be satisfied immediately from the available space in the heap, the garbage collector is responsible for identifying unreferenced objects (garbage), deleting them, and returning the heap to a state in which the immediate and subsequent allocation requests can be satisfied quickly. Such garbage collection cycles introduce occasional unexpected pauses in the execution of application code. Because applications grow in size and complexity, and heaps become correspondingly larger, this garbage collection pause time tends to grow in size and significance. The default garbage collection value, optthruput, delivers very high throughput to applications, but at the cost of these occasional pauses, which can vary from a few milliseconds to many seconds, depending on the size of the heap and the quantity of garbage.
The subpool option of -Xgcpolicy might provide additional throughput optimization because it can improve the efficiency of object allocation by reducing lock contention on large SMP systems. Pause time reduction
The optavgpause option substantially reduces the time that is spent in these garbage collection pauses, in addition to limiting the effect of increasing heap size on the length of the garbage collection pause. This option is particularly relevant to configurations that have large heaps. (Consider a heap as large when it is at least 1 GB.) The pause times are reduced by performing some garbage collection activities that are concurrent with normal program execution. With the reduced pause time, you might experience some reduction of application throughput, which varies from application to application. Environments with very full heaps
If the Java heap becomes nearly full, and very little garbage is to 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 of the above options is used; and, if requests for more heap space continue to be made, the application receives an OutofMemory exception, which results in JVM termination if the exception is not caught and handled. At this point the JVM will produce two diagnostic files: a Heapdump and a Javadump. These are detailed in the Diagnostics Guide for Java v1.4.2 and can be used to determine what caused the high occupancy of the Java heap. The Diagnostics Guide is on developerWorks(R), at: http://www.ibm.com/developerworks/java/jdk/diagnosis/. In these conditions, you are recommended either to increase the heap size by using the -Xmx option, or to reduce the number of application objects in use. Further information about garbage collection
For more detailed information about garbage collection, see:
http://www.ibm.com/developerworks/ibm/library/i-garbage1/
http://www.ibm.com/developerworks/ibm/library/i-garbage2/
http://www.ibm.com/developerworks/ibm/library/i-garbage3/
When the SDK runs in an AIX v5.2 or later logical partition (LPAR), you can move partition resources from one AIX v5.2 or later partition to another without requiring a reboot of the system of the affected partitions. Note that if you decrease the number of CPUs or real memory allocated to an LPAR, the performance of SDK applications might degrade.
If you run SDK applications on a single CPU LPAR and never dynamically add a CPU to that LPAR while those SDK applications are running, you can improve the performance (results vary depending on the execution characteristics of your application) by exporting the following environment variable: export NO_LPAR_RECONFIGURATION=1. Do not export this environment variable unless you can guarantee all of the following:
- You are running in a LPAR
- The LPAR has 1 CPU
- The LPAR will never be dynamically reconfigured to add more CPUs while SDK applications are running.
For more information, see http://www.ibm.com/servers/eserver/pseries/hardware/whitepapers/dlpar.html 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.
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.
To run an applet with the Applet Viewer, type the following at a command prompt: appletviewer name where 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 invoke the Applet Viewer on an HTML file that calls an applet, type at a command prompt:
appletviewer $HOME/filename.html where filename is the name of the HTML file.
For example, http://java.sun.com/applets/NervousText/example1.html is the URL of a Web page that calls an applet. To invoke the Applet Viewer on this Web page, type at a shell prompt:
appletviewer http://java.sun.com/applets/NervousText/example1.html
The Applet Viewer does not recognize the charset attribute of the <META> tag. If the file that appletviewer 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
You can debug applets by using the -debug option of the Applet Viewer. When debugging applets, you are advised to invoke the Applet Viewer from the directory that contains the HTML file that calls the applet. For example:
cd demo/applets/TicTacToe
../../bin/appletviewer -debug example1.htmlYou can find documentation about the debugger and its API at the Sun Web site: http://java.sun.com.
Read Loading JVM libraries for JNI applications for important information about a security fix that impacts native C/C+ applications that use the Java Native Interface (JNI) invocation API to imbed a Java virtual machine. The AIX web browsers are an example of applications that were impacted by this change. After installing Java 1.4.2 SR2 (service refresh 2) or a subsequent service refresh, you will probably receive the following error message when viewing a Java applet in the browser: # mozilla
Error: could not find libjavaplugin_oji.so
Plugin: can't find plugins/../java directory
INTERNAL ERROR on Browser End: Could not start JavaVM!
System error?:: A file or directory in the path name does not exist. To correct this problem, export LIBPATH=/usr/java14/jre/bin:/usr/java14/jre/bin/classic before running the Web browser.
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.
Java Plug-in for AIX Mozilla
The Mozilla for AIX Web browser is available from:
When the installation is complete, to use the Java Plug-in, create one of the following links: ln -s /usr/java14/jre/bin/libjavaplugin_oji.so
/usr/mozilla/base/plugins/libjavaplugin_oji.so or: ln -s /usr/java14/jre/bin/libjavaplugin_oji.so
$HOME/.mozilla/plugins/libjavaplugin_oji.soTo verify that the Java Plug-in is available and enabled, in Mozilla select Help -> About Plug-ins.
This Java Plug-in supports Mozilla 1.4, 1.7, and backward-compatible newer versions shipped as an option of the AIX operating system.
Note that you can have only one Java Plug-in shared library in /usr/mozilla/base/plugins. Mozilla attempts to load anything that is in that directory (or subdirectories underneath it) as a Plug-in, and results are unpredictable if two versions of the Java Plug-in are loaded. Visual Age C/C++ compiler object model
The Mozilla Java Plug-in is compiled with the Visual Age compiler compat object model -qobjmodel=compat. Only versions of Mozilla that were compiled with the same compiler object model work with the Mozilla Java Plug-in. Checking the compile option with which Mozilla was compiled
To find out the compiler object model with which your Mozilla has been compiled, type about:buildconfig in the URL field of Mozilla. If Mozilla was compiled with the ibm object model, the text -qobjmodel=ibm will appear in the "Compiler Flags" section of the build configuration options; if Mozilla was compiled with the compat object model, the "Compiler Flags" section will not display any objmodel information.. Java Plug-in for AIX Communicator V4
To use the Java Plug-in, ensure that the following link exists: ln -s /usr/java14/jre/bin/javaplugin.so
/usr/netscape/communicator/plugins/javaplugin.so To verify that the Java Plug-in is available and enabled, select Help -> About Plug-ins in Netscape Communicator.
To work around problems that you might have with Netscape's version of the C runtime (libc.a), any LIBPATH entries that contain "netscape/communicator" are ignored in the LIBPATH that is passed to the Plug-in's JVM. The Plug-in's JVM should load the system C runtime (/lib/libc.a) only. The side effect of this is that LIBPATH dependent JVM calls (such as System.loadLibrary()) return an UnsatisifiedLinkError exception if you attempt to load a shared library from a "netscape/communicator" path from within the Plug-in.
This Java Plug-in supports Netscape 4.8 and will not load with earlier versions of the Netscape browser that shipped with the AIX operating system.
Note that you can have only one Java Plug-in shared library in the directory /usr/netscape/communicator/plugins for Netscape 4. Netscape attempts to load anything that is in that directory or subdirectories underneath it as a Plug-in, and results are unpredictable if two versions of the Java Plug-in are loaded. 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 standalone Java application. To launch this Java application, run the shell script: /usr/java14/jre/bin/JavaPluginControlPanel
Using the Java Plug-in
The Java Plug-in is a Web browser plug-in. If you use the Java Plug-in, you can bypass your Web browser's default JVM and use instead a Runtime Environment for running applets or beans in the browser.
The Java Plug-in is documented by Sun at: http://java.sun.com/j2se/1.4.2/docs/guide/plugin/developer_guide/. Supported browsers
Table 1. Browsers supported by the Java Plug-in
| Operating System |
Supported Browsers |
| AIX V5.1 |
|
| AIX V5.2 |
|
| AIX v5.3 |
Mozilla 1.4, 1.7, available at http://www.ibm.com/servers/aix/browsers/ and the Mozilla for AIX CD. |
Notes:
- Netscape 4 can fail if you click the Back button while a v1.4.2 applet is running through the Plug-in (a problem not unique to the Java Plug-in).
- The <APPLET> tag does not invoke the Plug-in on Netscape 4. In Mozilla, the <APPLET>, <OBJECT>, and <EMBED> tags invoke the Plug-in. In Netscape 4, only <OBJECT> and <EMBED> invoke the Plug-in.
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.
- A sun.plugin.dom.exception.NotSupportedException is thrown for some of these functions.
- A sun.plugin.dom.exception.InvalidStateException is thrown when the browser does not support a particular function.
Using DBCS parameters
The Java Plug-in supports double-byte characters (for example Chinese Traditional BIG-5, Korean, 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. 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 using. All the parameters are passed to the Java Plug-in correctly. However, some of the 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.
You can specify which encoding you want to use to parse the HTML file:
- Netscape 4: View Menu -> Character Set
- Mozilla: View Menu -> Character Coding
The Java Plug-in HTML converter allows you to convert any HTML page that contains applets to a format that will use the Java Plug-in. The tool is in the /usr/java14/bin directory with a jar file in the /usr/java14/lib directory.
For more information about the Java Plug-in HTML Converter, see the Sun Web site: http://java.sun.com/j2se/1.4.2/docs/guide/plugin/developer_guide/html_converter.html
Consider the following string of tokens:
opcode:attributeName:attributeValue\t
In Version 1.2.2, you set the delimiter to ":", and through the nextToken() method of StringTokenizer obtain the token's "opcode" and "attributeName". Then the delimiter is changed to "\t", and token "attributeValue" is returned with StringTokenizer.nextToken().
In Version 1.3 and 1.4, if the delimiter is changed midway through tokenizing, the next token starts with the old delimiter. The token returned is ":attributeValue". Your application must check to see whether the next token is prepended with the previous delimiter when the delimiter has been changed, and remove it if it is.
The IBM 32-bit SDK for AIX, v1.4 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 machine to handle IPv6 addresses. The network interfaces can be configured for IPv6 with smitty or by using the autoconf6 or ifconfig commands. Alternatively, if you do not want to use IPv6 protocols, you can set the property java.net.preferIPv4Stack to force the use of IPv4 protocols.
However, all levels of AIX v5.1 currently do not support IPv4-mapped Multicast addresses. If you are using an IPv4 Multicast address, you cannot join a Multicast group whether or not you are switching your application to IPv6. You must change the default of your application by setting the java.net.preferIPv4Stack to true: java -Djava.net.preferIPv4Stack=true <classname> where <classname> is the file name of your .class file.
Thread pooling for RMI Connection Handlers is not enabled by default.
To enable the connection pooling implemented at the RMI TCPTransport level, set the option -Dsun.rmi.transport.tcp.connectionPool=true (or any non-null value) This version of the Runtime Environment does not have any setting that you can use to limit the number of threads in the connection pool.
The Java 2 Platform, Standard Edition (J2SE) supports, at a minimum, the specifications that are defined in the Official Specifications for CORBA support in J2SE V1.4 at http://java.sun.com/j2se/1.4.2/docs/api/org/omg/CORBA/doc-files/compliance.html. In some cases, the IBM J2SE ORB supports more recent versions of the specifications.
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, which you can obtain from:
http://www.omg.org/cgi-bin/doc?formal/99-10-07
Bidirectional GIOP is not supported.
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 through which ORB services can intercept the normal flow of execution of the ORB.
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 Sun Java Core API at Version 1.4.2. Programs that need 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.
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 is controlled by three system properties.
- To turn on tracing, set com.ibm.CORBA.Debug=true .
- To format and add to the trace GIOP m
| 
