src/docbkx/base-classes.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <chapter version="5.0" xml:id="base-classes" xmlns="http://docbook.org/ns/docbook"
   3          xmlns:ns5="http://www.w3.org/1999/xhtml"
   4          xmlns:ns4="http://www.w3.org/2000/svg"
   5          xmlns:ns3="http://www.w3.org/1998/Math/MathML"
   6          xmlns:ns2="http://www.w3.org/1999/xlink"
   7          xmlns:ns="http://docbook.org/ns/docbook">
   8   <info>
   9     <title>Base Classes</title>
  10   </info>
  11
  12   <section>
  13     <para>Almost all classes in the CDM implement ICdmBase, an interface that
  14     specifies common attributes which are:</para>
  15
  16     <programlisting>package eu.etaxonomy.cdm.model.common;
  17
  18 public interface ICdmBase {
  19
  20 /**
  21  * Returns local unique identifier for the concrete subclass
  22  * @return
  23  */
  24 public int getId();
  25
  26 /**
  27  * Assigns a unique local ID to this object.
  28  * Because of the EJB3 @Id and @GeneratedValue annotation this id will be
  29  * set automatically by the persistence framework when object is saved.
  30  * @param id
  31  */
  32 public void setId(int id);
  33
  34 public UUID getUuid();
  35
  36 public void setUuid(UUID uuid);
  37
  38 public DateTime getCreated();
  39
  40 /**
  41  * Sets the timestamp this object was created.
  42  *
  43  * @param created
  44  */
  45 public void setCreated(DateTime created);
  46
  47 public User getCreatedBy();
  48
  49 public void setCreatedBy(User createdBy);
  50 }</programlisting>
  51
  52     <para>Although all instances have a primary key (<varname>id</varname>)
  53     that is used by any database software, this should not be used to refer to
  54     the entity in an application. Instead, a surrogate key
  55     (<varname>uuid</varname>) is used to identify entities. Both values are
  56     auto-generated, <varname>uuid</varname> when the object is created,
  57     <varname>id</varname> at the point the object is persisted (through a call
  58     to <methodname>save</methodname> or
  59     <methodname>saveOrUpdate</methodname>).</para>
  60
  61     <para>Throughout the CDM, temporal data is represented using the <link
  62     href="http://joda-time.sourceforge.net/">Joda Time API</link> rather than
  63     the standard java Calender implementation. All CdmBase classes have a
  64     property that gives their time of creation (<varname>created</varname>,
  65     populated automatically), and the <classname>User</classname> that created
  66     the object. The user is retrieved from the security context automatically
  67     by the persistence layer (for more on security in the CDM, authentication
  68     and authorization, see the section on <link
  69     linkend="security">security</link>). For those applications that do not
  70     wish to use the security infrastructure, the User can also be set
  71     explicitly by the application.</para>
  72   </section>
  73
  74   <section>
  75     <title>Versionable Entities</title>
  76
  77     <para>Almost all entities in the CDM are subclasses of
  78     <classname>VersionableEntity</classname>. This means that the changing
  79     (persistent) state of an entity through time can be recorded in the
  80     database, and recovered. This is quite a complex idea and is covered in
  81     full in the chapter on <link linkend="versioning">versioning</link>.
  82     Versionable entities have two additional properties:
  83     <varname>updated</varname>, that holds the date-time when the object was
  84     last made persistent, and <varname>updatedBy</varname>, that provides the
  85     user that last updated the entity. Both work in an identical way to
  86     <varname>created</varname> and <varname>createdBy</varname>. </para>
  87   </section>
  88   <section>
  89     <title>Data model implementation and patterns used across the CDM</title>
  90     <para>It is worth touching on a couple of common patterns used in implementing the CDM in java: <emphasis>private no-arg constructor</emphasis>s and<emphasis>protected access to collection setters</emphasis>. The ORM technology used in the CDM requires that no-arg constructors exist, and likewise it requires that collections have setter methods as well as getters. However, it is good practice to prevent client application access to these methods to prevent application developers inadvertantly causing mischief (for example, by incorrectly implementing a bidirectional link between a parent and child object). </para>
  91     <para>To instantiate a new CDM entity programmatically, application developers must use one of the public static factory methods provided by the class. Changing the state of single properties is achieved through normal use of getters and setters. In the case of properties that extend <classname>java.util.Collection</classname> or <classname>java.util.Map</classname>, these collections can be changed through <methodname>add<emphasis>X</emphasis></methodname> and <methodname>remove<emphasis>X</emphasis></methodname>, where <emphasis>X</emphasis> is the property name rather than <methodname>set<emphasis>X</emphasis></methodname>.</para>
  92   </section>
  93 </chapter>