com.j256.ormlite.dao
Interface Dao<T,ID>

All Superinterfaces:

CloseableIterable<T>, Iterable<T>

All Known Implementing Classes:

BaseDaoImpl

public interface Dao<T,ID>
extends CloseableIterable<T>

The definition of the Database Access Objects that handle the reading and writing a class from the database. Kudos to Robert A. for the general concept of this hierarchy.

Author:

graywatson

Method Summary

<CT> CT	callBatchTasks(Callable<CT> callable) Call the call-able that will perform a number of batch tasks.
int	create(T data) Create a new row in the database from an object.
int	delete(Collection<T> datas) Delete a collection of objects from the database using an IN SQL clause.
int	delete(PreparedDelete<T> preparedDelete) Delete the objects that match the prepared statement argument.
int	delete(T data) Delete an object from the database.
DeleteBuilder<T,ID>	deleteBuilder() Like queryBuilder() but allows you to build an DELETE statement.
int	deleteIds(Collection<ID> ids) Delete the objects that match the collection of ids from the database using an IN SQL clause.
CloseableIterator<T>	iterator() This satisfies the Iterable interface for the class and allows you to iterate through the objects in the table using SQL.
CloseableIterator<T>	iterator(PreparedQuery<T> preparedQuery) Same as iterator() but with a prepared query parameter.
RawResults	iteratorRaw(String query) Same as iterator(PreparedQuery) except it returns a RawResults object associated with the SQL select query argument.
boolean	objectsEqual(T data1, T data2) Return true if the two arguments are equal.
String	objectToString(T data) Return the string version of the object with each of the known field values shown.
List<T>	query(PreparedQuery<T> preparedQuery) Query for the items in the object table which match the prepared query.
QueryBuilder<T,ID>	queryBuilder() Create and return a new query builder object which allows you to build a custom SELECT statement.
List<T>	queryForAll() Query for all of the items in the object table.
RawResults	queryForAllRaw(String query) Query for all of the items in the object table that match the SQL select query argument.
T	queryForFirst(PreparedQuery<T> preparedQuery) Query for and return the first item in the object table which matches the PreparedQuery.
T	queryForId(ID id) Retrieves an object associated with a specific ID.
int	refresh(T data) Does a query for the object's id and copies in each of the field values from the database to refresh the data parameter.
int	update(PreparedUpdate<T> preparedUpdate) Update all rows in the table according to the prepared statement argument.
int	update(T data) Save the fields from an object to the database.
UpdateBuilder<T,ID>	updateBuilder() Like queryBuilder() but allows you to build an UPDATE statement.
int	updateId(T data, ID newId) Update an object in the database to change its id to the newId parameter.

Method Detail

queryForId

T queryForId(ID id)
             throws SQLException

Retrieves an object associated with a specific ID.

Parameters:

id - Identifier that matches a specific row in the database to find and return.

Returns:

The object that has the ID field which equals id or null if no matches.

Throws:

SQLException - on any SQL problems or if more than 1 item with the id are found in the database.

queryForFirst

T queryForFirst(PreparedQuery<T> preparedQuery)
                throws SQLException

Query for and return the first item in the object table which matches the PreparedQuery. See queryBuilder() for more information. This can be used to return the object that matches a single unique column. You should use queryForId(ID) if you want to query for the id column.

Parameters:

preparedQuery - Query used to match the objects in the database.

Returns:

The first object that matches the query.

Throws:

SQLException - on any SQL problems.

queryForAll

List<T> queryForAll()
                    throws SQLException

Query for all of the items in the object table. For medium sized or large tables, this may load a lot of objects into memory so you should consider using the iterator() method instead.

Returns:

A list of all of the objects in the table.

Throws:

SQLException - on any SQL problems.

queryForAllRaw

RawResults queryForAllRaw(String query)
                          throws SQLException

Query for all of the items in the object table that match the SQL select query argument. Although you should use the StatementBuilder for most queries, this method allows you to do special queries that aren't supported otherwise. For medium sized or large tables, this may load a lot of objects into memory so you should consider using the iteratorRaw(String) method instead.

