Before using this information and the product it supports, read the information in Notices.
This edition of the user guide applies to the IBM SDK and Runtime Environment for Linux on multiple platforms.
The platforms this guide applies to are:
and all subsequent releases and modifications until otherwise indicated in new editions.
© Copyright Sun Microsystems, Inc. 1997, 2007, 901 San Antonio Rd., Palo Alto, CA 94303 USA. All rights reserved.
This user guide provides general information about the IBM® SDK and Runtime Environment for Linux® platforms, Java™ Technology Edition, Version 6 and specific information about any differences in the IBM implementation compared with the Sun implementation.
Read this user guide in conjunction with the more extensive documentation on the Sun Web site: http://java.sun.com.
For the list of distributions against which the SDK and Runtime Environment for Linux have been tested, see: http://www.ibm.com/developerworks/java/jdk/linux/tested.html.
(Intel® 32-bit platforms only) These Virtualized Environments are supported:
The Diagnostics Guide provides more detailed information about the IBM Virtual Machine for Java.
This user guide is part of a release and is applicable only to that particular release. Make sure that you have the user guide appropriate to the release you are using.
The terms "Runtime Environment" and "Java Virtual Machine" are used interchangeably throughout this user guide.
|Technical changes made for this version |of the user guide, other than minor or obvious ones, are indicated |by blue chevrons when viewing in an Information Center, in red with |vertical bars to the left of the changes when viewing in HTML or in |a color-printed copy, or by vertical bars to the left of the changes |when viewing as a PDF.
The Program Code is not designed or intended for use in real-time applications such as (but not limited to) the online control of aircraft, air traffic, aircraft navigation, or aircraft communications; or in the design, construction, operation, or maintenance of any nuclear facility.
The IBM SDK is a development environment for writing and running applets and applications that conform to the Java 6 Core Application Program Interface (API).
The SDK includes the Runtime Environment for Linux, which enables you only to run Java applications. If you have installed the SDK, the Runtime Environment is included.
The Runtime Environment contains the Java Virtual Machine and supporting files including non-debuggable .so files and class files. The Runtime Environment contains only a subset of the classes that are found in the SDK and allows you to support a Java program at runtime but does not provide compilation of Java programs. The Runtime Environment for Linux does not include any of the development tools, for example appletviewer or the Java compiler (javac), or classes that are only for development systems.
In addition, for IA32, PPC32/PPC64, and AMD64/EM64T platforms, the Java Communications application programming interface (API) package is provided for use with the Runtime Environment for Linux. You can find information about it in Java Communications API (JavaComm).
The license_xx.html file contains the license agreement for the Runtime Environment for Linux software, where xx is an abbreviation for the language. To view or print the license agreement, open the file in a Web browser.
Throughout this user guide the default installation directory of the SDK is referred to as /opt/ibm/java-<arch>-60/, where <arch> is the architecture of your platform.
The default installation directories for the various architectures are listed here; replace the directory for the architecture you are using when you see /opt/ibm/java-<arch>-60/:
Korn shell commands are used in examples throughout this user guide.
In general, any applet or application that ran with a previous version of the SDK should run correctly with the IBM SDK for Linux, v6. Classes compiled with this release are not guaranteed to work on previous releases.
For information about compatibility issues between releases, see the Sun web site at:
http://java.sun.com/javase/6/webnotes/compatibility.html
http://java.sun.com/j2se/5.0/compatibility.html
http://java.sun.com/j2se/1.4/compatibility.html
http://java.sun.com/j2se/1.3/compatibility.html
If you are using the SDK as part of another product (for example, IBM WebSphere® Application Server), and you upgrade from a previous level of the SDK, perhaps v5.0, serialized classes might not be compatible. However, classes are compatible between service refreshes.
From Version 5.0, the IBM Runtime Environment for Linux contains new versions of the IBM Virtual Machine for Java and the Just-In-Time (JIT) compiler.
If you are migrating from an older IBM Runtime Environment, note that:
The System z 31-bit and 64-bit SDKs and Runtime Environments run on System z9® and zSeries® hardware.
The SDKs and Runtime Environments run on the following servers or equivalents:
The SDK contains several development tools and a Java Runtime Environment (JRE). This section describes the contents of the SDK tools and the Runtime Environment.
Applications written entirely in Java must have no dependencies on the IBM SDK's directory structure (or files in those directories). Any dependency on the SDK's directory structure (or the files in those directories) might result in application portability problems.
The user guides, Javadoc, and the accompanying license, copyright files, javadoc, and demo directory are the only documentation included in this SDK for Linux. You can view Sun's software documentation by visiting the Sun Web site, or you can download Sun's software documentation package from the Sun Web site: http://java.sun.com.
A list of classes, tools, and other files that you can use with the standard Runtime Environment.
A list of tools and reference information that is included with the standard SDK.
The License file, /opt/ibm/java-<arch>-60/docs/content/<locale>/LA_<locale>, contains the license agreement for the SDK for Linux software (where <locale> is the name of your locale, for example en). To view or print the license agreement, open the file in a Web browser.
You can install the IBM Java SDK and Runtime Environment from either an RPM or a .tgz file. Unless you want to allow all the users on the machine to access this Java installation, use the .tgz installation method. If you do not have root access, use the .tgz file.
If you install using an RPM file, the Java files are installed in /opt/ibm/java-<arch>-60/. The examples in this guide assume that you have installed Java in this directory.
If you are upgrading the SDK from a previous release, back up all the configuration files and security policy files before you start the upgrade.
After the upgrade, you might have to restore or reconfigure these files because they might have been overwritten during the upgrade process. Check the syntax of the new files before restoring the original files because the format or options for the files might have changed.
The SDK depends on shared libraries that are not installed by default for Red Hat Enterprise Linux (RHEL).
In RHEL 4, the RPMs that contain these libraries are:
To include these libraries during RHEL 4 installation:
The SDK depends on shared libraries that are not installed by default for Red Hat Enterprise Linux (RHEL).
In RHEL 5, these RPMs contain the shared libraries:
To include these libraries during RHEL 5 installation:
You can run the IBM SDK for Java on Red Hat Enterprise Linux Version 5 with SELinux enabled on all platforms except PPC without any restrictions. For PPC platforms, Java must be installed in the default directory or you must enable it manually.
To enable Java manually on PPC platforms, enter this command:
chcon -R -t texrel_shlib_t <path_of_sdk>
Where <path_of_sdk> is the path where Java is installed.
For more information about SELinux, see Introduction to SELinux in the Red Hat documentation.
To run the SDK, you must install the correct versions of all libraries required by the SDK, either 32- or 64-bit.
In RHEL4, the 64-bit versions of the packages are available in the Compatibility Arch Support package group.
You can use the RPM tool to check which versions of the packages you have installed by adding the option --queryformat "%{NAME}.%{ARCH}\n" to your RPM command. For example:
/home/username : rpm --queryformat "%{NAME}.%{ARCH}\n" -q libstdc++
libstdc++.x86_64
libstdc++.i386
A procedure for installing from an RPM file.
To upgrade your JVM using the rpm tool, you must uninstall any previous version. To install two versions of the JVM in different locations, use the rpm --force option to ignore the version conflict or install the JVM from the .tgz file.
rpm -ivh ibm-java-<arch>-sdk-6.0-3.0.<arch>.rpmor
rpm -ivh ibm-java-<arch>-jre-6.0-3.0.<arch>.rpm
Where <arch> represents your architecture: i386, x86_64, ppc, ppc64, s390, or s390x.
A procedure for installing from a .tgz file.
tar -zxvf ibm-java-sdk-6.0-3.0-linux-<arch>.tgzor
tar -zxvf ibm-java-jre-6.0-3.0-linux-<arch>.tgz
Where <arch> represents your architecture: i386, x86_64, ppc, ppc64, s390, or s390x.
chcon -R -t texrel_shlib_t /opt/ibm/java-<arch>-60/jre chcon -R -t texrel_shlib_t /opt/ibm/java-<arch>-60/bin chcon -R -t texrel_shlib_t /opt/ibm/java-<arch>-60/lib
The IBM SDK for Linux, v6 is also available in a JPackage compatible format.
To simplify managing the SDK, the various components of it are now available as separate RPMs: the base Java Runtime Environment, Development Kit, Plug-in, JDBC, Demo, Sound, Source, and Fonts. "jpackage-utils" RPM (downloadable from http://jpackage.org), which allows managing multiple Java RPMs on a system, is a prerequisite for the IBM SDKs. For more information about the JPackage specification, see http://jpackage.org.
If you install the SDK using JPackage, it will not be installed in the default location. See the "Directory Structure" section of the JPackage Java™ infrastructure design and packaging policy for details about the default JPackage installation location: http://www.jpackage.org/cgi-bin/viewvc.cgi/src/jpackage-utils/doc/jpackage-1.5-policy.xhtml?root=jpackage&view=co
jpackage-utils version 1.5.38 or above is required to install the IBM SDK for Linux, v6.
JPackage is not supported on SLES9 or SLES10 platforms.
Inconsistencies in the font encodings on Red Hat Advanced Server
If you alter the PATH environment variable, you will override any existing Java launchers in your path.
The PATH environment variable enables Linux to find programs and utilities, such as javac, java, and javadoc, from any current directory. To display the current value of your PATH, type the following at a command prompt:
echo $PATH
To add the Java launchers to your path:
export PATH=/opt/ibm/java-<arch>-60/bin:/opt/ibm/java-<arch>-60/jre/bin:$PATH
After setting the path, you can run a tool by typing its name at a command prompt from any directory. For example, to compile the file Myfile.Java, at a command prompt, type:
javac Myfile.Java
The class path tells the SDK tools, such as java, javac, and javadoc, where to find the Java class libraries.
You need to set the class path explicitly only if:
To display the current value of your CLASSPATH environment variable, type the following command at a shell prompt:
echo $CLASSPATH
If you develop and run applications that use different runtime environments, including other versions that you have installed separately, you must set the CLASSPATH and PATH explicitly for each application. If you run multiple applications simultaneously and use different runtime environments, each application must run in its own shell prompt.
The process that you use to remove the SDK and Runtime Environment for Linux depends on what type of installation you used.
See Uninstalling the Red Hat Package Manager (RPM) package or Uninstalling the compressed Tape Archive (TAR) package for instructions.
A procedure for uninstalling the Red Hat Package Manager (RPM) package.
To uninstall the SDK or Runtime Environment for Linux if you installed the installable RPM package:
You will see a list of any IBM Java packages that you have installed; for example:
ibm-java-<arch>-jre-6.0-3.0.<arch> ibm-java-<arch>-sdk-6.0-3.0.<arch>
This output tells you which packages you can uninstall, using the rpm -e command; for example:
rpm -e ibm-java-<arch>-jre-6.0-3.0.<arch> rpm -e ibm-java-<arch>-sdk-6.0-3.0.<arch>
Alternatively, you can use a graphical tool such as kpackage or yast2
A list of the steps to remove the IBM SDK for Linux, v6 that was extracted from the compressed package.
Java applications can be started using the java launcher or through JNI. Settings are passed to a Java application using command-line arguments, environment variables, and properties files.
An overview of the java and javaw commands.
The java and javaw tools launch a Java application by starting a Java Runtime Environment and loading a specified class.
The javaw command is identical to java, except that javaw has no associated console window. Use javaw when you do not want a command prompt window to be displayed. The javaw launcher displays a dialog box with error information if a launch fails.
The JVM searches for the initial class (and other classes that are used) in three sets of locations: the bootstrap class path, the installed extensions, and the user class path. The arguments that you specify after the class name or jar file name are passed to the main function.
The java and javaw commands have the following syntax:
java [ options ] <class> [ arguments ... ] java [ options ] -jar <file.jar> [ arguments ... ] javaw [ options ] <class> [ arguments ... ] javaw [ options ] -jar <file.jar> [ arguments ... ]
You obtain The IBM build and version number for your Java installation using the -version option. You can also obtain version information for all jar files on the class path by using the -Xjarversion option.
java -versionYou will see information similar to:
java version "1.6.0-internal" Java(TM) SE Runtime Environment (build 20070329_01) IBM J9 VM (build 2.4, J2RE 1.6.0 IBM J9 2.4 Linux x86-32 jvmxi3260-20070326_12091 (JIT enabled) J9VM - 20070326_12091_lHdSMR JIT - dev_20070326_1800 GC - 20070319_AA)Exact build dates and versions will change.
You can also list the version information for all available jar files on the class path, the boot class path, and in the extensions directory. Type the following command:
java -Xjarversion
You will see information similar to:
... /opt/ibm/java-<arch>-60/jre/lib/ext/ibmpkcs11impl.jar VERSION: 1.0 build_20070125 /opt/ibm/java-<arch>-60/jre/lib/ext/dtfjview.jar /opt/ibm/java-<arch>-60/jre/lib/ext/xmlencfw.jar VERSION: 1.00, 20061011 LEVEL: -20061011 ...
The information available varies for each jar file and is taken from the Implementation-Version and Build-Level properties in the manifest of the jar file.
You can specify Java options and system properties on the command line, by using an options file, or by using an environment variable.
These methods of specifying Java options are listed in order of precedence. Rightmost options on the command line have precedence over leftmost options; for example, if you specify:
java -Xint -Xjit myClass
The -Xjit option takes precedence.
java -Dmysysprop1=tcpip -Dmysysprop2=wait -Xdisablejavadump MyJavaClass
export IBM_JAVA_OPTIONS="-Dmysysprop1=tcpip -Dmysysprop2=wait -Xdisablejavadump"
The definitions for the standard options.
See Appendix A. Nonstandard options for information about nonstandard (-X) options.
The java and javaw launchers accept arguments and class names containing any character that is in the character set of the current locale. You can also specify any Unicode character in the class name and arguments by using Java escape sequences.
To do this, use the -Xargencoding command-line option.
For example, to specify a class called HelloWorld using Unicode encoding for both capital letters, use this command:
java -Xargencoding '\u0048ello\u0057orld'
The java and javaw commands provide translated messages. These messages differ based on the locale in which Java is running. The detailed error descriptions and other debug information that is returned by java is in English.
The IBM Just-In-Time (JIT) compiler dynamically generates machine code for frequently used bytecode sequences in Java applications and applets during their execution. The JIT v6 compiler delivers new optimizations as a result of compiler research, improves optimizations implemented in previous versions of the JIT, and provides better hardware exploitation.
Both the IBM SDK and Runtime Environment include the JIT, which is enabled by default in user applications and SDK tools. Normally, you do not invoke the JIT explicitly; the compilation of Java bytecode to machine code occurs transparently. You can disable the JIT to help isolate a problem. If a problem occurs when executing a Java application or an applet, you can disable the JIT to help isolate the problem. Disabling the JIT is a temporary measure only; the JIT is required to optimize performance.
For more information about the JIT, see the Diagnostics Guide.
The JIT can be disabled in a number of different ways. Both command-line options override the JAVA_COMPILER environment variable.
Turning off the JIT is a temporary measure that can help isolate problems when debugging Java applications.
export JAVA_COMPILER=NONE
java -Djava.compiler=NONE <class>
java -Xint <class>
The JIT is enabled by default. You can explicitly enable the JIT in a number of different ways. Both command-line options override the JAVA_COMPILER environment variable.
export JAVA_COMPILER=jitcIf the JAVA_COMPILER environment variable is an empty string, the JIT remains disabled. To disable the environment variable, at the shell prompt, enter:
unset JAVA_COMPILER
java -Djava.compiler=jitc <class>
java -Xjit <class>
You can determine the status of the JIT using the -version option.
Run the java launcher with the -version option. Enter the following at a shell prompt:
java -version
If the
JIT is not in use, a message is displayed that includes the following:
(JIT disabled)
If
the JIT is in use, a message is displayed that includes the following:
(JIT enabled)
For more information about the JIT, see the Diagnostics Guide.
The Garbage Collector manages the memory used by Java and by applications running within the JVM.
When the Garbage Collector receives a request for storage, unused memory in the heap is set aside in a process called "allocation". The Garbage Collector also checks for areas of memory that are no longer referenced, and releases them for reuse. This is known as "collection".
The collection phase can be triggered by a memory allocation fault, which occurs when no space is left for a storage request, or by an explicit System.gc() call.
Garbage collection can significantly affect application performance, so the IBM virtual machine provides various methods of optimizing the way garbage collection is carried out, potentially reducing the effect on your application.
For more detailed information about garbage collection, see the Diagnostics Guide.
The -Xgcpolicy options control the behavior of the Garbage Collector. They make trade-offs between throughput of the application and overall system, and the pause times that are caused by garbage collection.
The format of the option and its values is:
Many Java application workloads depend on the Java heap size. The IBM SDK for Java can use compressed references on 64-bit platforms to decrease the size of Java objects and make more effective use of the available space.
The IBM SDK for Java 64-bit stores object references as 64-bit values. When the same application is run on a 32-bit JVM and a 64-bit JVM, the 64-bit JVM requires a larger heap because the references in the Java objects are larger. The -Xcompressedrefs command-line option causes object references to be stored as 32-bit values and maintains the 32-bit object size.
Use -Xcompressedrefs in any of these situations:
-Xcompressedrefs is not recommended for non-x86-based hardware running applications that have enough space in the Java heap provided by the 32-bit JVM.
See the Diagnostics Guide for more detailed information about compressed references.
When an application's attempt to create an object cannot be satisfied immediately from the available space in the heap, the Garbage Collector is responsible for identifying unreferenced objects (garbage), deleting them, and returning the heap to a state in which the immediate and subsequent allocation requests can be satisfied quickly.
Such garbage collection cycles introduce occasional unexpected pauses in the execution of application code. Because applications grow in size and complexity, and heaps become correspondingly larger, this garbage collection pause time tends to grow in size and significance.
The default garbage collection value, -Xgcpolicy:optthruput, delivers very high throughput to applications, but at the cost of these occasional pauses, which can vary from a few milliseconds to many seconds, depending on the size of the heap and the quantity of garbage.
The JVM uses two techniques to reduce pause times: concurrent garbage collection and generational garbage collection.
The -Xgcpolicy:optavgpause command-line option requests the use of concurrent garbage collection to reduce significantly the time that is spent in garbage collection pauses. Concurrent GC reduces the pause time by performing some garbage collection activities concurrently with normal program execution to minimize the disruption caused by the collection of the heap. The -Xgcpolicy:optavgpause option also limits the effect of increasing the heap size on the length of the garbage collection pause. The -Xgcpolicy:optavgpause option is most useful for configurations that have large heaps. With the reduced pause time, you might experience some reduction of throughput to your applications.
During concurrent garbage collection, a significant amount of time is wasted identifying relatively long-lasting objects that cannot then be collected. If garbage collection concentrates on only the objects that are most likely to be recyclable, you can further reduce pause times for some applications. Generational GC reduces pause times by dividing the heap into two generations: the "new" and the "tenure" areas. Objects are placed in one of these areas depending on their age. The new area is the smaller of the two and contains new objects; the tenure is larger and contains older objects. Objects are first allocated to the new area; if they have active references for long enough, they are promoted to the tenure area.
Generational GC depends on most objects not lasting long. Generational GC reduces pause times by concentrating the effort to reclaim storage on the new area because it has the most recyclable space. Rather than occasional but lengthy pause times to collect the entire heap, the new area is collected more frequently and, if the new area is small enough, pause times are comparatively short. However, generational GC has the drawback that, over time, the tenure area might become full. To minimize the pause time when this situation occurs, use a combination of concurrent GC and generational GC. The -Xgcpolicy:gencon option requests the combined use of concurrent and generational GC to help minimize the time that is spent in any garbage collection pause.
If the Java heap becomes nearly full, and very little garbage can be reclaimed, requests for new objects might not be satisfied quickly because no space is immediately available.
If the heap is operated at near-full capacity, application performance might suffer regardless of which garbage collection options are used; and, if requests for more heap space continue to be made, the application might receive an OutOfMemoryError, which results in JVM termination if the exception is not caught and handled. At this point, the JVM produces a Javadump file for use during diagnostics. In these conditions, you are recommended either to increase the heap size by using the -Xmx option or to reduce the number of objects in use.
For more information, see the Diagnostics Guide.
The IBM SDK and Runtime Environment set the Euro as the default currency for those countries in the European Monetary Union (EMU) for dates on or after 1 January, 2002. From 1 January 2008, Cyprus and Malta also have the Euro as the default currency.
To use the old national currency, specify -Duser.variant=PREEURO on the Java command line.
If you are running the UK, Danish, or Swedish locales and want to use the Euro, specify -Duser.variant=EURO on the Java command line.
The Linux fallback font configuration files (fontconfig.RedHat.bfc and fontconfig.SuSE.bfc) are installed to provide font settings suitable for new enterprise Linux distributions.
These files are for your convenience only. Their presence does not imply that the new Linux distribution is a supported platform for the IBM SDK and Runtime Environment for Linux platforms, Java Technology Edition, Version 6.
From Version 6, the Indian and Thai input methods are not available by default. You must manually include the input method jar files in your Java extensions path to use the Indian and Thai input methods.
In Version 5.0, the input method jar files were included in the jre/lib/ext directory and were automatically loaded by the JVM. In Version 6, the input method jar files are included in the jre/lib/im directory and you must manually add them to the Java extensions path to enable Indian and Thai input methods.
java -Djava.ext.dirs=/opt/ibm/java-<arch>-60/jre/lib/ext:/opt/ibm/java-<arch>-60/jre/lib/im <class>
If you installed the SDK or Runtime Environment in a different directory, replace /opt/ibm/java-<arch>-60/ with the directory in which you installed the SDK or Runtime Environment.
The SDK for Linux contains many tools and libraries required for Java software development.
See Contents of the SDK for details of the tools available.
The IBM SDK contains the XML4J and XL XP-J parsers, the XL TXE-J 1.0 XSLT compiler, and the XSLT4J XSLT interpreter. These tools allow you to parse, validate, transform, and serialize XML documents independently from any given XML processing implementation.
Use factory finders to locate implementations of the abstract factory classes, as described in Selecting an XML processor. By using factory finders, you can select a different XML library without changing your Java code.
The IBM SDK for Java contains the following XML libraries:
XML4J is a validating parser providing support for the following standards:
XML4J 4.5 is based on Apache Xerces-J 2.9.0. See http://xerces.apache.org/xerces2-j/ for more information.
XL XP-J 1.1 is a high-performance non-validating parser that provides support for StAX 1.0 (JSR 173). StAX is a bidirectional API for pull-parsing and streaming serialization of XML 1.0 and XML 1.1 documents. See the XL XP-J reference information section for more details about what is supported by XL XP-J 1.1.
For Version 5.0, the IBM SDK for Java included the XSLT4J compiler and interpreter. The XSLT4J interpreter was used by default.
For Version 6, the IBM SDK for Java includes XL TXE-J. XL TXE-J includes the XSLT4J 2.7.8 interpreter and a new XSLT compiler. The new compiler is used by default. The XSLT4J compiler is no longer included with the IBM SDK for Java. See Migrating to the XL-TXE-J for information about migrating to XL TXE-J.
XL TXE-J provides support for the following standards:
XML processor selection is performed using service providers. When using a factory finder, Java looks in the following places, in this order, to see which service provider to use:
The following service providers control the XML processing libraries used by Java:
The XL TXE-J compiler has replaced the XSLT4J interpreter as the default XSLT processor. Follow these steps to prepare your application for the new library.
The XL TXE-J compiler is faster than the XSLT4J interpreter when you are applying the same transformation more than once. If you perform each individual transformation only once, the XL TXE-J compiler is slower than the XSLT4J interpreter because of the compilation and optimization overhead.
To continue using the XSLT4J interpreter as your XSLT processor, set the javax.xml.transform.TransformerFactory service provider to org.apache.xalan.processor.TransformerFactoryImpl.
To migrate to the XL-TXE-J compiler, follow the instructions in this task.
Some generated functions exceeded the JVM method size limit and were automatically split into smaller functions. You might get better performance by manually splitting very large templates into smaller templates, by using the 'splitlimit' option to the Process or Compile command, or by setting the 'http://www.ibm.com/xmlns/prod/xltxe-j/split-limit' transformer factory attribute.
You can use the compiled classes, but you might get better performance by controlling the split limit manually.com.ibm.xtq.bcel.generic.ClassGenException: Branch target offset too large for short
orbytecode array size > 65535 at offset=#####
Try setting the split limit manually, or using a lower split limit.| XSL4J compiler attribute | XL TXE-J compiler attribute |
|---|---|
| translet-name | http://www.ibm.com/xmlns/prod/xltxe-j/translet-name |
| destination-directory | http://www.ibm.com/xmlns/prod/xltxe-j/destination-directory |
| package-name | http://www.ibm.com/xmlns/prod/xltxe-j/package-name |
| jar-name | http://www.ibm.com/xmlns/prod/xltxe-j/jar-name |
| generate-translet | http://www.ibm.com/xmlns/prod/xltxe-j/generate-translet |
| auto-translet | http://www.ibm.com/xmlns/prod/xltxe-j/auto-translet |
| use-classpath | http://www.ibm.com/xmlns/prod/xltxe-j/use-classpath |
| debug | http://www.ibm.com/xmlns/prod/xltxe-j/debug |
| indent-number | http://www.ibm.com/xmlns/prod/xltxe-j/indent-number |
| enable-inlining | Obsolete in new compiler |
The XL XP-J and XL TXE-J XML libraries are new for Version 6 of the SDK. This reference information describes the features supported by these libraries.
XL XP-J 1.1 is a high-performance non-validating parser that provides support for StAX 1.0 (JSR 173). StAX is a bidirectional API for pull-parsing and streaming serialization of XML 1.0 and XML 1.1 documents.
The following optional StAX features are not supported by XL XP-J:
The javax.xml.stream.XMLInputFactory implementation supports the following properties, as described in the XMLInputFactory Javadoc: http://java.sun.com/javase/6/docs/api/javax/xml/stream/XMLInputFactory.html.
| Property name | Supported? |
|---|---|
| javax.xml.stream.isValidating | No. The XL XP-J scanner does not support validation. |
| javax.xml.stream.isNamespaceAware | Yes, supports true and false. For XMLStreamReaders created from DOMSources, namespace processing depends on the methods that were used to create the DOM tree, and this value has no effect. |
| javax.xml.stream.isCoalescing | Yes |
| javax.xml.stream.isReplacingEntityReferences | Yes. For XMLStreamReaders created from DOMSources, if entities have already been replaced in the DOM tree, setting this parameter has no effect. |
| javax.xml.stream.isSupportingExternalEntities | Yes |
| javax.xml.stream.supportDTD |
True is always supported. Setting the value to false works only if the com.ibm.xml.xlxp.support.dtd.compat.mode system property is also set to false. When both properties are set to false, parsers created by the factory throw an XMLStreamException when they encounter an entity reference that requires expansion. This setting is useful for protecting against Denial of Service (DoS) attacks involving entities declared in the DTD. Setting the value to false does not work before Service Refresh 2. |
| javax.xml.stream.reporter | Yes |
| javax.xml.stream.resolver | Yes |
XL XP-J also supports the optional method createXMLStreamReader(javax.xml.transform.Source), which allows StAX readers to be created from DOM and SAX sources.
XL XP-J also supports the javax.xml.stream.isSupportingLocationCoordinates property. If you set this property to true, XMLStreamReaders created by the factory return accurate line, column, and character information using Location objects. If you set this property to false, line, column, and character information is not available. By default, this property is set to false for performance reasons.
The javax.xml.stream.XMLStreamReader implementation supports the following properties, as described in the XMLStreamReader Javadoc: http://java.sun.com/javase/6/docs/api/javax/xml/stream/XMLStreamReader.html.
| Property name | Supported? |
|---|---|
| javax.xml.stream.entities | Yes |
| javax.xml.stream.notations | Yes |
XL XP-J also supports the javax.xml.stream.isInterning property. This property returns a boolean value indicating whether or not XML names and namespace URIs returned by the API calls have been interned by the parser. This property is read-only.
The javax.xml.stream.XMLOutputFactory implementation supports the following properties, as described in the XMLOutputFactory Javadoc: http://java.sun.com/javase/6/docs/api/javax/xml/stream/XMLOutputFactory.html.
| Property name | Supported? |
|---|---|
| javax.xml.stream.isRepairingNamespaces | Yes |
XL XP-J also supports the javax.xml.stream.XMLOutputFactory.recycleWritersOnEndDocument property. If you set this property to true, XMLStreamWriters created by this factory are recycled when writeEndDocument() is called. After recycling, some XMLStreamWriter methods, such as getNamespaceContext(), must not be called. By default, XMLStreamWriters are recycled when close() is called. You must call the XMLStreamWriter.close() method when you have finished with an XMLStreamWriter, even if this property is set to true.
The javax.xml.stream.XMLStreamWriter implementation supports the following properties, as described in the XMLStreamWriter Javadoc: http://java.sun.com/javase/6/docs/api/javax/xml/stream/XMLStreamWriter.html.
| Property name | Supported? |
|---|---|
| javax.xml.stream.isRepairingNamespaces | Yes |
Properties on XMLStreamWriter objects are read-only.
XL XP-J also supports the javax.xml.stream.XMLStreamWriter.isSetPrefixBeforeStartElement property. This property returns a Boolean indicating whether calls to setPrefix() and setDefaultNamespace() should occur before calls to writeStartElement() or writeEmptyElement() to put a namespace prefix in scope for that element. XL XP-J always returns false; calls to setPrefix() and setDefaultNamespace() should occur after writeStartElement() or writeEmptyElement().
XL TXE-J is an XSLT library containing the XSLT4J 2.7.8 interpreter and a XSLT compiler.
| Feature | XSLT4J interpreter (included) | XSLT4J compiler (not included) | XL TXE-J compiler (included) |
|---|---|---|---|
| http://javax.xml.transform.stream.StreamSource/feature feature | Yes | Yes | Yes |
| http://javax.xml.transform.stream.StreamResult/feature feature | Yes | Yes | Yes |
| http://javax.xml.transform.dom.DOMSource/feature feature | Yes | Yes | Yes |
| http://javax.xml.transform.dom.DOMResult/feature feature | Yes | Yes | Yes |
| http://javax.xml.transform.sax.SAXSource/feature feature | Yes | Yes | Yes |
| http://javax.xml.transform.sax.SAXResult/feature feature | Yes | Yes | Yes |
| http://javax.xml.transform.stax.StAXSource/feature feature | Yes | No | Yes |
| http://javax.xml.transform.stax.StAXResult/feature feature | Yes | No | Yes |
| http://javax.xml.transform.sax.SAXTransformerFactory/feature feature | Yes | Yes | Yes |
| http://javax.xml.transform.sax.SAXTransformerFactory/feature/xmlfilter feature | Yes | Yes | Yes |
| http://javax.xml.XMLConstants/feature/secure-processing feature | Yes | Yes | Yes |
| http://xml.apache.org/xalan/features/incremental attribute | Yes | No | No |
| http://xml.apache.org/xalan/features/optimize attribute | Yes | No | No |
| http://xml.apache.org/xalan/properties/source-location attribute | Yes | No | No |
| translet-name attribute | N/A | Yes | Yes (with new name) |
| destination-directory attribute | N/A | Yes | Yes (with new name) |
| package-name attribute | N/A | Yes | Yes (with new name) |
| jar-name attribute | N/A | Yes | Yes (with new name) |
| generate-translet attribute | N/A | Yes | Yes (with new name) |
| auto-translet attribute | N/A | Yes | Yes (with new name) |
| use-classpath attribute | N/A | Yes | Yes (with new name) |
| enable-inlining attribute | No | Yes | No (obsolete in TL TXE-J) |
| indent-number attribute | No | Yes | Yes (with new name) |
| debug attribute | No | Yes | Yes (with new name) |
| Java extensions | Yes | Yes (abbreviated syntax only, xalan:component/xalan:script constructs not supported) | |
| JavaScript extensions | Yes | No | No |
| Extension elements | Yes | No | No |
| EXSLT extension functions | Yes | Yes (excluding dynamic) | Yes (excluding dynamic) |
| redirect extension | Yes | Yes (excluding redirect:open and redirect:close) | Yes |
| output extension | No | Yes | Yes |
| nodeset extension | Yes | Yes | Yes |
| NodeInfo extension functions | Yes | No | No |
| SQL library extension | Yes | No | No |
| pipeDocument extension | Yes | No | No |
| evaluate extension | Yes | No | No |
| tokenize extension | Yes | No | No |
| XML 1.1 | Yes | Yes | Yes |
If you are using an older version of Xerces (before 2.0) or Xalan (before 2.3) in the endorsed override, you might get a NullPointerException when you start your application. This exception occurs because these older versions do not handle the jaxp.properties file correctly.
To avoid this situation, use one of the following workarounds:
export IBM_JAVA_OPTIONS=-Djavax.xml.parsers.SAXParserFactory= org.apache.xerces.jaxp.SAXParserFactoryImplor
export IBM_JAVA_OPTIONS=-Djavax.xml.parsers.DocumentBuilderFactory= org.apache.xerces.jaxp.DocumentBuilderFactoryImplor
export IBM_JAVA_OPTIONS=-Djavax.xml.transform.TransformerFactory= org.apache.xalan.processor.TransformerFactoryImpl
To debug Java programs, you can use the Java Debugger (JDB) application or other debuggers that communicate by using the Java Platform Debugger Architecture (JPDA) that is provided by the SDK for Linux.
More information about problem diagnosis using Java can be found in the Diagnostics Guide.
The Java Debugger (JDB) is included in the SDK for Linux. The debugger is invoked by the jdb command; it attaches to the JVM using JPDA.
To debug a Java application:
java -Xdebug -Xrunjdwp:transport=dt_socket,server=y,address=<port> <class>The JVM starts up, but suspends execution before it starts the Java application.
jdb -attach <port>The debugger will attach to the JVM, and you can now issue a range of commands to examine and control the Java application; for example, type run to allow the Java application to start.
For more information about JDB options, type:
jdb -help
For more information about JDB commands:
You can also use JDB to debug Java applications running on remote machines. JPDA uses a TCP/IP socket to connect to the remote JVM.
java -Xdebug -Xrunjdwp:transport=dt_socket,server=y,address=<port> <class>The JVM starts up, but suspends execution before it starts the Java application.
jdb -attach <host>:<port>
The Java Virtual Machine Debugging Interface (JVMDI) is not supported in this release. It has been replaced by the Java Virtual Machine Tool Interface (JVMTI).
For more information about JDB and JPDA and their usage, see these Web sites:
Use the com.ibm.jvm.Debuggable annotation to mark classes and methods that should be available for debugging. Use the -XselectiveDebug parameter to enable selective debugging at run time. The JVM optimizes methods that do not need debugging to provide better performance in a debugging environment.
Selective debugging is useful when Java is being used as a framework for development, for example, as an IDE. The Java code for the IDE is optimized for performance while the user code is debugged.
import com.ibm.jvm.Debuggable;
@Debuggable
public int method1() {
...
}@Debuggable
public class Class1 {
...
}Applications will run faster while being debugged because the core Java API and any IDE code can be optimized for performance.
Some Java applications must be able to determine whether they are running on a 32-bit JVM or on a 64-bit JVM. For example, if your application has a native code library, the library must be compiled separately in 32- and 64-bit forms for platforms that support both 32- and 64-bit modes of operation. In this case, your application must load the correct library at runtime, because it is not possible to mix 32- and 64-bit code.
The system property com.ibm.vm.bitmode allows applications to determine the mode in which your JVM is running. It returns the following values:
You can inspect the com.ibm.vm.bitmode property from within your application code using the call:
System.getProperty("com.ibm.vm.bitmode");
When a signal is raised that is of interest to the JVM, a signal handler is called. This signal handler determines whether it has been called for a Java or non-Java thread.
If the signal is for a Java thread, the JVM takes control of the signal handling. If an application handler for this signal is installed and you did not specify the -Xnosigchain command-line option, the application handler for this signal is called after the JVM has finished processing.
If the signal is for a non-Java thread, and the application that installed the JVM had previously installed its own handler for the signal, control is given to that handler. Otherwise, if the signal is requested by the JVM or Java application, the signal is ignored or the default action is taken.
For exception and error signals, the JVM either:
For interrupt signals, the JVM also enters a controlled shutdown sequence, but this time it is treated as a normal termination that:
The shutdown is identical to the shutdown initiated by a call to the Java method System.exit().
Other signals that are used by the JVM are for internal control purposes and do not cause it to terminate. The only control signal of interest is SIGQUIT, which causes a Javadump to be generated.
The types of signals are Exceptions, Errors, Interrupts, and Controls.
Table 7 below shows the signals that are used by the JVM. The signals are grouped in the table by type or use, as follows:
| Signal Name | Signal type | Description | Disabled by -Xrs |
|---|---|---|---|
| SIGBUS (7) | Exception | Incorrect access to memory (data misalignment) | Yes |
| SIGSEGV (11) | Exception | Incorrect access to memory (write to inaccessible memory) | Yes |
| SIGILL (4) | Exception | Illegal instruction (attempt to invoke an unknown machine instruction) | No |
| SIGFPE (8) | Exception | Floating point exception (divide by zero) | Yes |
| SIGABRT (6) | Error | Abnormal termination. The JVM raises this signal whenever it detects a JVM fault. | Yes |
| SIGINT (2) | Interrupt | Interactive attention (CTRL-C). JVM exits normally. | Yes |
| SIGTERM (15) | Interrupt | Termination request. JVM will exit normally. | Yes |
| SIGHUP (1) | Interrupt | Hang up. JVM exits normally. | Yes |
| SIGQUIT (3) | Control | A quit signal for a terminal. By default, this triggers a Javadump. | Yes |
| SIGTRAP (5) | Control | Used by the JIT. | Yes |
| __SIGRTMAX - 2 | Control | Used by the SDK. | No |
| SIGCHLD (17) | Control | Used by the SDK for internal control. | No |
Use the -Xrs (reduce signal usage) option to prevent the JVM from handling most signals. For more information, see Sun's Java application launcher page.
Signals 1 (SIGHUP), 2 (SIGINT), 4 (SIGILL), 7 (SIGBUS), 8 (SIGFPE), 11 (SIGSEGV), and 15 (SIGTERM) on JVM threads cause the JVM to shut down; therefore, an application signal handler should not attempt to recover from these unless it no longer requires the JVM.
The Runtime Environment contains signal-chaining. Signal-chaining enables the JVM to interoperate more efficiently with native code that installs its own signal handlers.
Signal-chaining enables an application to link and load the shared library libjsig.so before the system libraries. The libjsig.so library ensures that calls such as signal(), sigset(), and sigaction() are intercepted so that their handlers do not replace the JVM's signal handlers. Instead, these calls save the new signal handlers, or "chain" them behind the handlers that are installed by the JVM. Later, when any of these signals are raised and found not to be targeted at the JVM, the preinstalled handlers are invoked.
If you install signal handlers that use sigaction() , some sa_flags are not observed when the JVM uses the signal. These are:
The libjsig.so library also hides JVM signal handlers from the application. Therefore, calls such as signal(), sigset(), and sigaction() that are made after the JVM has started no longer return a reference to the JVM's signal handler, but instead return any handler that was installed before JVM startup.
To use libjsig.so:
gcc -L$JAVA_HOME/bin -ljsig -L$JAVA_HOME/bin/j9vm -ljvm java_application.cor
export LD_PRELOAD=$JAVA_HOME/bin/libjsig.so; java_application (bash and ksh) setenv LD_PRELOAD=$JAVA_HOME/bin/libjsig.so; java_application (csh)
The environment variable JAVA_HOME should be set to the location of the SDK, for example,/opt/ibm/java-<arch>-60/.
To use libjsig.a:
cc_r -q64 <other compile/link parameter> -L/opt/ibm/java-<arch>-60/jre/bin -ljsig -L/opt/ibm/java-<arch>-60/jre/bin/j9vm -ljvm java_application.c
Valid JNI version numbers that native programs can specify on the JNI_CreateJavaVM() API call are: JNI_VERSION_1_2(0x00010002) and JNI_VERSION_1_4(0x00010004).
This version number determines only the level of the JNI native interface to use. The actual level of the JVM that is created is specified by the JSE libraries (that is, v6). The JNI interface API does not affect the language specification that is implemented by the JVM, the class library APIs, or any other area of JVM behavior. For more information, see http://java.sun.com/javase/6/docs/technotes/guides/jni/.
If your application needs two JNI libraries, one built for 32- and the other for 64-bit, use the com.ibm.vm.bitmode system property to determine if you are running with a 32- or 64-bit JVM and choose the appropriate library.
To compile and link a native application with the SDK, use the following command:
gcc -I/opt/ibm/java-<arch>-60/include -L/opt/ibm/java-<arch>-60/jre/lib/<arch>/j9vm -ljvm -ldl -lpthread <JNI program filename>
The -ljvm option specifies that libjvm.so is the shared library that implements the JVM. The -lpthread option indicates that you are using native pthread support; if you do not link with the pthread library, a segmentation fault (signal SIGSEGV) might be caused when you run the JNI program.
Four new IBM-specific SDK classes have been added to the com.ibm.jvm package to support the thread-level recovery of Blocked connectors. The new classes are packaged in core.jar.
These classes allow you to unblock threads that have become blocked on networking or synchronization calls. If an application does not use these classes, it must end the whole process, rather than interrupting an individual blocked thread.
The classes are:
Both InterruptibleLockContext and InterruptibleIOContext work by referencing the current thread. Therefore if you do not use InterruptibleThread, you must provide your own class that extends java.lang.Thread, to use these new classes.
The Javadoc for these classes is provided with the SDK in the docs/content/apidoc directory.
You can enable large page support, on systems that support it, by starting Java with the -Xlp option.
Large page usage is primarily intended to provide performance improvements to applications that allocate a lot of memory and frequently access that memory. The large page performance improvements are mainly caused by the reduced number of misses in the Translation Lookaside Buffer (TLB). The TLB maps a larger virtual memory range and thus causes this improvement.
Large page support must be available in the kernel, and enabled, to allow Java to use large pages.
To configure large page memory allocation, first ensure that the running kernel supports large pages. Check that the file /proc/meminfo contains the following lines:
HugePages_Total: <number of pages> HugePages_Free: <number of pages> Hugepagesize: <page size, in kB>
The number of pages available and their sizes vary between distributions.
If large page support is not available in your kernel, these lines will not exist in the /proc/meminfo file. In this case, you must install a new kernel containing support for large pages.
If large page support is available, but not enabled, HugePages_Total will be 0. In this case, your administrator must enable large page support. Check your operating system manual for more instructions.
For the JVM to use large pages, your system must have an adequate number of contiguous large pages available. If large pages cannot be allocated, even when enough pages are available, possibly the large pages are not contiguous. Configuring the number of large pages at bootup will create them contiguously.
Large page allocations will only succeed if the user is a member of the group whose gid is stored in /proc/sys/vm/hugetlb_chm_group, or if Java is run with root access. See http://devresources.linux-foundation.org/dev/robustmutexes/src/fusyn.hg/Documentation/vm/hugetlbpage.txt for more information.
If a non-root user needs access to large pages, their locked memory limit must be increased. The locked memory limit must be at least as large as the maximum size of the Java heap. The maximum size of the Java heap can be specified using the -Xmx command-line option, or determined by adding -verbose:sizes and inspecting the output for the value -Xmx. If pam is not installed, change the locked memory limit using the ulimit command. If pam is installed, change the locked memory limit by adding the following lines to /etc/security/limits.conf:
@<large group name> soft memlock 2097152 @<large group name> hard memlock 2097152
Where <large group name> is the name of the group whose gid is stored in /proc/sys/vm/hugetlb_chm_group.
The Java Platform, Standard Edition (JSE) supports, at a minimum, the specifications that are defined in the compliance document from Sun. In some cases, the IBM JSE ORB supports more recent versions of the specifications.
The minimum specifications supported are defined in the Official Specifications for CORBA support in Java SE 6: http://java.sun.com/javase/6/docs/api/org/omg/CORBA/doc-files/compliance.html.
This SDK supports all versions of GIOP, as defined by chapters 13 and 15 of the CORBA 2.3.1 specification, OMG document formal/99-10-07.
http://www.omg.org/cgi-bin/doc?formal/99-10-07
Bidirectional GIOP is not supported.
This SDK supports Portable Interceptors, as defined by the OMG in the document ptc/01-03-04, which you can obtain from:
http://www.omg.org/cgi-bin/doc?ptc/01-03-04
Portable Interceptors are hooks into the ORB that ORB services can use to intercept the normal flow of execution of the ORB.
This SDK supports the Interoperable Naming Service, as defined by the OMG in the document ptc/00-08-07, which you can obtain from:
http://www.omg.org/cgi-bin/doc?ptc/00-08-07
The default port that is used by the Transient Name Server (the tnameserv command), when no ORBInitialPort parameter is given, has changed from 900 to 2809, which is the port number that is registered with the IANA (Internet Assigned Number Authority) for a CORBA Naming Service. Programs that depend on this default might have to be updated to work with this version.
The initial context that is returned from the Transient Name Server is now an org.omg.CosNaming.NamingContextExt. Existing programs that narrow the reference to a context org.omg.CosNaming.NamingContext still work, and do not need to be recompiled.
The ORB supports the -ORBInitRef and -ORBDefaultInitRef parameters that are defined by the Interoperable Naming Service specification, and the ORB::string_to_object operation now supports the ObjectURL string formats (corbaloc: and corbaname:) that are defined by the Interoperable Naming Service specification.
The OMG specifies a method ORB::register_initial_reference to register a service with the Interoperable Naming Service. However, this method is not available in the Sun Java Core API at Version 6. Programs that need to register a service in the current version must invoke this method on the IBM internal ORB implementation class. For example, to register a service "MyService":
((com.ibm.CORBA.iiop.ORB)orb).register_initial_reference("MyService",
serviceRef);
Where orb is an instance of org.omg.CORBA.ORB, which is returned from ORB.init(), and serviceRef is a CORBA Object, which is connected to the ORB. This mechanism is an interim one, and is not compatible with future versions or portable to non-IBM ORBs.
A runtime debug feature provides improved serviceability. You might find it useful for problem diagnosis or it might be requested by IBM service personnel.
For example, to trace events and formatted GIOP messages from the command line, type:
java -Dcom.ibm.CORBA.Debug=true
-Dcom.ibm.CORBA.CommTrace=true <myapp>
Do not turn on tracing for normal operation, because it might cause performance degradation. Even if you have switched off tracing, FFDC (First Failure Data Capture) is still working, so serious errors are reported. If a debug output file is generated, examine it to check on the problem. For example, the server might have stopped without performing an ORB.shutdown().
The content and format of the trace output might vary from version to version.
The ORB can be tuned to work well with your specific network. The properties required to tune the ORB are described here.
To disable fragmentation, set the fragment size to 0 bytes:
java -Dcom.ibm.CORBA.FragmentSize=0 <myapp>
When running with a Java SecurityManager, invocation of some methods in the CORBA API classes might cause permission checks to be made, which might result in a SecurityException. If your program uses any of these methods, ensure that it is granted the necessary permissions.
| Class/Interface | Method | Required permission |
|---|---|---|
| org.omg.CORBA.ORB | init | java.net.SocketPermission resolve |
| org.omg.CORBA.ORB | connect | java.net.SocketPermission listen |
| org.omg.CORBA.ORB | resolve_initial_references | java.net.SocketPermission connect |
| org.omg.CORBA. portable.ObjectImpl | _is_a | java.net.SocketPermission connect |
| org.omg.CORBA. portable.ObjectImpl | _non_existent | java.net.SocketPermission connect |
| org.omg.CORBA. portable.ObjectImpl | OutputStream _request (String, boolean) | java.net.SocketPermission connect |
| org.omg.CORBA. portable.ObjectImpl | _get_interface_def | java.net.SocketPermission connect |
| org.omg.CORBA. Request | invoke | java.net.SocketPermission connect |
| org.omg.CORBA. Request | send_deferred | java.net.SocketPermission connect |
| org.omg.CORBA. Request | send_oneway | java.net.SocketPermission connect |
| javax.rmi. PortableRemoteObject | narrow | java.net.SocketPermission connect |
A list of the ORB implementation classes.
The ORB implementation classes in this release are:
These are the default values, and you are advised not to set these properties or refer to the implementation classes directly. For portability, make references only to the CORBA API classes, and not to the implementation. These values might be changed in future releases.
Java Remote Method Invocation (RMI) provides a simple mechanism for distributed Java programming. RMI over IIOP (RMI-IIOP) uses the Common Object Request Broker Architecture (CORBA) standard Internet Inter-ORB Protocol (IIOP) to extend the base Java RMI to perform communication. This allows direct interaction with any other CORBA Object Request Brokers (ORBs), whether they were implemented in Java or another programming language.
The following documentation is available:
Thread pooling for RMI Connection Handlers is not enabled by default.
To enable the connection pooling implemented at the RMI TCPTransport level, set the option
-Dsun.rmi.transport.tcp.connectionPool=true
This version of the Runtime Environment does not have a setting that you can use to limit the number of threads in the connection pool.
From Java 5.0, the IBM BigDecimal class has been adopted by Sun as java.math.BigDecimal. The com.ibm.math.BigDecimal class is reserved for possible future use by IBM and is currently deprecated. Migrate existing Java code to use java.math.BigDecimal.
The new java.math.BigDecimal uses the same methods as both the previous java.math.BigDecimal and com.ibm.math.BigDecimal. Existing code using java.math.BigDecimal continues to work correctly. The two classes do not serialize.
To migrate existing Java code to use the java.math.BigDecimal class, change the import statement at the top of your .java file from: import com.ibm.math.*; to import java.math.*;.
The IBM SDK for Linux, v6 includes XToolkit by default. You need XToolkit when using the Eclipse's SWT_AWT bridge to build an application that uses both SWT and Swing.
Related links:
The Java plug-in is used to run Java applications in the browser. The appletviewer is used to test applications designed to be run in a browser. Java Web Start is used to deploy desktop Java applications over a network, and provides a mechanism for keeping them up-to-date.
The Java plug-in is a Web browser plug-in. You use the Java plug-in to run applets in the browser.
You must allow applets to finish loading to prevent your browser from stopping. For example, if you use the Back button and then the Forward button while an applet is loading, the HTML pages might be unable to load.
The Java plug-in is documented by Sun at: http://java.sun.com/javase/6/docs/technotes/guides/plugin/developer_guide/.
The Java plug-in supports SeaMonkey, Mozilla, and Mozilla Firefox.
| Browser | Supported versions |
|---|---|
| Mozilla | 1.7, 1.8 |
| Firefox | 2.0, |3.0 |
| Browser | Supported Versions |
|---|---|
| Mozilla | 1.6 |
| SeaMonkey | 1.0.8 |
Later minor releases of browsers are also supported.
To install the Java plug-in, symbolically link it to the plug-in directory for your browser.
The Java plug-in is based on Mozilla's Open JVM Integration initiative, which is used with most Mozilla products and derivatives, including Firefox.
You must symbolically link the plug-in, rather than copy it, so that it can locate the JVM.
Symbolically link the Java plug-in to the plug-ins directory for the Mozilla Web browser. Use the "about" information in Mozilla to verify the Java plug-in is correctly installed.
Only Mozilla versions 1.4 and later are supported.
To install the plug-in on Mozilla:
cd /usr/local/mozilla/plugins/
cd $HOME/.mozilla/plugins
ln -s /opt/ibm/java-<arch>-60/jre/plugin/<arch>/ns7/libjavaplugin_oji.so .Where <arch> is the architecture of your system.
To verify that the Java plug-in is available and enabled, select Help -> About plug-ins in Mozilla.
You must symbolically link the plug-in, rather than copy it, so that it can locate the JVM.
These steps make the Java plug-in available to all users.
cd /usr/local/mozilla-firefox/plugins/
ln -s /opt/ibm/java-<arch>-60/jre/plugin/<arch>/ns7/libjavaplugin_oji.so .Where <arch> is the architecture of your system.
You must symbolically link the plug-in, rather than copy it, so that it can locate the JVM.
Because of limitations in particular browsers, you might not be able to implement all the functions of the org.w3c.dom.html package.
One of the following errors is thrown:
The Java plug-in supports double-byte characters (for example, Chinese Traditional BIG-5, Korean, and Japanese) as parameters for the tags <APPLET>, <OBJECT>, and <EMBED>. You must select the correct character encoding for your HTML document so that the Java plug-in can parse the parameter.
Specify character encoding for your HTML document by using the <META> tag in the <HEAD> section like this:
<meta http-equiv="Content-Type" content="text/html; charset=big5">
This example tells the browser to use the Chinese BIG-5 character encoding to parse the HTML file.
With the Applet Viewer, you can run one or more applets that are called by reference in a Web page (HTML file) by using the <APPLET> tag. The Applet Viewer finds the <APPLET> tags in the HTML file and runs the applets, in separate windows, as specified by the tags.
Because the Applet Viewer is for viewing applets, it cannot display a whole Web page that contains many HTML tags. It parses only the <APPLET> tags and no other HTML on the Web page.
Use the following commands to run and debug an applet with the Applet Viewer.
Running applets with the Applet Viewer:
From a shell prompt, enter:
appletviewer <name>
where <name> is one of the following:
For example, to invoke the Applet Viewer on an HTML file that calls an applet, type at a shell prompt:
appletviewer $HOME/<filename>.html
Where filename is the name of the HTML file.
To invoke the Applet Viewer on a Web page, type at a shell prompt:
appletviewer http://java.sun.com/applets/jdk/1.4/demo/applets/NervousText/example1.html
The Applet Viewer does not recognize the charset option of the <
META
> tag. If the file that the Applet Viewer loads is not encoded as the system default, an I/O exception might occur. To avoid the exception, use the -encoding option when you run appletviewer. For example:
appletviewer -encoding JISAutoDetect sample.html
Debugging applets with the Applet Viewer:
For example:
cd demo/applets/TicTacToe ../../../bin/appletviewer -debug example1.html
You can find documentation about how to debug applets using the Applet Viewer at the Sun Web site: http://java.sun.com/javase/6/docs/technotes/guides/plugin/developer_guide/debugger.html.
Java Web Start is used for Java application deployment.
With Web Start, you can launch and manage applications directly from the Web. Applications are cached to minimize installation times. Applications are automatically upgraded when new versions become available.
Web Start supports these java-vm-args documented at http://java.sun.com/javase/6/docs/technotes/guides/javaws/developersguide/syntax.html#resources:
Web Start also supports -Xgcpolicy to set the garbage collection policy.
For information about the browsers that support Web Start, see Supported browsers.
For more information about Web Start, see:
For more information about deploying applications, see:
Web Start can be run from a Web page or the command line. Web Start applications are stored in the Java Application Cache.
You can invoke Web Start in a number of different ways.
javaws <URL>Where <URL> is the location of a .jnlp file.
/opt/ibm/java-<arch>-60/jre/bin/javaws -viewer
All Java Web Start applications are stored in the Java Application Cache. An application is downloaded only if the latest version is not in the cache.
Static versioning allows Web Start applications to request a specific JVM version on which those applications will run. Because static versioning also allows applications to exploit old security vulnerabilities on systems which have been upgraded to a new JVM, Secure Static Versioning (SSV) is now used by default.
With SSV, the user is warned before running any unsigned Web Start application that requests a specific JVM, if the requested JVM is installed. Signed applications and applications that request the latest version of the JVM run as normal.
You can disable SSV by setting the deployment.javaws.ssv.enabled property in the deployment.properties file to false.
Java applications typically consist of class, resource, and data files.
When you distribute a Java application, your software package probably consists of the following parts:
To run your application, a user needs the Runtime Environment for Linux. The SDK for Linux software contains a Runtime Environment. However, you cannot assume that your users have the SDK for Linux software installed.
Your SDK for Linux software license does not allow you to redistribute any of the SDK's files with your application. You must ensure that a licensed version of the SDK for Linux is installed on the target machine.
Class data sharing allows multiple JVMs to share a single space in memory.
The Java Virtual Machine (JVM) allows you to share class data between JVMs by storing it in a memory-mapped cache file on disk. Sharing reduces the overall virtual memory consumption when more than one JVM shares a cache. Sharing also reduces the startup time for a JVM after the cache has been created. The shared class cache is independent of any active JVM and persists until it is destroyed.
A shared cache can contain:
Class data sharing provides a transparent method of reducing memory footprint and improving JVM start-up time. Java 6 provides new and improved features in cache management, isolation, and performance.
Enable class data sharing by using the -Xshareclasses option when starting a JVM. The JVM connects to an existing cache or creates a new cache if one does not exist.
All bootstrap and application classes loaded by the JVM are shared by default. Custom classloaders share classes automatically if they extend the application classloader; otherwise, they must use the Java Helper API provided with the JVM to access the cache. See Adapting custom classloaders to share classes.
The JVM can also store ahead-of-time (AOT) compiled code in the cache for certain methods to improve the startup time of subsequent JVMs. The AOT compiled code is not shared between JVMs, but is cached to reduce compilation time when the JVM starts up. The amount of AOT code stored in the cache is determined heuristically. You cannot control which methods get stored in the cache, but you can set upper and lower limits on the amount of cache space used for AOT code, or you can choose to disable AOT caching completely. See Class data sharing command-line options for more information.
A JVM can access a cache with either read-write or read-only access. Any JVM connected to a cache with read-write access can update the cache. Any number of JVMs can concurrently read from the cache, even while another JVM is writing to it.
You must take care if runtime bytecode modification is being used. See Runtime bytecode modification for more information.
Because the shared class cache persists beyond the lifetime of any JVM, the cache is updated dynamically to reflect any modifications that might have been made to JARs or classes on the file system. The dynamic updating makes the cache transparent to the application using it.
Access to the shared class cache is limited by operating system permissions and Java security permissions. The shared class cache is created with user access by default unless the groupAccess command-line suboption is used. Only a classloader that has registered to share class data can update the shared class cache.
The cache memory is protected against accidental or deliberate corruption using memory page protection. This protection is not an absolute guarantee against corruption because the JVM must unprotect pages to write to them. The only way to guarantee that a cache cannot be modified is to open it read-only.
If a Java SecurityManager is installed, classloaders, excluding the default bootstrap, application, and extension classloaders, must be granted permission to share classes by adding SharedClassPermission lines to the java.policy file. See Using SharedClassPermission. The RuntimePermission createClassLoader restricts the creation of new classloaders and therefore also restricts access to the cache.
Multiple caches can exist on a system and you specify them by name as a suboption to the -Xshareclasses command. A JVM can connect to only one cache at any one time.
You can override the default cache size on startup using -Xscmx<n><size>. This size is then fixed for the lifetime of the cache. Caches exist until they are explicitly destroyed using a suboption to the -Xshareclasses command or the cache file is deleted manually.
All cache utilities are suboptions to the -Xshareclasses command. See Class data sharing command-line options or use -Xshareclasses:help to see a list of available suboptions.
Class data sharing and the cache management utilities are controlled using command-line options to the Java launcher.
For options that take a <size> parameter, suffix the number with "k" or "K" to indicate kilobytes, "m" or "M" to indicate megabytes, or "g" or "G" to indicate gigabytes.
Some cache utilities can work with caches from previous Java versions or caches created by JVMs with different bit-widths. These caches are referred to as "incompatible" caches.
You can use the following suboptions with the -Xshareclasses option:
See the Diagnostics Guide for more information.
An overview of the lifecycle of a shared class data cache including examples of the cache management utilities.
To enable class data sharing, add -Xshareclasses[:name=<name>] to your application command line.
The JVM either connects to an existing cache of the given name or creates a new cache of that name. If a new cache is created, it is populated with all bootstrap and application classes being loaded until the cache becomes full. If two or more JVMs are started concurrently, they populate the cache concurrently.
To check that the cache has been created, run java -Xshareclasses:listAllCaches. To see how many classes and how much class data is being shared, run java -Xshareclasses:[name=<name>],printStats. You can run these utilities after the application JVM has terminated or in another command window.
For more feedback on cache usage while the JVM is running, use the verbose suboption. For example, java -Xshareclasses:[name=<name>],verbose.
To see classes being loaded from the cache or stored in the cache, add -Xshareclasses:[name=<name>],verboseIO to your application command line.
To delete the cache, run java -Xshareclasses:[name=<name>],destroy. You usually delete caches only if they contain many stale classes or if the cache is full and you want to create a bigger cache.
You should tune the cache size for your specific application, because the default is unlikely to be the optimum size. To determine the optimum cache size, specify a large cache, using -Xscmx, run the application, and then use printStats to determine how much class data has been stored. Add a small amount to the value shown in printStats for contingency. Because classes can be loaded at any time during the lifetime of the JVM, it is best to do this analysis after the application has terminated. However, a full cache does not have a negative impact on the performance or capability of any JVMs connected to it, so it is acceptable to decide on a cache size that is smaller than required.
If a cache becomes full, a message is displayed on the command line of any JVMs using the verbose suboption. All JVMs sharing the full cache then loads any further classes into their own process memory. Classes in a full cache can still be shared, but a full cache is read-only and cannot be updated with new classes.
Class data sharing is particularly useful on systems that use more than one JVM running similar code; the system benefits from reduced virtual memory consumption. It is also useful on systems that frequently start up and shut down JVMs, which benefit from the improvement in startup time.
The overhead to create and populate a new cache is minimal. The JVM startup cost in time for a single JVM is typically between 0 and 5% slower compared with a system not using class data sharing, depending on how many classes are loaded. JVM startup time improvement with a populated cache is typically between 10% and 40% faster compared with a system not using class data sharing, depending on the operating system and the number of classes loaded. Multiple JVMs running concurrently show greater overall startup time benefits.
Duplicate classes are consolidated in the shared class cache. For example, class A loaded from myClasses.jar and class A loaded from myOtherClasses.jar (with identical content) is stored only once in the cache. The printAllStats utility shows multiple entries for duplicated classes, with each entry pointing to the same class.
When you run your application with class data sharing, you can use the operating system tools to see the reduction in virtual memory consumption.
Consider these factors when deploying class data sharing in a product and using class data sharing in a development environment.
The maximum theoretical cache size is 2 GB. The size of cache you can specify is limited by the amount of physical memory and paging space available to the system.
The cache for sharing classes is allocated using the System V IPC Shared memory mechanism.
Because the virtual address space of a process is shared between the shared classes cache and the Java heap, if you increase the maximum size of the Java heap you might reduce the size of the shared classes cache you can create.
Cache size is limited by SHMMAX settings, which limits the amount of shared memory that can be allocated. You can find these settings by looking at the/proc/sys/kernel/shmmax file. SHMMAX is usually set to 30 MB.
Any JVM using a JVM Tool Interface (JVMTI) agent that can modify bytecode data must use the modified=<modified_context> suboption if it wants to share the modified classes with another JVM.
The modified context is a user-specified descriptor that describes the type of modification being performed. The modified context partitions the cache so that all JVMs running under the same context share a partition.
This partitioning allows JVMs that are not using modified bytecode to safely share a cache with those that are using modified bytecode. All JVMs using a given modified context must modify bytecode in a predictable, repeatable manner for each class, so that the modified classes stored in the cache have the expected modifications when they are loaded by another JVM. Any modification must be predictable because classes loaded from the shared class cache cannot be modified again by the agent.
If a JVMTI agent is used without a modification context, classes are still safely shared by the JVM, but with a small impact on performance. Using a modification context with a JVMTI agent avoids the need for extra checks and therefore has no impact on performance. A custom ClassLoader that extends java.net.URLClassLoader and modifies bytecode at load time without using JVMTI automatically stores that modified bytecode in the cache, but the cache does not treat the bytecode as modified. Any other VM sharing that cache loads the modified classes. You can use the modified=<modification_context> suboption in the same way as with JVMTI agents to partition modified bytecode in the cache. If a custom ClassLoader needs to make unpredictable load-time modifications to classes, that ClassLoader must not attempt to use class data sharing.
See the Diagnostics Guide for more detail on this topic.
You cannot share classes between 32-bit and 64-bit JVMs. Temporary disk space must be available to hold cache information. The operating system enforces cache permissions.
For operating systems that can run both 32-bit and 64-bit applications, class data sharing is not permitted between 32-bit and 64-bit JVMs. The listAllCaches suboption lists 32-bit or 64-bit caches, depending on the address mode of the JVM being used.
The shared class cache requires disk space to store identification information about the caches that exist on the system. This information is stored in /tmp/javasharedresources. If the identification information directory is deleted, the JVM cannot identify the shared classes on the system and must re-create the cache. Use the ipcs command to view the memory segments used by a JVM or application.
Users running a JVM must be in the same group to use a shared class cache. The operating system enforces the permissions for accessing a shared class cache. If you do not specify a cache name, the user name is appended to the default name so that multiple users on the same system create their own caches by default.
If a SecurityManager is being used with class data sharing and the running application uses its own class loaders, you must grant these class loaders shared class permissions before they can share classes.
You add shared class permissions to the java.policy file using the ClassLoader class name (wildcards are permitted) and either "read", "write", or "read,write" to determine the access granted. For example:
permission com.ibm.oti.shared.SharedClassPermission
"com.abc.customclassloaders.*", "read,write";If a ClassLoader does not have the correct permissions, it is prevented from sharing classes. You cannot change the permissions of the default bootstrap, application, or extension class loaders.
Any classloader that extends java.net.URLClassLoader can share classes without modification. You must adopt classloaders that do not extend java.net.URLClassLoader to share class data.
You must grant all custom classloaders shared class permissions if a SecurityManager is being used; see Using SharedClassPermission. IBM provides several Java interfaces for various types of custom classloaders, which allow the classloaders to find and store classes in the shared class cache. These classes are in the com.ibm.oti.shared package.
The Javadoc for this package is provided with the SDK in the docs/content/apidoc directory.
See the Diagnostics Guide for more information about how to use these interfaces.
The Java Communications (API) package (JavaComm) is an optional package provided for use with the Runtime Environment for Linux on the IA32, PPC32/PPC64, and AMD64/EM64T platforms. You install JavaComm independently of the SDK or Runtime Environment.
The JavaComm API gives Java applications a platform-independent way of performing serial and parallel port communications for technologies such as voice mail, fax, and smartcards.
The Java Communications API supports Electronic Industries Association (EIA)-232 (RS232) serial ports and Institute of Electrical and Electronics Engineers (IEEE) 1284 parallel ports and is supported on systems with the IBM Version 6 Runtime Environment.
Using the Java Communications API, you can:
Make sure that the SDK or Runtime Environment is installed before you install the Java Communications API.
If you used the RPM package to install Java originally, install the Java Communications API from the RPM file. To install the Java Communications API from an RPM package, see Installing the Java Communications API from an RPM file.
To install the Java Communications API from a compressed file:
tar -xvzf ibm-java-javacomm-3.0-0.0-<plat>-<arch>.tar.gz
Where <arch> represents your architecture: i386, x86_64, ppc, or ppc64.
Make sure that a copy of the SDK or Runtime Environment is installed before you install the Java Communications API.
If you used the RPM package to install Java originally, install the Java Communications API from the RPM file.
rpm -ivh ibm-java-<arch>-javacomm-3.0-0.0.rpmThe Java Communications API is installed within the /opt/ibm/java-<arch>-60/ directory structure.
By default, the Java Communications API files are installed in the /opt/ibm/java-<arch>-60/ directory.
The files and their structure are:
To use the Java Communications API, you must change the access mode of serial and parallel ports, and set the PATH if you did not set it when you installed Java.
See Setting the path.
After you install Java Communications API, you must change the access mode of serial and parallel ports so that users can access these devices.
You must give a user read and write access to the required devices. Log on as root and use the following commands, as applicable:
chmod 660 /dev/ttyS0 (serial port COM1)
chmod 660 /dev/ttyS1 (serial port COM2)
chmod 660 /dev/ttyS2 (serial port COM3)
chmod 660 /dev/ttyS3 (serial port COM4)
chmod 660 /dev/parport0 (raw parallel ports)
chmod 660 /dev/parport1 (raw parallel ports)
Add specific users to the group in which the devices reside. On a SUSE system, for example, the devices are in the uucp group. Thus, users can be added to the uucp group to gain access to the devices.
Change the access mode of any other ports as needed.
Use the javax.comm.properties file to specify the devices and drivers that are available to the Java Communications API and whether they are parallel or serial. Do not change this file without a very clear understanding of its use.
The following properties must be defined:
driver=<driver_name> serpath0=<serial_port_device> parpath0=<parallel_port_device>
For example:
# Implementation specific driver driver=com.sun.comm.LinuxDriver # Paths to server-side serial port devices serpath0 = /dev/ttyS0 serpath1 = /dev/ttyS1 # Paths to server-side parallel port devices parpath0 = /dev/parport0 parpath1 = /dev/parport1
For parallel port access, use /dev/parport<n>. /dev/lp<n> is not supported in Javacomm version 3.0.
Most ThinkPads have their serial ports disabled by default in the BIOS. Currently, there is no way to enable the ports with Linux (the tpctl package does not enable the ports if they are disabled in the BIOS).
To enable the ports in the BIOS, you must use the DOS version of the ThinkPad Configuration Utility that is available from the IBM ThinkPad Download site. To use the ThinkPad Configuration Utility, you need a bootable DOS diskette. The ThinkPad Configuration Utility might have been installed as part of the ThinkPad Utilities under Windows®, depending on your installation options, and you can run it from a command prompt in Windows.
The ThinkPad Configuration application provided with Windows has options to enable or disable the serial and parallel ports but this does not also change the settings in the BIOS. So if you use this application with Windows, the ports are available; however, if you reboot your system with Linux, the ports will not be enabled.
When printing with the Java Communications API, you might have to select "Form feed", "Continue", or a similar option on the printer.
The process you use to uninstall the Java Communications API depends on whether you installed the installable Red Hat Package Manager (RPM) package or the compressed Tape Archive (TAR) package.
Uninstalling the Java Communications API using the RPM package.
rpm -e ibm-java-<arch>-javacomm-3.0-0.0
Where <arch> is the architecture of your platform.
Alternatively, you can use a graphical tool such as kpackage or yast2.Where <arch> is the architecture of your platform.
By default, the SDK is installed in the /opt/ibm/java-<arch>-60/ directory.Uninstalling the Java Communications API, if you installed the compressed TAR package.
Delete the following files from the directory where you installed them:
Where <arch> is the architecture of your platform.
You can find API documentation and samples for the Java Communications API at the Sun Web site.
http://java.sun.com/products/javacomm/.
Contact points for service:
If you are entitled to services for the Program code pursuant to the IBM Solutions Developer Program, contact the IBM Solutions Developer Program through your normal method of access or on the Web at: http://www.ibm.com/partnerworld/.
If you have purchased a service contract (that is, IBM's Personal Systems Support Line or equivalent service by country), the terms and conditions of that service contract determine what services, if any, you are entitled to receive with respect to the Program.
The user guides that are supplied with this SDK and the Runtime Environment have been tested using screen readers.
To change the font sizes in the user guides, use the function that is supplied with your browser, typically found under the View menu option.
For users who require keyboard navigation, a description of useful keystrokes for Swing applications is in Swing Key Bindings at http://www.ibm.com/developerworks/java/jdk/additional/.
If you traverse the drop-down list of a JComboBox component with the cursor keys, the button or editable field of the JComboBox does not change value until an item is selected. This is the correct behavior for this release and improves accessibility and usability by ensuring that the keyboard traversal behavior is consistent with mouse traversal behavior.
From Version 5.0, Java Web Start contains several accessibility and usability improvements, including better support for screen readers and improved keyboard navigation.
You can use the command line to launch a Java application that is enabled for Web Start. To change preference options, you must edit a configuration file, .java/.deployment/.deployment.properties in the user's home directory. Take a backup before you edit this file. Not all of the preferences that can be set in the Java Application Cache Viewer are available in the configuration file.
If you have any comments about this user guide, contact us through one of the following channels. Note that these channels are not set up to answer technical queries, but are for comments about the documentation only.
Send your comments:
The fine print. By choosing to send a message to IBM, you acknowledge that all information contained in your message, including feedback data, such as questions, comments, suggestions, or the like, shall be deemed to be non-confidential and IBM shall have no obligation of any kind with respect to such information and shall be free to reproduce, use, disclose, and distribute the information to others without limitation. Further, IBM shall be free to use any ideas, concepts, know-how or techniques contained in such information for any purpose whatsoever, including, but not limited to, developing, manufacturing and marketing products incorporating such information.
The -X options listed below are nonstandard and subject to change without notice.
For options that take a <size> parameter, suffix the number with "k" or "K" to indicate kilobytes, "m" or "M" to indicate megabytes, or "g" or "G" to indicate gigabytes.
For options that take a <percentage> parameter, use a number from 0 to 1. For example, 50% is 0.5.
The options file does not support the following options:
.
Causes verbose garbage collection (GC) output to be written to the specified file. If the file exists, it is overwritten. Otherwise, if an existing file cannot be opened or a new file cannot be created, the output is redirected to stderr. If you specify the arguments X and Y (both are integers) the verbose GC output is redirected to X number of files, each containing Y number of gc cycles worth of verbose GC output. These files have the form filename1, filename2, and so on. By default, no verbose GC logging occurs.
See the Diagnostics Guide for more information about verbose GC output.
Known limitations on the SDK and Runtime Environment for Linux.
You can find more help with problem diagnosis in the Diagnostics Guide at http://www.ibm.com/developerworks/java/jdk/diagnosis/60.html.
|
|
| Installation can fail using RPM on Ubuntu
|because the RPM package dependencies are not met. The dependencies
|are met by Ubuntu packages. You can install the IBM SDK for Java using
|the .tgz package, or you can force RPM installation
|by using the --nodeps command-line option. For
|example: Where <arch> is
|the architecture of your system. The following error is displayed
|if you try to install using RPM without the -nodeps option:Installation
|on Ubuntu using RPM
|rpm -ivh --nodeps ibm-java-<arch>-sdk-6.0-3.0.<arch>.rpm
error: Failed dependencies:
| glibc >= 2.3 is needed by ibm-java-<arch>-sdk-6.0-3.0.<arch>
| libstdc++.so.5 is needed by ibm-java-<arch>-sdk-6.0-3.0.<arch>
| /bin/sh is needed by ibm-java-<arch>-sdk-6.0-3.0.<arch>
The IBM SDK for Java does not support printing using the CUPS interface.
The Node memory interleaving BIOS setting must be set to DISABLED. Otherwise, unpredictable results might occur, including Java crashes and hangs. This instruction is in accordance with AMD's recommendation.
In IBM's JConsole tool, the Local tab, which allows you to connect to other Virtual Machines on the same system, is not available. Also, the corresponding command-line pid option is not supported. Instead, use the Remote tab in JConsole to connect to the Virtual Machine that you want to monitor. Alternatively, use the connection command-line option, specifying a host of localhost and a port number. When you launch the application that you want to monitor, set these command-line options:
|
|
| When running a 32-bit JVM on a 64-bit Ubuntu system,
|GUI applications will not start because some AWT libraries are missing.
|To fix the problem, install the 32-bit libraries using the ia32-libs package: The
|following exception is thrown if the libraries are not available:GUI applications,
|such as the JConsole monitoring tool, on 64-bit Ubuntu with a 32-bit
|JVM
|sudo apt-get install ia32-libs
Exception in thread "main" java.lang.UnsatisfiedLinkError: awt (An exception was pending after running JNI_OnLoad)
| at java.lang.ClassLoader.loadLibraryWithPath(ClassLoader.java:993)
| at java.lang.ClassLoader.loadLibraryWithClassLoader(ClassLoader.java:962)
| at java.lang.System.loadLibrary(System.java:465)
| ... lines removed for clarity ...
If new classes are loaded after an Exception has been caught, the stack trace contained within the Exception might become incorrect. The stack trace becomes incorrect if classes in the stack trace are unloaded, and new classes are loaded into their memory segments.
The IBM SDK for Linux, v6 Web Start does not support launching Java 1.3 applications.
Creating DSA key pairs of unusual lengths can take a significant amount of time on slow machines. Do not interpret the delay as a hang because the process will complete if sufficient time is allowed. The DSA key generation algorithm has been optimized to generate standard key lengths (for instance, 512, 1024) more quickly than others.
Native programs cannot create a VM with JNI_VERSION_1_1(0x00010001) interfaces. You cannot call JNI_CreateJavaVM() and pass it a version of JNI_VERSION_1_1(0x00010001). The versions that can be passed are:
The VM created is determined by the Java libraries present (that is, 1.2.2, 1.3.x, 1.4.x, 5.x, 6.x), not the one that is implied by the JNI interface version passed.
The interface version does not affect any area of VM behavior other than the functions available to native code.
Your window manager might override some of the Java keyboard shortcuts. If you need to use an overridden Java keyboard shortcut, consult your operating system manual and change your window manager keyboard shortcuts.
The X Window System is unable to use file descriptors above 255. Because the JVM holds file descriptors for open jar files, X can run out of file descriptors. As a workaround, you can set the JAVA_HIGH_ZIPFDS environment variable to tell the JVM to use higher file descriptors for jar files.
To use the JAVA_HIGH_ZIPFDS environment variable, set it to a value between 0 and 512. The JVM will then open the first jar files using file descriptors up to 1024. For example, if your program is likely to load 300 jar files:
export JAVA_HIGH_ZIPFDS=300
The first 300 jar files will then be loaded using the file descriptors 724 to 1023. Any jar files opened after that will be opened in the normal range.
You might not be able to use the system clipboard with double-byte character set (DBCS) to copy information between Linux applications and Java applications if you are running the K Desktop Environment (KDE).
On SLES9 and newer distributions, the default threading library is NPTL, which implements Java threads as native threads. On earlier distributions, the default threading library is LinuxThreads, which implements threads as new processes. If the number of Java threads exceeds the maximum number of processes allowed, your program might hang.
The maximum number of threads available is determined by the lowest of:
However, you might run out of virtual storage before you reach the maximum number of threads.
There is no way to distinguish between user mode CPU time and system mode CPU time on this platform. ThreadMXBean.getThreadUserTime(), ThreadMXBean.getThreadCpuTime(), ThreadMXBean.getCurrentThreadUserTime(), and ThreadMXBean.getCurrentThreadCpuTime() all return the total CPU time for the required thread.
KeyEvent results that include the Alt key might differ between window managers in Linux. They also differ from results of other operating systems. When using the default settings, Ctrl+Alt+A in the KWin window manager produces a KeyEvent, whereas Ctrl+Alt+A in the Metacity window manager does not produce a key event.
On the Linux X Window System, the keymap is set to: 64 0xffe9 (Alt_L) 0xffe7 (Meta_L), and 113 0xffea (Alt_R) 0xffe8 (Meta_R). You can check this by typing the following at a shell prompt:
xmodmap -pk
This is why the SDK considers that Meta and Alt are being pressed together. As a workaround, you can remove the Meta_x mapping by typing the following at a shell prompt:
xmodmap -e "keysym Alt_L = Alt_L" -e "keysym Alt_R = Alt_R"
This workaround might affect other X-Window applications that are running on the same display if they use the Meta-key that was removed.
A call to JNI_CreateJavaVM() from a JNI application might cause a segmentation fault (signal SIGSEGV); to avoid this fault, rebuild your JNI program specifying the option -lpthread.
If you are running with a lot of concurrent threads, you might get a warning message:
java.lang.OutOfMemoryError
This is an indication that your machine is running out of system resources and messages can be caused by the following reasons:
Try tuning your system to increase the corresponding system resources.
|
|
| For Chinese, Korean, and Japanese
|language users of Ubuntu only. Chinese, Korean, and Japanese
|locales will not display the correct fonts if CJK fonts are not used.
|Input Method selection has not been tested.National
|language support on Ubuntu
|
When running a Java AWT or Swing application on a Linux machine and exporting the display to a second machine, you might experience problems displaying some dialogs if the set of fonts loaded on the X client machine is different from the set loaded on the X server machine. To avoid this problem, install the same fonts on both machines.
If your system locale is using a UTF-8 encoding, some SDK tools might throw a sun.io.MalformedInputException. To find out whether your system is using a UTF-8 encoding, examine the locale-specific environment variables such as LANG or LC_ALL to see if they end with the suffix ".UTF-8". If you get this sun.io.MalformedInputException, change characters that are not within the 7-bit ASCII range (0x00 - 0x7f) and are not represented as Java Unicode character literals to Java Unicode character literals (for example: '\u0080'). You can also work around this problem by removing the ".UTF-8" suffix from the locale-specific environment variables; for example, if your machine has default locale of "en_US.UTF-8", set LANG to "en_US".
If you are using AMI and xcin in a cross-platform environment (for example, if you try to export the display between a 32-bit and a 64-bit system, or between a big-endian and a little-endian system) there might be some problems. If you have this kind of problem, upgrade to the latest version of AMI and xcin.
For Chinese, Korean and Japanese language users of RHEL4 only.
No XIM server is installed by default. To input DBCS characters to a Java application, please install a XIM server package such as iiimf-x or kinput2.
For Chinese, Korean, and Japanese language users of RHEL4 only.
If you are using the Internet/Intranet Input Method Framework (IIIMF), use IIIMF packages that are included in Red Hat Enterprise Linux 4 Update 2 or later. Contact Red Hat for guidance, at http://www.redhat.com.
(zSeries 64-bit only) You might experience IIIMF failures or a failure to start. To resolve the problem, upgrade to the latest IIIMF packages.
(Traditional Chinese on PPC, s390, or s390x only) IIIMF might not work. To resolve the problem, use iiimf-le-xcin-0.1.7-13.EL4 or later.
(Simplified Chinese on PPC, s390, or s390x only) IIIMF might not work correctly. To resolve the problem, use IIMF packages included in RHEL4 Update 5 or later.
Simplified Chinese language users of RHEL4 only.
The zh_CN.GB18030 locale is not supported by xlib in RHEL4. xterm cannot activate Input Method Server to input GB18030 characters. Use the zh_CN.UTF8 locale instead. If you have legacy programs or data encoded with GB2312, GBK, or GB18030, and you want to migrate them to RHEL4, you must preprocess them with iconv to convert them to UTF-8 encoding so that the programs can run and data can be displayed properly in RHEL4 with the zh_CN.UTF8 locale.
This limitation is resolved in RHEL4 U3.
You might experience hangs with xcin on RHEL4. To resolve the problem, set ICCHECK_DISABLE to YES in the /etc/chinese/xcin/xcinrc file.
64-bit environments only
On RHEL4 with xcin (Traditional Chinese XIM server), you might experience unexpected behavior such as a segementation fault with Java on 64-bit environments (such as AMD64 or zSeries 64-bit platforms). To resolve the problem, upgrade to the latest xcin package.
RHEL4 only.
When using IIIMF (Internet Intranet Input Method Framework) to input DBCS characters, you might encounter focus change problems. The problem occurs when minimizing active input components. After restoring the component, the input method will switch back to SBCS. DBCS must then be manually reactivated.
The following components have this focus change problem:
RHEL4 and SLES9 only
For Japanese, Chinese, and Korean language users, you cannot use XIM to input your own characters into text components on a Java applet in a Web browser. This limitation occurs because XEmbed requires a fix to the X11 library file. To work around this situation, specify the -Dsun.awt.noxembed=true system parameter to disable XEmbed. You can set this option by using the control panel:
This limitation is resolved in RHEL4 U3 and SLES9 SP3.
Intel 32-bit platforms only
For Arabic text users, when using Linux with a Matrox video card and acceleration enabled, distortion of characters can be seen when using drawString to display large fonts. This problem is caused by the driver for those cards. The suggested workaround is to disable acceleration for the device.
Intel 32-bit platforms only
On SLES 9 NPTL, the parallel port driver causes a kernel crash and brings down a Java thread. The JVM detects this crash when it tries to suspend the thread for Garbage Collection and then crashes producing a core file and the message "JVMLH030: threads are disappearing when trying to suspend all threads".
SUSE Bugzilla report 47947 is raised against this problem. This bug is fixed in SLES 9 Service Pack 1.
PPC platforms only
If your Java code uses JNI calls, and any specific call has more than eight float or double parameters, your C code must be compiled with the gcc-2.95.3 Free Software Foundation (FSF) level of GNU C Compiler (GCC).
PPC platforms only
The JavaComm package cannot support parallel port operations on the SLES 9 GA and SP1 kernels. This limitation is resolved in the SP2 kernel. The SUSE Bugzilla number is 50028.
PPC 64-bit platforms only
The default gcc cross compiler (version 3.2-49) causes several errors. To generate the shared library libFileStat.so, run:
/opt/cross/bin/powerpc64-linux-gcc -shared -o libFileStat.so -I<SDK_PATH>/include FileStat.c
where <SDK_PATH> is the path to the installed SDK directory.
zSeries platforms only
Although the Linux kernel in the current distributions provides support for Internet Protocol version 6 (IPv6), you might encounter problems using it. Support for IPv6 from Java is included in this release, but you are advised to turn off the support with the -Djava.net.preferIPv4Stack=true option on the java command. If you install a kernel that fully supports IPv6, you do not need this option.
zSeries 64-bit platforms only
The Chinese and Taiwanese input method server (xcin) has not been tested.
The Java Desktop API might not work because one or more GNOME libraries are not available.
DBCS environments only
If your application fails with a NullPointerException using the GTK Look and Feel, unset the GNOME_DESKTOP_SESSION_ID environment variable.
Japanese users only
The unicode codepage alias "\u30b7\u30d5\u30c8\u7b26\u53f7\u5316\u8868\u73fe" for Shift_JIS has been removed. If you use this codepage in your applications, replace it with Shift_JIS.
This information was developed for products and services offered in the U.S.A. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area.
Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter 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:
For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to:
The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law:
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.
This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the 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:
Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee.
The licensed program described in this document and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement or any equivalent agreement between us.
Any performance data contained herein was determined in a controlled environment. Therefore, the results obtained in other operating environments may vary significantly. Some measurements may have been made on development-level systems and there is no guarantee that these measurements will be the same on generally available systems. Furthermore, some 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.
All statements regarding IBM's future direction or intent are subject to change or withdrawal without notice, and represent goals and objectives only.
IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of International Business Machines Corporation in the United States, other countries, or both. If these and other IBM trademarked terms are marked on their first occurrence in this information with a trademark symbol (® or ™), these symbols indicate U.S. registered or common law trademarks owned by IBM at the time this information was published. Such trademarks may also be registered or common law trademarks in other countries. A current list of IBM trademarks is available on the Web at "Copyright and trademark information" at http://www.ibm.com/legal/copytrade.shtml.
Intel is a trademark of Intel Corporation in the United States, other countries, or both.
Linux is a trademark of Linus Torvalds in the United States, other countries, or both.
UNIX is a registered trademark of The Open Group in the United States and other countries.
Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.
Other company, product, or service names may be trademarks or service marks of others.