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