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-2014
  35  */
  36
  37 public abstract class Persistent {
  38
  39         /**
  40          * Primary key of persistent objects.
  41          */
  42         private long rid;
  43         /**
  44          * UUID of the object used for identification in equals() and in hashCode().
  45          */
  46         private String _uid = IdGenerator.createId();
  47
  48         protected abstract static class Properties implements ObjectProperties {
  49                 /**
  50                  * Primary key of the persistent objects.
  51                  */
  52                 private long rid;
  53
  54                 private boolean tobechecked = true; // Property validity check flag
  55
  56                 public void disableCheck() {
  57                         tobechecked = false;
  58                 }
  59
  60                 public boolean mustBeChecked() {
  61                         return tobechecked;
  62                 }
  63
  64                 public void clear() {
  65                         tobechecked = true;
  66                 }
  67
  68                 /**
  69                  * Get the rid.
  70                  *
  71                  * @return the rid
  72                  */
  73                 public long getIndex() {
  74                         return rid;
  75                 }
  76
  77                 /**
  78                  * Set the rid.
  79                  *
  80                  * @param rid
  81                  *            the rid to set
  82                  */
  83                 public void setIndex(final long rid) {
  84                         this.rid = rid;
  85                 }
  86         }
  87
  88         // ==============================================================================================================================
  89         // Constructors
  90         // ==============================================================================================================================
  91         /**
  92          * Database fetch constructor.
  93          */
  94         protected Persistent() {
  95                 rid = 0; // Set when loading the object
  96         }
  97
  98         /**
  99          * Checks the mutual compatibility of arguments previously set in the given properties object, if the validity check is enabled. As this
 100          * validity depends on concrete classes, the check is delegated to subclasses of the given Persistent.Properties.
 101          */
 102         protected Persistent(final ObjectProperties oprop)
 103                         throws MissedPropertyException, InvalidPropertyException,
 104                         MultiplyDefinedException {
 105                 if (oprop.mustBeChecked()) {
 106                         oprop.checkValidity(); // Throws one of the above exception if not valid
 107                 }
 108                 rid = 0; // Set when saving the object
 109         }
 110
 111         // ==============================================================================================================================
 112         // Public member functions
 113         // ==============================================================================================================================
 114
 115         /**
 116          * Generate new GUID for this object. Must be called when this object is <BR>
 117          * intended to be copied as another new persistent object.
 118          */
 119         public void evict() {
 120                 _uid = IdGenerator.createId();
 121                 rid = 0;
 122         }
 123
 124         /**
 125          * Persistent objects are equal if their UIDs are equal.<BR>
 126          * {@inheritDoc}
 127          *
 128          * @see java.lang.Object#equals(java.lang.Object)
 129          */
 130         @Override
 131         public boolean equals(final Object entity) {
 132                 boolean res = (entity != null);
 133                 if (res) {
 134                         res = Persistent.class.isAssignableFrom(entity.getClass());
 135                         if (res) {
 136                                 Persistent object = (Persistent) entity;
 137                                 res = getUid().equals(object.getUid());
 138                         }
 139                 }
 140                 return res;
 141         }
 142
 143         /**
 144          * 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
 145          * object only.
 146          *
 147          * @return the PID of this, or 0 if this is not saved.
 148          * @see isSaved()
 149          */
 150         public long getIndex() {
 151                 return rid;
 152         }
 153
 154         /**
 155          * Set an id for the object.
 156          *
 157          * @param anId
 158          *            id to set
 159          */
 160         public void setIndex(final long anId) {
 161                 rid = anId;
 162         }
 163
 164         /**
 165          * {@inheritDoc}
 166          *
 167          * @see java.lang.Object#hashCode()
 168          */
 169         @Override
 170         public int hashCode() {
 171                 return getUid().hashCode();
 172         }
 173
 174         /**
 175          * Returns true if this object is saved.
 176          *
 177          * @return true if this is saved.
 178          * @see getIndex()
 179          */
 180         public boolean isSaved() {
 181                 return (getIndex() != 0); // getIndex() is supposed fetching the index if not yet done
 182         }
 183
 184         /**
 185          * Return a string representing uniquely this object.
 186          *
 187          * @return the unique string representation of this object.
 188          */
 189         @Override
 190         public String toString() {
 191                 return new StringBuffer("object ").append(getClass().getName()).append(
 192                                 "@").append(getUid()).append("@").append(getIndex()).toString();
 193         }
 194
 195         /**
 196          * Get the rid.
 197          *
 198          * @return the rid
 199          */
 200         public long getRid() {
 201                 return rid;
 202         }
 203
 204         /**
 205          * Set the rid.
 206          *
 207          * @param rid
 208          *            the rid to set
 209          */
 210         public void setRid(final long rid) {
 211                 this.rid = rid;
 212         }
 213
 214         /**
 215          * Get the uid.
 216          *
 217          * @return the uid
 218          */
 219         public String getUid() {
 220                 return _uid;
 221         }
 222
 223         /**
 224          * Set the uid.
 225          *
 226          * @param uid
 227          *            the uid to set
 228          */
 229         public void setUid(final String uid) {
 230                 _uid = uid;
 231         }
 232 }