IBM® AIX® Developer Kit, Java^(TM) 2 Technology Edition, Version 1.3.1, 32-bit version for POWER
- README -

- Compiles programs written in the Java programming language into bytecodes (compiled Java code).

- Executes Java bytecodes. The Java Interpreter runs programs written in the Java programming language.

- Use for testing and running applets.

- Helps debug your Java programs.

- Disassembles compiled files and prints a representation of the bytecodes.

- Parses the declarations and documentation comments in a set of source files and produces a set of HTML pages describing the public and protected classes, interfaces, constructors, methods, and fields. Also produces a class hierarchy and an index of all members.

- Attaches native methods to code written in the Java programming language.

- Generates signatures for Java Archive (JAR) files, and verifies the signatures of signed JAR files.

- Manages entities, including their keys, certificates, and the trust associated with them.

- Manages a keystore (database) of private keys and their associated X.509 certificate chains authenticating the corresponding public keys.

- Creates and modifies the external policy configuration files that define your installation's Java security policy.

- Converts a native encoding file to an ASCII file that includes the \udddd Unicode notation.

- Generates objects from the names of compiled classes that contain remote object implementations. Includes RMI-IIOP support.

- Starts the activation system daemon so that objects can be registered and activated in a Java virtual machine (JVM).

- Compiles OMG Interface Definition Language files to Java code.

- Starts the CORBA transient naming service.

- Creates and starts a remote object registry on the specified port of the current host.

- Returns the serialVersionUID for one or more classes in a form suitable for copying into an evolving class.

- Detects version conflicts between a target jar file and currently installed extension jar files.

Developer Kit README: This file, README.HTML, which is in the docs subdirectory of the directory where you installed the Developer Kit.

Copyright: Copyright notice for the Developer Kit software, which is in the directory where you installed the Developer Kit.

fixes.html: A file that describes any defects fixed after the initial release of this version. This file is in the directory where you installed the Developer Kit but will not be found in the first release.

Java examples and demos: Java131.samples is an optional package with the following subdirectories installed in the /usr/java131/demo directory:

• applets
  - Demo programs for applets.
• bigdecimal
  - Example programs and README for enhanced BigDecimal class.
• jdbcodbc
  - Example programs and README for Jdbc-Odbc Bridge.
• jfc
  - Demo programs for Swing and Java2D.
• jni
  - Example programs and README for developing JNI programs on AIX.
• jpda
  - Example programs for JPDA.
• rmi-iiop
  - Example programs for RMI-IIOP.
• Sound
  - Demo programs for Sound.
• xml4j
  - Demo programs for XML parsing
• misc
  - Miscellaneous demo programs

The Java security packages install the following subdirectories in /usr/java131/demo directory:

• cmp
  - Demo programs for Certificate Management Protocol.
• ikeyman
  - Demo programs for iKeyman (IBM key tool).
• jce
  - Demo programs for Java Cryptographic Extension.
• jsse
  - Demo programs for Java Secure Sockets Extension.
• pkcs
  - Demo programs for Public Key Cryptographic Standards.

Note:

See the documentation directory (/usr/java131/docs) for additional information about this Developer Kit. You might also be interested in downloading Sun's documentation package from this Web site:

http://java.sun.com/products/jdk/1.3/

The documentation package is designed to be extracted into the Developer Kit software installation directory. If you download the ZIP file archive version, make sure you preserve the path names when you extract the files from the archive.

The Just-In-Time (JIT) compiler

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 v4.0 compiler delivers dynamic compiler technology, including:

• Improvements to optimizations implemented in previous versions of the JIT
• Optimizations added to JIT v4.0
• Stack allocation of objects
• Improved hardware exploitation
• Startup time improvements with the -Xquickstart option

All Developer Kit 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.

Disabling the JIT

There are two ways to disable the JIT:

• Type the following at a command prompt:

For the Korn shell:

export JAVA_COMPILER=NONE

(Korn shell commands are used for the rest of this README)

For the Bourne shell:

JAVA_COMPILER=NONE

export JAVA_COMPILER

For the C shell:

setenv JAVA_COMPILER NONE

• Use the -D option on the java command to set java.compiler to NONE to override the default or the environment variable settings:

java -Djava.compiler=NONE <myapp>

Enabling the JIT

To enable the JIT, set the JAVA_COMPILER to "jitc" or switch the JIT compiler on through the command line:

java -Djava.compiler=jitc <myapp>

Determining whether the JIT is enabled

To determine if 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.

Using the Developer Kit

The following sections provide information about using the Developer Kit.

Setting the path

