                          VisualAge(R) for Java(TM)
                                  Version 3.0
    
                     Java Class Libraries and Program Execution

                                  RELEASE NOTES



Table of Contents
----------------

1.0 Introduction
2.0 The Class Libraries
    2.1 Limitations and known problems
        2.1.1 package java.lang
              2.1.1.1 Math
              2.1.1.2 Exceptions
              2.1.1.3 Class Loader
        2.1.2 package java.awt
              2.1.2.1 Fonts
              2.1.2.2 Graphics
              2.1.2.3 Widgets
        2.1.3 package sun.jdbc.odbc
        2.1.4 package sun.tools.jar
        2.1.5 package java.io
        2.1.6 package java.util
        2.1.7 package java.net
        2.1.8 RMI
    2.2 Hints and Tips
        2.2.1 package java.lang
              2.2.1.1 Special case for Runtime.getRuntime().exec (...);
        2.2.2 package java.applet
              2.2.2.1 Applet security
3.0 Program Execution
    3.1 Java threads
        3.1.1 Threads and JNI
        3.1.2 Terminating threads in the debugger
    3.2 Simulating multiple virtual machines
    3.3 Running Java programs and changing a type
    3.4 Object finalization
    3.5 Memory limit
    3.6 JNI
        3.6.1 Unsupported JNI API
        3.6.2 JNI on OS/2

1.0 Introduction
----------------

This release note provides information, which can not be found
elsewhere in the documentation on the class libraries provided with 
VisualAge Version 3.0. In addition, it describes how programs
are executed within the VisualAge environment.

This release is based on the Sun JDK 1.1.7A class libraries. In
general, there is a very high degree of compatibility between the 
Sun JDK and VisualAge implementations. However, there are some
differences. In the following sections, they will be described.  
They can be broken down into the following major areas:

    - The AWT peer classes provided with VisualAge are based on a 
      stable, multi-platform class library which uses real platform 
      widgets as the underlying implementation. This means VisualAge 
      can enable you to execute of multiple simultaneous Java 
      programs within a single execution environment, live edit AWT 
      widgets within the development tools, and correct platform 
      specific behavior from portable application code.

    - All native methods provided with VisualAge have been
      implemented by the VisualAge team. In the few cases where the Sun 
      JDK implementation differs from the Sun specified behavior, we
      have attempted to follow the spec. In cases where the spec was 
      ambiguous, VisualAge have attempted to match the Sun JDK behavior.
 
    - A small number of changes were made to the JDK libraries to address
      bugs which would have significant impact on the usability of the
      system.
 
2.0 Limitations and known problems
----------------------------------

2.1 The Class libraries

2.1.1 package java.lang

2.1.1.1 Math

VisualAge 3.0 uses the standard IEEE representation as defined in the
Java specification. VisualAge for Java 1.0 had a limitation where all
floating point values were double (that is, 8 byte IEEE). This was a 
known limitation that does not exist in this release.

2.1.1.2 Exceptions

The stack trace information which is provided by the
Throwable.printStackTrace(...) method will not match exactly the
output from a Sun VM's stack trace. This reflects different
underlying implementations, and is not a defect.

When an uncaught exception causes the debugger to open, only the
stack between the last place where the exception was caught (for
example, by a "synchronize (...) { ... }" statement) and the root of
the stack trace will be visible. There are two possible strategies
for debugging under this scenario. One is to breakpoint the method
causing the problem and manually step through the offending code. The
other strategy is to place a breakpoint where a particular exception
is thrown and just let the code run. You can activate this feature
from the Debugger (Exceptions) or from another browser, using
Window - Debug - Caught Exceptions.

The ThreadDeath exception does not provide any detailed stack trace
information.

2.1.1.3 ClassLoader

The classPath variable is used to specify which locations are 
examined when trying to load classes or resources. The IDE adds
the ability to treat projects loaded into the workspace as 
elements of the classPath.  When a program attempts to locate a
class or resource the search proceeds as follows:

1. Search the projects in the IDE workspace as specified by the classPath
2. Dynamically load class/resource from a jar/directory on the classPath
3. Dynamically load class/resource from the project resources directory
      
