Package org.kissweb.database

Class Record

java.lang.Object

org.kissweb.database.Record

All Implemented Interfaces:

AutoCloseable

public class Record
extends Object
implements AutoCloseable

Instances of this class represent a single row in a table or a row in a result set.

There are two ways of getting instances of this class. The first way is by doing a select against the database. In that case, a Record or list of Record's is returned. The other way is to create a new row or record for insertion into the database. In that case, one should create the new Record instance as follows:

Record rec = db.newRecord('myTable');

where db is a Connection instance.

See Also:

• Connection.newRecord(String)
• Connection.fetchAll(String, Object...)
• Connection.fetchOne(String, Object...)
• Command.fetchAll(String, Object...)
• Command.fetchOne(String, Object...)

Method Summary

Modifier and Type	Method	Description
boolean	addRecord()	Inserts a new row into the database by creating an executing an SQL statement.
Object	addRecordAutoInc()	Works like addRecord() except that it returns the value of the serial/primary key column that the database used for the new record.
org.json.JSONObject	addToJSON(org.json.JSONObject obj)	Add columns of a Record to an existing JSON object.
Record	clear()	Erases all the column information associated with a Record instance.
void	close()	Closes any open prepared statements against this record.
boolean	columnExists(String cname)	Tests if a given column exists.
void	copy(Record rec)	Copy all columns from rec to 'this'
void	copyCorresponding(Record fromRec)	Copy all columns from fromRec to this that have the same column names and types
void	delete()	Performs an SQL delete on the record.
Object	get(String cname)	Get the value of a column as an Object.
AbstractMap<String,Object>	getAllColumns()	Returns a map of all the columns in the record.
Boolean	getBoolean(String cname)	Return the Boolean value of the named column.
byte[]	getByteArray(String cname)	Return the byte[] value of the named column.
Character	getChar(String cname)	Return the Character value of the named column.
Connection	getConnection()	Returns the Connection instance associated to this Record instance.
int	getDateAsInt(String cname)	Return the date in an int formatted as YYYYMMDD for the named column.
Date	getDateOnly(String cname)	Return the java.util.Date value of the named column.
Date	getDateTime(String cname)	Return the java.util.Date value of the named column.
long	getDateTimeMS(String cname)	Return the date/time value as the number of milliseconds since 1970 UTC.
Double	getDouble(String cname)	Return the Double value of the named column.
Float	getFloat(String cname)	Return the Float value of the named column.
Integer	getInt(String cname)	Return the Integer value of the named column.
Long	getLong(String cname)	Return the Long value of the named column.
Short	getShort(String cname)	Return the Short value of the named column.
String	getString(String cname)	Return the String value of the named column.
String	getTableName()	Returns the name of the table associated to this Record instance.
long	getTime(String cname)	Return the long value of the named column.
ZonedDateTime	getZonedDateTime(String cname)	Return the ZonedDateTime value of the named column.
Record	set(String name, Object val)	Set the value of a column in the record.
Record	setDateOnly(String name, int dat)	Set the date portion of the Date only (no time info) value of a column in the record.
Record	setDateOnly(String name, Date val)	Set the date portion of the Date only (no time info) value of a column in the record.
Record	setDateTime(String name, long val)	Set the date and time value of a column in the record.
Record	setDateTime(String name, ZonedDateTime val)	Set the date and time value of a column in the record.
Record	setDateTime(String name, Date val)	Set the date and time value of a column in the record.
Record	setTime(String name, long dat)	Set the time value in milliseconds
org.json.JSONObject	toJSON()	Convert a record into a JSON object.
static org.json.JSONArray	toJSONArray(List<Record> recs)	Utility method to convert a list of Record's into a JSON array of JSON objects.
void	update()	Performs an SQL update on the record.

Methods inherited from class java.lang.Object

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

Method Details

set

public Record set(String name,
 Object val)

Set the value of a column in the record. This method should not be used with dates or times.

Parameters:

name - the column name

val - the value to set. Can be any type.

Returns:

See Also:

• Cursor.set(String, Object)
• setDateOnly(String, java.util.Date)
• setDateTime(String, java.util.Date)

setDateOnly

public Record setDateOnly(String name,
 Date val)

Set the date portion of the Date only (no time info) value of a column in the record.

Parameters:

name - the column name

val - the value to set.

Returns:

See Also:

• Cursor.set(String, Object)
• set(String, Object)
• setDateTime(String, java.util.Date)
• setDateOnly(String, int)
• setTime(String, long)

