-
Notifications
You must be signed in to change notification settings - Fork 8
/
service.resourcemonitoring.html
6993 lines (6886 loc) · 845 KB
/
service.resourcemonitoring.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>144 Resource Monitoring Specification - 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.network.html" title="143 Network Interface Information Service Specification" />
<link rel="next" href="service.usbinfo.html" title="145 USB Information Device Category Specification" />
<meta name="Section-title" content="144 Resource Monitoring Specification" />
<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.network.html">Prev</a>
</td>
<th width="60%" align="center"> </th>
<td width="20%" align="right"> <a accesskey="n" href="service.usbinfo.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.resourcemonitoring"></a><span xmlns="" class="number">144</span> Resource Monitoring Specification
</h1>
</div>
<div>
<p xmlns="http://www.w3.org/1999/xhtml" class="releaseinfo"><a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring" title="144.22 org.osgi.service.resourcemonitoring">Version 1.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="d0e104588"></a><span xmlns="" class="number">144.1</span> Introduction
</h2>
</div>
</div>
</div>
<p>Applications, executed on an OSGi platform, need hardware resources
(CPU, memory, disk, storage space) and software resources (sockets,
threads). As these resources are limited, applications have to share them
in order to preserve system quality of service. This is a general fact in
OSGi business cases where multiple bundles share the OSGi framework. This
is especially the case when the framework is shared by distinct tenants,
which are responsible for distinct set of bundles running with their own
business logic and lifecycle.
</p>
<p>The chapter defines an API for applications to monitor hardware
resources consumed by any set of bundles. The bundle is the smallest unit
that can be considered as a resource context, the entity that is
monitored. Monitored data may enable applications to take decisions on
management actions to apply. Resource management actions are mentioned as
examples in this chapter, for example, actions on the lifecycle of
components, bundles, the framework and the JVM, Java threads, raise of
exceptions.
</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="d0e104595"></a><span xmlns="" class="number">144.2</span> Essentials
</h2>
</div>
</div>
</div>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: bullet; ">
<li class="listitem" style="list-style-type: disc">
<p><span class="italic">Monitoring</span> - Bundle execution
resource usage is monitored.
</p>
</li>
<li class="listitem" style="list-style-type: disc">
<p><span class="emphasis"><em>Granular activation</em></span> - The resource
monitoring service can be activated and deactivated per bundle or per
bundle set.
</p>
</li>
<li class="listitem" style="list-style-type: disc">
<p><span class="emphasis"><em>Extensibility</em></span> - Five resource types are
specified (CPU, memory, disk storage, alive thread and in-use
sockets). The list of monitored resource types is extensible and
query-able.
</p>
</li>
<li class="listitem" style="list-style-type: disc">
<p><span class="emphasis"><em>Eventing</em></span> - The resource monitoring service
notifies interested entities of exceeded limits.
</p>
</li>
</ul>
</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="d0e104619"></a><span xmlns="" class="number">144.3</span> Entities
</h2>
</div>
</div>
</div>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: bullet; ">
<li class="listitem" style="list-style-type: disc">
<p><span class="emphasis"><em>Resource Context</em></span> - A logical entity for
resource accounting. A context may be related to a single bundle or a
set of bundles.
</p>
</li>
<li class="listitem" style="list-style-type: disc">
<p><span class="emphasis"><em>System Resource Context</em></span> - Resource context
of the core framework.
</p>
</li>
<li class="listitem" style="list-style-type: disc">
<p><span class="emphasis"><em>Platform Resource Context</em></span> - A Resource
context monitoring the resource usage of the platform as a
whole.
</p>
</li>
<li class="listitem" style="list-style-type: disc">
<p><span class="emphasis"><em>Resource Monitor</em></span> - Monitors the usage of a
specific resource type for a specific Resource Context. Resource
Monitors track resource usage. They hold Resource Thresholds
instances. Resource Monitor object implementation may depend on
standard or proprietary JVM APIs, and on operating system
features.
</p>
</li>
<li class="listitem" style="list-style-type: disc">
<p><span class="emphasis"><em>Resource Monitor Factory</em></span> - A factory
creating Resource Monitor instances for every Resource Context.
</p>
</li>
<li class="listitem" style="list-style-type: disc">
<p><span class="emphasis"><em>CPU Monitor</em></span> - Resource Monitor used to
monitor CPU.
</p>
</li>
<li class="listitem" style="list-style-type: disc">
<p><span class="emphasis"><em>Memory Monitor</em></span> - Resource Monitor used to
monitor memory.
</p>
</li>
<li class="listitem" style="list-style-type: disc">
<p><span class="emphasis"><em>Socket Monitor</em></span> - Resource Monitor used to
monitor socket resource.
</p>
</li>
<li class="listitem" style="list-style-type: disc">
<p><span class="emphasis"><em>Disk Storage Monitor</em></span> - Resource Monitor for
disk storage usage.
</p>
</li>
<li class="listitem" style="list-style-type: disc">
<p><span class="emphasis"><em>Thread Monitor</em></span> - Resource Monitor used to
monitor alive Java Thread objects.
</p>
</li>
<li class="listitem" style="list-style-type: disc">
<p><span class="emphasis"><em>Resource Listener</em></span> - A Resource Listener
receives resource threshold notifications.
</p>
</li>
<li class="listitem" style="list-style-type: disc">
<p><span class="emphasis"><em>Resource Event</em></span> - A Resource Event defines a
notification to be synchronously sent to Resource Listener
instances.
</p>
</li>
<li class="listitem" style="list-style-type: disc">
<p><span class="emphasis"><em>Resource Context Listener</em></span> - A Resource
Context Listener receives notifications about resource context
creation and configuration.
</p>
</li>
<li class="listitem" style="list-style-type: disc">
<p><span class="emphasis"><em>Resource Context Event</em></span> - A Resource Context
Event defines a notification to be sent to Resource Context Listeners
instances.
</p>
</li>
<li class="listitem" style="list-style-type: disc">
<p><span class="emphasis"><em>Resource Monitoring Service</em></span> - This is a
singleton entity which manages Resource Context instances. It is used
to create new Resource Context instances and to enumerate existing
contexts.
</p>
</li>
<li class="listitem" style="list-style-type: disc">
<p><span class="emphasis"><em>Resource Monitoring Client</em></span> - Makes any
decision to ensure the quality of the service of the system. They use
the Resource Monitoring Service to create Resource Context instances.
It configures them by adding bundles and Resource Monitors.
</p>
</li>
</ul>
</div>
<div class="figure"><a xmlns="" class="anchor" id="service.resourcemonitoring_bibliomixed_id_20141210_15h18_rfc_fig_2"></a><p class="title"><strong>Figure <span xmlns="" class="number">144</span>.1 Resource monitoring class diagram specification.</strong></p>
<div class="figure-contents">
<div class="mediaobject" align="center"><img src="images/144-service.resourcemonitoring_resource_monitoring_specification_class_diagram_rev_01.png" align="middle" width="450" height="315" alt="Resource monitoring class diagram specification." /></div>
</div>
</div><br class="figure-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="d0e104709"></a><span xmlns="" class="number">144.4</span> Operation Summary
</h2>
</div>
</div>
</div>
<p>Resource Monitoring Clients use the Resource Monitoring Service
service to create Resource Contexts. These clients set bundles or group of
bundles to Resource Contexts. They also request every Resource Monitor
Factory to create Resource Monitors for a resource type. These Resource
Monitors are associated to a single Resource Context.
</p>
<p>When activated, Resource Monitors provide the current resource usage
per Resource Context. Then, they check whether the current resource usage
is compatible with the thresholds held by their associated Resource
Listeners. When one of these thresholds is violated, the related Resource
Monitor notifies the Resource Listener holding this threshold.
</p>
<p>The Resource Monitoring Service manages the set of Resource
Contexts. Resource Contexts are persistent between platform restarts.
Resource Context Listeners are notified when a Resource Context is created
or deleted or when a Resource Context configuration (that is, adding or
removing of bundle) is updated.
</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="d0e104718"></a><span xmlns="" class="number">144.5</span> Resource Context
</h2>
</div>
</div>
</div>
<p>A <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceContext" title="144.22.2 public interface ResourceContext">ResourceContext</a> instance is a logical entity used to account
resource usage. Every Resource Context defines a bundle scope which can be
either a single bundle or a set of bundles. Once the bundle scope is
defined, resources used by those bundles are monitored through a set of
per-resource-type Resource Monitor instances.
</p>
<p>Resource Context instances are persistent. The persistence of those
instances is directly managed by the Resource Monitoring Service
instance.
</p>
<p>Each Resource Context is uniquely identified by a name. It can be
retrieved through the <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceContext.getName--" title="144.22.2.7 public String getName()">getName()</a> method. It can not be changed, that is it is
definitively set when the Resource Context instance is created.
</p>
<p>The Resource Context bundle scope is retrieved through the <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceContext.getBundleIds--" title="144.22.2.4 public long[] getBundleIds()">getBundleIds()</a> method. This bundle scope can be extended through
the <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceContext.addBundle-long-" title="144.22.2.1 public void addBundle(long bundleId) throws ResourceContextException">addBundle(long)</a> method. Bundles can also be removed from a
Resource Context through the <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceContext.removeBundle-long-ResourceContext-" title="144.22.2.10 public void removeBundle(long bundleId, ResourceContext destination) throws ResourceContextException">removeBundle(long,ResourceContext)</a> method. For this last method, a Resource Context
instance MAY be specified in order to associate the removed bundle to
another Resource Context instance.
</p>
<p>Resource Monitor instances are retrieved through <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceContext.getMonitor-String-" title="144.22.2.5 public ResourceMonitor<?> getMonitor(String resourceType) throws ResourceContextException">getMonitor(String)</a> method or the <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceContext.getMonitors--" title="144.22.2.6 public ResourceMonitor<?>[] getMonitors() throws ResourceContextException">getMonitors()</a> method. The list of available resource types is
retrieved through the Resource Monitoring Service singleton
instance.
</p>
<p>Resource Monitor instances are added to and removed from a Resource
Context instance by calling either <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceContext.addResourceMonitor-ResourceMonitor-" title="144.22.2.2 public void addResourceMonitor(ResourceMonitor<?> resourceMonitor) throws ResourceContextException">addResourceMonitor(ResourceMonitor)</a> method or <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceContext.removeResourceMonitor-ResourceMonitor-" title="144.22.2.12 public void removeResourceMonitor(ResourceMonitor<?> resourceMonitor) throws ResourceContextException">removeResourceMonitor(ResourceMonitor)</a> method. Both methods SHOULD only be called by
<a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceMonitorFactory" title="144.22.10 public interface ResourceMonitorFactory<T>">ResourceMonitorFactory</a> instances (see <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceMonitorFactory.createResourceMonitor-ResourceContext-" title="144.22.10.2 public ResourceMonitor<T> createResourceMonitor(ResourceContext resourceContext) throws ResourceMonitorException">createResourceMonitor(ResourceContext)</a> method).
</p>
<p>A Resource Context is retrieved through the Resource Monitoring
Service service.
</p>
<p>A Resource Context instance can be deleted through <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceContext.removeContext-ResourceContext-" title="144.22.2.11 public void removeContext(ResourceContext destination) throws ResourceContextException">removeContext(ResourceContext)</a> method. The Resource Context input argument then
defines a destination Resource Context instance for the bundles belonging
to the to-be-removed Resource Context instance.
</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="d0e104761"></a><span xmlns="" class="number">144.6</span> System Resource Context
</h2>
</div>
</div>
</div>
<p>The System Resource Context is the Resource Context of the execution
environment for the running OSGi bundles. It includes the resources of
bundle "0". It is retrieved through the Resource Monitoring Service
service.
</p>
<p>The name of this context is “system”. See <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceMonitoringService.SYSTEM_CONTEXT_NAME" title="144.22.11.7 public static final String SYSTEM_CONTEXT_NAME = "system"">SYSTEM_CONTEXT_NAME</a>.
</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="d0e104770"></a><span xmlns="" class="number">144.7</span> Framework Resource Context
</h2>
</div>
</div>
</div>
<p>The Framework Resource Context is a Resource Context monitoring
resources of the platform as a whole. It is retrieved through the Resource
Monitoring Service service. This Resource Context holds all hosted bundles
allowing access to the whole platform resource consumption.
</p>
<p>The name of this context is “framework”. See <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceMonitoringService.FRAMEWORK_CONTEXT_NAME" title="144.22.11.1 public static final String FRAMEWORK_CONTEXT_NAME = "framework"">FRAMEWORK_CONTEXT_NAME</a>.
</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="d0e104779"></a><span xmlns="" class="number">144.8</span> Resource Monitor
</h2>
</div>
</div>
</div>
<p>A <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceMonitor" title="144.22.8 public interface ResourceMonitor<T>">ResourceMonitor</a> instance monitors a resource type consumed by the
bundles of a specific Resource Context instance.
</p>
<p>A Resource Context instance holds at most one Resource Monitor
instance per monitor-able resource type. Resource Monitor instances are
retrieved through their related Resource Context instance. Resource
Monitor instances give access to their related Resource Context instance
through a call to See <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceMonitor.getContext--" title="144.22.8.5 public ResourceContext getContext()">getContext()</a> method.
</p>
<p>The monitored resource type is retrieved through the <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceMonitor.getResourceType--" title="144.22.8.7 public String getResourceType()">getResourceType()</a> method.
</p>
<p>The current usage of a resource consumed by a Resource Context
instance is given through the <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceMonitor.getUsage--" title="144.22.8.9 public Comparable<T> getUsage() throws ResourceMonitorException">getUsage()</a> method. This method returns a Java Object to be
casted to the appropriate Java object type depending on the Resource type.
The next table provides the expected Java Object type for each specified
resource type:
</p>
<div class="table"><a xmlns="" class="anchor" id="d0e104798"></a><p class="title"><strong>Table <span xmlns="" class="number">144</span>.1 Table of resource types.</strong></p>
<div class="table-contents">
<table summary="Table of resource types." 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 align="left" class="c1" />
<col align="left" class="c2" />
<col align="left" class="c3" />
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Type of Resource</th>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Expected Java Object type</th>
<th style="border-bottom: 0.5pt solid ; " align="left">Value description</th>
</tr>
</thead>
<tfoot>
<tr>
<th style="border-right: 0.5pt solid ; " align="left">Disk storage space</th>
<th style="border-right: 0.5pt solid ; " align="left"><code class="code">Long</code></th>
<th style="" align="left">Bytes on the bundle persistent storage area.</th>
</tr>
</tfoot>
<tbody>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">CPU</td>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left"><code class="code">Long</code></td>
<td style="border-bottom: 0.5pt solid ; " align="left">Cumulative CPU time in ns.</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Memory</td>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left"><code class="code">Long</code></td>
<td style="border-bottom: 0.5pt solid ; " align="left">Allocated memory in bytes.</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Threads</td>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left"><code class="code">Long</code></td>
<td style="border-bottom: 0.5pt solid ; " align="left">Number of alive thread.</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Socket</td>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left"><code class="code">Long</code></td>
<td style="border-bottom: 0.5pt solid ; " align="left">Number of in-use socket.</td>
</tr>
</tbody>
</table>
</div>
</div><br class="table-break" /><p>For example, for a <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.monitor.MemoryMonitor" title="144.23.4 public interface MemoryMonitor extends ResourceMonitor<Long>">MemoryMonitor</a> instance, a call to <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceMonitor.getUsage--" title="144.22.8.9 public Comparable<T> getUsage() throws ResourceMonitorException">getUsage()</a> returns a Long java object indicating the amount
of memory the related Resource Context instance is consuming.
</p>
<p>A Resource Monitor instance is enabled and disabled through <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceMonitor.enable--" title="144.22.8.3 public void enable() throws ResourceMonitorException">enable()</a> and <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceMonitor.disable--" title="144.22.8.2 public void disable() throws ResourceMonitorException">disable()</a> methods. The state (enabled or disabled) of a
Resource Monitor is retrieved through a call to <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceMonitor.isEnabled--" title="144.22.8.12 public boolean isEnabled()">isEnabled()</a> method. Enable and disable monitoring mechanisms
on-the-fly on localized set of bundles may be crucial for performance
issues. See <a xmlns="" class="xref" href="service.resourcemonitoring.html#service.resourcemonitoring_bibliomixed_id_20150105_11h45_1" title="Adaptive Monitoring of End-user OSGi based Home Boxes">[1] <em>Adaptive Monitoring of End-user OSGi based Home Boxes</em></a>.
</p>
<p>A Resource Monitor instance can also be deleted (<a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceMonitor.delete--" title="144.22.8.1 public void delete() throws ResourceMonitorException">delete()</a> method). <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceMonitor.isDeleted--" title="144.22.8.11 public boolean isDeleted()">isDeleted()</a> method returns true if the ResourceMonitor
instance has been deleted.
</p>
<p>Five types of Resource Monitor are specified:</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: bullet; ">
<li class="listitem" style="list-style-type: disc">
<p>CPU Monitor</p>
</li>
<li class="listitem" style="list-style-type: disc">
<p>Memory Monitor</p>
</li>
<li class="listitem" style="list-style-type: disc">
<p>Socket Monitor</p>
</li>
<li class="listitem" style="list-style-type: disc">
<p>Disk Storage Monitor</p>
</li>
<li class="listitem" style="list-style-type: disc">
<p>Thread Monitor</p>
</li>
</ul>
</div>
<p>The support of any Resource Monitor is optional. This list MAY be
extended by the solution vendor. The list of the types that are supported
on the OSGi platform can be computed by querying <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceMonitorFactory" title="144.22.10 public interface ResourceMonitorFactory<T>">ResourceMonitorFactory</a> services. Resource monitoring algorithms may vary
with factories, see <a xmlns="" class="xref" href="service.resourcemonitoring.html#service.resourcemonitoring_bibliomixed_id_20150105_11h46_2" title="Memory Monitoring in a Multi-tenant OSGi Execution Environment">[2] <em>Memory Monitoring in a Multi-tenant OSGi Execution Environment</em></a>.
They are out of the scope of this specification.
</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="d0e104901"></a><span xmlns="" class="number">144.9</span> Resource Monitor Factory
</h2>
</div>
</div>
</div>
<p>A <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceMonitorFactory" title="144.22.10 public interface ResourceMonitorFactory<T>">ResourceMonitorFactory</a> is a service that provides Resource Monitor
instances of a specific resource type (for example, <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.monitor.CPUMonitor" title="144.23.2 public interface CPUMonitor extends ResourceMonitor<Long>">CPUMonitor</a>, <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.monitor.MemoryMonitor" title="144.23.4 public interface MemoryMonitor extends ResourceMonitor<Long>">MemoryMonitor</a>, etc.) for every Resource Context.
</p>
<p>Every Resource Monitor Factory service is registered with the
<code class="code">org.osgi.resourcemonitoring.ResourceType</code> mandatory property,
see <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceMonitorFactory.RESOURCE_TYPE_PROPERTY" title="144.22.10.1 public static final String RESOURCE_TYPE_PROPERTY = "org.osgi.resourcemonitoring.ResourceType"">RESOURCE_TYPE_PROPERTY</a>. This property indicates which type of Resource
Monitor a Resource Monitor Factory is able to create. The type can also be
retrieved through a call to <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceMonitorFactory.getType--" title="144.22.10.3 public String getType()">getType()</a>. The type MUST be unique (two Resource Monitor
Factory services MUST not have the same type).
</p>
<p>New Resource Monitor instances are created by a call to <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceMonitorFactory.createResourceMonitor-ResourceContext-" title="144.22.10.2 public ResourceMonitor<T> createResourceMonitor(ResourceContext resourceContext) throws ResourceMonitorException">createResourceMonitor(ResourceContext)</a>. This method returns a new Resource Monitor
instance associated to the provided Resource Context instance. The
ResourceMonitorFactory MUST call <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceContext.addResourceMonitor-ResourceMonitor-" title="144.22.2.2 public void addResourceMonitor(ResourceMonitor<?> resourceMonitor) throws ResourceContextException">addResourceMonitor(ResourceMonitor)</a> to associate the newly created ResourceMonitor
with the provided ResourceContext instance. The newly created Resource
Monitor is disabled, that is, it is initially not monitoring the Resource
Context resource consumption. It can be activated through a call to <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceMonitor.enable--" title="144.22.8.3 public void enable() throws ResourceMonitorException">enable()</a>.
</p>
<p>Resource Monitor instances are deleted by calling <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceMonitor.delete--" title="144.22.8.1 public void delete() throws ResourceMonitorException">delete()</a> method.
</p>
<p>A Resource Monitor instance MUST only be created through its <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceMonitorFactory" title="144.22.10 public interface ResourceMonitorFactory<T>">ResourceMonitorFactory</a>.
</p>
<p>Resource Monitor Factory instances should be only used by the
Resource Monitoring Service singleton instance. The Resource Monitoring
Service singleton instance performs a service lookup on all existing
Resource Monitor Factories. It uses a Resource Monitor Factory instance
when it has to create a new Resource Context instance and their associated
Resource Monitor instances.
</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="d0e104939"></a><span xmlns="" class="number">144.10</span> CPU Monitor
</h2>
</div>
</div>
</div>
<p>A <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.monitor.CPUMonitor" title="144.23.2 public interface CPUMonitor extends ResourceMonitor<Long>">CPUMonitor</a> instance is a Resource Monitor used to monitor the
CPU usage of the bundles belonging to a Resource Context.
</p>
<p>CPU usage and thresholds are expressed as a cumulative number of
nanoseconds (long). The encapsulated value can be retrieved with the <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.monitor.CPUMonitor.getCPUUsage--" title="144.23.2.1 public long getCPUUsage()">getCPUUsage()</a> method.
</p>
<p>In case where a threshold is reached, the CPU Monitor instance
generates an event triggering Resource Monitoring Clients defined
corrective actions (for example, decrease thread priority).
</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="d0e104952"></a><span xmlns="" class="number">144.11</span> Memory Monitor
</h2>
</div>
</div>
</div>
<p>A <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.monitor.MemoryMonitor" title="144.23.4 public interface MemoryMonitor extends ResourceMonitor<Long>">MemoryMonitor</a> instance monitors and limits the memory used by
the bundles of a Resource Context instance.
</p>
<p>Memory is accounted as bytes. Memory usage and thresholds are long
java objects. The encapsulated value can be retrieved through the <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.monitor.MemoryMonitor.getMemoryUsage--" title="144.23.4.1 public long getMemoryUsage()">getMemoryUsage()</a> method.
</p>
<p>When an error threshold is reached, the next memory allocation MAY
be prevented by the system and MAY throw a specific Exception in the
associated context.
</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="d0e104965"></a><span xmlns="" class="number">144.12</span> Socket Monitor
</h2>
</div>
</div>
</div>
<p>A <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.monitor.SocketMonitor" title="144.23.5 public interface SocketMonitor extends ResourceMonitor<Long>">SocketMonitor</a> instance monitors and limits the number of
existing sockets (for example, TCP, UDP) which are considered to be in use
(for example, listening for incoming packet, bound, or sending outgoing
packets).
</p>
<p>A Socket is considered to be in-use state when a native socket file
descriptor is created. It leaves this state when this socket file
descriptor is deleted.
</p>
<p>The number of in-use sockets is a long. The encapsulated value can
be retrieved using <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.monitor.SocketMonitor.getSocketUsage--" title="144.23.5.1 public long getSocketUsage()">getSocketUsage()</a> method.
</p>
<p>When an <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceEvent.ERROR" title="144.22.6.1 public static final int ERROR = 2">ERROR</a> threshold is reached, the next socket file
descriptor creation in the associated context MAY throw a
SocketException.
</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="d0e104982"></a><span xmlns="" class="number">144.13</span> Disk Storage Monitor
</h2>
</div>
</div>
</div>
<p>A <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.monitor.DiskStorageMonitor" title="144.23.3 public interface DiskStorageMonitor extends ResourceMonitor<Long>">DiskStorageMonitor</a> instance monitors and limits the use of persistent
storage within Bundle Persistent Storage Area a Resource Context (the
bundles actually belonging to it) consumes.
</p>
<p>Disk Storage is expressed as a number of bytes of type long. The
encapsulated value can be retrieved using <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.monitor.DiskStorageMonitor.getUsedDiskStorage--" title="144.23.3.1 public long getUsedDiskStorage()">getUsedDiskStorage()</a> method.
</p>
<p>An IOException MAY be thrown in the associated context when an <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceEvent.ERROR" title="144.22.6.1 public static final int ERROR = 2">ERROR</a> threshold is reached.
</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="d0e104997"></a><span xmlns="" class="number">144.14</span> Thread Monitor
</h2>
</div>
</div>
</div>
<p>A <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.monitor.ThreadMonitor" title="144.23.6 public interface ThreadMonitor extends ResourceMonitor<Integer>">ThreadMonitor</a> instance monitors and limits the number of alive
Java Thread objects for a Resource Context instance. A Thread is
considered to be alive when it is in the <code class="code">RUNNABLE</code>,
<code class="code">BLOCKED</code>, <code class="code">WAITING</code> or <code class="code">TIMED_WAITING</code>
thread state.
</p>
<p>Usage and thresholds are Java int objects. The encapsulated value
can be retrieved using <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.monitor.ThreadMonitor.getAliveThreads--" title="144.23.6.1 public int getAliveThreads()">getAliveThreads()</a> method.
</p>
<p>When an <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceEvent.ERROR" title="144.22.6.1 public static final int ERROR = 2">ERROR</a> threshold is reached, any further thread
activation will be prevented in the associated context. An InternalError
exception MAY also be thrown in the associated context.
</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="d0e105024"></a><span xmlns="" class="number">144.15</span> Resource Listener
</h2>
</div>
</div>
</div>
<p>A <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceListener" title="144.22.7 public interface ResourceListener<T>">ResourceListener</a> receives notifications about resource usage for a
specific Resource Context and a specific type of resource. A notification
will be sent to a Resource Listener when one of its thresholds is
violated.
</p>
<p>A Resource Listener holds two types of threshold:</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: bullet; ">
<li class="listitem" style="list-style-type: disc">
<p>A lower threshold type. This kind of threshold is reached when
the monitored resource usage decreases below the threshold.
</p>
</li>
<li class="listitem" style="list-style-type: disc">
<p>An upper threshold type. An upper threshold is reached when the
monitored resource usage exceeds this threshold.
</p>
</li>
</ul>
</div>
<p>Each of them have two levels:</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: bullet; ">
<li class="listitem" style="list-style-type: disc">
<p>a <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceEvent.WARNING" title="144.22.6.3 public static final int WARNING = 1">WARNING</a> level.
</p>
</li>
<li class="listitem" style="list-style-type: disc">
<p>an <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceEvent.ERROR" title="144.22.6.1 public static final int ERROR = 2">ERROR</a> level.
</p>
</li>
</ul>
</div>
<p>A threshold has the following state diagram, which transitions are
associated to events:
</p>
<div class="figure"><a xmlns="" class="anchor" id="service.resourcemonitoring_bibliomixed_id_20141211_16h06_rfc_fig_3"></a><p class="title"><strong>Figure <span xmlns="" class="number">144</span>.2 Threshold state diagram.</strong></p>
<div class="figure-contents">
<div class="mediaobject" align="center"><img src="images/144-ResourceThresholdState.png" align="middle" height="315" alt="Threshold state diagram." /></div>
</div>
</div><br class="figure-break" /><p>A threshold state depends on the current consumption of resource and
the type of threshold (upper or lower threshold).
</p>
<p>A Resource Listener is registered as an OSGi service. The
implementer must provide the two following mandatory properties:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: bullet; ">
<li class="listitem" style="list-style-type: disc">
<p><a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceListener.RESOURCE_CONTEXT" title="144.22.7.3 public static final String RESOURCE_CONTEXT = "resource.context"">RESOURCE_CONTEXT</a> property – a String defining the name of
Resource Context for which the Listener want to receive threshold
notifications.
</p>
</li>
<li class="listitem" style="list-style-type: disc">
<p><a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceListener.RESOURCE_TYPE" title="144.22.7.4 public static final String RESOURCE_TYPE = "resource.type"">RESOURCE_TYPE</a> property – a String defining which type of
resource the listener wants to monitor.
</p>
</li>
</ul>
</div>
<p>It also has to provide at least one of these four properties when
registered as an OSGi service:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: bullet; ">
<li class="listitem" style="list-style-type: disc">
<p><a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceListener.UPPER_WARNING_THRESHOLD" title="144.22.7.6 public static final String UPPER_WARNING_THRESHOLD = "upper.warning.threshold"">UPPER_WARNING_THRESHOLD</a></p>
</li>
<li class="listitem" style="list-style-type: disc">
<p><a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceListener.UPPER_ERROR_THRESHOLD" title="144.22.7.5 public static final String UPPER_ERROR_THRESHOLD = "upper.error.threshold"">UPPER_ERROR_THRESHOLD</a></p>
</li>
<li class="listitem" style="list-style-type: disc">
<p><a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceListener.LOWER_WARNING_THRESHOLD" title="144.22.7.2 public static final String LOWER_WARNING_THRESHOLD = "lower.warning.threshold"">LOWER_WARNING_THRESHOLD</a></p>
</li>
<li class="listitem" style="list-style-type: disc">
<p><a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceListener.LOWER_ERROR_THRESHOLD" title="144.22.7.1 public static final String LOWER_ERROR_THRESHOLD = "lower.error.threshold"">LOWER_ERROR_THRESHOLD</a></p>
</li>
</ul>
</div>
<p>These properties are mapped to the four types of threshold values a
Resource Listener may support. The service properties are used to notify
the associated Resource Monitor when one of these threshold values is
modified.
</p>
<p>Threshold values can also be retrieved through a set of getter
methods. All of these methods returns a <code class="code">Comparable</code> object
used by the associated Resource Monitor in order to determine the current
state of the current usage.
</p>
<p><a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceListener.RESOURCE_CONTEXT" title="144.22.7.3 public static final String RESOURCE_CONTEXT = "resource.context"">RESOURCE_CONTEXT</a> and <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceListener.RESOURCE_TYPE" title="144.22.7.4 public static final String RESOURCE_TYPE = "resource.type"">RESOURCE_TYPE</a> properties are used by Resource Monitors to
identify their associated Resource Listeners. Once associated, a Resource
Monitor retrieves the threshold settings using service properties. When
one of its thresholds is reached, the Resource Monitor calls <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceListener.notify-ResourceEvent-" title="144.22.7.11 public void notify(ResourceEvent<T> event)">notify(ResourceEvent)</a>.
</p>
<p>Two examples of resource consumption are explained below, first with
in-use sockets monitoring, second with CPU monitoring. The next picture
shows the state diagram of the number of in-use state socket over the
time.
</p>
<div class="figure"><a xmlns="" class="anchor" id="service.resourcemonitoring_bibliomixed_id_20141211_16h07_rfc_fig_4"></a><p class="title"><strong>Figure <span xmlns="" class="number">144</span>.3 Number of in-use sockets over the time.</strong></p>
<div class="figure-contents">
<div class="mediaobject" align="center"><img src="images/144-LowerAndUpperThreshold.png" align="middle" height="315" alt="Number of in-use sockets over the time." /></div>
</div>
</div><br class="figure-break" /><p>In our example, the lower warning threshold and the lower error
threshold of the Resource Listener are respectively set to 10 and 5. When
the number of in-use sockets decreases under 10, the usage goes from the
<a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceEvent.NORMAL" title="144.22.6.2 public static final int NORMAL = 0">NORMAL</a> state to the <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceEvent.WARNING" title="144.22.6.3 public static final int WARNING = 1">WARNING</a> state and the Resource Listener receives a <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceEvent.WARNING" title="144.22.6.3 public static final int WARNING = 1">WARNING</a> event. If the number of in-use state sockets
decreases again and goes down to 5, the usage goes from the <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceEvent.WARNING" title="144.22.6.3 public static final int WARNING = 1">WARNING</a> state to the <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceEvent.ERROR" title="144.22.6.1 public static final int ERROR = 2">ERROR</a> state and the Resource Listener receives a <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceEvent.ERROR" title="144.22.6.1 public static final int ERROR = 2">ERROR</a> Resource Event.
</p>
<p>The upper threshold is also set. The upper warning threshold and the
upper error threshold are respectively set to 100 and 1000 in-use state
sockets. When the number of sockets reaches 100, the usage goes from the
<a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceEvent.NORMAL" title="144.22.6.2 public static final int NORMAL = 0">NORMAL</a> state to the <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceEvent.WARNING" title="144.22.6.3 public static final int WARNING = 1">WARNING</a> state and the Resource Listener receives a <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceEvent.WARNING" title="144.22.6.3 public static final int WARNING = 1">WARNING</a> Resource Event. If this number is still increasing
and exceeds 1000, then the usage goes from the <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceEvent.WARNING" title="144.22.6.3 public static final int WARNING = 1">WARNING</a> state to the <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceEvent.ERROR" title="144.22.6.1 public static final int ERROR = 2">ERROR</a> state and the Resource Listener receives an <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceEvent.ERROR" title="144.22.6.1 public static final int ERROR = 2">ERROR</a> Resource Event.
</p>
<p>This is a typical use case for a Java Web server. Indeed, one of the
most important quality of service indicator is the number of in-use state
sockets a java web server is handling. A low number of in-use state
sockets may indicate the java web server encounters network problems. On
the contrary, a high number of in-use state socket may be the result of an
external network attack or it could also indicates the java web server is
overused and its administrator should take actions to load-balance the
charge to another java web server instance.
</p>
<p>For other resource types, only upper thresholds may be useful. The
next diagram shows the CPU consumption a Resource Context is using over
the time:
</p>
<div class="figure"><a xmlns="" class="anchor" id="service.resourcemonitoring_bibliomixed_id_20141211_16h08_rfc_fig_5"></a><p class="title"><strong>Figure <span xmlns="" class="number">144</span>.4 CPU consumption (%) over the time – Upper Threshold.</strong></p>
<div class="figure-contents">
<div class="mediaobject" align="center"><img src="images/144-UpperThreshold.png" align="middle" height="315" alt="CPU consumption (%) over the time – Upper Threshold." /></div>
</div>
</div><br class="figure-break" /><p>In this example, only the upper threshold is set. The upper warning
threshold is set to 50%, the error one is set to 75%. CPU consumption
fluctuates between 0 and 50%, the usage is in the <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceEvent.NORMAL" title="144.22.6.2 public static final int NORMAL = 0">NORMAL</a> state. Then it increases and reaches 50%. The
usage then goes from the <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceEvent.NORMAL" title="144.22.6.2 public static final int NORMAL = 0">NORMAL</a> state to the <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceEvent.WARNING" title="144.22.6.3 public static final int WARNING = 1">WARNING</a> state and the Resource Listener holding the
threshold receives a <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceEvent.WARNING" title="144.22.6.3 public static final int WARNING = 1">WARNING</a> Resource Event.
</p>
<p>Afterwards, CPU consumption decreases under 50%; the usage goes from
the <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceEvent.WARNING" title="144.22.6.3 public static final int WARNING = 1">WARNING</a> state to the <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceEvent.NORMAL" title="144.22.6.2 public static final int NORMAL = 0">NORMAL</a> state. The related Resource listener receives a
<a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceEvent.NORMAL" title="144.22.6.2 public static final int NORMAL = 0">NORMAL</a> Resource Event.
</p>
<p>It then increases again and exceeds 50%. The usage goes to the <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceEvent.WARNING" title="144.22.6.3 public static final int WARNING = 1">WARNING</a> state. CPU consumption is still increasing and
exceeds 75%. At this moment, the usage goes from the <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceEvent.WARNING" title="144.22.6.3 public static final int WARNING = 1">WARNING</a> state to the <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceEvent.ERROR" title="144.22.6.1 public static final int ERROR = 2">ERROR</a> state and the related Resource Listener receives
an <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceEvent.ERROR" title="144.22.6.1 public static final int ERROR = 2">ERROR</a> Resource Event.
</p>
<p>After some seconds in the <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceEvent.ERROR" title="144.22.6.1 public static final int ERROR = 2">ERROR</a> state, the Resource Listener implementation stops
the bundle in order to preserve the quality of service.
</p>
<p>The choice of the type of threshold (lower or upper, or both of
them) depends on the type of resource and the needs of the Resource
Monitoring Clients providing the Resource Listener. Other resources like
the free memory may take advantage of a lower threshold.
</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="d0e105183"></a><span xmlns="" class="number">144.16</span> Resource Event
</h2>
</div>
</div>
</div>
<p>A <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceEvent" title="144.22.6 public class ResourceEvent<T>">ResourceEvent</a> instance is an event synchronously sent to a
Resource Listener when one of its thresholds is reached. This event is
notified to a Resource Listener through a call to
ResourceListener.notify(ResourceEvent).
</p>
<p>A Resource Event has a type among the following ones:</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: bullet; ">
<li class="listitem" style="list-style-type: disc">
<p><a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceEvent.ERROR" title="144.22.6.1 public static final int ERROR = 2">ERROR</a> – The resource consumption reaches either the
upper or the lower error threshold of the Resource Listener receiving
this event.
</p>
</li>
<li class="listitem" style="list-style-type: disc">
<p><a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceEvent.WARNING" title="144.22.6.3 public static final int WARNING = 1">WARNING</a> – The resource consumption reaches either the
upper or the lower warning threshold of the Resource Listener
receiving this event.
</p>
</li>
<li class="listitem" style="list-style-type: disc">
<p><a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceEvent.NORMAL" title="144.22.6.2 public static final int NORMAL = 0">NORMAL</a> – The resource consumption is back from
warning or error state to normal state.
</p>
</li>
</ul>
</div>
<p>The Resource Listener instance analyzes this event by calling the
following methods:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: bullet; ">
<li class="listitem" style="list-style-type: disc">
<p><a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceEvent.getValue--" title="144.22.6.8 public Comparable<T> getValue()">getValue()</a> method returns the resource consumption at the
time when the Resource Event instance was generated.
</p>
</li>
<li class="listitem" style="list-style-type: disc">
<p><a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceEvent.isUpperThreshold--" title="144.22.6.10 public boolean isUpperThreshold()">isUpperThreshold()</a> method returns true if the reached threshold
is an upper threshold type. If this method returns false, this is a
lower threshold.
</p>
</li>
<li class="listitem" style="list-style-type: disc">
<p><a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceEvent.getType--" title="144.22.6.7 public int getType()">getType()</a> method indicates the state (WARNING, ERROR, or
NORMAL) of the resource usage.
</p>
</li>
<li class="listitem" style="list-style-type: disc">
<p><a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceEvent.getContext--" title="144.22.6.6 public ResourceContext getContext()">getContext()</a> method returns the Resource Context instance
related to this event. The Resource Listener can use it to retrieve
the Resource Monitor instance. For example,
<code class="code">event.getContext().getMonitor(event.getResourceType())</code>.
</p>
</li>
</ul>
</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="d0e105227"></a><span xmlns="" class="number">144.17</span> Resource Context Listener
</h2>
</div>
</div>
</div>
<p>A <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceContextListener" title="144.22.5 public interface ResourceContextListener">ResourceContextListener</a> instance receives notifications about Resource
Context lifecycle and configuration.
</p>
<p>A notification will be sent when:</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: bullet; ">
<li class="listitem" style="list-style-type: disc">
<p>A Resource Context is created.</p>
</li>
<li class="listitem" style="list-style-type: disc">
<p>A Resource Context is updated, that is, a bundle has been added
or removed from a Resource Context instance.
</p>
</li>
<li class="listitem" style="list-style-type: disc">
<p>A Resource Context is deleted.</p>
</li>
</ul>
</div>
<p>An application which is interested in notifications has to register
a Resource Context Listener instance as an OSGi service. The application
may provide a set of properties at registration time to reduce the number
of notifications a Resource Listener instance will receive. The available
property is:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: bullet; ">
<li class="listitem" style="list-style-type: disc">
<p><a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceContextListener.RESOURCE_CONTEXT" title="144.22.5.1 public static final String RESOURCE_CONTEXT = "resource.context"">RESOURCE_CONTEXT</a> property – An array of String defining the
name of Resource Context instances. If defined, a Resource Listener
instance will only receive notifications related to these specified
Resource Context instances.
</p>
</li>
</ul>
</div>
<p>A Resource Context Listener instance is notified through a call to
<a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceContextListener.notify-ResourceContextEvent-" title="144.22.5.2 public void notify(ResourceContextEvent event)">notify(ResourceContextEvent)</a> method.
</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="d0e105257"></a><span xmlns="" class="number">144.18</span> Resource Context Event
</h2>
</div>
</div>
</div>
<p>A <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceContextEvent" title="144.22.3 public class ResourceContextEvent">ResourceContextEvent</a> instance is an event sent to Resource Context
Listener instances through a call to the <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceContextListener.notify-ResourceContextEvent-" title="144.22.5.2 public void notify(ResourceContextEvent event)">notify(ResourceContextEvent)</a> method.
</p>
<p>A Resource Context Event has a type among the four following
ones:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: bullet; ">
<li class="listitem" style="list-style-type: disc">
<p><a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceContextEvent.RESOURCE_CONTEXT_CREATED" title="144.22.3.3 public static final int RESOURCE_CONTEXT_CREATED = 0">RESOURCE_CONTEXT_CREATED</a> – A new Resource Context instance has been
created.
</p>
</li>
<li class="listitem" style="list-style-type: disc">
<p><a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceContextEvent.RESOURCE_CONTEXT_REMOVED" title="144.22.3.4 public static final int RESOURCE_CONTEXT_REMOVED = 1">RESOURCE_CONTEXT_REMOVED</a> – A Resource Context instance has been
deleted.
</p>
</li>
<li class="listitem" style="list-style-type: disc">
<p><a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceContextEvent.BUNDLE_ADDED" title="144.22.3.1 public static final int BUNDLE_ADDED = 2">BUNDLE_ADDED</a> – A bundle has been added in the scope of a
Resource Context instance.
</p>
</li>
<li class="listitem" style="list-style-type: disc">
<p><a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceContextEvent.BUNDLE_REMOVED" title="144.22.3.2 public static final int BUNDLE_REMOVED = 3">BUNDLE_REMOVED</a> – A bundle has been removed from the scope of
a Resource Context instance.
</p>
</li>
</ul>
</div>
<p>In the case of a <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceContextEvent.RESOURCE_CONTEXT_CREATED" title="144.22.3.3 public static final int RESOURCE_CONTEXT_CREATED = 0">RESOURCE_CONTEXT_CREATED</a> event or a <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceContextEvent.RESOURCE_CONTEXT_REMOVED" title="144.22.3.4 public static final int RESOURCE_CONTEXT_REMOVED = 1">RESOURCE_CONTEXT_REMOVED</a> event, a call to <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceContextEvent.getContext--" title="144.22.3.9 public ResourceContext getContext()">getContext()</a> returns the targeted Resource Context
instance.
</p>
<p>In the case of a <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceContextEvent.BUNDLE_ADDED" title="144.22.3.1 public static final int BUNDLE_ADDED = 2">BUNDLE_ADDED</a> type or <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceContextEvent.BUNDLE_REMOVED" title="144.22.3.2 public static final int BUNDLE_REMOVED = 3">BUNDLE_REMOVED</a> type, <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceContextEvent.getBundleId--" title="144.22.3.8 public long getBundleId()">getBundleId()</a> returns the id of the bundle to be added to or
removed from. The related Resource Context instance is given by a call to
<a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceContextEvent.getContext--" title="144.22.3.9 public ResourceContext getContext()">getContext()</a>.
</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="d0e105303"></a><span xmlns="" class="number">144.19</span> Resource Monitoring Service
</h2>
</div>
</div>
</div>
<p>The <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceMonitoringService" title="144.22.11 public interface ResourceMonitoringService">ResourceMonitoringService</a> manages the Resource Context instances. The
Resource Monitoring Service is available through the OSGi service
registry.
</p>
<p>This service holds the existing Resource Context instances. Resource
Context instances are created by calling the <a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceMonitoringService.createContext-String-ResourceContext-" title="144.22.11.8 public ResourceContext createContext(String name, ResourceContext template)">createContext(String,ResourceContext)</a> method. The caller provides a context name as a
string and optionally a template as a ResourceContext object.
</p>
<p>The list of existing Resource Context instances can be retrieved
through the following methods:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: bullet; ">
<li class="listitem" style="list-style-type: disc">
<p><a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceMonitoringService.getContext-String-" title="144.22.11.9 public ResourceContext getContext(String name)">getContext(String)</a> – returns the ResourceContext with the
specified resource context name.
</p>
</li>
<li class="listitem" style="list-style-type: disc">
<p><a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceMonitoringService.getContext-long-" title="144.22.11.10 public ResourceContext getContext(long bundleId)">getContext(long)</a> – returns the ResourceContext associated to
the provided bundle id.
</p>
</li>
<li class="listitem" style="list-style-type: disc">
<p><a xmlns="" class="xref" href="service.resourcemonitoring.html#org.osgi.service.resourcemonitoring.ResourceMonitoringService.listContext--" title="144.22.11.12 public ResourceContext[] listContext()">listContext()</a> – retrieve all existing Resource Context
instances as an array.
</p>
</li>
</ul>
</div>
<p>The Resource Monitoring Service singleton manages the persistence of
the Resource Context instances. The following properties are
stored:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: bullet; ">
<li class="listitem" style="list-style-type: disc">
<p>name of the Resource Context.</p>
</li>
<li class="listitem" style="list-style-type: disc">
<p>list of the bundles belonging to the Resource Context.</p>
</li>
<li class="listitem" style="list-style-type: disc">
<p>list of the Resource Monitor instances. For each one: the
sampling period, and the monitoring period.
</p>
</li>
</ul>
</div>
<p>The way the Resource Monitoring Service persists the Resource
Context instances is implementation specific. The implementer is free to
use any file format and file location it wants. At startup, the Resource
Monitoring Service will load the persisted Resource Context instances to
restore the state prior to shutdown.
</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="d0e105343"></a><span xmlns="" class="number">144.20</span> Resource Monitoring Client
</h2>
</div>
</div>
</div>
<p>A Resource Monitoring Client uses the Resource Monitoring Service
singleton instance to apply Resource Monitoring policies. These entities
MAY:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: bullet; ">
<li class="listitem" style="list-style-type: disc">