001package io.ebean.bean;
002
003import io.ebean.ExpressionList;
004
005import java.io.Serializable;
006import java.util.Collection;
007import java.util.Set;
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    /**
027     * The common mode
028     */
029    NONE,
030    /**
031     * Mode used for PrivateOwned
032     */
033    REMOVALS,
034    /**
035     * Mode used for ManyToMany relationships
036     */
037    ALL
038  }
039
040  /**
041   * Set the disableLazyLoad state.
042   */
043  void setDisableLazyLoad(boolean disableLazyLoad);
044
045  /**
046   * Load bean from another collection.
047   */
048  void loadFrom(BeanCollection<?> other);
049
050  /**
051   * Add a bean to the list/set with modifyListen notification.
052   */
053  void addBean(E bean);
054
055  /**
056   * Remove a bean to the list/set with modifyListen notification.
057   */
058  void removeBean(E bean);
059
060  /**
061   * Reset the collection back to an empty state ready for reloading.
062   * <p>
063   * This is done as part of bean refresh.
064   */
065  void reset(EntityBean ownerBean, String propertyName);
066
067  /**
068   * Return true if the collection is uninitialised or is empty without any held modifications.
069   * <p>
070   * Returning true means can safely skip cascade save for this bean collection.
071   * </p>
072   */
073  boolean isSkipSave();
074
075  /**
076   * Return true if the collection holds modifications.
077   */
078  boolean holdsModifications();
079
080  /**
081   * Return the bean that owns this collection.
082   */
083  EntityBean getOwnerBean();
084
085  /**
086   * Return the bean property name this collection represents.
087   */
088  String getPropertyName();
089
090  /**
091   * Check after the lazy load that the underlying collection is not null
092   * (handle case where join to many not outer).
093   * <p>
094   * That is, if the collection was not loaded due to filterMany predicates etc
095   * then make sure the collection is set to empty.
096   * </p>
097   */
098  boolean checkEmptyLazyLoad();
099
100  /**
101   * Return the filter (if any) that was used in building this collection.
102   * <p>
103   * This is so that the filter can be applied on refresh.
104   * </p>
105   */
106  ExpressionList<?> getFilterMany();
107
108  /**
109   * Set the filter that was used in building this collection.
110   */
111  void setFilterMany(ExpressionList<?> filterMany);
112
113  /**
114   * Return true if the collection has been registered with the batch loading context.
115   */
116  boolean isRegisteredWithLoadContext();
117
118  /**
119   * Set the loader that will be used to lazy/query load this collection.
120   * <p>
121   * This is effectively the batch loading context this collection is registered with.
122   * </p>
123   */
124  void setLoader(BeanCollectionLoader beanLoader);
125
126  /**
127   * Set to true if you want the BeanCollection to be treated as read only. This
128   * means no elements can be added or removed etc.
129   */
130  void setReadOnly(boolean readOnly);
131
132  /**
133   * Return true if the collection should be treated as readOnly and no elements
134   * can be added or removed etc.
135   */
136  boolean isReadOnly();
137
138  /**
139   * Add the bean to the collection.
140   * <p>
141   * This is disallowed for BeanMap.
142   * </p>
143   */
144  void internalAdd(Object bean);
145
146  /**
147   * Add the bean with a check to see if it is already contained.
148   */
149  void internalAddWithCheck(Object bean);
150
151  /**
152   * Return the number of elements in the List Set or Map.
153   */
154  int size();
155
156  /**
157   * Return true if the List Set or Map is empty.
158   */
159  boolean isEmpty();
160
161  /**
162   * Returns the underlying collection of beans from the Set, Map or List.
163   */
164  Collection<E> getActualDetails();
165
166  /**
167   * Returns the underlying entries so for Maps this is a collection of
168   * Map.Entry.
169   * <p>
170   * For maps this returns the entrySet as we need the keys of the map.
171   * </p>
172   */
173  Collection<?> getActualEntries();
174
175  /**
176   * return true if there are real rows held. Return false is this is using
177   * Deferred fetch to lazy load the rows and the rows have not yet been
178   * fetched.
179   */
180  boolean isPopulated();
181
182  /**
183   * Return true if this is a reference (lazy loading) bean collection. This is
184   * the same as !isPopulated();
185   */
186  boolean isReference();
187
188  /**
189   * Set modify listening on or off. This is used to keep track of objects that
190   * have been added to or removed from the list set or map.
191   * <p>
192   * This is required only for ManyToMany collections. The additions and
193   * deletions are used to insert or delete entries from the intersection table.
194   * Otherwise modifyListening is false.
195   * </p>
196   */
197  void setModifyListening(ModifyListenMode modifyListenMode);
198
199  /**
200   * Return the current modify listening mode. Can be null for on newly created beans.
201   */
202  ModifyListenMode getModifyListening();
203
204  /**
205   * Add an object to the additions list.
206   * <p>
207   * This will potentially end up as an insert into a intersection table for a
208   * ManyToMany.
209   * </p>
210   */
211  void modifyAddition(E bean);
212
213  /**
214   * Add an object to the deletions list.
215   * <p>
216   * This will potentially end up as an delete from an intersection table for a
217   * ManyToMany.
218   * </p>
219   */
220  void modifyRemoval(Object bean);
221
222  /**
223   * Return the list of objects added to the list set or map. These will used to
224   * insert rows into the intersection table of a ManyToMany.
225   */
226  Set<E> getModifyAdditions();
227
228  /**
229   * Return the list of objects removed from the list set or map. These will
230   * used to delete rows from the intersection table of a ManyToMany.
231   */
232  Set<E> getModifyRemovals();
233
234  /**
235   * Reset the set of additions and deletions. This is called after the
236   * additions and removals have been processed.
237   */
238  void modifyReset();
239
240  /**
241   * Has been modified by an addition or removal.
242   */
243  boolean wasTouched();
244
245  /**
246   * Return a shallow copy of this collection that is modifiable.
247   */
248  BeanCollection<E> getShallowCopy();
249}