The ClassLoaders included with VisualAge are constructed so
that they respect both the user-specified classPath and the rules of 
the development environment concerning how classes are brought into
the workspace and code repository. This causes the following 
restrictions:

    - ClassLoaders obey the classPath specified for the program, any 
    call to the default loadClass(...) methods in ClassLoader, or
    Class.forName(...) will throw a ClassNotFoundException if the 
    type is not reachable on the specified classPath.

    - When a program that has dynamically loaded classes completes or is
    terminated all dynamically loaded classes are unloaded.
     
    - The IDE allows a class of a given fully-qualified name to be
    dynamically loaded even if a like-named class exists in the IDE
    workspace. However, the workspace and dynamically loaded versions 
    of these classes cannot be run concurrently. The program that 
    loaded the dynamically loaded version must run to completion or be
    terminated before the workspace version can be invoked.

    - The IDE only safely supports one instance of a class with a given name
    across all default packages. For example, having a class named 'A' 
    in the default package of projects ProjA and ProjB can lead to
    unpredictable results.

    - It is not possible to use defineClass(...) to redefine an
    existing class in the workspace.

2.1.2 package java.awt

2.1.2.1 Fonts

The following are the known limitations and omissions in the AWT font
support as provided by the VisualAge Version 3.0 class libraries.
Some of these cases describe platform behavior which application
programmers should be aware of.

* Japanese characters specified in .properties files do not display 
  correctly on Solaris.

    When Japanese characters are specified in a .properties file using 
    the JavaSoft recommended approach of using a 6 character ASCII 
    unicode escape string (e.g. \u3058) per Japanese character, the 
    characters do not display correctly when the properties file is used 
    in VisualAge. This is due to the difference in the way font 
    sets are created and used on Solaris between VisualAge and JavaSoft.

* BeanBox dialog and menu fonts are hard to read on Japanese AIX

  The fonts used for the BeanBox dialogs and menus do not scale 
  to a small size well on Japanese AIX, which makes the dialogs 
  and menus hard to read.  

* Font names lowercased

  Font names returned by java.awt.Toolkit.getFontList() are in lower 
  case. This is correct behavior because they appear as lower case in 
  the resource file named 'font.properties'. Sun's VM returns mixed 
  case names because they have hardcoded font names and do not use the 
  font.properties resources.
    
* On Japanese AIX, some bold and italic versions of fonts are not bold 
  or italic.

  On Japanese AIX, some of the fonts in the default font.properties file
  do not correctly display bold or italic.  It is possible that if your 
  application uses its own .properties file(s), you could specify a font
  for which bold and italic work. The problem is due to the way font sets
  are created by Motif versus the way the JDK supports font sets.

2.1.2.2 Graphics

The following are the known limitations and omissions in the AWT
graphics support as provided by the VisualAge Version 3.0 class
libraries. Some of these cases describe platform behavior which
application programmers should be aware of.


* No support for PM Palette Manager (OS/2 only)

  Using the PM Palette Manager can cause other applications to display 
  with incorrect colors. Applications which do use the PM Palette 
  Manager, such as Netscape, can cause VisualAge to draw with 
  incorrect colors. We recommend disabling the 'Palette Aware' option 
  of Netscape, located on the Colors page of Netscape's Options / General 
  Preferences dialog.

* VisualAge running at 256 colors on UNIX has incorrect colors 
  when Netscape is running

  When running Netscape simultaneously with the VisualAge IDE, VisualAge 
  may not be able to obtain all the colors it requires, which results in 
  various colors being incorrect.

  Workaround: 
  If the incorrect colors create a problem, do not run Netscape at the same
  time as VisualAge.

* Image dithering quality (OS/2 only)

  Image dithering has lower quality on OS/2 WARP than on Windows.  This 
  is due to the limitation on the number of colors available in 256 
  color mode on OS/2 WARP when not using the PM Palette Manager. In 
  addition, ordered dithering of images produces images that are too 
  light in the OS/2 WARP implementation. Ordered dithering is only used
  when an ImageProducer sends data in random (that is, not in top-down, 
  left-right) order. This latter problem does not appear when loading 
  .GIF and .JPEG files.

