001package com.avaje.ebean.bean;
002
003import java.io.Serializable;
004import java.util.Collection;
005import java.util.Set;
006
007import com.avaje.ebean.ExpressionList;
008
009/**
010 * Lazy loading capable Maps, Lists and Sets.
011 * <p>
012 * This also includes the ability to listen for additions and removals to or
013 * from the Map Set or List. The purpose of gathering the additions and removals
014 * is to support persisting ManyToMany objects. The additions and removals
015 * become inserts and deletes from the intersection table.
016 * </p>
017 * <p>
018 * Technically this is <em>NOT</em> an extension of
019 * <em>java.util.Collection</em>. The reason being that java.util.Map is not a
020 * Collection. I realise this makes this name confusing so I apologise for that.
021 * </p>
022 */
023public interface BeanCollection<E> extends Serializable {
024
025  enum ModifyListenMode {
026    /** The common mode */
027    NONE,
028    /** Mode used for PrivateOwned */
029    REMOVALS,
030    /** Mode used for ManyToMany relationships */
031    ALL
032  }
033
034  /**
035   * Reset the collection back to an empty state ready for reloading.
036   * <p>
037   * This is done as part of bean refresh.
038   */
039  void reset(EntityBean ownerBean, String propertyName);
040
041  /**
042   * Return true if the collection is empty and untouched. Used to detect if a
043   * collection was 'cleared' deliberately or just un-initialised.
044   */
045  boolean isEmptyAndUntouched();
046
047  /**
048   * Return the bean that owns this collection.
049   */
050  EntityBean getOwnerBean();
051
052  /**
053   * Return the bean property name this collection represents.
054   */
055  String getPropertyName();
056
057  /**
058   * Check after the lazy load that the underlying collection is not null
059   * (handle case where join to many not outer).
060   * <p>
061   * That is, if the collection was not loaded due to filterMany predicates etc
062   * then make sure the collection is set to empty.
063   * </p>
064   */
065  boolean checkEmptyLazyLoad();
066
067  /**
068   * Return the filter (if any) that was used in building this collection.
069   * <p>
070   * This is so that the filter can be applied on refresh.
071   * </p>
072   */
073  ExpressionList<?> getFilterMany();
074
075  /**
076   * Set the filter that was used in building this collection.
077   */
078  void setFilterMany(ExpressionList<?> filterMany);
079
080  /**
081   * Set a listener to be notified when the BeanCollection is first touched.
082   */
083  void setBeanCollectionTouched(BeanCollectionTouched notify);
084
085  /**
086   * Return true if the collection has been registered with the batch loading context.
087   */
088  boolean isRegisteredWithLoadContext();
089
090  /**
091   * Set the loader that will be used to lazy/query load this collection.
092   * <p>
093   * This is effectively the batch loading context this collection is registered with.
094   * </p>
095   */
096  void setLoader(BeanCollectionLoader beanLoader);
097
098  /**
099   * Set to true if you want the BeanCollection to be treated as read only. This
100   * means no elements can be added or removed etc.
101   */
102  void setReadOnly(boolean readOnly);
103
104  /**
105   * Return true if the collection should be treated as readOnly and no elements
106   * can be added or removed etc.
107   */
108  boolean isReadOnly();
109
110  /**
111   * Add the bean to the collection.
112   * <p>
113   * This is disallowed for BeanMap.
114   * </p>
115   */
116  void internalAdd(Object bean);
117
118  /**
119   * Return the number of elements in the List Set or Map.
120   */
121  int size();
122
123  /**
124   * Return true if the List Set or Map is empty.
125   */
126  boolean isEmpty();
127
128  /**
129   * Returns the underlying collection of beans from the Set, Map or List.
130   */
131  Collection<E> getActualDetails();
132
133  /**
134   * Returns the underlying entries so for Maps this is a collection of
135   * Map.Entry.
136   * <p>
137   * For maps this returns the entrySet as we need the keys of the map.
138   * </p>
139   */
140  Collection<?> getActualEntries();
141
142  /**
143   * return true if there are real rows held. Return false is this is using
144   * Deferred fetch to lazy load the rows and the rows have not yet been
145   * fetched.
146   */
147  boolean isPopulated();
148
149  /**
150   * Return true if this is a reference (lazy loading) bean collection. This is
151   * the same as !isPopulated();
152   */
153  boolean isReference();
154
155  /**
156   * Set modify listening on or off. This is used to keep track of objects that
157   * have been added to or removed from the list set or map.
158   * <p>
159   * This is required only for ManyToMany collections. The additions and
160   * deletions are used to insert or delete entries from the intersection table.
161   * Otherwise modifyListening is false.
162   * </p>
163   */
164  void setModifyListening(ModifyListenMode modifyListenMode);
165
166  /**
167   * Add an object to the additions list.
168   * <p>
169   * This will potentially end up as an insert into a intersection table for a
170   * ManyToMany.
171   * </p>
172   */
173  void modifyAddition(E bean);
174
175  /**
176   * Add an object to the deletions list.
177   * <p>
178   * This will potentially end up as an delete from an intersection table for a
179   * ManyToMany.
180   * </p>
181   */
182  void modifyRemoval(Object bean);
183
184  /**
185   * Return the list of objects added to the list set or map. These will used to
186   * insert rows into the intersection table of a ManyToMany.
187   */
188  Set<E> getModifyAdditions();
189
190  /**
191   * Return the list of objects removed from the list set or map. These will
192   * used to delete rows from the intersection table of a ManyToMany.
193   */
194  Set<E> getModifyRemovals();
195
196  /**
197   * Reset the set of additions and deletions. This is called after the
198   * additions and removals have been processed.
199   */
200  void modifyReset();
201}