OpenJDK 6 for OS/2 and eCS Version 1.6.0 Build 22 WSE (2011-05-12) This is a special Warpstock Europe 2011 build that contains some important improvements over RC2. INTRODUCTION This document contains a brief information on the OS/2 version of the OpenJDK 6 product. Please read it carefully before starting your work. You may also visit the project page at http://svn.netlabs.org/java/wiki to get more information and the latest news and also to report bugs. To get a brief list of OS/2-specific changes from release to release please see the CHANGES.OS2 file included in this distribution. REQUIREMENTS In order to use this version of OpenJDK, you will need the following: - A OS/2 Warp 4 Fixpack 16+, OS/2 Warp 4.5 or eComStation operating system. - Odin32 library version 0.6.21632 (2011-05-12) or above: ftp://ftp.netlabs.org/pub/odin/odin32bin-20110512-release.wpi - Extended system tray widget for XCenter version 0.1.1 or above (optional, but required for system tray support in Java applications): ftp://ftp.netlabs.org/pub/qt4/xsystray/xsystray-0_1_1.wpi INSTALLATION The OpenJDK product is distributed in two packages: the JRE and the SDK (which includes a copy of JRE). Simply take a necessary package and unzip it to a directory of your choice. You will need to add the \bin subdirectory inside this directory to PATH and BEGINLIBPATH to allow for starting Java executables from an arbitrary location: set PATH=\bin;%PATH% set BEGINLIBPATH=\bin;%BEGINLIBPATH% Also make sure there are no traces of other Java installations in the environment because this is known to make problems (in particular, this means that the CLASSPATH/JAVA_HOME/SWING_HOME environment variables should not be set). Alternatively, you may add this subdirectory to PATH and LIBPATH statements of your CONFIG.SYS (and reboot) to make the given Java installation the default one. Please read the further sections (especially the "CURRENT LIMITATIONS" section below) to make sure that you are aware of possible problems you may run into while running Java applications using this product. FONT SELECTION OpenJDK comes with no fonts and uses the system fonts by default. On OS/2, these fonts are Helvetica, Times New Roman and Courier -- they are are present in any version of OS/2. However, these are very old Type1 fonts with many glyphs having poor quality which can be seen even with font anti-aliasing turned on. For this reason, OpenJDK for OS/2 provides an alternative font configuration that uses a freely available Liberation font family: Liberation Sans, Liberation Serif and Liberation Mono (with font metrics close to a widely used set of Monotype TTF fonts: Arial, Times New Roman and Courier New, respectively). In order to use the Liberation font family instead of the default Type1 fonts, do the following: 1. Download the latest binary (TTF) archive of Liberation fonts from: https://fedorahosted.org/liberation-fonts/ 2. Copy all *.TTF files from the archive to a directory and install them normally (for example, using the OS/2 Font Palette object). 3. Go to the directory "\bin\jre\lib" (where is where you installed SDK package) or "\lib" (where \bin\jre\lib" (or to "\lib") again and copy the file "fontconfig.default.bfc" to "fontconfig.bfc". Note that you need to restart all Java applications to let them pick up the new fonts. Font Anti-Aliasing In the current release, due to the low quality of the standard OS/2 Type1 fonts, both AWT and Swing Java GUI toolkits use subpixel font anti-aliasing by default for all standard components. If you want to change this behavior, you may use the following Java command line option: -Dawt.useSystemAAFontSettings= where is one of the following anti-aliasing modes: off Turns anti-aliasing off on Turns on monochrome anti-aliasing lcd | lcd_hrgb * Turns on subpixel anti-aliasing optimized for HRGB LCD panels lcd_hbgr Turns on subpixel anti-aliasing optimized for HBGR LCD panels lcd_vrgb Turns on subpixel anti-aliasing optimized for VRGB LCD panels lcd_vbgr Turns on subpixel anti-aliasing optimized for VBGR LCD panels The setting marked with * is the default anti-aliasing value as it is suitable for the majority of the modern display hardware. MEMORY REQUIREMENTS Sometimes you may find out that starting a Java application fails with the following error message: Error occured during initialization of VM Could not reserve enough space for object heap Could not create the Java virtual machine. This means that the amount of memory Java wants to reserve for its heap is bigger than the maximum free block of memory available to the Java process. Note that the size of this free block does not directly depend on the amount of physical RAM installed in your computer (because the physical RAM may be extended using the swap file, for instance). It rather depends on the virtual address limit set by OS/2 for the process. In older OS/2 versions that don't support high memory (e.g. the ones based on pre-WSeB kernels) this limit is known to be 512M. In later versions it is controlled by the VIRTUALADDRESSLIMIT parameter in CONFIG.SYS (which is specified in megabytes and defaults to 1024). Furthermore, not all memory within the virtual address limit is available to the process. Some small fraction of it is used by the kernel and the rest is divided in two more or less equal parts: the private arena and the shared arena. As said, the size of these arenas does not depend on the amount of physical RAM and can be approximated using the following table. Note that the values in the table are not the initial arena sizes but rather the sizes of the maximum free block of memory available in the corresponding arena to a dummy process that does nothing but queries these system values (all numbers are in MB, the first column is for systems with no high memory support): VIRTUALADDRESSLIMIT *512 | 1024 | 1536 | 2048 | 3072 ------------------------------------------------------------------- Max free block in private arena 267 | 432 | 880 | 1328 | 2224 Max free block in shared arena 228 | 404 | 852 | 1230 | 2196 Note that these values are gathered on a default eCS 2.0 GA system and may vary depending on what system DLLs get loaded into each process; they are given only as an example. You may get the real values on your system with a variety of tools gathering system information, such as THESEUS. On the other hand, when calculating the default amount of memory to reserve for the heap (which is called the maximum heap size in the documentation), Java uses the physical RAM size as a base, not the the size of the free block in the private arena (where Java actually allocates the heap). Below is a simplified version of the algorithm for these calculations: 1. Use MIN (MaxRAM, ) as the base RAM value. MaxRAM is a Java constant that defaults to 1G for the client (default) Java virtual machine and to 4G for the server JVM. 2. Divide this base RAM value by MaxRAMFraction (4 by default) and assign the result as the default value for the maximum heap size (MaxHeapSize). 3. Use the MaxHeapSize value increased by 20-30% (for the needs other than the Java heap) as the size of the memory block to allocate in the private arena. So, if your machine has, say, 2G of RAM and you attempt to start a Java application Java server mode (using the -server command line option), Java will want 512M (2G/4) plus additional 20-30%. This would obviously not fit into 432M of free private memory available for the process when VIRTUALADDRESSLIMIT is set to 1024 and this was the case with earlier releases of OpenJDK 6 for OS/2 as well as with the releases of InnoTek Java 1.4.x for OS/2. Starting with version 6 Beta 2, OpenJDK for OS/2 solves this problem by limiting the amount of memory Java wants for the heap to the actual size of the available memory block in the private arena. So, in the above case Java will actually get about 310M in server mode (instead of performing a failed attempt to allocate 512M). You may change this limit by changing the VIRTUALADDRESSLIMIT value in CONFIG.SYS (according to the table above), but please note that values higher than 1024 may cause problems with some drivers (for example, it is known that JFS and HPFS386 drivers cannot allocate a disk cache of the big size if the VIRTUALADDRESSLIMIT value is too high). In either case, the above describes how Java calculates the defaulut maximum heap size. You may always override this default using the -Xmx Java command line option if you are not satisfied with the default value for some reason or if your applcation gives you the "Could not reserve enough space for object heap" error message at startup. However, keep in mind that if you specify a -Xmx value which is, increased by 20-30% as described in step 3 above, bigger than the maximum free block in the private arena, you will get the same memory allocation error which indicates that you should use a smaller value. DLL NAMES In the environment necessary to run OpenJDK on OS/2, the directory containing JDK DLLs is listed in either LIBPATH or BEGINLIBPATH variable which makes these DLLs available to Java processes as well as to any other process running in the same environment. The original versions of OpenJDK use very generic DLL names for some components (such as jpeg.dll, zip.dll) which may create name conflicts with system DLLs and cause the Java DLLs to be loaded by programs instead of the system ones leading to program malfunction. To reduce the possibility of such conflicts, all Java DLLs that didn't have a 'j' prefix in their names were renamed by prepending 'j' to the original DLL name. Besides adding the 'j' prefix, some DLLs were also renamed further to fit the 8 character DLL name length limit forced by the OS/2 kernel loader. This rename operation is transparent to all Java applications except a few cases which involve custom agent libraries used to enhance the functionality of JDK or JVM. These libraries in particular include: Original Name New Name -------------------------------------------- hprof.dll jhprof.dll dt_shmem.dll jdtshmem.dll dt_socket.dll jdtsock.dll In order to use the renamed libraries, you need to substitute the old name with the new name wherever the old name is used in Java documentation, configuration files or command line options. For example, to use the profiler library, you will have to write "-agentlib:jhprof.dll" on the command line instead of "-agentlib:hprof.dll" and so on. CURRENT LIMITATIONS 1. OpenJDK will not work correctly under the OS/2 SMP kernel (Java process hangs are very likely). This is a known problem of Odin32 which will be addressed in further releases. The workaround is to use the OS/2 UNI or Warp4 kernel instead. 2. The com.sun.tools.attach package (API to attach to a Java virtual machine) is missing. See the project roadmap for more information on the current progress and future plans: http://svn.netlabs.org/java/roadmap Feel free to request new features and report bugs using the project bug tracker abaialble at: http://svn.netlabs.org/java/report CREDITS Dmitriy Kuminov (development) Silvan Scherrer (management) netlabs.org (hosting & support) Oracle Corporation (original OpenJDK product) We also want to THANK all individuals and organizations who made the donations to this project and helped to make it happen. Oracle and Java are registered trademarks of Oracle and/or its affiliates. OS/2 and OS/2 Warp are trademarks of the IBM Corporation and/or its subsidiary(-ies). eComStation is a trademark of Serenity Systems International and/or its subsidiary(-ies). Other names may be trademarks of their respective owners.