1   // Attributes2.java - extended Attributes
    2   // http://www.saxproject.org
    3   // Public Domain: no warranty.
    4   // $Id: Attributes2.java 226184 2005-04-08 10:53:24Z neeraj $
    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        */
   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   }