JBuilder 8

Release Notes

This document contains a subset of known problems, workarounds and tips for JBuilder 8.

Table of Contents

General
Installation
Web Services
Enterprise JavaBeans (EJB)
Web Development
Team Development
XML
Debugger
Designer
Runtime
New Features and Fixes in JDataStore 6.01
Linux/Solaris
Samples
Performance
International
Documentation
Copyrights, conditions and disclaimers

General

For the latest JBuilder FAQ's and TI's, please visit:

For updates and service packs for the Java Development Kit (JDK), see: http://java.sun.com/j2se/1.4.1/docs/index.html.

ATI Radeon video driver users

JBuilder hangs, crashes, or spontaneously reboots on Windows XP when using an ATI Radeon video driver. This often occurs after your screen saver appears. To work around this issue, uncomment the following lines in your jdk.config file:

vmparam -Dsun.java2d.noddraw=true
vmparam -Dsun.java2d.d3d=false

If you encounter these issues while debugging, add these VM parameters to the runtime configuration for the project you are debugging.

This is an issue with JDK 1.4.1 (Sun bug #4713003). Check the java.sun.com web site for possible fixes or updates.

Tips

Using JBuilder 8 with other versions of JBuilder

Some of the changes in JBuilder 8 make it extremely inconvenient to share the default configuration directory from previous versions of JBuilder (.jbuilderx, where x is the version number of JBuilder) with an installation of JBuilder 8. As a service to our customers, we put the settings for JBuilder 8 in a new directory, .jbuilder8.

Note: JBuilder 8 shares the following directories with previous versions of JBuilder:

You can change the location where JBuilder looks for your .jbuilderx directory by adding the following entry in the jbuilder.config file:

vmparam -Djbuilder.home=path to the parent directory for .jbuilder-dir

where .jbuilder-dir is the name of your alternate home directory.

Note: Do not place quotation marks around the values you add to your jbuilder.config file, even if they contain spaces. Doing so will generate a parsing error.

Known Problems

[ top ]

Installation

Tips

Linux

Uninstalling JBuilder 8

To uninstall JBuilder 8, run the following from the Uninstallxxxxxxx directory (where xxxxxxx is the name of the JBuilder edition you installed) under the directory where you installed JBuilder 8:

Known problems

[ top ]

Web Services

Tips

To enable the Axis TCP monitor feature on the server-side using Axis handler and the Axis SOAPMonitor Applet, follow these steps:

  1. Copy SOAPMonitorApplet.java from the JBuilder defaults directory to the project src directory.
  2. Uncomment the following two lines in the Axis index.xml file in the web services WebApps' Root directory:
    <li><a href="SOAPMonitor">SOAP Monitor Service</a>Launch SOAPMonitor Applet</li>
  3. Copy the following into any one of the deploy.wsdd in your project above or below the <service> element: 
    <globalConfiguration>
  <parameter name="adminPassword" value="admin"/>
  <parameter name="attachments.implementation" value="org.apache.axis.attachments.AttachmentsImpl"/>
  <parameter name="sendXsiTypes" value="true"/>
  <parameter name="sendMultiRefs" value="true"/>
  <parameter name="sendXMLDeclaration" value="true"/>
  <requestFlow>
   <handler type="java:org.apache.axis.handlers.JWSHandler">
    <parameter name="scope" value="session"/>
   </handler>
   <handler type="java:org.apache.axis.handlers.JWSHandler">
    <parameter name="scope" value="request"/>
    <parameter name="extension" value=".jwr"/>
   </handler>
   <handler type="java:org.apache.axis.handlers.SOAPMonitorHandler"/>
  </requestFlow>
  <responseFlow>
  <handler type="java:org.apache.axis.handlers.SOAPMonitorHandler"/>
  </responseFlow>
 </globalConfiguration>
  4. Make and run the project with the Web Services Server configuration.
  5. Click the SOAP Monitor Service link on the Axis index.html admin page.

Known Problems

[ top ]

Enterprise JavaBeans (EJB)

Support for Oracle 9i servers

Plug-ins to support the Oracle 9i application servers are provided on your JBuilder 8 product CD in the Oracle9iAS directory. Please see the README file in that directory for instructions on installing and configuring these plug-ins. Please note that these plug-ins are supported by Oracle. Contact Oracle Technical Support if you have any problems or issues regarding these plug-ins.

For the latest updates for the Oracle9i Application Server plug-ins, and to access plug-ins for previous JBuilder and 9iAS releases, please go to: http://otn.oracle.com/products/ias/9ias_partners.html#development.

Tips

Known problems

[ top ]

Web Development

Known problems

[ top ]

Team Development

Tips

To take full advantage of CVS capabilities in JBuilder, it is recommended that you use the version of CVS that is installed with JBuilder (1.11.1) or later.

For projects that are under version control, it is recommended you do not use "New Folder" feature from the Project Pane. It is better to organize your project using JBuilder's automatic source package discovery, or by choosing Add Files/Packages.

Known problems

[ top ]

XML

Tips

If transformation of your XML document fails, check to see if you are using the correct version of the stylesheet specification, http://www.w3.org/1999/XSL/Transform, and not the working draft.

Castor now requires 2001 schema support, <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">. If an older version is used, an error or exception might occur. The Castor sample has been updated: <jbuilder>/samples/tutorials/XML/databinding/fromSchema/Castor.jpx. The same is true for XML schema validation. You can find the latest Xerces schema samples with 2001 schema support in <jbuilder>/extras/xerces/data/.

Ignoring DTDs in XML documents

By default, JBuilder ignores DTDs in the editor. This option is set on the XML page of the IDE Options dialog box (Tools|IDE Options). When this option is selected, JBuilder does not resolve the DTD or report any errors in the structure pane. This makes it possible to work offline. Even when working online, leaving this option on results in a faster response time. If this option is unchecked, the editor must resolve the DTD each time and also reports any errors in the structure pane.

Known problems

[ top ]

Debugger

Remote debugging

When attaching to a process running on a remote computer, the default address has changed from 5000 to 3999.

To view this change,

  1. Choose Project|Project Properties.
  2. Click the Run tab.
  3. Choose a runtime configuration click Edit.
  4. Click the Debug tab. On the Debug page, choose Enable Remote Debugging, then choose Attach. Note that the Address option defaults to 3999.

    The port number/address that you set in this field should match the address parameter that you run your program from the command line on the remote computer.

If you are running Windows XP, do not use 5000 as the port number/address through which the debugger communicates with a remote computer. Windows XP reserves this port for the Universal Plug & Play.

Tips

Known problems

[ top ]

Designer

The Designer supports code generated by VisualAge (versions 3 and 4). You can view the source files generated by VisualAge, and use the Designer with these source files without having to modify them in any way. Use the Designer to add additional components, copy and paste, move components between containers, move to first, move to last, and change their properties and constraints.

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 .jbuilder8/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:

Known problems

[ top ]

Runtime

Running JDK 1.2 Applets

In order to run an applet on Solaris or Linux from within JBuilder, you must add the Open Tools SDK library to your project. Failing to add this library can lead to an exception about a "NoClassDefFoundError:AppletTestbed." This problem currently affects some of the applet samples, including the Primes Swing sample.

[ top ]

New Features and Fixes in JDataStore 6.01

Improved support for industry standards

The JDataStore 6.01 release has improved support for industry standards. In particular, it:

New JDBC extended properties

JDataStore 6.01 provides the following new extended properties that can be used when obtaining a new JDBC java.sql.Connection objects.

Semicolon-separated property settings in URLs

The extended properties discussed in the section above can be called in JDBC URLs using semicolons to separate the properties. For example:

jdbc:borland:dslocal:mydatabase.jds;create=true;tempDir=/tmp

Additional implementation for JDBC 2 interfaces

The following JDBC classes, interfaces and methods are now implemented:

Batch updates

Interfaces, classes, and methods required for batch update support.

Stored procedures

java.sql.CallableStatement is implemented.  The SQL extensions detail JDataStore's support for java methods. See Stored procedures and UDFs later in this document for details on how to create and use UDFs and stored procedures.

Scrollable/updateable JDBC cursors

ResultSet concurrency supported:

java.sql.ResultSet.CONCUR_UPDATABLE (new)
java.sql.ResultSet.CONCUR_READONLY

ResultSet types supported:

java.sql.ResultSet.TYPE_SCROLL_INSENSITIVE(new)
java.sql.ResultSet.TYPE_FORWARD_ONLY

Foreign keys

DatabaseMetaData methods that provide information on imported/exported keys are now implemented.

Additional implementation for JDBC 3 interfaces (requires JDK 1.4)

All JDBC interfaces, classes and methods required for JDBC 3 compliance are now implemented. This includes support for:

"heuristicCompletion" extended JDBC property for XA distributed transactions

This is a new JDBC extended property that controls how XA transactions that are prepared, but not finished (no commit or rollback) will be heuristically completed.  There are three possible string settings for this property:

The default setting for this property is commit.

Note: The heuristic commit and rollback options allow for more efficient execution, because locks can be released sooner and less information needs to be written to the transaction log file.

New keywords

The following keywords are new in JDataStore 6.01:

ACTION
ANY
CALL
CHECK
EXCEPT
FOREIGN
INTERSECT
NO
REFERENCES
SOME
USER

DATE and TIME data types

The DATE and TIME data types now store local date and local time. Prior to JDataStore 6.0, they stored GMT time. However, this approach was problematic.

Effect: DATE and TIME values are now independent of the time zone JDataStore is running in. A TIME value of 09:00:00 in San Francisco displays as 09:00:00 in New York.

The TIMESTAMP type has not changed. It is still stored in GMT time. Thus a TIMESTAMP of 2002-05-25 09:00:00 in San Francisco displays as 2002-05-25 12:00:00 in New York.

The FLOAT data type

The FLOAT data type has changed. Prior to JDataStore 6.0 the FLOAT data type was equivalent to the Java float type. However, according to the SQL92 standard, the FLOAT data type is an abbreviation of FLOAT(p) where p is the largest supported precision in bits of this floating point number.

This change means that the corresponding SQL type to a Java float is REAL. For JDataStore, a FLOAT is now an abbreviation of FLOAT(52) which corresponds to a Java double.

FLOAT(p) where p is [1,23] corresponds to a Java float.
FLOAT(p) where p is [24,52] corresponds to a Java double.

Two new system functions

Subqueries

General support for SQL92 subqueries has been added to JDataStore 6.0. This includes:

All of these subqueries can include outer references.

Foreign keys

JDataStore 6 now supports the use of FOREIGN KEYs in CREATE TABLE and ALTER TABLE statements, including cascading updates and deletes.

Create Table

The CREATE TABLE syntax is as follows:

<create table statement> ::=  
    CREATE TABLE <table name> ( <table element commalist> )

<table name> ::=  <SQL identifier>

<table element> ::=  
      <column definition> 
    | <primary key> 
    | <unique key> 
    | <foreign key>

<column definition> ::=   
    <column name> <data type> 
    [DEFAULT <default value>]
    [[NOT] NULL]
    [AUTOINCREMENT]
    [[CONSTRAINT <constraint name>] PRIMARY KEY]
    [[CONSTRAINT <constraint name>] UNIQUE]
    [[CONSTRAINT <constraint name>] <references definition>]

<column name> ::=  <SQL identifier>

<default value> ::=   
      <literal> 
    | <current date function>

<primary key> ::=    
    [CONSTRAINT <constraint name>] PRIMARY KEY <column name commalist>)

