Class | Line # | Actions | ||||
---|---|---|---|---|---|---|
AttributeList | 72 | 0 | 0 | 0 |
1 | // SAX Attribute List Interface. | |
2 | // http://www.saxproject.org | |
3 | // No warranty; no copyright -- use this as you will. | |
4 | // $Id: AttributeList.java,v 1.7 2004/04/26 17:34:34 dmegginson Exp $ | |
5 | ||
6 | package org.xml.sax; | |
7 | ||
8 | /** | |
9 | * Interface for an element's attribute specifications. | |
10 | * | |
11 | * <blockquote> | |
12 | * <em>This module, both source code and documentation, is in the | |
13 | * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em> | |
14 | * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a> | |
15 | * for further information. | |
16 | * </blockquote> | |
17 | * | |
18 | * <p>This is the original SAX1 interface for reporting an element's | |
19 | * attributes. Unlike the new {@link org.xml.sax.Attributes Attributes} | |
20 | * interface, it does not support Namespace-related information.</p> | |
21 | * | |
22 | * <p>When an attribute list is supplied as part of a | |
23 | * {@link org.xml.sax.DocumentHandler#startElement startElement} | |
24 | * event, the list will return valid results only during the | |
25 | * scope of the event; once the event handler returns control | |
26 | * to the parser, the attribute list is invalid. To save a | |
27 | * persistent copy of the attribute list, use the SAX1 | |
28 | * {@link org.xml.sax.helpers.AttributeListImpl AttributeListImpl} | |
29 | * helper class.</p> | |
30 | * | |
31 | * <p>An attribute list includes only attributes that have been | |
32 | * specified or defaulted: #IMPLIED attributes will not be included.</p> | |
33 | * | |
34 | * <p>There are two ways for the SAX application to obtain information | |
35 | * from the AttributeList. First, it can iterate through the entire | |
36 | * list:</p> | |
37 | * | |
38 | * <pre> | |
39 | * public void startElement (String name, AttributeList atts) { | |
40 | * for (int i = 0; i < atts.getLength(); i++) { | |
41 | * String name = atts.getName(i); | |
42 | * String type = atts.getType(i); | |
43 | * String value = atts.getValue(i); | |
44 | * [...] | |
45 | * } | |
46 | * } | |
47 | * </pre> | |
48 | * | |
49 | * <p>(Note that the result of getLength() will be zero if there | |
50 | * are no attributes.) | |
51 | * | |
52 | * <p>As an alternative, the application can request the value or | |
53 | * type of specific attributes:</p> | |
54 | * | |
55 | * <pre> | |
56 | * public void startElement (String name, AttributeList atts) { | |
57 | * String identifier = atts.getValue("id"); | |
58 | * String label = atts.getValue("label"); | |
59 | * [...] | |
60 | * } | |
61 | * </pre> | |
62 | * | |
63 | * @deprecated This interface has been replaced by the SAX2 | |
64 | * {@link org.xml.sax.Attributes Attributes} | |
65 | * interface, which includes Namespace support. | |
66 | * @since SAX 1.0 | |
67 | * @author David Megginson | |
68 | * @version 2.0.1 (sax2r2) | |
69 | * @see org.xml.sax.DocumentHandler#startElement startElement | |
70 | * @see org.xml.sax.helpers.AttributeListImpl AttributeListImpl | |
71 | */ | |
72 | public interface AttributeList { | |
73 | ||
74 | ||
75 | //////////////////////////////////////////////////////////////////// | |
76 | // Iteration methods. | |
77 | //////////////////////////////////////////////////////////////////// | |
78 | ||
79 | ||
80 | /** | |
81 | * Return the number of attributes in this list. | |
82 | * | |
83 | * <p>The SAX parser may provide attributes in any | |
84 | * arbitrary order, regardless of the order in which they were | |
85 | * declared or specified. The number of attributes may be | |
86 | * zero.</p> | |
87 | * | |
88 | * @return The number of attributes in the list. | |
89 | */ | |
90 | public abstract int getLength (); | |
91 | ||
92 | ||
93 | /** | |
94 | * Return the name of an attribute in this list (by position). | |
95 | * | |
96 | * <p>The names must be unique: the SAX parser shall not include the | |
97 | * same attribute twice. Attributes without values (those declared | |
98 | * #IMPLIED without a value specified in the start tag) will be | |
99 | * omitted from the list.</p> | |
100 | * | |
101 | * <p>If the attribute name has a namespace prefix, the prefix | |
102 | * will still be attached.</p> | |
103 | * | |
104 | * @param i The index of the attribute in the list (starting at 0). | |
105 | * @return The name of the indexed attribute, or null | |
106 | * if the index is out of range. | |
107 | * @see #getLength | |
108 | */ | |
109 | public abstract String getName (int i); | |
110 | ||
111 | ||
112 | /** | |
113 | * Return the type of an attribute in the list (by position). | |
114 | * | |
115 | * <p>The attribute type is one of the strings "CDATA", "ID", | |
116 | * "IDREF", "IDREFS", "NMTOKEN", "NMTOKENS", "ENTITY", "ENTITIES", | |
117 | * or "NOTATION" (always in upper case).</p> | |
118 | * | |
119 | * <p>If the parser has not read a declaration for the attribute, | |
120 | * or if the parser does not report attribute types, then it must | |
121 | * return the value "CDATA" as stated in the XML 1.0 Recommentation | |
122 | * (clause 3.3.3, "Attribute-Value Normalization").</p> | |
123 | * | |
124 | * <p>For an enumerated attribute that is not a notation, the | |
125 | * parser will report the type as "NMTOKEN".</p> | |
126 | * | |
127 | * @param i The index of the attribute in the list (starting at 0). | |
128 | * @return The attribute type as a string, or | |
129 | * null if the index is out of range. | |
130 | * @see #getLength | |
131 | * @see #getType(java.lang.String) | |
132 | */ | |
133 | public abstract String getType (int i); | |
134 | ||
135 | ||
136 | /** | |
137 | * Return the value of an attribute in the list (by position). | |
138 | * | |
139 | * <p>If the attribute value is a list of tokens (IDREFS, | |
140 | * ENTITIES, or NMTOKENS), the tokens will be concatenated | |
141 | * into a single string separated by whitespace.</p> | |
142 | * | |
143 | * @param i The index of the attribute in the list (starting at 0). | |
144 | * @return The attribute value as a string, or | |
145 | * null if the index is out of range. | |
146 | * @see #getLength | |
147 | * @see #getValue(java.lang.String) | |
148 | */ | |
149 | public abstract String getValue (int i); | |
150 | ||
151 | ||
152 | ||
153 | //////////////////////////////////////////////////////////////////// | |
154 | // Lookup methods. | |
155 | //////////////////////////////////////////////////////////////////// | |
156 | ||
157 | ||
158 | /** | |
159 | * Return the type of an attribute in the list (by name). | |
160 | * | |
161 | * <p>The return value is the same as the return value for | |
162 | * getType(int).</p> | |
163 | * | |
164 | * <p>If the attribute name has a namespace prefix in the document, | |
165 | * the application must include the prefix here.</p> | |
166 | * | |
167 | * @param name The name of the attribute. | |
168 | * @return The attribute type as a string, or null if no | |
169 | * such attribute exists. | |
170 | * @see #getType(int) | |
171 | */ | |
172 | public abstract String getType (String name); | |
173 | ||
174 | ||
175 | /** | |
176 | * Return the value of an attribute in the list (by name). | |
177 | * | |
178 | * <p>The return value is the same as the return value for | |
179 | * getValue(int).</p> | |
180 | * | |
181 | * <p>If the attribute name has a namespace prefix in the document, | |
182 | * the application must include the prefix here.</p> | |
183 | * | |
184 | * @param name the name of the attribute to return | |
185 | * @return The attribute value as a string, or null if | |
186 | * no such attribute exists. | |
187 | * @see #getValue(int) | |
188 | */ | |
189 | public abstract String getValue (String name); | |
190 | ||
191 | } | |
192 | ||
193 | // end of AttributeList.java |