src/docbkx/service.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <chapter version="5.0" xml:id="service" 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>Services</title>
  10   </info>
  11
  12   <section>
  13     <para>The service layer of the CDM contains a set of service objects that
  14     are intended to provide basic query, search and persistence functionality
  15     for the CDM objects, plus business logic to support common tasks. These
  16     objects are intended to be singleton services used across the whole
  17     application. As with the persistence layer, the services are strongly
  18     typed, generic service objects, with a single service per (significant
  19     base) class. All service classes implement
  20     <interfacename>IService</interfacename> and most implement
  21     <interfacename>IVersionableService</interfacename>, providing access to
  22     generic base methods to deal with the class.</para>
  23
  24      <figure>
  25       <title>An overview of the cdm service layer</title>
  26
  27       <mediaobject>
  28         <imageobject role="html">
  29           <imagedata fileref="resources/images/service.png" format="png" />
  30         </imageobject>
  31
  32         <imageobject role="fo">
  33           <imagedata contentwidth="160mm"
  34                      fileref="resources/images/service.png" format="png"
  35                      scalefit="1" />
  36         </imageobject>
  37
  38         <caption>The Service layer in the CDM Java Library. There is a service for each major type of data that the CDM deals with.</caption>
  39       </mediaobject>
  40     </figure>
  41
  42     <table frame="all" xml:id="iservice-methods">
  43       <title><interfacename>IService</interfacename> methods</title>
  44
  45       <tgroup align="left" cols="2" colsep="1" rowsep="1">
  46         <colspec colname="c1" />
  47
  48         <colspec colname="c2" />
  49
  50         <thead>
  51           <row>
  52             <entry>Method</entry>
  53
  54             <entry>Description</entry>
  55           </row>
  56         </thead>
  57
  58         <tbody>
  59           <row>
  60             <entry>
  61               <methodsynopsis>
  62                 <type>UUID</type>
  63
  64                 <methodname>saveOrUpdate</methodname>
  65
  66                 <methodparam>
  67                   <type>T</type>
  68
  69                   <parameter>newOrTransientEntity</parameter>
  70                 </methodparam>
  71               </methodsynopsis>
  72             </entry>
  73
  74             <entry>
  75               <para>Makes a new object persistent, or persists the state of a
  76               transient object.</para>
  77             </entry>
  78           </row>
  79
  80           <row>
  81             <entry>
  82               <methodsynopsis>
  83                 <type>Map&lt;UUID,T&gt;</type>
  84
  85                 <methodname>save</methodname>
  86
  87                 <methodparam>
  88                   <type>Collection&lt;T&gt;</type>
  89
  90                   <parameter>newEntities</parameter>
  91                 </methodparam>
  92               </methodsynopsis>
  93             </entry>
  94
  95             <entry>
  96               <para>Makes a collection of new objects persistent.</para>
  97             </entry>
  98           </row>
  99
 100           <row>
 101             <entry>
 102               <methodsynopsis>
 103                 <type>UUID</type>
 104
 105                 <methodname>save</methodname>
 106
 107                 <methodparam>
 108                   <type>T</type>
 109
 110                   <parameter>newEntity</parameter>
 111                 </methodparam>
 112               </methodsynopsis>
 113             </entry>
 114
 115             <entry>
 116               <para>Makes a new object persistent.</para>
 117             </entry>
 118           </row>
 119
 120           <row>
 121             <entry>
 122               <methodsynopsis>
 123                 <type>UUID</type>
 124
 125                 <methodname>update</methodname>
 126
 127                 <methodparam>
 128                   <type>T</type>
 129
 130                   <parameter>newEntity</parameter>
 131                 </methodparam>
 132               </methodsynopsis>
 133             </entry>
 134
 135             <entry>
 136               <para>Makes changes to a transient object persistent.</para>
 137             </entry>
 138           </row>
 139
 140           <row>
 141             <entry>
 142               <methodsynopsis>
 143                 <type>UUID</type>
 144
 145                 <methodname>merge</methodname>
 146
 147                 <methodparam>
 148                   <type>T</type>
 149
 150                   <parameter>newEntity</parameter>
 151                 </methodparam>
 152               </methodsynopsis>
 153             </entry>
 154
 155             <entry>
 156               <para>Merges the state of a detached object into the persisted
 157               version.</para>
 158             </entry>
 159           </row>
 160
 161           <row>
 162             <entry>
 163               <methodsynopsis>
 164                 <type>UUID</type>
 165
 166                 <methodname>delete</methodname>
 167
 168                 <methodparam>
 169                   <type>T</type>
 170
 171                   <parameter>persistentEntity</parameter>
 172                 </methodparam>
 173               </methodsynopsis>
 174             </entry>
 175
 176             <entry>
 177               <para>Deletes a persistent object.</para>
 178             </entry>
 179           </row>
 180
 181           <row>
 182             <entry>
 183               <methodsynopsis>
 184                 <type>List&lt;T&gt;</type>
 185
 186                 <methodname>list</methodname>
 187
 188                 <methodparam>
 189                   <type>Class&lt;? extends T&gt;</type>
 190
 191                   <parameter>clazz</parameter>
 192                 </methodparam>
 193
 194                 <methodparam>
 195                   <type>Integer</type>
 196
 197                   <parameter>pageSize</parameter>
 198                 </methodparam>
 199
 200                 <methodparam>
 201                   <type>Integer</type>
 202
 203                   <parameter>pageNumber</parameter>
 204                 </methodparam>
 205
 206                 <methodparam>
 207                   <type>List&lt;OrderHint&gt;</type>
 208
 209                   <parameter>orderHints</parameter>
 210                 </methodparam>
 211
 212                 <methodparam>
 213                   <type>List&lt;String&gt;</type>
 214
 215                   <parameter>propertyPaths</parameter>
 216                 </methodparam>
 217               </methodsynopsis>
 218             </entry>
 219
 220             <entry>
 221               <para>Returns a (sub-)list of objects matching the type
 222               <parameter>clazz</parameter>, sorted according to the order
 223               hints and initialized according to the propertyPaths.</para>
 224             </entry>
 225           </row>
 226
 227           <row>
 228             <entry>
 229               <methodsynopsis>
 230                 <type>Pager&lt;T&gt;</type>
 231
 232                 <methodname>page</methodname>
 233
 234                 <methodparam>
 235                   <type>Class&lt;? extends T&gt;</type>
 236
 237                   <parameter>clazz</parameter>
 238                 </methodparam>
 239
 240                 <methodparam>
 241                   <type>Integer</type>
 242
 243                   <parameter>pageSize</parameter>
 244                 </methodparam>
 245
 246                 <methodparam>
 247                   <type>Integer</type>
 248
 249                   <parameter>pageNumber</parameter>
 250                 </methodparam>
 251
 252                 <methodparam>
 253                   <type>List&lt;OrderHint&gt;</type>
 254
 255                   <parameter>orderHints</parameter>
 256                 </methodparam>
 257
 258                 <methodparam>
 259                   <type>List&lt;String&gt;</type>
 260
 261                   <parameter>propertyPaths</parameter>
 262                 </methodparam>
 263               </methodsynopsis>
 264             </entry>
 265
 266             <entry>
 267               <para>Returns a paged (sub-)list of objects matching the type
 268               <parameter>clazz</parameter>, sorted according to the order
 269               hints and initialized according to the propertyPaths.</para>
 270             </entry>
 271           </row>
 272
 273           <row>
 274             <entry>
 275               <methodsynopsis>
 276                 <type>int</type>
 277
 278                 <methodname>count</methodname>
 279
 280                 <methodparam>
 281                   <type>Class&lt;? extends T&gt;</type>
 282
 283                   <parameter>clazz</parameter>
 284                 </methodparam>
 285               </methodsynopsis>
 286             </entry>
 287
 288             <entry>
 289               <para>Returns a count of objects matching the type
 290               <parameter>clazz</parameter>.</para>
 291             </entry>
 292           </row>
 293
 294           <row>
 295             <entry>
 296               <methodsynopsis>
 297                 <type>T</type>
 298
 299                 <methodname>find</methodname>
 300
 301                 <methodparam>
 302                   <type>UUID</type>
 303
 304                   <parameter>uuid</parameter>
 305                 </methodparam>
 306               </methodsynopsis>
 307             </entry>
 308
 309             <entry>
 310               <para>Returns an object of type T matching the supplied uuid if
 311               it exists.</para>
 312             </entry>
 313           </row>
 314
 315           <row>
 316             <entry>
 317               <methodsynopsis>
 318                 <type>Collection&lt;T&gt;</type>
 319
 320                 <methodname>find</methodname>
 321
 322                 <methodparam>
 323                   <type>Collection&lt;UUID&gt;</type>
 324
 325                   <parameter>uuids</parameter>
 326                 </methodparam>
 327               </methodsynopsis>
 328             </entry>
 329
 330             <entry>
 331               <para>Returns a collection of objects of type T matching the
 332               uuids supplied, if they exist.</para>
 333             </entry>
 334           </row>
 335
 336           <row>
 337             <entry>
 338               <methodsynopsis>
 339                 <type>T</type>
 340
 341                 <methodname>load</methodname>
 342
 343                 <methodparam>
 344                   <type>UUID</type>
 345
 346                   <parameter>uuid</parameter>
 347                 </methodparam>
 348
 349                 <methodparam>
 350                   <type>Collection&lt;String&gt;</type>
 351
 352                   <parameter>propertyPaths</parameter>
 353                 </methodparam>
 354               </methodsynopsis>
 355             </entry>
 356
 357             <entry>
 358               <para>Returns an object of type T with properties initialized
 359               according to the rules described below.</para>
 360             </entry>
 361           </row>
 362
 363           <row>
 364             <entry>
 365               <methodsynopsis>
 366                 <type>Set&lt;T&gt;</type>
 367
 368                 <methodname>load</methodname>
 369
 370                 <methodparam>
 371                   <type>Collection&lt;UUID&gt;</type>
 372
 373                   <parameter>uuids</parameter>
 374                 </methodparam>
 375
 376                 <methodparam>
 377                   <type>Collection&lt;String&gt;</type>
 378
 379                   <parameter>propertyPaths</parameter>
 380                 </methodparam>
 381               </methodsynopsis>
 382             </entry>
 383
 384             <entry>
 385               <para>Returns a collection of objects of type T matching the
 386               uuids supplied, if they exist, initialized according to the
 387               rules described below.</para>
 388             </entry>
 389           </row>
 390
 391           <row>
 392             <entry>
 393               <methodsynopsis>
 394                 <type>boolean</type>
 395
 396                 <methodname>exists</methodname>
 397
 398                 <methodparam>
 399                   <type>UUID</type>
 400
 401                   <parameter>uuid</parameter>
 402                 </methodparam>
 403               </methodsynopsis>
 404             </entry>
 405
 406             <entry>
 407               <para>Returns true if there is an object of type T in the
 408               database matching the supplied uuid.</para>
 409             </entry>
 410           </row>
 411
 412           <row>
 413             <entry>
 414               <methodsynopsis>
 415                 <type>Class&lt;T&gt;</type>
 416
 417                 <methodname>getType</methodname>
 418               </methodsynopsis>
 419             </entry>
 420
 421             <entry>
 422               <para>Returns the class of objects that this Service provides
 423               access to.</para>
 424             </entry>
 425           </row>
 426         </tbody>
 427       </tgroup>
 428     </table>
 429
 430     <table frame="all" xml:id="iversionableservice-methods">
 431       <title><interfacename>IVersionableService</interfacename>
 432       methods</title>
 433
 434       <tgroup align="left" cols="2" colsep="1" rowsep="1">
 435         <colspec colname="c1" />
 436
 437         <colspec colname="c2" />
 438
 439         <thead>
 440           <row>
 441             <entry>Method</entry>
 442
 443             <entry>Description</entry>
 444           </row>
 445         </thead>
 446
 447         <tbody>
 448           <row>
 449             <entry>
 450               <methodsynopsis>
 451                 <type>Pager&lt;AuditEventRecord&lt;T&gt;&gt;</type>
 452
 453                 <methodname>pageAuditEvents</methodname>
 454
 455                 <methodparam>
 456                   <type>T</type>
 457
 458                   <parameter>versionablentity</parameter>
 459                 </methodparam>
 460
 461                 <methodparam>
 462                   <type>Integer</type>
 463
 464                   <parameter>pageSize</parameter>
 465                 </methodparam>
 466
 467                 <methodparam>
 468                   <type>Integer</type>
 469
 470                   <parameter>pageNumber</parameter>
 471                 </methodparam>
 472
 473                 <methodparam>
 474                   <type>AuditEventSort</type>
 475
 476                   <parameter>sort</parameter>
 477                 </methodparam>
 478               </methodsynopsis>
 479             </entry>
 480
 481             <entry>
 482               <para>Makes a new object persistent, or persists the state of a
 483               transient object.</para>
 484             </entry>
 485           </row>
 486
 487           <row>
 488             <entry>
 489               <methodsynopsis>
 490                 <type>AuditEvent</type>
 491
 492                 <methodname>getNextAuditEvent</methodname>
 493
 494                 <methodparam>
 495                   <type>T</type>
 496
 497                   <parameter>t</parameter>
 498                 </methodparam>
 499               </methodsynopsis>
 500             </entry>
 501
 502             <entry>
 503               <para>Makes a collection of new objects persistent.</para>
 504             </entry>
 505           </row>
 506
 507           <row>
 508             <entry>
 509               <methodsynopsis>
 510                 <type>AuditEvent</type>
 511
 512                 <methodname>getPreviousAuditEvent</methodname>
 513
 514                 <methodparam>
 515                   <type>T</type>
 516
 517                   <parameter>t</parameter>
 518                 </methodparam>
 519               </methodsynopsis>
 520             </entry>
 521
 522             <entry>
 523               <para>Makes a new object persistent.</para>
 524             </entry>
 525           </row>
 526
 527           <row>
 528             <entry>
 529               <methodsynopsis>
 530                 <type>boolean</type>
 531
 532                 <methodname>existed</methodname>
 533
 534                 <methodparam>
 535                   <type>UUID</type>
 536
 537                   <parameter>uuid</parameter>
 538                 </methodparam>
 539               </methodsynopsis>
 540             </entry>
 541
 542             <entry>
 543               <para>Makes a new object persistent.</para>
 544             </entry>
 545           </row>
 546         </tbody>
 547       </tgroup>
 548     </table>
 549
 550     <section>
 551       <info>
 552         <title>Paging Resultsets</title>
 553       </info>
 554
 555       <para>In addition to being able to return results as a
 556       <interfacename>java.util.List</interfacename>, service layer methods can
 557       return results as a <interfacename>Pager</interfacename>. Pagers contain
 558       a sublist of the total result set, plus a count of the total number of
 559       matching objects. In addition, they contain a number of convenience
 560       methods to facilitate the rendering of paged resultsets, including the
 561       generation of labels for pages, based upon the matching objects.</para>
 562     </section>
 563   </section>
 564 </chapter>