com.j256.ormlite.dao
Interface ForeignCollection<T>

All Superinterfaces:
CloseableIterable<T>, Collection<T>, Iterable<T>
All Known Implementing Classes:
BaseForeignCollection, EagerForeignCollection, LazyForeignCollection

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
 void closeLastIterator()
          This will close the last iterator returned by the Collection.iterator() method.
 CloseableWrappedIterable<T> getWrappedIterable()
          This makes a one time use iterable class that can be closed afterwards.
 boolean isEager()
          Returns true if this an eager collection otherwise false.
 CloseableIterator<T> iteratorThrow()
          Like Collection.iterator() but returns a closeable iterator instead and can throw a SQLException.
 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
add, addAll, clear, contains, containsAll, equals, hashCode, isEmpty, iterator, remove, removeAll, retainAll, size, toArray, toArray
 
Methods inherited from interface com.j256.ormlite.dao.CloseableIterable
closeableIterator
 

Method Detail

iteratorThrow

CloseableIterator<T> iteratorThrow()
                                   throws SQLException
Like Collection.iterator() but returns a closeable iterator instead and can throw a SQLException.

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.


closeLastIterator

void closeLastIterator()
                       throws SQLException
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:
SQLException

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


This documentation is licensed by Gray Watson under the Creative Commons Attribution-Share Alike 3.0 License.