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