001package com.avaje.ebean.event;
002
003import java.util.Set;
004
005/**
006 * Used to enhance or override the default bean persistence mechanism.
007 * <p>
008 * Note that if want to totally change the finding, you need to use a BeanQueryAdapter
009 * rather than using postLoad().
010 * </p>
011 * <p>
012 * Note that getTransaction() on the PersistRequest returns the transaction used
013 * for the insert, update, delete or fetch. To explicitly use this same
014 * transaction you should use this transaction via methods on EbeanServer.
015 * </p>
016 * 
017 * <pre class="code">
018 * 
019 *        Object extaBeanToSave = ...;
020 *        Transaction t = request.getTransaction();
021 *        EbeanServer server = request.getEbeanServer();
022 *        server.save(extraBeanToSave, t);
023 * 
024 * </pre>
025 * 
026 * <p>
027 * It is worth noting that BeanPersistListener is different in three main ways
028 * from BeanPersistController postXXX methods.
029 * <ul>
030 * <li>BeanPersistListener only sees successfully committed events.
031 * BeanController pre and post methods occur before the commit or a rollback and
032 * will see events that are later rolled back</li>
033 * <li>BeanPersistListener runs in a background thread and will not effect the
034 * response time of the actual persist where as BeanController code will</li>
035 * <li>BeanPersistListener can be notified of events from other servers in a
036 * cluster.</li>
037 * </ul>
038 * </p>
039 * <p>
040 * A BeanPersistController is either found automatically via class path search
041 * or can be added programmatically via ServerConfiguration.addEntity().
042 * </p>
043 */
044public interface BeanPersistController {
045
046  /**
047   * When there are multiple BeanPersistController's for a given entity type
048   * this controls the order in which they are executed.
049   * <p>
050   * Lowest values are executed first.
051   * </p>
052   * 
053   * @return an int used to control the order BeanPersistController's are
054   *         executed
055   */
056  int getExecutionOrder();
057
058  /**
059   * Return true if this BeanPersistController should be registered for events
060   * on this entity type.
061   */
062  boolean isRegisterFor(Class<?> cls);
063
064  /**
065   * Prior to the insert perform some action. Return true if you want the
066   * default functionality to continue.
067   * <p>
068   * Return false if you have completely replaced the insert functionality and
069   * do not want the default insert to be performed.
070   * </p>
071   */
072  boolean preInsert(BeanPersistRequest<?> request);
073
074  /**
075   * Prior to the update perform some action. Return true if you want the
076   * default functionality to continue.
077   * <p>
078   * Return false if you have completely replaced the update functionality and
079   * do not want the default update to be performed.
080   * </p>
081   */
082  boolean preUpdate(BeanPersistRequest<?> request);
083
084  /**
085   * Prior to the delete perform some action. Return true if you want the
086   * default functionality to continue.
087   * <p>
088   * Return false if you have completely replaced the delete functionality and
089   * do not want the default delete to be performed.
090   * </p>
091   */
092  boolean preDelete(BeanPersistRequest<?> request);
093
094  /**
095   * Called after the insert was performed.
096   */
097  void postInsert(BeanPersistRequest<?> request);
098
099  /**
100   * Called after the update was performed.
101   */
102  void postUpdate(BeanPersistRequest<?> request);
103
104  /**
105   * Called after the delete was performed.
106   */
107  void postDelete(BeanPersistRequest<?> request);
108
109}