Setting up JBuilder for database applications

Database application development is a feature of JBuilder Professional and Enterprise. Distributed application development is a feature of JBuilder Enterprise. If you downloaded JBuilder, you also need to download the Samples Pack in order to have the samples. Note that some samples only work with JBuilder Enterprise.

To operate the database tutorials included in this book, you'll need to install the JDataStore JDBC driver and/or the InterClient JDBC driver. This topic discusses setting up JDataStore and InterClient for use in the tutorials. See Adding a JDBC driver to JBuilder below.

Sun worked in conjunction with database and database tool vendors to create a DBMS independent API. Like ODBC (Microsoft's rough equivalent to JDBC), JDBC is based on the X/Open SQL Call Level Interface (CLI). Some of the differences between JDBC and ODBC are:

JDBC is endorsed by leading database, connectivity, and tools vendors including Oracle, Sybase, Informix, InterBase, DB2. Several vendors, including Borland, have JDBC drivers. Existing ODBC drivers can be utilized by way of the JDBC-ODBC bridge provided by Sun. Using the JDBC-ODBC bridge is not an ideal solution since it requires the installation of ODBC drivers and registry entries. ODBC drivers are also implemented natively which compromises cross-platform support and applet security.

JBuilder DataExpress components are implemented using the Sun database connectivity (JDBC) Application Programmer Interface (API). To create a Java data application, the Sun JDBC sql package must be accessible before you can start creating your data application. If your connection to your database server is through an ODBC driver, you also need the Sun JDBC-ODBC bridge software.

For more information about JDBC or the JDBC-ODBC bridge, visit the JDBC Database Access API web site at http://java.sun.com/products/jdbc/.

Connecting to databases

You can connect JBuilder applications to remote or local SQL databases, or to databases created with other Borland applications such as C++ Builder or Delphi.

To connect to a remote SQL database, you need either of the following:

When connecting to local, non-SQL databases such as Paradox or Visual dBASE, use an ODBC driver appropriate for the table type and level you are accessing in conjunction with the JDBC-ODBC bridge software.


JBuilder sample files

The JBuilder/samples directory contains files for various tutorials and examples presented in this manual. The DataExpress sample files are located in the /samples/DataExpress/ subdirectory of your JBuilder installation.

Note: If you downloaded JBuilder, you also need to download the Samples Pack in order to have the samples. Note that some samples only work with JBuilder Enterprise.

The database sample applications contain samples that access data from a JDataStore, employee.jds, and from the InterBase sample database employee.gdb. For more information on JDataStore, see JDataStore Developer's Guide. For more information on InterBase Server, refer to its on-line documentation.

If you wish to examine the sample applications in the JBuilder designer, please note that you should build the project for each sample before bringing it into the designer. To do this, select Project|Rebuild Project.

Note for Unix users

If you install JBuilder as 'root', but run JBuilder under your normal user account, you will not be able to run any of the samples directly from the JBuilder samples directory. Attempting to do so will result in a compile-time error, Error #: 914: unable to write to output directory.

In order to run a sample project, you must have read/write access to all files and directories created or used by the sample. In general, if you only have read-only access to the JBuilder samples subdirectory, you will need to copy the samples into a directory in which you have read/write access to run the samples. Because some samples require files (e.g., databases) in other subdirectories of the samples directory, it is recommended that you make your own copy of the entire samples tree, if possible. Samples which try to access files in other samples directories write a message indicating the directory in which they expect to find a file.

In order to run the samples in such an environment, copy the entire samples tree to another directory to which you have full read/write access. 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 automatically look for such files relative to the default sample tree hierarchy, and to display a message at run time 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 .

Alternatively, you could run the shell script in the main samples directory named 'chmod_samples'. Running this script enables the user who installs JBuilder to control access to the samples.

Usage: chmod_samples full
            to allow all users to compile, run, and modify sample
			files
   or  chmod_samples run
            to allow all users to compile, run, but not modify sample
			files
   or  chmod_samples read
            to allow all users to read but not run or modify sample
			files

Setting up JDataStore

JDataStore Explorer is disabled on the Tools menu when you first install JBuilder Foundation or Professional. To enable JDataStore Explorer and JDataStore Server under the Tools menu, and to include the JDataStore components on the Data Express tab of the component palette, you need to do one or more of the following:

Installing JDataStore installs the JDataStore Server on your local machine. No special configuration is necessary. The JDataStore library will be added to your project when you connect to a JDataStore database. The first time you connect using JDataStore, you will be prompted for your serial number and password.

To view and explore the contents of the JDataStore, use the JDataStore Explorer. To start the JDataStore Explorer, select Tools|JDataStore Explorer. To open the sample JDataStore, browse to /jbuilder/samples/JDataStore/datastores/employee.jds.

For more information on the JDataStore Explorer, see the JDataStore Developer's Guide.


Setting up InterBase and InterClient

About InterBase and InterClient

InterBase is a SQL-compliant, relational database management software product that is easy to use. InterBase is client and tools independent, supporting most of the popular desktop clients and application builder frameworks.

InterClient is an all-Java JDBC driver for InterBase databases. InterClient contains a library of Java classes which implement most of the JDBC API and a set of extensions to the JDBC API. It interacts with the JDBC Driver Manager to allow client-side Java applications and applets to interact with InterBase databases.

InterClient includes a server-side driver, called InterServer. It can be downloaded from www.interbase.com. This server-side middle ware serves as a translator between the InterClient-based clients and the InterBase database server. It includes the Java application development classes, and a web server deployment kit.

Developers can deploy InterClient-based clients in two ways:

As an all-Java API to InterBase, InterClient enables platform-independent, client-server development for the Internet and corporate Intranets. The advantage of an all-Java driver versus a native-code driver is that you can deploy InterClient-based applets without having to manually load platform-specific JDBC drivers on each client system (the web servers automatically download the InterClient classes along with the applets). Therefore, there's no need to manage local native database libraries, which simplifies administration and maintenance of customer applications. As part of a Java applet, InterClient can be dynamically updated, further reducing the cost of application deployment and maintenance.

Using InterBase and InterClient with JBuilder

To use InterBase and InterClient with JBuilder, install InterBase and InterClient following their instructions, then start the InterBase Server, followed by InterClient's InterServer.

If you have trouble connecting, be sure the InterBase database and InterServer are both running. InterServer and the database can run on the same machine as your application, or on a different machine. As a result, there are many possible configurations. It is important that your InterClient version be compatible with your database version and your JDK. For more information on these topics, please refer to the InterBase and InterClient documentation.

If InterBase Server and InterServer are on a different platform than JBuilder, you need to:

After InterClient is installed, add it to JBuilder using Tools|Enterprise Setup, then add it to your required list of libraries for your project in Project|Properties. For more information, see Adding a JDBC driver to JBuilder below.

Tips on using sample InterBase tables

To view the metadata for the sample tables,

  1. Run Tools|JDBC Explorer.


Adding a JDBC driver to JBuilder

After installing your JDBC driver following the manufacturer's instructions, use the steps below to set it up for use with JBuilder.

Note: Uninstalled drivers are red on the Drivers list in the Connection Property dialog box and cannot be selected for use in JBuilder. You must install them according to the manufacturer first before setting them up in JBuilder.

Creating the .library and .config files

There are three steps to adding a database driver to JBuilder: The first two steps can be accomplished in one dialog box:
  1. Open JBuilder and choose Tools|Enterprise Setup. Click the Database Drivers tab which displays .config files for all the currently known database drivers.
  2. Click Add to add a new driver, then New to create a new library file for the driver. The library file is used to add the driver to the required libraries list for projects.

    Note: You can also create a new library under Tools|Configure Libraries, but since you would then have to use Enterprise Setup to derive the .config file, it is simpler to do it all here.

  3. Type a name and select a location for the new file in the Create New Library dialog box.

  4. Click Add, and browse to the location of the driver. You can select the directory containing the driver and all it's support files, or you can select just the archive file for the driver. Either will work. JBuilder will extract the information it needs.

  5. Click OK to close the file browser. This displays the new library at the bottom of the library list and selects it.

  6. Click OK. JBuilder creates a new .library file in the JBuilder /lib directory with the name you specified (for example, InterClient.library). It also returns you to the Database Drivers page which displays the name of the corresponding .config file in the list which will be derived from the library file (for example, InterClient.config).

  7. Select the new .config file in the database driver list and click OK. This places the .config file in the JBuilder /lib/ext directory.

  8. Close and restart JBuilder so the changes to the database drivers will take effect, and the new driver will be put on the JBuilder classpath.

Important: If you make changes to the .library file after the .config file has been derived, you must re-generate the .config file using Enterprise Setup, then restart JBuilder.

Adding the JDBC driver to projects

Projects run from within JBuilder use only the classpath defined for that project. Therefore, to make sure the JDBC driver is available for all new projects that will need it, define the library and add it to your default list of required libraries. This is done from within JBuilder using the following steps:

  1. Start JBuilder and close any open projects.
  2. Choose Project|Default Project Properties.
  3. Select the Required Libraries tab on the Paths page, then click the Add button.
  4. Select the new JDBC driver from the library list and click OK.
  5. Click OK to close the Default Project Properties dialog box.
Note: You can also add the JDBC driver to an existing project. Just open the project, then choose Project|Properties and use the same process as above.

Now JBuilder and the new JDBC driver are set up to work together. The next step is to create or open a project that uses this driver, add a Database component to it, and set its connection property so it can use that driver to access the data. For an example of how to do this, see "Tutorial: Connecting to a database using InterClient" in the Database Application Developer's Guide.