com.digitalscores.jcdatabase
Class JCTable

java.lang.Object
  |
  +--com.digitalscores.jcdatabase.JCTable

public class JCTable
extends java.lang.Object

Represents a table of data using the JC database management system. The data is represented within a physical file that has the filename [tablename].dat in the default directory. The definitions of this data are provided in the filename [tablename].def in the default directory. The data is not represented within instances of the class (eg, as an array of JCRow objects) because that would require enormous memory. JCTable does provide a memory copy of the data definition file (in the form of an object called JCDataDefinition) so that the table's data-types can be referred to without re-opening the definition file many times. JCTable is instantiated once by an application, usually as a global variable, and from there various common SQL-like methods can be performed on the table very conveniently.

Example of use:

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 extention. 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
float HEIGHT

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 jcdatabase.jar is in your CLASSPATH for this to work.

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

..

JCTable people = new JCTable("PEOPLE");

So far there hasn't been much code. 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);
newRow.setFloat(167.23f);
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 HEIGHT=167.23");

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"));
}

Since:
1.3
See Also:
JCRow

Field Summary
 int cacheSizeInBytes
           
 java.lang.String dataFileExtension
           
static int defaultSortMethodForSelectStatements
           
 com.digitalscores.jcdatabase.JCDataDefinition definition
           
protected  int numberOfCachedRecords
           
static int ORDER_IN_WHICH_DATA_WAS_SAVED
           
static int SORT_BY_FIRST_COLUMN
           
 java.lang.String tableName
           
 
Constructor Summary
JCTable(java.lang.String tableName)
          Creates a reference to the physical database table named 'tableName'.
JCTable(java.lang.String tableName, int cacheSizeInBytes)
          Alternative constructor that provides memory caching for faster select, insert, update and delete statements.
 
Method Summary
static java.lang.String characterReplace(java.lang.String message, char charToFind, char replaceWith)
           
 void commit()
           
 int delete(com.digitalscores.jcdatabase.JCRow[] rowsToDelete)
          Deletes arbitrary rows from the result of a select(..) method call and returns the number of rows deleted.
 int delete(java.lang.String columnName, java.lang.String operator, float match)
          Performs the SQL statement "delete from [this table] where columnName [operator] match and returns the number of rows deleted.
 int delete(java.lang.String columnName, java.lang.String operator, int match)
          Performs the SQL statement "delete from [this table] where columnName [operator] match and returns the number of rows deleted.
 int delete(java.lang.String columnName, java.lang.String operator, java.lang.String match)
          Performs the SQL statement "delete from [this table] where columnName [operator] match and returns the number of rows deleted.
static java.lang.String fixedLength(java.lang.String text, int newSize)
          Adds or deletes ' ' characters from the end of the string to fix it to 'newSize'
 int insert(com.digitalscores.jcdatabase.JCRow newRow)
          Inserts a supplied row of data as a JCRow into the table.
 int insert(java.lang.String message)
          Inserts a row of data into the table using the syntax: "column1=value1 column2=colum2 ...".
static boolean like(java.lang.String string1, java.lang.String string2)
          Returns true iff the two strings are equal without case sensitivity and after '_' characters are converted to spaces.
 int maxInteger(java.lang.String columnName)
          Returns the maximum integer value in the table for a given column name.
 void printAllData()
          Displays all column names and all rows of data to System.out using a tab separated format.
 com.digitalscores.jcdatabase.JCRow[] select()
          Performs the SQL statement "select * from [this table]" and returns an array of JCRow objects.
 com.digitalscores.jcdatabase.JCRow[] select(java.lang.String columnName, java.lang.String operator, float match)
          Performs the SQL statement "select * from [this table] where columnName [operator] match" and returns an array of JCRow objects.
 com.digitalscores.jcdatabase.JCRow[] select(java.lang.String columnName, java.lang.String operator, int match)
          Performs the SQL statement "select * from [this table] where columnName [operator] match" and returns an array of JCRow objects.
 com.digitalscores.jcdatabase.JCRow[] select(java.lang.String columnOfThisTable, java.lang.String columnOfOtherTable, com.digitalscores.jcdatabase.JCRow[] rowSetFromOtherTable)
          Method to allow fast join operations.
 com.digitalscores.jcdatabase.JCRow[] select(java.lang.String columnOfThisTable, java.lang.String columnOfOtherTable, com.digitalscores.jcdatabase.JCTable otherTable)
          Convenience method that is similar to: "select * from [this table], otherTable where [this table].columnOfThisTable = otherTable.columnOfOtherTable.
 com.digitalscores.jcdatabase.JCRow[] select(java.lang.String columnName, java.lang.String operator, java.lang.String match)
          Performs the SQL statement "select * from [this table] where columnName [operator] match" and returns an array of JCRow objects.
 com.digitalscores.jcdatabase.JCRow[] select(java.lang.String columnName1, java.lang.String operator1, java.lang.String match1, java.lang.String combination, java.lang.String columnName2, java.lang.String operator2, java.lang.String match2)
          Performs the SQL statement "select * from [this table] where columnName1 [operator1] match1 [combination] columnName2 [operator2] match2" and returns an array of JCRow objects.
 com.digitalscores.jcdatabase.JCRow[] setRelationship(com.digitalscores.jcdatabase.JCRow[] result1, java.lang.String combination, com.digitalscores.jcdatabase.JCRow[] result2)
          Allows more complex select statements to be formed by combining the results of two simpler select statements.
 com.digitalscores.jcdatabase.JCRow[] sortBy(com.digitalscores.jcdatabase.JCRow[] rowToSort, java.lang.String columnToSortBy)
          Sorts an arrow of JCRow objects by any column.