<unique key> ::=  
    [CONSTRAINT <constraint name>] UNIQUE ( <column name commalist>)

<foreign key> ::=  
    [CONSTRAINT <constraint name>] FOREIGN KEY (<column name commalist>)
         <references definition>

<references definition> ::= 
    REFERENCES <table name> [( <column name commalist> )]  
    [ON DELETE <action>] 
    [ON UPDATE <action>]  
    [NO CHECK]

<action> ::= 
      NO ACTION  
    | CASCADE  
    | SET DEFAULT 
    | SET NULL

<constraint name> ::=  <SQL identifier>
Note

The NO CHECK option creates the foreign key without checking the consistency at creation time. Use this option with caution.

Example 

CREATE TABLE Orders ( CustId INTEGER PRIMARY KEY, Item VARCHAR(30),
     Amount INT, OrderDate DATE DEFAULT CURRENT_DATE)
Example  Creating a table using two columns for the primary key constraint: 
CREATE TABLE TABLE1 (c1 INT, c2 STRING, c3 STRING, primary key (c1, c2))

Alter Table

ALTER TABLE adds and removes columns in a table. The syntax is as follows: 
<alter table statement> ::= 
    ALTER TABLE <table name> <change definition commalist>

<change definition> ::=
      <add column element>
    | <drop column element>
    | <alter column element>
    | <add constraint>
    | <drop constraint>

