001package com.avaje.ebean;
002
003import java.beans.PropertyChangeListener;
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   *
049   * <p>
050   *   Typically this would be used to set the loaded state of a property
051   *   to false to ensure that the specific property is excluded from a
052   *   stateless update.
053   * </p>
054   *
055   * <pre>{@code
056   *
057   *   // populate a bean via say JSON
058   *   User user = ...;
059   *
060   *   // set loaded state on the email property to false so that
061   *   // the email property is not included in a stateless update
062   *   Ebean.getBeanState(user).setPropertyLoaded("email", false);
063   *
064   *   user.update();
065   *
066   * }</pre>
067   *
068   *
069   * This will throw an IllegalArgumentException if the property is unknown.
070   */
071  void setPropertyLoaded(String propertyName, boolean loaded);
072
073  /**
074   * For partially populated beans returns the properties that are loaded on the
075   * bean.
076   * <p>
077   * Accessing another property will cause lazy loading to occur.
078   * </p>
079   */
080  Set<String> getLoadedProps();
081
082  /**
083   * Return the set of changed properties.
084   */
085  Set<String> getChangedProps();
086
087  /**
088   * Return a map of the updated properties and their new and old values.
089   */
090  Map<String,ValuePair> getDirtyValues();
091  
092  /**
093   * Return true if the bean is readOnly.
094   * <p>
095   * If a setter is called on a readOnly bean it will throw an exception.
096   * </p>
097   */
098  boolean isReadOnly();
099
100  /**
101   * Set the readOnly status for the bean.
102   */
103  void setReadOnly(boolean readOnly);
104
105  /**
106   * Add a propertyChangeListener.
107   */
108  void addPropertyChangeListener(PropertyChangeListener listener);
109
110  /**
111   * Remove a propertyChangeListener.
112   */
113  void removePropertyChangeListener(PropertyChangeListener listener);
114
115  /**
116   * Advanced - Used to programmatically build a partially or fully loaded
117   * entity bean. First create an entity bean via
118   * {@link EbeanServer#createEntityBean(Class)}, then populate its properties
119   * and then call this method specifying which properties where loaded or null
120   * for a fully loaded entity bean.
121   */
122  void setLoaded();
123}