-
Notifications
You must be signed in to change notification settings - Fork 8
/
service.remoteservices.html
5319 lines (5319 loc) · 688 KB
/
service.remoteservices.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>100 Remote 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="introduction.html" title="1 Introduction" />
<link rel="next" href="service.device.html" title="103 Device Access Specification" />
<meta name="Section-title" content="100 Remote 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="introduction.html">Prev</a>
</td>
<th width="60%" align="center"> </th>
<td width="20%" align="right"> <a accesskey="n" href="service.device.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.remoteservices"></a><span xmlns="" class="number">100</span> Remote Services
</h1>
</div>
<div>
<p xmlns="http://www.w3.org/1999/xhtml" class="releaseinfo">Version
1.1
</p>
</div>
</div>
</div>
<p>The OSGi framework provides a <span class="emphasis"><em>local</em></span> service
registry for bundles to communicate through service objects, where a service
is an object that one bundle registers and another bundle gets. A
<span class="emphasis"><em>distribution provider</em></span> can use this loose coupling
between bundles to <span class="emphasis"><em>export</em></span> a registered service by
creating an <span class="emphasis"><em>endpoint</em></span>. Vice versa, the distribution
provider can create a <span class="emphasis"><em>proxy</em></span> that accesses an endpoint
and then registers this proxy as an <span class="emphasis"><em>imported</em></span> service. A
Framework can contain multiple distribution providers simultaneously, each
independently importing and exporting services.
</p>
<p>An endpoint is a communications access mechanisms to a service in
another framework, a (web) service, another process, or a queue or topic
destination, etc., requiring some protocol for communications. The
constellation of the mapping between services and endpoints as well as their
communication characteristics is called the <span class="emphasis"><em>topology</em></span>. A
common case for distribution providers is to be present on multiple
frameworks importing and exporting services; effectively distributing the
service registry.
</p>
<p>The local architecture for remote services is depicted in <a xmlns="" class="xref" href="service.remoteservices.html#i1691895" title="Figure 100.1 Architecture">Figure <span class="number">100</span>.1 on page </a>.
</p>
<div class="figure"><a xmlns="" class="anchor" id="i1691895"></a><p class="title"><strong>Figure <span xmlns="" class="number">100</span>.1 Architecture</strong></p>
<div class="figure-contents">
<div class="mediaobject" align="center"><img src="images/100-architecture.png" align="middle" width="630" height="205" alt="Architecture" /></div>
</div>
</div><br class="figure-break" /><p>Local services imply in-VM call semantics. Many of these semantics
cannot be supported over a communications connection, or require special
configuration of the communications connection. It is therefore necessary to
define a mechanism for bundles to convey their assumptions and requirements
to the distribution provider. This chapter defines a number of service
properties that a distribution provider can use to establish a topology
while adhering to the given constraints.
</p>
<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="d0e860"></a><span xmlns="" class="number">100.1</span> The Fallacies
</h2>
</div>
</div>
</div>
<p>General abstractions for distributed systems have been tried before
and often failed. Well known are the fallacies described in <a xmlns="" class="xref" href="service.remoteservices.html#i1661227" title="The Fallacies of Distributed Computing Explained">[1] <em>The Fallacies of Distributed Computing Explained</em></a>:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<p>The network is reliable</p>
</li>
<li class="listitem">
<p>Latency is zero</p>
</li>
<li class="listitem">
<p>Bandwidth is infinite</p>
</li>
<li class="listitem">
<p>The network is secure</p>
</li>
<li class="listitem">
<p>Topology doesn't change</p>
</li>
<li class="listitem">
<p>There is one administrator</p>
</li>
<li class="listitem">
<p>Transport cost is zero</p>
</li>
<li class="listitem">
<p>The network is homogeneous</p>
</li>
</ul>
</div>
<p>Most fallacies represent non-functional trade-offs that should be
considered by administrators, their decisions can then be reflected in the
topology. For example, in certain cases limited bandwidth is acceptable
and the latency in a datacenter is near zero. However, the reliability
fallacy is the hardest because it intrudes into the application code. If a
communication channel is lost, the application code needs to take specific
actions to recover from this failure.
</p>
<p>This reliability aspect is also addressed with OSGi services because
services are dynamic. Failures in the communications layer can be mapped
to the unregistration of the imported service. OSGi bundles are already
well aware of these dynamics, and a number of programming models have been
developed to minimize the complexity of writing these dynamic
applications.
</p>
</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="i1710847"></a><span xmlns="" class="number">100.2</span> Remote Service Properties
</h2>
</div>
</div>
</div>
<p>This section introduces a number of properties that participating
bundles can use to convey information to the distribution provider
according to this Remote Service specification.
</p>
<p>The following table lists the properties that must be listed by a
distribution provider.
</p>
<div class="table"><a xmlns="" class="anchor" id="d0e903"></a><p class="title"><strong>Table <span xmlns="" class="number">100</span>.1 Remote Service Properties registered by the Distribution
Provider</strong></p>
<div class="table-contents">
<table summary="Remote Service Properties registered by the Distribution
 Provider" 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">remote.configs.supported</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>Registered by the distribution provider on one of its