<add column element> ::= ADD [COLUMN] <column definition>

<drop column element> ::= DROP [COLUMN] <column name>

<alter column element> ::= 
      ALTER [COLUMN] <column name> SET <default-definition>
    | ALTER [COLUMN] <column name> DROP DEFAULT

<add constraint> ::= ADD <base table constraint>

<base table constraint> ::= 
    <primary key> |  <unique key> |  <foreign key>

<primary key> ::=    
    [CONSTRAINT <constraint name>] PRIMARY KEY <column name commalist>)

<unique key> ::=  
    [CONSTRAINT <constraint name>] UNIQUE ( <column name commalist>)

<foreign key> ::=  
    [CONSTRAINT <constraint name>] FOREIGN KEY (<column name commalist>)
         <references definition>

<references definition> ::= 
    REFERENCES <table name> [( <column name commalist> )]  
    [ON DELETE <action>] 
    [ON UPDATE <action>]  
    [NO CHECK]

<action> ::= 
      NO ACTION  
    | CASCADE  
    | SET DEFAULT 
    | SET NULL

<constraint name> ::=  <SQL identifier>

<drop constraint> ::= DROP CONSTRAINT <constraint name>
Example: 
ALTER TABLE Orders Add ShipDate DATE, DROP Amount

Table expressions

