JBuilder 3 Hints and Tips

This document contains a subset of known problems, workarounds and tips for JBuilder 3 Foundation, Professional and Enterprise Editions. Therefore, some items mentioned may or may not apply to your edition.

For the latest information on JBuilder, please see the JBuilder 3.0 section at: http://www.borland.com/jbuilder/.

The online Help is the most complete and updated version of the product documentation. To display the online Help, choose Help | Help Topics. See the JBuilder technical publications page at: http://www.borland.com/techpubs/jbuilder and select the appropriate link.

Table of Contents

General
Install
Editor
Components
Debugger
Designer
Wizards
Compiler / Build System
Runtime
JDataStore / DataStore Explorer
Samples
Performance
International

General

The QuickStart topic in the online help is a good place to get info on what's new in JBuilder 3.0.

There are features in JBuilder 3.0 -- Enterprise edition to support Java 2 Enterprise Edition (J2EE) functionality.  J2EE is not yet finalized, so these features are currently disabled in JBuilder 3.0, Enterprise Edition. To enable these features (e.g, Enterprise JavaBeans support), you must install the J2EE libraries. J2EE can be downloaded from Sun's web site at:

http://java.sun.com/j2ee

Once J2EE has been downloaded and installed locally, edit the jbuilder launch file (shell script or batch file) and add the j2ee.jar to the classpath. This will enable the J2EE files to be found by JBuilder, which will enable the Enterprise features that use J2EE.  You will also need to create a library for J2EE in JBuilder so these classes will become available to your project.

JBuilder is available on multiple platforms. For consistency, JBuilder documentation and screen shots are based on the Solaris platform. See the table below for a description of platform conventions and directories.

Platform conventions and directories

Item	Meaning
Paths	All paths in the documentation are indicated with a forward slash (/). For the Windows platform, use a backslash (\).
Home directory	The location of the home directory varies by platform. JBuilder documentation is based on the Solaris platform. For Solaris and Linux, the home directory can vary. For example, it could be /user/[username} or /home/[username]. For Windows 95/98, the home directory is C:\Windows. For Windows NT, the home directory is C:\Winnt\Profiles\[username] .
.jbuilder directory	The .jbuilder directory, where JBuilder settings are stored, is located in the home directory.
jbproject directory	The jbproject directory, which contains project, class, and source files, is located in the home directory. JBuilder saves files to this default path.
Screen shots	Screen shots reflect the Java Metal look and feel on the Solaris platform.

[top]

Install

Tips:

For explicit install instructions, look at setup.html. It is very important to follow those directions.

Known problems:

• [75016] Install hangs with no message if not running under X-windows.
• [75323] An unsuccessful install will leave a number-named directory under your "temporary" directory. This could sometimes occur because install expects a JDK to already be installed and on your environment path.
• [74874] When launching Install.exe, two directories created in the $TEMP that do not get deleted after a success install.

[top]

Editor

There are many changes in the editor, including Emacs support, code templates and an improved Code Insight.  There is an all new editor for JBuilder 3.0.

Code Insight improvements:

The ability to "drill down" and open a class that's being used in the context (main editor) pane is still there but instead of working via alt + mouse click, it is used by moving the caret to the class and selecting with a Ctrl + Enter. Other ways of engaging this functionality are to right click on the method/class you want to drill into and select Browse Symbol, Ctrl + mouse click on the method in the structure pane, or to look at an unused class use the "Browse symbol" menu choice from the Search menu.

There are additional adjustments available to code insights from the Tools | IDE Options menu, including user selectable keystrokes.

Code Templates are now available from the context pane via Ctrl+J, the templates are commonly used programming blocks (try/catch, if/else, switch).

Known problems:

• Cursor position may not reflect actual position at times.  Workaround is to turn off the Bold attribute for syntax highlighting.  (Javasoft Bug)
• [71075]  Incremental search of Read-only file fails
• [72582]  Imported classes need to be available (i.e. the project needs to be compiled) in order for CodeInsight to provide assistance.  For example, to see changes in a newly updated class via CodeInsight, compile first.
• [73956] Under KDE Ctrl + F4 switches to desktop #4 instead of closing the editor tab that currently has focus.

[top]

Components

Y2K support:

