-
Notifications
You must be signed in to change notification settings - Fork 8
/
service.jakartars.html
8914 lines (8719 loc) · 949 KB
/
service.jakartars.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>151 Whiteboard Specification for Jakarta™ RESTful Web Services - OSGi Compendium 8</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.78.1" />
<link rel="home" href="index.html" title="OSGi Compendium" />
<link rel="up" href="index.html" title="OSGi Compendium" />
<link rel="prev" href="service.configurator.html" title="150 Configurator Specification" />
<link rel="next" href="service.cdi.html" title="152 CDI Integration Specification" />
<meta name="Section-title" content="151 Whiteboard Specification for Jakarta™ RESTful Web Services" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<link rel="shortcut icon" href="images/favicon.png" type="image/x-icon" />
<link rel="stylesheet" type="text/css" href="css/custom.css" />
<link rel="stylesheet" type="text/css" href="css/github.css" />
<link rel="stylesheet" type="text/css" href="//fonts.googleapis.com/css?family=Ubuntu:regular,bold&subset=Latin" /><script type="text/javascript" src="js/highlight.pack.js"></script><script type="text/javascript" src="js/main.js"></script></head>
<body>
<div id="fullbody">
<div id="header">
<div class="menu-top-container"></div>
<div id="shadow-block"><a class="logo" href="index.html"><img src="images/OSGi.svg" alt="OSGi Working Group Documentation" /><h1>OSGi Compendium Release 8</h1></a></div>
</div>
<div id="mobile-menu-icon">⋮</div>
<div id="column-two">
<div id="content">
<div id="scrollable">
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<td width="20%" align="left"><a accesskey="p" href="service.configurator.html">Prev</a>
</td>
<th width="60%" align="center"> </th>
<td width="20%" align="right"> <a accesskey="n" href="service.cdi.html">Next</a></td>
</tr>
</table>
<hr />
</div>
<div class="chapter">
<div xmlns="" class="titlepage">
<div>
<div>
<h1 xmlns="http://www.w3.org/1999/xhtml" class="title"><a xmlns="" class="anchor" id="service.jakartars"></a><span xmlns="" class="number">151</span> Whiteboard Specification for Jakarta™ RESTful Web Services
</h1>
</div>
<div>
<p xmlns="http://www.w3.org/1999/xhtml" class="releaseinfo"><a xmlns="" class="xref" href="service.jakartars.html#org.osgi.service.jakartars.whiteboard" title="151.15 org.osgi.service.jakartars.whiteboard">Version 2.0</a></p>
</div>
</div>
</div>
<div class="section">
<div xmlns="" class="titlepage">
<div>
<div>
<h2 xmlns="http://www.w3.org/1999/xhtml" class="title" style="clear: both"><a xmlns="" class="anchor" id="d0e131548"></a><span xmlns="" class="number">151.1</span> Introduction
</h2>
</div>
</div>
</div>
<p>REpresentational State Transfer (REST) is a simple pattern for
producing Web Services. RESTful services use URI pattern matching to match
a particular web resource. Different HTTP verbs, for example
<code class="code">GET</code> and <code class="code">DELETE</code>, map to different operations on
that resource. Standard HTTP response codes are used to communicate the
result of an operation, potentially including a response body if the
operation returns a result.
</p>
<p>The <a xmlns="" class="xref" href="service.jakartars.html#service.jakartars-i21217577" title="Jakarta RESTful Web Services 3.0 Specification">[1] <em>Jakarta RESTful Web Services 3.0 Specification</em></a> defines a set of
annotation mappings which allow Plain Old Java Objects (POJOs) to be
directly exposed as RESTful web resources; these resources can also be
grouped together using a Jakarta RESTful Web Services
<code class="code">Application</code>. Furthermore the specification defines a plugable
model for extending the behavior of the application and the features of
the Jakarta RESTful Web Services container itself. For example an
extension may define specific error responses that should be sent when
particular exceptions occur, or an extension may add support for
serializing responses to a different format. The OSGi Whiteboard
Specification for Jakarta RESTful Web Services provides a light and
convenient way of using these POJOs, applications and extensions in an
OSGi environment through the use of the <a xmlns="" class="xref" href="service.jakartars.html#service.jakartars-whiteboard.pattern.ref" title="Whiteboard Pattern">[3] <em>Whiteboard Pattern</em></a>.
</p>
<p>The Whiteboard Specification for Jakarta RESTful Web Services
supports:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<p><span class="emphasis"><em>Registering Resources</em></span> - Registering a
Jakarta RESTful Web Services annotated POJO in the Service Registry
makes it available to be bound to an endpoint and to start responding
to incoming requests.
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>Registering Applications</em></span> - Registering a
Jakarta RESTful Web Services <code class="code">Application</code> in the Service
Registry makes it available to be bound to an endpoint and to start
responding to incoming requests.
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>Registering Extensions</em></span> - The Jakarta
RESTful Web Services specification defines a variety of plugable
extensions. These extensions can be registered in the Service Registry
to include them in the handling pipeline.
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>Requiring Extensions</em></span> - Sometimes Jakarta
RESTful Web Services resources, or even Jakarta RESTful Web Services
extensions, depend upon the presence of another extension. For example
a Jakarta RESTful Web Services resource and exception mapper may both
depend on a JSON serializer. Jakarta RESTful Web Services Whiteboard
services may define preconditions that must be satisfied before they
can be bound.
</p>
</li>
</ul>
</div>
<p>Jakarta RESTful Web Services Whiteboard implementations must support
at least version 3.0 of the Jakarta RESTful Web Services API.
</p>
<div class="section">
<div xmlns="" class="titlepage">
<div>
<div>
<h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a xmlns="" class="anchor" id="d0e131596"></a><span xmlns="" class="number">151.1.1</span> Entities
</h3>
</div>
</div>
</div>
<p>This specification defines the following entities:</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<p><span class="emphasis"><em>Jakarta RESTful Web Services Whiteboard
service</em></span> - An object registered in the Service Registry
providing the necessary Whiteboard service properties defined by
this specification. Whiteboard services may be
<span class="emphasis"><em>resource</em></span>, <span class="emphasis"><em>application</em></span> or
<span class="emphasis"><em>extension</em></span> services
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>Jakarta RESTful Web Services Whiteboard
implementation</em></span> - An implementation that provides one or
more Jakarta RESTful Web Services Whiteboards.
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>Jakarta RESTful Web Services Whiteboard</em></span> -
A runtime instance that processes Jakarta RESTful Web Services
Whiteboard services. Each Jakarta RESTful Web Services Whiteboard
service may be processed by multiple Jakarta RESTful Web Services
Whiteboards. Different Jakarta RESTful Web Services Whiteboards
provided by the same Jakarta RESTful Web Services Whiteboard
implementation may configured differently, for example using
different ports or root contexts.
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>Jakarta RESTful Web Services Service Runtime
service</em></span> - A service providing runtime introspection into
a Jakarta RESTful Web Services Whiteboard instance.
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>Jakarta RESTful Web Services Resource
Service</em></span> - A service that provides one or more RESTful
resource methods which map to incoming HTTP requests.
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>Jakarta RESTful Web Services Application
Service</em></span> - A service that provides a
<code class="code">jakarta.ws.rs.core.Application</code> to be hosted by a
Jakarta RESTful Web Services Whiteboard.
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>Jakarta RESTful Web Services Extension
Service</em></span> - A service that extends the functionality of a
Jakarta RESTful Web Services Whiteboard.
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>Static Resources</em></span> - Jakarta RESTful Web
Services resources that are included programmatically in a Jakarta
RESTful Web Services Whiteboard application, rather than being added
at runtime by the whiteboard.
</p>
</li>
</ul>
</div>
<div class="figure"><a xmlns="" class="anchor" id="service.jakartars.whiteboard-overview"></a><p class="title"><strong>Figure <span xmlns="" class="number">151</span>.1 Jakarta RESTful Web Services Whiteboard Overview
Diagram</strong></p>
<div class="figure-contents">
<div class="mediaobject" align="center"><img src="images/151-overall.png" align="middle" width="495" height="298" alt="Jakarta RESTful Web Services Whiteboard Overview Diagram" /></div>
</div>
</div><br class="figure-break" /><p>The <a xmlns="" class="xref" href="service.jakartars.html#service.jakartars.whiteboard-overview" title="Figure 151.1 Jakarta RESTful Web Services Whiteboard Overview Diagram">Figure <span class="number">151</span>.1</a> shows
an OSGi framework running a Jakarta RESTful Web Services Whiteboard
Implementation bundle. This bundle has been configured to provide two
Jakarta RESTful Web Services whiteboards, each of which has a
corresponding Jakarta RESTful Web Services Service Runtime Service. The
various Jakarta RESTful Web Services Whiteboard services available in
the framework are discovered and processed by both whiteboards.
</p>
</div>
</div>
<div class="section">
<div xmlns="" class="titlepage">
<div>
<div>
<h2 xmlns="http://www.w3.org/1999/xhtml" class="title" style="clear: both"><a xmlns="" class="anchor" id="service.jakartars.whiteboard"></a><span xmlns="" class="number">151.2</span> The Jakarta RESTful Web Services Whiteboard
</h2>
</div>
</div>
</div>
<p>An important principle of the Whiteboard Specification for Jakarta
RESTful Web Services is that an OSGi framework may contain many active
Jakarta RESTful Web Services Whiteboards at any time, even if there is
only a single Jakarta RESTful Web Services Whiteboard implementation
present in the framework. In addition to providing a web endpoint with
which to register Whiteboard services, a Jakarta RESTful Web Services
Whiteboard provides a holder for Jakarta RESTful Web Services
Applications.
</p>
<p>All Jakarta RESTful Web Services Whiteboards have a
<code class="code">default</code> application which is used to register resources that
do not target an existing application. In this respect a Jakarta RESTful
Web Services whiteboard application shares some similarities with a
Servlet Context in the <a xmlns="" class="xref" href="service.servlet.html" title="140 Whiteboard Specification for Jakarta™ Servlet"><em xmlns="http://www.w3.org/1999/xhtml">Jakarta Servlet Whiteboard</em></a>. Resources
registered with a Jakarta RESTful Web Services Whiteboard are always
registered as part of an application. The generated name of the default
application is <code class="code">.default</code>, and it is mapped to the root context
of the Jakarta RESTful Web Services Whiteboard.
</p>
<p>A Jakarta RESTful Web Services Whiteboard implementation must create
a Jakarta RESTful Web Services Whiteboard instance, however it is expected
that most implementations will permit multiple Jakarta RESTful Web
Services whiteboards to be configured. These instances may differ
significantly, or may simply offer the same capabilities on a different
port.
</p>
<p>For details on the association process between Jakarta RESTful Web
Services Whiteboard services and a Jakarta RESTful Web Services Whiteboard
see <a xmlns="" class="xref" href="service.servlet.html#service.http.whiteboard.common.properties" title="140.3 Common Whiteboard Properties">Common Whiteboard Properties</a>.
</p>
<div class="section">
<div xmlns="" class="titlepage">
<div>
<div>
<h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a xmlns="" class="anchor" id="d0e131685"></a><span xmlns="" class="number">151.2.1</span> The Jakarta RESTful Web Services Service Runtime Service
</h3>
</div>
</div>
</div>
<p>The <a xmlns="" class="xref" href="service.jakartars.html#org.osgi.service.jakartars.runtime.JakartarsServiceRuntime" title="151.13.2 public interface JakartarsServiceRuntime">JakartarsServiceRuntime</a> service represents the runtime state information
of a Jakarta RESTful Web Services Whiteboard instance. This information
is provided through Data Transfer Objects (DTOs). The architecture of
OSGi DTOs is described in <a xmlns="" class="xref" href="introduction.html#intro.core.release" title="1.2.1 OSGi Core Release 8">OSGi Core Release 8</a>.
</p>
<p>Each Jakarta RESTful Web Services Whiteboard implementation
registers exactly one <code class="code">JakartarsServiceRuntime</code> service per
Jakarta RESTful Web Services Whiteboard. The service properties of the
Jakarta RESTful Web Services Service Runtime Service can be used to
target Jakarta RESTful Web Services Whiteboard services at specific
Jakarta RESTful Web Services whiteboards, as described by the
<code class="code">osgi.jakartars.whiteboard.target</code> property in <a xmlns="" class="xref" href="service.jakartars.html#service.jakartars.common.properties" title="151.3 Common Whiteboard Properties">Common Whiteboard Properties</a>.
</p>
<p>The <code class="code">JakartarsServiceRuntime</code> provides service
registration properties to declare its underlying Jakarta RESTful Web
Services Whiteboard. These service properties can include
implementation-specific key-value pairs. They also include the
following:
</p>
<div class="table"><a xmlns="" class="anchor" id="d0e131709"></a><p class="title"><strong>Table <span xmlns="" class="number">151</span>.1 Service properties for the <code class="code">JakartarsServiceRuntime</code>
service</strong></p>
<div class="table-contents">
<table summary="Service properties for the JakartarsServiceRuntime
 service" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col />
