001: // Attributes.java - attribute list with Namespace support
002: // Written by David Megginson, sax@megginson.com
003: // NO WARRANTY! This class is in the public domain.
004:
005: // $Id$
006:
007: package org.xml.sax;
008:
009: /**
010: * Interface for a list of XML attributes.
011: *
012: * <blockquote>
013: * <em>This module, both source code and documentation, is in the
014: * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
015: * </blockquote>
016: *
017: * <p>This interface allows access to a list of attributes in
018: * three different ways:</p>
019: *
020: * <ol>
021: * <li>by attribute index;</li>
022: * <li>by Namespace-qualified name; or</li>
023: * <li>by qualified (prefixed) name.</li>
024: * </ol>
025: *
026: * <p>The list will not contain attributes that were declared
027: * #IMPLIED but not specified in the start tag. It will also not
028: * contain attributes used as Namespace declarations (xmlns*) unless
029: * the <code>http://xml.org/sax/features/namespace-prefixes</code>
030: * feature is set to <var>true</var> (it is <var>false</var> by
031: * default).</p>
032: *
033: * <p>If the namespace-prefixes feature (see above) is <var>false</var>,
034: * access by qualified name may not be available; if the
035: * <code>http://xml.org/sax/features/namespaces</code>
036: * feature is <var>false</var>, access by Namespace-qualified names
037: * may not be available.</p>
038: *
039: * <p>This interface replaces the now-deprecated SAX1 {@link
040: * org.xml.sax.AttributeList AttributeList} interface, which does not
041: * contain Namespace support. In addition to Namespace support, it
042: * adds the <var>getIndex</var> methods (below).</p>
043: *
044: * <p>The order of attributes in the list is unspecified, and will
045: * vary from implementation to implementation.</p>
046: *
047: * @since SAX 2.0
048: * @author David Megginson,
049: * <a href="mailto:sax@megginson.com">sax@megginson.com</a>
050: * @version 2.0
051: * @see org.xml.sax.helpers.AttributeListImpl
052: */
053: public interface Attributes {
054:
055: ////////////////////////////////////////////////////////////////////
056: // Indexed access.
057: ////////////////////////////////////////////////////////////////////
058:
059: /**
060: * Return the number of attributes in the list.
061: *
062: * <p>Once you know the number of attributes, you can iterate
063: * through the list.</p>
064: *
065: * @return The number of attributes in the list.
066: * @see #getURI(int)
067: * @see #getLocalName(int)
068: * @see #getQName(int)
069: * @see #getType(int)
070: * @see #getValue(int)
071: */
072: public abstract int getLength();
073:
074: /**
075: * Look up an attribute's Namespace URI by index.
076: *
077: * @param index The attribute index (zero-based).
078: * @return The Namespace URI, or the empty string if none
079: * is available, or null if the index is out of
080: * range.
081: * @see #getLength
082: */
083: public abstract String getURI(int index);
084:
085: /**
086: * Look up an attribute's local name by index.
087: *
088: * @param index The attribute index (zero-based).
089: * @return The local name, or the empty string if Namespace
090: * processing is not being performed, or null
091: * if the index is out of range.
092: * @see #getLength
093: */
094: public abstract String getLocalName(int index);
095:
096: /**
097: * Look up an attribute's XML 1.0 qualified name by index.
098: *
099: * @param index The attribute index (zero-based).
100: * @return The XML 1.0 qualified name, or the empty string
101: * if none is available, or null if the index
102: * is out of range.
103: * @see #getLength
104: */
105: public abstract String getQName(int index);
106:
107: /**
108: * Look up an attribute's type by index.
109: *
110: * <p>The attribute type is one of the strings "CDATA", "ID",
111: * "IDREF", "IDREFS", "NMTOKEN", "NMTOKENS", "ENTITY", "ENTITIES",
112: * or "NOTATION" (always in upper case).</p>
113: *
114: * <p>If the parser has not read a declaration for the attribute,
115: * or if the parser does not report attribute types, then it must
116: * return the value "CDATA" as stated in the XML 1.0 Recommentation
117: * (clause 3.3.3, "Attribute-Value Normalization").</p>
118: *
119: * <p>For an enumerated attribute that is not a notation, the
120: * parser will report the type as "NMTOKEN".</p>
121: *
122: * @param index The attribute index (zero-based).
123: * @return The attribute's type as a string, or null if the
124: * index is out of range.
125: * @see #getLength
126: */
127: public abstract String getType(int index);
128:
129: /**
130: * Look up an attribute's value by index.
131: *
132: * <p>If the attribute value is a list of tokens (IDREFS,
133: * ENTITIES, or NMTOKENS), the tokens will be concatenated
134: * into a single string with each token separated by a
135: * single space.</p>
136: *
137: * @param index The attribute index (zero-based).
138: * @return The attribute's value as a string, or null if the
139: * index is out of range.
140: * @see #getLength
141: */
142: public abstract String getValue(int index);
143:
144: ////////////////////////////////////////////////////////////////////
145: // Name-based query.
146: ////////////////////////////////////////////////////////////////////
147:
148: /**
149: * Look up the index of an attribute by Namespace name.
150: *
151: * @param uri The Namespace URI, or the empty string if
152: * the name has no Namespace URI.
153: * @param localName The attribute's local name.
154: * @return The index of the attribute, or -1 if it does not
155: * appear in the list.
156: */
157: public int getIndex(String uri, String localPart);
158:
159: /**
160: * Look up the index of an attribute by XML 1.0 qualified name.
161: *
162: * @param qName The qualified (prefixed) name.
163: * @return The index of the attribute, or -1 if it does not
164: * appear in the list.
165: */
166: public int getIndex(String qName);
167:
168: /**
169: * Look up an attribute's type by Namespace name.
170: *
171: * <p>See {@link #getType(int) getType(int)} for a description
172: * of the possible types.</p>
173: *
174: * @param uri The Namespace URI, or the empty String if the
175: * name has no Namespace URI.
176: * @param localName The local name of the attribute.
177: * @return The attribute type as a string, or null if the
178: * attribute is not in the list or if Namespace
179: * processing is not being performed.
180: */
181: public abstract String getType(String uri, String localName);
182:
183: /**
184: * Look up an attribute's type by XML 1.0 qualified name.
185: *
186: * <p>See {@link #getType(int) getType(int)} for a description
187: * of the possible types.</p>
188: *
189: * @param qName The XML 1.0 qualified name.
190: * @return The attribute type as a string, or null if the
191: * attribute is not in the list or if qualified names
192: * are not available.
193: */
194: public abstract String getType(String qName);
195:
196: /**
197: * Look up an attribute's value by Namespace name.
198: *
199: * <p>See {@link #getValue(int) getValue(int)} for a description
200: * of the possible values.</p>
201: *
202: * @param uri The Namespace URI, or the empty String if the
203: * name has no Namespace URI.
204: * @param localName The local name of the attribute.
205: * @return The attribute value as a string, or null if the
206: * attribute is not in the list.
207: */
208: public abstract String getValue(String uri, String localName);
209:
210: /**
211: * Look up an attribute's value by XML 1.0 qualified name.
212: *
213: * <p>See {@link #getValue(int) getValue(int)} for a description
214: * of the possible values.</p>
215: *
216: * @param qName The XML 1.0 qualified name.
217: * @return The attribute value as a string, or null if the
218: * attribute is not in the list or if qualified names
219: * are not available.
220: */
221: public abstract String getValue(String qName);
222:
223: }
224:
225: // end of Attributes.java
|