General support for SQL92 table expressions has been added to JDataStore 6.0. This includes:

These table expressions can be combined the table JOIN operator.

Single-row SELECT

The SELECT ... INTO statement has been added to JDataStore 6.0. This is a SELECT statement that retrieves at most one row (it's an error if the result table has more than one row), and then binds the values of that result row to a set of parameter markers.

Example

SELECT SUM(COL1),MAX(COL2) INTO ?, ? 
  FROM TABLE1 
    WHERE COL1 < COL2;

This statement must be prepared as a CallableStatement in order to retrieve the output values from the parameters.

Stored procedures and UDFs

Stored procedures are user-defined functions that are designed to handle business logic. These functions serve to hide the complexity of dealing with relational tables. Stored procedures are called directly, and optionally have input and or output parameters. For example:

CALL  INCREASE_SALARY(10000);

UDFs are user-defined functions that are designed to be used in subexpressions of a SQL statement. Typically a SELECT statement can use a UDF in its WHERE clause. For example:

SELECT * FROM TABLE1 WHERE   MY_XOR_UDF(COL1,COL2) = 8;

Language for stored procedures and UDFs

Stored procedures and UDFs for JDataStore must be written in Java. There is no security against bad behaviors of the written Java code. However, the compiled Java classes must be added to the classpath of the JDataStore server process in order to be available for use. This should give the database administrator a chance to control which code is added. Only public static methods in public classes can be made available for use.

Making a stored procedure or a UDF available to the SQL engine

After a stored procedure or a UDF has been written and added to the classpath of the JDataStore server process, a function name is associated with that Java method using the following SQL syntax:

CREATE JAVA_METHOD <method-name> AS <method-definition-string>

where the <method-name> is a SQL identifier such as INCREASE_SALARY and <method-definition-string> is a string with a fully qualified method name, such ascom.mycompany.util.MyClass.increaseSalary.

A stored procedure or a UDF can be dropped from the database by executing:

DROP JAVA_METHOD <method-name>

After a method is created, the method is ready for use. See the following section for examples.

Input parameters

A final type-checking of parameters is performed when the Java method is called. Numeric types are cast to a higher type if necessary in order to match the parameter types of a Java method. The numeric type order for Java types is:

  1. double or Double
  2. float or Float
  3. java.math.BigDecimal
  4. long or Long
  5. int or Integer
  6. short or Short
  7. byte or Byte

The other recognized Java types are:

Note that if you pass NULL values to the Java method, you cannot use the primitive types (e.g short, double). Use the equivalent encapsulation classes instead (Short, Double). A SQL NULL value is passed as Java null value.

If a Java method has a parameter of a type (or an array of a type) that is not listed in the tables above, then it is handled as SQL OBJECT type.

A UDF example

  package com.mycompany.util;
  public class MyClass {
    public static int findNextSpace(String str, int start) {
      return str.indexOf(' ',start);
    }
  }

  
   CREATE JAVA_METHOD FIND_NEXT_SPACE AS 
       'com.mycompany.util.MyClass.findNextSpace';
   SELECT * FROM TABLE1 
         WHERE FIND_NEXT_SPACE(FIRST_NAME, CHAR_LENGTH(LAST_NAME)) < 0;

Note: This example defines a method that locates the first space character after a certain index in a string. The SQL snippet has the definition of this UDF and an example of its use. Assume that TABLE1 has two VARCHAR columns: FIRST_NAME and LAST_NAME. The CHAR_LENGTH function is a built-in SQL function.

Output parameters

If a Java method parameter is an array of one of the recognized input types (except for byte[]), the parameter is expected to be an output parameter. JDataStore passes an array of length 1 into the method call, and the method is expected to populate the first element in the array with the output value. The recognized Java types for output parameters are:

Output parameters can be bound only to variable markers in SQL. All output parameters are essentially INOUT parameters, since any value set before the statement is executed is passed to the Java method. If no value is set, the initial value is arbitrary. If any of the parameters can output a SQL NULL (or have a valid NULL input), use the encapsulated classes instead of the primitive types. For example: 
  package com.mycompany.util;
  public class MyClass {
   public static void max(int i1, int i2, int i3, int result[]) {
      result[0] = Math.max(i1, Math.max(i2,i3));
   } 
  }

CREATE JAVA_METHOD MAX AS
    'com.mycompany.util.MyClass.max';

CALL MAX(1,2,3,?);

Note: The CALL statement must be prepared with a Callable statement in order to get the output value. See the JDBC documentation for how to use java.sql.CallableStatement. Notice the assignment of result[0] in the Java method. The array passed into the method has exactly one element.

Implicit connection parameter

If the first parameter of a Java method is of type java.sql.Connection, JDataStore passes a connection object which shares the transactional connection context used to call the stored procedure in the first place. This connection object can be used to execute SQL statements using the JDBC API.

Do not pass anything for this parameter; let JDataStore do it.

Example 

  package com.mycompany.util;
  public class MyClass {
    public static void increaseSalary(java.sql.Connection con, java.math.BigDecimal amount) {
     java.sql.PreparedStatement stmt = con.prepareStatement("UPDATE EMPLOYEE SET SALARY=SALARY+?");
     stmt.setBigDecimal(1,amount);
     stmt.executeUpdate();
     stmt.close();
    }
  }
CREATE JAVA_METHOD INCREASE_SALARY AS 'com.mycompany.util.MyClass.increaseSalary';

CALL INCREASE_SALARY(20000.00);

Notes

Overloaded method signatures

The Java methods can be overloaded to avoid numeric loss of precision.

Example 

  package com.mycompany.util;
  public class MyClass {
    public static int abs(int p) {
      return Math.abs(p);
    }

    public static long abs(long p) {
      return Math.abs(p);
    }

    public static BigDecimal abs(java.math.BigDecimal
p) {
      return p.abs();
    }

    public static double abs(double p) {
      return Math.abs(p);
    }
  }

CREATE JAVA_METHOD ABS_NUMBER AS 'com.mycompany.util.MyClass.abs';

SELECT * FROM TABLE1 WHERE ABS(NUMBER1) = 2.1434;

Note: The overloaded method abs is registered only once in the SQL engine. Now imagine that the abs method taking a BigDecimal was not implemented! If NUMBER1 was a NUMERIC with decimals, then the abs method taking a double would be called, which has the potential of losing precision when the number is converted from a BigDecimal to a double.

Return type mapping

The return value of the method is mapped into an equivalent SQL type. Here is the type mapping table:
 
Return type of method JDataStore SQL type
byte or Byte SMALLINT
short or Short SMALLINT
int or Integer INT
long or Long BIGINT
java.math.BigDecimal DECIMAL
float or Float REAL
double or Double DOUBLE
String VARCHAR
boolean or Boolean BOOLEAN
java.io.InputStream INPUTSTREAM
java.sql.Date DATE
java.sql.Time TIME
java.sql.Timestamp TIMESTAMP
All other types: OBJECT

Note: Any type derived from java.io.InputStream is handled as an INPUTSTREAM.

[ top ]

Linux/Solaris

Tips

Printing on Linux and Solaris platforms

A workaround for users on Unix platforms who do not need to use AWT components in the designer and want to be able to select a printer that is different than lpr is to comment out the line in the jbuilder.config file that adds the LightWeight Toolkit to the boot path as shown:

# Put the Lightweight Toolkit on the boot path 
#addbootpath ../lib/lawt.jar

Known problems

[ top ]

Samples

The samples.html file should be viewed in the JBuilder AppBrowser or from the link in the Welcome Project if you want to use the links to load the project files in JBuilder. If you have configured file associations so that JBuilder projects are associated with JBuilder, you can view samples.html in most web browsers, and the links to projects will work.

Known problems

[ top ]

Performance

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

[ top ]

International

Installing to a Japanese NEC machine:

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

Japanese Fonts on Linux:

[75704][75705] If you experience problems displaying Japanese fonts on Linux, you may need to update the file, <jdk1.3.1>/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).

Command Line Compiler:

Other Known Problems:

[ top ]

Documentation

Check the JBuilder Technical Publication web site, http://www.borland.com/techpubs/jbuilder, for updates to the documentation.

For the latest JBuilder FAQ's and TI's, please visit:

Known problems

[ top ]