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