com.avaje.ebean.bean.BeanCollection Maven / Gradle / Ivy
package com.avaje.ebean.bean;
import java.io.Serializable;
import java.util.Collection;
import java.util.Set;
import java.util.concurrent.Future;
import java.util.concurrent.TimeUnit;
import com.avaje.ebean.ExpressionList;
import com.avaje.ebean.Query;
/**
* Lazy loading capable Maps, Lists and Sets.
*
* This also includes the ability to listen for additions and removals to or
* from the Map Set or List. The purpose of gathering the additions and removals
* is to support persisting ManyToMany objects. The additions and removals
* become inserts and deletes from the intersection table.
*
*
* Technically this is NOT an extension of
* java.util.Collection. The reason being that java.util.Map is not a
* Collection. I realise this makes this name confusing so I apologise for that.
*
*/
public interface BeanCollection extends Serializable {
public enum ModifyListenMode {
/** The common mode */
NONE,
/** Mode used for PrivateOwned */
REMOVALS,
/** Mode used for ManyToMany relationships */
ALL
}
/**
* Return the bean that owns this collection.
*/
public Object getOwnerBean();
/**
* Return the bean property name this collection represents.
*/
public String getPropertyName();
/**
* Return the index position of this collection in the lazy/query loader.
*
* Used for batch loading of collections.
*
*/
public int getLoaderIndex();
/**
* Check after the lazy load that the underlying collection is not null
* (handle case where join to many not outer).
*
* That is, if the collection was not loaded due to filterMany predicates etc
* then make sure the collection is set to empty.
*
*/
public boolean checkEmptyLazyLoad();
/**
* Return the filter (if any) that was used in building this collection.
*
* This is so that the filter can be applied on refresh.
*
*/
public ExpressionList getFilterMany();
/**
* Set the filter that was used in building this collection.
*/
public void setFilterMany(ExpressionList filterMany);
/**
* Set when this collection is being loaded via a background thread.
*
* Refer to {@link Query#setBackgroundFetchAfter(int)}
*
*/
public void setBackgroundFetch(Future future);
/**
* Wait for the fetch to complete with a given timeout.
*
* Refer to {@link Query#setBackgroundFetchAfter(int)}
*
*/
public void backgroundFetchWait(long wait, TimeUnit timeUnit);
/**
* Wait for the fetch to complete.
*
* Refer to {@link Query#setBackgroundFetchAfter(int)}
*
*/
public void backgroundFetchWait();
/**
* Set a listener to be notified when the BeanCollection is first touched.
*/
public void setBeanCollectionTouched(BeanCollectionTouched notify);
/**
* Set the loader that will be used to lazy/query load this collection.
*/
public void setLoader(int beanLoaderIndex, BeanCollectionLoader beanLoader);
/**
* Set to true if you want the BeanCollection to be treated as read only. This
* means no elements can be added or removed etc.
*/
public void setReadOnly(boolean readOnly);
/**
* Return true if the collection should be treated as readOnly and no elements
* can be added or removed etc.
*/
public boolean isReadOnly();
/**
* Add the bean to the collection.
*
* This is disallowed for BeanMap.
*
*/
public void internalAdd(Object bean);
/**
* Returns the underlying List Set or Map object.
*/
public Object getActualCollection();
/**
* Return the number of elements in the List Set or Map.
*/
public int size();
/**
* Return true if the List Set or Map is empty.
*/
public boolean isEmpty();
/**
* Returns the underlying details as an iterator.
*
* Note that for maps this returns the entrySet as we need the keys of the
* map.
*
*/
public Collection getActualDetails();
/**
* Set to true if maxRows was hit and there are actually more rows available.
*
* Can be used by client code that is paging through results using
* setFirstRow() setMaxRows(). If this returns true then the client can
* display a 'next' button etc.
*
*/
public boolean hasMoreRows();
/**
* Set to true when maxRows is hit but there are actually more rows available.
* This is set so that client code knows that there is more data available.
*/
public void setHasMoreRows(boolean hasMoreRows);
/**
* Returns true if the fetch has finished. False if the fetch is continuing in
* a background thread.
*/
public boolean isFinishedFetch();
/**
* Set to true when a fetch has finished. Used when a fetch continues in the
* background.
*/
public void setFinishedFetch(boolean finishedFetch);
/**
* return true if there are real rows held. Return false is this is using
* Deferred fetch to lazy load the rows and the rows have not yet been
* fetched.
*/
public boolean isPopulated();
/**
* Return true if this is a reference (lazy loading) bean collection. This is
* the same as !isPopulated();
*/
public boolean isReference();
/**
* Set modify listening on or off. This is used to keep track of objects that
* have been added to or removed from the list set or map.
*
* This is required only for ManyToMany collections. The additions and
* deletions are used to insert or delete entries from the intersection table.
* Otherwise modifyListening is false.
*
*/
public void setModifyListening(ModifyListenMode modifyListenMode);
/**
* Add an object to the additions list.
*
* This will potentially end up as an insert into a intersection table for a
* ManyToMany.
*
*/
public void modifyAddition(E bean);
/**
* Add an object to the deletions list.
*
* This will potentially end up as an delete from an intersection table for a
* ManyToMany.
*
*/
public void modifyRemoval(Object bean);
/**
* Return the list of objects added to the list set or map. These will used to
* insert rows into the intersection table of a ManyToMany.
*/
public Set getModifyAdditions();
/**
* Return the list of objects removed from the list set or map. These will
* used to delete rows from the intersection table of a ManyToMany.
*/
public Set getModifyRemovals();
/**
* Reset the set of additions and deletions. This is called after the
* additions and removals have been processed.
*/
public void modifyReset();
}