The main Developer Kit tools are programs that are run from a command prompt. After installing the Developer Kit 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/java131/bin, you can compile a file named myfile.java by typing the following at a command prompt:

   /usr/java131/bin/javac myfile.java

   javac myfile.java

   echo $PATH

Note:

Like the 1.3.0 version, the IBM AIX Developer Kit, Java 2 Technology Edition, Version 1.3.1 ships the java tools as binary executables as opposed to shipping shell scripts 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/java131/bin:/usr/java131/jre/bin:$PATH

Although jre/sh and sh are now links created by installp packaging for backward compatibility, you are strongly advised to use jre/bin and bin directories as these links may not be guaranteed in future releases.

Tools options

To get the command options of java, type:

java

Note: The output from the -verbosegc option is not guaranteed to remain the same in future releases, and should be used only as a guide to the functioning of garbage collection.

To get the nonstandard options of java, type the following at a command prompt:

java -X

To get help on profiling options of java, type:

javaSimilarlyrof:help

Similarly, javac command options can be obtained with the following command:

javac

The command options allowed for the java command can be passed to the runtime system when you are using tools like javac or javadoc as follows:

javac -Jflag *.java

For example, to disable the JIT when compiling classes, the command is:

javac -J-Djava.compiler=none *.java

Some standard command options in Java 1.1.x have been changed to nonstandard options, and some of the 1.1.x command options are not formally supported. However, command options in 1.1.x format are still supported in this release for backward compatibility but it is not guaranteed that they will be supported in future releases.

Improving the startup time of Java applications

-Xquickstart is a JVM option used for improving startup time of some Java applications. -Xquickstart causes the JIT to run with a subset of optimizations - a quick compile. This quick compile allows for improved startup time.

-Xquickstart is appropriate for shorter-running applications, especially those for which execution time is not concentrated in a small number of methods. -Xquickstart might degrade performance if used on longer-running applications containing hot methods.

The implementation of -Xquickstart is subject to change in future releases.

IBM Java options

You can specify Java options and system properties by creating an environment variable, IBM_JAVA_OPTIONS, and setting it to the values you require. Any Java options or system properties specified must be preceded by a space, except for the first option. For example, you could set up the options as follows:

  exportIBM_JAVA_OPTIONS="-Dmysysprop1=tcpip -Dmysysprop2=wait"

If you specify the same options or properties from the command line (or from a JNI program), these options take precedence over the options and properties specified by the environment variable. The only exception to this rule is when specifying -Xt, -Xtm, or -Xdebug, which all imply that no JIT should be used.

To provide compatibility when running with Java 1.1 programs, IBM_JAVA_OPTIONS has no effect when running with JNI_VERSION_1_1. For more information, see:

http://java.sun.com/products/jdk/1.2/docs/guide/jni/jni-12.html

Also, Java options should be specified in their current format; for example, -verbose:gc rather than -verbosegc.

Defaults

If no command options are used when calling java, the following defaults are used:

• JIT is on, but you can disable the JIT.
• Initial Java heap size is 1M. Use -Xms<number> to change size.
• Maximum Java heap size is 64M. Use -Xmx<number> to change size.

You can specify numbers in kilobyte or megabyte for command options; for example, -Xms1024K or -Xmx128M.

Setting the CLASSPATH

The CLASSPATH tells the Java Virtual Machine (JVM) and other Java applications where to find the class libraries. The class libraries, such as the rt.jar file, are located in the /usr/java131/jre/lib directory. This path is already set up by the JVM. If you keep the bin and lib directories under the same parent directory level, the executable files will find the classes.

You need to set the CLASSPATH only if you move the classes provided by the JVM, or if you want to use other classes (such as classes you develop).

Note: If you want to develop applications in several versions of the Developer Kit (for example, 1.1.8 and 1.3.1), you must set the CLASSPATH and PATH separately for the different versions. For details, refer to the respective Developer Kit READMEs.

To see if the CLASSPATH is set, type the following at a command prompt:

echo $CLASSPATH

To set the CLASSPATH to include a particular class of an application, follow this model:

    export CLASSPATH=/java/apps/classes:$CLASSPATH

To reset the CLASSPATH to null and remove unwanted classes, type the following at a command prompt:

    export CLASSPATH=

Required AIX environment variables for JNI

You must set the following environment variables before running Java if you are using JNI:

export AIXTHREAD_SCOPE=S

export AIXTHREAD_MUTEX_DEBUG=OFF

export AIXTHREAD_RWLOCK_DEBUG=OFF

export AIXTHREAD_COND_DEBUG=OFF

For more information on these environment variables, see the JNI Compatibility section of this README.

Setting the LIBPATH and the Use of LD_LIBRARY_PATH

