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