1 /*
2 * reserved comment block
3 * DO NOT REMOVE OR ALTER!
4 */
5 /*
6 * The Apache Software License, Version 1.1
7 *
8 *
9 * Copyright (c) 2000-2002 The Apache Software Foundation. All rights
10 * reserved.
11 *
12 * Redistribution and use in source and binary forms, with or without
13 * modification, are permitted provided that the following conditions
14 * are met:
15 *
16 * 1. Redistributions of source code must retain the above copyright
17 * notice, this list of conditions and the following disclaimer.
18 *
19 * 2. Redistributions in binary form must reproduce the above copyright
20 * notice, this list of conditions and the following disclaimer in
21 * the documentation and/or other materials provided with the
22 * distribution.
23 *
24 * 3. The end-user documentation included with the redistribution,
25 * if any, must include the following acknowledgment:
26 * "This product includes software developed by the
27 * Apache Software Foundation (http://www.apache.org/)."
28 * Alternately, this acknowledgment may appear in the software itself,
29 * if and wherever such third-party acknowledgments normally appear.
30 *
31 * 4. The names "Xerces" and "Apache Software Foundation" must
32 * not be used to endorse or promote products derived from this
33 * software without prior written permission. For written
34 * permission, please contact apache@apache.org.
35 *
36 * 5. Products derived from this software may not be called "Apache",
37 * nor may "Apache" appear in their name, without prior written
38 * permission of the Apache Software Foundation.
39 *
40 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
41 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
42 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
43 * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
44 * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
45 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
46 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
47 * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
48 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
49 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
50 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
51 * SUCH DAMAGE.
52 * ====================================================================
53 *
54 * This software consists of voluntary contributions made by many
55 * individuals on behalf of the Apache Software Foundation and was
56 * originally based on software copyright (c) 1999, International
57 * Business Machines, Inc., http://www.apache.org. For more
58 * information on the Apache Software Foundation, please see
59 * <http://www.apache.org/>.
60 */
61
62 package com.sun.org.apache.xerces.internal.xni;
63
64 /**
65 * The XMLAttributes interface defines a collection of attributes for
66 * an element. In the parser, the document source would scan the entire
67 * start element and collect the attributes. The attributes are
68 * communicated to the document handler in the startElement method.
69 * <p>
70 * The attributes are read-write so that subsequent stages in the document
71 * pipeline can modify the values or change the attributes that are
72 * propogated to the next stage.
73 *
74 * @see XMLDocumentHandler#startElement
75 *
76 * @author Andy Clark, IBM
77 *
78 */
79 public interface XMLAttributes {
80
81 //
82 // XMLAttributes methods
83 //
84
85 /**
86 * Adds an attribute. The attribute's non-normalized value of the
87 * attribute will have the same value as the attribute value until
88 * set using the <code>setNonNormalizedValue</code> method. Also,
89 * the added attribute will be marked as specified in the XML instance
90 * document unless set otherwise using the <code>setSpecified</code>
91 * method.
92 * <p>
93 * <strong>Note:</strong> If an attribute of the same name already
94 * exists, the old values for the attribute are replaced by the new
95 * values.
96 *
97 * @param attrName The attribute name.
98 * @param attrType The attribute type. The type name is determined by
99 * the type specified for this attribute in the DTD.
100 * For example: "CDATA", "ID", "NMTOKEN", etc. However,
101 * attributes of type enumeration will have the type
102 * value specified as the pipe ('|') separated list of
103 * the enumeration values prefixed by an open
104 * parenthesis and suffixed by a close parenthesis.
105 * For example: "(true|false)".
106 * @param attrValue The attribute value.
107 *
108 * @return Returns the attribute index.
109 *
110 * @see #setNonNormalizedValue
111 * @see #setSpecified
112 */
113 public int addAttribute(QName attrName, String attrType, String attrValue);
114
115 /**
116 * Removes all of the attributes. This method will also remove all
117 * entities associated to the attributes.
118 */
119 public void removeAllAttributes();
120
121 /**
122 * Removes the attribute at the specified index.
123 * <p>
124 * <strong>Note:</strong> This operation changes the indexes of all
125 * attributes following the attribute at the specified index.
126 *
127 * @param attrIndex The attribute index.
128 */
129 public void removeAttributeAt(int attrIndex);
130
131 /**
132 * Returns the number of attributes in the list.
133 * <p>
134 * Once you know the number of attributes, you can iterate
135 * through the list.
136 *
137 * @see #getURI(int)
138 * @see #getLocalName(int)
139 * @see #getQName(int)
140 * @see #getType(int)
141 * @see #getValue(int)
142 */
143 public int getLength();
144
145 /**
146 * Look up the index of an attribute by XML 1.0 qualified name.
147 *
148 * @param qName The qualified (prefixed) name.
149 *
150 * @return The index of the attribute, or -1 if it does not
151 * appear in the list.
152 */
153 public int getIndex(String qName);
154
155 /**
156 * Look up the index of an attribute by Namespace name.
157 *
158 * @param uri The Namespace URI, or the empty string if
159 * the name has no Namespace URI.
160 * @param localName The attribute's local name.
161 *
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 localPart);
166
167 /**
168 * Sets the name of the attribute at the specified index.
169 *
170 * @param attrIndex The attribute index.
171 * @param attrName The new attribute name.
172 */
173 public void setName(int attrIndex, QName attrName);
174
175 /**
176 * Sets the fields in the given QName structure with the values
177 * of the attribute name at the specified index.
178 *
179 * @param attrIndex The attribute index.
180 * @param attrName The attribute name structure to fill in.
181 */
182 public void getName(int attrIndex, QName attrName);
183
184 /**
185 * Returns the prefix of the attribute at the specified index.
186 *
187 * @param index The index of the attribute.
188 */
189 public String getPrefix(int index);
190
191 /**
192 * Look up an attribute's Namespace URI by index.
193 *
194 * @param index The attribute index (zero-based).
195 *
196 * @return The Namespace URI, or the empty string if none
197 * is available, or null if the index is out of
198 * range.
199 *
200 * @see #getLength
201 */
202 public String getURI(int index);
203
204 /**
205 * Look up an attribute's local name by index.
206 *
207 * @param index The attribute index (zero-based).
208 *
209 * @return The local name, or the empty string if Namespace
210 * processing is not being performed, or null
211 * if the index is out of range.
212 *
213 * @see #getLength
214 */
215 public String getLocalName(int index);
216
217 /**
218 * Look up an attribute's XML 1.0 qualified name by index.
219 *
220 * @param index The attribute index (zero-based).
221 *
222 * @return The XML 1.0 qualified name, or the empty string
223 * if none is available, or null if the index
224 * is out of range.
225 *
226 * @see #getLength
227 */
228 public String getQName(int index);
229
230 //why the above method doens't return QName ?
231 public QName getQualifiedName(int index);
232
233
234 /**
235 * Sets the type of the attribute at the specified index.
236 *
237 * @param attrIndex The attribute index.
238 * @param attrType The attribute type. The type name is determined by
239 * the type specified for this attribute in the DTD.
240 * For example: "CDATA", "ID", "NMTOKEN", etc. However,
241 * attributes of type enumeration will have the type
242 * value specified as the pipe ('|') separated list of
243 * the enumeration values prefixed by an open
244 * parenthesis and suffixed by a close parenthesis.
245 * For example: "(true|false)".
246 */
247 public void setType(int attrIndex, String attrType);
248
249 /**
250 * Look up an attribute's type by index.
251 * <p>
252 * The attribute type is one of the strings "CDATA", "ID",
253 * "IDREF", "IDREFS", "NMTOKEN", "NMTOKENS", "ENTITY", "ENTITIES",
254 * or "NOTATION" (always in upper case).
255 * <p>
256 * If the parser has not read a declaration for the attribute,
257 * or if the parser does not report attribute types, then it must
258 * return the value "CDATA" as stated in the XML 1.0 Recommentation
259 * (clause 3.3.3, "Attribute-Value Normalization").
260 * <p>
261 * For an enumerated attribute that is not a notation, the
262 * parser will report the type as "NMTOKEN".
263 *
264 * @param index The attribute index (zero-based).
265 *
266 * @return The attribute's type as a string, or null if the
267 * index is out of range.
268 *
269 * @see #getLength
270 */
271 public String getType(int index);
272
273 /**
274 * Look up an attribute's type by XML 1.0 qualified name.
275 * <p>
276 * See {@link #getType(int) getType(int)} for a description
277 * of the possible types.
278 *
279 * @param qName The XML 1.0 qualified name.
280 *
281 * @return The attribute type as a string, or null if the
282 * attribute is not in the list or if qualified names
283 * are not available.
284 */
285 public String getType(String qName);
286
287 /**
288 * Look up an attribute's type by Namespace name.
289 * <p>
290 * See {@link #getType(int) getType(int)} for a description
291 * of the possible types.
292 *
293 * @param uri The Namespace URI, or the empty String if the
294 * name has no Namespace URI.
295 * @param localName The local name of the attribute.
296 *
297 * @return The attribute type as a string, or null if the
298 * attribute is not in the list or if Namespace
299 * processing is not being performed.
300 */
301 public String getType(String uri, String localName);
302
303 /**
304 * Sets the value of the attribute at the specified index. This
305 * method will overwrite the non-normalized value of the attribute.
306 *
307 * @param attrIndex The attribute index.
308 * @param attrValue The new attribute value.
309 *
310 * @see #setNonNormalizedValue
311 */
312 public void setValue(int attrIndex, String attrValue);
313
314 public void setValue(int attrIndex, String attrValue, XMLString value);
315
316 /**
317 * Look up an attribute's value by index.
318 * <p>
319 * If the attribute value is a list of tokens (IDREFS,
320 * ENTITIES, or NMTOKENS), the tokens will be concatenated
321 * into a single string with each token separated by a
322 * single space.
323 *
324 * @param index The attribute index (zero-based).
325 *
326 * @return The attribute's value as a string, or null if the
327 * index is out of range.
328 *
329 * @see #getLength
330 */
331 public String getValue(int index);
332
333 /**
334 * Look up an attribute's value by XML 1.0 qualified name.
335 * <p>
336 * See {@link #getValue(int) getValue(int)} for a description
337 * of the possible values.
338 *
339 * @param qName The XML 1.0 qualified name.
340 *
341 * @return The attribute value as a string, or null if the
342 * attribute is not in the list or if qualified names
343 * are not available.
344 */
345 public String getValue(String qName);
346
347 /**
348 * Look up an attribute's value by Namespace name.
349 * <p>
350 * See {@link #getValue(int) getValue(int)} for a description
351 * of the possible values.
352 *
353 * @param uri The Namespace URI, or the empty String if the
354 * name has no Namespace URI.
355 * @param localName The local name of the attribute.
356 *
357 * @return The attribute value as a string, or null if the
358 * attribute is not in the list.
359 */
360 public String getValue(String uri, String localName);
361
362 /**
363 * Sets the non-normalized value of the attribute at the specified
364 * index.
365 *
366 * @param attrIndex The attribute index.
367 * @param attrValue The new non-normalized attribute value.
368 */
369 public void setNonNormalizedValue(int attrIndex, String attrValue);
370
371 /**
372 * Returns the non-normalized value of the attribute at the specified
373 * index. If no non-normalized value is set, this method will return
374 * the same value as the <code>getValue(int)</code> method.
375 *
376 * @param attrIndex The attribute index.
377 */
378 public String getNonNormalizedValue(int attrIndex);
379
380 /**
381 * Sets whether an attribute is specified in the instance document
382 * or not.
383 *
384 * @param attrIndex The attribute index.
385 * @param specified True if the attribute is specified in the instance
386 * document.
387 */
388 public void setSpecified(int attrIndex, boolean specified);
389
390 /**
391 * Returns true if the attribute is specified in the instance document.
392 *
393 * @param attrIndex The attribute index.
394 */
395 public boolean isSpecified(int attrIndex);
396
397
398 /**
399 * Look up an augmentation by attribute's index.
400 *
401 * @param attributeIndex The attribute index.
402 * @return Augmentations
403 */
404 public Augmentations getAugmentations (int attributeIndex);
405
406 /**
407 * Look up an augmentation by namespace name.
408 *
409 * @param uri The Namespace URI, or the empty string if
410 * the name has no Namespace URI.
411 * @param localPart
412 * @return Augmentations
413 */
414 public Augmentations getAugmentations (String uri, String localPart);
415
416
417 /**
418 * Look up an augmentation by XML 1.0 qualified name.
419 * <p>
420 *
421 * @param qName The XML 1.0 qualified name.
422 *
423 * @return Augmentations
424 *
425 */
426 public Augmentations getAugmentations(String qName);
427
428 /**
429 * Sets the augmentations of the attribute at the specified index.
430 *
431 * @param attrIndex The attribute index.
432 * @param augs The augmentations.
433 */
434 public void setAugmentations(int attrIndex, Augmentations augs);
435
436
437
438
439 } // interface XMLAttributes