The shared libraries for JVM are located in jre/bin and jre/bin/classic subdirectories of your Java Installation - if Java was installed as an AIX fileset this will be /usr/java131, but packages which "bundle" Java may use different directories. This path is already set up by the Java "launcher" programs such as "java", "javac", "jar", etc.

You need to set the LIBPATH

• If you are using other shared libraries (such as libraries you develop). In this case, you will need to set LIBPATH to include the directory or directories containing your libraries.
• If you use the JNI Invocation API to launch a JVM from one of your own programs. In this case you will need to set LIBPATH to include the directories containing the JVM libraries, plus those containing any libraries of your own.

Obtaining the IBM Build and Version Number

The IBM build and version number can be obtained by typing the following at a command prompt:

    java -version

Running applets with the Applet Viewer

The Applet Viewer allows you to run one or more applets that are called by reference in a Web page (HTML file) 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 an entire Web page that contains numerous HTML tags. It parses only the APPLET tag and no other HTML on the Web page.

To run an applet with the Applet Viewer, type the following at a command prompt:

    appletviewer filename

To invoke the Applet Viewer on a file-based Web page, go to the directory where you installed the Developer Kit package and at the command prompt type:

    bin/appletviewer demo/applets/GraphLayout/example1.html

To invoke the Applet Viewer on a URL-based Web page, at the command prompt type:

    bin/appletviewer http://java.sun.com/applets/NervousText/example1.html

Debugging applets with the Applet Viewer

You can debug applets 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 applet's HTML file. For example:

    cd demo/applets/TicTacToe

    ../../bin/appletviewer -debug example1.html

http://java.sun.com/products/jdk/1.3/debugging/

Java Plug-in HTML converter

The Java Plug-in HTML Converter is a utility that allows you to convert any HTML page that contains applets to a format that will use the Java Plug-in. The utility is in the sdk/bin directory with a jar file in sdk/lib.

For more information about the Java Plug-in HTML Converter, see this Sun Web site:

http://www.javasoft.com/products/plugin/1.3/features.html

Change in behavior of StringTokenizer class

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().

From Version 1.3.0, if the delimiter is changed mid-way through tokenizing, the next token  starts with the old delimiter. The token returned is ":attributeValue". Your application must check to see if the next token is prepended with the previous delimiter once the delimiter has been changed and remove it if it is.

Specifying garbage collection policy

The IBM AIX Developer Kit, Java 2 Technology Edition, Version 1.3.1 introduces the -Xgcpolicy JVM runtime option for specifying garbage collection policy.

-Xgcpolicy takes two values, optthruput (the default) and optavgpause. The option controls garbage collector behavior, making tradeoffs between throughput of the application and overall system and the pause times caused by garbage collection.

The format of the option and its values is:

-Xgcpolicy:optthruput

-Xgcpolicy:optavgpause

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. As 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.

Pause time reduction

The optavgpause value substantially reduces the time spent in these garbage collection pauses, as well as limiting the effect of increasing heap size on the length of the garbage collection pause. This is particularly relevant to configurations with large heaps. (Consider a heap as large when it is at least 1 GB.) The pause times are reduced by overlapping garbage collection activities with normal program execution. This overlapping results in a small reduction to application throughput.

Environments with very full heaps

If the Java heap becomes nearly full, and there is very little garbage to be reclaimed, requests for new objects might not be satisfied quickly because there is no space 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 Out of Memory exception, which results in JVM termination if the exception is not caught and handled. In these situations, you are recommended either to increase the heap size using the -Xmx option or to reduce the number of application objects in use.

Further information about garbage collection

For information on heap size tuning and the implications of garbage collection for application performance, see:

http://www.ibm.com/developerworks/java/jdk/diagnosis/

http://www.ibm.com/developerworks/java/jdk/diagnosis/addenda-131.html

http://www.ibm.com/developerworks/java/library/j-jtctips/

AIX native threads

The IBM AIX Developer Kit, Java 2 Technology Edition, Version 1.3.1 uses the AIX POSIX threads (pthreads) package for its threading. This means that Java threads can be scheduled on multiple processors on multiprocessor systems. Although Java thread priorities can be controlled using the standard Java interfaces, the underlying native thread priorities are controlled by the AIX scheduler using the default AIX scheduling policy (SCHED_OTHER).

For more details on AIX thread scheduling, see:

http://publib.boulder.ibm.com/doc_link/en_US/a_doc_lib/aixprggd/genprogc/threads_sched.htm

Then select "General Programming Concepts: Writing and Debugging Programs -> Threads Programming Guidelines -> Threads Scheduling".

Scaling support

