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