001package io.ebean;
002
003import java.util.Map;
004import java.util.Set;
005
006/**
007 * Provides access to the internal state of an entity bean.
008 */
009public interface BeanState {
010
011  /**
012   * Return true if this is a lazy loading reference bean.
013   * <p>
014   * If so the this bean only holds the Id property and will invoke lazy loading
015   * if any other property is get or set.
016   * </p>
017   */
018  boolean isReference();
019
020  /**
021   * Return true if the bean is new (and not yet saved).
022   */
023  boolean isNew();
024
025  /**
026   * Return true if the bean is new or dirty (and probably needs to be saved).
027   */
028  boolean isNewOrDirty();
029
030  /**
031   * Return true if the bean has been changed but not yet saved.
032   */
033  boolean isDirty();
034
035  /**
036   * This can be called with true to disable lazy loading on the bean.
037   */
038  void setDisableLazyLoad(boolean disableLazyLoading);
039
040  /**
041   * Return true if the bean has lazy loading disabled.
042   */
043  boolean isDisableLazyLoad();
044
045  /**
046   * Set the loaded state of the property given it's name.
047   * <p>
048   * Typically this would be used to set the loaded state of a property
049   * to false to ensure that the specific property is excluded from a
050   * stateless update.
051   * </p>
052   * <pre>{@code
053   *
054   *   // populate a bean via say JSON
055   *   User user = ...;
056   *
057   *   // set loaded state on the email property to false so that
058   *   // the email property is not included in a stateless update
059   *   DB.beanState(user).setPropertyLoaded("email", false);
060   *
061   *   user.update();
062   *
063   * }</pre>
064   * <p>
065   * This will throw an IllegalArgumentException if the property is unknown.
066   */
067  void setPropertyLoaded(String propertyName, boolean loaded);
068
069  /**
070   * For partially populated beans returns the properties that are loaded on the
071   * bean.
072   * <p>
073   * Accessing another property will cause lazy loading to occur.
074   */
075  Set<String> loadedProps();
076
077  /**
078   * Deprecated migrate to loadedProps().
079   */
080  @Deprecated
081  default Set<String> getLoadedProps() {
082    return loadedProps();
083  }
084
085  /**
086   * Return the set of changed properties.
087   */
088  Set<String> changedProps();
089
090  /**
091   * Deprecated migrate to changedProps().
092   */
093  @Deprecated
094  default Set<String> getChangedProps() {
095    return changedProps();
096  }
097
098  /**
099   * Return a map of the updated properties and their new and old values.
100   */
101  Map<String, ValuePair> dirtyValues();
102
103  /**
104   * Deprecated migrate to dirtyValues().
105   */
106  @Deprecated
107  default Map<String, ValuePair> getDirtyValues() {
108    return dirtyValues();
109  }
110
111  /**
112   * Return true if the bean is readOnly.
113   * <p>
114   * If a setter is called on a readOnly bean it will throw an exception.
115   */
116  boolean isReadOnly();
117
118  /**
119   * Set the readOnly status for the bean.
120   */
121  void setReadOnly(boolean readOnly);
122
123  /**
124   * Advanced - Used to programmatically build a partially or fully loaded
125   * entity bean. First create an entity bean via
126   * {@link Database#createEntityBean(Class)}, then populate its properties
127   * and then call this method specifying which properties where loaded or null
128   * for a fully loaded entity bean.
129   */
130  void setLoaded();
131
132  /**
133   * Reset the bean putting it into NEW state such that a save() results in an insert.
134   */
135  void resetForInsert();
136
137  /**
138   * Returns a map with load errors.
139   */
140  Map<String, Exception> loadErrors();
141
142  /**
143   * Deprecated migrate to loadErrors().
144   */
145  @Deprecated
146  default Map<String, Exception> getLoadErrors() {
147    return loadErrors();
148  }
149
150  /**
151   * Return the sort order value for an order column.
152   */
153  int sortOrder();
154
155  /**
156   * Deprecated migrate to sortOrder().
157   */
158  @Deprecated
159  default int getSortOrder() {
160    return sortOrder();
161  }
162}