<col />
<col />
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">Service Property Name</th>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">Type</th>
<th style="border-bottom: 0.5pt solid ; ">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="code">osgi.jakartars.endpoint</code></td>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="code">String+</code></td>
<td style="border-bottom: 0.5pt solid ; ">
<p> Endpoint(s) where this Jakarta RESTful Web
Services Whiteboard is listening. Registered Whiteboard services
are made available here. Values could be provided as URLs e.g.
<code class="code">http://192.168.1.10:8080/</code> or relative paths, e.g.
<code class="code">/myapp/</code>. Relative paths may be used if the scheme
and authority parts of the URLs are not known, for example if
the Jakarta RESTful Web Services Whiteboard is delegating to a
bridged Http Service implementation. If the Jakarta RESTful Web
Services Whiteboard Service is serving the root context and
scheme and authority are not known, the value of the property is
<code class="code">/</code>. Each entry must end with a
slash.
</p>
<p>See <a xmlns="" class="xref" href="service.jakartars.html#org.osgi.service.jakartars.runtime.JakartarsServiceRuntimeConstants.JAKARTA_RS_SERVICE_ENDPOINT" title="151.13.3.1 public static final String JAKARTA_RS_SERVICE_ENDPOINT = "osgi.jakartars.endpoint"">JAKARTA_RS_SERVICE_ENDPOINT</a>.
</p>
</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; "><code class="code">service.changecount</code></td>
<td style="border-right: 0.5pt solid ; "><code class="code">Long</code></td>
<td style="">
<p>Whenever the DTOs available from the Jakarta
RESTful Web Services Service Runtime service change, the value
of this property will increase.
</p>
<p>This allows
interested parties to be notified of changes to the DTOs by
observing Service Events of type <code class="code">MODIFIED</code> for the
<a xmlns="" class="xref" href="service.jakartars.html#org.osgi.service.jakartars.runtime.JakartarsServiceRuntime" title="151.13.2 public interface JakartarsServiceRuntime">JakartarsServiceRuntime</a> service. See
<code class="code">org.osgi.framework.Constants.SERVICE_CHANGECOUNT</code> in
<a xmlns="" class="xref" href="introduction.html#intro.core.release" title="1.2.1 OSGi Core Release 8">OSGi Core Release 8</a>.
</p>
</td>
</tr>
</tbody>
</table>
</div>
</div><br class="table-break" /></div>
<div class="section">
<div xmlns="" class="titlepage">
<div>
<div>
<h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a xmlns="" class="anchor" id="d0e131774"></a><span xmlns="" class="number">151.2.2</span> Inspecting the Runtime DTOs
</h3>
</div>
</div>
</div>
<p>The Jakarta RESTful Web Services Service Runtime service provides
information about registered Whiteboard services through the <a xmlns="" class="xref" href="service.jakartars.html#org.osgi.service.jakartars.runtime.dto.RuntimeDTO" title="151.14.13 public class RuntimeDTO extends DTO">RuntimeDTO</a>.
</p>
<p>The Runtime DTO provides information about services that have been
successfully registered as well as information about the Jakarta RESTful
Web Services Whiteboard services that were not successfully registered.
Jakarta RESTful Web Services Whiteboard services that have the required
properties set but cannot be processed, are reflected in the failure
DTOs. Jakarta RESTful Web Services Whiteboard services of interfaces
described in this specification that do not have the required properties
set are ignored and not reflected in the failure DTOs.
</p>
<p>The Runtime DTO can be obtained using the <a xmlns="" class="xref" href="service.jakartars.html#org.osgi.service.jakartars.runtime.JakartarsServiceRuntime.getRuntimeDTO--" title="151.13.2.1 public RuntimeDTO getRuntimeDTO()">getRuntimeDTO()</a> method. The Runtime DTO returned provides a
snapshot of the state of the Jakarta RESTful Web Services Runtime,
including the Jakarta RESTful Web Services Whiteboard resources,
extensions and applications that are active in each registered
application. The Runtime DTO also includes information about Whiteboard
services which could not be activated.
</p>
<div class="section">
<div xmlns="" class="titlepage">
<div>
<div>
<h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a xmlns="" class="anchor" id="d0e131787"></a><span xmlns="" class="number">151.2.2.1</span> DTO properties
</h4>
</div>
</div>
</div>
<p>When whiteboard services are registered with the whiteboard they
must be introspected and this information reflected in the DTO(s) for
that service. This introspection will include looking for annotations
such as <code class="code">@GET</code> and <code class="code">@Path</code> both at a class and
method level. The values associated with these annotations must then
be appropriately combined, for example when <code class="code">@Path</code> is
declared on a type and method level, and recorded in the DTO.
</p>
</div>
<div class="section">
<div xmlns="" class="titlepage">
<div>
<div>
<h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a xmlns="" class="anchor" id="d0e131801"></a><span xmlns="" class="number">151.2.2.2</span> Failure DTOs
</h4>
</div>
</div>
</div>
<p>There are a variety of reasons that whiteboard services may not
be able to be used by the whiteboard. For example, if the whiteboard
service cannot be retrieved from the service registry, or if the
whiteboard service provides an invalid service property value, such as
a malformed filter.
</p>
<p>In these cases the failed services are represented in the
Runtime DTO under one of the failed DTO properties. Depending upon the
failure reason one or more of the properties of the failed DTO may be
unavailable. For example if the service cannot be retrieved from the
service registry then it cannot be introspected for annotations. A
failure DTO will always contain the service id for the failed service
and the failure reason. The whiteboard implementation must then fill
in other DTO properties on a best effort basis.
</p>
</div>
</div>
<div class="section">
<div xmlns="" class="titlepage">
<div>
<div>
<h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a xmlns="" class="anchor" id="d0e131808"></a><span xmlns="" class="number">151.2.3</span> Relation to the Servlet Container
</h3>
</div>
</div>
</div>
<p>Implementations of this specification will often be backed by
existing servlet containers, such as the OSGi Http Whiteboard, or a
Jakarta EE application server. There may also exist implementations
which bridge into a servlet container into which the OSGi Framework has
been deployed as a Web Application.
</p>
<p>In bridged situations the Jakarta RESTful Web Services Whiteboard
implementation will have limited facilities for creating new Jakarta
RESTful Web Services whiteboards, and may also have limited information
about its environment.
</p>
<p>Information about the surrounding Servlet Container, including
ServletContext information and HttpSession data, is available to Jakarta
RESTful Web Services Whiteboard resources using standard Jakarta RESTful
Web Services injection behavior.
</p><pre xmlns="" class="programlisting"><code>@GET
@Path("{name}")
public String interrogateSession(@PathParam("name") String name,
@Context HttpServletRequest req) {
HttpSession s = req.getSession();
return String.valueOf(s.getAttribute(name));
}</code></pre><p>A Jakarta RESTful Web Services Whiteboard implementation needs to
ensure that Http Sessions are not shared amongst different Jakarta
RESTful Web Services Whiteboards, or amongst different Jakarta RESTful
Web Services Whiteboard applications. That is,
<code class="code">HttpServletRequest.getSession()</code> calls must provide
different sessions for each whiteboard application with which a Jakarta
RESTful Web Services whiteboard service is associated.
</p>
</div>
<div class="section">
<div xmlns="" class="titlepage">
<div>
<div>
<h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a xmlns="" class="anchor" id="d0e131824"></a><span xmlns="" class="number">151.2.4</span> Isolation between Jakarta RESTful Web Services
Whiteboards
</h3>
</div>
</div>
</div>
<p>Even when they are created by the same Jakarta RESTful Web
Services Whiteboard implementation, each Jakarta RESTful Web Services
Whiteboard instance is separate, and isolated from other instances.
Importantly, Jakarta RESTful Web Services Whiteboard services targeted
to one Jakarta RESTful Web Services Whiteboard application must not be
visible in any other Whiteboard or applications to which they are not
targeted.
</p>
<p>This isolation restriction is critical, as it ensures that
different Jakarta RESTful Web Services Whiteboard applications can be
configured with different, potentially overlapping, incompatible
extension features.
</p>
</div>
</div>
<div class="section">
<div xmlns="" class="titlepage">
<div>
<div>
<h2 xmlns="http://www.w3.org/1999/xhtml" class="title" style="clear: both"><a xmlns="" class="anchor" id="service.jakartars.common.properties"></a><span xmlns="" class="number">151.3</span> Common Whiteboard Properties
</h2>
</div>
</div>
</div>
<p>Jakarta RESTful Web Services Whiteboard services support common
service registration properties to associate them with a Jakarta RESTful
Web Services Whiteboard. These properties apply to whiteboard resources,
extensions and applications except where explicitly stated otherwise. Each
service property has an associated Component Property Type annotation that
can be used to easily apply the property to a Declarative Services
Component.
</p>
<div class="table"><a xmlns="" class="anchor" id="service.jakartars.common.properties.table"></a><p class="title"><strong>Table <span xmlns="" class="number">151</span>.2 Common properties</strong></p>
<div class="table-contents">
<table summary="Common properties" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col />
<col />
<col />
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">Service Property</th>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">Type</th>
<th style="border-bottom: 0.5pt solid ; ">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">
<p><code class="code">osgi.jakartars.name</code></p>
<p><a xmlns="" class="xref" href="service.jakartars.html#org.osgi.service.jakartars.whiteboard.propertytypes.JakartarsName" title="151.17.7 @JakartarsName">JakartarsName</a></p>
</td>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">
<p><code class="code">String</code></p>
<p><span class="emphasis"><em>optional</em></span></p>
</td>
<td style="border-bottom: 0.5pt solid ; ">
<p>A user defined name that can be used to identify a
Jakarta RESTful Web Services whiteboard service. Names must follow
OSGi symbolic name rules, and also must not start with the
prefixes <code class="code">'.'</code> or <code class="code">'osgi.'</code>.
</p>
<p>If
no name is defined for a Jakarta RESTful Web Services whiteboard
service then one is generated for it. This generated name will
start with a <code class="code">'.'</code>. The prefix <code class="code">osgi.</code> is
currently unused, but reserved for future versions of this
specification.
</p>
<p>If a Jakarta RESTful Web Services
service is registered with an illegal name then it is not bound
and this is reflected in the failure DTOs. If two Jakarta RESTful
Web Services services are registered with the same name (even if
they are advertised as different types) then only the first
service in ranking order, as specified in
<code class="code">ServiceReference.compareTo</code>, is bound and the lower
ranked service(s) are reflected in the failure DTOs. See <a xmlns="" class="xref" href="service.jakartars.html#org.osgi.service.jakartars.whiteboard.JakartarsWhiteboardConstants.JAKARTA_RS_NAME" title="151.15.2.8 public static final String JAKARTA_RS_NAME = "osgi.jakartars.name"">JAKARTA_RS_NAME</a>.
</p>
</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">
<p><code class="code">osgi.jakartars.application.select</code><span class="strong"><strong><sup>†</sup></strong></span></p>
<p><a xmlns="" class="xref" href="service.jakartars.html#org.osgi.service.jakartars.whiteboard.propertytypes.JakartarsApplicationSelect" title="151.17.3 @JakartarsApplicationSelect">JakartarsApplicationSelect</a></p>
</td>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">
<p><code class="code">String+</code></p>
<p><span class="emphasis"><em>optional</em></span></p>
</td>
<td style="border-bottom: 0.5pt solid ; ">
<p>One or more LDAP-style filters to select the Jakarta
RESTful Web Services Application(s) with which this Whiteboard
service should be associated. Any service property of the
Application can be filtered on. If these filters are not defined
then the default Application is used. If multiple filters are
defined then each filter is used to select target applications.
Target applications are selected at most once, even if they match
more than one filter. The default application can also be
specifically targeted using the application name
<code class="code">.default</code>.
</p>
<p>For example, to select an
Application with name <code class="code">myApp</code> provide the following
filter:
</p><pre xmlns="" class="programlisting"><code>(osgi.jakartars.name=myApp)</code></pre><p>To
select all Applications in the whiteboard provide the following
value:
</p><pre xmlns="" class="programlisting"><code>(osgi.jakartars.name=*)</code></pre><p>If
no matching application exists this is reflected in the failure
DTOs. See <a xmlns="" class="xref" href="service.jakartars.html#org.osgi.service.jakartars.whiteboard.JakartarsWhiteboardConstants.JAKARTA_RS_APPLICATION_SELECT" title="151.15.2.2 public static final String JAKARTA_RS_APPLICATION_SELECT = "osgi.jakartars.application.select"">JAKARTA_RS_APPLICATION_SELECT</a>.
</p>
<p>† Note that this property is
not valid for Jakarta RESTful Web Services Application
services.
</p>
</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">
<p><code class="code">osgi.jakartars.extension.select</code></p>
<p><a xmlns="" class="xref" href="service.jakartars.html#org.osgi.service.jakartars.whiteboard.propertytypes.JakartarsExtensionSelect" title="151.17.5 @JakartarsExtensionSelect">JakartarsExtensionSelect</a>
</p>
</td>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">
<p><code class="code">String+</code></p>
<p><span class="emphasis"><em>optional</em></span></p>
</td>
<td style="border-bottom: 0.5pt solid ; ">
<p>A set of LDAP-style filters used to express
dependencies on one or more extension services. If a filter is
provided then the Jakarta RESTful Web Services Whiteboard attempts
to match that filter against the service properties of the
Whiteboard runtime, the service properties of the whiteboard
application, and each of the extension services currently active
in the application. This search may occur in any order. If all of
the supplied filters are matched then the whiteboard service is
registered into the Jakarta RESTful Web Services Whiteboard
application.
</p>
<p>For example, to require an extension
which provides JSON serialization advertising property name
<code class="code">serialize.to</code> with value <code class="code">JSON</code> provide the
following filter:
</p> <pre xmlns="" class="programlisting"><code>(serialize.to=JSON)</code></pre>
<p>A more detailed version of this example is available in
<a xmlns="" class="xref" href="service.jakartars.html#service.jakartars.extension.example" title="151.5.7 A Jakarta RESTful Web Services Whiteboard Extension Example">A Jakarta RESTful Web Services Whiteboard Extension
Example</a></p>
<p>If any filter(s) fail to match then this is reflected in the
failure DTOs. See <a xmlns="" class="xref" href="service.jakartars.html#org.osgi.service.jakartars.whiteboard.JakartarsWhiteboardConstants.JAKARTA_RS_EXTENSION_SELECT" title="151.15.2.6 public static final String JAKARTA_RS_EXTENSION_SELECT = "osgi.jakartars.extension.select"">JAKARTA_RS_EXTENSION_SELECT</a>.
</p>
</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; ">
<p> <code class="code">osgi.jakartars.whiteboard.target</code>
</p>
<p><a xmlns="" class="xref" href="service.jakartars.html#org.osgi.service.jakartars.whiteboard.propertytypes.JakartarsWhiteboardTarget" title="151.17.9 @JakartarsWhiteboardTarget">JakartarsWhiteboardTarget</a>
</p>
</td>
<td style="border-right: 0.5pt solid ; ">
<p><code class="code">String</code></p>
<p><span class="emphasis"><em>optional</em></span></p>
</td>
<td style="">
<p>The value of this service property is an LDAP-style
filter expression to select the Jakarta RESTful Web Services
Whiteboard(s) to handle this Whiteboard service. The LDAP filter
is used to match <a xmlns="" class="xref" href="service.jakartars.html#org.osgi.service.jakartars.runtime.JakartarsServiceRuntime" title="151.13.2 public interface JakartarsServiceRuntime">JakartarsServiceRuntime</a> services. Each Jakarta RESTful Web
Services Whiteboard exposes exactly one
<code class="code">JakartarsServiceRuntime</code> service. This property is
used to associate the Whiteboard service with the Jakarta RESTful
Web Services Whiteboard that registered the
<code class="code">JakartarsServiceRuntime</code> service. If this property is
not specified then the service will target all Jakarta RESTful Web
Services Whiteboards. See <a xmlns="" class="xref" href="service.jakartars.html#org.osgi.service.jakartars.whiteboard.JakartarsWhiteboardConstants.JAKARTA_RS_WHITEBOARD_TARGET" title="151.15.2.12 public static final String JAKARTA_RS_WHITEBOARD_TARGET = "osgi.jakartars.whiteboard.target"">JAKARTA_RS_WHITEBOARD_TARGET</a>.
</p>
</td>
</tr>
</tbody>
</table>
</div>
</div><br class="table-break" /></div>
<div class="section">
<div xmlns="" class="titlepage">
<div>
<div>
<h2 xmlns="http://www.w3.org/1999/xhtml" class="title" style="clear: both"><a xmlns="" class="anchor" id="service.jakartars.resource.services"></a><span xmlns="" class="number">151.4</span> Registering RESTful Resources
</h2>
</div>
</div>
</div>
<p>Jakarta RESTful Web Services resources can be registered with the
Jakarta RESTful Web Services Whiteboard by registering them as Whiteboard
services. This means that the resource POJO implementations are registered
in the Service Registry. As Jakarta RESTful Web Services resources are
POJOs they may be registered using <span class="emphasis"><em>any</em></span> valid service
interface, including <code class="code">Object</code>. The Jakarta RESTful Web Services
container will then use reflection to discover methods and annotations on
the resource object, just as it would outside of OSGi.
</p>
<p>As Jakarta RESTful Web Services resources have no common interface
type they are instead registered with the
<code class="code">osgi.jakartars.resource</code> service property with a value of
<code class="code">"true"</code>. This property serves as a marker to the Jakarta
RESTful Web Services whiteboard runtime, indicating that this OSGi service
should be hosted as a Jakarta RESTful Web Services Whiteboard
resource.
</p>
<div class="section">
<div xmlns="" class="titlepage">
<div>
<div>
<h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a xmlns="" class="anchor" id="d0e132022"></a><span xmlns="" class="number">151.4.1</span> Jakarta RESTful Web Services Resource mapping
</h3>
</div>
</div>
</div>
<p>Jakarta RESTful Web Services resources use the <code class="code">Path</code>
annotation to bind themselves to particular URIs within the Jakarta
RESTful Web Services container. The path annotation can be applied to
the resource class, and to individual resource methods. For example the
following Jakarta RESTful Web Services resource:
</p><pre xmlns="" class="programlisting"><code>@Path("foo")
public class Foo {
private final List<String> entries =
Arrays.asList("fizz", "buzz", "fizzbuzz");
@GET
public List<String> getFoos() {
return Collections.unmodifiableList(entries);
}
@GET
@Path("{name}")
public String getFoo(@PathParam("name") String name) {
if(entries.contains(name)) {
return "A foo called " + name;
}
throw new IllegalArgumentException(“No foo called “ + name);
}
}</code></pre><p>This Jakarta RESTful Web Services resource defines two resource
methods. The <code class="code">Path</code> annotation applied to the class sets the
base URI for all methods in the resource. The <code class="code">getFoos()</code>
method is therefore bound to the URI <code class="code">foo</code>. The
<code class="code">Path</code> annotation on the <code class="code">getFoo()</code> method makes
this method a sub-resource which captures the next token in the URI.
This method is therefore bound to URIs of the form
<code class="code">foo/buzz</code>.
</p>
<p>When used as an OSGi Jakarta RESTful Web Services Whiteboard
service a Jakarta RESTful Web Services resource follows the same mapping
rules, but the base context(s) it uses are determined by the
Application(s) to which it is mapped. For example, when mapped to the
default application of a whiteboard with endpoint
<code class="code">http://127.0.0.1/</code> the <code class="code">getFoos()</code> method would
be available at <code class="code">http://127.0.0.1/foo</code>.
</p>
<div class="section">
<div xmlns="" class="titlepage">
<div>
<div>
<h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a xmlns="" class="anchor" id="service.jakartars.resource.services.clashes"></a><span xmlns="" class="number">151.4.1.1</span> Clashing resource mappings
</h4>
</div>
</div>
</div>
<p>Resource services bound to a Jakarta RESTful Web Services
whiteboard application share a single URI namespace with other
resources in the application (including any existing static
resources). When Jakarta RESTful Web Services services are bound it is
possible that one or more methods on these services will map to the
same URI. This situation is permitted by the Jakarta RESTful Web
Services specification which defines a detailed selection
algorithm.
</p>
<p>When clashes occur in the Jakarta RESTful Web Services
whiteboard then resources supplied using the service whiteboard must
be preferred to static resources contained in the application. If two
or more whiteboard resources exist then they must be ordered using
ranking order, as specified in
<code class="code">ServiceReference.compareTo</code>. Unlike for other services in
the Jakarta RESTful Web Services whiteboard, whiteboard resource
services must not be ordered using their natural ordering. Whiteboard
resource services with the same ranking must be considered equal,
following the normal resource method selection rules defined in the
Jakarta RESTful Web Services specification. As per the Core
specification, whiteboard services with no
<code class="code">service.ranking</code> property must be treated as having a
ranking of <code class="code">0</code>.
</p>
</div>
</div>
<div class="section">
<div xmlns="" class="titlepage">
<div>
<div>
<h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a xmlns="" class="anchor" id="d0e132079"></a><span xmlns="" class="number">151.4.2</span> Jakarta RESTful Web Services Whiteboard Resource
Lifecycle
</h3>
</div>
</div>
</div>
<p>A key tenet of Jakarta RESTful Web Services is that all resource
objects are stateless. In the Jakarta RESTful Web Services specification
resources therefore have one of two scopes, they are either singleton,
or request-scoped. Singleton resources are created once, potentially
outside the Jakarta RESTful Web Services container, and request-scoped
resources are created on-demand for each request, then discarded
afterwards.
</p>
<p>Typically Jakarta RESTful Web Services developers are encouraged
to write request-scoped resources, as this makes it difficult to
accidentally write stateful components. In OSGi, however, it is more
common to write singleton services. On demand instances of OSGi services
can be created, but only if the service is registered as a
<code class="code">prototype</code> scope.
</p>
<p>The Jakarta RESTful Web Services whiteboard implementation is
responsible for managing the mismatch between the OSGi service lifecycle
model and the Jakarta RESTful Web Services resource lifecycle model. If
the Jakarta RESTful Web Services whiteboard resource is registered as
prototype scope then the implementation must treat the resources as
request-scoped, creating a new service instance for each request and
releasing it when the request completes. Otherwise the Jakarta RESTful
Web Services whiteboard service must be registered as a singleton scope
resource within the application. Singleton scope whiteboard resources
must be released by the Jakarta RESTful Web Services whiteboard when the
application with which they have been registered is removed from the
whiteboard, even if this is only a temporary situation.
</p>
<p>If a failure occurs when getting the resource service this will
prevent the service from being used, which is reflected using a failure
DTO. In such a case the system treats the resource as unusable.
</p>
<p>When multiple Jakarta RESTful Web Services Whiteboard
implementations are present all of them can potentially process the
whiteboard resources. In such situations it can be useful to associate
the servlet with a specific whiteboard by specifying the
<code class="code">osgi.http.whiteboard.target</code> property on the service.
</p>
<div class="section">
<div xmlns="" class="titlepage">
<div>
<div>
<h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a xmlns="" class="anchor" id="d0e132098"></a><span xmlns="" class="number">151.4.2.1</span> Resource Context Injection
</h4>
</div>
</div>
</div>
<p>Jakarta RESTful Web Services resources may have objects injected
into them by the Jakarta RESTful Web Services container. These objects
may be related to an incoming request, for example an HTTP header
value, or part of the container runtime. Injected resources are
annotated with a Jakarta RESTful Web Services annotation, for example
<code class="code">@Context</code>, and may be injected as method parameters, or as
fields in the object.
</p>
<p>If the Jakarta RESTful Web Services injected objects are passed
as method parameters then the resource object may be a singleton. If,
however, the objects are injected into fields by the Jakarta RESTful
Web Services container then the resource should be declared as a
<code class="code">prototype</code> scope. Jakarta RESTful Web Services Whiteboard
implementations may support field injection for singleton resources,
however this behavior is non portable, and may lead to errors at
runtime when using other implementations.
</p>
</div>
<div class="section">
<div xmlns="" class="titlepage">
<div>
<div>
<h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a xmlns="" class="anchor" id="d0e132111"></a><span xmlns="" class="number">151.4.2.2</span> Request-Scoped Resources
</h4>
</div>
</div>
</div>
<p>Request-scoped resources are created on demand for a request and
then discarded afterwards. Critically for OSGi services the Jakarta
RESTful Web Services whiteboard <span class="emphasis"><em>must not</em></span> release
a prototype scope service until <span class="emphasis"><em>after</em></span> the
response has completed. If the resource makes use of a Jakarta RESTful
Web Services <code class="code">AsyncResponse</code>, <code class="code">SseEventSink</code> or
a <code class="code">StreamingOutput</code> then this may be some time after the
return of resource method, and potentially on a different
thread.
</p>
<p>Jakarta RESTful Web Services whiteboard implementations must
therefore take special care not to release request scoped instances
until they are completely finished.
</p>
</div>
<div class="section">
<div xmlns="" class="titlepage">
<div>
<div>
<h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a xmlns="" class="anchor" id="d0e132133"></a><span xmlns="" class="number">151.4.2.3</span> Asynchronous Responses
</h4>
</div>
</div>
</div>
<p>Jakarta RESTful Web Services supports asynchronous responses
either for single-valued results, or for streams of data.
</p>
<p>Single valued results may be provided by the
<code class="code">AsyncResponse</code> type which is injected into resource
methods using the <code class="code">@Suspended</code> annotation. If the resource
is request scoped then the resource must not be released until after
the <code class="code">AsyncResponse</code> has completed.
</p>
<p>The following example demonstrates the use of the
<code class="code">AsyncResponse</code>:
</p><pre xmlns="" class="programlisting"><code>@Component(service = MyResource.class,
scope = ServiceScope.PROTOTYPE)
@JakartarsResource
public class MyResource {
@Path(“foo”)
@GET
public void getFoo(@Suspended AsyncResponse async) {
Promise<String> p = doLongRunningTaskAsynchronously();
p.onSuccess(v -> async.resume(v))
.onFailure(t -> async.resume(t));
}
}</code></pre><p>Single valued asynchronous results can also be provided by
returning a suitable type from the resource method. This can be a
<code class="code">CompletionStage</code> as described in the Jakarta RESTful Web
Services specification, or an OSGi <code class="code">Promise</code> type. In this
case the response from the resource method will be sent once the
returned type has completed, either successfully or by failing.
</p>
<p>The following example demonstrates the use of an asynchronous
return value:
</p><pre xmlns="" class="programlisting"><code>@Component(service = MyResource.class,
scope = ServiceScope.PROTOTYPE)
@JakartarsResource
public class MyResource {
@Path(“foo”)
@GET
public Promise<String> getFoo() {
Promise<String> p = doLongRunningTaskAsynchronously();
return p;
}
}</code></pre><p>Multi-valued results in Jakarta RESTful Web Services are handled
using Server Sent Events. To send Server Sent Events a Jakarta RESTful
Web Services resource must declare its produced media type
appropriately, and inject its resource method with a
<code class="code">SseEventSink</code>. The resource must also gain access to a
<code class="code">Sse</code> to use as a factory for Outbound Server Sent Events.
If the resource is request scoped then the resource must not be
released until after the <code class="code">SseEvent</code> has closed.
</p>
<p>The following example demonstrates the use of the Server Sent
Events:
</p><pre xmlns="" class="programlisting"><code>@Component(service = MyResource.class,
scope = ServiceScope.PROTOTYPE)
@JakartarsResource
public class MyResource {
@Context
Sse sse;
@GET
@Produces(MediaType.SERVER_SENT_EVENTS)
public void getFoo(@Context SseEventSink sink) {
PushStream<String> p = getStreamOfMessages();
p.map(sse::newEvent)
.forEach(e -> sink::send)
.onResolve(sink::close);
}
}</code></pre></div>
</div>
<div class="section">
<div xmlns="" class="titlepage">
<div>
<div>
<h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a xmlns="" class="anchor" id="d0e132183"></a><span xmlns="" class="number">151.4.3</span> Resource Service Properties
</h3>
</div>
</div>
</div>
<p>The following table describes the properties that can be used by
Jakarta RESTful Web Services resources registered as Whiteboard
services. Additionally, the common properties listed in <a xmlns="" class="xref" href="service.jakartars.html#service.jakartars.common.properties.table" title="Table 151.2 Common properties">Table <span class="number">151</span>.2 on page </a> are supported.
</p>
<div class="table"><a xmlns="" class="anchor" id="d0e132190"></a><p class="title"><strong>Table <span xmlns="" class="number">151</span>.3 Service properties for Jakarta RESTful Web Services Whiteboard
resource services.</strong></p>
<div class="table-contents">
<table summary="Service properties for Jakarta RESTful Web Services Whiteboard
 resource services." width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col />
