lib/classpath/external/sax/org/xml/sax/ext/Attributes2.java

   1 // Attributes2.java - extended Attributes
   2 // http://www.saxproject.org
   3 // Public Domain: no warranty.
   4 // $Id: Attributes2.java,v 1.1 2004/12/23 22:38:42 mark 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      */
  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 }