com.strangelight.db
Class TableRow

java.lang.Object
  |
  +--com.strangelight.db.TableRow

Direct Known Subclasses:

JoinRow, KeyedRow, OwnableRow

public abstract class TableRow

extends java.lang.Object

A single row from a single table in a SQL database.

Applications typically encapsulate a specific SQL table by subclassing TableRow and defining a getTableName() method, a constructor or constructors which call #fetchFromDB( String ), and accessor methods which wrap getString( String ), setString( String, String ), getObject( String ), and/or setObject( String, Object ).

See Also:

KeyedRow

Constructor Summary

protected	TableRow()
	TableRow(java.lang.String where_clause)

Method Summary

void	commit() Writes any changes made to this TableRow object back to the database.
void	drop() Deletes this TableRow object's row from the database.
void	finalize()
protected java.util.HashMap	getFields()
protected java.lang.Object	getObject(java.lang.String column_name) Gets an Object from the database row.
protected java.lang.String	getString(java.lang.String column_name) Gets a String value from the database row.
protected abstract java.lang.String	getTableName()
protected java.lang.String	getWhereClause()
protected void	setObject(java.lang.String column_name, java.lang.Object the_object) Stores an Object into the specified field of this TableRow object.
protected void	setString(java.lang.String column_name, java.lang.String the_string) Stores a String into the specified field of this TableRow object.

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TableRow

protected TableRow()

TableRow

public TableRow(java.lang.String where_clause)

Parameters:

where_clause - the SQL WHERE clause used to retrieve this row. (For example, where_clause() might be "name='Aleister'".) If this clause returns multiple rows, only the first one will be used. Warning: no input validation is done on this String. Calling this method with a String that is not a valid SQL WHERE clause will produce unpredictable results!

Method Detail

getFields

protected java.util.HashMap getFields()

Returns:

a HashMap representing the fields in this row of the database. (Keys are column names, Values are field values.)

getWhereClause

protected java.lang.String getWhereClause()

Returns:

the WHERE clause of the SQL SELECT command which was used to retrieve this TableRow object from the database, or null if this is a newly-created row which was not retrieved from the database. For example, getWhereClause() might return "name='Aleister'".

getTableName

protected abstract java.lang.String getTableName()

Returns:

the name of the table that this TableRow class encapsulates. Subclasses typically implement this method by simply returning a static String object. For example, a typical implementation might be:

                         protected String getTableName() { return "MyTable"; }
                 

getString

protected java.lang.String getString(java.lang.String column_name)

Gets a String value from the database row.

Subclasses of TableRow typically implement accessor methods as simple wrappers of getString. For example, a subclass of TableRow might define an accessor method like this:

                         public String get_name() {
                                 getString( "name" );
                         }
                 

Parameters:

column_name - the database column to retrieve.

Returns:

a String representation of the value of this database field. E.g. getString("name") might return "Aleister".

setString

protected void setString(java.lang.String column_name,
                         java.lang.String the_string)

Stores a String into the specified field of this TableRow object. Note that this value will not be written back to the database until this object is garbage-collected, or until this object's commit() method is called.

Subclasses of TableRow typically implement accessor methods as simple wrappers of setString. For example, a subclass of TableRow might define an accessor method like this:

                         public void set_name( String n ) {
                                 setString( "name", n );
                         }
                 

Parameters:

column_name - the column in which to store the string value.

the_string - the value to store.

getObject

protected java.lang.Object getObject(java.lang.String column_name)

Gets an Object from the database row.

[[ THIS METHOD IS NOT YET FULLY IMPLEMENTED! ]]

Parameters:

column_name - the database column to retrieve.

Returns:

an Object representing the value of this database field.

See Also:

getString(java.lang.String)

setObject

protected void setObject(java.lang.String column_name,
                         java.lang.Object the_object)

Stores an Object into the specified field of this TableRow object. Note that this value will not be written back to the database until this TableRow object is garbage-collected, or until this object's commit() method is called.

[[ THIS METHOD IS NOT YET FULLY IMPLEMENTED! ]]

Parameters:

column_name - the column in which to store the string value.

the_object - the value to store.

See Also:

setString(java.lang.String, java.lang.String)

commit

public void commit()

Writes any changes made to this TableRow object back to the database.

This method is called automatically during garbage-collection.

finalize

public void finalize()

Overrides:

finalize in class java.lang.Object

drop

public void drop()

Deletes this TableRow object's row from the database.

Note that, unlike most other TableRow methods, drop() alters the database immediately, rather than deferring modifications until garbage-collection or until the next call to commit().