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

• This file contains all of the compiled .class files for the platform. Do not modify these classes; instead, create subclasses and override where you need to.

• Java Compiler (javac)
  
  Compiles programs written in the Java programming language into bytecodes (compiled Java code).
   
• Java Interpreter (java)
  
  Executes Java bytecodes. The Java Interpreter runs programs written in the Java programming language.
   
• Java Applet Viewer (appletviewer)
  
  Used for testing and running applets.
   
• Java Debugger (jdb)
  
  Helps debug your Java programs.
   
• Class File Disassembler (javap)
  
  Disassembles compiled files and prints a representation of the bytecodes.
   
• Java Documentation Generator (javadoc)
  
  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.
   
• C Header and Stub File Generator (javah)
  
  Attaches native methods to code written in the Java programming language.
   
• Java Archive Tool (jar)
  
  Generates signatures for Java Archive (JAR) files, and verifies the signatures of signed JAR files.
   
• JAR Signing and Verification Tool (jarsigner)
  
  Manages entities, including their keys, certificates, and the trust associated with them.
   
• Key and Certificate Management Tool (keytool)
  
  Manages a keystore (database) of private keys and their associated X.509 certificate chains authenticating 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.
   
• Native-To-ASCII Converter (native2ascii)
  
  Converts a native encoding file to an ASCII file that includes the \udddd Unicode notation.
   
• Java Remote Method Invocation (RMI) Stub Converter (rmic)
  
  Generates objects from the names of compiled classes that contain remote object implementations. Includes RMI-IIOP support.
   
• RMI activation system daemon (rmid)
  
  Starts the activation system daemon so that objects can be registered and activated in a JVM.
   
• IDL to Java Compiler (idlj)
  
  Compiles OMG Interface Definition Language files to Java code.
   
• 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.
   
• Serial Version Command (serialver)
  
  Returns the serialVersionUID for one or more classes in a form suitable for copying into an evolving class.
   
• Extcheck utility (extcheck)
  
  Detects version conflicts between a target jar file and currently installed extension jar files.
   
• Various C libraries and include files.

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: Java13_64.samples is an optional package with the following subdirectories installed in the /usr/java13_64/demo directory:

• applets
  - Demo programs for applets.
• bigdecimal
  - Example programs and a README file for enhanced BigDecimal class.
• jfc
  - Demo programs for Swing and Java2D.
• jni
  - Example programs and a README file 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 Java13_64.ext.security package is an optional package that installs the following subdirectories in /usr/java13_64/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/java13_64/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, be sure to preserve the path names when you extract the files from the archive.

The Just-In-Time (JIT) compiler

• 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

• 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

java -Djava.compiler=jitc <myapp>

Determining whether the JIT is enabled

java -version

JIT disabled

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

Setting the path

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/java13_64/bin, you can compile a file named myfile.java by typing the following at a command prompt:

   /usr/java13_64/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/java13_64/bin:/usr/java13_64/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

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

java -Xrunhprof:help

javac

javac -Jflag *.java

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 the 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

   export IBM_JAVA_OPTIONS="-Dmysysprop1=tcpip -Dmysysprop2=wait"

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

• 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 kilobytes or megabytes for command options; for example, -Xms1024K or -Xmx128M.

Setting the CLASSPATH

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), 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

    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

export AIXTHREAD_SCOPE=S

export AIXTHREAD_MUTEX_DEBUG=OFF

export AIXTHREAD_RWLOCK_DEBUG=OFF

export AIXTHREAD_COND_DEBUG=OFF

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/java13_64, 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

    java -version

Running applets with the Applet Viewer

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

    cd demo/applets/TicTacToe

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

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

Change in behavior of StringTokenizer class

opcode:attributeName:attributeValue\t

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://publibn.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>

ulimit -n 3000

chuser nofiles=3000 <user_id>

JNI compatibility

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, then 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.

Verify the compatibility of an executable program by:

dump -ov

If the modtype is not UR, you can use the LDR_CNTRL environment variable to make programs behave as though they were compiled with the -bM:UR binder option.  For example:

export LDR_CNTRL=USERREGS

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. If 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, controlled by the following environment setting:

export AIXTHREAD_SCOPE=S

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

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

AIX sets the default value of the AIXTHREAD_MUTEX_DEBUG, AIXTHREAD_RWLOCK_DEBUG and AIX_THREAD_COND_DEBUG environment variables to ON. A JNI program that creates and attaches to a JVM must set these environment variables OFF. See:

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

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

Fonts and locales

Java 1.3.1 uses the WorldType fonts shipped with AIX. These fonts are available on the AIX 5.1 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) is displayed if that font is not available.

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, as follows.

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. These fonts are installed automatically if you install the UTF8 locales.

