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 }