|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface Dao<T,ID>
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.
Nested Class Summary | |
---|---|
static class |
Dao.CreateOrUpdateStatus
Return class for the createOrUpdate(Object) method. |
Method Summary | ||
---|---|---|
void |
assignEmptyForeignCollection(T parent,
String fieldName)
Creates an empty collection and assigns it to the appropriate field in the parent object. |
|
|
callBatchTasks(Callable<CT> callable)
Call the call-able that will perform a number of batch tasks. |
|
void |
clearObjectCache()
Flush the object cache if it has been enabled. |
|
void |
closeLastIterator()
This closes the last iterator returned by the iterator() method. |
|
void |
commit(DatabaseConnection connection)
If you have previously set auto-commit to false using setAutoCommit(DatabaseConnection, boolean) then
this will commit all changes to the database made from that point up to now on the connection returned by the
startThreadConnection() . |
|
long |
countOf()
Returns the number of rows in the table associated with the data class. |
|
long |
countOf(PreparedQuery<T> preparedQuery)
Returns the number of rows in the table associated with the prepared query passed in. |
|
int |
create(T data)
Create a new row in the database from an object. |
|
T |
createIfNotExists(T data)
This is a convenience method to creating a data item but only if the ID does not already exist in the table. |
|
Dao.CreateOrUpdateStatus |
createOrUpdate(T data)
This is a convenience method for creating an item in the database if it does not exist. |
|
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 |
deleteById(ID id)
Delete an object from the database that has an id. |
|
int |
deleteIds(Collection<ID> ids)
Delete the objects that match the collection of ids from the database using an IN SQL clause. |
|
void |
endThreadConnection(DatabaseConnection connection)
WARNING: This method is for advanced users only. |
|
int |
executeRaw(String statement,
String... arguments)
Run a raw execute SQL statement to the database. |
|
int |
executeRawNoArgs(String statement)
Run a raw execute SQL statement on the database without any arguments. |
|
ID |
extractId(T data)
Returns the ID from the data argument passed in. |
|
FieldType |
findForeignFieldType(Class<?> clazz)
Returns the class of the DAO. |
|
ConnectionSource |
getConnectionSource()
Return the associated ConnectionSource or null if none set on the DAO yet. |
|
Class<T> |
getDataClass()
Returns the class of the DAO. |
|
|
getEmptyForeignCollection(String fieldName)
Like assignEmptyForeignCollection(Object, String) but it returns the empty collection that you assign to
the appropriate field. |
|
ObjectCache |
getObjectCache()
Returns the current object-cache being used by the DAO or null if none. |
|
RawRowMapper<T> |
getRawRowMapper()
Return a row mapper that is suitable for use with queryRaw(String, RawRowMapper, String...) . |
|
GenericRowMapper<T> |
getSelectStarRowMapper()
Return a row mapper that is suitable for mapping results from a query to select * (star). |
|
CloseableWrappedIterable<T> |
getWrappedIterable()
This makes a one time use iterable class that can be closed afterwards. |
|
CloseableWrappedIterable<T> |
getWrappedIterable(PreparedQuery<T> preparedQuery)
Same as getWrappedIterable() but with a prepared query parameter. |
|
boolean |
idExists(ID id)
Returns true if an object exists that matches this ID otherwise false. |
|
boolean |
isAutoCommit()
Deprecated. You should use the isAutoCommit(DatabaseConnection) method instead. |
|
boolean |
isAutoCommit(DatabaseConnection connection)
Return true if the database connection returned by the startThreadConnection() is in auto-commit mode
otherwise false. |
|
boolean |
isTableExists()
Returns true if the table already exists otherwise false. |
|
boolean |
isUpdatable()
Returns true if we can call update on this class. |
|
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(int resultFlags)
Same as iterator() but while specifying flags for the results. |
|
CloseableIterator<T> |
iterator(PreparedQuery<T> preparedQuery)
Same as iterator() but with a prepared query parameter. |
|
CloseableIterator<T> |
iterator(PreparedQuery<T> preparedQuery,
int resultFlags)
Same as iterator(PreparedQuery) but while specifying flags for the results. |
|
T |
mapSelectStarRow(DatabaseResults results)
Return the latest row from the database results from a query to select * (star). |
|
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. |
|
List<T> |
queryForEq(String fieldName,
Object value)
Query for the items in the object table that match a simple where with a single field = value type of WHERE clause. |
|
List<T> |
queryForFieldValues(Map<String,Object> fieldValues)
Query for the rows in the database that matches all of the field to value entries from the map passed in. |
|
List<T> |
queryForFieldValuesArgs(Map<String,Object> fieldValues)
Same as queryForFieldValues(Map) but this uses SelectArg and SQL ? arguments. |
|
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. |
|
List<T> |
queryForMatching(T matchObj)
Query for the rows in the database that match the object passed in as an argument. |
|
List<T> |
queryForMatchingArgs(T matchObj)
Same as queryForMatching(Object) but this uses SelectArg and SQL ? arguments. |
|
T |
queryForSameId(T data)
Query for a data item in the table that has the same ID as the data parameter. |
|
GenericRawResults<Object[]> |
queryRaw(String query,
DataType[] columnTypes,
String... arguments)
Similar to the queryRaw(String, String...) but instead of an array of String results being returned by
the iterator, this uses the column-types parameter to return an array of Objects instead. |
|
|
queryRaw(String query,
RawRowMapper<UO> mapper,
String... arguments)
Similar to the queryRaw(String, String...) but this iterator returns rows that you can map yourself. |
|
GenericRawResults<String[]> |
queryRaw(String query,
String... arguments)
Similar to the iterator(PreparedQuery) except it returns a GenericRawResults object associated with the
SQL select query argument. |
|
long |
queryRawValue(String query,
String... arguments)
Perform a raw query that returns a single value (usually an aggregate function like MAX or COUNT). |
|
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. |
|
void |
rollBack(DatabaseConnection connection)
If you have previously set auto-commit to false using setAutoCommit(DatabaseConnection, boolean) then
this will roll-back and flush all changes to the database made from that point up to now on the connection
returned by the startThreadConnection() . |
|
void |
setAutoCommit(boolean autoCommit)
Deprecated. You should use the setAutoCommit(DatabaseConnection, boolean) method instead. |
|
void |
setAutoCommit(DatabaseConnection connection,
boolean autoCommit)
Set auto-commit mode to be true or false on the connection returned by the startThreadConnection() . |
|
void |
setObjectCache(boolean enabled)
Call this with true to enable an object cache for the DAO. |
|
void |
setObjectCache(ObjectCache objectCache)
Same as setObjectCache(boolean) except you specify the actual cache instance to use for the DAO. |
|
void |
setObjectFactory(ObjectFactory<T> objectFactory)
Set an object factory so we can wire in controls over an object when it is constructed. |
|
DatabaseConnection |
startThreadConnection()
WARNING: This method is for advanced users only. |
|
int |
update(PreparedUpdate<T> preparedUpdate)
Update all rows in the table according to the prepared statement argument. |
|
int |
update(T data)
Store 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. |
|
int |
updateRaw(String statement,
String... arguments)
Run a raw update SQL statement to the database. |
Methods inherited from interface com.j256.ormlite.dao.CloseableIterable |
---|
closeableIterator |
Method Detail |
---|
T queryForId(ID id) throws SQLException
id
- Identifier that matches a specific row in the database to find and return.
SQLException
- on any SQL problems or if more than 1 item with the id are found in the database.T queryForFirst(PreparedQuery<T> preparedQuery) throws SQLException
queryBuilder()
for more information. This can be used to return the object that matches a single unique
column. You should use queryForId(Object)
if you want to query for the id column.
preparedQuery
- Query used to match the objects in the database.
SQLException
- on any SQL problems.List<T> queryForAll() throws SQLException
iterator()
method instead.
SQLException
- on any SQL problems.List<T> queryForEq(String fieldName, Object value) throws SQLException
SQLException
- on any SQL problems.List<T> queryForMatching(T matchObj) throws SQLException
queryForMatchingArgs(Object)
.
SQLException
List<T> queryForMatchingArgs(T matchObj) throws SQLException
queryForMatching(Object)
but this uses SelectArg
and SQL ? arguments. This is slightly
more expensive but you don't have to worry about SQL quote escaping.
SQLException
List<T> queryForFieldValues(Map<String,Object> fieldValues) throws SQLException
queryForFieldValuesArgs(Map)
.
SQLException
List<T> queryForFieldValuesArgs(Map<String,Object> fieldValues) throws SQLException
queryForFieldValues(Map)
but this uses SelectArg
and SQL ? arguments. This is slightly
more expensive but you don't have to worry about SQL quote escaping.
SQLException
T queryForSameId(T data) throws SQLException
SQLException
QueryBuilder<T,ID> queryBuilder()
QueryBuilder.prepare()
once you are
ready to build. This returns a PreparedQuery
object which gets passed to query(PreparedQuery)
or
iterator(PreparedQuery)
.
UpdateBuilder<T,ID> updateBuilder()
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<T,ID> deleteBuilder()
queryBuilder()
but allows you to build an DELETE statement. You can then call call
DeleteBuilder.prepare()
and pass the returned PreparedDelete
to delete(PreparedDelete)
.
List<T> query(PreparedQuery<T> preparedQuery) throws SQLException
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.
preparedQuery
- Query used to match the objects in the database.
SQLException
- on any SQL problems.int create(T data) throws SQLException
data
- The data item that we are creating in the database.
SQLException
T createIfNotExists(T data) throws SQLException
queryForId(Object)
on it, returning the data if it
exists. If it does not exist create(Object)
will be called with the parameter.
SQLException
Dao.CreateOrUpdateStatus createOrUpdate(T data) throws SQLException
SQLException
int update(T data) throws SQLException
updateId(T, ID)
.
NOTE: This will not save changes made to foreign objects or to foreign collections.
data
- The data item that we are updating in the database.
SQLException
- on any SQL problems.
IllegalArgumentException
- If there is only an ID field in the object. See the updateId(T, ID)
method.int updateId(T data, ID newId) throws SQLException
NOTE: Depending on the database type and the id type, you may be unable to change the id of the field.
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.
SQLException
- on any SQL problems.int update(PreparedUpdate<T> preparedUpdate) throws SQLException
UpdateBuilder
must have set-columns applied to it using the UpdateBuilder.updateColumnValue(String, Object)
or
UpdateBuilder.updateColumnExpression(String, String)
methods.
preparedUpdate
- A prepared statement to match database rows to be deleted and define the columns to update.
SQLException
- on any SQL problems.
IllegalArgumentException
- If there is only an ID field in the object. See the updateId(T, ID)
method.int refresh(T data) throws SQLException
data
- The data item that we are refreshing with fields from the database.
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.int delete(T data) throws SQLException
data
- The data item that we are deleting from the database.
SQLException
- on any SQL problems.int deleteById(ID id) throws SQLException
id
- The id of the item that we are deleting from the database.
SQLException
- on any SQL problems.int delete(Collection<T> datas) throws SQLException
datas
- A collection of data items to be deleted.
SQLException
- on any SQL problems.int deleteIds(Collection<ID> ids) throws SQLException
ids
- A collection of data ids to be deleted.
SQLException
- on any SQL problems.int delete(PreparedDelete<T> preparedDelete) throws SQLException
preparedDelete
- A prepared statement to match database rows to be deleted.
SQLException
- on any SQL problems.CloseableIterator<T> iterator()
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.
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 CloseableIterator.close()
directly. You can also call the
closeLastIterator()
if you are not iterating across this DAO in multiple threads.
iterator
in interface Iterable<T>
IllegalStateException
- When it encounters a SQLException or in other cases.CloseableIterator<T> iterator(int resultFlags)
iterator()
but while specifying flags for the results. This is necessary with certain database
types.
WARNING: Depending on the database type the underlying connection may never be freed -- even if you go all
of the way through the results. It is strongly recommended that you call the
CloseableIterator.close()
method when you are done with the iterator.
CloseableIterator<T> iterator(PreparedQuery<T> preparedQuery) throws SQLException
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 CloseableIterator<Account> iterator = partialDao.iterator(qb.prepare()); try { while (iterator.hasNext()) { Account account = iterator.next(); ... } } finish { iterator.close(); }
preparedQuery
- Query used to iterate across a sub-set of the items in the database.
SQLException
- on any SQL problems.CloseableIterator<T> iterator(PreparedQuery<T> preparedQuery, int resultFlags) throws SQLException
iterator(PreparedQuery)
but while specifying flags for the results. This is necessary with
certain database types.
SQLException
CloseableWrappedIterable<T> getWrappedIterable()
CloseableWrappedIterable
but multiple threads can each call this to get their own closeable iterable.
This allows you to do something like:
CloseableWrappedIterablewrappedIterable = fooDao.getWrappedIterable(); try { for (Foo foo : wrappedIterable) { ... } } finally { wrappedIterable.close(); }
CloseableWrappedIterable<T> getWrappedIterable(PreparedQuery<T> preparedQuery)
getWrappedIterable()
but with a prepared query parameter. See queryBuilder()
or
iterator(PreparedQuery)
for more information.
void closeLastIterator() throws SQLException
iterator()
method.
NOTE: This is not reentrant. If multiple threads are getting iterators from this DAO then you should use
the getWrappedIterable()
method to get a wrapped iterable for each thread instead.
SQLException
GenericRawResults<String[]> queryRaw(String query, String... arguments) throws SQLException
iterator(PreparedQuery)
except it returns a GenericRawResults 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. The arguments are optional but can be set with
strings to expand ? type of SQL.
You can use the StatementBuilder.prepareStatementString()
method here if you want to build the query using
the structure of the QueryBuilder.
QueryBuilder<Account, Integer> qb = accountDao.queryBuilder(); qb.where().ge("orderCount", 10); results = accountDao.queryRaw(qb.prepareStatementString());If you want to use the QueryBuilder with arguments to the raw query then you should do something like:
QueryBuilder<Account, Integer> qb = accountDao.queryBuilder(); // we specify a SelectArg here to generate a ? in the statement string below qb.where().ge("orderCount", new SelectArg()); // the 10 at the end is an optional argument to fulfill the SelectArg above results = accountDao.queryRaw(qb.prepareStatementString(), rawRowMapper, 10);
NOTE: If you are using the StatementBuilder.prepareStatementString()
to build your query, it may have
added the id column to the selected column list if the Dao object has an id you did not include it in the columns
you selected. So the results might have one more column than you are expecting.
SQLException
<UO> GenericRawResults<UO> queryRaw(String query, RawRowMapper<UO> mapper, String... arguments) throws SQLException
queryRaw(String, String...)
but this iterator returns rows that you can map yourself. For
every result that is returned by the database, the RawRowMapper.mapRow(String[], String[])
method is
called so you can convert the result columns into an object to be returned by the iterator. The arguments are
optional but can be set with strings to expand ? type of SQL. For a simple implementation of a raw row mapper,
see getRawRowMapper()
.
SQLException
GenericRawResults<Object[]> queryRaw(String query, DataType[] columnTypes, String... arguments) throws SQLException
queryRaw(String, String...)
but instead of an array of String results being returned by
the iterator, this uses the column-types parameter to return an array of Objects instead. The arguments are
optional but can be set with strings to expand ? type of SQL.
SQLException
long queryRawValue(String query, String... arguments) throws SQLException
SQLException
int executeRaw(String statement, String... arguments) throws SQLException
executeRawNoArgs(String)
.
SQLException
int executeRawNoArgs(String statement) throws SQLException
SQLException
int updateRaw(String statement, String... arguments) throws SQLException
SQLException
<CT> CT callBatchTasks(Callable<CT> callable) throws Exception
NOTE: If neither auto-commit nor transactions are supported by the database type then this may just call the callable. Also, "commit()" is not called on the connection at all. If "auto-commit" is disabled then this will leave it off and nothing will have been persisted.
Exception
String objectToString(T data)
data
- The data item for which we are returning the toString information.boolean objectsEqual(T data1, T data2) throws SQLException
data1
- One of the data items that we are checking for equality.data2
- The other data item that we are checking for equality.
SQLException
ID extractId(T data) throws SQLException
SQLException
Class<T> getDataClass()
FieldType findForeignFieldType(Class<?> clazz)
boolean isUpdatable()
boolean isTableExists() throws SQLException
SQLException
long countOf() throws SQLException
SQLException
long countOf(PreparedQuery<T> preparedQuery) throws SQLException
SQLException
void assignEmptyForeignCollection(T parent, String fieldName) throws SQLException
@ForeignCollectionField(columnName = "orders") Collection<Order> orders;You would then call:
accoundDao.assignEmptyForeignCollection(account, "orders"); // this would add it the collection and the internal DAO account.orders.add(order1);
parent
- Parent object that will be associated with all items added to this collection if not already assigned.fieldName
- parameter is the field name of the foreign collection field -- you might consider using the
ForeignCollectionField.columnName()
to set the name to a static name.
SQLException
<FT> ForeignCollection<FT> getEmptyForeignCollection(String fieldName) throws SQLException
assignEmptyForeignCollection(Object, String)
but it returns the empty collection that you assign to
the appropriate field.
NOTE: May be deprecated in the future.
SQLException
void setObjectCache(boolean enabled) throws SQLException
ReferenceObjectCache
of the objects (using
WeakReference
) referenced by the DAO. No support for objects returned by the queryRaw(java.lang.String, java.lang.String...)
methods.
SQLException
- If the DAO's class does not have an id field which is required by the ObjectCache
.void setObjectCache(ObjectCache objectCache) throws SQLException
setObjectCache(boolean)
except you specify the actual cache instance to use for the DAO. This
allows you to use a ReferenceObjectCache
with SoftReference
setting, the LruObjectCache
,
or inject your own cache implementation. Call it with null to disable the cache.
SQLException
- If the DAO's class does not have an id field which is required by the ObjectCache
.ObjectCache getObjectCache()
void clearObjectCache()
T mapSelectStarRow(DatabaseResults results) throws SQLException
SQLException
GenericRowMapper<T> getSelectStarRowMapper() throws SQLException
SQLException
RawRowMapper<T> getRawRowMapper()
queryRaw(String, RawRowMapper, String...)
. This is a
bit experimental at this time. It most likely will _not_ work with all databases since the string output for each
data type is hard to forecast. Please provide feedback.
boolean idExists(ID id) throws SQLException
SQLException
DatabaseConnection startThreadConnection() throws SQLException
WARNING: This method is for advanced users only. It is only to support the
setAutoCommit(DatabaseConnection, boolean)
and other methods below. Chances are you should be using the
callBatchTasks(Callable)
instead of this method unless you know what you are doing.
This allocates a connection for this specific thread that will be used in all other DAO operations. The thread
must call endThreadConnection(DatabaseConnection)
once it is done with the connection. It is
highly recommended that a
try { conn = dao.startThreadConnection(); ... } finally { dao.endThreadConnection(conn); }
type of
pattern be used here to ensure you do not leak connections.
SQLException
void endThreadConnection(DatabaseConnection connection) throws SQLException
WARNING: This method is for advanced users only. It is only to support the
setAutoCommit(DatabaseConnection, boolean)
and other methods below. Chances are you should be using the
callBatchTasks(Callable)
instead of this method unless you know what you are doing.
This method is used to free the connection returned by the startThreadConnection()
above.
connection
- Connection to be freed. If null then it will be a no-op.
SQLException
@Deprecated void setAutoCommit(boolean autoCommit) throws SQLException
setAutoCommit(DatabaseConnection, boolean)
method instead.
SQLException
void setAutoCommit(DatabaseConnection connection, boolean autoCommit) throws SQLException
startThreadConnection()
. This
may not be supported by all database types.
WARNING: Chances are you should be using the callBatchTasks(Callable)
instead of this method
unless you know what you are doing.
SQLException
@Deprecated boolean isAutoCommit() throws SQLException
isAutoCommit(DatabaseConnection)
method instead.
SQLException
boolean isAutoCommit(DatabaseConnection connection) throws SQLException
startThreadConnection()
is in auto-commit mode
otherwise false. This may not be supported by all database types.
SQLException
void commit(DatabaseConnection connection) throws SQLException
setAutoCommit(DatabaseConnection, boolean)
then
this will commit all changes to the database made from that point up to now on the connection returned by the
startThreadConnection()
. The changes will be written to the database and discarded. The connection will
continue to stay in the current auto-commit mode.
WARNING: Chances are you should be using the callBatchTasks(Callable)
instead of this method
unless you know what you are doing.
SQLException
void rollBack(DatabaseConnection connection) throws SQLException
setAutoCommit(DatabaseConnection, boolean)
then
this will roll-back and flush all changes to the database made from that point up to now on the connection
returned by the startThreadConnection()
. None of those changes will be written to the database and are
discarded. The connection will continue to stay in the current auto-commit mode.
WARNING: Chances are you should be using the callBatchTasks(Callable)
instead of this method
unless you know what you are doing.
SQLException
ConnectionSource getConnectionSource()
void setObjectFactory(ObjectFactory<T> objectFactory)
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |