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
006package org.xml.sax.ext;
007
008import 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 */
039public 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}