001package io.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 Database.
013 * </p>
014 * <pre>{@code
015 *
016 *   Object extaBeanToSave = ...;
017 *   Transaction t = request.getTransaction();
018 *   Database server = request.getEbeanServer();
019 *   database.save(extraBeanToSave, t);
020 *
021 * }</pre>
022 * <p>
023 * It is worth noting that BeanPersistListener is different in three main ways
024 * from BeanPersistController postXXX methods.
025 * </p>
026 * <ul>
027 * <li>BeanPersistListener only sees successfully committed events.
028 * BeanController pre and post methods occur before the commit or a rollback and
029 * will see events that are later rolled back</li>
030 * <li>BeanPersistListener runs in a background thread and will not effect the
031 * response time of the actual persist where as BeanController code will</li>
032 * <li>BeanPersistListener can be notified of events from other servers in a
033 * cluster.</li>
034 * </ul>
035 * <p>
036 * A BeanPersistController is either found automatically via class path search
037 * or can be added programmatically via DatabaseConfig.add().
038 * </p>
039 */
040public interface BeanPersistController {
041
042  /**
043   * When there are multiple BeanPersistController's for a given entity type
044   * this controls the order in which they are executed.
045   * <p>
046   * Lowest values are executed first.
047   * </p>
048   *
049   * @return an int used to control the order BeanPersistController's are executed
050   */
051  int getExecutionOrder();
052
053  /**
054   * Return true if this BeanPersistController should be registered for events
055   * on this entity type.
056   */
057  boolean isRegisterFor(Class<?> cls);
058
059  /**
060   * Prior to the insert perform some action. Return true if you want the
061   * default functionality to continue.
062   * <p>
063   * Return false if you have completely replaced the insert functionality and
064   * do not want the default insert to be performed.
065   * </p>
066   */
067  boolean preInsert(BeanPersistRequest<?> request);
068
069  /**
070   * Prior to the update perform some action. Return true if you want the
071   * default functionality to continue.
072   * <p>
073   * Return false if you have completely replaced the update functionality and
074   * do not want the default update to be performed.
075   * </p>
076   */
077  boolean preUpdate(BeanPersistRequest<?> request);
078
079  /**
080   * Prior to the delete perform some action. Return true if you want the
081   * default functionality to continue.
082   * <p>
083   * Return false if you have completely replaced the delete functionality and
084   * do not want the default delete to be performed.
085   * </p>
086   */
087  boolean preDelete(BeanPersistRequest<?> request);
088
089  /**
090   * Prior to a soft delete perform some action. Return true if you want the
091   * default functionality to continue.
092   */
093  boolean preSoftDelete(BeanPersistRequest<?> request);
094
095  /**
096   * Prior to a delete by id perform some action.
097   */
098  void preDelete(BeanDeleteIdRequest request);
099
100  /**
101   * Called after the insert was performed.
102   */
103  void postInsert(BeanPersistRequest<?> request);
104
105  /**
106   * Called after the update was performed.
107   */
108  void postUpdate(BeanPersistRequest<?> request);
109
110  /**
111   * Called after the delete was performed.
112   */
113  void postDelete(BeanPersistRequest<?> request);
114
115  /**
116   * Called after the soft delete was performed.
117   */
118  void postSoftDelete(BeanPersistRequest<?> request);
119}