001 /*
002 * Copyright 2004-2005 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 // Attributes2.java - extended Attributes
027 // http://www.saxproject.org
028 // Public Domain: no warranty.
029 // $Id: Attributes2.java,v 1.2 2004/11/03 22:49:07 jsuttor Exp $
030 package org.xml.sax.ext;
031
032 import org.xml.sax.Attributes;
033
034 /**
035 * SAX2 extension to augment the per-attribute information
036 * provided though {@link Attributes}.
037 * If an implementation supports this extension, the attributes
038 * provided in {@link org.xml.sax.ContentHandler#startElement
039 * ContentHandler.startElement() } will implement this interface,
040 * and the <em>http://xml.org/sax/features/use-attributes2</em>
041 * feature flag will have the value <em>true</em>.
042 *
043 * <blockquote>
044 * <em>This module, both source code and documentation, is in the
045 * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
046 * </blockquote>
047 *
048 * <p> XMLReader implementations are not required to support this
049 * information, and it is not part of core-only SAX2 distributions.</p>
050 *
051 * <p>Note that if an attribute was defaulted (<em>!isSpecified()</em>)
052 * it will of necessity also have been declared (<em>isDeclared()</em>)
053 * in the DTD.
054 * Similarly if an attribute's type is anything except CDATA, then it
055 * must have been declared.
056 * </p>
057 *
058 * @since SAX 2.0 (extensions 1.1 alpha)
059 * @author David Brownell
060 * @version TBS
061 */
062 public interface Attributes2 extends Attributes {
063 /**
064 * Returns false unless the attribute was declared in the DTD.
065 * This helps distinguish two kinds of attributes that SAX reports
066 * as CDATA: ones that were declared (and hence are usually valid),
067 * and those that were not (and which are never valid).
068 *
069 * @param index The attribute index (zero-based).
070 * @return true if the attribute was declared in the DTD,
071 * false otherwise.
072 * @exception java.lang.ArrayIndexOutOfBoundsException When the
073 * supplied index does not identify an attribute.
074 */
075 public boolean isDeclared(int index);
076
077 /**
078 * Returns false unless the attribute was declared in the DTD.
079 * This helps distinguish two kinds of attributes that SAX reports
080 * as CDATA: ones that were declared (and hence are usually valid),
081 * and those that were not (and which are never valid).
082 *
083 * @param qName The XML qualified (prefixed) name.
084 * @return true if the attribute was declared in the DTD,
085 * false otherwise.
086 * @exception java.lang.IllegalArgumentException When the
087 * supplied name does not identify an attribute.
088 */
089 public boolean isDeclared(String qName);
090
091 /**
092 * Returns false unless the attribute was declared in the DTD.
093 * This helps distinguish two kinds of attributes that SAX reports
094 * as CDATA: ones that were declared (and hence are usually valid),
095 * and those that were not (and which are never valid).
096 *
097 * <p>Remember that since DTDs do not "understand" namespaces, the
098 * namespace URI associated with an attribute may not have come from
099 * the DTD. The declaration will have applied to the attribute's
100 * <em>qName</em>.
101 *
102 * @param uri The Namespace URI, or the empty string if
103 * the name has no Namespace URI.
104 * @param localName The attribute's local name.
105 * @return true if the attribute was declared in the DTD,
106 * false otherwise.
107 * @exception java.lang.IllegalArgumentException When the
108 * supplied names do not identify an attribute.
109 */
110 public boolean isDeclared(String uri, String localName);
111
112 /**
113 * Returns true unless the attribute value was provided
114 * by DTD defaulting.
115 *
116 * @param index The attribute index (zero-based).
117 * @return true if the value was found in the XML text,
118 * false if the value was provided by DTD defaulting.
119 * @exception java.lang.ArrayIndexOutOfBoundsException When the
120 * supplied index does not identify an attribute.
121 */
122 public boolean isSpecified(int index);
123
124 /**
125 * Returns true unless the attribute value was provided
126 * by DTD defaulting.
127 *
128 * <p>Remember that since DTDs do not "understand" namespaces, the
129 * namespace URI associated with an attribute may not have come from
130 * the DTD. The declaration will have applied to the attribute's
131 * <em>qName</em>.
132 *
133 * @param uri The Namespace URI, or the empty string if
134 * the name has no Namespace URI.
135 * @param localName The attribute's local name.
136 * @return true if the value was found in the XML text,
137 * false if the value was provided by DTD defaulting.
138 * @exception java.lang.IllegalArgumentException When the
139 * supplied names do not identify an attribute.
140 */
141 public boolean isSpecified(String uri, String localName);
142
143 /**
144 * Returns true unless the attribute value was provided
145 * by DTD defaulting.
146 *
147 * @param qName The XML qualified (prefixed) name.
148 * @return true if the value was found in the XML text,
149 * false if the value was provided by DTD defaulting.
150 * @exception java.lang.IllegalArgumentException When the
151 * supplied name does not identify an attribute.
152 */
153 public boolean isSpecified(String qName);
154 }
|