JBuilder uses Java's short date pattern to format and parse date values. The default Java behavior is this: when a string contains a four-digit year, the year is taken just as it is; when a string contains a two-digit year, the year is assumed to fall in a window that runs from 80 years before the current date to 20 years in the future. To understand the implications of this rule, consider an example:
This character string is parsed: "9/23/2085"
The value in the resulting date object is: September 23, 2085
With the default formatting, this is displayed as: "9/23/85"
The string is edited: "10/23/85"
Parsing it gives this value in a date object: October 23, 1985
Only the month was edited, but the century also changed.

To prevent this unexpected behavior, dbSwing and JBCL components display a four-digit year when a date value is being edited using the default format. Because the edit pattern specifies a four-digit year, the 80/20 window is not used: any year from one to four digits may be entered, and that year is stored in the date object. dbSwing also substitutes a four-digit year when a custom displayMask is used to control editing. However, when you specify an editMask, it takes precedence. JBuilder uses the editMask just as you specify it, whether it calls for two or four digits.

In a JdbTextField, four-digit year substitution is done for both display and editing. In a JdbTable, it is only done during editing. This works well when editing an existing value, but may be confusing when a new value is entered in a JdbTable. For example, the string '10/23/85' would now be parsed as October 23, 85. To prevent this, you can set the column's editMask property to a pattern that requires a four-digit year to be entered.

[top]

Debugger

Tips:

Debugging the generated source of a JSP page (Enterprise Edition only):

When a web server is asked for a URL that contains a JSP page. the page is compiled into a java servlet. It's the output from the servlet that is seen on the browser. To debug this generated servlet take the following steps.

1. Create a new project and use the JSP Wizard to create a new JSP.
2. In the project properties dialog. Select the Run tab and then select the JSP/SHTML tab.   Enable the keep generated check box.
3. Right click on the .jsp file and select run. This forces the page to be compiled and creates the source code to the servlet.
4. Stop the running web server by clicking the square stop button.
5. Select 'Add file to project'. In the your project directory there will be a directory called 'work'.  Below that there is a directory containing the generated servlet. Add this java file to the project.
6. Set a break point and debug.

Known problems:

• Use the provided or recomended JDK when debugging.  If you must debug projects against the shipping JDK 1.2.0, expect the VM to fail on occasion.   This is due to bugs in JDK 1.2.0 that are fixed in JDK 1.2.2.
• When a class is compiled without debug information, the debugger will not be able to see any local variable information. However, it can see the "this" object.  If you are debugging, and only the "this" object shows up, it could mean that the class was built with no debug information. It could also mean that there are no local variables in the class.

[top]

Designer

Tips:

"Red Beans"

If you see one of your components as a red box with its class name at the top, JBuilder has not been able to create an instance of that  component  for the designer. This is called a "Red Bean". Some reasons you  might see a  Red Bean are:

1. The class or its constructor is not public
2. The class threw exceptions on every constructor JBuilder tried
3. The class is the 'this' object and it extends an abstract class

Items (1) and (2) can be fixed by supplying a proper default constructor or subclassing that class in order to provide a default constructor.  Item (3) is more complex. Whenever JBuilder needs to instantiate an object to be the 'this' object, it encounters a paradox. It cannot instantiate the  object  you are designing. To circumvent this problem, JBuilder always attempts to  instantiate the superclass of the "this" object. If the superclass is abstract, it cannot be instantiated. Here is the solution:

In the file .jbuilder/user.properties, you will find a line that looks like:

designer;proxy.java.awt.Component=com.borland.jbuilder.designer.dt.ComponentProxy

This line says that whenever you are forced to instantiate com.sun.java.swing.JComponent (which is abstract), you will find an  acceptable   concrete proxy class for it in:

com.borland.jbuilder.dt.JComponentProxy.

You may add your own proxy objects using this pattern. The proxy class does not need to do anything other than the following:

1. Extend the abstract class in question.
2. Be concrete (not be declared abstract itself).
3. Be public (both the class and its constructor).

Known problems:

• [72337]  Drop down editor for setting properties of type Color (e.g., background, foreground) list "named" colors that are used for AWT (Control, Text, etc.) as well as items for JFC.  If you are writing a JFC program it is better to use the colors defined by the Look-And-Feel you are using and not the awt items presented in the property editor for type java.awt.Color..

[top]

Wizards

Known problems:

• [70382]  Tools | CORBA Setup does not ensure that the VisiBroker or OrbixWeb library being added is placed  above any prior instance of the other library in the default project.
• [72856]  If you get compile errors from the CORBA-wizard generated source code and are using OrbixWeb, remove any setting for the "Package" field in the IDL properties and do a Project | Rebuild.

[top]

Compiler / Build System