For maximum threads (with JIT) try setting the command line parameter with -ss<size> by specifying the maximum native stack size to be smaller than the default value which is 256K. A smaller setting allows for a larger number of threads. For example:

java -ss<size> <other params>

For maximum file descriptors, use the command line statement ulimit, for example:

ulimit -n 3000

chuser nofiles=3000 <user_id>

to increase the limit. (ulimit -a shows the current limit.)

Large program model support

The JVM of the IBM AIX Developer Kit, Java 2 Technology Edition, Version 1.3.1 supports the large program model. For more details on the large program model, see:

http://publib.boulder.ibm.com/doc_link/en_US/a_doc_lib/aixprggd/genprogc/lrg_prg_support.htm

Then select "General Programming Concepts: Writing and Debugging Programs -> Large Program Support -> Understanding the Large Address-Space Model".
Note: AIX's Very Large Address-Space Model is not supported by Java 1.3.1.

By default, Java runs using the eight segments. (Eight is the maximum value allowed; each segment is 256 MB). You can reduce the number of segments Java uses with the LDR_CNTRL environment variable. For example, if you want Java to use only three segments set LDR_CNTRL to the following value prior to starting Java:

export LDR_CNTRL=MAXDATA=0x30000000

Specifying LDR_CNTRL=MAXDATA=0 restricts a program to one segment for data. However, if a Java invocation specifies a heap of greater than 1 GB, the JVM switches from allocating the Java heap in the data area to doing an mmap. Therefore, for a Java heap less than or equal to 1 GB, you should not specify LDR_CNTRL=MAXDATA=0 (which uses the normal large data support). With a Java heap of greater than 1 GB, specify LDR_CNTRL=MAXDATA=0 to free up data segments for use by the mmap.

If you are running with very large heap sizes (in general, greater than 2GB), you have limited memory available for non-object allocation. In this situation, you might see Out of Memory exceptions. Also, the JVM might not close down cleanly because further storage allocations are required to shut down the JVM, and these allocations will probably fail.

JNI compatibility

The C/C++ compiler on AIX 4.3 is installed in /usr/ibmcxx and on AIX 5.1 is installed in /usr/vacpp. Because of incompatibility between the IBM AIX Developer Kit, Java 2 Technology Edition, Version 1.3.1 and some system-defined types, compilation of JNI code requires that the compiler uses the flag _AIX43. This flag is defined by default in /etc/ibmcxx.cfg on AIX 4.3 and defined in /etc/vac.cfg and /etc/vacpp.cfg on AIX 5.1. But, if you are using a version of xlc prior to v3.6.4 on AIX 4.3, you must add _AIX43 to /etc/xlC.cfg or use -D_AIX43 as a compilation command-line option. Also, make sure that you are building while in the correct Developer Kit environment.

The Developer Kit does not support runtime linking (using the -brtl loader option). Any applications built for use with the Developer Kit should not rely on runtime linking functionality.

When executing a JNI program (for example, a non-java application executable that creates and initializes a JVM and then runs .class files on that JVM), make sure that the CLASSPATH is set up correctly to enable the JVM to find your class files. If you modify the Java 2 boot class path, include the Developer Kit files necessary to run your applications.

This product has made use of AIX extensions to enable faster and more efficient execution without impacting non-Java applications. The launchers, and other programs in this release, use these extensions automatically, but, for use by another program, that program must be linked with an additional AIX binder option (-bM:UR). If you develop a JNI program that creates and attaches to the JVM in this and future releases, this binder option is required. The (-bM:UR) option is only for application programs with a main executable; it has no meaning for shared modules/libraries and can introduce errors if it is used to build a shared library.

A side-effect of this requirement is that such JNI executable programs, including third-party software packages and those built for previous Java software releases on AIX, that were built without this binder option, are NOT compatible with the JVM in this release.

Compatibility of an executable program can be verified using:

dump -ov

The stdout output will show the modtype to be 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:

The Developer Kit uses an advanced IBM technology called Mixed Mode Interpreter (MMI), which significantly reduces the startup time of the JVM. The MMI and JIT compiler make use of internal calling conventions and SIGTRAP signals that might make debugging of JNI programs using dbx more difficult.

The Developer Kit handles various AIX signals. If you install your signal handler after launching the JVM, you must chain your signal through to the JVM's handler. Where signal handlers are installed by JNI invocation API applications before launching the JVM, the JVM attempts to chain to the existing handlers when receiving unexpected signals.

Java threads created by the Developer Kit use the POSIX pthreads model 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. This can be controlled 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:

http://publib.boulder.ibm.com/doc_link/en_US/a_doc_lib/aixprggd/genprogc/understanding_threads.htm#D3A446E559manu

