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