<col />
<col />
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">Service Property</th>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">Type</th>
<th style="border-bottom: 0.5pt solid ; ">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td style="border-right: 0.5pt solid ; ">
<p><code class="code">osgi.jakartars.resource</code></p>
<p><a xmlns="" class="xref" href="service.jakartars.html#org.osgi.service.jakartars.whiteboard.propertytypes.JakartarsResource" title="151.17.8 @JakartarsResource">JakartarsResource</a></p>
</td>
<td style="border-right: 0.5pt solid ; ">
<p><code class="code">String</code> /
<code class="code">Boolean</code></p>
<p><span class="emphasis"><em>required</em></span></p>
</td>
<td style="">
<p>Declares that this service must be processed by the
Jakarta RESTful Web Services whiteboard when set to
<code class="code">true</code>. See <a xmlns="" class="xref" href="service.jakartars.html#org.osgi.service.jakartars.whiteboard.JakartarsWhiteboardConstants.JAKARTA_RS_RESOURCE" title="151.15.2.9 public static final String JAKARTA_RS_RESOURCE = "osgi.jakartars.resource"">JAKARTA_RS_RESOURCE</a>.
</p>
</td>
</tr>
</tbody>
</table>
</div>
</div><br class="table-break" /></div>
<div class="section">
<div xmlns="" class="titlepage">
<div>
<div>
<h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a xmlns="" class="anchor" id="d0e132231"></a><span xmlns="" class="number">151.4.4</span> A Jakarta RESTful Web Services Whiteboard Resource
Example
</h3>
</div>
</div>
</div>
<p>The following example code uses Declarative Services annotations
to register a Jakarta RESTful Web Services Whiteboard service.
</p><pre xmlns="" class="programlisting"><code>@Component(service = MyResource.class,
scope = ServiceScope.PROTOTYPE)