← Back to branch summary

~ubuntu-branches/ubuntu/karmic/libxerces2-java/karmic

« back to all changes in this revision

Viewing changes to docs/faq-sax.xml

  • Committer: Bazaar Package Importer
  • Author(s): Matthias Klose
  • Date: 2006-12-04 17:37:55 UTC
  • mfrom: (2.1.2 etch)
  • Revision ID: james.westby@ubuntu.com-20061204173755-hb6ybrrrk097zhx7
Tags: 2.8.1-1ubuntu1
* Merge with Debian unstable; remaining changes:
  - Build -gcj package.

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/faq-sax.xml
1
1
<?xml version='1.0' encoding='UTF-8'?>
 
2
<!--
 
3
 * Copyright 2004-2006 The Apache Software Foundation.
 
4
 *
 
5
 * Licensed under the Apache License, Version 2.0 (the "License");
 
6
 * you may not use this file except in compliance with the License.
 
7
 * You may obtain a copy of the License at
 
8
 *
 
9
 *     http://www.apache.org/licenses/LICENSE-2.0
 
10
 *
 
11
 * Unless required by applicable law or agreed to in writing, software
 
12
 * distributed under the License is distributed on an "AS IS" BASIS,
 
13
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 
14
 * See the License for the specific language governing permissions and
 
15
 * limitations under the License.
 
16
-->
2
17
<!DOCTYPE faqs SYSTEM 'dtd/faqs.dtd'>
3
18
<faqs title='Programming with SAX'>
4
19
 
