/* |
|
* Copyright (c) 2000, 2019, Oracle and/or its affiliates. All rights reserved. |
|
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
|
* |
|
* This code is free software; you can redistribute it and/or modify it |
|
* under the terms of the GNU General Public License version 2 only, as |
|
* published by the Free Software Foundation. Oracle designates this |
|
* particular file as subject to the "Classpath" exception as provided |
|
* by Oracle in the LICENSE file that accompanied this code. |
|
* |
|
* This code is distributed in the hope that it will be useful, but WITHOUT |
|
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
|
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
|
* version 2 for more details (a copy is included in the LICENSE file that |
|
* accompanied this code). |
|
* |
|
* You should have received a copy of the GNU General Public License version |
|
* 2 along with this work; if not, write to the Free Software Foundation, |
|
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
|
* |
|
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
|
* or visit www.oracle.com if you need additional information or have any |
|
* questions. |
|
*/ |
|
package org.xml.sax; |
|
/** |
|
* Interface for a list of XML attributes. |
|
* |
|
* <p>This interface allows access to a list of attributes in |
|
* three different ways:</p> |
|
* |
|
* <ol> |
|
* <li>by attribute index;</li> |
|
* <li>by Namespace-qualified name; or</li> |
|
* <li>by qualified (prefixed) name.</li> |
|
* </ol> |
|
* |
|
* <p>The list will not contain attributes that were declared |
|
* #IMPLIED but not specified in the start tag. It will also not |
|
* contain attributes used as Namespace declarations (xmlns*) unless |
|
* the <code>http://xml.org/sax/features/namespace-prefixes</code> |
|
* feature is set to <var>true</var> (it is <var>false</var> by |
|
* default). |
|
* Because SAX2 conforms to the original "Namespaces in XML" |
|
* recommendation, it normally does not |
|
* give namespace declaration attributes a namespace URI. |
|
* </p> |
|
* |
|
* <p>Some SAX2 parsers may support using an optional feature flag |
|
* (<code>http://xml.org/sax/features/xmlns-uris</code>) to request |
|
* that those attributes be given URIs, conforming to a later |
|
* backwards-incompatible revision of that recommendation. (The |
|
* attribute's "local name" will be the prefix, or "xmlns" when |
|
* defining a default element namespace.) For portability, handler |
|
* code should always resolve that conflict, rather than requiring |
|
* parsers that can change the setting of that feature flag. </p> |
|
* |
|
* <p>If the namespace-prefixes feature (see above) is |
|
* <var>false</var>, access by qualified name may not be available; if |
|
* the <code>http://xml.org/sax/features/namespaces</code> feature is |
|
* <var>false</var>, access by Namespace-qualified names may not be |
|
* available.</p> |
|
* |
|
* <p>This interface replaces the now-deprecated SAX1 {@link |
|
* org.xml.sax.AttributeList AttributeList} interface, which does not |
|
* contain Namespace support. In addition to Namespace support, it |
|
* adds the <var>getIndex</var> methods (below).</p> |
|
* |
|
* <p>The order of attributes in the list is unspecified, and will |
|
* vary from implementation to implementation.</p> |
|
* |
|
* @since 1.4, SAX 2.0 |
|
* @author David Megginson |
|
* @see org.xml.sax.helpers.AttributesImpl |
|
* @see org.xml.sax.ext.DeclHandler#attributeDecl |
|
*/ |
|
public interface Attributes |
|
{ |
|
//////////////////////////////////////////////////////////////////// |
|
// Indexed access. |
|
//////////////////////////////////////////////////////////////////// |
|
/** |
|
* Return the number of attributes in the list. |
|
* |
|
* <p>Once you know the number of attributes, you can iterate |
|
* through the list.</p> |
|
* |
|
* @return The number of attributes in the list. |
|
* @see #getURI(int) |
|
* @see #getLocalName(int) |
|
* @see #getQName(int) |
|
* @see #getType(int) |
|
* @see #getValue(int) |
|
*/ |
|
public abstract int getLength (); |
|
/** |
|
* Look up an attribute's Namespace URI by index. |
|
* |
|
* @param index The attribute index (zero-based). |
|
* @return The Namespace URI, or the empty string if none |
|
* is available, or null if the index is out of |
|
* range. |
|
* @see #getLength |
|
*/ |
|
public abstract String getURI (int index); |
|
/** |
|
* Look up an attribute's local name by index. |
|
* |
|
* @param index The attribute index (zero-based). |
|
* @return The local name, or the empty string if Namespace |
|
* processing is not being performed, or null |
|
* if the index is out of range. |
|
* @see #getLength |
|
*/ |
|
public abstract String getLocalName (int index); |
|
/** |
|
* Look up an attribute's XML qualified (prefixed) name by index. |
|
* |
|
* @param index The attribute index (zero-based). |
|
* @return The XML qualified name, or the empty string |
|
* if none is available, or null if the index |
|
* is out of range. |
|
* @see #getLength |
|
*/ |
|
public abstract String getQName (int index); |
|
/** |
|
* Look up an attribute's type by index. |
|
* |
|
* <p>The attribute type is one of the strings "CDATA", "ID", |
|
* "IDREF", "IDREFS", "NMTOKEN", "NMTOKENS", "ENTITY", "ENTITIES", |
|
* or "NOTATION" (always in upper case).</p> |
|
* |
|
* <p>If the parser has not read a declaration for the attribute, |
|
* or if the parser does not report attribute types, then it must |
|
* return the value "CDATA" as stated in the XML 1.0 Recommendation |
|
* (clause 3.3.3, "Attribute-Value Normalization").</p> |
|
* |
|
* <p>For an enumerated attribute that is not a notation, the |
|
* parser will report the type as "NMTOKEN".</p> |
|
* |
|
* @param index The attribute index (zero-based). |
|
* @return The attribute's type as a string, or null if the |
|
* index is out of range. |
|
* @see #getLength |
|
*/ |
|
public abstract String getType (int index); |
|
/** |
|
* Look up an attribute's value by index. |
|
* |
|
* <p>If the attribute value is a list of tokens (IDREFS, |
|
* ENTITIES, or NMTOKENS), the tokens will be concatenated |
|
* into a single string with each token separated by a |
|
* single space.</p> |
|
* |
|
* @param index The attribute index (zero-based). |
|
* @return The attribute's value as a string, or null if the |
|
* index is out of range. |
|
* @see #getLength |
|
*/ |
|
public abstract String getValue (int index); |
|
//////////////////////////////////////////////////////////////////// |
|
// Name-based query. |
|
//////////////////////////////////////////////////////////////////// |
|
/** |
|
* Look up the index of an attribute by Namespace name. |
|
* |
|
* @param uri The Namespace URI, or the empty string if |
|
* the name has no Namespace URI. |
|
* @param localName The attribute's local name. |
|
* @return The index of the attribute, or -1 if it does not |
|
* appear in the list. |
|
*/ |
|
public int getIndex (String uri, String localName); |
|
/** |
|
* Look up the index of an attribute by XML qualified (prefixed) name. |
|
* |
|
* @param qName The qualified (prefixed) name. |
|
* @return The index of the attribute, or -1 if it does not |
|
* appear in the list. |
|
*/ |
|
public int getIndex (String qName); |
|
/** |
|
* Look up an attribute's type by Namespace name. |
|
* |
|
* <p>See {@link #getType(int) getType(int)} for a description |
|
* of the possible types.</p> |
|
* |
|
* @param uri The Namespace URI, or the empty String if the |
|
* name has no Namespace URI. |
|
* @param localName The local name of the attribute. |
|
* @return The attribute type as a string, or null if the |
|
* attribute is not in the list or if Namespace |
|
* processing is not being performed. |
|
*/ |
|
public abstract String getType (String uri, String localName); |
|
/** |
|
* Look up an attribute's type by XML qualified (prefixed) name. |
|
* |
|
* <p>See {@link #getType(int) getType(int)} for a description |
|
* of the possible types.</p> |
|
* |
|
* @param qName The XML qualified name. |
|
* @return The attribute type as a string, or null if the |
|
* attribute is not in the list or if qualified names |
|
* are not available. |
|
*/ |
|
public abstract String getType (String qName); |
|
/** |
|
* Look up an attribute's value by Namespace name. |
|
* |
|
* <p>See {@link #getValue(int) getValue(int)} for a description |
|
* of the possible values.</p> |
|
* |
|
* @param uri The Namespace URI, or the empty String if the |
|
* name has no Namespace URI. |
|
* @param localName The local name of the attribute. |
|
* @return The attribute value as a string, or null if the |
|
* attribute is not in the list. |
|
*/ |
|
public abstract String getValue (String uri, String localName); |
|
/** |
|
* Look up an attribute's value by XML qualified (prefixed) name. |
|
* |
|
* <p>See {@link #getValue(int) getValue(int)} for a description |
|
* of the possible values.</p> |
|
* |
|
* @param qName The XML qualified name. |
|
* @return The attribute value as a string, or null if the |
|
* attribute is not in the list or if qualified names |
|
* are not available. |
|
*/ |
|
public abstract String getValue (String qName); |
|
} |
|
// end of Attributes.java |