cdmlib/src/docbkx/service.xml @ 31f1e71a
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<UUID,T></type> |
84 |
|
85 |
<methodname>save</methodname> |
86 |
|
87 |
<methodparam>
|
88 |
<type>Collection<T></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<T></type> |
185 |
|
186 |
<methodname>list</methodname> |
187 |
|
188 |
<methodparam>
|
189 |
<type>Class<? extends T></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<OrderHint></type> |
208 |
|
209 |
<parameter>orderHints</parameter> |
210 |
</methodparam>
|
211 |
|
212 |
<methodparam>
|
213 |
<type>List<String></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<T></type> |
231 |
|
232 |
<methodname>page</methodname> |
233 |
|
234 |
<methodparam>
|
235 |
<type>Class<? extends T></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<OrderHint></type> |
254 |
|
255 |
<parameter>orderHints</parameter> |
256 |
</methodparam>
|
257 |
|
258 |
<methodparam>
|
259 |
<type>List<String></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<? extends T></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<T></type> |
319 |
|
320 |
<methodname>find</methodname> |
321 |
|
322 |
<methodparam>
|
323 |
<type>Collection<UUID></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<String></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<T></type> |
367 |
|
368 |
<methodname>load</methodname> |
369 |
|
370 |
<methodparam>
|
371 |
<type>Collection<UUID></type> |
372 |
|
373 |
<parameter>uuids</parameter> |
374 |
</methodparam>
|
375 |
|
376 |
<methodparam>
|
377 |
<type>Collection<String></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<T></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<AuditEventRecord<T>></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>
|