http://publib.boulder.ibm.com/doc_link/en_US/a_doc_lib/aixprggd/genprogc/threads_sched.htm#D3A44A4324manu

Then select: "Understanding Threads".

AIX sets default value of the AIXTHREAD_MUTEX_DEBUG, AIXTHREAD_RWLOCK_DEBUG and AIX_THREAD_COND_DEBUG environment variables ON. A JNI program that creates and attaches to a JVM must set these environment variables OFF. See: http://publib.boulder.ibm.com/doc_link/en_US/a_doc_lib/aixbman/prftungd/2365a81.htm#34490 (for AIX 4.3.3) and http://publibn.boulder.ibm.com/doc_link/en_US/a_doc_lib/aixbman/prftungd/2365a81.htm#HDRI34490 (for AIX 5.1).

Note: The old-style native interface is no longer supported.

There is a README file and example programs in the /usr/java131/demo/jni directory. The demos can be optionally installed with the Java131.samples package.

Fonts and locales

Certain performance enhancements have been added to improve text-draw operations in the case of simple text. If you experience problems with text or with fonts, try disabling this performance enhancement by setting the environment variable:

export JAVA2D_USEAWTFONTS=0

Euro symbol support

Support for the European Union currency, the Euro, is included in this release of the IBM AIX Developer Kit, Java 2 Technology Edition, Version 1.3.1. Platform-level support is required to make use of this.

On AIX, the Euro is supported by the ISO8859-15 and UTF8 locales. They are the primary mechanisms for Euro support on the AIX operating system. Applications can then make use of the Euro symbol, which looks like a 'C' with '=' superimposed on it and can be created using Unicode character '\u20AC'. Euro variants of Java software locales, which provide the appropriate currency formatting, can also be used by Java applications. The environment variable LC_MONETARY is currently not used by this Java implementation.

For more information on IBM's position on the Euro currency, see http://www.ibm.com/euro.

Unicode font

To obtain multi-lingual text, you must install the WorldType fonts that are available on the AIX distribution media as the package X11.fnt.ucs.ttf (AIXwindows Unicode TrueType Fonts). There are alternative versions of this font for Chinese and Korean. If you decide not to install the WorldType fonts, an undefined glyph symbol (normally an open rectangle) will be displayed if that font is not available. The fonts are installed automatically if you install the UTF8 locales.

Also, Java 1.3.1 uses the Monotype Unicode fonts shipped with AIX (Times New Roman WorldType and Sans Monospace WorldType) to support Devanagari (Hindi) fonts.

Supported locales

The IBM AIX Developer Kit, Java 2 Technology Edition, Version 1.3.1 supports all the locales supported by the AIX platform. The user interface is provided in these languages:

• Brazilian Portuguese
• Catalan
• Czech
• English
• French
• German
• Hungarian
• Italian
• Japanese
• Korean
• Polish
• Russian
• Simplified Chinese
• Slovak
• Spanish
• Traditional Chinese

Translation from English is partial, in particular in the programming and error handling areas, where you will see some English.

IBM AIX Developer Kit, Java 2 Technology Edition, Version 1.3.1, 32-bit version for POWER adds support for these CORBA specifications:

This Developer Kit 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://cgi.omg.org/cgi-bin/doc?formal/99-10-07

Bi-directional GIOP is not supported.

This Developer Kit supports Portable Interceptors, as defined by the OMG in the document formal/01-09-58, which you can obtain from:

http://cgi.omg.org/cgi-bin/doc?formal/01-09-58

Portable Interceptors are hooks into the ORB through which ORB services can intercept the normal flow of execution of the ORB.

Several new classes are introduced in the API to support Portable Interceptors. These are:

