Contents

1. Introduction to JCDatabase
   
2. Strengths
   
3. Weaknesses
   
4. Coding example
   
5. Deployment
   
6. How to obtain JCDatabase
   

1. Introduction to JCDatabase

JCDatabase is a simplified version of JDBC (Java Database Connectivity) that lets developers use Java's write once, run everywhere capabilities for cross-platform applications that need data access. JCDatabase has the following advantages over JDBC:

1. JCDatabase does not require you to run a database server or configure your system to provide access to a local database and;
2. JCDatabase can be deployed either on a server for access by many users or as part of a traditional client-side application using direct file access.

JCDatabase was originally written to allow games to have fast access to a local file system for saving and retrieving the player's data using a relational database. It was also used in the 3DMatrix product to save and retrieve data conveniently and has been used succesfully in many other commercial products.

It is much nicer to arrange data in tables and perform queries rather than using an ad-hoc approach to creating data files and dealing with stored data in general. If you want to be storing data from your Java application and you prefer to use a relational database approach, then JCDatabase might be an ideal set of Java classes for your needs. JCDatabase also works beautifully for Servlets, allowing multiple people could access the same database.

2. Strengths

1. JCDatabase is extremely simple to use.
2. JCDatabase is flexible. The database can function with your Java code whether it is deployed as an Applet accessing a local database on the client, a Java Servlet accessing a database on the server or a Java Application running either on the client or on the server.
3. If deploying your application on the server you do not need to buy a commercial database server or ask your system administration to assist with the setup - you just have to put the JCDatabase data files in the default directory.
4. If deploying your application in the traditional way on the client (such as with a CD-ROM distribution with your installation or simply providing a ZIP file with the entire application and database) then you do not require your customers to configure their system in any way.

3. Weaknesses

1. You cannot import/export data between a JCDatabase and other databases. This means JCDatabase is not suitable if you want to link to an existing large database.
2. The SQL model used in JCDatabase is greatly simplified such that you only have a collection of bare essentials. For me this works however if you want a complete SQL language then JCDatabase is not going to cut it.
3. The software costs US$25. The good news however is that you can have it for free provided you are not dealing with too much data.

4. Coding example

Let us say that we want to create a database table that stores the names of people and their year of birth. To create a table you firstly have to make a text file containing the definition of the table columns. This file must have the same name as the table and with a .def extension. In our particular case the table definition text file could be:

string FIRST_NAME 15
string LAST_NAME 15
integer ID autonumber
integer YEAR_OF_BIRTH

We need to save this text file as people.def and then we can add the following code to our Java Application, Applet or Servlet to establish a reference to the table. Make sure that you have the file jcdatabase.jar in one of the directories within your CLASSPATH.

import com.digitalscores.jcdatabase.JCRow;
import com.digitalscores.jcdatabase.JCTable;

..

JCTable people = new JCTable("PEOPLE");

So far there has only been one line of code and we already have a reference to our table. To create a row of data for our table, you can use:

JCRow newRow = new JCRow(people);
newRow.setString("FIRST_NAME", "Julian");
newRow.setString("LAST_NAME", "Cochran");
newRow.setInt("YEAR_OF_BIRTH", 1974);
people.insert(newRow);

You could use the alternative syntax to acheive the same thing with one line of code:

people.insert("FIRST_NAME=Julian LAST_NAME=Cochran YEAR_OF_BIRTH=1974");

If you then wanted to delete all the rows in which the person's last name was 'Cochran', you would add the following code:

people.delete("LAST_NAME", "=", "Cochran");

To change the first name of anyone called "Julian" to "Jules", you use the update method in the following way:

people.update("FIRST_NAME", "Jules", "FIRST_NAME", "=", "Julian");

And if you wanted to select all the rows in which the year of birth is less than 1980 you would add:

JCRow[] result = people.select("YEAR_OF_BIRTH", "<", 1980);

And to print the results of that query, the following code works fine:

for (int i = 0; i < result.length; i++) {
  System.out.println(result[i].getString("FIRST_NAME"));
}

Within this section we have covered all of the essential concepts that allow you to do anything with your database -- inserting, updating, deleting and querying rows. The complete JCDatabase API can be viewed here.

To do the same things with JDBC you need to write a lot more code, install and configure software if accessing a local database, or be charged by your ISP if you wish to access your own ODBC or JDBC database on their server. JCDatabase bypasses these requirements by using Java's standard IO classes and a simple direct file access design.

5. Deployment

JCDatabase can be deployed with (1) Java Applets accessing the customer's local database, (2) Java Applications running on the client accessing the customer's local database, (3) Java Servlets or Applications running on a server accessing a server database.

In the case of deploying JCDatabase with a traditional client-side application, you can simply deploy your product by making a ZIP file available to the customer containing the following files:

1. All the .class files of your Java program.
2. The JCDatabase .class files.
3. Your table definition files (.def) - these define the columns for each table.
4. Optionally, any database files (.dat) - these contain the actual rows of data for each table.

6. How to obtain JCDatabase

You can download JCDatabase jcdatabase.zip here. This version includes a running example of a simple database and requires that your tables do not exceed 100 rows. I express many thanks to anyone willing to purchase JCDatabase. I have spent a lot of time putting these classes together and I am sure you understand that it is reasonable to ask for a small fee. To obtain the unrestricted version you may order JCDatabase by credit card here. You will then receive the latest version of JCDatabase via email.

Please email me at julian@digitalscores.com to ask any question about how JCDatabase works and to enquire about the range of applications for which JCDatabase has proven to be most effective.

Julian Cochran
DigitalScores
www.digitalscores.com