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 
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      */
isDeclared(int index)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      */
isDeclared(String qName)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      */
isDeclared(String uri, String localName)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      */
isSpecified(int index)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      */
isSpecified(String uri, String localName)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      */
isSpecified(String qName)131     public boolean isSpecified (String qName);
132 }
133