Also, Java Version 1.3.1 no longer ships Devanagari fonts (Devamt.ttf and Devamtb.ttf) in the jre/lib/fonts directory. Instead, Java 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, with the exception of the UTF8 locales for Korean and Chinese. 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, 64-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

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:

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

Enhanced BigDecimal

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 http://www2.hursley.ibm.com/decimalj/.

JNDI

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

JAAS

For further details of this extension, see /usr/java13_64/docs/jaas/readme.jaas.ibm.html, after installing the Java13_64.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 is supported on AIX 5.1 or higher. Resource collection must be enabled with the AIX environment variable AIXTHREAD_ENRUSG set to ON, as follows:

export AIXTHREAD_ENRUSG=ON

You will get 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 affects performance. Resource collection should never be enabled in a production environment. To disable the resource collection, do one of the following:

unset AIXTHREAD_ENRUSG

export AIXTHREAD_ENRUSG=OFF

The default for the Java environment is AIXTHREAD_ENRUSG=OFF.

When the resource collection is enabled, the HPROF profiling agent, invoked with:

-Xrunhprof:cpu=times

Known restrictions

JVMPI_EVENT_INSTRUCTION_START

This event is not currently supported in the IBM AIX Developer Kit, Java 2 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, Java 2 Technology Edition, Version 1.3.1, 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.

You can determine the location of the javacore file as follows:

1) If the environment variable IBM_JAVACOREDIR refers to a writable directory, the javacore file is written to that directory.
2) Otherwise, if the current working directory is writable, the javacore file is written there.
3) Otherwise, if the environment variable TMPDIR refers to a writable directory, the javacore file is written to that directory.
4) Otherwise, the javacore file is written to the "/tmp" directory.

If the javacore cannot be opened for some reason, the information is written to standard error.

The javacore file provides information of the java program at the time of the core dump. To study JNI native code, you will still need to use the core file.

To debug java programs, you can use JPDA or JDB. For native JNI binary programs, you can still use dbx for debugging.

JPDA

For more information with respect to JPDA and its usage please refer to the following site: http://java.sun.com/j2se/1.3/docs/guide/jpda/

JDB

The new JDB uses the JPDA and allows the jdb example tool to attach to a listening Virtual Machine (VM) or to start a new debug session. It is invoked by the jdb command and can be used in the same way as oldjdb. Invoking jdb_g with the intention of creating a new debug session as follows:

jdb_g -launch <myapp>

attempts to launch a new VM using the java executable rather than the java_g executable. If the java executable is not found, jdb_g will fail.

The JDB can debug remote java applications, including java applications running on remote machines over a TCP/IP link. To debug a remote java program, the java program should start as follows:

java -Xdebug -Xnoagent -Xrunjdwp:transport=dt_socket,server=y,suspend=y -Djava.compiler=NONE <other args> <myapp> <myapp class args>

Specify the port number by the "address" sub-option.

The port on which the JPDA is listening is displayed. At the remote debugging machine, enter:

jdb -attach <machine name or ip address>:<port>

For more information with respect to JDB and its usage please refer to the following site: http://java.sun.com/j2se/1.3/docs/tooldocs/solaris/jdb.html

Note: Sun's documentation for using JDB assumes that the JVM to be debugged is a HotSpot JVM. However, IBM implementations of the JVM always run as a Classic JVM. So, when using IBM's JDB, always assume that the -classic option has been implicitly specified and follow the guidance for debugging a Classic JVM. This requires that the -Xnoagent option is specified unless the agent class is required, in which case specify the -Xbootclasspath option to locate it explicitly.

DBX

dbx /usr/java13_64/jre/bin/java

run <MyAppClass>

Java Communications API

The API is shipped in the Java13_64.ext.commapi fileset. With the fileset at 1.3.1.1 (or higher) fix level the API supports unlimited number of tty's, with ttyn mapped to COM(n+1) where n is 0 or a positive decimal integer:

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

For API details, see http://www.javasoft.com/products/javacomm/.

Java security tools

Java Cryptography Extension (JCE), version 1.2.1

JCE provides a framework and implementations for encryption, key generation and key agreement, and Message Authentication Code (MAC) algorithms. Support for encryption includes symmetric, asymmetric, block, and stream ciphers. The software also supports secure streams and sealed objects. For a general overview of JCE, visit http://java.sun.com/products/jce. IBM's JCE implementation provides more cryptographic algorithms than Sun's.

Note: After installing JCE, you must move the file ibmjcaprovider.jar from the /usr/java13_64/jre/lib/ext directory.  Otherwise, java will not work correctly.  Save the ibmjcaprovider.jar file in a safe place.  If you uninstall JCE, you must move this file back into the /usr/java13_64/jre/lib/ext directory.

Certificate Management Protocol (CMP)

