001: // Attributes.java - attribute list with Namespace support
002: // http://www.saxproject.org
003: // Written by David Megginson
004: // NO WARRANTY! This class is in the public domain.
005:
006: package org.xml.sax;
007:
008: /**
009: * Interface for a list of XML attributes.
010: *
011: * <blockquote>
012: * <em>This module, both source code and documentation, is in the
013: * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
014: * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
015: * for further information.
016: * </blockquote>
017: *
018: * <p>This interface allows access to a list of attributes in
019: * three different ways:</p>
020: *
021: * <ol>
022: * <li>by attribute index;</li>
023: * <li>by Namespace-qualified name; or</li>
024: * <li>by qualified (prefixed) name.</li>
025: * </ol>
026: *
027: * <p>The list will not contain attributes that were declared
028: * #IMPLIED but not specified in the start tag. It will also not
029: * contain attributes used as Namespace declarations (xmlns*) unless
030: * the <code>http://xml.org/sax/features/namespace-prefixes</code>
031: * feature is set to <var>true</var> (it is <var>false</var> by
032: * default).
033: * Because SAX2 conforms to the original "Namespaces in XML"
034: * recommendation, it normally does not
035: * give namespace declaration attributes a namespace URI.
036: * </p>
037: *
038: * <p>Some SAX2 parsers may support using an optional feature flag
039: * (<code>http://xml.org/sax/features/xmlns-uris</code>) to request
040: * that those attributes be given URIs, conforming to a later
041: * backwards-incompatible revision of that recommendation. (The
042: * attribute's "local name" will be the prefix, or "xmlns" when
043: * defining a default element namespace.) For portability, handler
044: * code should always resolve that conflict, rather than requiring
045: * parsers that can change the setting of that feature flag. </p>
046: *
047: * <p>If the namespace-prefixes feature (see above) is
048: * <var>false</var>, access by qualified name may not be available; if
049: * the <code>http://xml.org/sax/features/namespaces</code> feature is
050: * <var>false</var>, access by Namespace-qualified names may not be
051: * available.</p>
052: *
053: * <p>This interface replaces the now-deprecated SAX1 {@link
054: * org.xml.sax.AttributeList AttributeList} interface, which does not
055: * contain Namespace support. In addition to Namespace support, it
056: * adds the <var>getIndex</var> methods (below).</p>
057: *
058: * <p>The order of attributes in the list is unspecified, and will
059: * vary from implementation to implementation.</p>
060: *
061: * @since SAX 2.0
062: * @author David Megginson
063: * @version 2.0.1 (sax2r2)
064: * @see org.xml.sax.helpers.SaxAttributes
065: * @see org.xml.sax.ext.DeclHandler#attributeDecl
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 qualified (prefixed) name by index.
112: *
113: * @param index The attribute index (zero-based).
114: * @return The XML 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 Recommendation
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 qualified (prefixed) 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 qualified (prefixed) 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 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 qualified (prefixed) 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 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
|