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/>
  10  * This Design Pattern supports the 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.
  18  * These properties objects are passed to persistent object constructors and database select functions for execution.
  19  * For example, as based on this Design Pattern, a User object could be created that way:
  20  * <pre>
  21  *   User.Properties  args = new User.Properties();
  22  *   User  user = new User( args.setUsername("mypseudo").setMailAddress("me@provider.domain") );
  23  * </pre>
  24  * Classes implementing this Design Pattern must inherit from Persistent and implement their Properties class as a nested
  25  * subclass of Persistent.Properties.<br/>
  26  * <br/>
  27  * Naturally, as usual with Hibernate, any class can be persistent (you don't need to inherit from Persistent for being
  28  * persistent). Inheriting from Persistent is only a matter of enabling the API supported by the above Design Pattern.
  29  *
  30  * @see ObjectProperties
  31  * @see Persistent.Properties
  32  * @author    Daniel Brunier-Coulin
  33  * @copyright OPEN CASCADE 2012
  34  */
  35
  36
  37 public abstract class Persistent {
  38
  39     private  int rid;                                     // Primary key of persistent objects
  40
  41     protected abstract static class Properties implements ObjectProperties {
  42 //  ----------------------------------------------------------------------
  43       private boolean tobechecked = true;                 // Property validity check flag
  44
  45           public void disableCheck () {
  46         tobechecked = false;
  47       }
  48           public boolean mustBeChecked () {
  49                 return tobechecked;
  50           }
  51           public void clear () {
  52                 tobechecked = true;
  53           }
  54     }
  55
  56 //  ==============================================================================================================================
  57 //  Constructors
  58 //  ==============================================================================================================================
  59 /**
  60  * Database fetch constructor.
  61  */
  62     protected Persistent () {
  63 //  -----------------------
  64       rid = 0;                                            // Set when loading the object
  65     }
  66
  67 /**
  68  * Checks the mutual compatibility of arguments previously set in the given properties object, if the validity check is enabled.
  69  * As this validity depends on concrete classes, the check is delegated to subclasses of the given Persistent.Properties.
  70  */
  71     protected Persistent (ObjectProperties oprop) throws MissedPropertyException, InvalidPropertyException, MultiplyDefinedException {
  72 //  ---------------------------------------------
  73       if (oprop.mustBeChecked()) oprop.checkValidity();   // Throws one of the above exception if not valid
  74       rid = 0;                                            // Set when saving the object
  75     }
  76
  77 //  ==============================================================================================================================
  78 //  Public member functions
  79 //  ==============================================================================================================================
  80
  81     public boolean equals(Object entity) {
  82 //  ------------------------------------
  83       if (entity == null) return false;
  84       if (entity.getClass().equals(this.getClass())) {
  85         Persistent object = (Persistent)entity;
  86         int   he = object.getIndex();                     // getIndex() is supposed fetching the index if not yet done
  87         int   me = this.getIndex();                       // getIndex() is supposed fetching the index if not yet done
  88         if (me*he != 0) return (he == me);
  89         if (me+he == 0) return (this == object);
  90       }
  91       return false;
  92     }
  93
  94 /**
  95  * Returns the Persistent ID of this object. The PID is set when saving this object. It is unique in the scope of the class
  96  * of this object only.
  97  *
  98  * @return the PID of this, or 0 if this is not saved.
  99  * @see    isSaved()
 100  */
 101     public int getIndex () {
 102 //  ----------------------
 103       return rid;
 104     }
 105
 106     public int hashCode () {
 107 //  ----------------------
 108       return toString().hashCode();
 109     }
 110
 111 /**
 112  * Returns true if this object is saved.
 113  *
 114  * @return true if this is saved.
 115  * @see    getIndex()
 116  */
 117     public boolean isSaved () {
 118 //  -------------------------
 119       return (getIndex() != 0);                           // getIndex() is supposed fetching the index if not yet done
 120     }
 121
 122 /**
 123  * Return a string representing uniquely this object.
 124  *
 125  * @return the unique string representation of this object.
 126  */
 127     public String toString () {
 128 //  -------------------------
 129       int oid = getIndex();                               // getIndex() is supposed fetching the index if not yet done
 130       if (oid == 0) oid = super.hashCode();               //WARNING: Must not call super.toString() as it goes back here (this.toString())
 131       return new StringBuffer("object ").append(getClass().getName()).append("@").append(oid).toString();
 132     }
 133 }