001 // Attributes2.java - extended Attributes
002 // http://www.saxproject.org
003 // Public Domain: no warranty.
004 // $Id: Attributes2.java,v 1.1 2004/12/23 22:38:42 mark Exp $
005
006 package org.xml.sax.ext;
007
008 import org.xml.sax.Attributes;
009
010
011 /**
012 * SAX2 extension to augment the per-attribute information
013 * provided though {@link Attributes}.
014 * If an implementation supports this extension, the attributes
015 * provided in {@link org.xml.sax.ContentHandler#startElement
016 * ContentHandler.startElement() } will implement this interface,
017 * and the <em>http://xml.org/sax/features/use-attributes2</em>
018 * feature flag will have the value <em>true</em>.
019 *
020 * <blockquote>
021 * <em>This module, both source code and documentation, is in the
022 * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
023 * </blockquote>
024 *
025 * <p> XMLReader implementations are not required to support this
026 * information, and it is not part of core-only SAX2 distributions.</p>
027 *
028 * <p>Note that if an attribute was defaulted (<em>!isSpecified()</em>)
029 * it will of necessity also have been declared (<em>isDeclared()</em>)
030 * in the DTD.
031 * Similarly if an attribute's type is anything except CDATA, then it
032 * must have been declared.
033 * </p>
034 *
035 * @since SAX 2.0 (extensions 1.1 alpha)
036 * @author David Brownell
037 * @version TBS
038 */
039 public interface Attributes2 extends Attributes
040 {
041 /**
042 * Returns false unless the attribute was declared in the DTD.
043 * This helps distinguish two kinds of attributes that SAX reports
044 * as CDATA: ones that were declared (and hence are usually valid),
045 * and those that were not (and which are never valid).
046 *
047 * @param index The attribute index (zero-based).
048 * @return true if the attribute was declared in the DTD,
049 * false otherwise.
050 * @exception java.lang.ArrayIndexOutOfBoundsException When the
051 * supplied index does not identify an attribute.
052 */
053 public boolean isDeclared (int index);
054
055 /**
056 * Returns false unless the attribute was declared in the DTD.
057 * This helps distinguish two kinds of attributes that SAX reports
058 * as CDATA: ones that were declared (and hence are usually valid),
059 * and those that were not (and which are never valid).
060 *
061 * @param qName The XML qualified (prefixed) name.
062 * @return true if the attribute was declared in the DTD,
063 * false otherwise.
064 * @exception java.lang.IllegalArgumentException When the
065 * supplied name does not identify an attribute.
066 */
067 public boolean isDeclared (String qName);
068
069 /**
070 * Returns false unless the attribute was declared in the DTD.
071 * This helps distinguish two kinds of attributes that SAX reports
072 * as CDATA: ones that were declared (and hence are usually valid),
073 * and those that were not (and which are never valid).
074 *
075 * <p>Remember that since DTDs do not "understand" namespaces, the
076 * namespace URI associated with an attribute may not have come from
077 * the DTD. The declaration will have applied to the attribute's
078 * <em>qName</em>.
079 *
080 * @param uri The Namespace URI, or the empty string if
081 * the name has no Namespace URI.
082 * @param localName The attribute's local name.
083 * @return true if the attribute was declared in the DTD,
084 * false otherwise.
085 * @exception java.lang.IllegalArgumentException When the
086 * supplied names do not identify an attribute.
087 */
088 public boolean isDeclared (String uri, String localName);
089
090 /**
091 * Returns true unless the attribute value was provided
092 * by DTD defaulting.
093 *
094 * @param index The attribute index (zero-based).
095 * @return true if the value was found in the XML text,
096 * false if the value was provided by DTD defaulting.
097 * @exception java.lang.ArrayIndexOutOfBoundsException When the
098 * supplied index does not identify an attribute.
099 */
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 }