TGen - JDBC Database Code Generator

By Vasian CEPA [email protected]

How to set up org.peoplink.database.TGen to generate the code

To setup manualy, if it does not exist, created create the directory "/org/peoplink/database/."

Put TGen.java there and compile it:

javac TGen.java

Then run it as:

java org.peoplink.database.TGen

Note than before you do this you must setup your classpath variable as necessary. The classpath should have the directory classes in its path, and if you are using InstantDB as database its jar files.

TGen uses the same file structure as HDB. Thus it uses 'hdb.txt" to set database connection parameters. Normally you should edit "hdb.txt" to fit your database. It also uses "htypes.txt" file on the same directory. TGen also requires 'HUtils.java' and 'HDB.java' in order to compile. These files are part of "org.peoplink.hdb" package. They must be under the correct package directory structure and in CLASSPATH, in order for TGen to be succesfuly compiled.

Download

Here is the source for TGen.java. It is has one class org.peoplink.database.TGen

Generated Java classes

After you start TGen, it will scan the database, showing progress information in stdout. It will generate Java classes for database connection under /org/peolink/database folder. These classes belong to org.peoplink.database package.

For every table two classes will be generated. One is called ‘TableNameData.java’ and contains plain data objects, that are used by the other class, ‘TableName.java’.

The ‘TableNames.java’ classes have code to access database and return objects to user, and also to update/insert and delete records. They inherits behaviour from the abstract TableCode generated class (file TableCode.java). These methods of TableCode.java can be used in code with objects of derived classes:

• public static String getTGenVersion() – return TGen version. Normally ‘1.0’. Your code should theoretically test if classes it is using are of this version or of a newer version. Practically this test can be omitted for now.
• public void setWhereCondition(String cond) – set the condition of the sql, that is the WHERE clause, for the sql used by public Vector getData(Connection con) , public Vector getPrimaryKeysData(Connection con), and public void delete(Connection con) methods. The argument "cond" is the WHERE clause of the sql, without "WHERE".

These abstract methods are overriden in derived classes:

• public Vector getData(Connection con) throws Exception – returns a vector of ‘TableNameData’ objects, takes from a ResultSet, whose where condition is set by setWhereCondition(). If the condition is not set, then all the table data will be returned into a vector. To use the vector element cast them to the corresponding ‘TableNameData’ class.
• public Vector getPrimaryKeysData(Connection con) throws Exception – basically the same as getData(), but returns a vector made up of TableData objects, but with only their variables that part of the primary key filled up with data and other variables set to null, or zeros (that is the default java initialization for that type). You can use this method to get a vector of objects to be used with "int delete(con, pkData)" method. The result can be filtered by setting the ‘where’ clause via setWhereCondition() method.
• public int update2(Connection con, Vector data) throws Exception - Every 'TableData' object of data vector is inserted in database if it does not exists, otherwise it is updated.
• public int update(Connection con, Object obj) throws Exception - updates/inserts a single object of 'TableNameData' type. If the record represented by TableNameData object exists, it will be updated based on ‘data’ object data. If data-object does not exists it will be inserted. Uses exists() and setCurrentRecordData() methods internally. Used by the generic form of update().
• public int delete(Connection con, Vector pkData) throws Exception – deletes a set of rows from the table. The ‘pkData’ vector is the result of getPrimaryKeys() method, or a vecotor returned by getData() method. I recomend to use this method with vectors from getPrimaryKeys() method, since it is optimized not to read any unnecessary data.
• public int delete(Connection con) throws Exception – deletes a set of rows from a table, filtered by the setWhereCondition() method. If you call setWhereCondition() with "" or null, all records will be deleted.
• public void setWhereCondition2(Object obj) throws Exception - uses a dataobject obj of the 'TableNameData' class to set the WHERE condition. Only primary key attributes are used. Uses setWhereCondition(String) internally.
• public boolean exists(Connection con, Object obj) throws Exception – returns true if the record represented by ‘TableNameData’ type, 'obj' object is found in TableName table. This is used by update(), but can also be used direclty.
• public Vector validate(Object obj) – test will the fields of the dataobject 'obj' are within the bounds allowed by the database, returns a Vector of errors. Normally this code tests only the string fields.
• public Object getCurrentRecordData(ResultSet rs) throws Exception – reads current row from a ResultSet given as an argument. The result is a ‘TableNameData’ object. This function is used by getData(), but if necessary it can be used direclty.
• public void setCurrentRecordData(PreparedStatement pstmt, Object obj) throws Exception – fills a PreparedStatement object with data form ‘TableNameData’ obj object. Used by update().