CMP provides support to online interactions between Public Key Infrastructure (PKI) components. For example, a management protocol might be used between a Certificate Authority (CA) and a client system with which a key pair is associated, or between two CAs that issue cross-certificates for each other. For a full description of CMP, refer to RFC 2510 and 2511 for CRMF. These RFCs are available at http://www.ietf.org/rfc.html.

Public Key Cryptography Standards (PKCS)

As public-key cryptography begins to see wide application and acceptance, one thing is increasingly clear. If it is going to be as effective as the underlying technology allows it to be, there must be interoperability standards. Even though vendors might agree on the basic public-key techniques, compatibility between implementations is by no means guaranteed. Interoperability requires strict adherence to an agreed-upon standard format for transferred data. The IBM PKCS implementation supports the following RSA standards: PKCS #1, #3, #5, #6, #7, #8, #9, #10 and #12. Visit http://www.rsasecurity.com/rsalabs/pkcs for more information.

Secure Multi-Purpose Internet Mail Extensions (S/MIME)

S/MIME provides the Java classes needed to encode and decode S/MIME messages. This implementation provides a limited S/MIME parser geared to understanding and extracting PKCS #7 ContentInfo and PKCS #10 CertificationRequest objects from S/MIME messages. For more information on S/MIME, refer to RFC 2311 (S/MIME Version 2 Message Specification) at http://www.ietf.org/rfc.html

Java Secure Sockets Extension (JSSE), version 1.0.2

JSSE enables secure Internet communications. It implements a Java version of SSL (Secure Sockets Layer) and TLS (Transport Layer Security) protocols and includes functionality for data encryption, server authentication, message integrity, and optional client authentication. For more information, see http://java.sun.com/products/jsse.

To use the security providers mentioned, edit /usr/java13_64/jre/lib/security/java.security. An example of some of the providers that can be used in this file is as follows:

security.provider.1=sun.security.provider.sun

security.provider.2=com.ibm.crypto.provider.IBMJCE

security.provider.3=com.ibm.jsse.JSSEProvider

XML parser for Java

This release also includes XML parser for Java, version 4.0.3. The fileset, Java13_64.ext.xml4j, is optionally installable. For more information, see the files in /usr/java13_64/xml4j (after installing  the fileset).  For more information on XML, see http://www.ibm.com/developerworks/xml/.

Shipping Java applications

• Your own class, resource, and data files
• A runtime environment
• An installation procedure or program

If you want to ship the Java Runtime Environment with your applications, go to this website and accept the JRE license agreement. If you agree with the terms and conditions, you will be able to download the JRE from:

http://www.ibm.com/developerworks/java/jdk/aix/index.html

The READMEs supplied with this Developer Kit and the Runtime Environment have been tested using screen readers. You can use a screen reader such as the Home Page Reader or the JAWS screen reader with these READMEs.

To change the font sizes in the READMEs, use the function supplied with your browser, usually found under the View menu option.

The Java console does not respond to the tab key for navigation. Use the control-tab key pair to navigate the console.

Policy Tool does not meet accessibility requirements. Policy Tool is used to edit a JVM's security policy files. Because these files are in regular text format, you may edit them with any standard text editor (Notepad on Windows or vi on Unix systems, for example). Information on the policy file location and contents, including required format, can be found at: http://java.sun.com/j2se/1.3/docs/guide/security/PolicyFiles.html.

Information about the permissions granted in a policy file can be found at: http://java.sun.com/j2se/1.3/docs/guide/security/permissions.html

Notices

This information was developed for products and services offered in the U.S.A.

IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the users responsibility to evaluate and verify the operation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to:

IBM Director of Licensing
IBM Corporation
North Castle Drive, Armonk
NY 10504-1758 U.S.A.

IBM World Trade Asia Corporation Licensing
2-31 Roppongi 3-chome, Minato-ku
Tokyo 106, Japan

INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.

This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the information. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this information at any time without notice.

Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk.

IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you.

Licensees of this program who wish to have information about it for the purpose of enabling (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact:

JTCMAIL@uk.ibm.com
[IBM Java Technology Center (JTC) contact]

The licensed program described in this document and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement or any equivalent agreement between us.

Any performance data contained herein was determined in a controlled environment. Therefore, the results obtained in other operating environments may vary significantly. Some measurements may have been made on development-level systems and there is no guarantee that these measurements will be the same on generally available systems. Furthermore, some measurement may have been estimated through extrapolation. Actual results may vary. Users of this document should verify the applicable data for their specific environment.

Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products. 

Trademarks

IBM and AIX are trademarks of International Business Machines Corporation in the U.S., or other countries, or both.

Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States, other countries, or both. The Java technology is owned and exclusively licensed by Sun Microsystems, Inc.

Other company, product, and service names may be trademarks or service marks of others.

This product is also based in part on the work of the FreeType Project. For more information about FreeType see http://www.freetype.org.