001: /*
002: *
003: *
004: * Copyright 1990-2007 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program is distributed in the hope that it will be useful, but
012: * WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * General Public License version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: */
026:
027: // Attributes.java - attribute list with Namespace support
028: package org.xml.sax;
029:
030: /**
031: * Interface for a list of XML attributes.
032: *
033: * <blockquote>
034: * <em>This module, both source code and documentation, is in the
035: * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
036: * </blockquote>
037: *
038: * <p>This interface allows access to a list of attributes in
039: * three different ways:</p>
040: *
041: * <ol>
042: * <li>by attribute index;</li>
043: * <li>by Namespace-qualified name; or</li>
044: * <li>by qualified (prefixed) name.</li>
045: * </ol>
046: *
047: * <p>The list will not contain attributes that were declared
048: * #IMPLIED but not specified in the start tag. It will also not
049: * contain attributes used as Namespace declarations (xmlns*) unless
050: * the <code>http://xml.org/sax/features/namespace-prefixes</code>
051: * feature is set to <var>true</var> (it is <var>false</var> by
052: * default).</p>
053: *
054: * <p>If the namespace-prefixes feature (see above) is <var>false</var>,
055: * access by qualified name may not be available; if the
056: * <code>http://xml.org/sax/features/namespaces</code>
057: * feature is <var>false</var>, access by Namespace-qualified names
058: * may not be available.</p>
059: *
060: * <p>The order of attributes in the list is unspecified, and will
061: * vary from implementation to implementation.</p>
062: *
063: * @since SAX 2.0
064: *
065: * @version 2.0
066: */
067: public interface Attributes {
068:
069: ////////////////////////////////////////////////////////////////////
070: // Indexed access.
071: ////////////////////////////////////////////////////////////////////
072:
073: /**
074: * Return the number of attributes in the list.
075: *
076: * <p>Once you know the number of attributes, you can iterate
077: * through the list.</p>
078: *
079: * @return The number of attributes in the list.
080: * @see #getURI(int)
081: * @see #getLocalName(int)
082: * @see #getQName(int)
083: * @see #getType(int)
084: * @see #getValue(int)
085: */
086: public abstract int getLength();
087:
088: /**
089: * Look up an attribute's Namespace URI by index.
090: *
091: * @param index The attribute index (zero-based).
092: * @return The Namespace URI, or the empty string if none
093: * is available, or null if the index is out of
094: * range.
095: * @see #getLength
096: */
097: public abstract String getURI(int index);
098:
099: /**
100: * Look up an attribute's local name by index.
101: *
102: * @param index The attribute index (zero-based).
103: * @return The local name, or the empty string if Namespace
104: * processing is not being performed, or null
105: * if the index is out of range.
106: * @see #getLength
107: */
108: public abstract String getLocalName(int index);
109:
110: /**
111: * Look up an attribute's XML 1.0 qualified name by index.
112: *
113: * @param index The attribute index (zero-based).
114: * @return The XML 1.0 qualified name, or the empty string
115: * if none is available, or null if the index
116: * is out of range.
117: * @see #getLength
118: */
119: public abstract String getQName(int index);
120:
121: /**
122: * Look up an attribute's type by index.
123: *
124: * <p>The attribute type is one of the strings "CDATA", "ID",
125: * "IDREF", "IDREFS", "NMTOKEN", "NMTOKENS", "ENTITY", "ENTITIES",
126: * or "NOTATION" (always in upper case).</p>
127: *
128: * <p>If the parser has not read a declaration for the attribute,
129: * or if the parser does not report attribute types, then it must
130: * return the value "CDATA" as stated in the XML 1.0 Recommentation
131: * (clause 3.3.3, "Attribute-Value Normalization").</p>
132: *
133: * <p>For an enumerated attribute that is not a notation, the
134: * parser will report the type as "NMTOKEN".</p>
135: *
136: * @param index The attribute index (zero-based).
137: * @return The attribute's type as a string, or null if the
138: * index is out of range.
139: * @see #getLength
140: */
141: public abstract String getType(int index);
142:
143: /**
144: * Look up an attribute's value by index.
145: *
146: * <p>If the attribute value is a list of tokens (IDREFS,
147: * ENTITIES, or NMTOKENS), the tokens will be concatenated
148: * into a single string with each token separated by a
149: * single space.</p>
150: *
151: * @param index The attribute index (zero-based).
152: * @return The attribute's value as a string, or null if the
153: * index is out of range.
154: * @see #getLength
155: */
156: public abstract String getValue(int index);
157:
158: ////////////////////////////////////////////////////////////////////
159: // Name-based query.
160: ////////////////////////////////////////////////////////////////////
161:
162: /**
163: * Look up the index of an attribute by Namespace name.
164: *
165: * @param uri The Namespace URI, or the empty string if
166: * the name has no Namespace URI.
167: * @param localName The attribute's local name.
168: * @return The index of the attribute, or -1 if it does not
169: * appear in the list.
170: */
171: public int getIndex(String uri, String localName);
172:
173: /**
174: * Look up the index of an attribute by XML 1.0 qualified name.
175: *
176: * @param qName The qualified (prefixed) name.
177: * @return The index of the attribute, or -1 if it does not
178: * appear in the list.
179: */
180: public int getIndex(String qName);
181:
182: /**
183: * Look up an attribute's type by Namespace name.
184: *
185: * <p>See {@link #getType(int) getType(int)} for a description
186: * of the possible types.</p>
187: *
188: * @param uri The Namespace URI, or the empty String if the
189: * name has no Namespace URI.
190: * @param localName The local name of the attribute.
191: * @return The attribute type as a string, or null if the
192: * attribute is not in the list or if Namespace
193: * processing is not being performed.
194: */
195: public abstract String getType(String uri, String localName);
196:
197: /**
198: * Look up an attribute's type by XML 1.0 qualified name.
199: *
200: * <p>See {@link #getType(int) getType(int)} for a description
201: * of the possible types.</p>
202: *
203: * @param qName The XML 1.0 qualified name.
204: * @return The attribute type as a string, or null if the
205: * attribute is not in the list or if qualified names
206: * are not available.
207: */
208: public abstract String getType(String qName);
209:
210: /**
211: * Look up an attribute's value by Namespace name.
212: *
213: * <p>See {@link #getValue(int) getValue(int)} for a description
214: * of the possible values.</p>
215: *
216: * @param uri The Namespace URI, or the empty String if the
217: * name has no Namespace URI.
218: * @param localName The local name of the attribute.
219: * @return The attribute value as a string, or null if the
220: * attribute is not in the list.
221: */
222: public abstract String getValue(String uri, String localName);
223:
224: /**
225: * Look up an attribute's value by XML 1.0 qualified name.
226: *
227: * <p>See {@link #getValue(int) getValue(int)} for a description
228: * of the possible values.</p>
229: *
230: * @param qName The XML 1.0 qualified name.
231: * @return The attribute value as a string, or null if the
232: * attribute is not in the list or if qualified names
233: * are not available.
234: */
235: public abstract String getValue(String qName);
236:
237: }
238:
239: // end of Attributes.java
|