Package org.kissweb.database

Class Command

java.lang.Object

org.kissweb.database.Command

All Implemented Interfaces:

AutoCloseable

public class Command
extends Object
implements AutoCloseable

This class represents a single statement or command against a database. Of course, each Connection may have many Command instances in play at a time. New Command instances may by obtained via the Connection class as follows:

Command cmd = db.newCommand();

where db is a Connection instance.

See Also:

• Connection.newCommand()

Method Summary

Modifier and Type	Method	Description
void	close()	This closes the Command instance.
boolean	execute(String sql, Object... args)	Execute non-select statement.
boolean	exists(String sql, Object... args)	Returns true if there are any records matching the given SQL statement and false otherwise.
List<Record>	fetchAll(int page, int max, String sql, Object... args)	Fetch all (but no more than max) records and then close the Kiss cursor.
List<Record>	fetchAll(int max, String sql, Object... args)	Fetch all (but no more than max) records and then close the Kiss cursor.
List<Record>	fetchAll(String sql, Object... args)	Fetch all the records and close the Kiss cursor.
org.json.JSONArray	fetchAllJSON(int page, int max, String sql, Object... args)	This method is the same as fetchAll except that it returns a JSON array of the records.
org.json.JSONArray	fetchAllJSON(int max, String sql, Object... args)	This method is the same as fetchAll except that it returns a JSON array of the records.
org.json.JSONArray	fetchAllJSON(String sql, Object... args)	This method is the same as fetchAll except that it returns the list of records as a JSON array of JSON objects where each object represents a column.
Record	fetchOne(String sql, Object... args)	Read in the first record and then close the Kiss cursor.
org.json.JSONObject	fetchOneJSON(String sql, Object... args)	This method is the same as fetchOne except that it returns a JSON object.
org.json.JSONObject	fetchOneJSON(org.json.JSONObject obj, String sql, Object... args)	This method is the same as fetchOne except that it adds the columns to en existing JSON object.
Cursor	query(int page, int max, String sql, Object... args)	Execute a select statement returning a Kiss Cursor (not a database cursor) that may be used to obtain each subsequent row.
Cursor	query(int max, String sql, Object... args)	Execute a select statement returning a Kiss Cursor (not a database cursor) that may be used to obtain each subsequent row.
Cursor	query(String sql, Object... args)	Execute a select statement returning a Kiss Cursor (not a database cursor) that may be used to obtain each subsequent row.

Methods inherited from class java.lang.Object

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

Method Details

execute

public boolean execute(String sql,
 Object... args)
                throws SQLException

Execute non-select statement. This is useful, for example, for UPDATE, INSERT, and DELETE SQL statements.

The SQL string may contain parameters indicated by the '?' character. A variable number of arguments to this method are used to fill those parameters. Each argument gets applied to each '?' parameter in the same order as they appear in the SQL statement. An SQL prepared statement is used.

This method normally takes a variable argument list representing the consecutive parameters. However, this method also accepts a single argument (which must be an ArrayList) that represents the parameters rather than an in-line list of parameters.

Parameters:

sql - the sql statement with ? parameters

args - the parameter values

Returns:

false is a normal result

Throws:

SQLException

See Also:

• fetchOne(String, Object...)
• fetchAll(String, Object...)

query

public Cursor query(String sql,
 Object... args)
             throws SQLException,
IOException

Execute a select statement returning a Kiss Cursor (not a database cursor) that may be used to obtain each subsequent row. This is useful when a large number of records is possible and fetching all into memory at one time is unneeded. This can save a significant amount of memory since only one record is in memory at a time.

The SQL string may contain parameters indicated by the '?' character. A variable number of arguments to this method are used to fill those parameters. Each argument gets applied to each '?' parameter in the same order as they appear in the SQL statement. An SQL prepared statement is used.

This method normally takes a variable argument list representing the consecutive parameters. However, this method also accepts a single argument (which must be an ArrayList) that represents the parameters rather than an in-line list of parameters.

Parameters:

sql - the sql statement with ? parameters

args - the parameter values

Returns:

Throws:

SQLException

IOException

See Also:

• Cursor
• fetchAll(String, Object...)
• fetchOne(String, Object...)
• query(int, String, Object...)

query

public Cursor query(int max,
 String sql,
 Object... args)
             throws SQLException,
IOException

Execute a select statement returning a Kiss Cursor (not a database cursor) that may be used to obtain each subsequent row.

The maximum number of records returned is given by max. This is useful when a large number of records is possible and fetching all into memory at one time is unneeded. This can save a significant amount of memory since only one record is in memory at a time.

The SQL string may contain parameters indicated by the '?' character. A variable number of arguments to this method are used to fill those parameters. Each argument gets applied to each '?' parameter in the same order as they appear in the SQL statement. An SQL prepared statement is used.

This method normally takes a variable argument list representing the consecutive parameters. However, this method also accepts a single argument (which must be an ArrayList) that represents the parameters rather than an in-line list of parameters.

Parameters:

max -

sql - the sql statement with ? parameters

args - the parameter values

Returns:

Throws:

SQLException

IOException

See Also:

• Cursor
• fetchAll(String, Object...)
• fetchOne(String, Object...)
• query(String, Object...)

query

public Cursor query(int page,
 int max,
 String sql,
 Object... args)
             throws SQLException,
IOException

Execute a select statement returning a Kiss Cursor (not a database cursor) that may be used to obtain each subsequent row. This version is used for paging results. The total result set is broken down into max sized pages (starting at zero) You can then choose which group of max records wanted.

The page parameter selects the desired page of results (starting at zero).

The maximum number of records returned is given by max. This is useful when a large number of records is possible and fetching all into memory at one time is unneeded. This can save a significant amount of memory since only one record is in memory at a time.

The SQL string may contain parameters indicated by the '?' character. A variable number of arguments to this method are used to fill those parameters. Each argument gets applied to each '?' parameter in the same order as they appear in the SQL statement. An SQL prepared statement is used.

This method normally takes a variable argument list representing the consecutive parameters. However, this method also accepts a single argument (which must be an ArrayList) that represents the parameters rather than an in-line list of parameters.

Parameters:

page - starting at zero

max -

sql - the sql statement with ? parameters

args - the parameter values

Returns:

Throws:

SQLException

IOException

See Also:

• Cursor
• fetchAll(String, Object...)
• fetchOne(String, Object...)
• query(String, Object...)

fetchOne

public Record fetchOne(String sql,
 Object... args)
                throws Exception

Read in the first record and then close the Kiss cursor. The record can be updated or deleted if it was a single-table select and the primary key was selected.

Adding code to the SQL statement telling the database to limit its result set to one record doesn't affect the result but it can make the query significantly faster.

The SQL string may contain parameters indicated by the '?' character. A variable number of arguments to this method are used to fill those parameters. Each argument gets applied to each '?' parameter in the same order as they appear in the SQL statement. An SQL prepared statement is used.

This method normally takes a variable argument list representing the consecutive parameters. However, this method also accepts a single argument (which must be an Array) that represents the parameters rather than an in-line list of parameters.

Parameters:

sql - SQL statement with ? parameters

args - the parameter values

Returns:

the Record or null if none

Throws:

SQLException

Exception

See Also:

• fetchAll(String, Object...)
• execute(String, Object...)

fetchOneJSON

public org.json.JSONObject fetchOneJSON(String sql,
 Object... args)
                                 throws Exception

This method is the same as fetchOne except that it returns a JSON object.

Parameters:

sql -

args -

Returns:

the JSON object or null if no record

Throws:

SQLException

Exception

See Also:

• fetchOne(String, Object...)

fetchOneJSON

public org.json.JSONObject fetchOneJSON(org.json.JSONObject obj,
 String sql,
 Object... args)
                                 throws Exception

This method is the same as fetchOne except that it adds the columns to en existing JSON object.

Parameters:

obj - the JSON object that is to be added to

sql -

args -

Returns:

the JSON object passed in

Throws:

SQLException

Exception

See Also:

• fetchOne(String, Object...)

fetchAll

public List<Record> fetchAll(String sql,
 Object... args)
                      throws Exception

Fetch all the records and close the Kiss cursor. The records can be updated or deleted if there was a single-table select and the primary key was selected.