Known problems:

• [72592]  If project source and out paths are the same, the build system still copies the .gif files in the source path to the out path during a Make. Results in unnecessary .gif~ files.  This can also result in 0 byte gif images on the outpath.   The workaround is to differentiate between your sourcepath and your outpath.

[top]

Runtime

Known Problems:

• [71510]  Parameter is not passed to applet when set in project run applet parameter.  Set the proper <PARAM> argument in the HTML for the applet.
• [71959]  Specifying more than one classpath for a -D parameter forces the VM to interpret the second classpath as the class to run.
• [72208]  A Submit button in a jsp has no effect if an action isn't defined.   If a submit button does not have a name attribute the from is submitted as a GET instead of a POST. even if the action says POST.  Workaround is to set the name attribute.

[top]

JDataStore / DataStore Explorer

To enable DataStore Explorer and DataStore Server under the Tools menu and the DataStore components on the Data Express tab of the component palette, you need to install JDataStore on top of a Professional Pack into the same location as JBuilder 3. Next you need to enter a valid JDataStore Developer license. The JDataStore license is entered by selecting File | License Manager within DataStore Explorer.

Known Problems:

• [70987]  On Solaris, while editing column data on DataStore Explorer, the Enter key of the numeric keypad will be treated as an Invalid character when used on a Numeric field. It will work in alphanumeric column (String, Char type).

[top]

VisiBroker

Known Problems:

• [Documentation]  Invalid characters appear in the index for VisiBroker and can block access to valid index targets.  The workaround is to access the VisiBroker documentation from the Contents and Find tab.

[top]

Samples

The OnlineStore sample requires the use of platform-specific InterBase database (.gdb) files in the 'OnlineStore/database' subdirectory. Database files are provided for the Windows, Solaris, and Linux platforms. Before running the OnlineStore sample, you will need to copy both of the platform-specific acmecb and cliffhanger databases to filenames with the normal .gdb file extension. For example, to run the sample on Windows, copy 'acmecb.gdb.windows' to 'acmecb.gdb' and 'cliffhanger.gdb.windows' to 'cliffhanger.gdb'.

The Samples.html file should be viewed in the JBuilder AppBrowser or from the link in the Welcome Project.

Known Problems:

• "Error #: 914: unable to write to output directory". If you have installed JBuilder 3.0 -- as root but are running as a regular user you need to copy the entire samples tree to a directory in which you have full read/write permissions in order to run them.  While it is possible to copy projects individually from the sample tree, there are several samples which require access to files in peer-level directories. Such samples have been modified to look automatically for such files relative to the default sample tree hierarchy, and display a message at runtime indicating the path being used to locate such files.
  
  An easy way to copy the entire samples tree is to use the 'cp -R' command. For example, to copy the tree to a 'samples' subdirectory of your home directory, do the following:
  
  % cd
  % cp -R /usr/local/jbuilder/samples .
• [73147]  You must compile the DataStore and DataExpress samples before using them in the Designer.  This will make classes and data available to the Designer.
• [73245]  The main gif image for the OnlineStore/OrderEntry sample will not display at runtime.  On line 132 of MainFrame.java in OnlineStore/OrderEntry sample, Products.gif is referenced when it should be products.gif (lower case as is on the disk).   Change the source and recompile.
• [72912]  Chess server fails to run when launched by user (JBuilder installed by root). The error message is: Could not listen on port: 4444, java.net.BindException: Permission denied.  If running as a user (not root), the basePort var in ChessServer.java has to be greater than 1025. Line 52 in ChessServer.java is currently:
  
  final static in basePort = 101;
  
  To run the client, you have to set the port to one less that the server port. line 632 in ChessViewer.java is currently:
  
  int port = 100;
  
  For example the server could run at port 1026 and the client at port 1025.
• [73420]  Chess viewer applet fails because of image Parameter specified in the Run Applet parameter.  First, make the changes for [72912] above.  To run the applet client:
  
  Run | Configurations...
  Select Chessviewer applet
  Click Edit
  Change the Values for the image Parameter to the correct file names and locations. For example:
  
  images/cmpieces.gif becomes com/borland/samples/chess/client/images/CMPIECES.GIF
•  

[top]

Performance

These are some suggestions for improving local performance of JBuilder 3.0.

• Adding "-Xverify:none" to your launch script will decrease the load time for JBuilder 3.0, Solaris/Linux Edition.
• Set VM heap usage settings to values you think are typical for your usage of the product. This avoids the degradation that occurs because the VM resists growing its heap. For medium to large projects try the following VM settings:
  
  -ms48m -mx128m
  
  You will need to experiment and fine tune these heap settings to your usage pattern.