setDateOnly

public Record setDateOnly(String name,
 int dat)

Set the date portion of the Date only (no time info) value of a column in the record.

Parameters:

name - the column name

dat - the value to set. Format is YYYYMMDD

Returns:

See Also:

• setDateOnly(String, java.util.Date)
• setTime(String, long)
• Cursor.set(String, Object)
• set(String, Object)
• setDateTime(String, java.util.Date)

setTime

public Record setTime(String name,
 long dat)

Set the time value in milliseconds

Parameters:

name - the column name

dat - the value to set in milliseconds

Returns:

See Also:

• setDateOnly(String, java.util.Date)
• Cursor.set(String, Object)
• set(String, Object)
• setDateTime(String, java.util.Date)

setDateTime

public Record setDateTime(String name,
 Date val)

Set the date and time value of a column in the record.

Parameters:

name - the column name

val - the value to set.

Returns:

See Also:

• Cursor.set(String, Object)
• setDateOnly(String, java.util.Date)
• setTime(String, long)
• set(String, Object)

setDateTime

public Record setDateTime(String name,
 ZonedDateTime val)

Set the date and time value of a column in the record. This is especially useful for columns with timezone information.

If the underlying database does not actually store a timezone (like PostgreSQL) then this method will fail.

Parameters:

name - the column name

val - the value to set.

Returns:

See Also:

• Cursor.set(String, Object)
• setDateOnly(String, java.util.Date)
• setTime(String, long)
• set(String, Object)

setDateTime

public Record setDateTime(String name,
 long val)

Set the date and time value of a column in the record.

Parameters:

name - the column name

val - number ov milliseconds since 1970 UTC

Returns:

See Also:

• Cursor.set(String, Object)
• setDateOnly(String, java.util.Date)
• setTime(String, long)
• set(String, Object)

get

public Object get(String cname)
           throws SQLException

Get the value of a column as an Object. Other methods that get expected types are typically used over this method.

Parameters:

cname -

Returns:

Throws:

SQLException

See Also:

• Cursor.get(String)
• getShort(String)
• getLong(String)
• etc.

getBoolean

public Boolean getBoolean(String cname)
                   throws SQLException

Return the Boolean value of the named column.

Parameters:

cname -

Throws:

SQLException

columnExists

public boolean columnExists(String cname)
                     throws SQLException

Tests if a given column exists. Returns true of the column exists, and false if it does not.

Parameters:

cname -

Returns:

Throws:

SQLException

getShort

public Short getShort(String cname)
               throws SQLException

Return the Short value of the named column. A null is returned on null valued columns.

Parameters:

cname -

Returns:

Throws:

SQLException

See Also:

• Cursor.getShort(String)

getInt

public Integer getInt(String cname)
               throws SQLException

Return the Integer value of the named column. A null is returned on null valued columns.

Parameters:

cname -

Returns:

Throws:

SQLException

See Also:

• Cursor.getInt(String)

getLong

public Long getLong(String cname)
             throws SQLException

Return the Long value of the named column. A null is returned on null valued columns.

Parameters:

cname -

Returns:

Throws:

SQLException

See Also:

• Cursor.getLong(String)

getFloat

public Float getFloat(String cname)
               throws SQLException

Return the Float value of the named column. A null is returned on null valued columns.

Parameters:

cname -

Returns:

Throws:

SQLException

See Also:

• Cursor.getFloat(String)

getDouble

public Double getDouble(String cname)
                 throws SQLException

Return the Double value of the named column. A null is returned on null valued columns.

Parameters:

cname -

Returns:

Throws:

SQLException

See Also:

• Cursor.getDouble(String)

getDateOnly

public Date getDateOnly(String cname)
                 throws SQLException

Return the java.util.Date value of the named column. Just a date and no time. A null is returned on null valued columns.

Parameters:

cname -

Returns:

Throws:

SQLException

See Also:

• getDateAsInt(String)
• Cursor.getDateOnly(String)
• getDateTime(String)

getDateAsInt

public int getDateAsInt(String cname)
                 throws SQLException

Return the date in an int formatted as YYYYMMDD for the named column. A 0 is returned on null valued columns.

Parameters:

cname -

Returns:

date format YYYYMMDD

Throws:

SQLException

See Also:

• getDateOnly(String)
• Cursor.getDateOnly(String)
• getDateTime(String)

getDateTime

public Date getDateTime(String cname)
                 throws SQLException