The SQL string may contain parameters indicated by the '?' character. A variable number of arguments to this method are used to fill those parameters. Each argument gets applied to each '?' parameter in the same order as they appear in the SQL statement. An SQL prepared statement is used.

This method normally takes a variable argument list representing the consecutive parameters. However, this method also accepts a single argument (which must be an Array) that represents the parameters rather than an in-line list of parameters.

If no records are found, an empty list is returned.

Parameters:

sql - SQL statement with ? parameters

args - the parameter values

Returns:

Throws:

SQLException

Exception

See Also:

• fetchAll(int, String, Object...)
• fetchAll(int, int, String, Object...)
• fetchOne(String, Object...)
• execute(String, Object...)

fetchAllJSON

public org.json.JSONArray fetchAllJSON(String sql,
 Object... args)
                                throws Exception

This method is the same as fetchAll except that it returns the list of records as a JSON array of JSON objects where each object represents a column.

Parameters:

sql -

args -

Returns:

Throws:

SQLException

Exception

See Also:

• fetchAll(String, Object...)

fetchAll

public List<Record> fetchAll(int max,
 String sql,
 Object... args)
                      throws Exception

Fetch all (but no more than max) records and then close the Kiss cursor. The records can be updated or deleted if there was a single-table select and the primary key was selected.

The SQL string may contain parameters indicated by the '?' character. A variable number of arguments to this method are used to fill those parameters. Each argument gets applied to each '?' parameter in the same order as they appear in the SQL statement. An SQL prepared statement is used.

This method normally takes a variable argument list representing the consecutive parameters. However, this method also accepts a single argument (which must be an Array) that represents the parameters rather than an in-line list of parameters.

If no records are found, an empty list is returned.

Parameters:

max -

sql - SQL statement with ? parameters

args - the parameter values

Returns:

Throws:

SQLException

Exception

See Also:

• fetchAll(String, Object...)
• fetchAll(int, int, String, Object...)
• fetchOne(String, Object...)
• execute(String, Object...)

fetchAll

public List<Record> fetchAll(int page,
 int max,
 String sql,
 Object... args)
                      throws Exception

Fetch all (but no more than max) records and then close the Kiss cursor.

page determine which block of max records to read. page starts at zero and is used for paging output.

The records can be updated or deleted if there was a single-table select and the primary key was selected.

The SQL string may contain parameters indicated by the '?' character. A variable number of arguments to this method are used to fill those parameters. Each argument gets applied to each '?' parameter in the same order as they appear in the SQL statement. An SQL prepared statement is used.

This method normally takes a variable argument list representing the consecutive parameters. However, this method also accepts a single argument (which must be an Array) that represents the parameters rather than an in-line list of parameters.

If no records are found, an empty list is returned.

Parameters:

page - starting at zero

max -

sql - SQL statement with ? parameters

args - the parameter values

Returns:

Throws:

SQLException

Exception

See Also:

• fetchAll(String, Object...)
• fetchAll(int, String, Object...)
• fetchOne(String, Object...)
• execute(String, Object...)

fetchAllJSON

public org.json.JSONArray fetchAllJSON(int max,
 String sql,
 Object... args)
                                throws Exception

This method is the same as fetchAll except that it returns a JSON array of the records.

Parameters:

max -

sql -

args -

Returns:

Throws:

SQLException

Exception

See Also:

• fetchAll(int, String, Object...)

fetchAllJSON

public org.json.JSONArray fetchAllJSON(int page,
 int max,
 String sql,
 Object... args)
                                throws Exception

This method is the same as fetchAll except that it returns a JSON array of the records.

Parameters:

max -

sql -

args -

Returns:

Throws:

SQLException

Exception

See Also:

• fetchAll(int, int, String, Object...)

exists

public boolean exists(String sql,
 Object... args)
               throws Exception

Returns true if there are any records matching the given SQL statement and false otherwise.

Parameters:

sql -

args -

Returns:

Throws:

Exception

close

public void close()

This closes the Command instance. This need not be done manually since this class implements the AutoCloseable interface.

Specified by:

close in interface AutoCloseable