• Install HotSpot. The faster memory management of hotspot makes a significant performance improvement. The apps you debug will probably need to use the classic VM so add -classic to your Project | Properties | Run | VM Parameters:
  
  Using HotSpot, we have noticed that some things are faster and some things (such as scrolling and other raw painting tasks) are slower.  If you decide to use HotSpot, you will have to determine if the benefits outweigh the costs for your usage patterns.
• If you use HotSpot, you can get smother garbage collection performance by enabling incremental gc. Use the following VM setting to do this:
  
  -Xincgc
  
  It is worth noting that the incremental garbage collector, while smoothing GC hiccups, also slows the VM down noticeably. We should suggest using this only if you experience long GC induced pauses while using JBuilder.
• You can reduce the amount of background source parsing for the structure pane by increasing the parsing time delay. To do this right click on the structure pain and select properties. Now increase the Parse Delay setting.

International

Installing to a Japanese NEC machine

[75607] If you are installing JBuilder to a Japanese NEC machine and the install program causes an operating system error message saying that "Drive C: is not ready... the drive door may be open...", then you should press the <Ignore> button in this dialog. Install will then complete normally. (The <Abort> button should also work.)

Japanese Fonts on Linux

[74990][75704][75705] If you experience problems displaying Japanese fonts on Linux, you may need to update the file, <jdk1.2.2>/jre/lib/font.properties.ja. JavaSoft's web site has instructions on how to do this in Japanese: Directions to modify the font.properties file (in Japanese).

You can also try some font files provided along with the JBuilder install files. These font files are offered as samples only, and cannot be supported for all installations of Linux.

Instructions for installing the sample fonts are in the following location: <JBuilder_Install_directory>/intl_patches/font-readme.txt, where<JBuilder_Install_directory> refers to the directory where you ran JBuilder's installation program (possibly on a CD-ROM, or part of a Web download).

Solaris JDK Patch -- libawt.so

The following problem can be worked around by applying the Patch described immediately afterwards. Note, these instructions apply only to Solaris. Linux users should check the JBuilder Web site for any updated information and patches.

[70036][70507] With the setting, "Enable international input methods" turned on (found under Tools | IDE Options; <Editor>; <Smart key options>), Editor actions associated with Ctrl-Shift keys do not get executed.

Examples of this problem in CUA mode are:
Ctrl-Shift-1 to Ctrl-Shift-9: Set bookmarks
Ctrl-Shift-Y: Delete to end of line
Ctrl-Shift-I: Indent block
Ctrl-Shift-U: Unindent block
Ctrl-Shift-Z:Redo

Example Emacs mappings effected:
Alt-> Go to top of buffer
Alt-< Go to bottom of buffer

This section describes application of the libawt.so patch for Solaris, which addresses the problems mentioned above.

Note:  In these instructions please consider <your_jdk_122> to be the path to your installed JDK-1.2.2-004 and replace <jb_install_dir> with the path to where you ran JBuilder's installation program. This directory could either be on a CD-ROM or a directory path uncompressed from a file you downloaded on the Internet.

1. Confirm Applicable JDK.

