src/docbkx/basic-persistence.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <chapter version="5.0" xml:id="basic-persistence"
   3          xmlns="http://docbook.org/ns/docbook"
   4          xmlns:ns5="http://www.w3.org/1999/xhtml"
   5          xmlns:ns4="http://www.w3.org/2000/svg"
   6          xmlns:ns3="http://www.w3.org/1998/Math/MathML"
   7          xmlns:ns2="http://www.w3.org/1999/xlink"
   8          xmlns:ns="http://docbook.org/ns/docbook">
   9   <info>
  10     <title>Basic Persistence</title>
  11   </info>
  12
  13   <section>
  14     <para>The persistence layer of the CDM primarily consists of a set of
  15     <emphasis>data access objects (DAOs)</emphasis>. These DAOs are generic,
  16     strongly typed, and form a hierachy that reflects the inheritance of the
  17     data entities that they provide access too. The root DAO implements
  18     <interfacename>ICdmEntityDao</interfacename>.</para>
  19
  20     <table frame="all" xml:id="icdmentitydao-methods">
  21       <title><interfacename>ICdmEntityDao</interfacename> methods</title>
  22
  23       <tgroup align="left" cols="2" colsep="1" rowsep="1">
  24         <colspec colname="c1" />
  25
  26         <colspec colname="c2" />
  27
  28         <thead>
  29           <row>
  30             <entry>Method</entry>
  31
  32             <entry>Description</entry>
  33           </row>
  34         </thead>
  35
  36         <tbody>
  37           <row>
  38             <entry>
  39               <methodsynopsis>
  40                 <type>UUID</type>
  41
  42                 <methodname>saveOrUpdate</methodname>
  43
  44                 <methodparam>
  45                   <type>T</type>
  46
  47                   <parameter>newOrTransientEntity</parameter>
  48                 </methodparam>
  49               </methodsynopsis>
  50             </entry>
  51
  52             <entry>
  53               <para>Makes a new object persistent, or persists the state of a
  54               transient object.</para>
  55             </entry>
  56           </row>
  57
  58           <row>
  59             <entry>
  60               <methodsynopsis>
  61                 <type>Map&lt;UUID,T&gt;</type>
  62
  63                 <methodname>save</methodname>
  64
  65                 <methodparam>
  66                   <type>Collection&lt;T&gt;</type>
  67
  68                   <parameter>newEntities</parameter>
  69                 </methodparam>
  70               </methodsynopsis>
  71             </entry>
  72
  73             <entry>
  74               <para>Makes a collection of new objects persistent.</para>
  75             </entry>
  76           </row>
  77
  78           <row>
  79             <entry>
  80               <methodsynopsis>
  81                 <type>UUID</type>
  82
  83                 <methodname>save</methodname>
  84
  85                 <methodparam>
  86                   <type>T</type>
  87
  88                   <parameter>newEntity</parameter>
  89                 </methodparam>
  90               </methodsynopsis>
  91             </entry>
  92
  93             <entry>
  94               <para>Makes a new object persistent.</para>
  95             </entry>
  96           </row>
  97
  98           <row>
  99             <entry>
 100               <methodsynopsis>
 101                 <type>UUID</type>
 102
 103                 <methodname>update</methodname>
 104
 105                 <methodparam>
 106                   <type>T</type>
 107
 108                   <parameter>newEntity</parameter>
 109                 </methodparam>
 110               </methodsynopsis>
 111             </entry>
 112
 113             <entry>
 114               <para>Makes changes to a transient object persistent.</para>
 115             </entry>
 116           </row>
 117
 118           <row>
 119             <entry>
 120               <methodsynopsis>
 121                 <type>UUID</type>
 122
 123                 <methodname>merge</methodname>
 124
 125                 <methodparam>
 126                   <type>T</type>
 127
 128                   <parameter>newEntity</parameter>
 129                 </methodparam>
 130               </methodsynopsis>
 131             </entry>
 132
 133             <entry>
 134               <para>Merges the state of a detached object into the persisted
 135               version.</para>
 136             </entry>
 137           </row>
 138
 139           <row>
 140             <entry>
 141               <methodsynopsis>
 142                 <type>UUID</type>
 143
 144                 <methodname>delete</methodname>
 145
 146                 <methodparam>
 147                   <type>T</type>
 148
 149                   <parameter>persistentEntity</parameter>
 150                 </methodparam>
 151               </methodsynopsis>
 152             </entry>
 153
 154             <entry>
 155               <para>Deletes a persistent object.</para>
 156             </entry>
 157           </row>
 158
 159           <row>
 160             <entry>
 161               <methodsynopsis>
 162                 <type>List&lt;T&gt;</type>
 163
 164                 <methodname>list</methodname>
 165
 166                 <methodparam>
 167                   <type>Class&lt;? extends T&gt;</type>
 168
 169                   <parameter>clazz</parameter>
 170                 </methodparam>
 171
 172                 <methodparam>
 173                   <type>Integer</type>
 174
 175                   <parameter>limit</parameter>
 176                 </methodparam>
 177
 178                 <methodparam>
 179                   <type>Integer</type>
 180
 181                   <parameter>start</parameter>
 182                 </methodparam>
 183
 184                 <methodparam>
 185                   <type>List&lt;OrderHint&gt;</type>
 186
 187                   <parameter>orderHints</parameter>
 188                 </methodparam>
 189
 190                 <methodparam>
 191                   <type>List&lt;String&gt;</type>
 192
 193                   <parameter>propertyPaths</parameter>
 194                 </methodparam>
 195               </methodsynopsis>
 196             </entry>
 197
 198             <entry>
 199               <para>Returns a (sub-)list of objects matching the type
 200               <parameter>clazz</parameter>, sorted according to the order
 201               hints and initialized according to the propertyPaths.</para>
 202             </entry>
 203           </row>
 204
 205           <row>
 206             <entry>
 207               <methodsynopsis>
 208                 <type>int</type>
 209
 210                 <methodname>count</methodname>
 211
 212                 <methodparam>
 213                   <type>Class&lt;? extends T&gt;</type>
 214
 215                   <parameter>clazz</parameter>
 216                 </methodparam>
 217               </methodsynopsis>
 218             </entry>
 219
 220             <entry>
 221               <para>Returns a count of objects matching the type
 222               <parameter>clazz</parameter>.</para>
 223             </entry>
 224           </row>
 225
 226           <row>
 227             <entry>
 228               <methodsynopsis>
 229                 <type>T</type>
 230
 231                 <methodname>find</methodname>
 232
 233                 <methodparam>
 234                   <type>UUID</type>
 235
 236                   <parameter>uuid</parameter>
 237                 </methodparam>
 238               </methodsynopsis>
 239             </entry>
 240
 241             <entry>
 242               <para>Returns an object of type T matching the supplied uuid if
 243               it exists.</para>
 244             </entry>
 245           </row>
 246
 247           <row>
 248             <entry>
 249               <methodsynopsis>
 250                 <type>Collection&lt;T&gt;</type>
 251
 252                 <methodname>find</methodname>
 253
 254                 <methodparam>
 255                   <type>Collection&lt;UUID&gt;</type>
 256
 257                   <parameter>uuids</parameter>
 258                 </methodparam>
 259               </methodsynopsis>
 260             </entry>
 261
 262             <entry>
 263               <para>Returns a collection of objects of type T matching the
 264               uuids supplied, if they exist.</para>
 265             </entry>
 266           </row>
 267
 268           <row>
 269             <entry>
 270               <methodsynopsis>
 271                 <type>T</type>
 272
 273                 <methodname>load</methodname>
 274
 275                 <methodparam>
 276                   <type>UUID</type>
 277
 278                   <parameter>uuid</parameter>
 279                 </methodparam>
 280
 281                 <methodparam>
 282                   <type>Collection&lt;String&gt;</type>
 283
 284                   <parameter>propertyPaths</parameter>
 285                 </methodparam>
 286               </methodsynopsis>
 287             </entry>
 288
 289             <entry>
 290               <para>Returns an object of type T with properties initialized
 291               according to the rules described below.</para>
 292             </entry>
 293           </row>
 294
 295           <row>
 296             <entry>
 297               <methodsynopsis>
 298                 <type>Set&lt;T&gt;</type>
 299
 300                 <methodname>load</methodname>
 301
 302                 <methodparam>
 303                   <type>Collection&lt;UUID&gt;</type>
 304
 305                   <parameter>uuids</parameter>
 306                 </methodparam>
 307
 308                 <methodparam>
 309                   <type>Collection&lt;String&gt;</type>
 310
 311                   <parameter>propertyPaths</parameter>
 312                 </methodparam>
 313               </methodsynopsis>
 314             </entry>
 315
 316             <entry>
 317               <para>Returns a collection of objects of type T matching the
 318               uuids supplied, if they exist, initialized according to the
 319               rules described below.</para>
 320             </entry>
 321           </row>
 322
 323           <row>
 324             <entry>
 325               <methodsynopsis>
 326                 <type>boolean</type>
 327
 328                 <methodname>exists</methodname>
 329
 330                 <methodparam>
 331                   <type>UUID</type>
 332
 333                   <parameter>uuid</parameter>
 334                 </methodparam>
 335               </methodsynopsis>
 336             </entry>
 337
 338             <entry>
 339               <para>Returns true if there is an object of type T in the
 340               database matching the supplied uuid.</para>
 341             </entry>
 342           </row>
 343
 344           <row>
 345             <entry>
 346               <methodsynopsis>
 347                 <type>Class&lt;T&gt;</type>
 348
 349                 <methodname>getType</methodname>
 350               </methodsynopsis>
 351             </entry>
 352
 353             <entry>
 354               <para>Returns the class of objects that this DAO provides access
 355               to.</para>
 356             </entry>
 357           </row>
 358         </tbody>
 359       </tgroup>
 360     </table>
 361
 362     <figure>
 363       <title>An overview of the cdm persistence layer</title>
 364
 365       <mediaobject>
 366         <imageobject role="html">
 367           <imagedata fileref="resources/images/dao.png" format="png" />
 368         </imageobject>
 369
 370         <imageobject role="fo">
 371           <imagedata contentwidth="160mm"
 372                      fileref="resources/images/dao.png" format="png"
 373                      scalefit="1" />
 374         </imageobject>
 375
 376         <caption>The DAO hierarchy in the CDM persistence layer. Data Access Objects are strongly typed
 377         and their hierarchy follows the hierarchy of major entities in the CDM.</caption>
 378       </mediaobject>
 379     </figure>
 380
 381     <section>
 382       <info>
 383         <title>Object Initialization</title>
 384       </info>
 385
 386       <para>DAO methods that return objects, return entities without any
 387       relationships initialized by default (to learn more about initialization
 388       of related entities, lazy-loading etc, please consult the hibernate
 389       documentation). Because some applications (particularly stateless
 390       multi-user applications with concise units of work i.e. web
 391       applications), may wish to limit the length of transactions, it is
 392       important to be able to explicitly initialize related entities according
 393       to the particular use-case. The CDM library allows application
 394       developers to do this on a per-method call basis.</para>
 395
 396       <para>Properties of the root object specified using java-beans-like
 397       syntax and passed using the <parameter>propertyPaths</parameter>
 398       parameter will be initialialised before the object(s) are returned and
 399       can safely used. Applications that access other properties (that are
 400       part of related entities) outside of the transaction in which the entity
 401       was retrieved (i.e. the entity is detached) are likely to throw a
 402       <exceptionname>LazyInitializationException</exceptionname>. In addition
 403       to specifying properties by name, developers can also use an asterisk
 404       (*) to represent all *-to-many properties, and a dollar sign ($) to
 405       represent all *-to-one properties of the root entity or a related
 406       entity. Using a wildcard terminates the property path (i.e. it is not
 407       valid syntax to include characters after a wildcard in a propertyPath
 408       expression - the wildcard must be the final character in the
 409       string).</para>
 410     </section>
 411
 412     <section>
 413       <info>
 414         <title>Listing objects and sorting lists</title>
 415       </info>
 416
 417       <para>In addition to allowing single objects and collections of objects
 418       matching specific UUIDs to be returned, the GenericDAO also allows lists
 419       of objects of type T to be returned (to allow browsing of the entire
 420       collection of entities, for example). In many cases, applications will
 421       wish to restrict the total number of objects returned to a subset of the
 422       total available objects (to reduce resource requirements, or increase
 423       speed of rendering of a response, for example). This can be achieved by
 424       supplying non-null <parameter>limit</parameter> and
 425       <parameter>start</parameter> parameters to restrict the total number of
 426       objects returned. These parameters are analogous to the "limit" and
 427       "offset" parameters in SQL and are zero-based (i.e. the first result is
 428       0, not 1).</para>
 429
 430       <para>Lists of objects are returned sorted according to the
 431       <parameter>orderHints</parameter> parameter. Like the
 432       <parameter>propertyPaths</parameter> parameter,
 433       <classname>OrderHint</classname> objects take a java-beans-style string
 434       that indicates the property or related entity that the list of returned
 435       objects should be ordered by, and a <classname>SortOrder</classname>
 436       that determined whether the list is sorted in ascending or descending
 437       order.</para>
 438     </section>
 439   </section>
 440 </chapter>