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    }