1 // Attributes2.java - extended Attributes 2 // http://www.saxproject.org 3 // Public Domain: no warranty. 4 // $Id: Attributes2.java,v 1.6 2004/03/08 13:01:00 dmegginson 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 */ isDeclared(int index)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 */ isDeclared(String qName)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 */ isDeclared(String uri, String localName)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 */ isSpecified(int index)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 */ isSpecified(String uri, String localName)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 */ isSpecified(String qName)131 public boolean isSpecified (String qName); 132 } 133