services to indicate the supported configuration types. See <a xmlns="" class="xref" href="service.remoteservices.html#i1698916" title="100.5 Configuration Types">Configuration Types</a> and <a xmlns="" class="xref" href="service.remoteservices.html#i1708968" title="100.5.2 Dependencies">Dependencies</a>.
</p>
</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="code">remote.intents.supported</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>Registered by the distribution provider on one of its
services to indicate the vocabulary of implemented intents. See
<a xmlns="" class="xref" href="service.remoteservices.html#i1708968" title="100.5.2 Dependencies">Dependencies</a>.
</p>
</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="code">service.imported</code></td>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="code">*</code></td>
<td style="border-bottom: 0.5pt solid ; ">
<p>Must be set by a distribution provider to any value
when it registers the endpoint proxy as an imported service. A
bundle can use this property to filter out imported
services.
</p>
</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="code">service.imported.configs</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>The configuration information used to import this
service, as described in <code class="code">service.exported.configs</code>.
Any associated properties for this configuration types must be
properly mapped to the importing system. For example, a URL in
these properties must point to a valid resource when used in the
importing framework.
</p>
<p>If multiple configuration types
are listed in this property, then they must be synonyms for
exactly the same remote endpoint that is used to export this
service.
</p>
</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; "><code class="code">service.intents</code></td>
<td style="border-right: 0.5pt solid ; "><code class="code">String+</code></td>
<td style="">
<p>A distribution provider must use this property to
convey the combined intents of:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<p>The exporting service, and</p>
</li>
<li class="listitem">
<p>The intents that the exporting distribution provider
adds.
</p>
</li>
<li class="listitem">
<p>The intents that the importing distribution provider
adds.
</p>
</li>
</ul>
</div>
</td>
</tr>
</tbody>
</table>
</div>
</div><br class="table-break" /><p>The properties for bundles providing services to be exported or
require services to be imported are listed alphabetically in the following
table. The scenarios that these properties are used in are discussed in
later sections.
</p>
<div class="table"><a xmlns="" class="anchor" id="d0e992"></a><p class="title"><strong>Table <span xmlns="" class="number">100</span>.2 Remote Service Properties registered by Exporting bundles</strong></p>
<div class="table-contents">
<table summary="Remote Service Properties registered by Exporting bundles" 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">service.exported.configs</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>A list of configuration types that should be used to
export the service. Each configuration type represents the
configuration parameters for one or more Endpoints. A distribution
provider should create endpoints for each configuration type that
it supports. See <a xmlns="" class="xref" href="service.remoteservices.html#i1698916" title="100.5 Configuration Types">Configuration Types</a> for more details. If
this property is not set or empty a distribution provider is free
to choose a default configuration type for the
service.
</p>
</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="code">service.exported.intents</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>A list of <span class="emphasis"><em>intents</em></span> that the
distribution provider must implement to distribute the service.
Intents listed in this property are reserved for intents that are
critical for the code to function correctly, for example, ordering
of messages. These intents should not be configurable. For more
information about intents, see <a xmlns="" class="xref" href="service.remoteservices.html#i1693415" title="100.3 Intents">Intents</a>. This
property is optional.
</p>
</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="code">service.exported.intents.extra</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>This property is merged with the
<code class="code">service.exported.intents</code> property before the
distribution provider interprets the listed intents; it has
therefore the same semantics but the property should be
configurable so the administrator can choose the intents based on
the topology. Bundles should therefore make this property
configurable, for example through the Configuration Admin service.
See <a xmlns="" class="xref" href="service.remoteservices.html#i1693415" title="100.3 Intents">Intents</a>. This property is optional. If
absent or empty no specific intents are required.
</p>
</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="code">service.exported.interfaces</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>Setting this property marks this service for export.
It defines the interfaces under which this service can be
exported. This list must be a subset of the types listed in the
<code class="code">objectClass</code> service property. The single value of an
asterisk (<code class="code">'*' \u002A</code>) indicates all interfaces in the
registration's <code class="code">objectClass</code> property and ignore the
classes. It is strongly recommended to only export interfaces and
not concrete classes due to the complexity of creating proxies for
some type of concrete classes. See <a xmlns="" class="xref" href="service.remoteservices.html#i1709051" title="100.2.1 Registering a Service for Export">Registering a Service for Export</a>.
</p>
</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="code">service.intents</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>A list of intents that this service implements. A
distribution provider must use this property to convey the
combined intents of:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<p>The exporting service, and</p>
</li>
<li class="listitem">
<p>The intents that the exporting distribution provider
adds.
</p>
</li>
<li class="listitem">
<p>The intents that the importing distribution provider
adds.
</p>
</li>
</ul>
</div>
<p>To export a service, a distribution
provider must expand any qualified intents to include those
supported by the endpoint. This can be a subset of all known
qualified intents. See <a xmlns="" class="xref" href="service.remoteservices.html#i1693415" title="100.3 Intents">Intents</a>. This property
is optional for registering bundles.
</p>
</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; "><code class="code">service.pid</code></td>
<td style="border-right: 0.5pt solid ; "><code class="code">String+</code></td>
<td style="">
<p>Services that are exported should have a
<code class="code">service.pid</code> property. The <code class="code">service.pid</code>
(PID) is a unique persistent identity for the service, the PID is
defined in <span class="emphasis"><em>Persistent Identifier (PID)</em></span> of
<a xmlns="" class="xref" href="introduction.html#intro.core.release" title="1.2.1 OSGi Core Release 8">OSGi Core Release 8</a>. This
property enables a distribution provider to associate persistent
proprietary data with a service registration.
</p>
</td>
</tr>
</tbody>
</table>
</div>
</div><br class="table-break" /><p>The properties and their treatment by the distribution provider is
depicted in <a xmlns="" class="xref" href="service.remoteservices.html#i1698927" title="Figure 100.2 Distribution Service Properties">Figure <span class="number">100</span>.2</a>.
</p>
<div class="figure"><a xmlns="" class="anchor" id="i1698927"></a><p class="title"><strong>Figure <span xmlns="" class="number">100</span>.2 Distribution Service Properties</strong></p>
<div class="figure-contents">
<div class="mediaobject" align="center"><img src="images/100-distribution-properties.png" align="middle" width="442" height="240" alt="Distribution Service Properties" /></div>
</div>
</div><br class="figure-break" /><div class="section">
<div xmlns="" class="titlepage">
<div>
<div>
<h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a xmlns="" class="anchor" id="i1709051"></a><span xmlns="" class="number">100.2.1</span> Registering a Service for Export
</h3>
</div>
</div>
</div>
<p>A distribution provider should create one or more endpoints for an
exported service when the following conditions are met:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<p>The service has the service property
<code class="code">service.exported.interfaces</code> set.
</p>
</li>
<li class="listitem">
<p>All intents listed in <code class="code">service.exported.intents</code>,
<code class="code">service.exported.intents.extra</code> and
<code class="code">service.intents</code> are part of the distributed provider's
vocabulary
</p>
</li>
<li class="listitem">
<p>None of the intents are mutually exclusive.</p>
</li>
<li class="listitem">
<p>The distribution provider can use the configuration types in
<code class="code">service.exported.configs</code> to create one or more
endpoints.
</p>
</li>
</ul>
</div>
<p>The endpoint must at least implement all the intents that are
listed in the <code class="code">service.exported.intents</code> and
<code class="code">service.exported.intents.extra</code> properties.
</p>
<p>The configuration types listed in the <code class="code">
service.exported.configs</code> can contain
<span class="emphasis"><em>alternatives</em></span> and/or <span class="emphasis"><em>synonyms</em></span>.
Alternatives describe different endpoints for the same service while a
synonym describes a different configuration type for the same
endpoint.
</p>
<p>A distribution provider should create endpoints for each of the
configuration types it supports; these configuration types should be
alternatives. Synonyms are allowed.
</p>
<p>If no configuration types are recognized, the distribution
provider should create an endpoint with a default configuration type
except when one of the listed configuration types is
<code class="code"><<nodefault>></code>.
</p>
<p>For more information about the configuration types, see further
<a xmlns="" class="xref" href="service.remoteservices.html#i1698916" title="100.5 Configuration Types">Configuration Types</a>.
</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="d0e1189"></a><span xmlns="" class="number">100.2.2</span> Getting an Imported Service
</h3>
</div>
</div>
</div>
<p>An imported service must be a normal service, there are therefore
no special rules for getting it. An imported service has a number of
additional properties that must be set by the distribution
provider.
</p>
<p>If the endpoint for an exported service is imported as an OSGi
service in another framework, then the following properties must be
treated as special.
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<p><code class="code">service.imported</code> - Must be set to some
value.
</p>
</li>
<li class="listitem">
<p><code class="code">service.intents</code> - This must be the combination of
the following:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; ">
<li class="listitem">
<p>The <code class="code">service.intents</code> property on the exported
service
</p>
</li>
<li class="listitem">
<p>The <code class="code">service.exported.intents</code> and
<code class="code">service.exported.intents.extra</code> properties on the
exported service
</p>
</li>
<li class="listitem">
<p>Any additional intents implemented by the distribution
providers on both sides.
</p>
</li>
</ul>
</div>
</li>
<li class="listitem">
<p><code class="code">service.imported.configs</code> - Contains the
configuration types that can be used to import this service. The
types listed in this property must be
<span class="emphasis"><em>synonymous</em></span>, that is, they must refer to exactly
the same endpoint that is exporting the service. See <a xmlns="" class="xref" href="service.remoteservices.html#i1698916" title="100.5 Configuration Types">Configuration Types</a>.
</p>
</li>
<li class="listitem">
<p><code class="code">service.exported.*</code> - Properties starting with
<code class="code">service.exported.</code> must not be set on the imported
service.
</p>
</li>
<li class="listitem">
<p><code class="code">service.exported.interfaces</code> - This property must
not be set, its content is reflected in the <code class="code">objectClass</code>
property.
</p>
</li>
</ul>
</div>
<p>All other <span class="emphasis"><em>public</em></span> service properties (not
starting with a full stop (<code class="code">'.' \u002E</code>)) must be listed on
the imported service if they use the basic service property types. If
the service property cannot be communicated because, for example, it
uses a type that can not be marshaled by the distribution provider then
the distribution provider must ignore this property.
</p>
<p>The <code class="code">service.imported</code> property indicates that a
service is an imported service. If this service property is set to any
value, then the imported service is a proxy for an endpoint. If a bundle
wants to filter out imported services, then it can add the following
filter:
</p><pre xmlns="" class="programlisting"><code>(&(!(service.imported=*)) <previousfilter>)</code></pre><p>Distribution providers can also use the <span class="emphasis"><em>Service Hook
Service Specification</em></span> of <a xmlns="" class="xref" href="introduction.html#intro.core.release" title="1.2.1 OSGi Core Release 8">OSGi Core Release 8</a> to hide services from specific bundles.
</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="i1699559"></a><span xmlns="" class="number">100.2.3</span> On Demand Import
</h3>
</div>
</div>
</div>
<p>The Service Hooks Service Specification of <a xmlns="" class="xref" href="introduction.html#intro.core.release" title="1.2.1 OSGi Core Release 8">OSGi Core Release 8</a>, allows a
distribution provider to detect when a bundle is listening for specific
services. Bundles can request imported services with specific intents by
building an appropriate filter. The distribution provider can use this
information to import a service on demand.
</p>
<p>The following example creates a Service Tracker that is interested
in an imported service.
</p><pre xmlns="" class="programlisting"><code>Filter f = context.createFilter(
"(&(objectClasss=com.acme.Foo)"
+ "(service.intents=confidentiality))"
);
ServiceTracker tracker =
new ServiceTracker(context, f, null );
tracker.open();</code></pre><p>Such a Service Tracker will inform the Listener Hook and will give
it the filter expression. If the distribution provider has registered
such a hook, it will be informed about the need for an imported
<code class="code">com.acme.Foo</code> service that has a
<code class="code">confidentiality</code> intent. It can then use some proprietary
means to find a service to import that matches the given object class
and intent.
</p>
<p>How the distribution provider finds an appropriate endpoint is out
of scope for this specification.
</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="i1693415"></a><span xmlns="" class="number">100.3</span> Intents
</h2>
</div>
</div>
</div>
<p>An intent is a name for an abstract distribution capability. An
intent can be <span class="emphasis"><em>implemented</em></span> by a service; this can then
be reflected in the <code class="code">service.intents</code> property. An intent can
also <span class="emphasis"><em>constrain</em></span> the possible communication mechanisms
that a distribution provider can choose to distribute a service. This is
reflected in the <code class="code">service.exported.intents</code> and
<code class="code">service.exported.intents.extra</code> properties.
</p>
<p>The purpose of the intents is to have a
<span class="emphasis"><em>vocabulary</em></span> that is shared between distribution aware
bundles and the distribution provider. This vocabulary allows the bundles
to express constraints on the export of their services as well as
providing information on what intents are implemented by a service.
</p>
<p>Intents have the following syntax</p><pre xmlns="" class="programlisting"><code>intent ::= token ( '.' token )?</code></pre><p><span class="emphasis"><em>Qualified intents</em></span> use a full stop (<code class="code">'.'
\u002E</code>) to separate the intent from the qualifier. A qualifier
provides additional details, however, it implies its prefix. For
example:
</p><pre xmlns="" class="programlisting"><code>confidentiality.message</code></pre><p>This example, can be <span class="emphasis"><em>expanded</em></span> into
<code class="code">confidentiality</code> and <code class="code">confidentiality.message</code>.
Qualified intents can be used to provide additional details how an intent
is achieved. However, a Distribution Provider must expand any qualified
intents to include those supported by the endpoint. This can be a subset
of all known qualified intents.
</p>
<p>The concept of intents is derived from the <a xmlns="" class="xref" href="service.remoteservices.html#i1674930" title="SCA Policy Framework specification">[3] <em>SCA Policy Framework specification</em></a>. When designing a vocabulary for a distribution
provider it is recommended to closely follow the vocabulary of intents
defined in the SCA Policy Framework.
</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="service.remoteservices-osgi.basic"></a><span xmlns="" class="number">100.3.1</span> Basic Remote Services: osgi.basic
</h3>
</div>
</div>
</div>
<p>Remote Services implementations have a large amount of freedom.
For example, they may use any mechanism that they choose to transmit
data between the caller of the remote service and the provider of the
service. This freedom means that there can be a large variation in the
behaviors supported by different Remote Services implementations.
</p>
<p>The purpose of the <code class="code"><a xmlns="" class="anchor" id="service.remoteservices-osgi.basic-name"></a>osgi.basic</code> intent
is to provide a common set of rules that can be relied upon when
exporting a simple remote service. This includes rules about the service
interface, including supported parameter and return types, as well as a
means of configuring a timeout for remote invocations.
</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="d0e1358"></a><span xmlns="" class="number">100.3.1.1</span> Minimum Supported Service Signature
</h4>
</div>
</div>
</div>
<p>Remote Services implementations which offer the
<code class="code">osgi.basic</code> intent must support remote services which
advertise a single Java interface containing zero or more
methods.
</p>
<p>The following types must be supported as declared parameters or
returns from methods on the remote service:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<p>Primitive values</p>
</li>
<li class="listitem">
<p>The OSGi scalar types, OSGi Version objects, Java enums, and
types which conform to the OSGi DTO rules as described in the OSGi
core specification. In the rest of this section these will be
known as the <span class="emphasis"><em>basic types</em></span>.
</p>
</li>
<li class="listitem">
<p>Arrays of primitive values or the basic types</p>
</li>
<li class="listitem">
<p>Lists, Collections or Iterables of the basic types, however
the implementation of the collection may not be preserved in
transit. For example a <code class="code">LinkedList</code> may be converted to
an <code class="code">ArrayList</code>.
</p>
</li>
<li class="listitem">
<p>Sets of the OSGi basic types where <code class="code">equals</code> is
used to determine identity. <code class="code">SortedSet</code> is not required
to be supported due to the difficulties associated with
serializing comparators. The implementation of the set may not be
preserved in transit. For example a <code class="code">LinkedHashSet</code> may
be converted to a <code class="code">HashSet</code>.
</p>
</li>
<li class="listitem">
<p>Maps where the keys and values are the OSGi basic types, and
<code class="code">equals</code> is used to determine identity for the keys.
<code class="code">SortedMap</code> is not required to be supported due to the
difficulties associated with serializing comparators. The
implementation of the map may not be preserved in transit. For
example a <code class="code">LinkedHashMap</code> may be converted to a
<code class="code">HashMap</code>.
</p>
</li>
<li class="listitem">
<p>Methods with no arguments, and methods with a
<code class="code">void</code> return
</p>
</li>
</ul>
</div>
</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="d0e1426"></a><span xmlns="" class="number">100.3.1.2</span> Remote Invocation Timeout
</h4>
</div>
</div>
</div>
<p>The implementation of a Remote Services provider is entirely
opaque. In many cases there will be no feedback mechanism if the
remote call hangs, or if the remote node fails. The local client must
therefore decide at what point to fail after a certain amount of time
has elapsed.
</p>
<p>A single Remote Services implementation must be able to handle a
wide variety of different remote service invocations across many
services, therefore it is difficult to identify a sensible timeout for
the remote service invocation. Some calls may be quick, and so a ten
second timeout is desirable for rapid failure detection, other calls
may be long-running, and a two minute timeout too short. The remote
service must therefore be able to declare its own timeout.
</p>
<p>To declare a timeout the remoteable service may provide a
service property <code class="code">osgi.basic.timeout</code> which provides a
timeout value in milliseconds. The value may be declared as a
<code class="code">String</code> or as a <code class="code">Number</code>, which will be
converted into a Long. The timeout value is used to limit the maximum
time for which a remote service client will be blocked waiting for a
response. The same timeout value applies to all methods on the
service. In the event that the invocation reaches the timeout value
the client must fail the method call with a ServiceException with its
type set to REMOTE.
</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="d0e1444"></a><span xmlns="" class="number">100.3.2</span> Asynchronous Remote Services: osgi.async
</h3>
</div>
</div>
</div>
<p>Some service invocations operate asynchronously, returning quickly
and continuing to process in the background. For void methods with no
completion notifications this is simple to achieve remotely, but more
useful scenarios are difficult to support without using higher-level
abstractions to represent the eventual result.
</p>
<p>The purpose of the <code class="code">osgi.async</code> intent is to provide a
common set of rules that can be relied upon for remote services which
return types representing an asynchronously executing method.
</p>
<p>The <code class="code">osgi.async</code> intent makes no guarantees about the
service interface(s) or method parameters supported by the remote
services implementation. It is therefore recommended that it be used in
conjunction with another intent, such as the <a xmlns="" class="xref" href="service.remoteservices.html#service.remoteservices-osgi.basic" title="100.3.1 Basic Remote Services: osgi.basic">osgi.basic</a> intent.
</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="d0e1461"></a><span xmlns="" class="number">100.3.2.1</span> Supported Return Types
</h4>
</div>
</div>
</div>
<p>Asynchronous returns are implemented using a holder type. The
holder represents the state of the asynchronous execution, and can be
queried for its completion state. When the execution is complete the
holder can be queried for the result of the execution, or for its
failure.
</p>
<p>The following holder types must be supported as return types
from methods on the remote service:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<p><code class="code">org.osgi.util.promise.Promise</code></p>
</li>
<li class="listitem">
<p><code class="code">java.util.concurrent.Future</code></p>
</li>
<li class="listitem">
<p><code class="code">java.util.concurrent.CompletionStage</code></p>
</li>
<li class="listitem">
<p><code class="code">java.util.concurrent.CompletableFuture</code></p>
</li>
</ul>
</div>
<p>The full set of supported types for the eventual return value
encapsulated by the holder object are not defined by the
<code class="code">osgi.async</code> intent. Instead the full set of supported
types can be inferred from the other supported intents supported by
the Remote Services implementation. For example the <a xmlns="" class="xref" href="service.remoteservices.html#service.remoteservices-osgi.basic" title="100.3.1 Basic Remote Services: osgi.basic">osgi.basic</a> intent would ensure
support for a return value of
<code class="code">Promise<List<String>></code></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="d0e1494"></a><span xmlns="" class="number">100.3.2.2</span> Asynchronous Failures
</h4>
</div>
</div>
</div>
<p>If an asynchronous remote execution fails then the holder type
must be failed with the same exception that would have been thrown in
a synchronous call.
</p>
<p>The reason for the failure may be as a result of a failure in
communications, a timeout, or because the remote invocation resulted
in an exception
</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="d0e1501"></a><span xmlns="" class="number">100.3.3</span> Confidential Remote Services: osgi.confidential
</h3>
</div>
</div>
</div>
<p>The <code class="code">osgi.confidential</code> intent can be used to state
that the remote service communications must only be readable by the
intended recipient, for example, through the use of TLS-based transport
encryption.
</p>
<p>If a Remote Services implementation does not support confidential
communications, or is not configured as such, it must not expose the
service remotely.
</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="d0e1511"></a><span xmlns="" class="number">100.3.4</span> Private Remote Services: osgi.private
</h3>
</div>
</div>
</div>
<p>In many deployment scenarios, including cloud, embedded or IoT
deployments, hosts may be accessible via a public network and via a
private network. In such cases hosts will have multiple IP addresses to
separate public network access from private network access. Private IP
addresses normally in one of the following blocks:
<code class="code">10.0.0.0/8</code>, <code class="code">172.16.0.0/12</code> or
<code class="code">192.168.0.0/16</code>.
</p>
<p>In many cases it is desirable to expose remote services only on
the private network so that these services cannot be accessed from the
outside world. This is especially useful if this service is used as a
microservice within a larger application. The <code class="code">osgi.private</code>
intent can be specified for this purpose.
</p>
<p>If the <code class="code">osgi.private</code> intent is required on the remote
service, it will only be exposed as a remote service on a private
network on the host. If the host does not support a private IP address
or if the Remote Services implementation does not have the information
to decide whether a host IP is private, the service should not be
exposed.
</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="d0e1535"></a><span xmlns="" class="number">100.4</span> General Usage
</h2>
</div>
</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="d0e1538"></a><span xmlns="" class="number">100.4.1</span> Call by Value
</h3>
</div>
</div>
</div>
<p>Normal service semantics are call-by-reference. An object passed
as an argument in a service call is a direct reference to that object.
Any changes to this object will be shared on both sides of the service
registry.
</p>
<p>Distributed services are different. Arguments are normally passed
by value, which means that a copy is sent to the remote system, changes
to this value are not reflected in the originating framework. When using
distributed services, call-by-value should always be assumed by all
participants in the distribution chain.
</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="d0e1545"></a><span xmlns="" class="number">100.4.2</span> Data Fencing
</h3>
</div>
</div>
</div>
<p>Services are syntactically defined by their Java interfaces. When
exposing a service over a remote protocol, typically such an interface
is mapped to a protocol-specific interface definition. For example, in
CORBA the Java interfaces would be converted to a corresponding IDL
definition. This mapping does not always result in a complete
solution.
</p>
<p>Therefore, for many practical distributed applications it will be
necessary to constrain the possible usage of data types in service
interfaces. A distribution provider must at least support interfaces
(not classes) that only use the basic types as defined for the service
properties. These are the primitive types and their wrappers as well as
arrays and collections. See <span class="emphasis"><em>Filter Syntax</em></span> of <a xmlns="" class="xref" href="introduction.html#intro.core.release" title="1.2.1 OSGi Core Release 8">OSGi Core Release 8</a> for a list of
service property types.
</p>
<p>Distribution providers will in general provide a richer set of
types that can be distributed.
</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="d0e1559"></a><span xmlns="" class="number">100.4.3</span> Remote Services Life Cycle
</h3>
</div>
</div>
</div>
<p>A distributed service must closely track any modifications on the
corresponding service registration. If service properties are modified,
these modifications should be propagated to the distributed service and
associated service proxies. If the exported service is unregistered, the
endpoint must be withdrawn as soon as possible and any imported service
proxies unregistered.
</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="d0e1564"></a><span xmlns="" class="number">100.4.4</span> Runtime
</h3>
</div>
</div>
</div>
<p>An imported service is just like any other service and can be used
as such. However, certain non-functional characteristics of this service
can differ significantly from what is normal for an in-VM object call.
Many of these characteristics can be mapped to the normal service
operations. That is, if the connection fails in any way, the service can
be unregistered. According to the standard OSGi contract, this means
that the users of that service must perform the appropriate cleanup to
prevent stale references.
</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="d0e1569"></a><span xmlns="" class="number">100.4.5</span> Exceptions
</h3>
</div>
</div>
</div>
<p>It is impossible to guarantee that a service is not used when it
is no longer valid. Even with the synchronous callbacks from the Service
Listeners, there is always a finite window where a service can be used
while the underlying implementation has failed. In a distributed
environment, this window can actually be quite large for an imported
service.
</p>
<p>Such failure situations must be exposed to the application code
that uses a failing imported service. In these occasions, the
distribution provider must notify the application by throwing a Service
Exception, or subclass thereof, with the reason <code class="code">REMOTE</code>. The
Service Exception is a Runtime Exception, it can be handled higher up in
the call chain. The cause of this Service Exception must be the
Exception that caused the problem.
</p>
<p>A distribution provider should log any problems with the
communications layer to the Log Service, if available.
</p>
</div>
</div>
<div class="section">
<div xmlns="" class="titlepage">