001package com.avaje.ebean.event;
002
003import java.util.Set;
004
005import com.avaje.ebean.config.ServerConfig;
006
007/**
008 * Listens for committed bean events.
009 * <p>
010 * These listen events occur after a successful commit. They also occur in a
011 * background thread rather than the thread used to perform the actual insert
012 * update or delete. In this way there is a delay between the commit and when
013 * the listener is notified of the event.
014 * </p>
015 * <p>
016 * For a cluster these events may need to be broadcast. Each of the inserted(),
017 * updated() and deleted() methods return true if you want those events to be
018 * broadcast to the other members of a cluster (the id values are broadcast). If
019 * these methods return false then the events are not broadcast.
020 * </p>
021 * <p>
022 * It is worth noting that BeanPersistListener is different in three main ways
023 * from BeanPersistController postXXX methods.
024 * <ul>
025 * <li>BeanPersistListener only sees successfully committed events.
026 * BeanPersistController pre and post methods occur before the commit or a
027 * rollback and will see events that are later rolled back</li>
028 * <li>BeanPersistListener runs in a background thread and will not effect the
029 * response time of the actual persist where as BeanPersistController code will</li>
030 * <li>BeanPersistListener can be notified of events from other servers in a
031 * cluster.</li>
032 * </ul>
033 * </p>
034 * <p>
035 * A BeanPersistListener is either found automatically via class path search or
036 * can be added programmatically via {@link ServerConfig#add(BeanPersistListener)}}.
037 * </p>
038 * @see ServerConfig#add(BeanPersistListener)
039 */
040public interface BeanPersistListener {
041
042  /**
043   * Return true if this BeanPersistListener should be registered for events
044   * on this entity type.
045   */
046  boolean isRegisterFor(Class<?> cls);
047
048  /**
049   * Notified that a bean has been inserted locally. Return true if you want the
050   * cluster to be notified of the event.
051   * 
052   * @param bean
053   *          The bean that was inserted.
054   */
055  boolean inserted(Object bean);
056
057  /**
058   * Notified that a bean has been updated locally. Return true if you want the
059   * cluster to be notified of the event.
060   * 
061   * @param bean
062   *          The bean that was updated.
063   * @param updatedProperties
064   *          The properties that were modified by this update.
065   */
066  boolean updated(Object bean, Set<String> updatedProperties);
067
068  /**
069   * Notified that a bean has been deleted locally. Return true if you want the
070   * cluster to be notified of the event.
071   * 
072   * @param bean
073   *          The bean that was deleted.
074   */
075  boolean deleted(Object bean);
076
077  /**
078   * Notify that a bean was inserted on another node of the cluster.
079   * 
080   * @param id
081   *          the id value of the inserted bean
082   */
083  void remoteInsert(Object id);
084
085  /**
086   * Notify that a bean was updated on another node of the cluster.
087   * 
088   * @param id
089   *          the id value of the updated bean.
090   */
091  void remoteUpdate(Object id);
092
093  /**
094   * Notify that a bean was deleted on another node of the cluster.
095   * 
096   * @param id
097   *          the id value of the deleted bean.
098   */
099  void remoteDelete(Object id);
100
101}