org.omg.CORBA.LocalObject
org.omg.Dynamic.Parameter
org.omg.IOP.Codec
org.omg.IOP.CodecFactory
org.omg.IOP.CodecFactoryHelper
org.omg.IOP.CodecFactoryOperations
org.omg.IOP.CodecFactoryPackage.UnknownEncoding
org.omg.IOP.CodecOperations
org.omg.IOP.CodecPackage.FormatMismatch
org.omg.IOP.CodecPackage.InvalidTypeForEncoding
org.omg.IOP.CodecPackage.TypeMismatch
org.omg.IOP.ENCODING_CDR_ENCAPS
org.omg.IOP.Encoding
org.omg.IOP.ServiceContext
org.omg.IOP.TaggedComponent
org.omg.IOP.TaggedProfile
org.omg.Messaging.SYNC_NONE
org.omg.Messaging.SYNC_WITH_SERVER
org.omg.Messaging.SYNC_WITH_TARGET
org.omg.Messaging.SYNC_WITH_TRANSPORT
org.omg.PortableInterceptor.ClientRequestInfo
org.omg.PortableInterceptor.ClientRequestInfoOperations
org.omg.PortableInterceptor.ClientRequestInterceptor
org.omg.PortableInterceptor.ClientRequestInterceptorOperations
org.omg.PortableInterceptor.Current
org.omg.PortableInterceptor.CurrentHelper
org.omg.PortableInterceptor.CurrentOperations
org.omg.PortableInterceptor.ForwardRequest
org.omg.PortableInterceptor.IORInfo
org.omg.PortableInterceptor.IORInfoOperations
org.omg.PortableInterceptor.IORInterceptor
org.omg.PortableInterceptor.IORInterceptorOperations
org.omg.PortableInterceptor.Interceptor
org.omg.PortableInterceptor.InterceptorOperations
org.omg.PortableInterceptor.InvalidSlot
org.omg.PortableInterceptor.LOCATION_FORWARD
org.omg.PortableInterceptor.ORBInitInfo
org.omg.PortableInterceptor.ORBInitInfoOperations
org.omg.PortableInterceptor.ORBInitInfoPackage.DuplicateName
org.omg.PortableInterceptor.ORBInitInfoPackage.InvalidName
org.omg.PortableInterceptor.ORBInitializer
org.omg.PortableInterceptor.ORBInitializerOperations
org.omg.PortableInterceptor.PolicyFactory
org.omg.PortableInterceptor.PolicyFactoryOperations
org.omg.PortableInterceptor.RequestInfo
org.omg.PortableInterceptor.RequestInfoOperations
org.omg.PortableInterceptor.SUCCESSFUL
org.omg.PortableInterceptor.SYSTEM_EXCEPTION
org.omg.PortableInterceptor.ServerRequestInfo
org.omg.PortableInterceptor.ServerRequestInfoOperations
org.omg.PortableInterceptor.ServerRequestInterceptor
org.omg.PortableInterceptor.ServerRequestInterceptorOperations
org.omg.PortableInterceptor.TRANSPORT_RETRY
org.omg.PortableInterceptor.USER_EXCEPTION

These classes are not part of the Sun Java 1.3 Core API, and could change in future versions of the IBM Developer Kit.

This Developer Kit has added support for the Interoperable Naming Service, as defined by the OMG in the document ptc/00-08-07, which you can obtain from:

http://cgi.omg.org/cgi-bin/doc?ptc/00-08-07

The default port 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 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.

Several new classes are introduced in the API to support the Interoperable Naming Service:

org.omg.CosNaming.NamingContextExt
org.omg.CosNaming.NamingContextExtHelper
org.omg.CosNaming.NamingContextExtHolder
org.omg.CosNaming.NamingContextExtOperations
org.omg.CosNaming.NamingContextExtPackage.AddressHelper
org.omg.CosNaming.NamingContextExtPackage.InvalidAddress
org.omg.CosNaming.NamingContextExtPackage.InvalidAddressHelper
org.omg.CosNaming.NamingContextExtPackage.InvalidAddressHolder
org.omg.CosNaming.NamingContextExtPackage.StringNameHelper
org.omg.CosNaming.NamingContextExtPackage.URLStringHelper
org.omg.CosNaming._NamingContextExtImplBase
org.omg.CosNaming._NamingContextExtStub

These classes are not part of the Sun Java 1.3 Core API, and could change in future versions of the IBM Developer Kit.

The initial context returned from the Transient Name Server is now an org.omg.CosNaming.NamingContextExt. Existing programs that narrow the reference to an org.omg.CosNaming.NamingContext will still work, and do not need to be recompiled.

The ORB supports the -ORBInitRef and -ORBDefaultInitRef parameters defined by the Interoperable Naming Service specification, and the ORB::string_to_object operation now supports the ObjectURL string formats (corbaloc: and corbaname:) 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.3.1. 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":

where orb is an instance of org.omg.CORBA.ORB, returned from ORB.init(), and serviceRef is a CORBA Object, connected to the ORB. This mechanism is an interim one, and is not compatible with future versions or portable to non-IBM ORBs.

A new 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. Set com.ibm.CORBA.Debug=true to turn on tracing. To format and add to the trace GIOP messages sent and received, set com.ibm.CORBA.CommTrace=true. By default, ORB tracing goes to the standard error stream, java.lang.System.err. To direct it to a file, set com.ibm.CORBA.Debug.Output. For example, to trace events and formatted GIOP messages to a file:

The trace will be sent to the files orbtrc.DDMMYYYY.HHmm.SS.txt and orbmsg.DDMMYYYY.HHmm.SS.txt.

