001: // SAX Attribute List Interface.
002: // No warranty; no copyright -- use this as you will.
003: // $Id$
004:
005: package org.xml.sax;
006:
007: /**
008: * Interface for an element's attribute specifications.
009: *
010: * <blockquote>
011: * <em>This module, both source code and documentation, is in the
012: * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
013: * </blockquote>
014: *
015: * <p>This is the original SAX1 interface for reporting an element's
016: * attributes. Unlike the new {@link org.xml.sax.Attributes Attributes}
017: * interface, it does not support Namespace-related information.</p>
018: *
019: * <p>When an attribute list is supplied as part of a
020: * {@link org.xml.sax.DocumentHandler#startElement startElement}
021: * event, the list will return valid results only during the
022: * scope of the event; once the event handler returns control
023: * to the parser, the attribute list is invalid. To save a
024: * persistent copy of the attribute list, use the SAX1
025: * {@link org.xml.sax.helpers.AttributeListImpl AttributeListImpl}
026: * helper class.</p>
027: *
028: * <p>An attribute list includes only attributes that have been
029: * specified or defaulted: #IMPLIED attributes will not be included.</p>
030: *
031: * <p>There are two ways for the SAX application to obtain information
032: * from the AttributeList. First, it can iterate through the entire
033: * list:</p>
034: *
035: * <pre>
036: * public void startElement (String name, AttributeList atts) {
037: * for (int i = 0; i < atts.getLength(); i++) {
038: * String name = atts.getName(i);
039: * String type = atts.getType(i);
040: * String value = atts.getValue(i);
041: * [...]
042: * }
043: * }
044: * </pre>
045: *
046: * <p>(Note that the result of getLength() will be zero if there
047: * are no attributes.)
048: *
049: * <p>As an alternative, the application can request the value or
050: * type of specific attributes:</p>
051: *
052: * <pre>
053: * public void startElement (String name, AttributeList atts) {
054: * String identifier = atts.getValue("id");
055: * String label = atts.getValue("label");
056: * [...]
057: * }
058: * </pre>
059: *
060: * @deprecated This interface has been replaced by the SAX2
061: * {@link org.xml.sax.Attributes Attributes}
062: * interface, which includes Namespace support.
063: * @since SAX 1.0
064: * @author David Megginson,
065: * <a href="mailto:sax@megginson.com">sax@megginson.com</a>
066: * @version 2.0
067: * @see org.xml.sax.DocumentHandler#startElement startElement
068: * @see org.xml.sax.helpers.AttributeListImpl AttributeListImpl
069: */
070: public interface AttributeList {
071:
072: ////////////////////////////////////////////////////////////////////
073: // Iteration methods.
074: ////////////////////////////////////////////////////////////////////
075:
076: /**
077: * Return the number of attributes in this list.
078: *
079: * <p>The SAX parser may provide attributes in any
080: * arbitrary order, regardless of the order in which they were
081: * declared or specified. The number of attributes may be
082: * zero.</p>
083: *
084: * @return The number of attributes in the list.
085: */
086: public abstract int getLength();
087:
088: /**
089: * Return the name of an attribute in this list (by position).
090: *
091: * <p>The names must be unique: the SAX parser shall not include the
092: * same attribute twice. Attributes without values (those declared
093: * #IMPLIED without a value specified in the start tag) will be
094: * omitted from the list.</p>
095: *
096: * <p>If the attribute name has a namespace prefix, the prefix
097: * will still be attached.</p>
098: *
099: * @param i The index of the attribute in the list (starting at 0).
100: * @return The name of the indexed attribute, or null
101: * if the index is out of range.
102: * @see #getLength
103: */
104: public abstract String getName(int i);
105:
106: /**
107: * Return the type of an attribute in the list (by position).
108: *
109: * <p>The attribute type is one of the strings "CDATA", "ID",
110: * "IDREF", "IDREFS", "NMTOKEN", "NMTOKENS", "ENTITY", "ENTITIES",
111: * or "NOTATION" (always in upper case).</p>
112: *
113: * <p>If the parser has not read a declaration for the attribute,
114: * or if the parser does not report attribute types, then it must
115: * return the value "CDATA" as stated in the XML 1.0 Recommentation
116: * (clause 3.3.3, "Attribute-Value Normalization").</p>
117: *
118: * <p>For an enumerated attribute that is not a notation, the
119: * parser will report the type as "NMTOKEN".</p>
120: *
121: * @param i The index of the attribute in the list (starting at 0).
122: * @return The attribute type as a string, or
123: * null if the index is out of range.
124: * @see #getLength
125: * @see #getType(java.lang.String)
126: */
127: public abstract String getType(int i);
128:
129: /**
130: * Return the value of an attribute in the list (by position).
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 separated by whitespace.</p>
135: *
136: * @param i The index of the attribute in the list (starting at 0).
137: * @return The attribute value as a string, or
138: * null if the index is out of range.
139: * @see #getLength
140: * @see #getValue(java.lang.String)
141: */
142: public abstract String getValue(int i);
143:
144: ////////////////////////////////////////////////////////////////////
145: // Lookup methods.
146: ////////////////////////////////////////////////////////////////////
147:
148: /**
149: * Return the type of an attribute in the list (by name).
150: *
151: * <p>The return value is the same as the return value for
152: * getType(int).</p>
153: *
154: * <p>If the attribute name has a namespace prefix in the document,
155: * the application must include the prefix here.</p>
156: *
157: * @param name The name of the attribute.
158: * @return The attribute type as a string, or null if no
159: * such attribute exists.
160: * @see #getType(int)
161: */
162: public abstract String getType(String name);
163:
164: /**
165: * Return the value of an attribute in the list (by name).
166: *
167: * <p>The return value is the same as the return value for
168: * getValue(int).</p>
169: *
170: * <p>If the attribute name has a namespace prefix in the document,
171: * the application must include the prefix here.</p>
172: *
173: * @param i The index of the attribute in the list.
174: * @return The attribute value as a string, or null if
175: * no such attribute exists.
176: * @see #getValue(int)
177: */
178: public abstract String getValue(String name);
179:
180: }
181:
182: // end of AttributeList.java
|