source: trunk/doc/README.OS2@ 295

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=<directory>\bin;%PATH%
    set BEGINLIBPATH=<directory>\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 "<SDK>\bin\jre\lib" (where <SDK> is where you installed
     SDK package) or "<JRE>\lib" (where <JRE is where you installed the JRE
     package) and copy the file "fontconfig.liberation.bfc" to "fontconfig.bfc".
     It is safe to overwrite the target file.

  In order to return back to the default fonts, go to "<OpenJDK>\bin\jre\lib"
  (or to "<JRE>\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=<mode>

  where <mode> 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, <physical_RAM>) 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<size> 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. Due to the way how importing from DLLs works in OS/2, it is not possible to
     have two applications using the same OpenJDK installation but different JVM
     types (client or server) running at the same time.

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

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