Do not turn on tracing for normal operation, because it might cause performance degradation.

The content and format of the trace output could vary from version to version.

The following properties help you to tune the ORB:

• To control GIOP 1.2 fragmentation, set the system property com.ibm.CORBA.FragmentSize. For example, to set the fragment size to 4096 bytes: java -Dcom.ibm.CORBA.FragmentSize=4096 myapp

  The default fragment size is 1024 bytes. You can turn off fragmentation by setting the fragment size to 0.

• In a heterogeneous network, the response to a CORBA Request could be delayed or lost. You can set the maximum time to wait using the system property com.ibm.CORBA.RequestTimeout. Also, you can use com.ibm.CORBA.LocateRequestTimeout to control the timeout for LocateRequests. For example, to restrict both delays to 30 seconds: java -Dcom.ibm.CORBA.RequestTimeout=30 -Dcom.ibm.CORBA.LocateRequestTimeout=30 myapp

  By default, the ORB waits indefinitely for a response. Do not set the timeout too low, or connections might be ended unnecessarily.

• If your program is providing a service in the network, you might have to set to a well-known value the number of the port from which the ORB reads incoming requests. You can control this using the system property com.ibm.CORBA.ListenerPort. For example, to make the ORB use port 1050: java -Dcom.ibm.CORBA.ListenerPort=1050 myapp

  If this property is set, the ORB starts listening as soon as it is initialized. Otherwise, it starts listening only when required.

The following properties may be necessary to enable non-standard behaviour for some vendor ORBs:

• To use the POA ImplicitActivation policy with, for example, older Visibroker ORBs, it may be necessary to set the system property com.ibm.CORBA.POACompatibilityMode=true

  This property causes non-standard system exception, CORBA::OBJ_ADAPTER, to be thrown from org.omg.PortableServer.Servant._get_delegate when the delegate is null, in place of the standard exception CORBA::BAD_INV_ORDER.

  When using an ORB whose POA implementation relies upon receiving the CORBA::OBJ_ADAPTER system exception without this property set, the following failure may be observed: org.omg.CORBA.INTERNAL:org.omg.CORBA.BAD_INV_ORDER: The Servant has not been associated with an ORBinstance

When running with a Java 2 SecurityManager, invocation of some methods in the CORBA API classes might cause permission checks to be made, which could result in a SecurityException. Affected methods include the following:

If your program uses any of these methods, ensure that it is granted the necessary permissions.

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. Theses values might be changed in future releases.

Implementing the Connection Handler Pool for RMI

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

RMI over IIOP

Java Remote Method Invocation (RMI) provides a straightforward mechanism to do distributed Java programming. RMI over IIOP (RMI-IIOP) extends the base Java RMI to perform communication using the CORBA standard Internet Inter-ORB Protocol (IIOP protocol). This allows direct interaction with any other CORBA Object Request Brokers (ORBs), whether they were implemented in Java or another programming language.

For information about IBM and RMI-IIOP, see the following IBM Web site:

http://www.ibm.com/developerworks/java/rmi-iiop

The following documentation is available:

• The RMI-IIOP Programmer's Guide is an introduction to writing RMI-IIOP programs. The guide is installed when you install the Developer Kit and is on the Web site under "Documents".

• The IDL-to-Java Compiler User's Guide describes how to use the tool that generates Java code from IDL. The guide is installed when you install the Developer Kit and is on the Web site under "Documents".

• The samples directory 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 IDL program (demo/rmi-iiop/idl)

• The Java Language to IDL Mapping document is a detailed technical specification of RMI-IIOP and can be found at the following FTP site:

  http://cgi.omg.org/cgi-bin/doc?ptc/00-01-06.pdf

Enhanced BigDecimal

The Runtime Environment includes an enhanced BigDecimal class (com.ibm.math.BigDecimal) for Java programming as an alternative to the java.math.BigDecimal class. The new class (with its supporting class MathContext) is fully implemented and exploits the java.lang.Comparable interface, which is used for sorting in the Java 2 language.

If you are using the java.math.BigDecimal class in a Java program and you want to access the Enhanced BigDecimal class, you must change the import statement in your source code as shown.

Change:

import java.math.*;

to:

import com.ibm.math.*;

You do not need to change any other code.

More information about enhanced BigDecimal can be found at:

JDBC-ODBC Bridge

This Developer Kit includes a JDBC-ODBC bridge which supports JDBC 2.0. You need ODBC Driver Manager of version 3.5.0 or above to work with this release of JDBC-ODBC Bridge. The bridge assumes that your ODBC driver can support concurrency and therefore you are expected to provide locking in your application if necessary.