static java.lang.String stringWithTrailingCharactersTrimmed(java.lang.String message, char c)
          Deletes characters (usually c = ' ') from the end of 'message' until the first character other than c is reached.
 int update(java.lang.String columnToChange, int newValue, java.lang.String columnNameToMatch, java.lang.String operator, int match)
          Changes 'columnNameToChange' to 'newValue' for all rows that yield a match between 'columnNameToMatch', 'operator' and 'match'.
 int update(java.lang.String columnToChange, int newValue, java.lang.String columnNameToMatch, java.lang.String operator, java.lang.String match)
          Changes 'columnNameToChange' to 'newValue' for all rows that yield a match between 'columnNameToMatch', 'operator' and 'match'.
 int update(java.lang.String message, java.lang.String columnNameToMatch, java.lang.String operator, java.lang.String match)
          Updates multiple attributes of multiple records with a single pass of the database file.
 int update(java.lang.String columnToChange, java.lang.String newValue, java.lang.String columnNameToMatch, java.lang.String operator, int match)
          Changes 'columnNameToChange' to 'newValue' for all rows that yield a match between 'columnNameToMatch', 'operator' and 'match'.
 int update(java.lang.String columnToChange, java.lang.String newValue, java.lang.String columnNameToMatch, java.lang.String operator, java.lang.String match)
          Changes 'columnNameToChange' to 'newValue' for all rows that yield a match between 'columnNameToMatch', 'operator' and 'match'.
 boolean validateOperator(java.lang.String operator)
          Returns true if and only if the supplied operator is a valid operator.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

tableName

public java.lang.String tableName

definition

public com.digitalscores.jcdatabase.JCDataDefinition definition

dataFileExtension

public final java.lang.String dataFileExtension
See Also:
Constant Field Values

cacheSizeInBytes

public int cacheSizeInBytes

ORDER_IN_WHICH_DATA_WAS_SAVED

public static int ORDER_IN_WHICH_DATA_WAS_SAVED

SORT_BY_FIRST_COLUMN

public static int SORT_BY_FIRST_COLUMN

defaultSortMethodForSelectStatements

public static int defaultSortMethodForSelectStatements

numberOfCachedRecords

protected int numberOfCachedRecords
Constructor Detail

JCTable

public JCTable(java.lang.String tableName)
Creates a reference to the physical database table named 'tableName'. The files that relate to this table are [tableName].def (column definition file) and [tableName].dat (containing the actual table data).

An example of a .def file is as follows:

string FIRST_NAME 15
string LAST_NAME 15
integer ID autonumber
integer YEAR_OF_BIRTH


JCTable

public JCTable(java.lang.String tableName,
               int cacheSizeInBytes)
Alternative constructor that provides memory caching for faster select, insert, update and delete statements. Caching begins from the start of a .dat file and runs as far as possible until cacheSizeInBytes is exceeded. If caching is used then database updates, deletes and inserts all require the commit() method to be called in order to guarantee that updates are made to the physical file. Caches are not shared between different JCTable objects, that is, only one JCTable object should be created per table and re-used in order for the cache to take effect.

Method Detail

commit

public void commit()

select

public com.digitalscores.jcdatabase.JCRow[] select()
Performs the SQL statement "select * from [this table]" and returns an array of JCRow objects.


select

public com.digitalscores.jcdatabase.JCRow[] select(java.lang.String columnName,
                                                   java.lang.String operator,
                                                   int match)
Performs the SQL statement "select * from [this table] where columnName [operator] match" and returns an array of JCRow objects. Valid operators are =, >, <, >=, <=. When '=' is used with strings the comparison is case sensitive. For case-insensitive comparisons use the operator 'like'.


select

public com.digitalscores.jcdatabase.JCRow[] select(java.lang.String columnName,
                                                   java.lang.String operator,
                                                   float match)
Performs the SQL statement "select * from [this table] where columnName [operator] match" and returns an array of JCRow objects.


select

public com.digitalscores.jcdatabase.JCRow[] select(java.lang.String columnName,
                                                   java.lang.String operator,
                                                   java.lang.String match)
Performs the SQL statement "select * from [this table] where columnName [operator] match" and returns an array of JCRow objects. Valid operators are =, >, <, >=, <=. When '=' is used with strings the comparison is case sensitive. For case-insensitive comparisons use the operator 'like'. All select methods order the results by the first column of the table by default. Use orderBy(..) to order by other columns.


select

public com.digitalscores.jcdatabase.JCRow[] select(java.lang.String columnName1,
                                                   java.lang.String operator1,
                                                   java.lang.String match1,
                                                   java.lang.String combination,
                                                   java.lang.String columnName2,
                                                   java.lang.String operator2,
                                                   java.lang.String match2)
Performs the SQL statement "select * from [this table] where columnName1 [operator1] match1 [combination] columnName2 [operator2] match2" and returns an array of JCRow objects. Valid values for 'combination' are "AND" or "OR". This method requires that the table has a column of type AUTOINTEGER that acts as the primary key.


setRelationship

public com.digitalscores.jcdatabase.JCRow[] setRelationship(com.digitalscores.jcdatabase.JCRow[] result1,
                                                            java.lang.String combination,
                                                            com.digitalscores.jcdatabase.JCRow[] result2)
Allows more complex select statements to be formed by combining the results of two simpler select statements. Takes either the conjuction (if combination.equals("AND")) or the union (if combination.equals("OR")) of two arrays of JCRow objects, useful for allowing select statements of arbitary complexity to be constructed by combining result sets of simpler select statements. The current implementation requires both tables to have a column of type AUTOINTEGER which functions as the primary key for which comparisons are made between the two JCRow[] arrays.


select

public com.digitalscores.jcdatabase.JCRow[] select(java.lang.String columnOfThisTable,
                                                   java.lang.String columnOfOtherTable,
                                                   com.digitalscores.jcdatabase.JCRow[] rowSetFromOtherTable)
Method to allow fast join operations. Returns rows from this table in which values under columnOfThisTable match at least one value of columnOfAnotherTable and restricted further to rows within rowSetFromOtherTable.

For example, to perform "select NAME from PERSON P, ADDRESS A where P.ID = A.PERSON_ID and ADDRESS.SUBURB = 'Bridgewater'" and display all of the results, you can make the following method calls:

JCTable address = new JCTable("address");
JCTable name = new JCTable("name");
JCRow result[] = select("ID", "PERSON_ID", address.select("SUBURB", "=", "Brigdewater"));
for (int i = 0; i < result.length; i++) {
  System.out.println(result[i].name);
}


select

public com.digitalscores.jcdatabase.JCRow[] select(java.lang.String columnOfThisTable,
                                                   java.lang.String columnOfOtherTable,
                                                   com.digitalscores.jcdatabase.JCTable otherTable)
Convenience method that is similar to: "select * from [this table], otherTable where [this table].columnOfThisTable = otherTable.columnOfOtherTable. The method returns rows from this table in which values under columnOfThisTable matches at least one value under columnOfOtherTable.

The method is implementated by calling the select(String columnOfThisTable, String operator, columnOfOtherTable, rowSetFromOtherTable) method and replacing rowSetFromOtherTable with otherTable.select();


validateOperator

public boolean validateOperator(java.lang.String operator)
Returns true if and only if the supplied operator is a valid operator. Valid operators are "=", "<=", ">=", ">", "<" and "<>".


delete

public int delete(java.lang.String columnName,
                  java.lang.String operator,
                  int match)
Performs the SQL statement "delete from [this table] where columnName [operator] match and returns the number of rows deleted.


delete

public int delete(com.digitalscores.jcdatabase.JCRow[] rowsToDelete)
Deletes arbitrary rows from the result of a select(..) method call and returns the number of rows deleted. The method requires that this table has a column of type AUTOINTEGER. Example of use:

 JCRow[] rowsToDelete = people.select("FIRSTNAME", "=", "Julian", "AND", "LASTNAME", "=", "Cochran");
 people.delete(rowsToDelete);
 


delete

public int delete(java.lang.String columnName,
                  java.lang.String operator,
                  float match)
Performs the SQL statement "delete from [this table] where columnName [operator] match and returns the number of rows deleted.


delete

public int delete(java.lang.String columnName,
                  java.lang.String operator,
                  java.lang.String match)
Performs the SQL statement "delete from [this table] where columnName [operator] match and returns the number of rows deleted.


update