23
38
String xmlFile = &quot;file:///&parserdir;/data/personal.xml&quot;; 
24
39
try {
25
40
    SAXParserFactory factory = SAXParserFactory.newInstance();
 
41
    factory.setNamespaceAware(true);
26
42
    SAXParser parser = factory.newSAXParser();
27
43
    DefaultHandler handler = /* custom handler class */;
28
44
    parser.parse(xmlFile, handler);
64
80
    <q>Why doesn't the SAX parser report ignorable whitespace for XML Schemas?</q>
65
81
    <a>
66
82
      <p>SAX is very clear that ignorableWhitespace is only called for
67
 
         <jump href="http://www.w3.org/TR/REC-xml/#sec-white-space">
 
83
         <jump href="http://www.w3.org/TR/2006/REC-xml-20060816/#sec-white-space">
68
84
         element content whitespace</jump>, which is defined in the context of a DTD.
69
85
         The result of schema validation is the Post-Schema-Validation Infoset (PSVI). 
70
86
         Schema processors augment the base Infoset by adding new properties to 
74
90
    </a>
75
91
  </faq>
76
92
  
 
93
  <faq title="Attributes and ContentHandler.startElement">
 
94
    <q>Why is the Attributes parameter passed to startElement always a 
 
95
    reference to the same object?</q>
 
96
    <a>
 
97
      <p>Outside the scope of <code>startElement</code>, the value of the 
 
98
         <code>Attributes</code> parameter is undefined. For each instance of Xerces'
 
99
         SAX parser, there exists only one <code>Attributes</code> instance which 
 
100
         is reused for every new set of attributes. Before each 
 
101
         <code>startElement</code> callback, the previous values in this object
 
102
         will be overwritten. This is done for performance reasons in order
 
103
         to reduce object creation. To persist a set of attributes
 
104
         beyond <code>startElement</code> the object should be cloned, for
 
105
         instance by using <code>org.xml.sax.helpers.AttributesImpl</code>.
 
106
      </p>
 
107
    </a>
 
108
  </faq>
 
109
  
77
110
  <faq title="Namespace of xmlns attributes">
78
111
    <q>Why does the SAX parser report that xmlns attributes have no namespace?</q>
79
112
    <a>
80
 
       <p>An erratum for the Namespaces in XML recommendation put namespace declaration 
81
 
          attributes in the namespace "http://www.w3.org/2000/xmlns/". SAX2 (SAX 2.0.1)
82
 
          does not agree with this change so conforming parsers must report that these 
83
 
          attributes have no namespace. Xerces behaves according to SAX2. Your code
84
 
          must handle this discrepancy when interacting with APIs such as DOM and
85
 
          applications which expect a namespace for xmlns attributes.</p>
 
113
       <p>An erratum for the Namespaces in XML Recommendation put namespace declaration 
 
114
          attributes in the namespace "http://www.w3.org/2000/xmlns/". By default, 
 
115
          SAX2 (SAX 2.0.2) follows the original Namespaces in XML Recommendation, so 
 
116
          conforming parsers must report that these attributes have no namespace. To
 
117
          configure the parser to report a namespace for such attributes, turn on
 
118
          the <link idref='features' anchor='xmlns-uris'>xmlns-uris</link> feature.
 
119
       </p>
 
120
       <p>When using Xerces 2.6.2 (or prior) or other parser implementations
 
121
          that do not support this feature, your code must handle this discrepancy
 
122
          when interacting with APIs such as DOM and applications which expect a namespace 
 
123
          for xmlns attributes.
 
124
       </p>
86
125
    </a>
87
126
  </faq>
88
127
 
89
 
  <faq title="Encodings and XML Version Via SAX">
 
128
  <faq title="Encodings and XML Version via SAX">
90
129
    <q>Is there any way I can determine what encoding an entity was
91
130
    written in, or what XML version the document conformed to, if I'm
92
131
    using SAX?</q>
93
132
    <a>
94
 
        <p>The answer to this question is that, yes there is a way, but it's
95
 
        not particularly beautiful.  There is no way in SAX 2.0.0 or
96
 
        2.0.1 to get hold of these pieces of information; the SAX
97
 
        Locator2 interface from the 1.1 extensions--still in Beta at
98
 
        the time of writing--does provide methods to accomplish this,
99
 
        but since Xerces is required to support precisely SAX 2.0.1 by
100
 
        Sun TCK rules, we cannot ship this interface.  However, we can
101
 
        still support the appropriate methods on the objects we
102
 
        provide to implement the SAX Locator interface.  Therefore,
103
 
        assuming <code>Locator</code> is an instance of the SAX
104
 
        Locator interface that Xerces has passed back in a
105
 
        <code>setDocumentLocator</code> call, 
106
 
        you can use a method like this to determine the encoding of
107
 
        the entity currently being parsed:
108
 
        </p>
109
 
        <source>import java.lang.reflect.Method;
110
 
private String getEncoding(Locator locator) {
111
 
    String encoding = null;
112
 
    Method getEncoding = null;
113
 
    try {
114
 
        getEncoding = 
115
 
            locator.getClass().getMethod("getEncoding", new Class[]{});
116
 
        if(getEncoding != null) {
117
 
            encoding = (String)getEncoding.invoke(locator, null);
118
 
        }
119
 
    } catch (Exception e) {
120
 
        // either this locator object doesn't have this
121
 
        // method, or we're on an old JDK
122
 
    }
123
 
    return encoding;
124
 
}</source>
125
 
        <p>This code has the advantage that it will compile on JDK
126
 
        1.1.8, though it will only produce non-null results on 1.2.x
127
 
        JDK's and later.  Substituting <code>getXMLVersion</code> for
128
 
        <code>getEncoding</code> will enable you to determine the
129
 
        version of XML to which the instance document conforms.
 
133
        <p>Yes. As of SAX 2.0.2 encoding and version information is made
 
134
        available through the <code>org.xml.sax.ext.Locator2</code>
 
135
        interface. In Xerces, instances of the SAX <code>Locator</code> interface
 
136
        passed to a <code>setDocumentLocator</code> call will also implement
 
137
        the <code>Locator2</code> interface. You can determine the encoding
 
138
        and XML version of the entity currently being parsed by calling the
 
139
        <code>getEncoding()</code> and <code>getXMLVersion()</code> methods.
130
140
        </p>
131
141
    </a>
132
142
  </faq>