Attributes2.java revision 6b811c5daec1b28e6f63b57f98a032236f2c3cf7 
1// Attributes2.java - extended Attributes
2// http://www.saxproject.org
3// Public Domain: no warranty.
4// $Id: Attributes2.java,v 1.6 2004/03/08 13:01:00 dmegginson Exp $
5
6package org.xml.sax.ext;
7
8import 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 */
39public 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}
133