1
2
3
4
5
6 package org.xml.sax.ext;
7
8 import org.xml.sax.Attributes;
9
10
11 /***
12 * SAX2 extension to augment the per-attribute information
13 * provided though {@link Attributes}.
14 * If an implementation supports this extension, the attributes
15 * provided in {@link org.xml.sax.ContentHandler#startElement
16 * ContentHandler.startElement() } will implement this interface,
17 * and the <em>http://xml.org/sax/features/use-attributes2</em>
18 * feature flag will have the value <em>true</em>.
19 *
20 * <blockquote>
21 * <em>This module, both source code and documentation, is in the
22 * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
23 * </blockquote>
24 *
25 * <p> XMLReader implementations are not required to support this
26 * information, and it is not part of core-only SAX2 distributions.</p>
27 *
28 * <p>Note that if an attribute was defaulted (<em>!isSpecified()</em>)
29 * it will of necessity also have been declared (<em>isDeclared()</em>)
30 * in the DTD.
31 * Similarly if an attribute's type is anything except CDATA, then it
32 * must have been declared.
33 * </p>
34 *
35 * @since SAX 2.0 (extensions 1.1 alpha)
36 * @author David Brownell
37 * @version TBS
38 */
39 public interface Attributes2 extends Attributes
40 {
41 /***
42 * Returns false unless the attribute was declared in the DTD.
43 * This helps distinguish two kinds of attributes that SAX reports
44 * as CDATA: ones that were declared (and hence are usually valid),
45 * and those that were not (and which are never valid).
46 *
47 * @param index The attribute index (zero-based).
48 * @return true if the attribute was declared in the DTD,
49 * false otherwise.
50 * @exception java.lang.ArrayIndexOutOfBoundsException When the
51 * supplied index does not identify an attribute.
52 */
53 public boolean isDeclared (int index);
54
55 /***
56 * Returns false unless the attribute was declared in the DTD.
57 * This helps distinguish two kinds of attributes that SAX reports
58 * as CDATA: ones that were declared (and hence are usually valid),
59 * and those that were not (and which are never valid).
60 *
61 * @param qName The XML qualified (prefixed) name.
62 * @return true if the attribute was declared in the DTD,
63 * false otherwise.
64 * @exception java.lang.IllegalArgumentException When the
65 * supplied name does not identify an attribute.
66 */
67 public boolean isDeclared (String qName);
68
69 /***
70 * Returns false unless the attribute was declared in the DTD.
71 * This helps distinguish two kinds of attributes that SAX reports
72 * as CDATA: ones that were declared (and hence are usually valid),
73 * and those that were not (and which are never valid).
74 *
75 * <p>Remember that since DTDs do not "understand" namespaces, the
76 * namespace URI associated with an attribute may not have come from
77 * the DTD. The declaration will have applied to the attribute's
78 * <em>qName</em>.
79 *
80 * @param uri The Namespace URI, or the empty string if
81 * the name has no Namespace URI.
82 * @param localName The attribute's local name.
83 * @return true if the attribute was declared in the DTD,
84 * false otherwise.
85 * @exception java.lang.IllegalArgumentException When the
86 * supplied names do not identify an attribute.
87 */
88 public boolean isDeclared (String uri, String localName);
89
90 /***
91 * Returns true unless the attribute value was provided
92 * by DTD defaulting.
93 *
94 * @param index The attribute index (zero-based).
95 * @return true if the value was found in the XML text,
96 * false if the value was provided by DTD defaulting.
97 * @exception java.lang.ArrayIndexOutOfBoundsException When the
98 * supplied index does not identify an attribute.
99 */
100 public boolean isSpecified (int index);
101
102 /***
103 * Returns true unless the attribute value was provided
104 * by DTD defaulting.
105 *
106 * <p>Remember that since DTDs do not "understand" namespaces, the
107 * namespace URI associated with an attribute may not have come from
108 * the DTD. The declaration will have applied to the attribute's
109 * <em>qName</em>.
110 *
111 * @param uri The Namespace URI, or the empty string if
112 * the name has no Namespace URI.
113 * @param localName The attribute's local name.
114 * @return true if the value was found in the XML text,
115 * false if the value was provided by DTD defaulting.
116 * @exception java.lang.IllegalArgumentException When the
117 * supplied names do not identify an attribute.
118 */
119 public boolean isSpecified (String uri, String localName);
120
121 /***
122 * Returns true unless the attribute value was provided
123 * by DTD defaulting.
124 *
125 * @param qName The XML qualified (prefixed) name.
126 * @return true if the value was found in the XML text,
127 * false if the value was provided by DTD defaulting.
128 * @exception java.lang.IllegalArgumentException When the
129 * supplied name does not identify an attribute.
130 */
131 public boolean isSpecified (String qName);
132 }