Programming with VisualAge for Java

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

/ Programming with VisualAge for Java / IBMVJAVA.ISO / vajwin / data1.cab / Ide / relnotes / jcl.txt < prev next >

Wrap

Text File | 1997-07-04 | 24.6 KB | 597 lines

============================================================================ VisualAge for Java Version 1.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 Threads 2.2.3 Exceptions 2.2.4 Class Loader 2.3 package java.awt 2.3.1 Widgets 2.3.2 Graphics 2.4 package java.io 2.5 package java.applet 2.5.1 Sound support 2.5.2 Applet security 2.6 package java.util 2.6.1 Locale support 2.7 package sun.jdbc.odbc 2.8 package sun.tools.jar 3.0 Program Execution 3.1 Java threads 3.1.2 Terminating threads in the Debugger 3.2 Object mutation 3.3 Object finalization 3.4 JNI 3.4.1 Unsupported JNI API 3.4.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 for Java Version 1.0 . In addition, it describes how programs are executed within the VisualAge for Java environment. 2.0 The Class Libraries 2.1 General Notes This release is based on the Sun JDK 1.1.1 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, we will describe these differences, but 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 for Java have been implemented by the VisualAge team. In the few cases, where the Sun JDK 1.1.1 implementation differs from the Sun specified behavior, we have attempted to follow the spec. In cases where the spec. was ambiguous, we have attempted to match the Sun JDK 1.1.1 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. - There are some known limitations which will be fixed in a later release. 2.2 package java.lang 2.2.1 Math The internal representation of all floating point values in VisualAge for Java is double (i.e. 8 byte IEEE). This is a know limitation which will be fixed in a later release. 2.2.2 Threads Please see Section 3.1 2.2.3 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 the differing 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. This is technically correct, but less than optimal from a debugging standpoint. The best strategy is to breakpoint the method causing the problem and manual step through the offending code. The ThreadDeath exception does not provide interesting stack trace information. 2.2.4 ClassLoader The ClassLoaders included with VisualAge for Java are constructed in such a way that they respect the rules of the development environment concerning how classes are brought into the workspace and code repository. This leads to the following restrictions: All pre-defined types which VisualAge for Java deals with must exist in the repository as well as the workspace. Any call to the default loadClass(...) methods in ClassLoader, or Class.forName(...) will throw a ClassNotFoundException if the type is not already loaded in the workspace. If a class is dynamically constructed (i.e. via defineClass(...)), then it is both created in the repository and loaded into the workspace. All dynamically loaded class are created in their respective packages in an automatically generated project named 'Uvm dynamically loaded classes'. In addition, it is not possible to use defineClass(...) to *redefine* an existing class in the workspace, and finally, all classes which are referred to by the class being constructed must exist in the workspace, or Problems will occur (i.e. they will show up on the "Unresolved Problems" page of the Workbench). 2.3 package java.awt 2.3.1 Widgets The following are the known limitations and omissions in the AWT widget peer classes as provided by the VisualAge for Java R1.0 class libraries. Typically, these represent problems which will be fixed in a subsequent release. In a small number of cases they simply describe platform behavior which application programmers should be aware of. * 1.0.2 Events Returning false from handleEvent() (Sun JDK 1.0.2 style events) is not guaranteed to stop event processing by the operating system. * Sun JDK 1.1.1 API missing features All API for the Java AWT peer interfaces are implemented, with the exception of the following two: OS/2 i) java.awt.peer.ComponentPeer print(java.awt.Graphics) 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. Possible workarounds: 1) Use 16-bit color mode. * Color limitation (OS/2 only) On OS/2 Warp 4 in 256 color mode when running 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. (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; * Text events Text events do not allow character modification to be reflected in the text widget. In the JDK 1.1.1 keyChars can be changed in a key event (like KeyPressed), and this is reflected in the text widget. We do not currently support this. * Scrollpane scrollbars lurch 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. * Widget positioning without a layout manager When you create a widget as a child of a shell with no layout manager the x,y of the widget is relative to the top left of the shell in Sun JDK 1.1.1. This means you actually can place widgets under the title bar. In VisualAge (0,0) is considered the top left corner of the client area of the shell. If there is a menu it would be right below the menu bar. If there is no menu it would be below the title bar. * 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 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 for Java they will not open so small that widgets are not visible. They pick a minimum size which makes widgets visible in the Frame. * Clipboard lost ownership notifications Clipboard owners are notified via #lostOwnership() when the clipboard contents change. * Unicode support Unicode characters (and Character to Byte conversion) are not supported. 2.3.2 Graphics The following are the known limitations and omissions in the AWT graphics support as provided by the VisualAge for Java R1.0 class libraries. Typically, these represent problems which will be fixed in a subsequent release. In a small number of cases they simply describe platform behavior which application programmers should be aware of. * Printing is not supported This affects the following APIs: - java.awt.Toolkit.getPrintJob(Frame, String, Properties); - java.awt.Component.print(Graphics); - java.awt.Component.printAll(Graphics); - java.awt.PrintJob class - java.awt.PrintGraphics interface * Unicode characters are not supported Only ASCII characters draw reliably using the java.awt.Graphics.drawString(...) method. * 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 for Java to draw with incorrect colors. We recommend disabling the 'Palette Aware' option of Netscape, located on the Colors page of the Options / General Preferences dialog. * java.awt.Graphics.drawString(...) truncates at the first null character All characters in the string after and including the null character will not be displayed. * 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. * 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. * Arc/oval dimensions Arcs and ovals draw one pixel too large in some situations. This is more likely when the dimensions are even. 2.4 package java.io The following are the known limitations and omissions in the java.io package as provided by the VisualAge for Java R1.0 class libraries. Typically, these represent problems which will be fixed in a subsequent release. In a small number of cases they simply describe platform behavior which application programmers should be aware of. * isDirectory for paths ending in '\' (OS/2 only) OS/2 java.io.File>>#isDirectory() answers false for paths ending with a slash character. * absolute path length limitations The maximum file or directory name length is 254 characters. The maximum path length is 259 characters. Note that these are operating system limitations on Win95 (VFAT/FAT32), OS/2 (HPFS), and NT (NTFS). 2.5 package java.applet 2.5.1 Sound support When an audio clip is being played it may take as much as one second to stop after a stop request is processed on OS2 only. The same delay will occur when a second clip is started if an audio clip is already being played. 2.5.2 Applet security Applets are always 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.6 package java.util 2.6.1 Locale support VisualAge for Java R1.0 provides full support only for the english US locale. Because of this, the locale setting is preset to en_US whenever a program (applet or main) is started. However, there is partial support for several other single-byte locales. It is possible to set the local which your program runs in after it starts using the Local.setDefault(...) method, so for example, displaying the result of executing the following statements in the Scrapbook: java.util.Locale.setDefault(java.util.Locale.ITALIAN); new java.util.Date().toLocaleString() will return something of the form: (java.lang.String) 30-giu-97 10.55.59 2.7 package sun.jdbc.odbc The following are the known limitations and omissions in the sun.jdbc.odbc package as provided by the VisualAge for Java R1.0 class libraries. * OS/2 JDBC-ODBC Bridge At the time of product availability, the Bridge was not included in the 1.1.1 OS/2 JDK. JDBC data access via OS/2 ODBC drivers is not supported in the VAJava for OS/2 development environment. * Stored Procedures While the full JDBC API is fully preserved, access to Stored Procedures via the JDBC-ODBC bridge is not supported in the development environment. Calling Stored Procedures via the bridge will result in an internal Java exception thrown at execution-time, to prevent further program execution. 2.8 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 arguments such as jar cvf test.jar . 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 250 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 causes the other threads to "freeze" when IDE operations are being performed. This approach allows the UI to be more responsive to user actions. However, it also means that if the UI blocks for some reason (and it can), the environment feels 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 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 composition editor. An attempt is made to detect the case where the UI will lock and warn the user. 3.1.2 Terminating threads in the Debugger Caution should be used when terminating threads in the debugger. The standard AWT event dispatch thread for the IDE shows up in the list of available threads, and if it is terminated, AWT widgets which are visible in builder windows may fail to display properly. If this situation arises, exit the environment (saving your workspace is OK) and restart it. 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 y = null; and you go to one new page of the Scrapbook and run: X.y = "abc"; uvm.tools.DebugSupport.inspect (X.y); you get an Inspector showing: "abc" Now go to another new page of the Scrapbook and run: 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, is immediately visible in all Scrapbook pages where these classes are used (and in all associated inspectors, debuggers, and so on). 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.2 Object mutation The fact that the Scrapbook maintains the objects created and still referenced by code run in each page raises the issue of what happens to the existing instances when classes are modified. Typical cases of this kind of change are: - Add a new instance variable (instance slot). - Add a new static slot. - Delete an instance variable. - Delete a static slot. - Change the definition of an instance variable (change its type, for example). - Change the definition of static slot. In VisualAge for Java, when a class definition changes for some reason, all existing instances are *mutated* into instances that conform to the new definition. The behavior of the mutation code is as follows: - Unchanged slots from the old instance have the same value in the new instance. - New (non-static) slots are null, 0, 0.0, or false based on the type (Object, integer valued, float valued, boolean valued respectively). This means that they do not have their initialized value declared by the class, since the initialization code is not run when mutation is performed. - Deleted slots do not exist in the new instances. 3.3 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, but there is already a different thread in the monitor associated with the object, in which 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 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, and that is why IDE is careful about finalizing as much as possible. In order to cope with the constraints above, there are actually two possibilities when finalizers can be run. Whenever the IDE is idle (no user events, no Java threads running) an internal, very low priority thread is launched to execute the finalizers. If this thread is blocked forever and the machine becomes idle again, a new finalizer thread is launched. After running each finalizer they detect if there are more than one low priority finalizer threads, and terminate themselves to bring the state back to having only one low-priority finalizer. At system startup there will be only one finalizer thread running, even if the Workspace was saved in a state with multiple, blocked finalizers. However a low priority thread running finalizers is not good enough. For those applications that generate exceptional amounts of garbage, a more aggressive finalization strategy is required. At runtime, if the system detects that there are too many objects that need to be finalized, a high priority finalizer thread starts right away. While this thread runs, no other Java threads can run (unless the high priority finalizer blocks, etc). In cases where finalization loops forever or blocks, instead of launching more high-priority threads, the execution of each finalizer is bounded by a timeout. If it takes too long to run, the thread is terminated (therefore releasing monitors it might have acquired) and the system goes back to its initial state. If it detects that more finalization has to run immediately, the cycle is repeated. Note that this strategy means that if an application generates garbage intensively and the finalizers take too long to run they will not run to completion. Currently the timout value is set at 5 seconds and cannot be changed by the user. In normal conditions the low priority thread should be enough to run finalizers. When too much garbage is generated, the high priority thread may be run to finalize objects at a higher rate. In cases where finalizers cause deadlocks in the low priority thread you may end up having multiple instances of them blocked, trying to perform finalization (which in this case have no timeout). There is no mechanism to verify how many of these low priority finalizers are running/blocked. If you want to make sure you have only one, you can exit and run the IDE again. As said before, on startup there will be only one. 3.4 JNI 3.4.1 Unsupported JNI API The following JNI API methods are not implemented. Calling any of these will result in a NoSuchMethodError exception. DefineClass ExceptionDescribe FatalError RegisterNatives UnregisterNatives MonitorEnter MonitorExit GetJavaVM This is a known limitation in R1.0 of VisualAge for Java which will be fixed in a subsequent release. 3.4.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.