org.xml.sax.Attributes Maven / Gradle / Ivy
/*
* Portions Copyright 2000-2008 Sun Microsystems, Inc. All Rights
* Reserved. Use is subject to license terms.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
*
* This program 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.
*
* This program 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 at /legal/license.txt).
*
* 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 Sun Microsystems, Inc., 4150 Network Circle, Santa
* Clara, CA 95054 or visit www.sun.com if you need additional
* information or have any questions.
*/
// Attributes.java - attribute list with Namespace support
// http://www.saxproject.org
// Written by David Megginson
// NO WARRANTY! This class is in the public domain.
package org.xml.sax;
/**
* Interface for a list of XML attributes.
*
* This interface allows access to a list of attributes in
* three different ways:
*
*
* - by attribute index;
* - by Namespace-qualified name; or
* - by qualified (prefixed) name.
*
*
* 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 http://xml.org/sax/features/namespace-prefixes
* feature is set to true (it is false by
* default).
* Because SAX2 conforms to the original "Namespaces in XML"
* recommendation, it normally does not
* give namespace declaration attributes a namespace URI.
*
*
* Some SAX2 parsers may support using an optional feature flag
* (http://xml.org/sax/features/xmlns-uris) 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.
*
* If the namespace-prefixes feature (see above) is
* false, access by qualified name may not be available; if
* the http://xml.org/sax/features/namespaces feature is
* false, access by Namespace-qualified names may not be
* available.
*
* The order of attributes in the list is unspecified, and will
* vary from implementation to implementation.
*
* @since SAX 2.0
* @author David Megginson
* @see org.xml.sax.ext.Attributes2
*/
public interface Attributes
{
////////////////////////////////////////////////////////////////////
// Indexed access.
////////////////////////////////////////////////////////////////////
/**
* Return the number of attributes in the list.
*
* Once you know the number of attributes, you can iterate
* through the list.
*
* @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.
*
* The attribute type is one of the strings "CDATA", "ID",
* "IDREF", "IDREFS", "NMTOKEN", "NMTOKENS", "ENTITY", "ENTITIES",
* or "NOTATION" (always in upper case).
*
* 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").
*
* For an enumerated attribute that is not a notation, the
* parser will report the type as "NMTOKEN".
*
* @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.
*
* 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.
*
* @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.
*
* See {@link #getType(int) getType(int)} for a description
* of the possible types.
*
* @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.
*
* See {@link #getType(int) getType(int)} for a description
* of the possible types.
*
* @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.
*
* See {@link #getValue(int) getValue(int)} for a description
* of the possible values.
*
* @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.
*
* See {@link #getValue(int) getValue(int)} for a description
* of the possible values.
*
* @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