Note that 'obj' objects should be of the same type as 'TableNameData' objects for a given 'TableName' class. A 'ClassCastException' will be thrown if wrong type of object 'obj' is passed. In the previous revision of TGen, 'TableNameData' objects we used direclty and may of these methods were not accessible through the class hierarchy. This revision uses run-time object checking, compared to compile-time object checking the previous revision used. This adds more fleksibility to the code usage in generic (polimorphic) methods. (Some methods have an index '2' added since Vector is a kind of Object, so that no overriding can take place.)

The inheritance of Table code classes allow generic methods to be writen, that work with more that a type of dataobject. The example below is such a method, used to delete data in a module, in both local and remote databases (a simplified version is given here):

public void deleteObjects(PeoplinkServer server, Connection con, TableCode tc, Vector data) {}
	int tryCount = 0; // we try twice in case of a rmi error
	while(tryCount < 2){
		try{
			server.delete(name, password, data); // this calls our delete(con, pkData) method internally
			tryCount = 3;
		} catch(Exception e){
			SUtils.log(e.getMessage());
			tryCount++;
		}
	}
	if(tryCount == 3) tc.delete(con, data); // delete local data only if remote delete succeeds
}	

// this can be used as:

Images im = new Images();
Stories st = new Stories();
Vector data = null;

im.setWhereCondition("ImageKey IN (10001, 10002)");
data = im.getPrimaryKeysData();
deleteObjects(server, con, im, data);

st.setWhereCondition("StoryKey IN (10003, 10004)");
data = st.getPrimaryKeysData(); // this line can be included in deleteObjects() :-))
deleteObjects(server, con, st, data);

Some methods like delete(), update() etc., return an integer value which is the row count of the records afected by that operation.

Sample code usage

// obtain a connection object somewhere, it will not be closed by our methods
java.sql.Connection con = ...;

// TO GET DATA

// get one or more objects and use them

Images im = new Images();

im.setWhereCondition("ImageKey  IN (3, 6)");
java.util.Vector data = im.getData(con);
java.util.Enumeration e = data.elements();

// data.size() has the record count if needed

ImagesData imd = null;
while(e.hasMoreElements()){
	imd = (ImagesData)e.nextElement();
	System.out.println(imd.Description);
	System.out.println(imd.TPCode);
	// use any other fields ...
}


// TO DELETE DATA

// to delete the above objects
// or change the set of the objects afected by recalling 
// im.setWhereCondition("ImageKey = 2"); \
// call setWhereCondition(""); to effect all records
im.delete(con);

// TO UPDATE - you must have some ImagesData (imd) object first

// change some value and update object in database (the record)
imd.Description = "Peoplink Logo"; // note no set/get methods here
imd.ImageBlob = org.peoplink.launcher.LUtils.readFile("./config/cl.jpg");
im.update(con, imd); // only this call is needed to make an update!

// TO INSERT

// build a new object and insert it
// take care to fill in all fields that are part of the primary key
ImagesData imd2 = new ImagesData();
imd2.Description = "Image 2";
img2.TPCode = ... // some tp code 
img2.ImageKey = 2; // note: it may be an autoincrement field!
img2.ImageBlob = org.peoplink.launcher.LUtils.readFile("./config/launcher.gif");
// this is byte[] type
im.update(con, imd2); // this does now an insert!

Data Types

These five basic types are used: String, int, boolean, double, byte[]. See the appropriate TableNameData.java to find how each database table column is mapped.

Some details: datetime-s are get/set as String (correct datetime format is "yyyy-mm-dd hh:nn:ss"), binary types as byte[].

Maintaining the code written with org.peoplink.database classes

The TGen code may change in the future as other features will be needed or if bugs are found. To ensure that your code is compatible with later versions always use the methods of the interface, as they are described here.

Do not rely on the internal arrangement of the columns inside the generated methods. That may change. If you need to know the order of the columns (normally this is not needed) use org.peoplink.hdb.HUtils methods.

Even if changes are made to the TGen, its present interface will be kept the same. If you use only the methods of the interface without messing up into their details, you can ensure that, your code will even run with a new set of generated classes of TGen, perhaps from a newer database version.

END