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