Return the java.util.Date value of the named column. If the column had timezone information, it is stripped off. A null is returned on null valued columns.

Parameters:

cname -

Returns:

Throws:

SQLException

See Also:

• getZonedDateTime(String)
• Cursor.getDateOnly(String)
• getTime(String)
• getDateTimeMS(String)

getZonedDateTime

public ZonedDateTime getZonedDateTime(String cname)
                               throws SQLException

Return the ZonedDateTime value of the named column. Time zone information is preserved. A null is returned on null valued columns.

If the underlying database does not actually store a timezone (like PostgreSQL) then this method will fail.

Parameters:

cname -

Returns:

Throws:

SQLException

See Also:

• getDateTime(String)
• getDateTimeMS(String)
• getTime(String)

getDateTimeMS

public long getDateTimeMS(String cname)
                   throws SQLException

Return the date/time value as the number of milliseconds since 1970 UTC. A 0 is returned on null valued columns.

Parameters:

cname -

Returns:

Throws:

SQLException

See Also:

• getDateOnly(String)
• getTime(String)
• getDateTime(String)

getTime

public long getTime(String cname)
             throws SQLException

Return the long value of the named column. Only time information is returned. A 0 is returned on null valued columns.

Parameters:

cname -

Returns:

time in milliseconds

Throws:

SQLException

See Also:

• getDateOnly(String)

getString

public String getString(String cname)
                 throws SQLException

Return the String value of the named column. A null is returned on null valued columns.

Parameters:

cname -

Returns:

Throws:

SQLException

See Also:

• Cursor.getString(String)

getChar

public Character getChar(String cname)
                  throws SQLException

Return the Character value of the named column. A null is returned on null valued columns.

Parameters:

cname -

Returns:

Throws:

SQLException

See Also:

• Cursor.getChar(String)

getByteArray

public byte[] getByteArray(String cname)
                    throws SQLException

Return the byte[] value of the named column. A null is returned on null valued columns.

Parameters:

cname -

Returns:

Throws:

SQLException

See Also:

• Cursor.get(String)

clear

public Record clear()

Erases all the column information associated with a Record instance.

Returns:

this

update

public void update()
            throws SQLException

Performs an SQL update on the record. This is done by creating an actual update statement and executing it against the database. It does not affect any cursors.

This method is smart. It only updates the fields that have changed, and if none have, it does nothing.

Throws:

SQLException

See Also:

• Connection.commit()

delete

public void delete()
            throws SQLException

Performs an SQL delete on the record. This is done by creating an actual update statement and executing it against the database. It does not affect any cursors.

Throws:

SQLException

See Also:

• Connection.commit()

addRecordAutoInc

public Object addRecordAutoInc()
                        throws SQLException

Works like addRecord() except that it returns the value of the serial/primary key column that the database used for the new record.

Returns:

an Object - should be cast to (short), (int), or (long) depending on the serial type

Throws:

SQLException

See Also:

• addRecord()
• Connection.commit()

addRecord

public boolean addRecord()
                  throws SQLException

Inserts a new row into the database by creating an executing an SQL statement. It does not affect any cursors.

Returns:

Throws:

SQLException

See Also:

• addRecordAutoInc()
• Connection.commit()

copyCorresponding

public void copyCorresponding(Record fromRec)
                       throws SQLException

Copy all columns from fromRec to this that have the same column names and types

Parameters:

fromRec - the record to be copied from

Throws:

SQLException

copy

public void copy(Record rec)

Copy all columns from rec to 'this'

Parameters:

rec - the record to be copied from

close

public void close()

Closes any open prepared statements against this record. It is not normally needed since this class implements the AutoCloseable interface.

Specified by:

close in interface AutoCloseable

getConnection

public Connection getConnection()

Returns the Connection instance associated to this Record instance.

Returns:

getTableName

public String getTableName()

Returns the name of the table associated to this Record instance.

Returns:

getAllColumns

public AbstractMap<String,Object> getAllColumns()

Returns a map of all the columns in the record.

Returns:

toJSON

public org.json.JSONObject toJSON()

Convert a record into a JSON object.

Returns:

addToJSON

public org.json.JSONObject addToJSON(org.json.JSONObject obj)

Add columns of a Record to an existing JSON object.

Returns:

toJSONArray

public static org.json.JSONArray toJSONArray(List<Record> recs)

Utility method to convert a list of Record's into a JSON array of JSON objects.

Parameters:

recs -

Returns: