Let us assume that we have a MySQL server located at http://mysql.somedomain.com:3306. Let's also assume that we have a one table database (test) on that server. The schema for test looks something like this:

Cartographer generates three types of classes for use in your applications.

Base Class	This is the class that all Data and Factory classes extend. It contains constants and 'global' fields and methods.
Data Class	Encapsulates the data found in a given table in the database. It contains setter/getter and persistence methods.
Factory Class	Provides the methods needed for performing queries with given search criteria.

2.0 Generating Java Objects:

Edit/Create a config file. An example config file is located in the config directory where you installed Cartographer. Update this config file for the sample database with the following:

See the INSTALL document for complete installation and setup instructions. The example database has one (1) table, so Cartographer will generate three (3) files. They will be found in the 'outputPath' specified in the config file. Compiling the generated java files is very simple. The DBObject.java must be compiled first, as the other files depend upon it. The purpose and structure of each of the files generated by Cartographer is detailed in the next section.


3.0 Using Generated Class Files:

The three java files generated by Cartographer from our sample database are:

DBObject.java (Base Class)	Source  Javadoc
The DBObject.java file is always generated once when Cartographer is run, regardless of the number of tables in the database. The DBObject class is an abstract class that is used to hold utility functions and constants common to all of the generated Data and Factory classes.
MyTable.java (Data Class)	Source  Javadoc
The MyTable.java file contains member fields that represent the various columns in the database table for which it was generated. This class also contains the persistence methods necessary for creating, updating, and deleting MyTable records in the database.
MyTableFactory.java (Factory Class)	Source  Javadoc
The MyTableFactory.java file contains the search methods needed to locate specific sets of MyTable records within the database.

3.1 Creating New Records

To create a new MyTable record with the default constructor:

// Setup our field values. Integer id = new Integer("10"); String name = 'This is the Name'; String description = 'This is the Description'; // Instantiate a new MyTable object. MyTable t = new MyTable(); // Set all of the fields to the desired values. t.setId(id); t.setName(name); t.setDescription(description); // Create the SQL record. t.create();

To create a new MyTable record with the default constructor:

// Setup our field values. Integer id = new Integer("10"); String name = 'This is the Name'; String description = 'This is the Description'; // Instantiate a new MyTable object and pass our field values // to the constructor. MyTable t = new MyTable(id,name,description); // Create the SQL record. t.create();

Equivalent SQL statement:
INSERT INTO t_my_table (c_id,c_name,c_description) VALUES(10,'This is the Name','This is the Description');


3.2 Updating Existing Records

To update an existing MyTable record:

// Given that the object (MyTable) t exists. // Assume that object (MyTable) t has primary key (id = 10). // Set the values that are being updated. t.setName("New Name"); t.setDescription("New Description"); // Update the sql record t.update();

Equivalent SQL statement:
UPDATE t_my_table SET c_name = 'New Name' ,c_description = 'New Description' WHERE c_id = 10;

If the primary key value of the data object being manipulated is changed, and a record with that new primary key value does not exist, then an SQLException will be thrown.


3.3 Deleting Records

To delete an existing MyTable record:

// Given that the object (MyTable) t exists. // Assume that object (MyTable) t has primary key (id = 10). // Delete the sql record t.destroy();

Equivalent SQL statement:
DELETE FROM t_my_table WHERE c_id = 10;

3.4 Querying Records

To perform a simple query using only one field in the criteria:

// Setup the search criteria we will be using. Integer id = new Integer("10"); // Instantiate a new MyTableFactory object. MyTableFactory mtf = new MyTableFactory(); // Set the search criteria. mtf.findById(id); // Query the factory object for the given record(s). Vector myTableVector = mtf.search();

Equivalent SQL statement:
SELECT c_id,c_name,c_description FROM t_my_table WHERE c_id = 10;

If mtf.search() is called without specifying any criteria, then all MyTable records will be returned. The default behavior of searches is to assume that the '=' operator is to be used. If another operator is desired the following can be used:

// Set the search criteria. mtf.findById('>',id); // Query the factory object for the given record(s). Vector myTableVector = mtf.search();

Equivalent SQL statement:
SELECT c_id,c_name,c_description FROM t_my_table WHERE c_id = 10;

To perform a simple query using multiple fields in the criteria:

// Setup the search criteria we will be using. Integer id = new Integer("10"); String name = 'This is the Name'; // Instantiate a new MyTableFactory object. MyTableFactory mtf = new MyTableFactory(); // Set the search criteria. mtf.findById(id); mtf.findByName(name); // Query the factory object for the given record(s). Vector myTableVector = mtf.search();

Equivalent SQL statement:
SELECT c_id,c_name,c_description FROM t_my_table WHERE c_id = 10 AND c_name = 'This is the Name';

The default behavior for searches involving multiple fields in the criteria is to use the boolean operator AND on the fields. If other boolean operators are desired the following can be used:

// Set the search criteria. mtf.findById('>',id,'OR'); mtf.findByName(name); // Query the factory object for the given record(s). Vector myTableVector = mtf.search();

Equivalent SQL statement:
SELECT c_id,c_name,c_description FROM t_my_table WHERE c_id > 10 OR c_name = 'This is the Name';

To perform a complex query using multiple fields with grouped operators:

// Setup the search criteria we will be using. Integer id = new Integer(10) String name = 'This is the Name'; String description = 'This is the Description'; // Instantiate a new MyTableFactory object. MyTableFactory mtf = new MyTableFactory(); // Setup the search criteria using an SQL WHERE clause. // This WHERE clause takes the same form as an SQL statement // passed to a PreparedStatement object. mtf.findByCustomSQL("c_id = ? OR ( c_name = ? AND c_description = ?)"); // Set the objects for the query. The setObject calls must // be in the same order as the String passed to the // findByCustomSQL() method. mtf.setObject(id); mtf.setObject(name); mtf.setObject(description); // Query the factory object for the given record(s). Vector myTableVector = mtf.search();

Equivalent SQL statement:
SELECT c_id,c_name,c_description FROM t_my_table WHERE c_id = 10 OR ( c_name = 'This is the Name' AND c_description = 'This is the Description');