* Arc/oval dimensions

  Arcs and ovals are drawn one pixel too large in some situations. 
  This event is more likely when the dimensions are even.  
 
* Internal Error running image loading code.

  VisualAge can get internal errors under high stress conditions -
  typically while running multiple programs that load images. Code
  which fetches images must call back to Java from native code, and
  this can fail occasionally when the system is very busy.

* Large Bold characters added when printing from OS/2 Japanese.

  There is an OS/2 printer driver bug when printing from OS/2 Warp 4 
  Japanese to a 'Hewlett Packard Laser Jet III Si' printer. Occasionally 
  large bold characters are added to the text that is printed.

* Non-black text is not printed on 'Hewlett Packard Laser Jet III Si' printer
  from Windows NT.

  Printing text using the java.awt.Graphics.drawString(String g, int x, int y)
  method will map all non-black text to white giving the appearance that the
  text is not printed.  

  Workaround: Print only black text.

* Printing Japanese characters from Windows 95 can cause Windows 
  General Protection Faults

  For some printers, printing Japanese characters from certain Japanese 
  fonts from Windows 95 can cause General Protection Faults which will 
  terminate VisualAge.  The same problem will happen when using
  the same font and printer with other Windows applications as well.

  Workaround: Do not allow your application to use that font and
  printer combination.

* Off screen images are not printed on Postscript printers from Windows NT
  when image files, such as GIF or JPEG, are drawn on top of it using
  the java.awt.Graphics.drawImage() methods.

  Workaround: Print in two steps:
              1. Print the off-screen image without drawing any 
                file images on top of it;
              2. Print the file images directly to the printer.

2.1.2.3 Widgets

The following are the known limitations and omissions in the AWT
widget peer classes as provided by the VisualAge Version 3.0 class
libraries.  Some of these cases describe platform behavior which
application programmers should be aware of.

* Sun JDK 1.1.7A API missing features

    All API for the Java AWT peer interfaces are implemented, with the 
    exception of the following on all platforms: 

    java.awt.peer.FileDialogPeer
    setFilenameFilter(java.io.FilenameFilter)
   
* Color limitation (Windows 95/98/NT only)

    When running the VisualAge IDE on Windows in 256 color mode it is 
    possible that widgets will not be drawn using the exact color that 
    was requested. On Windows, in 256 color mode, only the 20 system
    colors are used by the operating system to draw the background 
    and foreground of widgets. 

    Workaround: 
    Use 16-bit color mode.

* Button Color limitation (Windows 95/98/NT only) 

   The background and foreground colors for java.awt.Buttons can not
   be changed.

* Color limitation (OS/2 only)
    
  On OS/2, Warp 4 in 256 color mode when you run Netscape 2.2 
  simultaneously with the VisualAge IDE, the IDE is unable to get all 
  the colors needed to draw widgets and graphics.
       
    Possible workarounds: 
    1. Disable palette awareness in Netscape by deselecting the 
       palette aware option on the General Preferences Color page.
    2. Use 16-bit color mode.
    3. Do not run Netscape when using the IDE in 256 color mode.

* Button has extra border (OS/2 only)

  Buttons have an extra border around them which is drawn in black when
  they are selected, and in the background color when they are not. This
  can give the appearances of extra space during layout relative to the
  appearance on other platforms, but is not a bug.

* Cursors in lightweight components (OS/2 only)

  If the cursor is inside a lightweight component and the cursor type for 
  this component is changed, it will not be updated until the mouse 
  pointer is moved out of the component and back in.

* Fonts in menus

  Setting fonts in menus (using MenuComponent.setFont(...)) will not 
  change the font.

* Paint and update events
        
  Paint and update events are sent right after showing a window.
  Application code which sends show() or setVisible() to a window before 
  ensuring that all initialization required to handle the paint() and 
  update() methods is complete may be unprepared for the first paint or 
  update call. For example, code like the following which needs 
  paintColor to be non-nil in the paint() method may fail.

        MyFrame mf = new MyFrame("Not Initialized");
        mf.show();
        // paint method uses paintColor to draw things
        // but initializes it after sending show() (*wrong!*)
        Color paintColor = Color.red;

