1 /*
2 * reserved comment block
3 * DO NOT REMOVE OR ALTER!
4 */
5 /*
6 * Licensed to the Apache Software Foundation (ASF) under one or more
7 * contributor license agreements. See the NOTICE file distributed with
8 * this work for additional information regarding copyright ownership.
9 * The ASF licenses this file to You under the Apache License, Version 2.0
10 * (the "License"); you may not use this file except in compliance with
11 * the License. You may obtain a copy of the License at
12 *
13 * http://www.apache.org/licenses/LICENSE-2.0
14 *
15 * Unless required by applicable law or agreed to in writing, software
16 * distributed under the License is distributed on an "AS IS" BASIS,
17 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
18 * See the License for the specific language governing permissions and
19 * limitations under the License.
20 */
21
22 package com.sun.org.apache.xerces.internal.xni;
23
24 /**
25 * The XMLAttributes interface defines a collection of attributes for
26 * an element. In the parser, the document source would scan the entire
27 * start element and collect the attributes. The attributes are
28 * communicated to the document handler in the startElement method.
29 * <p>
30 * The attributes are read-write so that subsequent stages in the document
31 * pipeline can modify the values or change the attributes that are
32 * propogated to the next stage.
33 *
34 * @see XMLDocumentHandler#startElement
35 *
36 * @author Andy Clark, IBM
37 *
38 */
39 public interface XMLAttributes {
40
41 //
42 // XMLAttributes methods
43 //
44
45 /**
46 * Adds an attribute. The attribute's non-normalized value of the
47 * attribute will have the same value as the attribute value until
48 * set using the <code>setNonNormalizedValue</code> method. Also,
49 * the added attribute will be marked as specified in the XML instance
50 * document unless set otherwise using the <code>setSpecified</code>
51 * method.
52 * <p>
53 * <strong>Note:</strong> If an attribute of the same name already
54 * exists, the old values for the attribute are replaced by the new
55 * values.
56 *
57 * @param attrName The attribute name.
58 * @param attrType The attribute type. The type name is determined by
59 * the type specified for this attribute in the DTD.
60 * For example: "CDATA", "ID", "NMTOKEN", etc. However,
61 * attributes of type enumeration will have the type
62 * value specified as the pipe ('|') separated list of
63 * the enumeration values prefixed by an open
64 * parenthesis and suffixed by a close parenthesis.
65 * For example: "(true|false)".
66 * @param attrValue The attribute value.
67 *
68 * @return Returns the attribute index.
69 *
70 * @see #setNonNormalizedValue
71 * @see #setSpecified
72 */
73 public int addAttribute(QName attrName, String attrType, String attrValue);
74
75 /**
76 * Removes all of the attributes. This method will also remove all
77 * entities associated to the attributes.
78 */
79 public void removeAllAttributes();
80
81 /**
82 * Removes the attribute at the specified index.
83 * <p>
84 * <strong>Note:</strong> This operation changes the indexes of all
85 * attributes following the attribute at the specified index.
86 *
87 * @param attrIndex The attribute index.
88 */
89 public void removeAttributeAt(int attrIndex);
90
91 /**
92 * Returns the number of attributes in the list.
93 * <p>
94 * Once you know the number of attributes, you can iterate
95 * through the list.
96 *
97 * @see #getURI(int)
98 * @see #getLocalName(int)
99 * @see #getQName(int)
100 * @see #getType(int)
101 * @see #getValue(int)
102 */
103 public int getLength();
104
105 /**
106 * Look up the index of an attribute by XML 1.0 qualified name.
107 *
108 * @param qName The qualified (prefixed) name.
109 *
110 * @return The index of the attribute, or -1 if it does not
111 * appear in the list.
112 */
113 public int getIndex(String qName);
114
115 /**
116 * Look up the index of an attribute by Namespace name.
117 *
118 * @param uri The Namespace URI, or the empty string if
119 * the name has no Namespace URI.
120 * @param localName The attribute's local name.
121 *
122 * @return The index of the attribute, or -1 if it does not
123 * appear in the list.
124 */
125 public int getIndex(String uri, String localPart);
126
127 /**
128 * Sets the name of the attribute at the specified index.
129 *
130 * @param attrIndex The attribute index.
131 * @param attrName The new attribute name.
132 */
133 public void setName(int attrIndex, QName attrName);
134
135 /**
136 * Sets the fields in the given QName structure with the values
137 * of the attribute name at the specified index.
138 *
139 * @param attrIndex The attribute index.
140 * @param attrName The attribute name structure to fill in.
141 */
142 public void getName(int attrIndex, QName attrName);
143
144 /**
145 * Returns the prefix of the attribute at the specified index.
146 *
147 * @param index The index of the attribute.
148 */
149 public String getPrefix(int index);
150
151 /**
152 * Look up an attribute's Namespace URI by index.
153 *
154 * @param index The attribute index (zero-based).
155 *
156 * @return The Namespace URI, or the empty string if none
157 * is available, or null if the index is out of
158 * range.
159 *
160 * @see #getLength
161 */
162 public String getURI(int index);
163
164 /**
165 * Look up an attribute's local name by index.
166 *
167 * @param index The attribute index (zero-based).
168 *
169 * @return The local name, or the empty string if Namespace
170 * processing is not being performed, or null
171 * if the index is out of range.
172 *
173 * @see #getLength
174 */
175 public String getLocalName(int index);
176
177 /**
178 * Look up an attribute's XML 1.0 qualified name by index.
179 *
180 * @param index The attribute index (zero-based).
181 *
182 * @return The XML 1.0 qualified name, or the empty string
183 * if none is available, or null if the index
184 * is out of range.
185 *
186 * @see #getLength
187 */
188 public String getQName(int index);
189
190 //why the above method doens't return QName ?
191 public QName getQualifiedName(int index);
192
193
194 /**
195 * Sets the type of the attribute at the specified index.
196 *
197 * @param attrIndex The attribute index.
198 * @param attrType The attribute type. The type name is determined by
199 * the type specified for this attribute in the DTD.
200 * For example: "CDATA", "ID", "NMTOKEN", etc. However,
201 * attributes of type enumeration will have the type
202 * value specified as the pipe ('|') separated list of
203 * the enumeration values prefixed by an open
204 * parenthesis and suffixed by a close parenthesis.
205 * For example: "(true|false)".
206 */
207 public void setType(int attrIndex, String attrType);
208
209 /**
210 * Look up an attribute's type by index.
211 * <p>
212 * The attribute type is one of the strings "CDATA", "ID",
213 * "IDREF", "IDREFS", "NMTOKEN", "NMTOKENS", "ENTITY", "ENTITIES",
214 * or "NOTATION" (always in upper case).
215 * <p>
216 * If the parser has not read a declaration for the attribute,
217 * or if the parser does not report attribute types, then it must
218 * return the value "CDATA" as stated in the XML 1.0 Recommentation
219 * (clause 3.3.3, "Attribute-Value Normalization").
220 * <p>
221 * For an enumerated attribute that is not a notation, the
222 * parser will report the type as "NMTOKEN".
223 *
224 * @param index The attribute index (zero-based).
225 *
226 * @return The attribute's type as a string, or null if the
227 * index is out of range.
228 *
229 * @see #getLength
230 */
231 public String getType(int index);
232
233 /**
234 * Look up an attribute's type by XML 1.0 qualified name.
235 * <p>
236 * See {@link #getType(int) getType(int)} for a description
237 * of the possible types.
238 *
239 * @param qName The XML 1.0 qualified name.
240 *
241 * @return The attribute type as a string, or null if the
242 * attribute is not in the list or if qualified names
243 * are not available.
244 */
245 public String getType(String qName);
246
247 /**
248 * Look up an attribute's type by Namespace name.
249 * <p>
250 * See {@link #getType(int) getType(int)} for a description
251 * of the possible types.
252 *
253 * @param uri The Namespace URI, or the empty String if the
254 * name has no Namespace URI.
255 * @param localName The local name of the attribute.
256 *
257 * @return The attribute type as a string, or null if the
258 * attribute is not in the list or if Namespace
259 * processing is not being performed.
260 */
261 public String getType(String uri, String localName);
262
263 /**
264 * Sets the value of the attribute at the specified index. This
265 * method will overwrite the non-normalized value of the attribute.
266 *
267 * @param attrIndex The attribute index.
268 * @param attrValue The new attribute value.
269 *
270 * @see #setNonNormalizedValue
271 */
272 public void setValue(int attrIndex, String attrValue);
273
274 public void setValue(int attrIndex, String attrValue, XMLString value);
275
276 /**
277 * Look up an attribute's value by index.
278 * <p>
279 * If the attribute value is a list of tokens (IDREFS,
280 * ENTITIES, or NMTOKENS), the tokens will be concatenated
281 * into a single string with each token separated by a
282 * single space.
283 *
284 * @param index The attribute index (zero-based).
285 *
286 * @return The attribute's value as a string, or null if the
287 * index is out of range.
288 *
289 * @see #getLength
290 */
291 public String getValue(int index);
292
293 /**
294 * Look up an attribute's value by XML 1.0 qualified name.
295 * <p>
296 * See {@link #getValue(int) getValue(int)} for a description
297 * of the possible values.
298 *
299 * @param qName The XML 1.0 qualified name.
300 *
301 * @return The attribute value as a string, or null if the
302 * attribute is not in the list or if qualified names
303 * are not available.
304 */
305 public String getValue(String qName);
306
307 /**
308 * Look up an attribute's value by Namespace name.
309 * <p>
310 * See {@link #getValue(int) getValue(int)} for a description
311 * of the possible values.
312 *
313 * @param uri The Namespace URI, or the empty String if the
314 * name has no Namespace URI.
315 * @param localName The local name of the attribute.
316 *
317 * @return The attribute value as a string, or null if the
318 * attribute is not in the list.
319 */
320 public String getValue(String uri, String localName);
321
322 /**
323 * Sets the non-normalized value of the attribute at the specified
324 * index.
325 *
326 * @param attrIndex The attribute index.
327 * @param attrValue The new non-normalized attribute value.
328 */
329 public void setNonNormalizedValue(int attrIndex, String attrValue);
330
331 /**
332 * Returns the non-normalized value of the attribute at the specified
333 * index. If no non-normalized value is set, this method will return
334 * the same value as the <code>getValue(int)</code> method.
335 *
336 * @param attrIndex The attribute index.
337 */
338 public String getNonNormalizedValue(int attrIndex);
339
340 /**
341 * Sets whether an attribute is specified in the instance document
342 * or not.
343 *
344 * @param attrIndex The attribute index.
345 * @param specified True if the attribute is specified in the instance
346 * document.
347 */
348 public void setSpecified(int attrIndex, boolean specified);
349
350 /**
351 * Returns true if the attribute is specified in the instance document.
352 *
353 * @param attrIndex The attribute index.
354 */
355 public boolean isSpecified(int attrIndex);
356
357
358 /**
359 * Look up an augmentation by attribute's index.
360 *
361 * @param attributeIndex The attribute index.
362 * @return Augmentations
363 */
364 public Augmentations getAugmentations (int attributeIndex);
365
366 /**
367 * Look up an augmentation by namespace name.
368 *
369 * @param uri The Namespace URI, or the empty string if
370 * the name has no Namespace URI.
371 * @param localPart
372 * @return Augmentations
373 */
374 public Augmentations getAugmentations (String uri, String localPart);
375
376
377 /**
378 * Look up an augmentation by XML 1.0 qualified name.
379 * <p>
380 *
381 * @param qName The XML 1.0 qualified name.
382 *
383 * @return Augmentations
384 *
385 */
386 public Augmentations getAugmentations(String qName);
387
388 /**
389 * Sets the augmentations of the attribute at the specified index.
390 *
391 * @param attrIndex The attribute index.
392 * @param augs The augmentations.
393 */
394 public void setAugmentations(int attrIndex, Augmentations augs);
395
396
397
398
399 } // interface XMLAttributes