Workspace/Siman-Common/src/org/splat/dal/bo/kernel/Persistent.java

   1 package org.splat.dal.bo.kernel;
   2
   3 import org.splat.kernel.InvalidPropertyException;
   4 import org.splat.kernel.MissedPropertyException;
   5 import org.splat.kernel.MultiplyDefinedException;
   6 import org.splat.kernel.ObjectProperties;
   7
   8 /**
   9  * Base implementation of the API Design Pattern of objects which persistence is based on Hibernate.<br/> This Design Pattern supports the
  10  * following features:
  11  * <ul>
  12  * <li>Flexible API for constructing objects from many variable arguments</li>
  13  * <li>Impossible to leave persistent objects in inconsistent state, even temporarily, during their construction</li>
  14  * <li>Same Object Oriented API for constructing and selecting objects from the database</li>
  15  * <li>Centralized validity check of arguments</li>
  16  * </ul>
  17  * The API is based on intermediate properties objects used for collecting arguments and checking their validity. These properties objects
  18  * are passed to persistent object constructors and database select functions for execution. For example, as based on this Design Pattern, a
  19  * User object could be created that way:
  20  *
  21  * <pre>
  22  * User.Properties args = new User.Properties();
  23  * User user = new User(args.setUsername(&quot;mypseudo&quot;).setMailAddress(
  24  *              &quot;me@provider.domain&quot;));
  25  * </pre>
  26  *
  27  * Classes implementing this Design Pattern must inherit from Persistent and implement their Properties class as a nested subclass of
  28  * Persistent.Properties.<br/> <br/> Naturally, as usual with Hibernate, any class can be persistent (you don't need to inherit from
  29  * Persistent for being persistent). Inheriting from Persistent is only a matter of enabling the API supported by the above Design Pattern.
  30  *
  31  * @see ObjectProperties
  32  * @see Persistent.Properties
  33  * @author Daniel Brunier-Coulin
  34  * @copyright OPEN CASCADE 2012
  35  */
  36
  37 public abstract class Persistent {
  38
  39         private long rid; // Primary key of persistent objects
  40
  41         protected abstract static class Properties implements ObjectProperties {
  42                 private long rid; // Primary key of persistent objects
  43
  44                 private boolean tobechecked = true; // Property validity check flag
  45
  46                 public void disableCheck() {
  47                         tobechecked = false;
  48                 }
  49
  50                 public boolean mustBeChecked() {
  51                         return tobechecked;
  52                 }
  53
  54                 public void clear() {
  55                         tobechecked = true;
  56                 }
  57
  58                 /**
  59                  * Get the rid.
  60                  *
  61                  * @return the rid
  62                  */
  63                 public long getIndex() {
  64                         return rid;
  65                 }
  66
  67                 /**
  68                  * Set the rid.
  69                  *
  70                  * @param rid
  71                  *            the rid to set
  72                  */
  73                 public void setIndex(long rid) {
  74                         this.rid = rid;
  75                 }
  76         }
  77
  78         // ==============================================================================================================================
  79         // Constructors
  80         // ==============================================================================================================================
  81         /**
  82          * Database fetch constructor.
  83          */
  84         protected Persistent() {
  85                 // -----------------------
  86                 rid = 0; // Set when loading the object
  87         }
  88
  89         /**
  90          * Checks the mutual compatibility of arguments previously set in the given properties object, if the validity check is enabled. As this
  91          * validity depends on concrete classes, the check is delegated to subclasses of the given Persistent.Properties.
  92          */
  93         protected Persistent(ObjectProperties oprop)
  94                         throws MissedPropertyException, InvalidPropertyException,
  95                         MultiplyDefinedException {
  96                 // ---------------------------------------------
  97                 if (oprop.mustBeChecked())
  98                         oprop.checkValidity(); // Throws one of the above exception if not valid
  99                 rid = 0; // Set when saving the object
 100         }
 101
 102         // ==============================================================================================================================
 103         // Public member functions
 104         // ==============================================================================================================================
 105
 106         public boolean equals(Object entity) {
 107                 // ------------------------------------
 108                 if (entity == null)
 109                         return false;
 110                 if (entity.getClass().equals(this.getClass())) {
 111                         Persistent object = (Persistent) entity;
 112                         long he = object.getIndex(); // getIndex() is supposed fetching the index if not yet done
 113                         long me = this.getIndex(); // getIndex() is supposed fetching the index if not yet done
 114                         if (me * he != 0)
 115                                 return (he == me);
 116                         if (me + he == 0)
 117                                 return (this == object);
 118                 }
 119                 return false;
 120         }
 121
 122         /**
 123          * Returns the Persistent ID of this object. The PID is set when saving this object. It is unique in the scope of the class of this
 124          * object only.
 125          *
 126          * @return the PID of this, or 0 if this is not saved.
 127          * @see isSaved()
 128          */
 129         public long getIndex() {
 130                 // ----------------------
 131                 return rid;
 132         }
 133
 134         /**
 135          * Set an id for the object.
 136          *
 137          * @param anId
 138          *            id to set
 139          */
 140         public void setIndex(long anId) {
 141                 rid = anId;
 142         }
 143
 144         public int hashCode() {
 145                 // ----------------------
 146                 return toString().hashCode();
 147         }
 148
 149         /**
 150          * Returns true if this object is saved.
 151          *
 152          * @return true if this is saved.
 153          * @see getIndex()
 154          */
 155         public boolean isSaved() {
 156                 // -------------------------
 157                 return (getIndex() != 0); // getIndex() is supposed fetching the index if not yet done
 158         }
 159
 160         /**
 161          * Return a string representing uniquely this object.
 162          *
 163          * @return the unique string representation of this object.
 164          */
 165         public String toString() {
 166                 // -------------------------
 167                 long oid = getIndex(); // getIndex() is supposed fetching the index if not yet done
 168                 if (oid == 0)
 169                         oid = super.hashCode(); // WARNING: Must not call super.toString() as it goes back here (this.toString())
 170                 return new StringBuffer("object ").append(getClass().getName()).append(
 171                                 "@").append(oid).toString();
 172         }
 173
 174         /**
 175          * Get the rid.
 176          *
 177          * @return the rid
 178          */
 179         public long getRid() {
 180                 return rid;
 181         }
 182
 183         /**
 184          * Set the rid.
 185          *
 186          * @param rid
 187          *            the rid to set
 188          */
 189         public void setRid(long rid) {
 190                 this.rid = rid;
 191         }
 192 }