README for Symantec Visual Cafe Trial Version 2.5 for Java ================================================================= Copyright (c) 1998 by Symantec Corporation. All Rights Reserved. Visual Cafe is a trademark of Symantec Corporation. Other brands and their products are trademarks of their respective holders. ================================================================= Table of Contents: I. Welcome II. Installation Notes, JFC and KL Group III. User Tips IV. Known Problems and Caveats V. Questions and Answers VI. Addendum to Symantec Native Java documentation VII. JFC VIII. JAR Packager IX. Contacting Symantec for Technical Support X. Database Development Edition XI. What's new in Visual Cafe 2.5 XII. What's new and fixed in Database Edition I. Welcome ================================================================= Thank you using Symantec's Visual Cafe for Java v2.5 Database Development Edition (Win95/NT4.0) Trialware! When you are ready to purchase the latest version of Visual Cafe for Java DDE, you have several choices: 1) Visit your favorite computer software reseller or call your favorite computer software mail order house and ask for the latest version of Symantec's Visual Cafe for Java - Database Development Edition. For a complete list of resellers, please see our web page at: http://www.symantec.com/domain/cafe/itools_resellers.html 2) Visit our web site at http://www.symantec.com and click on the Purchase icon at the top of the page. You can purchase and download the product directly or order the box from this web site (boxed product not available online outside USA and Canada). II. Installation Notes, JFC and KL Group ================================================================= Run setup.exe. The installation is smooth and intuitive. As with any new software, please install Visual Cafe for Java in a clean directory. Please note that Visual Cafe for Java 2.5 will not install over previous versions of Visual Cafe. If you are using the FAT16 file system (e.g., Windows 95), the total installed size of Visual Cafe for Java is significantly affected by the cluster size of the hard drive partition used. The total installed size will be substantially larger for drive partitions with 32k clusters (1-2GB drives) than for drive partitions with 16k (513MB-1GB) or 8k (257-512MB) cluster sizes. Note: If you do NOT have ODBC installed on your system, you will see an error message that ODBC32.dll could not be found at the end of installation (after installation of the native runtime),. That DLL is not actually needed by installation; simply dismiss this error dialog and ignore it. Visual Cafe ships with the KL Group full suite of components. They can be found in <"VCafe">\KL Group (where <"VCafe"> is your installation directory). To install these components, drop the JAR file into the Component Library from Windows Explorer. In order to run any of your JDK 1.1.x applets in the Netscape browser, we recommend version 4.04 or later of Netscape Communicator PLUS the JDK 1.1 update available from Netscape at http://developer.netscape.com/software. For easier reading and navigation, the readme has also been provided in HTML format. If you prefer this format, open Main.html, located in the VisualCafe directory, in your favorite Web Browser. Installing and Running the Tour ----------------------------------------------------------------- If you are new to Java development, please take the time to work through the exciting and informative tour that is part of Visual Cafe for Java. This tour will provide you with an overview of some of Visual Cafe's most powerful features. Note: The Database Edition of the tour needs Sybase SQLAnywhere 5.0 installed on the same machine as DBAnywhere. You can download a copy of this database from their web site. What is in the Tour ----------------------------------------------------------------- In the Tour you will learn how to: * Design an applet, build it, and install it in a Web page. * Run the applet in Visual Page. * Design an application, then build, test, debug, and run it. To run the Tour: * Click the Tour Book icon in the Symantec Visual Cafe program group, and follow the Tour instructions. You need to have Adobe Acrobat reader installed in order to read the Tour Book. III. User Tips ================================================================= SC.INI ----------------------------------------------------------------- Visual Cafe uses the CLASSPATH from the sc.ini file in the <"VCafe">\Bin directory. The CLASSPATH in sc.ini, by default, does not contain the environment classpath (i.e.,%CLASSPATH%). Existing projects relying on the environment classpath setting may fail to build. To correct this, you may either add the package directories manually to the sc.ini classpath, add the package directories to the project in project/options/directories, or add the %CLASSPATH% variable to the end of the classpath line in the sc.ini file. Remote Debugging ----------------------------------------------------------------- To pass arguments to the VM for debugging applications: 1. Open a command line window in the directory with your Main class. Execute the line below. XXXX are the arguments you want to pass, e.g. -ms16m, -mx128m. java_g -debug -XXXX symantec.tools.debug.EmptyApp This will print: Agent password=yyyy 2. In the menu go to: Project | Options... | Debugger. Enable Remote Debugging. Set the Host Address to 127.0.0.1. Set the password to the output you got from the command line in step 1. 3. You may now begin debugging normally. 4. When you are finished, do in the command line window to end the session. 5. To start another session, do step 1 to get a new password. Executing & Debugging applets in Netscape Navigator ----------------------------------------------------------------- Visual Cafe now supports the ability to debug Java applets using Netscape Navigator. You must have version 4.04 or later of Netscape Communicator installed on your system to do this. In addition you must have the updated support for JDK 1.1. You may obtain this from Netscape's web site at http://developer.netscape.com/software. Make sure you install the support patch for version 4.03 or greater. In order for Visual Cafe to execute your applets in Netscape Navigator, you need to edit your project options and select "Execute applet in default web browser." You will also need to ensure that Netscape Navigator is configured as your default browser. Netscape will issue some security violation exceptions when you attempt to execute or debug applets from within Visual Cafe. To avoid this security constraint, please add the following options to your prefs.js file: user_pref("unsigned.applets.low_security_for_local_classes", true); user_pref("signed.applets.local_classes_have_30_powers", true); user_pref("signed.applets.low_security_for_local_classes", true); user_pref("signed.applets.verbose_security_exception", true); Notes 1. This file states that it should not be edited by hand. In order to add entries to this file, you must first close all running instances of the Netscape Navigator. You may then edit the file manually. 2. You will see a message in the Java console, "# Security Exception: checkpropsaccess.key". This message can be ignored. For more information on Netscape security please refer to following URLs: http://developer.netscape.com/support/faqs/champions/security.html http://developer.netscape.com/library/technote/security/sectn3.html Executing & Debugging applets in Microsoft's Internet Explorer ----------------------------------------------------------------- In order for Visual Cafe to execute your applets in Microsoft's Internet Explorer, you need to edit your project options and select "Execute applet in default web browser." You will also need to ensure that Microsoft's Internet Explorer is configured as your default browser. The Microsoft browser does not support JNI, the native code required by Sun's JDBC-ODBC Bridge. Microsoft has its own version of the JDBC-ODBC Bridge, which can be obtained by downloading the Microsoft SDK for Java from their web site. Source Control ----------------------------------------------------------------- Visual Cafe supports the ability to manage source files (such as .java) from within the environment through a version control system such as Starbase Versions. Because of the special nature of the project file (.vep), checking this in or out must be done outside Visual Cafe with the project closed. The procedures are: Checking out the project file: 1) Close the project in Visual Cafe. 2) Check-out or get the .vep file 3) Delete the .vpj and .ve2 files from project directory. 4) Now open the project. Checking in a project file: 1) Close the project in visual cafe. 2) Check-in the .vep file NOTES: * The .vep file is a binary file. * It is not recommended that the .vpj and .ve2 files be kept under version control since these are binary files. If you do elect to check them in, make certain that they are not marked read-only. If you do, Visual Cafe will be unable to open the project. * Visual Cafe offers an API to allow checking in of .vep files into the source control. Source control vendors are working on integrating this ability. IV. Known Problems and Caveats ================================================================= This section lists information about known problems: * If you encounter certain errors when starting Visual Cafe or if your tool palette appears empty, delete the following files from \VisualCafe\Bin: *.rps *.reg *.vws Note: Some of the errors are: "No starter templates could be found" "Cannot open local repository" "Cannot open registry" These files are platform-dependent and must be regenerated when switching from one operating system or to another machine. * When using the Parse All Imports option, we recommend that you allow the parser to finish parsing before editing or changing a file. To view the status of the parser, select Messages from the Visual Cafe Window menu. * Java Beans custom painters (e.g. any implementation of PropertyEditor.paintValue will not be called). * Under Windows 95 it is best to drop larger JAR files one at a time. This is a problem with the Java VM under Windows 95, and we expect it to be resolved in version 1.2 of the Java VM. * Visual Cafe uses the code generation model. If a bean has a property editor, the method PropertyEditor.getJavaIntializationString() must be properly implemented. * In some cases, stepping over a statement in a try block that triggers an exception will cause the app to terminate. To get around this, set a breakpoint in your catch block. This breakpoint will get hit and you can continue to debug. * Using the menu item File > Open Page in the Netscape browser to load html pages which contain applets may not work due to various security constraints and security exceptions. We anticipate that these problems will be resolved in future versions of Netscape browser. These html pages normally work in deployment scenarios. * JAR Packager: Dynamically loaded classes forName(...); getResource(...); getBundle(...) do not show up as JAR entries; you must add them manually. If you add them to your project then the JAR Packager will be able to find them. * JAR Packager: There is a bug in the JDK that results in corrupt JAR entries being created in compressed JARs. If you get a Cannot Find File error message when creating a JAR, you may be able to fix it by uncompressing the JAR that you are getting the class from and re-JAR'ing it without compression. * JAR Packager: When entries are coming from another JAR that have Depends-On clauses the dependent classes will also be pulled into your JAR. However, the dependent classes will not be marked as dependents of the entry. * When creating a JAR from a project, you should not create a JAR that has the same name as a JAR that is referenced outside of your project. For example: If you are using a SpecialGrid in c:\SGRID.JAR from a third party vendor in your project, do not create a JAR with the name of c:\SGRID.JAR. * Jar Viewer: The manifest display is limited to 32K of text. To view Manifest files that are larger than 32K, multi select (shift-click) the entries in chunks less than 32K at a time. * Custom property editors: All custom property editors must be serializable; otherwise Visual Cafe cannot initialize the state of the bean. * AutoJAR: During the bean development cycle, it is advisable not to include JARs with dependencies, such as swing.jar, into an "autojar". Manually add the dependent JAR into the class path of the project. * Netscape can crash if a breakpoint set in code for a timer_event is hit while debugging. * Occasionally, when debugging in browsers, actions may lead to an attempt to open source files which are not available. In such cases, simply dismiss the open file dialog box and continue debugging by choosing Debug > Continue or the Run in Debugger arrow button. * Hitting a breakpoint in the run() method of an applet within Netscape Communicator implementing Runnable will cause Visual Cafe to crash. * When debugging in Netscape or Internet Explorer, stepping into code for components will use the browsers' VM. Line-number info will be incorrect, thus the code displayed will not be correct. Low-memory warning on startup ----------------------------------------------------------------- If the sum of your system's available physical memory (RAM) and swap space on disk is below a minimal level when Visual Cafe starts up, a warning dialog will notify you of this condition. It advises you to increase swap space (see below). You have the option of ignoring this warning (answer "No" to the "Quit?" prompt), and proceeding to run Visual Cafe. With light use, you may not experience any problems at all. But with typical use, at some time in the course of your Visual Cafe session you may begin to see "low virtual memory" warnings from the operating system. Typical symptoms of running any complex application with too little available memory are sluggish performance and unstable system behavior. If the warning dialog recommends that you increase swap space by some small amount, such as 2 or 3 MB, increase the minimum swap space on Windows NT or free disk space on Windows 95 by at least 5 MB. For Windows 95, if the option is selected in Settings > Control Panel > System > Performance > Virtual Memory to let the OS manage swap space (this is the default), then available swap space is simply the amount of free disk space; but note that there is no guaranteed minimum: if the disk is full, there is no swap space available. For Windows NT 4.0, the Control Panel is started from the Settings menu item, as on Windows 95. The page file setting that matters most to an application under NT is the minimum page size setting. On a system with 32 MB RAM, the minimum swap space should be not less than 20 MB, and 32 MB is better. A reasonable setting for the maximum is at least twice the minimum. For further details about virtual memory, see the OS Help in the System dialog box. JDK Version Incompatibilities ----------------------------------------------------------------- Symantec Visual Cafe 2.5 supports version 1.1.5 of the Java Development Kit from Sun Microsystems. Please see http://www.javasoft.com for information regarding specific OS incompatibilities with the JDK. Java Beans ----------------------------------------------------------------- When a bean has multiple types of event listeners that implement event types having the same name, Visual Cafe will generate code to handle that event type only for the first listener. If you select that event type for the second event listener, it will generate the code for using that event type from the first listener. Converting Visual Cafe 1.0x projects ----------------------------------------------------------------- When converting a 1.0 project that used a card layout with unnamed cards, the backparse will fail. To work around this, you must manually edit the add() statements for those cards without names. It is important to note that JDK 1.1 has disallowed unnamed cards in a card layout; the same code would also fail at runtime. Native compiler ----------------------------------------------------------------- When using 3rd party classes (and components) in a native code compiled project, you must do one of the following two tasks: o include the source for these classes as part of the project o pre-compile the source for these classes to a native DLL and have the import library for that DLL listed in the Libraries section of the Compiler Project Options. Native compiler and Visual Cafe 1.x and Cafe 1.x ----------------------------------------------------------------- If the sj.exe from Visual Cafe 1.x or Cafe 1.x is specified in the path before Visual Cafe 2.5, an invalid flag error -link will result when using the native compiler. To avoid this error, make sure that the sj.exe from Visual Cafe 2.5 is specified in the path first. Z-order of heavyweight components ----------------------------------------------------------------- Z-order of heavyweight java.awt components is undefined in JDK 1.1.5. As of this writing, the current JDK 1.1 versions of Internet Explorer and Netscape both use the same z-order. However, this may not be true in future versions of either browser or of other Java execution environments. Lightweight component behavior between JDK 1.1 and 1.1.5 ----------------------------------------------------------------- Between JDK 1.1 and JDK 1.1.5, behavior of lightweight components has changed in many ways (primarily to fix problems in the initial implementation). If you run your program in an environment with an implementation of lightweight components that is earlier than the implementation in JDK 1.1.5, behavior of the lightweight components may vary. Incremental Debugging ----------------------------------------------------------------- Changes made to static variables require a restart of the application or applet before they will take effect. Similarly, changes made to methods in the active call chain will require a restart of the method before they can take effect. In both cases a dialog will present you with this choice. When using incremental debugging, changes made do not take effect until the next time the modified method is called. This means if you modify a method that runs only once during the execution of your applet or application (e.g. init for an applet, run for a thread, a constructor for an already loaded class, etc.) AND that method has been executed, then you will need to restart the applet or application. The debugger does not always detect this case and you may not get a prompt to restart. Also, if you modify static initializations, then you will need to restart the app as static initialization is done once the class is loaded. The environment does detect this case and will present the user with the appropriate prompt. See the topic "Incremental debugging features" in the online help files for more features and expected behavior using incremental debugging. V. Questions and Answers ================================================================= How do I register Starbase Versions? ----------------------------------------------------------------- Versions 2.0 provides intuitive version control for individuals and local groups of developers using Windows 95 and Windows NT. Register for the full version at http://www.starbase.com/verreg.htm or phoning (714) 442-4460 CODE: VISUALCAFE97 ----------------------------------------------------------------- How do I distribute my applet on a Web server? ----------------------------------------------------------------- The easiest solution is to JAR your applet by choosing the menu item Project > JAR... The resulting JAR file can be specified in your HTML file by using the ARCHIVE tag. For example, if you create an applet with the name of foo and from that project you create a JAR file with the name of bar.jar, then within the HTML file you would specify: Not all browsers currently support the use of .jar files. To address this you can create the JAR and then "unJAR" the file. To unjar your previously created .jar file go to a DOS command line and enter the command: \VisualCafe\Java\Bin\jar.exe xf jarfilename.jar The resulting directory tree of supporting class files can then be transferred via FTP to your Web space. Note: the manifest.mf file is not needed to deploy. ----------------------------------------------------------------- What is the "Execute applet in default HTML viewer" option in the Project Options dialog? ----------------------------------------------------------------- The "Execute applet in default HTML viewer" option, located in the Project Options dialog box, allows you to view your applet in your favorite Web browser, instead of the AppletViewer, when executing from the Visual Cafe environment. ----------------------------------------------------------------- Will Visual Cafe recognize my own source code? ----------------------------------------------------------------- When adding controls directly within the source editor, we recommend that you adhere to the same coding style as generated by Visual Cafe. This will allow controls you add to be displayed in the form editor. Controls you add outside Visual Cafe's tags (which are comments that indicate where Visual Cafe generates Java code for the form editor) will not be displayed in the form editor and will not be affected by automatic code generation. If you are adding controls within Visual Cafe's tags in the source editor, you should adhere to Visual Cafe's coding style. Otherwise, you can add controls outside of Visual Cafe's tags using your own coding style. ----------------------------------------------------------------- When I open a project in the Form Designer, the dialog for Dial Up Networking appears. If I log on, all is well. If I cancel, Visual Cafe "hangs" for several minutes. ----------------------------------------------------------------- The use of relative URLs (for example, IMAGES/test.gif) can cause this behavior on some systems. To avoid it, use absolute URLs (for example, file://C:/.../PROJECT/IMAGES/test.gif) during design time and then switch to relative URLs for deployment. ----------------------------------------------------------------- How can I increase the size of a form within the Form Designer larger than the resolution of my screen? ----------------------------------------------------------------- A form in the Form Designer is limited to the resolution of your display. If your display system is capable, increase the its resolution to allow more information on the screen such as changing from 800x600 to 1024x768. If your display system supports the use of a "viewport" or "virtual desktop" where only a portion of the desktop is displayed on the monitor, the form size can be increased to the size of the desktop. Note that this has not been thoroughly tested with all display systems and is a function of your video card driver. ----------------------------------------------------------------- I would like to distribute my applications created with Visual Cafe along with the Symantec Virtual Machine. Do I need to obtain a license to distribute the Symantec JIT/JVM? ----------------------------------------------------------------- Yes. Please email jit-licensing@devtools.symantec.com. The .class files included with Visual Cafe are freely distributable. JavaSoft has licensed the Symantec JIT for redistribution in the JRE. The JRE is Sun's Java Runtime Environment and is freely redistributable. Please visit http://www.javasoft.com for more specific information regarding the JavaSoft JRE. ----------------------------------------------------------------- I place a component on top of another and yet it seems to disappear underneath the other component. ----------------------------------------------------------------- The new JDK supports both lightweight and heavyweight components (see the online help files for a brief discussion of what constitutes a lightweight component). Lightweight components will always be drawn behind heavyweight components. For example, if you drop a java.awt.Canvas component onto a form and then drop a Label3D component on top, the Label3D still is drawn beneath the Canvas because the Label3D is lightweight and the Canvas is heavyweight. VI. Addendum to Symantec Native Java documentation. ================================================================= a. What is covered in this addendum b. Resource binding c. Differences with bytecode d. Restrictions e. Library lookup f. Debugging Native Java Runtime g. Changes to the Native Java Runtime h. Changes to the Native Java Compiler a. What is covered in this addendum ----------------------------------------------------------------- This addendum discusses items that couldn't be covered in other documentation due to time constraints. The primary topics discussed are the resource binding feature and limitations present in the current implementation of Symantec Native Java. b. Resource binding ----------------------------------------------------------------- You can bind your resources (e.g. gif files) directly to your DLL or EXE or you can leave them on disk. For an example of how to bind resources refer to the sample 'resource'. c. Differences from bytecode ----------------------------------------------------------------- 1. Applets Native Applets are not supported. Support for running native applets would have to be provided by the browser vendor. 2. ClassLoaders and dynamic class definition The default native classloader will load its classes from the executable or DLLs directly. Custom classloaders are not supported in native Java. Specifically the method ClassLoader.defineClass(..) will throw an exception if used. The reason for this is the defineClass(..) method allows the user to load a class from an array of bytecode. The native implementation understands x86 code only; it does not understand bytecode. 3. (Custom) Security Managers Security managers are meant to provide security control for access to several class attributes (properties and methods). Currently this is not supported in native Java, as it comes with a lot of runtime overhead. Also this feature is mainly needed for bytecode, so browsers can control what level of access downloaded Java bytecode will get to the local system. Native Java is meant for applications only, and will provide you with the fastest possible executables instead. d. Current Restrictions ----------------------------------------------------------------- 1. JNI The native Java implementation provides complete support for the Java Native Interface (JNI). Please refer to the samples for any additional information. Currently, JNI Global references don't register themselves with the garbage collector. The reference functions simply return the jobject value that was passed in. 2. Byte code to x86 code conversion. We currently don't support the conversion of byte code (.class files), to x86 code (native code). This means that in order to use 3rd party classes you will need to have the source for them, or you will need a DLL and import libraries from the vendor of the classes. An enhancement may be made in the future to support this functionality. 3. GEO components. The GEO package included in the symbeans components library was not included in the symbeans.dll; consequently, the user cannot use the GEO components in building native applications. e. Automatic library lookup ----------------------------------------------------------------- When using a native DLL, under most conditions you will need to link with the corresponding import library of that specific DLL. The import library name will have to be explicitly specified in the command line or if one is using the Visual Cafe IDE, it has to be added to the library listing under the project options. As an added feature, the native compiler will add information to class files that were compiled and linked to DLLs. So, when these class files are used as class definition lookups during a native compilation of another Java source code, there is no need to explicitly specify the import library name during that compilation. The import library will be found automatically as long as it is located in the directory where the LIB environment variable specifies (e.g. C:\VisualCafe\Lib). This feature does not invalidate the class files as legal bytecode class files specific to your installation. f. Debugging Native Java Runtime ----------------------------------------------------------------- The default installation of Visual Cafe creates shortcuts in the start menu for switching between debug and release version of the Native Java runtime DLLs. In order to step into the runtime source while debugging, you must first switch to the debug versions of these DLLs. These DLLs reside in your windows\system (system32 for Windows NT). These Debug DLL files and redistributable DLL files can also be found on the Visual Cafe installation CD under VCafe. g. Changes to Native Java Runtime ----------------------------------------------------------------- * snjres tool now exits with error code of 0 if there are no problems. The exit code was random before. * snjreg tool crash problem fixed. * System.getProperty( "java.version" ) now returns "1.1.4" instead of "Unknown Version". The following symbeans components are affected by this: symantec.itools.awt.TreeView symantec.itools.awt.MultiList * JNI bug fixed - passing arguments to methods from C/C++ code. * Added internationalization support DLLs. Groupings are based upon locale_str.h. snjint - additional internationalization support classes. snj_ext - Extra encoding classes that don't have an associated locale in java\text\resources and that are not platform specific. ( EBCDIC, Taiwanese ) snj_mac - Encodings for the Macintosh platform. snj_la - Catalan, German ( Germany, Austria, Switzerland ), English ( Canada, GB, Ireland ), Spanish, Italian, Dutch snj_ibm - Misc IBM encodings snj_fr - French for all supported locales. ( France, Belgium, Canada, Switzerland ) snj_is - Icelandic snj_sv - Swedish, Norwegian ( Nynorsk ), Danish, and Finnish snj_pt - Portuguese snj_ar - Arabic snj_ru - Belorussian, Bulgarian, Macedonian, Russian, Serbian, Ukranian snj_pl - Czech, Hungarian, Polish, Romanian, Serbo-Croatian, Slovak, Slovenian, Albanian snj_el - Greek snj_et - Estonian, Lithuanian, Latvian, Lettish snj_iw - Hebrew snj_ja - Japanese snj_ko - Korean snj_tr - Turkish snj_zh - Chinese snj_tw - Taiwanese The import libraries for each group name ends with .lib and the DLLs are in the form of snj*11.dll * Added native JDBC-ODBC bridge and other sun support classes. * Garbage collection bug fixed - different problems with garbage collecting static objects. * Linked/bounded resource bug fixed - problem with the call Toolkit.getImage(URL) when resource is linked/bounded into the application. * MediaTracker bug fixed - problem with loading more than 10 resources using MediaTracker. * Fixed initialize problem that broke output streams on Japanese ( as well some other ) systems. * Several changes to reduce the number of 'C' runtime file handles consumed. * AWT bug fixed - problem with using AWT components in NT4.0 with Service Pack 3 installed and when display is set to 24 bit colors. * Key input events in AWT bug fixed - problem with inputting certain key combinations like the 'umlaut' character in AWT. * Thread.stop() now works in most cases. When Thread.stop() is called, a ThreadDeath exception gets noticed when the thread calls sleep() or yield(), or if the thread passes into 'C' code and tries to come back. h. Changes to the Native Java Compiler ----------------------------------------------------------------- * Garbage collection bugs were fixed. In certain rare cases, compiler-generated objects (members of statically allocated objects) would be incorrectly garbage collected, yielding runtime null-pointer exceptions. As a result of these changes, compilers of version 210.184 and later require the use of runtime DLLs version 113.044 or higher. * Two native floating point code generation bugs were fixed. One regarded extreme values and integer conversion, and another regarded expressions involving sign changes and common subexpressions. * All reproducible cases of compiler-reported internal errors have been addressed. * Memory usage of the compiler is now more efficient. It will now use less memory when compiling large projects. * Fixed bug in producing proper names for overloaded native methods. VII. JFC ================================================================= Contents: 1. How does Visual Cafe support Swing? 2. Deploying your Applet with Swing components. 3. Known Issues and Workarounds. 4. How to install a new version of Swing. 5. Future support for Swing. 6. Swing resources. ***** 1 ***** How does Visual Cafe support Swing? ----------------------------------- We have done several things to make Swing work within Visual Cafe 2.5 that are not in previous releases of VCafe. * The code generation for components dropped onto a bean that implements RootPaneContainer such as JFrame and JApplet will produce getContentPane().add(xxx) * You can create a JMenu Hierarchy by drag and drop. For example, drag a JMenuBar onto a JFrame, then a JMenu onto the JMenuBar, and finally a JMenuItem on the JMenu. If you want to use the menu editor, you can use the standard JDK Menu components and add them to a JFrame. * Swing is part of the default parse information. This means you can view Swing in the Class Browser, Hierarchy Editor, Class Wizard, etc. * The Jar Utility can pull in the Plugable Look and Feels that you specify. * We made property editors for properties that can be set with the Swing constants. ***** 2 ***** Deploying your Applet with Swing components ------------------------------------------------------- There are a couple ways to do this: 1. Have the target audience use the Project Java Activator (see Resources below). This runs applets as a plug-in in Communicator 3.0+,and Explorer 3.0+. The nice thing about this is that swingall.jar is already on the users machine. You just provide the classes needed that aren't in swing on the server. 2. Include an ARCHIVE tag with two jars. One of them is "swingall.jar", and the other one is a jar with all the non-swing classes. Note that Communicator doesn't support the ARCHIVE tag, and you'll have leave your classes unjarred on the server. This can lead to a long download time as you can imagine. Also, the user will need Explorer 4.0+ or Communicator 4.03+ with the JDK 1.1 patch. 3. The target audience can have a copy of swingall.jar on their machine and in their classpath. Also, the user will need Explorer 4.0+ or Communicator 4.03+ with the JDK 1.1 patch. When you are ready to deploy your applet, you can use the JAR Utility to create a JAR with all the necessary swing classes. ***** 3 ***** Known Issues and Workarounds ---------------------------- * Code is not generated for adding components to JTabbedPane, JSplitPane, JTree, etc. For example, when you drop a JPanel on a JTabbedPane, code gen for addTab() won't be generated. You add this code after the //{{INIT_CONTROLS block. * When using a JPanel on an Applet (not JApplet) events are not propagated in the AppletViewer or Communicator. * JSlider doesn't initially paint correctly. If you manually call setValue() after the //{{INIT_CONTROL block it will paint properly. * The Win32 DLLs for swing are not included. * When dropping a JComboBox on the Form Designer, you will get an error message. All this means is that the index needs to be set. * The JDialog icon is not included. * There are cases where compressing your jar will fail with Swing components. JAR your project uncompressed and it should complete properly. * If you install Visual Cafe without the JFC option, then at a later time run the installer to install JFC, you will need to manually insert swingall.jar into the component library. ***** 4 ***** How to install a new version of Swing ------------------------------------- When a new version of Swing comes out, follow these steps to integrate it into Visual Cafe. 1. Exit Visual Cafe if it is running. 2. Replace the /<"vcafe">/Jfc directory with the new version of Swing. 3. Unzip the source (src.zip) into /<"vcafe:>/Jfc retaining the directory structure. 4. In /<"vcafe">/bin delete "jdk.vep" and "jdk.ve2" 5. Restart VCafe. 6. When prompted to reparse the JDK, select Yes. This will take a few minutes. 7. After parsing is finished, start a new JFC Applet project, and open the Class Browser. You should be able to see the Swing packages and methods. ***** 5 ***** Future support for Swing ------------------------ We are currently working on adding additional support for Swing within Visual Cafe. We also welcome your suggestions which you can reach us on the Visual Cafe newsgroups. Information can be found at the end of this readme. ***** 6 ****** Swing resources --------------- Project Java Activator: Visit http://developer.javasoft.com They tell you how to download it and to put the correct tags in your html file to use it. Swing: Check out http://java.sun.com/products/jfc/swingdoc-current/index.html for all the information about Swing Sun has to offer. VIII. JAR Packager ================================================================= 1. Overview of features. 2. JAR Packager options. 3. Files generated by the JAR Packager. 4. Known Bugs. 5. What to do about bugs. 6. Feedback. 7. General Issues 1. Overview of features Here is a basic description of the JARing process. 1. The project is built 2. The JAR Packager is invoked. 3. It calls sj -depend x.dar on your Java source files to determine the dependencies. 4. If you selected JAR... the dependencies are displayed. If you selected Auto JAR goto step 12. Auto JARing selects the checkbox in step 11 to true. 5. For non-java files that are part of your project (eg: .gif) the package is guessed based on your CLASSPATH. 6. You can exclude selected files via the Remove Files button. 7. You can remove entire JAR/ZIP files or entire packages as well as recover removed files via the Manage Files... button. 8. You can set what classes are Java-Beans or Design-Time-Only via the check boxes (see the Java Beans spec at http://www.javasoft.com for more info). 9. You can set the Depends-On clause for each entry as required via the Manage Dependencies... button (see the JAR spec at http://www.javasoft.com for more info). Depends-On: should be used for any dynamically loaded classes or any resources (resource bundles, images, etc). 10. If you are creating a JavaBean that you want added to the Visual Cafe Component Library you should select the Add To Library checkbox. 11. Once you have set up your JAR the way you want you can press OK and the JAR will be created. 4a. If you are creating a Debug build then, by default, all dependent files that are in archive (JAR/ZIP) files are not included in the JAR. This can be over-ridden with the IgnoreArchivesInDebug. 4b. If you are creating a Final build then, by default, all dependent files that are in archive (JAR/ZIP) files are included in the JAR. This can be over-ridden with the IgnoreArchivesInRelease. 4c. If you are using Swing classes and you are including files from archives (4a, 4b) some additional steps are performed: 4c.1. if you have the Swing.include flag set to false then no Swing classes are included. Goto step 5. 4c.2. if you selected Project|Auto JAR goto 4c.4 4c.3. if you have the Swing.promptForLAFs flag set to true a dialog is shown allowing you to select the Look And Feels to include in the JAR. Goto 4c.6 4c.5 if you have the Swing.promptForLAFs flag set to false the Swing.defaultLAFs Look And Feels will be selected. 4c.6 the selected Look And Feels are added to the dependency list. 2. JAR Packager options The JAR Packager has a number of configurable options. At the moment you must configure the options by hand - We are working on a way to set these through the JAR Packager GUI. ***IMPORTANT*** The following directions are case sensitive. If you do not enter the information with the exact case given the Options will not work. *************** If you are using Visual Cafe 2.1 - Copy the sample Bundler.properties file to the VisualCafe\java\lib directory. - This will give you : VisualCafe\java\lib\Bundler.properties You can get a list and description of the options by going to a DOS prompt and typing : java symantec.itools.vcafe.Bundler -options You can get the current settings of the options by going to a DOS prompt and typing : java symantec.itools.vcafe.Bundler -settings To set a particular option (eg: Debug) all you need to do is edit the Bundler.properties file appropriately. For example, to set the Debug option you would add the following line to the Bundler.properties file: Debug=true You do not need to provide settings for each option. If you do not set a value (or do not provide a Bundler.properties file) the JAR Packager will use the default for all unset options. Description of options: A default Bundler.properties file is included please look at it for explanations of the options. 3. Files generated by the JAR Packager The JAR packager always generates the following files: - .bundler A serialized file used for storing options (like the JAR Name, compression, etc) between runs. The JAR Packager can keep some other files around (by using the KeepFiles flag): - bundler.rsp The files passed to the compiler to compute the dependencies. - bundler.dar The list of dependencies 4. Known Bugs - If you get an error saying that the JAR Packager cannot calculate the entries and to make sure that your project is buildable do the following: - Project|Build - if that is successful then look for any warnings in the output window - either fix the warnings or turn the TestSJOutput to false - Abstract Classes with BeanInfo files are marked as JavaBeans - this will cause a warning on introspection. - Given: package1.X.class package1.XBeanInfo.class package2.X.class Both package1.X and package2.X are marked as Beans. 5. What to do about bugs If you encounter a bug in the JAR Packager please follow the directions in the "Technical Support" section unless the Bug is an "Internal Exception" dialog. If you get an "Internal Exception" Dialog please do the following: - Turn off the JIT (Just In Time compiler) (add JAVA_COMPCMD=DIS to the VisualCafe\bin\SC.INI file) - Re-start VisualCafe - Turn on the Debug option (Debug=true) - this will generate a C:\Bundler.log (you can change the name of this file via the "DebugLog=" option). - Post the ***ENTIRE*** contents of the DebugLog file to the symantec.support.devtools.windows.vcafe4java.Deployment deployment newsgroup. 6. Recent Bug Fixes - Improved Swing support. - IgnoreArchives flags for Debug/Final builds. - Some errors that were not getting logged now are. - Added TestSJOutput flag. - Fixed bug with a space in the output dir. - Sped the JARing up from the slowdown in 3.0.0. 7. General Issues Dynamically loaded classes forName(...); getResource(...); getBundle(...) do not show up as JAR entries; you must add them manually. There is a bug in the JDK that results in corrupt JAR entries being created in compressed JARs. If you get a Cannot Find File error message when creating a JAR, you may be able to fix it by uncompressing the JAR that you are getting the class from and re-JAR'ing it without compression. When entries are coming from another JAR that have Depends-On clauses the dependent classes will also be pulled into your JAR. However, the dependent classes will not be marked as dependents of the entry. When creating a JAR from a project, you should not create a JAR that has the same name as a JAR that is referenced outside of your project. For example: If you are using a SpecialGrid in c:\SGRID.JAR from a third party vendor in your project, do not create a JAR with the name of c:\SGRID.JAR. IX. Technical Support ================================================================= Before contacting Technical Support, look at the Knowledgebase and FAQ areas listed below as these contain solutions to the most common customer problems: 1. Knowledgebase The online Knowledgebase is a searchable database of technical problems and solutions. http://service.symantec.com/knowbase/index.html 2. FAQs The Frequently Asked Questions section provides a list of commonly asked questions and clear answers. http://service.symantec.com/faq/index.html 3. Newsgroup Support a) NNTP Access Free newsgroup support is available for as long as you own Visual Cafe on Symantec's news server at service.symantec.com. Please refer to the news groups under: symantec.support.devtools.windows.vcafe4Java.* Note: your company's firewall may prevent you from accessing this NNTP service. b) HTTP Access You can also access the Newsgroups via HTTP from the "Ask a Tech" facility on the Service and Support section of the Symantec Web site or via DejaNews (see below). http://service.symantec.com/news/index.html c) Newsgroup Archives The Newsgroup archives can be searched on DejaNews at http://www.dejanews.com 4. Telephone Support For help with installation and general usage during the first 90 days of your purchase, and for a charge thereafter, you may call Technical Support free of charge at (541) 465-8470. International Customers can find their local tech support number from the web site at: http://service.symantec.com/global_index.html 5. Bug Reports Please send bug reports to: techsupp@devtools.com 6. Replacement Password/ID a) If your User ID and Password become inoperative, please send e-mail notification to Customer Service at cafe@symantec.com with your name, address, daytime phone number, ID and password. Please type "Visual Cafe" in the subject field. We will respond shortly thereafter. b) If you have lost your Visual Cafe ID set, please send notification to Customer Service at custserv@symantec.com In the event that your information does not appear in our registration database, we will provide additional avenues for verification of ownership. 7. Replacement CDs For CD purchases or damaged disks please call Customer Service at 800-441-7234. International Customers can find their local Customer Service number by calling their local Symantec office listed in the manual and Help files or from the web site at http://www.symantec.com/custserv/index.html X. Database Development Edition ================================================================ For information on new features for Visual Cafe for Java Database Development Edition, see the What's New.pdf on the CD. Major fix ========== We fixed an problem with optimistic concurrency whereby the result set was not in sync with the database. There was no data corruption in the database but the user did not see the refreshed data till Restart was pressed. This problem only occurred in the JDBC API that was included in Visual Cafe Database Development Edition 2.1. Change in Getting Started Instructions ============== There is a correction to the instructions in the Getting Started manual. On page 6-17, under the heading entitled "Setting initial record positions," step 8, add the following lines of code rather than the single line listed in the documentation. DBA_registrationNavigator.restart(); DBA_registrationNavigator.insert(); Package_ID2.setText("780"); Number_in_Party.setText("0"); Total_Cost.setText("0"); Note: To complete the tour, Visual Cafe for Java - Database Development Edition normally requires the SQL Anywhere database. We do not include this database in the trial version of the product, but a trial download is available from the Sybase web site. Applet reload problem ===================== Previously we have seen problems with applets freezing if a user tried to reload an active applet. This problem has been addressed. If you are using the AppletViewer to reload an active applet, please add the following line of code in the applet before the init section: symantec.itools.db.beans.binding.databus.DataBus.initialize(); You only need to add this line if you are using the DBAW API. Instantiating Query Navigator in Master Detail scenario ======================================================== The master query navigator has to be instantiated before adding the detail. Migration of old Applets ======================== If you have been using a previous version of dbANYWHERE API, please note that the constructor of symantec.itools.db.pro.Session has been changed to include an additional parameter: public Session (String serverURL, boolean designtime) The additional parameter specifies whether the Session object is instantiated at design time or run time, and is required to support the Symantec Visual Cafe development environment dbDE 2.1. In Visual Cafe dbDE 2.1, the Migrate utility will automatically converts your existing projects to use the new Session constructor or new Session(serverURL,false) if using JDK 1.0.2 Migrating an 1.0e project with list component in the current environment will delete the constructor and databinding property for the List. Please add the constructor and set databinding property for this component in the source code. Executing & Debugging applets in Netscape Navigator =================================================== Netscape Version ------------------------ Visual Cafe now supports the ability to debug Java applets using Netscape Navigator. You must have version 4.04 or later of Netscape Communicator installed on your system. In addition you must have the updated support for JDK 1.1. You may obtain this from Netscape's web site at http://developer.netscape.com. Make sure you install the support patch for version 4.03 or greater. Enabling Execution/Debugging in Netscape Navigator -------------------------------------------------- In order for Visual Cafe to execute your applets in Netscape Navigator, you need to edit your project options and select "Execute applet in default web browser." You will also need to ensure that Netscape Navigator is configured as your default browser. Avoiding Security Violations ---------------------------- Netscape will issue security violation exceptions when you attempt to execute or debug applets from within Visual Cafe. To avoid this security constraint, please add the following options to your pref.js file: user_pref("unsigned.applets.low_security_for_local_classes", true); user_pref("signed.applets.local_classes_have_30_powers", true); user_pref("signed.applets.low_security_for_local_classes", true); user_pref("signed.applets.verbose_security_exception", true); Notes 1. This file states that it should not be edited by hand. In order to add entries to this file, you must first close all running instances of the Netscape Navigator. You may then edit the file manually. 2. You will see a message in the Java console, "# Security Exception: checkpropsaccess.key". This message can be ignored. For more information on Netscape security please refer to following URLs: http://developer.netscape.com/support/faqs/champions/security.html http://developer.netscape.com/library/technote/security/sectn3.html The Netscape browser will execute and debug applets that use the JDBC-ODBC bridge. In order to deploy these applets, users may need to purchase the JDBC-ODBC solution package from Intersolv. For further assistance please refer to Intersolv's home page. Microsoft's Internet Explorer Browser ===================================== Applets can be debugged and executed, within visual cafe environment, in Internet Explorer. Deployed applets can also be downloaded in Internet Explorer. The Microsoft browser does not support JNI, the native code required by Sun's JDBC-ODBC Bridge. Microsoft has its own version of the JDBC-ODBC Bridge, which can be obtained by downloading the Microsoft SDK for Java from their Web site. General Web Browser Information =============================== Please remember that ODBC is not acceptable for untrusted applets. It requires access to local ODBC configurations, as well as the ability to load the native code for the ODBC manager and for ODBC drivers. The dbANYWHERE Server may be used for ODBC access when a three tier deployment scenario is required. dbANYWHERE Server Issues ======================== NOTE: Please refer to the dbANYWHERE Server readme.wri file for information on features, etc. Multiple select statements -------------------------- Sometimes the dbANYWHERE Server shows multiple select statements in its log window when a single operation is being performed. This duplication of messages can be ignored, as they do not indicate that the database has actually been called multiple times. Informix float datatype ----------------------- Informix supports float data types with a maximum scale value of 6. Attempting to use a greater scale value will result in rounded data values. This in turn causes update statements to fail their integrity constraints, thereby disallowing updates. DML operations are not currently supported ------------------------------------------ The following datatypes are not supported in DML operations: o Informix Longvarchar o MSSQLServer and Sybase SQLServer Longvarbinary (during insert operation only) o SQLServer smallmoney and smalldatetime Microsoft Access Bugs --------------------- In Access every query navigator would require a different record definition bean which in turn would need a different jdbc connection bean. Access does not support != (not equal to operator) for join operator. If you are working with Microsoft ODBC driver please be aware that you need to add square brackets [ and ] around the path name. For Example, if Access is a directory under an office folder in C drive and the database you are accessing is named foo in this directory. The record definition object for any table from this database would be named as C_office_Access_foo_tablename_Record where tablename is the name of the table you are trying to access. There is a method in this object called: setTableName("C:\\Office\\Access\\foo.tablename"); Add [ ] to enclose the path name so that this method would be setTableName("[C:\\Office\\Access\\foo].tablename"); Currently, we do not support column names or table names with spaces in them. The workaround for this is to add [ ] around the column name or table name in your record definition source code. If the Table Name property in the record definition object is clicked you may get a "data source not found" error. Access does not let the user change the boolean data value from No to Yes, while changing from Yes to No works successfully. (The Access boolean datatype maps to a Bit data type in Java and is typically displayed with a checkbox component.) Views cannot be chosen through the project wizard but can be dropped from the dbNAVIGATOR. This is due to a limitation in Access's ODBC driver. Oracle number data type ----------------------- Number data type with scale 0 is displayed as a decimal instead of an integer. Values entered to the right of the decimal point will be truncated, which may be confusing to some end users. Informix ODBC driver from Intersolv and transactions ---------------------------------------------------- Currently the dbANYWHERE API does not support Informix databases when using Intersolv's ODBC driver, if the database is created to NOT support transactions. Informix databases that are configured to support transactions will be supported via the dbANYWHERE API. NOTE: Use of the Intersolv ODBC driver to Informix is always supported when using the JDBC API through the dbANYWHERE Server. Development Environment Issues ============================== ArrayOutOfBoundException while dragging and dropping QueryNavigator on a form ------------------------------------------------------------------ Dropping the QueryNavigator object from the component palette onto an applet will cause the QueryNavigator object to be added to the end of the INIT block, within the source code. This results in code which will not compile. To eradicate this problem, you must either move the QueryNavigator above the component panel in the project window or move the code so that the navigator is instantiated before a component calls for data from that navigator. List and Listplus ----------------- There are two components with similar names, List and Listplus. The Listplus component is designed to work with the JDBC API and the List component is designed to work with the dbANYWHERE API. To reduce confusion, we have exposed the Listplus component (for JDBC) in the component palette. Meanwhile, the List component (for PRO) is available in the component library under dbAWARE components. DBTimestamp ----------- The default value that will be stored in the database for a timestamp datatype, using the DBTimestamp component is 10:10:10. The format of this data is HH:MM:SS. If the table that this component is based on is empty then please add DBTSTAMP1.setType(symantec.itools.db.awt.DBTSTAMP.DATE or DBTSTAMP1.setType(symantec.itools.db.awt.DBTSTAMP.TIME or DBTSTAMP1.setType(symantec.itools.db.awt.DBTSTAMP.TIMESTAMP) Where DBTSTAMP1 is the component name and DATE,TIME,TIMESTAMP are the JAVA mapping of the data type. XI. What's new and fixed in 2.5 ================================================================ 1. Fixed icon failure in Bean Wizard 2. Fixed package support for Bean Wizard 3. Fixed slow response times in form designer and parser 4. Fixed crash when closing a running project 5. Fixed crash when editing in class browser & focus is changed 6. Fixed multiple JAR Packager issues 7. Fixed project directories settings failure to save on reopen 8. Fixed crashes on non-intel based processors 9. Fixed GBL ipadx\y setting resetting after project close\open 10. Fixed incorrect boolean property codegen in Bean Wizard 11. Fixed incorrect codegen when overiding setSize in Bean Wizard 12. Added online registration to installer 13. Added better exception handling to treeview 14. Added sort by column headers in file view 15. Fixed crash when setting URLs for multiple components 16. Fixed many spinner issues 17. Added support for Multidimensional anonymous arrays 18. Fixed Class browser not showing nested classes 19. Fixed crash in Brief mode when column copy & paste 20. Added RAD on\off 21. Added UUI 22. Fixed codgen of bound and constrained properties 23. Fixed Calendar component to return 4 digit year - year 2K 24. Fixed crash in advanced searching - year 2K 25. Added deselect node to treeview 26. Added isHidden for treeNodes in treeView 27. Fixed parse imports checkbox to toggle XII. What's new and fixed in Database Edition ================================================================ 1. Generating Master Detail scenario through the wizard for JDBC API 2. New Tour using JDBC API 3. Year 2000 compliant 4. Fixed the frame freeze problem for applications with multiple instances of detail frame 5. Fixed problems with navigation while trying to reload applet in browser 6. Fixed problem with displaying images in Internet Explorer 7. Improved performance for data navigation 8. Fixed bugs in grid to improve performance in DBAW API 9. Fixed problems with save method for enhanced support to databases that do not support transactions 10. Fixed problems with combo box lookup property 11. Fixed the checkbox * * * * * Thank you for using Visual Cafe 2.5 for Java. We are confident that it will enhance and improve the productivity of your development efforts. Sincerely, The Symantec Internet Tools Team