This patch is applicable only to JDK-1.2.2-004 (the JDK delivered for use with this version of JBuilder. To check your version of the JDK do the following at a command line (the initial '%' simply stands for your prompt):

% <your_jdk_122>/bin/java -version

It should report:

java version "1.2.2"
Classic VM (build JDK-1.2.2-004, green threads, sunwjit)

2. Save original shared libraries

% cd <your_jdk_122>/jre/lib/sparc
% mv libawt.so libawt.so.original
% mv libawt_g.so libawt_g.so.original

3.  Copy patched shared libraries.

% cp <jb_install_dir>/intl_patches/Solaris/*.so <your_jdk_122>/jre/lib/sparc
(Again, <jb_install_dir> is the directory that contains JBuilder's installation program.)

Unix & Enterprise Edn. Patch -- AwtMotifPatch.jar (Solaris & Linux), DBCSpatch.jar (JBuilder Enterprise Edition, all platforms)

The following problems can be worked around by applying the Patch described immediately afterwards.

Solaris & Linux Platforms
• [70509] Turning on/off "Enable International input methods" repeatedly causes JVM crash. (AwtMotifPatch.jar)
• [65058] While entering Japanese characters with the Wnn6 IME on Solaris-7, if you click outside of JBuilder's code editor while the composition window is opening, JBuilder can freeze. (AwtMotifPatch.jar)
  
  JBuilder Enterprise Edition
• [69947][69948] Data Modeler and SQL Builder are effected by the following JDK 1.2.x limitation (JavaSoft #4215746): When using the JdbcOdbc driver from Sun, an SQL command that contains a DBCS table or field name will not execute correctly. (DBCSpatch.jar)
• [72052] Any SQL command that returns DBCS (or other) data which have Unicode character codes with a second byte equal to 00h will result in truncated data in the resulting query. (DBCSpatch.jar)

Take the following steps to apply this patch.

Linux users:
1. The file, <path_to_JBuilder>/lib/AwtMotifPatch.jar, is for Solaris. Go to that directory and change the name of the file to, Sol_AwtMotifPatch.jar.
2. Copy the Linux version of this file from <JBuilder_Install_directory>/intl_patches/Linux/AwtMotifPatch.jar, to <path_to_JBuilder>/lib/. (Note, the <JBuilder_Install_directory> is the directory where you ran JBuilder's installation program. This directory could either be on a CD-ROM or a directory path uncompressed from a file you downloaded on the Internet.)
3. Make a back up of the launch script, <path_to_JBuilder>/bin/jbuilder
4. Now use your favorite editor to open this file, <path_to_JBuilder>/bin/jbuilder
5. Near the bottom of the script, find the line, "# Boot class path for International language OS support"
6. Uncomment the next line, by removing the "# " (i.e. #<space>). So that line should now read:
   
   "bootclasspath=<path_to_JBuilder>/lib/lwtoolkit.jar:<path_to_JBuilder>/lib/DBCSpatch.jar:<path_to_JBuilder>/lib/AwtMotifPatch.jar"

Solaris users:
1. Make a back up of the launch script, <path_to_JBuilder>/bin/jbuilder
2. Now use your favorite editor to open this file, <path_to_JBuilder>/bin/jbuilder
3. Near the bottom of the script, find the line, "# Boot class path for International language OS support"
4. Uncomment the next line, by removing the "# " (i.e. #<space>). So that line should now read:
   
   "bootclasspath=<path_to_JBuilder>/lib/lwtoolkit.jar:<path_to_JBuilder>/lib/DBCSpatch.jar:<path_to_JBuilder>/lib/AwtMotifPatch.jar"

MS Windows users (Note, AwtMotifPatch.jar is not needed for MS Windows):
1. Make a back up of the launch batch file <path_to_JBuilder>/bin/jbuilder.bat
2. Now use your favorite editor to open this file, <path_to_JBuilder>/bin/jbuilder.bat
3. Near the bottom of the file, find the line, "rem Boot class path for International language OS support"
4. Uncomment the next line, by replacing "rem" with "set", so that line should now read:
   
   "set bootclasspath=<path_to_JBuilder>\lib\lwtoolkit.jar;<path_to_JBuilder>\lib\DBCSpatch.jar"

Known Problems:

• [49327] If the Sparc Compose key does not function properly, be sure that the setting, "Enable international input methods" is turned on (found under Tools | IDE Options; <Editor>; <Smart key options>). If the problem persists, a mouse click in the field or edit region will often cause the Compose key to work.
• [73279] If the environment variable, LC_CTYPE, is set to the POSIX 'C' locale, the Sparc Compose key may not function for certain versions of Xlib client libraries.
• [65318] DBCS (for example, Japanese character set) literal string in .JSP corrupts in HTML browser and DBCS string that returned from bean corrupts in HTML browser.
• [70954] Emacs keymap "Set Mark" is actually Ctrl-2 instead of Ctrl-Space, or Ctrl-@ under Japanese Keyboard.
• [71929] Can't display localized exception messages of the native method calls correctly under a non-English locale. If these messages must be read, unix users can display them in English by setting the "LANG" environment variable to the POSIX "C" locale. For example unix users would execute at the command prompt: export LANG=C. 
• [72107] Undo <Ctrl_> under Emacs keymap is mapped to <Ctrl Shift -(hyphen)> using Japanese Keyboard.
• [72519] Undo <Ctrl_> under Emacs keymap does not work using French Keyboard. Workaround is to use <Ctrl x><u> [70533] Recommend using "DialogInput" font (the default setting) to avoid Italic and Bold attribute problems, and a cursor position problem in the Editor under Japanese OS. 

[top]