public int update(java.lang.String columnToChange,
                  int newValue,
                  java.lang.String columnNameToMatch,
                  java.lang.String operator,
                  int match)
Changes 'columnNameToChange' to 'newValue' for all rows that yield a match between 'columnNameToMatch', 'operator' and 'match'. Valid operators are "=", "<=", ">=", ">", "<" and "<>" and "like". Returns the number of rows updated.


update

public int update(java.lang.String columnToChange,
                  java.lang.String newValue,
                  java.lang.String columnNameToMatch,
                  java.lang.String operator,
                  int match)
Changes 'columnNameToChange' to 'newValue' for all rows that yield a match between 'columnNameToMatch', 'operator' and 'match'. Valid operators are "=", "<=", ">=", ">", "<" and "<>" and "like". Returns the number of rows updated.


update

public int update(java.lang.String columnToChange,
                  int newValue,
                  java.lang.String columnNameToMatch,
                  java.lang.String operator,
                  java.lang.String match)
Changes 'columnNameToChange' to 'newValue' for all rows that yield a match between 'columnNameToMatch', 'operator' and 'match'. Valid operators are "=", "<=", ">=", ">", "<" and "<>" and "like". Returns the number of rows updated.


update

public int update(java.lang.String message,
                  java.lang.String columnNameToMatch,
                  java.lang.String operator,
                  java.lang.String match)
Updates multiple attributes of multiple records with a single pass of the database file.

Updates rows of data using the syntax for 'message' as: "column1=value1 column2=colum2 ...".

The format uses '=' characters to separate colummn names and values and uses ' ' characters to separate each column-name value pair. Examples of invalid strings include "column1 = value1 column2 = value2" and "column1='value1' column2='value2'". If you wish to update ' ' characters within values then use the '_' character.


update

public int update(java.lang.String columnToChange,
                  java.lang.String newValue,
                  java.lang.String columnNameToMatch,
                  java.lang.String operator,
                  java.lang.String match)
Changes 'columnNameToChange' to 'newValue' for all rows that yield a match between 'columnNameToMatch', 'operator' and 'match'. Valid operators are "=", "<=", ">=", ">", "<" and "<>" and "like". Returns the number of rows updated.

The method is equivalent to the SQL statement: update [this table] set 'columnNameToChange' = 'newValue' where 'columnNameToMatch' [operator] 'match'"


insert

public int insert(com.digitalscores.jcdatabase.JCRow newRow)
Inserts a supplied row of data as a JCRow into the table. If the table has an autonumber column then this method returns the value of that column for the newly inserted row or -1 if there was an error during the insert.


insert

public int insert(java.lang.String message)
Inserts a row of data into the table using the syntax: "column1=value1 column2=colum2 ...".

The format uses '=' characters to separate colummn names ane values and uses ' ' characters to separate each pair of values to be set. Examples of invalid strings include "column1 = value1 column2 = value2" and "column1='value1' column2='value2'". If you wish to insert ' ' characters within values then use the '_' character.

Within your Java code it can be more convenient to create a JCRow and use the JCRow.setString and JCRow.setInt methods to define values within the new row and JCTable.insert(JCRow newRow) to insert the new JCRow into the table. If the table has an autonumber column then this method returns the value of that column for the newly inserted row or -1 if there was an error during the insert.


stringWithTrailingCharactersTrimmed

public static java.lang.String stringWithTrailingCharactersTrimmed(java.lang.String message,
                                                                   char c)
Deletes characters (usually c = ' ') from the end of 'message' until the first character other than c is reached. This method is useful for removing trailing spaces.


fixedLength

public static java.lang.String fixedLength(java.lang.String text,
                                           int newSize)
Adds or deletes ' ' characters from the end of the string to fix it to 'newSize'


maxInteger

public int maxInteger(java.lang.String columnName)
Returns the maximum integer value in the table for a given column name. If the column is not an integer type then -1 is returned.


sortBy

public com.digitalscores.jcdatabase.JCRow[] sortBy(com.digitalscores.jcdatabase.JCRow[] rowToSort,
                                                   java.lang.String columnToSortBy)
Sorts an arrow of JCRow objects by any column. Returns a new sorted array that points to the same JCRow objects within the list provided, in other words a new array is created but new JCRow objects are not created. Sorts integer columns in ascending order and string columns alphabetically. Returns null if columnToSortBy is not a valid column name for the array of rows.


printAllData

public void printAllData()
Displays all column names and all rows of data to System.out using a tab separated format.


like

public static boolean like(java.lang.String string1,
                           java.lang.String string2)
Returns true iff the two strings are equal without case sensitivity and after '_' characters are converted to spaces.


characterReplace

public static java.lang.String characterReplace(java.lang.String message,
                                                char charToFind,
                                                char replaceWith)