* Scrollpane scrollbars readjust
  
  Clicking on a scroll bar within the scrollpane to page up or down can 
  cause the scroll bar to readjust after the block increment is set.  

* FileDialog save (Windows 95,98,NT only)

   FileDialog does not prompt to overwrite files by default. When 
   opening a FileDialog for saving a file, the VisualAge AWT file 
   dialog does not prompt the user if they want to overwrite an 
   existing file of the same name.

* Initial Frame sizes

   When the width and height are not specified for Frames in VisualAge
   they will not open so small that widgets are not visible. 
   VisualAge Java picks a minimum size which makes widgets visible in 
   the Frame.

* Clipboard lost ownership notifications

   Clipboard owners are not notified via #lostOwnership() when the 
   clipboard contents change.

2.1.3 package sun.jdbc.odbc

The following are the known limitations and omissions in the sun.jdbc.odbc 
package as provided by the VisualAge Version 3.0 class libraries. 

* OS/2 JDBC-ODBC Bridge
 
  At the time of product availability, the Bridge was not included 
  in the most recent OS/2 JDK. JDBC data access via OS/2 ODBC drivers is 
  not supported in the VisualAge for OS/2 development environment.

2.1.4 package sun.tools.jar

* Running the jar utility from the IDE does not convert wildcard 
arguments as in the following:

   jar cvf test.jar *.class

This is correct behavior -- in the Sun implementation it is the JAR.EXE 
file which provides wildcarding, not the Java code. 

Under OS/2, the jar utility does not support specifying options such as

    jar cvf test.jar .

2.1.5 package java.io

* java.io.FileStreams

  The bytes written in a file are flushed only when the file
  is closed. A program that writes bytes on a FileOutputStream and, 
  without closing it, opens a FileInputStream on the same file
  will not be able to read the bytes because they were not flushed yet.

2.1.6 package java.util
 
* java.util.TimeZone ( OS/2 )

  If the field java.util.TimeZoneData.zones does not include the time
  zone taken from the Operating System another one with the same 
  offset will be chosen.

  On OS/2 German the TZ var is set as 'MEZ-1' which is not
  in the TimeZoneData table; consequently the user.time zone will be
  set as "Europe/Paris" (GMT). In this case the API currentTimeMillis
  will answer a number with a one hour difference.

   Workaround: change the TZ var before starting VisualAge

2.1.7 package java.net

The following behaviour can be observed in the VisualAge version 3.0 
java.net classes:

In general, the return errors vary slightly from the JDK. 
For example, errors in attempting to connect to a socket address/port 
will generate a SocketException with the error Connection Refused
instead of a ConnectException. 

On AIX/Solaris:

java.net.ServerSocket does not free the socket properly in the
following case:

The server socket is waiting on an accept call with no timeout
specified and an attempt is made to close the socket from another
thread. It will not be possible to reuse that address/port pair
until you exit the VisualAge and restart it.  This problem stems 
from an underlying tcp stack problem, so it may occur differently
depending upon the OS version.
    
2.1.8 RMI

* RMI Registry only starts once

  The RMI Registry will start once, but it fails to close the
  server socket and the pair address/port will not be freed starting 
  the RMI Registry a second time in the same port will fail. The
  status message will say that rmi registry is started, but
  an exception will be printed in the console and the
  status message will not be updated.

There are two possible workarounds for this problem:
        1. Restart VisualAge for Java.
        2. Start the RMI registry on another port.

* RMI Registry class path (all platforms) required

  The RMI Registry is using the workspace class path which needs
  to include the project that has the stub/skeleton classes. 
  Otherwise, a NoClassDefFoundError exception will be thrown.
  As well, other programs started after changing the workspace
  classPath will have that entry in the classPath as well.

2.2 Hints and Tips

2.2.1 package java.lang

2.2.1.1 Special case for Runtime.getRuntime().exec (...);

You can launch an external program by the use of
Runtime.getRuntime().exec (...).  If that program is the
"java" executable, the IDE will recognize it and automatically
redirect this and run the java program in the IDE itself.  For
instance, load project "IBM Java Examples" and try the following in
the Scrapbook:

Runtime.getRuntime().exec ("java com.ibm.ivj.examples.awttests.AwtRollingOTI");

If you go to the Debugger you will see that the new Java program is
running in the IDE itself.  As part of the name listed in the
Debugger you will see the extra text "<unnamed>".  

If you need to launch "java" outside the IDE, ensure you give
it a different name or simply use an absolute file path to it (e.g.
"c:\bin\java ..." instead of "java ...").

2.2.2. package java.applet

2.2.2.1 Applet security

Applets are run from within the environment with an AppletSecurity
manager active. By default this security manager will provide only very
restrictive network access. This access can be changed using the
AppletViewer properties menu.

3.0 Program Execution
---------------------

Warning: The aspects of the execution environment described in this
section may change in future releases. Therefore, you should avoid
implementing code that relies on the behavior described here.

3.1 Java threads

Java threads are not implemented as OS threads. Basically, the
whole environment runs as a single OS thread, and Java threads are
implemented in software by the environment itself. Threads are
scheduled based on time slices of approximately 10 milliseconds. You
cannot change this value.

Although priorities of Java threads can be changed by the API
available in java.lang.Thread, internally they are scheduled as
though they all have the same priority. The IDE itself also runs as a
thread (which is not visible to application code), but at a higher
priority. This may cause the other threads to "freeze" when IDE
operations are being performed.

This approach allows the IDE UI to be more responsive to user
actions.  However, it also means that if the IDE UI blocks for some
reason (and it can), the environment will act as though it has hung.
Typical actions that cause this are waiting on OS blocking calls or
blocking on monitors (that is, synchronized methods). Therefore, Java
code that is run from within the IDE UI thread can potentially lock
the environment. Typically, this does not happen, but it can occur
when evaluating synchronized methods from the debugger and during
certain operations performed by the visual composition editor. 

3.1.1 Threads and JNI

Even though Threads in the IDE are not implemented with real OS
threads, a JNI call that may end up making an OS blocking call will
not lock the whole VM. A proprietary mechanism is used so that the
other Java threads still run, simulating the concurrent running
of real OS threads.

3.1.2 Terminating threads in the debugger

Caution should be used when terminating threads in the debugger,
since this may cause deadlocks or prevent an application from
processing events. For instance, the standard AWT event dispatch
thread for a Java program (that has AWT windows) shows up in the list
of available threads, and if it is terminated, that particular
program will no longer respond to UI events (mouse move/enter/click,
etc ). You will have to terminate that Java program using the
Debugger to get the window(s) to close.

If you use the Visual Composition Editor (VCE) and you have enabled
"Show system programs" from the Debugging page of the Options dialog,
you will be able to see the AWT EventQueue thread for the program you
are building visually. The same restrictions apply here - make sure
you do not terminate any of the threads or the program itself. Make
sure you use just the VCE itself for that particular program.
Internal errors may happen if you fail to do so.

3.2 Simulating multiple virtual machines

The Scrapbook can have multiple pages, each of which behaves like a
completely separate Java program running in its own virtual machine.
Code that is run in one page has no side-effects on code running in
other pages. Therefore, if you have client/server programs for
example, and you want to test them in the same machine, there is no
need to start two separate environments. All you need to do is open a
page in the Scrapbook and type in code to launch your server. Then go
to another page and type the code to launch your client code. They
behave as if they were launched from two separate virtual machines.

Here is a simpler example. If you have class X with static slot y,
and it is initialized with null as shown below:

   public static String y = null;

and you go to one new page of the Scrapbook and run:

   X.y = "abc"; com.ibm.uvm.tools.DebugSupport.inspect (X.y);

you get an Inspector showing:

   "abc"

Now go to another new page of the Scrapbook and run:

   com.ibm.uvm.tools.DebugSupport.inspect (X.y);

In this Inspector the value of y is still null.

Note, however, that if you add, modify or delete methods or classes,
the changes are global to the environment. That is, any changes in
the code either in methods, or the shape of the classes, are
immediately visible in all Scrapbook pages where these classes are
used (and in all associated inspectors, debuggers, and so on). In
some cases, depending on the change, the Scrapbook page may be reset
- see the section: 'Running Java Programs and Changing a Type'.

As you would expect, code which is run from the Run - In Applet
Viewer... and Run - Run Main... menu items also behaves like a
completely separate Java program running in its own virtual machine.

3.3 Running Java programs and changing a type

You can change methods as a Java program runs, and this will have
immediate impact on the behavior of the application, so that you can
experiment with changes. However, if you change a type significantly
(adding/removing fields, etc.) all programs where that type has
been initialized will be terminated. In the case of Scrapbook pages,
the pages will be reset.

Changes in static fields do not cause program termination or Scrapbook 
pages to be reset.

A special case of this behavior is the finalize() method. An object
will only be finalized if a finalize() method (other than the one in
Object) was defined at the time the object was instantiated. Adding a
finalizer to running code will allow any new objects to be finalized
when they become garbage, but any pre-existing objects will not be
finalized.  If a finalizer is deleted, when the objects are collected
the nearest superclass finalize() implementation is used (potentially
the one in Object)

3.4 Object finalization

Objects that are no longer referenced may be finalized if they
implement the finalize() method. However, it is important to note
that nothing prevents users from writing finalizers that can,
potentially, loop forever. For instance, a finalizer can be
implemented to do

    while (true) {};

This would make the finalizer thread loop forever,
being unable to finalize any other objects.

Another obvious case is deadlock, where a finalizer attempts to call
a synchronized method, and there is already a different thread in the
monitor associated with the object. In this case the finalizer will
have to wait until the monitor is released. If the monitor is never
released due to program bugs, the finalizer will also block forever.

Programs can also generate garbage at a high rate, in which case the
finalizers have to be run more often. Running finalizers is very
important in an integrated environment like the IDE, since it can
host multiple programs running (for instance, multiple applets, or
multiple pages in the Scrapbook), simulating multiple virtual
machines as described in section 3.2.

Not running finalizers could mean leaking OS resources, which
is why the IDE is careful about finalizing as much as possible.

In order to cope with the constraints above, the IDE reserves a
finalizer thread with an internal priority higher than the priority
at which the Java programs usually run (See the section: 'Java
threads').  This thread sleeps for a while, then it wakes up and
finalizes some objects, then it sleeps again. If the garbage creation
rate is high, it will run longer (finalizing) between sleeps.  It
also has a timeout to run finalization. If objects cannot be
finalized in that particular interval the finalizer thread is
terminated and a new one is created, and the whole finalization
mechanism is restarted. Currently the finalization timeout is five
seconds, and the finalizer sleeps/wakes up every one second. These
values cannot be changed.

3.5 Memory limit

This release of VisualAge has an aggressive memory allocation scheme
that attempts to compact the heap several times before asking the OS
for more memory.  In addition, there is a relatively high limit on
how much memory can be allocated from the OS.  If the machine has
overcommitted on memory allocation, the compaction algorithm will
cause swapping.  If the user wishes to manually cut down the amount
of memory available to the product (i.e.: cause OutOfMemoryError
exception to be thrown earlier), please add the following two lines
of text to the end of the ide.ini file in the program directory:

[VM Options]
maximumMemoryLimit=ZZZ

Where ZZZ is the maximum number of BYTES the product should be
allowed to allocate. (for example,: maximumMemoryLimit=128000000 for approx.
128MB memory limit).

Note also that the VM behaves differently than the Sun JDK when
dealing with OutOfMemoryError.  Attempting to allocate many more
objects after the exception has been thrown can lead to the abrupt
termination of the whole IDE.

3.6 JNI

3.6.1 Unsupported JNI API

* The JNI Invocation API methods are not implemented.

  This is a known limitation in R3.0 of VisualAge.

3.6.2 JNI on OS/2

* JNI on OS/2 requires IBM VisualAge C++ for OS/2, Version 3 CSD level 
  CTC306 or later.

  The following system error, which prematurely terminates the IDE, 
  may occur with prior CSD levels of the C compiler when a JNI 
  native C implementation contains a printf() and console output 
  is not redirected (that is, IDE > trace).

   OS/2 - SYS-147

   Not enough resources are available to process this command.
   The process for which this pop-up is displayed will end.