To use the JDBC-ODBC Bridge, you set up your own ODBC driver to work with the target database. You set up the JDBC-ODBC bridge only after you have successfully tested your ODBC driver. Check the following websites to obtain information about ODBC drivers for your DB2 Universal database or for other non-IBM databases. The ODBC driver will typically be in libodbc.a in /usr/lib. This library is imported during the time when the JDBC-ODBC Bridge library libJdbcOdbc.a is loaded at runtime.

The Bridge is expecting member libodbc.o in libodbc.a. Check the member name in your libodbc.a using the following command:

dump -H libodbc.a

If your libodbc.a has a different member name for libodbc.a, for example, odbc.so, perform the following operations after saving your original libodbc.a in a backup directory.

To extract and rename the member:

ar -p libodbc.a odbc.so > libodbc.o

To add the libodbc.o member to libodbc.a:

ar -v -r libodbc.a libodbc.o

Finally, to delete the odbc.so member from libodbc.a:

ar -v -d libodbc.a odbc.so

There is a README file and some example programs in the /usr/java131/demo/jdbcodbc directory. The examples can be optionally installed with the package Java131.samples.

JNDI

This Developer Kit provides a unified interface, the Java Naming and Directory Interface (JNDI), to the following naming and directory services:

• Lightweight Directory Access Protocol (LDAP)
• Corba Object Services (COS) Naming Service
• RMI Registry
• filesystem

JAAS

Also packaged with this release is the Java Authentication and Authorization Service (JAAS) standard extension which provides Principal-based authorization on authenticated identities.

For further details of this extension, see /usr/java131/docs/jaas/readme.jaas.ibm.html, after installing the Java131.ext.jaas fileset.

HPROF Performance Profiler and JVMPI

IBM extensions

The Java Virtual Machine Profiling Interface (JVMPI) has been extended to include profiling in the IBM JIT. These additional definitions are defined in jvmpi.h.

GetCurrentThreadCpuTime

The JVMPI interface function GetCurrentThreadCpuTime does not currently return accumulated thread CPU time. CPU times are returned as 0 from GetCurrentThreadCpuTime. This restriction applies to any profiling agent that makes use of thread CPU time, including the supplied HPROF profiling agent when invoked with -Xrunhprof:cpu=times. In this case, CPU time is displayed as NaNQ% in the HPROF output.

An alternative source of CPU data is to invoke HPROF with -Xrunhprof:cpu=samples, which provides estimates of thread CPU from a sampling technique. The JIT compiler must be disabled to provide data with this option.

The JVMPI interface function GetCurrentThreadCpuTime is supported on AIX 5.1. Resource collection must be enabled with AIX environment variable AIXTHREAD_ENRUSG set to ON, as follows:

export AIXTHREAD_ENRUSG=ON

You see the following message output 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.

Make sure that the resource collection is disabled after your profiling session because the overhead for tracking cpu time for individual threads will affect performance. Do not enable resource collection in a production environment. To disable the resource collection, do one of the following:

unset AIXTHREAD_ENRUSG

export AIXTHREAD_ENRUSG=OFF

The default for the Java environment is AIXTHREAD_ENRUSG=OFF. When resource collection is disabled, all profiling behavior will be as if you are running on AIX Level below 5.1.

When the resource collection is enabled, HPROF profiling agent invoked with -Xrunhprof:cpu=times provides meaningful data in the HPROF output.

Known restrictions

JVMPI_EVENT_INSTRUCTION_START

This event is not currently supported in the IBM AIX Developer Kit, Java Technology Edition, Version 1.3.1. It might be added in a future release.

Debugging environment

Traditionally, libraries intended for use with java_g must be named with _g; for example libmyapp_g.a. In the IBM AIX Developer Kit, if the JDK cannot locate a library named with _g, it will try to locate a library named without _g. This makes it possible to use the same library with both the regular and debug versions of the JDK. It means that a JNI application need not provide two versions of its libraries but can still work with java_g. This enhanced process for loading libraries has made it easier to use the debug version of the JDK (java_g) with JNI applications.

If the library named without _g is loaded, a warning message is printed to stderr. Only if this library cannot be found is UnsatisfiedLinkError thrown.

In the event of a core dump in your application when using the IBM AIX Developer Kit, Java 2 Technology Edition, Version 1.3.1, you get a javacore text file in addition to the core file. The javacore file has a filename of the format of javacore<process id>.<time>.txt. The <time> is the return value from the time subroutine at the time of the core dump, so each javacore file is not overwritten as for core file.

    /dev/tty0 -> COM1
    /dev/tty1 -> COM2
    ...
    /dev/tty9 -> COM10
    /dev/tty10 -> COM11
    ...