-
Notifications
You must be signed in to change notification settings - Fork 8
/
util.xml.html
4404 lines (4364 loc) · 579 KB
/
util.xml.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>702 XML Parser Service Specification - OSGi Compendium 7</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.78.1" />
<link rel="home" href="toc.html" title="OSGi Compendium" />
<link rel="up" href="toc.html" title="OSGi Compendium" />
<link rel="prev" href="service.jaxrs.html" title="151 JAX-RS Whiteboard Specification" />
<link rel="next" href="util.position.html" title="703 Position Specification" />
<meta name="Section-title" content="702 XML Parser Service 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/logo.svg" alt="OSGi Alliance Documentation" /><h1>OSGi Compendium Release 7</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.jaxrs.html">Prev</a>
</td>
<th width="60%" align="center"> </th>
<td width="20%" align="right"> <a accesskey="n" href="util.position.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="util.xml"></a><span xmlns="" class="number">702</span> XML Parser Service Specification
</h1>
</div>
<div>
<p xmlns="http://www.w3.org/1999/xhtml" class="releaseinfo"><a xmlns="" class="xref" href="util.xml.html#org.osgi.util.xml" title="702.9 org.osgi.util.xml">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="d0e136535"></a><span xmlns="" class="number">702.1</span> Introduction
</h2>
</div>
</div>
</div>
<p>The Extensible Markup Language (XML) has become a popular method of
describing data. As more bundles use XML to describe their data, a common
XML Parser becomes necessary in an embedded environment in order to reduce
the need for space. Not all XML Parsers are equivalent in function,
however, and not all bundles have the same requirements on an XML
parser.
</p>
<p>This problem was addressed in the Java API for XML Processing, see
<a xmlns="" class="xref" href="util.xml.html#i1255594" title="JAXP">[4] <em>JAXP</em></a> for Java 2 Standard Edition and Enterprise
Edition. This specification addresses how the classes defined in JAXP can
be used in an OSGi framework. It defines how:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<p>Implementations of XML parsers can become available to other
bundles
</p>
</li>
<li class="listitem">
<p>Bundles can find a suitable parser</p>
</li>
<li class="listitem">
<p>A standard parser in a JAR can be transformed to a bundle</p>
</li>
</ul>
</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="d0e136554"></a><span xmlns="" class="number">702.1.1</span> Essentials
</h3>
</div>
</div>
</div>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<p><span class="emphasis"><em>Standards</em></span> - Leverage existing standards
in Java based XML parsing: JAXP, SAX and DOM
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>Unmodified JAXP code</em></span> - Run unmodified
JAXP code
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>Simple</em></span> - It should be easy to provide a
SAX or DOM parser as well as easy to find a matching parser
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>Multiple</em></span> - It should be possible to have
multiple implementations of parsers available
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>Extendable</em></span> - It is likely that parsers
will be extended in the future with more functionality
</p>
</li>
</ul>
</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="d0e136583"></a><span xmlns="" class="number">702.1.2</span> Entities
</h3>
</div>
</div>
</div>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<p><span class="emphasis"><em>XMLParserActivator</em></span> - A utility class that
registers a parser factory from declarative information in the
Manifest file.
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>SAXParserFactory</em></span> - A class that can
create an instance of a <code class="code">SAXParser</code> class.
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>DocumentBuilderFactory</em></span> - A class that can
create an instance of a <code class="code">DocumentBuilder</code> class.
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>SAXParser</em></span> - A parser, instantiated by a
<code class="code">SaxParserFactory</code> object, that parses according to the
SAX specifications.
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>DocumentBuilder</em></span> - A parser, instantiated
by a <code class="code">DocumentBuilderFactory</code>, that parses according to
the DOM specifications.
</p>
</li>
</ul>
</div>
<div class="figure"><a xmlns="" class="anchor" id="d0e136624"></a><p class="title"><strong>Figure <span xmlns="" class="number">702</span>.1 XML Parsing diagram</strong></p>
<div class="figure-contents">
<div class="mediaobject" align="center"><img src="images/702-xml-classes.png" align="middle" width="446" height="310" alt="XML Parsing diagram" /></div>
</div>
</div><br class="figure-break" /></div>
<div class="section">
<div xmlns="" class="titlepage">
<div>
<div>
<h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a xmlns="" class="anchor" id="d0e136630"></a><span xmlns="" class="number">702.1.3</span> Operations
</h3>
</div>
</div>
</div>
<p>A bundle containing a SAX or DOM parser is started. This bundle
registers a <code class="code">SAXParserFactory</code> and/or a
<code class="code">DocumentBuilderFactory</code> service object with the Framework.
Service registration properties describe the features of the parsers to
other bundles. A bundle that needs an XML parser will get a
<code class="code">SAXParserFactory</code> or <code class="code">DocumentBuilderFactory</code>
service object from the Framework service registry. This object is then
used to instantiate the requested parsers according to their
specifications.
</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="d0e136647"></a><span xmlns="" class="number">702.2</span> JAXP
</h2>
</div>
</div>
</div>
<p>XML has become very popular in the last few years because it allows
the interchange of complex information between different parties. Though
only a single XML standard exists, there are multiple APIs to XML parsers,
primarily of two types:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<p>The Simple API for XML (SAX1 and SAX2)</p>
</li>
<li class="listitem">
<p>Based on the Document Object Model (DOM 1 and 2)</p>
</li>
</ul>
</div>
<p>Both standards, however, define an abstract API that can be
implemented by different vendors.
</p>
<p>A given XML Parser implementation may support either or both of
these parser types by implementing the <code class="code">org.w3c.dom</code> and/or
<code class="code">org.xml.sax</code> packages. In addition, parsers have
characteristics such as whether they are validating or non-validating
parsers and whether or not they are name-space aware.
</p>
<p>An application which uses a specific XML Parser must code to that
specific parser and become coupled to that specific implementation. If the
parser has implemented <a xmlns="" class="xref" href="util.xml.html#i1255594" title="JAXP">[4] <em>JAXP</em></a>, however, the
application developer can code against SAX or DOM and let the runtime
environment decide which parser implementation is used.
</p>
<p>JAXP uses the concept of a <span class="emphasis"><em>factory</em></span>. A factory
object is an object that abstracts the creation of another object. JAXP
defines a <code class="code">DocumentBuilderFactory</code> and a
<code class="code">SAXParserFactory</code> class for this purpose.
</p>
<p>JAXP is implemented in the <code class="code">javax.xml.parsers</code> package
and provides an abstraction layer between an application and a specific
XML Parser implementation. Using JAXP, applications can choose to use any
JAXP compliant parser without changing any code, simply by changing a
System property which specifies the SAX- and DOM factory class
names.
</p>
<p>In JAXP, the default factory is obtained with a static method in the
<code class="code">SAXParserFactory</code> or <code class="code">DocumentBuilderFactory</code>
class. This method will inspect the associated System property and create
a new instance of that class.
</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="d0e136697"></a><span xmlns="" class="number">702.3</span> XML Parser service
</h2>
</div>
</div>
</div>
<p>The current specification of JAXP has the limitation that only one
of each type of parser factories can be registered. This specification
specifies how multiple <code class="code">SAXParserFactory</code> objects and
<code class="code">DocumentBuilderFactory</code> objects can be made available to
bundles simultaneously.
</p>
<p>Providers of parsers should register a JAXP factory object with the
OSGi service registry under the factory class name. Service properties are
used to describe whether the parser:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<p>Is validating</p>
</li>
<li class="listitem">
<p>Is name-space aware</p>
</li>
<li class="listitem">
<p>Has additional features</p>
</li>
</ul>
</div>
<p>With this functionality, bundles can query the OSGi service registry
for parsers supporting the specific functionality that they
require.
</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="i1259424"></a><span xmlns="" class="number">702.4</span> Properties
</h2>
</div>
</div>
</div>
<p>Parsers must be registered with a number of properties that qualify
the service. In this specification, the following properties are
specified:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<p><a xmlns="" class="xref" href="util.xml.html#org.osgi.util.xml.XMLParserActivator.PARSER_NAMESPACEAWARE" title="702.9.2.3 public static final String PARSER_NAMESPACEAWARE = "parser.namespaceAware"">PARSER_NAMESPACEAWARE</a> - The registered parser is aware of
name-spaces. Name-spaces allow an XML document to consist of
independently developed DTDs. In an XML document, they are recognized
by the <code class="code">xmlns</code> attribute and names prefixed with an
abbreviated name-space identifier, like: <code class="code"><xsl:if
...></code>. The type is a <code class="code">Boolean</code> object that must be
<code class="code">true</code> when the parser supports name-spaces. All other
values, or the absence of the property, indicate that the parser does
not implement name-spaces.
</p>
</li>
<li class="listitem">
<p><a xmlns="" class="xref" href="util.xml.html#org.osgi.util.xml.XMLParserActivator.PARSER_VALIDATING" title="702.9.2.4 public static final String PARSER_VALIDATING = "parser.validating"">PARSER_VALIDATING</a> - The registered parser can read the DTD and
can validate the XML accordingly. The type is a <code class="code">Boolean</code>
object that must <code class="code">true</code> when the parser is validating. All
other values, or the absence of the property, indicate that the parser
does not validate.
</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="d0e136754"></a><span xmlns="" class="number">702.5</span> Getting a Parser Factory
</h2>
</div>
</div>
</div>
<p>Getting a parser factory requires a bundle to get the appropriate
factory from the service registry. In a simple case in which a
non-validating, non-name-space aware parser would suffice, it is best to
use <code class="code">getServiceReference(String)</code>.
</p><pre xmlns="" class="programlisting"><code>DocumentBuilder getParser(BundleContext context)
throws Exception {
ServiceReference ref = context.getServiceReference(
DocumentBuilderFactory.class.getName() );
if ( ref == null )
return null;
DocumentBuilderFactory factory =
(DocumentBuilderFactory) context.getService(ref);
return factory.newDocumentBuilder();
}</code></pre><p>In a more demanding case, the filtered version allows the bundle to
select a parser that is validating and name-space aware:
</p><pre xmlns="" class="programlisting"><code>SAXParser getParser(BundleContext context)
throws Exception {
ServiceReference refs[] = context.getServiceReferences(
SAXParserFactory.class.getName(),
"(&(parser.namespaceAware=true)"
+ "(parser.validating=true))" );
if ( refs == null )
return null;
SAXParserFactory factory =
(SAXParserFactory) context.getService(refs[O]);
return factory.newSAXParser();
}</code></pre></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="d0e136768"></a><span xmlns="" class="number">702.6</span> Adapting a JAXP Parser to OSGi
</h2>
</div>
</div>
</div>
<p>If an XML Parser supports JAXP, then it can be converted to an OSGi
aware bundle by adding a <code class="code">BundleActivator</code> class which
registers an XML Parser Service. The utility
<code class="code">org.osgi.util.xml.XMLParserActivator</code> class provides this
function and can be added (copied, not referenced) to any XML Parser
bundle, or it can be extended and customized if desired.
</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="d0e136779"></a><span xmlns="" class="number">702.6.1</span> JAR Based Services
</h3>
</div>
</div>
</div>
<p>Its functionality is based on the definition of the <a xmlns="" class="xref" href="util.xml.html#i1267674" title="JAR File specification, services directory">[5] <em>JAR File specification, services directory</em></a>. This specification defines a concept for service
providers. A JAR file can contain an implementation of an abstractly
defined service. The class (or classes) implementing the service are
designated from a file in the <code class="code">META-INF/services</code> directory.
The name of this file is the same as the abstract service class.
</p>
<p>The content of the UTF-8 encoded file is a list of class names
separated by new lines. White space is ignored and the number sign
(<code class="code">'#' \u0023</code>) is the comment character.
</p>
<p>JAXP uses this service provider mechanism. It is therefore likely
that vendors will place these service files in the
<code class="code">META-INF/services</code> directory.
</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="d0e136799"></a><span xmlns="" class="number">702.6.2</span> XMLParserActivator
</h3>
</div>
</div>
</div>
<p>To support this mechanism, the XML Parser service provides a
utility class that should be normally delivered with the OSGi framework
implementation. This class is a Bundle Activator and must start when the
bundle is started. This class is copied into the parser bundle, and
<span class="emphasis"><em>not</em></span> imported.
</p>
<p>The <code class="code">start</code> method of the utility
<code class="code">BundleActivator</code> class will look in the
<code class="code">META-INF/services</code> service provider directory for the files
<code class="code">javax.xml.parsers.SAXParserFactory (</code> <a xmlns="" class="xref" href="util.xml.html#org.osgi.util.xml.XMLParserActivator.SAXFACTORYNAME" title="702.9.2.6 public static final String SAXFACTORYNAME = "javax.xml.parsers.SAXParserFactory"">SAXFACTORYNAME</a> ) or
<code class="code">javax.xml.parsers.DocumentBuilderFactory (</code> <a xmlns="" class="xref" href="util.xml.html#org.osgi.util.xml.XMLParserActivator.DOMFACTORYNAME" title="702.9.2.2 public static final String DOMFACTORYNAME = "javax.xml.parsers.DocumentBuilderFactory"">DOMFACTORYNAME</a> ). The full path name is specified in the
constants <a xmlns="" class="xref" href="util.xml.html#org.osgi.util.xml.XMLParserActivator.SAXCLASSFILE" title="702.9.2.5 public static final String SAXCLASSFILE = "/META-INF/services/javax.xml.parsers.SAXParserFactory"">SAXCLASSFILE</a> and <a xmlns="" class="xref" href="util.xml.html#org.osgi.util.xml.XMLParserActivator.DOMCLASSFILE" title="702.9.2.1 public static final String DOMCLASSFILE = "/META-INF/services/javax.xml.parsers.DocumentBuilderFactory"">DOMCLASSFILE</a> respectively.
</p>
<p>If either of these files exist, the utility
<code class="code">BundleActivator</code> class will parse the contents according to
the specification. A service provider file can contain multiple class
names. Each name is read and a new instance is created. The following
example shows the possible content of such a file:
</p><pre xmlns="" class="programlisting"><code># ACME example SAXParserFactory file
com.acme.saxparser.SAXParserFast # Fast
com.acme.saxparser.SAXParserValidating # Validates</code></pre><p>Both the <code class="code">javax.xml.parsers.SAXParserFactory</code> and the
<code class="code">javax.xml.parsers.DocumentBuilderFactory</code> provide methods
that describe the features of the parsers they can create. The
<code class="code">XMLParserActivator</code> activator will use these methods to set
the values of the properties, as defined in <a xmlns="" class="xref" href="util.xml.html#i1259424" title="702.4 Properties">Properties</a>,
that describe the instances.
</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="d0e136852"></a><span xmlns="" class="number">702.6.3</span> Adapting an Existing JAXP Compatible Parser
</h3>
</div>
</div>
</div>
<p>To incorporate this bundle activator into a XML Parser Bundle, do
the following:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<p>If SAX parsing is supported, create a
<code class="code">/META-INF/services/javax.xml.parsers.SAXParserFactory</code>
resource file containing the class names of the
<code class="code">SAXParserFactory</code> classes.
</p>
</li>
<li class="listitem">
<p>If DOM parsing is supported, create a
<code class="code">/META-INF/services/javax.xml.parsers.DocumentBuilderFactory</code>
file containing the fully qualified class names of the
<code class="code">DocumentBuilderFactory</code> classes.
</p>
</li>
<li class="listitem">
<p>Create manifest file which imports the packages
<code class="code">org.w3c.dom</code>, <code class="code">org.xml.sax</code>, and
<code class="code">javax.xml.parsers</code>.
</p>
</li>
<li class="listitem">
<p>Add a Bundle-Activator header to the manifest pointing to the
<code class="code">XMLParserActivator</code>, the sub-class that was created, or
a fully custom one.
</p>
</li>
<li class="listitem">
<p>If the parsers support attributes, properties, or features
that should be registered as properties so they can be searched,
extend the <code class="code">XMLParserActivator</code> class and override <a xmlns="" class="xref" href="util.xml.html#org.osgi.util.xml.XMLParserActivator.setSAXProperties-javax.xml.parsers.SAXParserFactory-Hashtable-" title="702.9.2.10 public void setSAXProperties(SAXParserFactory factory, Hashtable<String, Object> properties)">setSAXProperties(javax.xml.parsers.SAXParserFactory,Hashtable)</a> and <a xmlns="" class="xref" href="util.xml.html#org.osgi.util.xml.XMLParserActivator.setDOMProperties-javax.xml.parsers.DocumentBuilderFactory-Hashtable-" title="702.9.2.9 public void setDOMProperties(DocumentBuilderFactory factory, Hashtable<String, Object> props)">setDOMProperties(javax.xml.parsers.DocumentBuilderFactory,Hashtable)</a>.
</p>
</li>
<li class="listitem">
<p>Ensure that custom properties are put into the
<code class="code">Hashtable</code> object. JAXP does not provide a way for
<code class="code">XMLParserActivator</code> to query the parser to find out what
properties were added.
</p>
</li>
<li class="listitem">
<p>Bundles that extend the <code class="code">XMLParserActivator</code> class
must call the original methods via super to correctly initialize the
XML Parser Service properties.
</p>
</li>
<li class="listitem">
<p>Compile this class into the bundle.</p>
</li>
<li class="listitem">
<p>Install the new XML Parser Service bundle.</p>
</li>
<li class="listitem">
<p>Ensure that the
<code class="code">org.osgi.util.xml.XMLParserActivator</code> class is contained
in the bundle.
</p>
</li>
</ul>
</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="d0e136931"></a><span xmlns="" class="number">702.7</span> Usage of JAXP
</h2>
</div>
</div>
</div>
<p>A single bundle should export the JAXP, SAX, and DOM APIs. The
version of contained packages must be appropriately labeled. JAXP 1.1 or
later is required which references SAX 2 and DOM 2. See <a xmlns="" class="xref" href="util.xml.html#i1255594" title="JAXP">[4] <em>JAXP</em></a> for the exact version dependencies.
</p>
<p>This specification is related to related packages as defined in the
JAXP 1.1 document. The following table contains the expected minimum
versions.
</p>
<div class="table"><a xmlns="" class="anchor" id="d0e136940"></a><p class="title"><strong>Table <span xmlns="" class="number">702</span>.1 JAXP 1.1 minimum package versions</strong></p>
<div class="table-contents">
<table summary="JAXP 1.1 minimum package versions" 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 />
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">Package</th>
<th style="border-bottom: 0.5pt solid ; ">Minimum Version</th>
</tr>
</thead>
<tbody>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">
<p>javax.xml.parsers</p>
</td>
<td style="border-bottom: 0.5pt solid ; ">
<p>1.1</p>
</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">
<p>org.xml.sax</p>
</td>
<td style="border-bottom: 0.5pt solid ; ">
<p>2.0</p>
</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">
<p>org.xml.sax.helpers</p>
</td>
<td style="border-bottom: 0.5pt solid ; ">
<p>2.0</p>
</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">
<p>org.xsml.sax.ext</p>
</td>
<td style="border-bottom: 0.5pt solid ; ">
<p>1.0</p>
</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; ">
<p>org.w3c.dom</p>
</td>
<td style="">
<p>2.0</p>
</td>
</tr>
</tbody>
</table>
</div>
</div><br class="table-break" /><p>The Xerces project from the Apache group, <a xmlns="" class="xref" href="util.xml.html#i1286146" title="Xerces 2 Java Parser">[6] <em>Xerces 2 Java Parser</em></a>, contains a number libraries that implement the
necessary APIs. These libraries can be wrapped in a bundle to provide the
relevant packages.
</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="d0e136990"></a><span xmlns="" class="number">702.8</span> Security
</h2>
</div>
</div>
</div>
<p>A centralized XML parser is likely to see sensitive information from
other bundles. Provisioning an XML parser should therefore be limited to
trusted bundles. This security can be achieved by providing
<code class="code">ServicePermission[javax.xml.parsers.DocumentBuilderFactory</code> |
<code class="code">javax.xml.parsers.SAXFactory,REGISTER]</code> to only trusted
bundles.
</p>
<p>Using an XML parser is a common function, and
<code class="code">ServicePermission[javax.xml.parsers.DOMParserFactory</code> |
<code class="code">javax.xml.parsers.SAXFactory, GET]</code> should not be
restricted.
</p>
<p>The XML parser bundle will need <code class="code">FilePermission[<<ALL
FILES>>,READ]</code> for parsing of files because it is not known
beforehand where those files will be located. This requirement further
implies that the XML parser is a system bundle that must be fully
trusted.
</p>
</div>
<div class="section package">
<div xmlns="" class="titlepage">
<div>
<div>
<h2 xmlns="http://www.w3.org/1999/xhtml" class="title" style="clear: both"><a xmlns="" class="anchor" id="org.osgi.util.xml"></a><span xmlns="" class="number">702.9</span> org.osgi.util.xml
</h2>
</div>
<div>
<p xmlns="http://www.w3.org/1999/xhtml" class="releaseinfo">Version 1.0</p>
</div>
</div>
</div>
<p>
XML Parser Package Version 1.0.
</p>
<p>
Bundles wishing to use this package must list the package in the
Import-Package header of the bundle's manifest.
</p>
<p>
Example import for consumers using the API in this package:
</p>
<p>
<code class="code">Import-Package: org.osgi.util.xml; version="[1.0,2.0)"</code>
</p>
<div class="section summary">
<div xmlns="" class="titlepage">
<div>
<div>
<h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a xmlns="" class="anchor" id="d0e137033"></a><span xmlns="" class="number">702.9.1</span> Summary
</h3>
</div>
</div>
</div>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<p>
<a xmlns="" class="link" href="util.xml.html#org.osgi.util.xml.XMLParserActivator" title="702.9.2 public class XMLParserActivator implements BundleActivator, ServiceFactory<Object>">
<code xmlns="http://www.w3.org/1999/xhtml" class="code">XMLParserActivator</code>
</a> -
A BundleActivator class that allows any JAXP compliant XML Parser to register
itself as an OSGi parser service.
</p>
</li>
</ul>
</div>
</div>
<div class="section class">
<div xmlns="" class="titlepage">
<div>
<div>
<h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a xmlns="" class="anchor" id="org.osgi.util.xml.XMLParserActivator"></a><span xmlns="" class="number">702.9.2</span> public class XMLParserActivator<br xmlns="" /> implements BundleActivator, ServiceFactory<Object>
</h3>
</div>
</div>
</div>
<p>
A BundleActivator class that allows any JAXP compliant XML Parser to register
itself as an OSGi parser service.
Multiple JAXP compliant parsers can concurrently register by using this
BundleActivator class. Bundles who wish to use an XML parser can then use the
framework's service registry to locate available XML Parsers with the desired
characteristics such as validating and namespace-aware.
</p>
<p>
The services that this bundle activator enables a bundle to provide are:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<p>
<code class="code">javax.xml.parsers.SAXParserFactory</code>(<a xmlns="" class="link" href="util.xml.html#org.osgi.util.xml.XMLParserActivator.SAXFACTORYNAME" title="702.9.2.6 public static final String SAXFACTORYNAME = "javax.xml.parsers.SAXParserFactory"">SAXFACTORYNAME</a>)
</p>
</li>
<li class="listitem">
<p>
<code class="code">javax.xml.parsers.DocumentBuilderFactory</code>( <a xmlns="" class="link" href="util.xml.html#org.osgi.util.xml.XMLParserActivator.DOMFACTORYNAME" title="702.9.2.2 public static final String DOMFACTORYNAME = "javax.xml.parsers.DocumentBuilderFactory"">DOMFACTORYNAME</a>
)
</p>
</li>
</ul>
</div>
<p>
The algorithm to find the implementations of the abstract parsers is derived
from the JAR file specifications, specifically the Services API.
</p>
<p>
An XMLParserActivator assumes that it can find the class file names of the
factory classes in the following files:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<p>
<code class="code">/META-INF/services/javax.xml.parsers.SAXParserFactory</code> is a file
contained in a jar available to the runtime which contains the implementation
class name(s) of the SAXParserFactory.
</p>
</li>
<li class="listitem">
<p>
<code class="code">/META-INF/services/javax.xml.parsers.DocumentBuilderFactory</code> is a
file contained in a jar available to the runtime which contains the
implementation class name(s) of the <code class="code">DocumentBuilderFactory</code>
</p>
</li>
</ul>
</div>
<p>
If either of the files does not exist, <code class="code">XMLParserActivator</code> assumes
that the parser does not support that parser type.
</p>
<p>
<code class="code">XMLParserActivator</code> attempts to instantiate both the
<code class="code">SAXParserFactory</code> and the <code class="code">DocumentBuilderFactory</code>. It registers
each factory with the framework along with service properties:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<p>
<a xmlns="" class="link" href="util.xml.html#org.osgi.util.xml.XMLParserActivator.PARSER_VALIDATING" title="702.9.2.4 public static final String PARSER_VALIDATING = "parser.validating"">PARSER_VALIDATING</a>- indicates if this factory supports validating
parsers. It's value is a <code class="code">Boolean</code>.
</p>
</li>
<li class="listitem">
<p>
<a xmlns="" class="link" href="util.xml.html#org.osgi.util.xml.XMLParserActivator.PARSER_NAMESPACEAWARE" title="702.9.2.3 public static final String PARSER_NAMESPACEAWARE = "parser.namespaceAware"">PARSER_NAMESPACEAWARE</a>- indicates if this factory supports
namespace aware parsers It's value is a <code class="code">Boolean</code>.
</p>
</li>
</ul>
</div>
<p>
Individual parser implementations may have additional features, properties,
or attributes which could be used to select a parser with a filter. These can
be added by extending this class and overriding the <code class="code">setSAXProperties</code>
and <code class="code">setDOMProperties</code> methods.
</p>
<p xmlns="" class="parameter"><label>Concurrency</label><span>Thread-safe </span></p>
<div class="section field">
<div xmlns="" class="titlepage">
<div>
<div>
<h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a xmlns="" class="anchor" id="org.osgi.util.xml.XMLParserActivator.DOMCLASSFILE"></a><span xmlns="" class="number">702.9.2.1</span> public static final String DOMCLASSFILE = "/META-INF/services/javax.xml.parsers.DocumentBuilderFactory"
</h4>
</div>
</div>
</div>
<p>
Fully qualified path name of DOM Parser Factory Class Name file
</p>
</div>
<div class="section field">
<div xmlns="" class="titlepage">
<div>
<div>
<h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a xmlns="" class="anchor" id="org.osgi.util.xml.XMLParserActivator.DOMFACTORYNAME"></a><span xmlns="" class="number">702.9.2.2</span> public static final String DOMFACTORYNAME = "javax.xml.parsers.DocumentBuilderFactory"
</h4>
</div>
</div>
</div>
<p>
Filename containing the DOM Parser Factory Class name. Also used as the
basis for the <code class="code">SERVICE_PID</code> registration property.
</p>
</div>
<div class="section field">
<div xmlns="" class="titlepage">
<div>
<div>
<h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a xmlns="" class="anchor" id="org.osgi.util.xml.XMLParserActivator.PARSER_NAMESPACEAWARE"></a><span xmlns="" class="number">702.9.2.3</span> public static final String PARSER_NAMESPACEAWARE = "parser.namespaceAware"
</h4>
</div>
</div>
</div>
<p>
Service property specifying if factory is configured to support namespace
aware parsers. The value is of type <code class="code">Boolean</code>.
</p>
</div>
<div class="section field">
<div xmlns="" class="titlepage">
<div>
<div>
<h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a xmlns="" class="anchor" id="org.osgi.util.xml.XMLParserActivator.PARSER_VALIDATING"></a><span xmlns="" class="number">702.9.2.4</span> public static final String PARSER_VALIDATING = "parser.validating"
</h4>
</div>
</div>
</div>
<p>
Service property specifying if factory is configured to support
validating parsers. The value is of type <code class="code">Boolean</code>.
</p>
</div>
<div class="section field">
<div xmlns="" class="titlepage">
<div>
<div>
<h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a xmlns="" class="anchor" id="org.osgi.util.xml.XMLParserActivator.SAXCLASSFILE"></a><span xmlns="" class="number">702.9.2.5</span> public static final String SAXCLASSFILE = "/META-INF/services/javax.xml.parsers.SAXParserFactory"
</h4>
</div>
</div>
</div>
<p>
Fully qualified path name of SAX Parser Factory Class Name file
</p>
</div>
<div class="section field">
<div xmlns="" class="titlepage">
<div>
<div>
<h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a xmlns="" class="anchor" id="org.osgi.util.xml.XMLParserActivator.SAXFACTORYNAME"></a><span xmlns="" class="number">702.9.2.6</span> public static final String SAXFACTORYNAME = "javax.xml.parsers.SAXParserFactory"
</h4>
</div>
</div>
</div>
<p>
Filename containing the SAX Parser Factory Class name. Also used as the
basis for the <code class="code">SERVICE_PID</code> registration property.
</p>
</div>
<div class="section method">
<div xmlns="" class="titlepage">
<div>
<div>
<h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a xmlns="" class="anchor" id="org.osgi.util.xml.XMLParserActivator.XMLParserActivator--"></a><span xmlns="" class="number">702.9.2.7</span> public XMLParserActivator()
</h4>
</div>
</div>
</div>
<p></p>
</div>
<div class="section method">
<div xmlns="" class="titlepage">
<div>
<div>
<h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a xmlns="" class="anchor" id="org.osgi.util.xml.XMLParserActivator.getService-Bundle-ServiceRegistration-"></a><span xmlns="" class="number">702.9.2.8</span> public Object getService(Bundle bundle, ServiceRegistration<Object> registration)
</h4>
</div>
</div>
</div>
<p xmlns="" class="parameter"><label>bundle</label><span>The bundle using the service.</span></p>
<p xmlns="" class="parameter"><label>registration</label><span>The <code xmlns="http://www.w3.org/1999/xhtml" class="code">ServiceRegistration</code> object for the
service.</span></p>
<p xmlns="" class="description"><label>□</label><span>
Creates a new XML Parser Factory object.
</span></p>
<p>
A unique XML Parser Factory object is returned for each call to this
method.
</p>
<p>
The returned XML Parser Factory object will be configured for validating
and namespace aware support as specified in the service properties of the
specified ServiceRegistration object.
This method can be overridden to configure additional features in the
returned XML Parser Factory object.
</p>
<p xmlns="" class="parameter"><label>Returns</label><span>A new, configured XML Parser Factory object or null if a
configuration error was encountered</span></p>
<p></p>
</div>
<div class="section method">
<div xmlns="" class="titlepage">
<div>
<div>
<h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a xmlns="" class="anchor" id="org.osgi.util.xml.XMLParserActivator.setDOMProperties-javax.xml.parsers.DocumentBuilderFactory-Hashtable-"></a><span xmlns="" class="number">702.9.2.9</span> public void setDOMProperties(DocumentBuilderFactory factory, Hashtable<String, Object> props)
</h4>
</div>
</div>
</div>
<p xmlns="" class="parameter"><label>factory</label><span>- the DocumentBuilderFactory object</span></p>
<p xmlns="" class="parameter"><label>props</label><span>- Hashtable of service properties.</span></p>
<p>
Set the customizable DOM Parser Service Properties.
</p>
<p>
This method attempts to instantiate a validating parser and a namespace
aware parser to determine if the parser can support those features. The
appropriate properties are then set in the specified props object.
</p>
<p>
This method can be overridden to add additional DOM2 features and
properties. If you want to be able to filter searches of the OSGi service
registry, this method must put a key, value pair into the properties
object for each feature or property. For example,
properties.put("http://www.acme.com/features/foo", Boolean.TRUE);
</p>
</div>
<div class="section method">
<div xmlns="" class="titlepage">
<div>
<div>
<h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a xmlns="" class="anchor" id="org.osgi.util.xml.XMLParserActivator.setSAXProperties-javax.xml.parsers.SAXParserFactory-Hashtable-"></a><span xmlns="" class="number">702.9.2.10</span> public void setSAXProperties(SAXParserFactory factory, Hashtable<String, Object> properties)
</h4>
</div>
</div>
</div>
<p xmlns="" class="parameter"><label>factory</label><span>- the SAXParserFactory object</span></p>
<p xmlns="" class="parameter"><label>properties</label><span>- the properties object for the service</span></p>
<p>
Set the customizable SAX Parser Service Properties.
</p>
<p>
This method attempts to instantiate a validating parser and a namespace
aware parser to determine if the parser can support those features. The
appropriate properties are then set in the specified properties object.
</p>
<p>
This method can be overridden to add additional SAX2 features and
properties. If you want to be able to filter searches of the OSGi service
registry, this method must put a key, value pair into the properties
object for each feature or property. For example,
properties.put("http://www.acme.com/features/foo", Boolean.TRUE);
</p>
</div>
<div class="section method">
<div xmlns="" class="titlepage">
<div>
<div>
<h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a xmlns="" class="anchor" id="org.osgi.util.xml.XMLParserActivator.start-BundleContext-"></a><span xmlns="" class="number">702.9.2.11</span> public void start(BundleContext context) throws Exception
</h4>
</div>
</div>
</div>
<p xmlns="" class="parameter"><label>context</label><span>The execution context of the bundle being started.</span></p>
<p xmlns="" class="description"><label>□</label><span>
Called when this bundle is started so the Framework can perform the
bundle-specific activities necessary to start this bundle. This method
can be used to register services or to allocate any resources that this
bundle needs.
</span></p>
<p>
This method must complete and return to its caller in a timely manner.
</p>
<p>
This method attempts to register a SAX and DOM parser with the