com.j256.ormlite.dao

Interface ForeignCollection<T>

All Superinterfaces:

CloseableIterable<T>, Collection<T>, Iterable<T>

All Known Implementing Classes:

BaseForeignCollection, EagerForeignCollection, LazyForeignCollection, StreamableLazyForeignCollection

public interface ForeignCollection<T>
extends Collection<T>, CloseableIterable<T>

Collection that is set on a field that as been marked with the ForeignCollectionField annotation when an object is refreshed or queried (i.e. not created).

 @ForeignCollectionField(eager = false)
 private ForeignCollection<Order> orders;
 

NOTE: If the collection has been marked as being "lazy" then just about all methods in this class result in a pass through the database using the Collection.iterator(). Even Collection.size() and other seemingly simple calls can cause a lot of database I/O. Most likely just the Collection.iterator(), Collection.toArray(), and Collection.toArray(Object[]) methods should be used if you are using a lazy collection. Any other methods have no guarantee to be at all efficient. Take a look at the source if you have any question.

NOTE: It is also important to remember that lazy iterators hold a connection open to the database which needs to be closed. See LazyForeignCollection.iterator().

Author:

graywatson

Method Summary

Modifier and Type	Method and Description
boolean	add(T obj) Adds the object to the collection.
CloseableIterator<T>	closeableIterator(int flags) Same as iterator(int).
void	closeLastIterator() This will close the last iterator returned by the Collection.iterator() method.
Dao<T,?>	getDao() Return the DAO object associated with this foreign collection.
CloseableWrappedIterable<T>	getWrappedIterable() This makes a one time use iterable class that can be closed afterwards.
CloseableWrappedIterable<T>	getWrappedIterable(int flags) Like getWrappedIterable() but while specifying flags for the results.
boolean	isEager() Returns true if this an eager collection otherwise false.
CloseableIterator<T>	iterator(int flags) Like Collection.iterator() but while specifying flags for the results.
CloseableIterator<T>	iteratorThrow() Like Collection.iterator() but returns a closeable iterator instead and can throw a SQLException.
CloseableIterator<T>	iteratorThrow(int flags) Like iteratorThrow() but while specifying flags for the results.
int	refresh(T obj) This is a call through to Dao.refresh(Object) using the internal collection DAO.
int	refreshAll() Call to refresh on all of the items currently in the collection with the database.
int	refreshCollection() This re-issues the query that initially built the collection replacing any underlying result collection with a new one build from the database.
int	update(T obj) This is a call through to Dao.update(Object) using the internal collection DAO.
int	updateAll() Update all of the items currently in the collection with the database.

Methods inherited from interface java.util.Collection

addAll, clear, contains, containsAll, equals, hashCode, isEmpty, iterator, parallelStream, remove, removeAll, removeIf, retainAll, size, spliterator, stream, toArray, toArray

Methods inherited from interface com.j256.ormlite.dao.CloseableIterable

closeableIterator

Methods inherited from interface java.lang.Iterable

forEach

Method Detail

iterator

CloseableIterator<T> iterator(int flags)

Like Collection.iterator() but while specifying flags for the results. This is necessary with certain database types. The resultFlags could be something like ResultSet.TYPE_SCROLL_INSENSITIVE or other values.

closeableIterator

CloseableIterator<T> closeableIterator(int flags)

Same as iterator(int).

iteratorThrow

CloseableIterator<T> iteratorThrow()
                            throws SQLException

Like Collection.iterator() but returns a closeable iterator instead and can throw a SQLException.

Throws:

SQLException

iteratorThrow

CloseableIterator<T> iteratorThrow(int flags)
                            throws SQLException

Like iteratorThrow() but while specifying flags for the results. This is necessary with certain database types. The resultFlags could be something like ResultSet.TYPE_SCROLL_INSENSITIVE or other values.

Throws:

SQLException

getWrappedIterable

CloseableWrappedIterable<T> getWrappedIterable()

This makes a one time use iterable class that can be closed afterwards. The ForeignCollection itself is CloseableWrappedIterable but multiple threads can each call this to get their own closeable iterable.

getWrappedIterable

CloseableWrappedIterable<T> getWrappedIterable(int flags)

Like getWrappedIterable() but while specifying flags for the results. This is necessary with certain database types. The resultFlags could be something like ResultSet.TYPE_SCROLL_INSENSITIVE or other values.

closeLastIterator

void closeLastIterator()
                throws Exception

This will close the last iterator returned by the Collection.iterator() method.

NOTE: For lazy collections, this is not reentrant. If multiple threads are getting iterators from a lazy collection from the same object then you should use getWrappedIterable() to get a reentrant wrapped iterable for each thread instead.

Throws:

Exception

isEager

boolean isEager()

Returns true if this an eager collection otherwise false.

update

int update(T obj)
    throws SQLException

This is a call through to Dao.update(Object) using the internal collection DAO. Objects inside of the collection are not updated if the parent object is refreshed so you will need to so that by hand.

Throws:

SQLException

updateAll

int updateAll()
       throws SQLException

Update all of the items currently in the collection with the database. This is only applicable for eager collections.

Returns:

The number of rows updated.

Throws:

SQLException

refresh

int refresh(T obj)
     throws SQLException

This is a call through to Dao.refresh(Object) using the internal collection DAO. Objects inside of the collection are not refreshed if the parent object is refreshed so you will need to so that by hand.

Throws:

SQLException

refreshAll

int refreshAll()
        throws SQLException

Call to refresh on all of the items currently in the collection with the database. This is only applicable for eager collections. If you want to see new objects in the collection then you should use refreshCollection().

Returns:

The number of rows refreshed.

Throws:

SQLException

refreshCollection

int refreshCollection()
               throws SQLException

This re-issues the query that initially built the collection replacing any underlying result collection with a new one build from the database. This is only applicable for eager collections and is a no-op for lazy collections.

Returns:

The number of objects loaded into the new collection.

Throws:

SQLException

add

boolean add(T obj)

Adds the object to the collection. This will also add it to the database by calling through to [@link Dao.create(Object). If the object has already been created in the database then you just need to set the foreign field on the object and call Dao.update(Object). If you add it here the DAO will try to create it in the database again which will most likely cause an error.

Specified by:

add in interface Collection<T>

See Also:

Collection.add(Object)

getDao

Dao<T,?> getDao()

Return the DAO object associated with this foreign collection. For usage for those who know what they are doing.