Returns:

A raw results object from which you can get the results.

Throws:

SQLException - on any SQL problems.

queryBuilder

QueryBuilder<T,ID> queryBuilder()

Create and return a new query builder object which allows you to build a custom SELECT statement. You call methods on the builder to construct your statement and then call QueryBuilder.prepare() once you are ready to build. This returns a PreparedQuery object which gets passed to query(PreparedQuery) or iterator(PreparedQuery).

updateBuilder

UpdateBuilder<T,ID> updateBuilder()

Like queryBuilder() but allows you to build an UPDATE statement. You can then call call UpdateBuilder.prepare() and pass the returned PreparedUpdate to update(PreparedUpdate).

deleteBuilder

DeleteBuilder<T,ID> deleteBuilder()

Like queryBuilder() but allows you to build an DELETE statement. You can then call call DeleteBuilder.prepare() and pass the returned PreparedDelete to delete(PreparedDelete).

query

List<T> query(PreparedQuery<T> preparedQuery)
              throws SQLException

Query for the items in the object table which match the prepared query. See queryBuilder() for more information.

NOTE: For medium sized or large tables, this may load a lot of objects into memory so you should consider using the iterator(PreparedQuery) method instead.

Parameters:

preparedQuery - Query used to match the objects in the database.

Returns:

A list of all of the objects in the table that match the query.

Throws:

SQLException - on any SQL problems.

create

int create(T data)
           throws SQLException

Create a new row in the database from an object.

Parameters:

data - The data item that we are creating in the database.

Returns:

The number of rows updated in the database. This should be 1.

Throws:

SQLException

update

int update(T data)
           throws SQLException

Save the fields from an object to the database. If you have made changes to an object, this is how you persist those changes to the database. You cannot use this method to update the id field -- see updateId(T, ID).

Parameters:

data - The data item that we are updating in the database.

Returns:

The number of rows updated in the database. This should be 1.

Throws:

SQLException - on any SQL problems.

IllegalArgumentException - If there is only an ID field in the object. See the updateId(T, ID) method.

updateId

int updateId(T data,
             ID newId)
             throws SQLException

Update an object in the database to change its id to the newId parameter. The data must have its current id set. If the id field has already changed then it cannot be updated. After the id has been updated in the database, the id field of the data object will also be changed.

NOTE: Depending on the database type and the id type, you may be unable to change the id of the field.

Parameters:

data - The data item that we are updating in the database with the current id.

newId - The new id that you want to update the data with.

Returns:

The number of rows updated in the database. This should be 1.

Throws:

SQLException - on any SQL problems.

update

int update(PreparedUpdate<T> preparedUpdate)
           throws SQLException

Update all rows in the table according to the prepared statement argument. To use this, the UpdateBuilder must have set-columns applied to it using the UpdateBuilder.updateColumnValue(String, Object) or UpdateBuilder.updateColumnExpression(String, String) methods.

Parameters:

preparedUpdate - A prepared statement to match database rows to be deleted and define the columns to update.

Returns:

The number of rows updated in the database.

Throws:

SQLException - on any SQL problems.

IllegalArgumentException - If there is only an ID field in the object. See the updateId(T, ID) method.

refresh

int refresh(T data)
            throws SQLException

Does a query for the object's id and copies in each of the field values from the database to refresh the data parameter. Any local object changes to persisted fields will be overwritten. If the database has been updated this brings your local object up to date.

Parameters:

data - The data item that we are refreshing with fields from the database.

Returns:

The number of rows found in the database that correspond to the data id. This should be 1.

Throws:

SQLException - on any SQL problems or if the data item is not found in the table or if more than 1 item is found with data's id.

delete

int delete(T data)
           throws SQLException

Delete an object from the database.

Parameters:

data - The data item that we are deleting from the database.

Returns:

The number of rows updated in the database. This should be 1.

Throws:

SQLException - on any SQL problems.

delete

int delete(Collection<T> datas)
           throws SQLException

Delete a collection of objects from the database using an IN SQL clause.

Parameters:

datas - A collection of data items to be deleted.

Returns:

The number of rows updated in the database. This should be the size() of the collection.

Throws:

SQLException - on any SQL problems.

deleteIds

int deleteIds(Collection<ID> ids)
              throws SQLException

Delete the objects that match the collection of ids from the database using an IN SQL clause.

Parameters:

ids - A collection of data ids to be deleted.

Returns:

The number of rows updated in the database. This should be the size() of the collection.

Throws:

SQLException - on any SQL problems.

delete

int delete(PreparedDelete<T> preparedDelete)
           throws SQLException

Delete the objects that match the prepared statement argument.

Parameters:

preparedDelete - A prepared statement to match database rows to be deleted.

Returns:

The number of rows updated in the database.

Throws:

SQLException - on any SQL problems.

iterator

CloseableIterator<T> iterator()

This satisfies the Iterable interface for the class and allows you to iterate through the objects in the table using SQL. You can use code similar to the following:

 for (Account account : accountDao) { ... }
 

WARNING: because the Iterator.hasNext(), Iterator.next(), etc. methods can only throw RuntimeException, the code has to wrap any SQLException with IllegalStateException. Make sure to catch IllegalStateException and look for a SQLException cause. See the SelectIterator source code for more details.

WARNING: The underlying results object will only be closed if you page all the way to the end of the iterator using the for() loop or if you call SelectIterator.close() directly. It is also closed when it is garbage collected but this is considered bad form.

Specified by:

iterator in interface CloseableIterable<T>

Specified by:

iterator in interface Iterable<T>

Returns:

An iterator of the class that uses SQL to step across the database table.

Throws:

IllegalStateException - When it encounters a SQLException or in other cases.

iterator

CloseableIterator<T> iterator(PreparedQuery<T> preparedQuery)
                              throws SQLException

Same as iterator() but with a prepared query parameter. See queryBuilder() for more information. You use it like the following:

 QueryBuilder<Account, String> qb = accountDao.queryBuilder();
 ... custom query builder methods
 SelectIterator<Account> iterator = partialDao.iterator(qb.prepare());
 try {
     while (iterator.hasNext()) {
         Account account = iterator.next();
         ...
     }
 } finish {
     iterator.close();
 }
 

Parameters:

preparedQuery - Query used to iterate across a sub-set of the items in the database.

Returns:

An iterator for T.

Throws:

SQLException - on any SQL problems.

iteratorRaw

RawResults iteratorRaw(String query)
                       throws SQLException

Same as iterator(PreparedQuery) except it returns a RawResults object associated with the SQL select query argument. Although you should use the iterator() for most queries, this method allows you to do special queries that aren't supported otherwise. Like the above iterator methods, you must call close on the returned RawResults object once you are done with it.

Throws:

SQLException

callBatchTasks

<CT> CT callBatchTasks(Callable<CT> callable)
                  throws Exception

Call the call-able that will perform a number of batch tasks. This is for performance when you want to run a number of database operations at once -- maybe loading data from a file. This will turn off what databases call "auto-commit" mode, run the call-able and then re-enable "auto-commit".

NOTE: This is only supported by databases that support auto-commit. Android, for example, does not support auto-commit although using the TransactionManager and performing actions within a transaction seems to have the same batch performance implications.

Throws:

Exception

objectToString

String objectToString(T data)

Return the string version of the object with each of the known field values shown. Useful for testing and debugging.

Parameters:

data - The data item for which we are returning the toString information.

objectsEqual

boolean objectsEqual(T data1,
                     T data2)
                     throws SQLException

Return true if the two arguments are equal. This checks each of the fields defined in the database to see if they are equal. Useful for testing and debugging.

Parameters:

data1 - One of the data items that we are checking for equality.

data2 - The other data item that we are checking for equality.

Throws:

SQLException