CD Actual Thematic 7: Programming

home *** CD-ROM | disk | FTP | other *** search

/ CD Actual Thematic 7: Programming / CDAT7.iso / demos / VisualAge for Java 2.0 Entry / setup / data1.cab / ide-e / IDE / RELNOTES / JCL.TXT < prev next >

Wrap

Text File | 1998-09-16 | 29.7 KB | 719 lines

============================================================================ VisualAge for Java Version 2.0 Java Class Libraries and Program Execution RELEASE NOTES ============================================================================ Table of Contents 1.0 Introduction 2.0 The Class Libraries 2.1 General Notes 2.2 package java.lang 2.2.1 Math 2.2.2 Exceptions 2.2.3 Class Loader 2.2.4 Special case for Runtime.getRuntime().exec (...); 2.3 package java.awt 2.3.1 Fonts 2.3.2 Graphics 2.3.3 Widgets 2.4 package java.applet 2.4.1 Applet security 2.5 package sun.jdbc.odbc 2.6 package sun.tools.jar 2.7 package java.io 2.8 package java.util 2.8.1 package java.util.zip 2.9 package java.net 2.10 RMI 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, on the class libraries provided with VisualAge Version 2.0 . In addition, it describes how programs are executed within the VisualAge environment. 2.0 The Class Libraries 2.1 General Notes This release is based on the Sun JDK 1.1.6 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 allows us to provide capabilities such as execution of multiple simultaneous Java programs within a single execution environment, live edit of 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 1.1.6 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 1.1.6 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.2 package java.lang 2.2.1 Math VisualAge 2.0 uses the standard IEEE representation as defined in the Java specification. The previous release (VisualAge for Java 1.0) had a limitation where all floating point values were double (i.e. 8 byte IEEE). This was a known limitation which has been removed in this release. 2.2.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 (Caught Exceptions) or from another browser, using Window->Debug->Caught Exceptions. The ThreadDeath exception does not provide interesting stack trace information. 2.2.3 ClassLoader As per a standard Java virtual machine 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 in such a way 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 leads to 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.2.4 Special case for Runtime.getRuntime().exec (...); You can launch an external program by the use of Runtime.getRuntime().exec (...). If that program happens to be the "java" executable, the IDE will recognize it and will 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, make sure you give it a different name or simply use an absolute file path to it (e.g. "c:\bin\java ..." instead of "java ..."). 2.3 package java.awt 2.3.1 Fonts The following are the known limitations and omissions in the AWT font support as provided by the VisualAge Version 2.0 class libraries. Some of these cases describe platform behavior which application programmers should be aware of. 2.3.1 Fonts * 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, 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.3.2 Graphics The following are the known limitations and omissions in the AWT graphics support as provided by the VisualAge Version 2.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 colours available in 256 colour 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 (i.e. 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 draw one pixel too large in some situations. This 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: - first print the off-screen image without drawing any file images on top of it; - then print the file images directly to the printer. 2.3.3 Widgets The following are the known limitations and omissions in the AWT widget peer classes as provided by the VisualAge Version 2.0 class libraries. Some of these cases describe platform behavior which application programmers should be aware of. * Sun JDK 1.1.6 API missing features All API for the Java AWT peer interfaces are implemented, with the exception of the following: ALL Platforms. ii) java.awt.peer.FileDialogPeer setFilenameFilter(java.io.FilenameFilter) * Color limitation (Windows 95/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/NT only) The background and foreground colours for java.awt.Buttons can not be changed. * Color limitation (OS/2 only) On OS/2 Warp 4 in 256 color mode when running Netscape 2.02 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. (i.e. Unchecking 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 (OS2 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 jump Clicking on a scroll bar within the scrollpane to page up or down can cause the scroll bar to jump once after the block increment is set. * FileDialog save (Windows 95, 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. * F1 and F10 keys are not captured using a java.awt.event.KeyListener on OS/2. F10 triggers the system menu or the first menu of a menu bar and F1 starts up on-line help. 2.4 package java.applet 2.4.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. 2.5 package sun.jdbc.odbc The following are the known limitations and omissions in the sun.jdbc.odbc package as provided by the VisualAge Version 2.0 class libraries. * OS/2 JDBC-ODBC Bridge At the time of product availability, the Bridge was not included in the 1.1.6 OS/2 JDK. JDBC data access via OS/2 ODBC drivers is not supported in the VisualAge for OS/2 development environment. 2.6 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.7 package java.io * The API lastModified() will return zero when the file has a name with double byte characters. *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.8 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.8.1 package java.util.zip *ZipOutputStream.write(...) fails to zip all bytes ZipOutputStream.write(...) is failing to zip all bytes into the stream if the buffer passed as a parameter is bigger than 32K. The zip entry will be truncated to 32K if a program opens a file, reads it into a byte array (bigger than 32K) and trys to zip it into a zip file. Workaround: write into the zip stream using a small buffer (4K for example) in a loop. 2.9 package java.net The following behaviour can be observed in the VisualAge version 2.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. 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 re-use 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.10 RMI * RMIRegistry (AIX and Solaris) 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 1) re-start VisualAge. 2) start the RMI registry on another port. * RMIRegistry 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 a side effect other programs started after changing the workspace classPath will have that entry in the classPath as well. 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. Roughly speaking, 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 feel as though it has hung. Typical actions that cause this are waiting on OS blocking calls or blocking on monitors (i.e., 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 concurrency 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 just as 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 behaviour 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 (ie: 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. (e.g.: 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 R2.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 (i.e. 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.