|
|||||||||||||||||||
Source file | Conditionals | Statements | Methods | TOTAL | |||||||||||||||
Element.java | - | - | - | - |
|
1 | /* | |
2 | * Copyright 2001-2005 (C) MetaStuff, Ltd. All Rights Reserved. | |
3 | * | |
4 | * This software is open source. | |
5 | * See the bottom of this file for the licence. | |
6 | */ | |
7 | ||
8 | package org.dom4j; | |
9 | ||
10 | import java.util.Iterator; | |
11 | import java.util.List; | |
12 | import java.util.Map; | |
13 | ||
14 | /** | |
15 | * <p> | |
16 | * <code>Element</code> interface defines an XML element. An element can have | |
17 | * declared namespaces, attributes, child nodes and textual content. | |
18 | * </p> | |
19 | * | |
20 | * <p> | |
21 | * Some of this interface is optional. Some implementations may be read-only and | |
22 | * not support being modified. Some implementations may not support the parent | |
23 | * relationship and methods such as {@link #getParent}or {@link#getDocument}. | |
24 | * </p> | |
25 | * | |
26 | * @author <a href="mailto:jstrachan@apache.org">James Strachan </a> | |
27 | * @version $Revision: 1.47 $ | |
28 | */ | |
29 | public interface Element extends Branch { | |
30 | // Name and namespace related methods | |
31 | // ------------------------------------------------------------------------- | |
32 | ||
33 | /** | |
34 | * <p> | |
35 | * Returns the <code>QName</code> of this element which represents the | |
36 | * local name, the qualified name and the <code>Namespace</code>. | |
37 | * </p> | |
38 | * | |
39 | * @return the <code>QName</code> associated with this element | |
40 | */ | |
41 | QName getQName(); | |
42 | ||
43 | /** | |
44 | * <p> | |
45 | * Sets the <code>QName</code> of this element which represents the local | |
46 | * name, the qualified name and the <code>Namespace</code>. | |
47 | * </p> | |
48 | * | |
49 | * @param qname | |
50 | * is the <code>QName</code> to be associated with this element | |
51 | */ | |
52 | void setQName(QName qname); | |
53 | ||
54 | /** | |
55 | * <p> | |
56 | * Returns the <code>Namespace</code> of this element if one exists | |
57 | * otherwise <code>Namespace.NO_NAMESPACE</code> is returned. | |
58 | * </p> | |
59 | * | |
60 | * @return the <code>Namespace</code> associated with this element | |
61 | */ | |
62 | Namespace getNamespace(); | |
63 | ||
64 | /** | |
65 | * <p> | |
66 | * Returns the <code>QName</code> for the given qualified name, using the | |
67 | * namespace URI in scope for the given prefix of the qualified name or the | |
68 | * default namespace if the qualified name has no prefix. | |
69 | * </p> | |
70 | * | |
71 | * @param qualifiedName | |
72 | * DOCUMENT ME! | |
73 | * | |
74 | * @return the <code>QName</code> for the given qualified name | |
75 | */ | |
76 | QName getQName(String qualifiedName); | |
77 | ||
78 | /** | |
79 | * <p> | |
80 | * Returns the <code>Namespace</code> which is mapped to the given prefix | |
81 | * or null if it could not be found. | |
82 | * </p> | |
83 | * | |
84 | * @param prefix | |
85 | * DOCUMENT ME! | |
86 | * | |
87 | * @return the <code>Namespace</code> associated with the given prefix | |
88 | */ | |
89 | Namespace getNamespaceForPrefix(String prefix); | |
90 | ||
91 | /** | |
92 | * <p> | |
93 | * Returns the <code>Namespace</code> which is mapped to the given URI or | |
94 | * null if it could not be found. If there is more than one | |
95 | * <code>Namespace</code> mapped to the URI, which of them will be | |
96 | * returned is undetermined. | |
97 | * </p> | |
98 | * | |
99 | * @param uri | |
100 | * DOCUMENT ME! | |
101 | * | |
102 | * @return the <code>Namespace</code> associated with the given URI | |
103 | */ | |
104 | Namespace getNamespaceForURI(String uri); | |
105 | ||
106 | /** | |
107 | * <p> | |
108 | * Returns the all namespaces which are mapped to the given URI or an empty | |
109 | * list if no such namespaces could be found. | |
110 | * </p> | |
111 | * | |
112 | * @param uri | |
113 | * DOCUMENT ME! | |
114 | * | |
115 | * @return the namespaces associated with the given URI | |
116 | * | |
117 | * @since 1.5 | |
118 | */ | |
119 | List getNamespacesForURI(String uri); | |
120 | ||
121 | /** | |
122 | * <p> | |
123 | * Returns the namespace prefix of this element if one exists otherwise an | |
124 | * empty <code>String</code> is returned. | |
125 | * </p> | |
126 | * | |
127 | * @return the prefix of the <code>Namespace</code> of this element or an | |
128 | * empty <code>String</code> | |
129 | */ | |
130 | String getNamespacePrefix(); | |
131 | ||
132 | /** | |
133 | * <p> | |
134 | * Returns the URI mapped to the namespace of this element if one exists | |
135 | * otherwise an empty <code>String</code> is returned. | |
136 | * </p> | |
137 | * | |
138 | * @return the URI for the <code>Namespace</code> of this element or an | |
139 | * empty <code>String</code> | |
140 | */ | |
141 | String getNamespaceURI(); | |
142 | ||
143 | /** | |
144 | * <p> | |
145 | * Returns the fully qualified name of this element. This will be the same | |
146 | * as the value returned from {@link #getName}if this element has no | |
147 | * namespace attached to this element or an expression of the form | |
148 | * | |
149 | * <pre> | |
150 | * getNamespacePrefix() + ":" + getName() | |
151 | * </pre> | |
152 | * | |
153 | * will be returned. | |
154 | * </p> | |
155 | * | |
156 | * @return the fully qualified name of the element. | |
157 | */ | |
158 | String getQualifiedName(); | |
159 | ||
160 | /** | |
161 | * <p> | |
162 | * Returns any additional namespaces declarations for this element other | |
163 | * than namespace returned via the {@link #getNamespace()}method. If no | |
164 | * additional namespace declarations are present for this element then an | |
165 | * empty list will be returned. The list is backed by the element such that | |
166 | * changes to the list will be reflected in the element though the reverse | |
167 | * is not the case. | |
168 | * </p> | |
169 | * | |
170 | * @return a list of any additional namespace declarations. | |
171 | */ | |
172 | List additionalNamespaces(); | |
173 | ||
174 | /** | |
175 | * <p> | |
176 | * Returns all the namespaces declared by this element. If no namespaces are | |
177 | * declared for this element then an empty list will be returned. The list | |
178 | * is backed by the element such that changes to the list will be reflected | |
179 | * in the element though the reverse is not the case. | |
180 | * </p> | |
181 | * | |
182 | * @return a list of namespaces declared for this element. | |
183 | */ | |
184 | List declaredNamespaces(); | |
185 | ||
186 | // Builder methods | |
187 | // ------------------------------------------------------------------------- | |
188 | ||
189 | /** | |
190 | * <p> | |
191 | * Adds the attribute value of the given local name. If an attribute already | |
192 | * exists for the given name it will be replaced. Attributes with null | |
193 | * values are silently ignored. If the value of the attribute is null then | |
194 | * this method call will remove any attributes with the given name. | |
195 | * </p> | |
196 | * | |
197 | * @param name | |
198 | * is the name of the attribute whose value is to be added or | |
199 | * updated | |
200 | * @param value | |
201 | * is the attribute's value | |
202 | * | |
203 | * @return this <code>Element</code> instance. | |
204 | */ | |
205 | Element addAttribute(String name, String value); | |
206 | ||
207 | /** | |
208 | * <p> | |
209 | * Adds the attribute value of the given fully qualified name. If an | |
210 | * attribute already exists for the given name it will be replaced. | |
211 | * Attributes with null values are silently ignored. If the value of the | |
212 | * attribute is null then this method call will remove any attributes with | |
213 | * the given name. | |
214 | * </p> | |
215 | * | |
216 | * @param qName | |
217 | * is the fully qualified name of the attribute whose value is to | |
218 | * be added or updated | |
219 | * @param value | |
220 | * is the attribute's value | |
221 | * | |
222 | * @return this <code>Element</code> instance. | |
223 | */ | |
224 | Element addAttribute(QName qName, String value); | |
225 | ||
226 | /** | |
227 | * Adds a new <code>Comment</code> node with the given text to this | |
228 | * element. | |
229 | * | |
230 | * @param comment | |
231 | * is the text for the <code>Comment</code> node. | |
232 | * | |
233 | * @return this <code>Element</code> instance. | |
234 | */ | |
235 | Element addComment(String comment); | |
236 | ||
237 | /** | |
238 | * Adds a new <code>CDATA</code> node with the given text to this element. | |
239 | * | |
240 | * @param cdata | |
241 | * is the text for the <code>CDATA</code> node. | |
242 | * | |
243 | * @return this <code>Element</code> instance. | |
244 | */ | |
245 | Element addCDATA(String cdata); | |
246 | ||
247 | /** | |
248 | * Adds a new <code>Entity</code> node with the given name and text to | |
249 | * this element and returns a reference to the new node. | |
250 | * | |
251 | * @param name | |
252 | * is the name for the <code>Entity</code> node. | |
253 | * @param text | |
254 | * is the text for the <code>Entity</code> node. | |
255 | * | |
256 | * @return this <code>Element</code> instance. | |
257 | */ | |
258 | Element addEntity(String name, String text); | |
259 | ||
260 | /** | |
261 | * Adds a namespace to this element for use by its child content | |
262 | * | |
263 | * @param prefix | |
264 | * is the prefix to use, which should not be null or blank | |
265 | * @param uri | |
266 | * is the namespace URI | |
267 | * | |
268 | * @return this <code>Element</code> instance. | |
269 | */ | |
270 | Element addNamespace(String prefix, String uri); | |
271 | ||
272 | /** | |
273 | * Adds a processing instruction for the given target | |
274 | * | |
275 | * @param target | |
276 | * is the target of the processing instruction | |
277 | * @param text | |
278 | * is the textual data (key/value pairs) of the processing | |
279 | * instruction | |
280 | * | |
281 | * @return this <code>Element</code> instance. | |
282 | */ | |
283 | Element addProcessingInstruction(String target, String text); | |
284 | ||
285 | /** | |
286 | * Adds a processing instruction for the given target | |
287 | * | |
288 | * @param target | |
289 | * is the target of the processing instruction | |
290 | * @param data | |
291 | * is a Map of the key / value pairs of the processing | |
292 | * instruction | |
293 | * | |
294 | * @return this <code>Element</code> instance. | |
295 | */ | |
296 | Element addProcessingInstruction(String target, Map data); | |
297 | ||
298 | /** | |
299 | * Adds a new <code>Text</code> node with the given text to this element. | |
300 | * | |
301 | * @param text | |
302 | * is the text for the <code>Text</code> node. | |
303 | * | |
304 | * @return this <code>Element</code> instance. | |
305 | */ | |
306 | Element addText(String text); | |
307 | ||
308 | // Typesafe modifying methods | |
309 | // ------------------------------------------------------------------------- | |
310 | ||
311 | /** | |
312 | * Adds the given <code>Attribute</code> to this element. If the given | |
313 | * node already has a parent defined then an | |
314 | * <code>IllegalAddException</code> will be thrown. Attributes with null | |
315 | * values are silently ignored. | |
316 | * | |
317 | * <p> | |
318 | * If the value of the attribute is null then this method call will remove | |
319 | * any attributes with the QName of this attribute. | |
320 | * </p> | |
321 | * | |
322 | * @param attribute | |
323 | * is the attribute to be added | |
324 | */ | |
325 | void add(Attribute attribute); | |
326 | ||
327 | /** | |
328 | * Adds the given <code>CDATA</code> to this element. If the given node | |
329 | * already has a parent defined then an <code>IllegalAddException</code> | |
330 | * will be thrown. | |
331 | * | |
332 | * @param cdata | |
333 | * is the CDATA to be added | |
334 | */ | |
335 | void add(CDATA cdata); | |
336 | ||
337 | /** | |
338 | * Adds the given <code>Entity</code> to this element. If the given node | |
339 | * already has a parent defined then an <code>IllegalAddException</code> | |
340 | * will be thrown. | |
341 | * | |
342 | * @param entity | |
343 | * is the entity to be added | |
344 | */ | |
345 | void add(Entity entity); | |
346 | ||
347 | /** | |
348 | * Adds the given <code>Text</code> to this element. If the given node | |
349 | * already has a parent defined then an <code>IllegalAddException</code> | |
350 | * will be thrown. | |
351 | * | |
352 | * @param text | |
353 | * is the text to be added | |
354 | */ | |
355 | void add(Text text); | |
356 | ||
357 | /** | |
358 | * Adds the given <code>Namespace</code> to this element. If the given | |
359 | * node already has a parent defined then an | |
360 | * <code>IllegalAddException</code> will be thrown. | |
361 | * | |
362 | * @param namespace | |
363 | * is the namespace to be added | |
364 | */ | |
365 | void add(Namespace namespace); | |
366 | ||
367 | /** | |
368 | * Removes the given <code>Attribute</code> from this element. | |
369 | * | |
370 | * @param attribute | |
371 | * is the attribute to be removed | |
372 | * | |
373 | * @return true if the attribute was removed | |
374 | */ | |
375 | boolean remove(Attribute attribute); | |
376 | ||
377 | /** | |
378 | * Removes the given <code>CDATA</code> if the node is an immediate child | |
379 | * of this element. If the given node is not an immediate child of this | |
380 | * element then the {@link Node#detach()}method should be used instead. | |
381 | * | |
382 | * @param cdata | |
383 | * is the CDATA to be removed | |
384 | * | |
385 | * @return true if the cdata was removed | |
386 | */ | |
387 | boolean remove(CDATA cdata); | |
388 | ||
389 | /** | |
390 | * Removes the given <code>Entity</code> if the node is an immediate child | |
391 | * of this element. If the given node is not an immediate child of this | |
392 | * element then the {@link Node#detach()}method should be used instead. | |
393 | * | |
394 | * @param entity | |
395 | * is the entity to be removed | |
396 | * | |
397 | * @return true if the entity was removed | |
398 | */ | |
399 | boolean remove(Entity entity); | |
400 | ||
401 | /** | |
402 | * Removes the given <code>Namespace</code> if the node is an immediate | |
403 | * child of this element. If the given node is not an immediate child of | |
404 | * this element then the {@link Node#detach()}method should be used | |
405 | * instead. | |
406 | * | |
407 | * @param namespace | |
408 | * is the namespace to be removed | |
409 | * | |
410 | * @return true if the namespace was removed | |
411 | */ | |
412 | boolean remove(Namespace namespace); | |
413 | ||
414 | /** | |
415 | * Removes the given <code>Text</code> if the node is an immediate child | |
416 | * of this element. If the given node is not an immediate child of this | |
417 | * element then the {@link Node#detach()}method should be used instead. | |
418 | * | |
419 | * @param text | |
420 | * is the text to be removed | |
421 | * | |
422 | * @return true if the text was removed | |
423 | */ | |
424 | boolean remove(Text text); | |
425 | ||
426 | // Text methods | |
427 | // ------------------------------------------------------------------------- | |
428 | ||
429 | /** | |
430 | * Returns the text value of this element without recursing through child | |
431 | * elements. This method iterates through all {@link Text},{@link CDATA} | |
432 | * and {@link Entity}nodes that this element contains and appends the text | |
433 | * values together. | |
434 | * | |
435 | * @return the textual content of this Element. Child elements are not | |
436 | * navigated. This method does not return null; | |
437 | */ | |
438 | String getText(); | |
439 | ||
440 | /** | |
441 | * DOCUMENT ME! | |
442 | * | |
443 | * @return the trimmed text value where whitespace is trimmed and normalised | |
444 | * into single spaces. This method does not return null. | |
445 | */ | |
446 | String getTextTrim(); | |
447 | ||
448 | /** | |
449 | * Returns the XPath string-value of this node. The behaviour of this method | |
450 | * is defined in the <a href="http://www.w3.org/TR/xpath">XPath | |
451 | * specification </a>. This method returns the string-value of all the | |
452 | * contained {@link Text},{@link CDATA},{@link Entity}and {@link | |
453 | * Element} nodes all appended together. | |
454 | * | |
455 | * @return the text from all the child Text and Element nodes appended | |
456 | * together. | |
457 | */ | |
458 | String getStringValue(); | |
459 | ||
460 | /** | |
461 | * Accesses the data of this element which may implement data typing | |
462 | * bindings such as XML Schema or Java Bean bindings or will return the same | |
463 | * value as {@link #getText} | |
464 | * | |
465 | * @return DOCUMENT ME! | |
466 | */ | |
467 | Object getData(); | |
468 | ||
469 | /** | |
470 | * Sets the data value of this element if this element supports data binding | |
471 | * or calls {@link #setText}if it doesn't | |
472 | * | |
473 | * @param data | |
474 | * DOCUMENT ME! | |
475 | */ | |
476 | void setData(Object data); | |
477 | ||
478 | // Attribute methods | |
479 | // ------------------------------------------------------------------------- | |
480 | ||
481 | /** | |
482 | * <p> | |
483 | * Returns the {@link Attribute}instances this element contains as a backed | |
484 | * {@link List}so that the attributes may be modified directly using the | |
485 | * {@link List}interface. The <code>List</code> is backed by the | |
486 | * <code>Element</code> so that changes to the list are reflected in the | |
487 | * element and vice versa. | |
488 | * </p> | |
489 | * | |
490 | * @return the attributes that this element contains as a <code>List</code> | |
491 | */ | |
492 | List attributes(); | |
493 | ||
494 | /** | |
495 | * Sets the attributes that this element contains | |
496 | * | |
497 | * @param attributes | |
498 | * DOCUMENT ME! | |
499 | */ | |
500 | void setAttributes(List attributes); | |
501 | ||
502 | /** | |
503 | * DOCUMENT ME! | |
504 | * | |
505 | * @return the number of attributes this element contains | |
506 | */ | |
507 | int attributeCount(); | |
508 | ||
509 | /** | |
510 | * DOCUMENT ME! | |
511 | * | |
512 | * @return an iterator over the attributes of this element | |
513 | */ | |
514 | Iterator attributeIterator(); | |
515 | ||
516 | /** | |
517 | * Returns the attribute at the specified indexGets the | |
518 | * | |
519 | * @param index | |
520 | * DOCUMENT ME! | |
521 | * | |
522 | * @return the attribute at the specified index where index >= 0 and | |
523 | * index < number of attributes or throws an | |
524 | * IndexOutOfBoundsException if the index is not within the | |
525 | * allowable range | |
526 | */ | |
527 | Attribute attribute(int index); | |
528 | ||
529 | /** | |
530 | * Returns the attribute with the given name | |
531 | * | |
532 | * @param name | |
533 | * DOCUMENT ME! | |
534 | * | |
535 | * @return the attribute for the given local name in any namespace. If there | |
536 | * are more than one attributes with the given local name in | |
537 | * different namespaces then the first one is returned. | |
538 | */ | |
539 | Attribute attribute(String name); | |
540 | ||
541 | /** | |
542 | * DOCUMENT ME! | |
543 | * | |
544 | * @param qName | |
545 | * is the fully qualified name | |
546 | * | |
547 | * @return the attribute for the given fully qualified name or null if it | |
548 | * could not be found. | |
549 | */ | |
550 | Attribute attribute(QName qName); | |
551 | ||
552 | /** | |
553 | * <p> | |
554 | * This returns the attribute value for the attribute with the given name | |
555 | * and any namespace or null if there is no such attribute or the empty | |
556 | * string if the attribute value is empty. | |
557 | * </p> | |
558 | * | |
559 | * @param name | |
560 | * is the name of the attribute value to be returnd | |
561 | * | |
562 | * @return the value of the attribute, null if the attribute does not exist | |
563 | * or the empty string | |
564 | */ | |
565 | String attributeValue(String name); | |
566 | ||
567 | /** | |
568 | * <p> | |
569 | * This returns the attribute value for the attribute with the given name | |
570 | * and any namespace or the default value if there is no such attribute | |
571 | * value. | |
572 | * </p> | |
573 | * | |
574 | * @param name | |
575 | * is the name of the attribute value to be returnd | |
576 | * @param defaultValue | |
577 | * is the default value to be returned if the attribute has no | |
578 | * value defined. | |
579 | * | |
580 | * @return the value of the attribute or the defaultValue if the attribute | |
581 | * has no value defined. | |
582 | */ | |
583 | String attributeValue(String name, String defaultValue); | |
584 | ||
585 | /** | |
586 | * <p> | |
587 | * This returns the attribute value for the attribute with the given fully | |
588 | * qualified name or null if there is no such attribute or the empty string | |
589 | * if the attribute value is empty. | |
590 | * </p> | |
591 | * | |
592 | * @param qName | |
593 | * is the fully qualified name | |
594 | * | |
595 | * @return the value of the attribute, null if the attribute does not exist | |
596 | * or the empty string | |
597 | */ | |
598 | String attributeValue(QName qName); | |
599 | ||
600 | /** | |
601 | * <p> | |
602 | * This returns the attribute value for the attribute with the given fully | |
603 | * qualified name or the default value if there is no such attribute value. | |
604 | * </p> | |
605 | * | |
606 | * @param qName | |
607 | * is the fully qualified name | |
608 | * @param defaultValue | |
609 | * is the default value to be returned if the attribute has no | |
610 | * value defined. | |
611 | * | |
612 | * @return the value of the attribute or the defaultValue if the attribute | |
613 | * has no value defined. | |
614 | */ | |
615 | String attributeValue(QName qName, String defaultValue); | |
616 | ||
617 | /** | |
618 | * <p> | |
619 | * Sets the attribute value of the given local name. | |
620 | * </p> | |
621 | * | |
622 | * @param name | |
623 | * is the name of the attribute whose value is to be added or | |
624 | * updated | |
625 | * @param value | |
626 | * is the attribute's value | |
627 | * | |
628 | * @deprecated As of version 0.5. Please use {@link | |
629 | * #addAttribute(String,String)} instead. WILL BE REMOVED IN | |
630 | * dom4j-1.6 !! | |
631 | */ | |
632 | void setAttributeValue(String name, String value); | |
633 | ||
634 | /** | |
635 | * <p> | |
636 | * Sets the attribute value of the given fully qualified name. | |
637 | * </p> | |
638 | * | |
639 | * @param qName | |
640 | * is the fully qualified name of the attribute whose value is to | |
641 | * be added or updated | |
642 | * @param value | |
643 | * is the attribute's value | |
644 | * | |
645 | * @deprecated As of version 0.5. Please use {@link | |
646 | * #addAttribute(QName,String)} instead. WILL BE REMOVED IN | |
647 | * dom4j-1.6 !! | |
648 | */ | |
649 | void setAttributeValue(QName qName, String value); | |
650 | ||
651 | // Content methods | |
652 | // ------------------------------------------------------------------------- | |
653 | ||
654 | /** | |
655 | * Returns the first element for the given local name and any namespace. | |
656 | * | |
657 | * @param name | |
658 | * DOCUMENT ME! | |
659 | * | |
660 | * @return the first element with the given local name | |
661 | */ | |
662 | Element element(String name); | |
663 | ||
664 | /** | |
665 | * Returns the first element for the given fully qualified name. | |
666 | * | |
667 | * @param qName | |
668 | * is the fully qualified name to search for | |
669 | * | |
670 | * @return the first element with the given fully qualified name | |
671 | */ | |
672 | Element element(QName qName); | |
673 | ||
674 | /** | |
675 | * <p> | |
676 | * Returns the elements contained in this element. If this element does not | |
677 | * contain any elements then this method returns an empty list. The list is | |
678 | * backed by the element such that changes to the list will be reflected in | |
679 | * the element though the reverse is not the case. | |
680 | * </p> | |
681 | * | |
682 | * @return a list of all the elements in this element. | |
683 | */ | |
684 | List elements(); | |
685 | ||
686 | /** | |
687 | * <p> | |
688 | * Returns the elements contained in this element with the given local name | |
689 | * and any namespace. If no elements are found then this method returns an | |
690 | * empty list. The list is backed by the element such that changes to the | |
691 | * list will be reflected in the element though the reverse is not the case. | |
692 | * </p> | |
693 | * | |
694 | * @param name | |
695 | * DOCUMENT ME! | |
696 | * | |
697 | * @return a list of all the elements in this element for the given local | |
698 | * name | |
699 | */ | |
700 | List elements(String name); | |
701 | ||
702 | /** | |
703 | * <p> | |
704 | * Returns the elements contained in this element with the given fully | |
705 | * qualified name. If no elements are found then this method returns an | |
706 | * empty list. The list is backed by the element such that changes to the | |
707 | * list will be reflected in the element though the reverse is not the case. | |
708 | * </p> | |
709 | * | |
710 | * @param qName | |
711 | * is the fully qualified name to search for | |
712 | * | |
713 | * @return a list of all the elements in this element for the given fully | |
714 | * qualified name. | |
715 | */ | |
716 | List elements(QName qName); | |
717 | ||
718 | /** | |
719 | * Returns an iterator over all this elements child elements. | |
720 | * | |
721 | * @return an iterator over the contained elements | |
722 | */ | |
723 | Iterator elementIterator(); | |
724 | ||
725 | /** | |
726 | * Returns an iterator over the elements contained in this element which | |
727 | * match the given local name and any namespace. | |
728 | * | |
729 | * @param name | |
730 | * DOCUMENT ME! | |
731 | * | |
732 | * @return an iterator over the contained elements matching the given local | |
733 | * name | |
734 | */ | |
735 | Iterator elementIterator(String name); | |
736 | ||
737 | /** | |
738 | * Returns an iterator over the elements contained in this element which | |
739 | * match the given fully qualified name. | |
740 | * | |
741 | * @param qName | |
742 | * is the fully qualified name to search for | |
743 | * | |
744 | * @return an iterator over the contained elements matching the given fully | |
745 | * qualified name | |
746 | */ | |
747 | Iterator elementIterator(QName qName); | |
748 | ||
749 | // Helper methods | |
750 | // ------------------------------------------------------------------------- | |
751 | ||
752 | /** | |
753 | * DOCUMENT ME! | |
754 | * | |
755 | * @return true if this element is the root element of a document and this | |
756 | * element supports the parent relationship else false. | |
757 | */ | |
758 | boolean isRootElement(); | |
759 | ||
760 | /** | |
761 | * <p> | |
762 | * Returns true if this <code>Element</code> has mixed content. Mixed | |
763 | * content means that an element contains both textual data and child | |
764 | * elements. | |
765 | * </p> | |
766 | * | |
767 | * @return true if this element contains mixed content. | |
768 | */ | |
769 | boolean hasMixedContent(); | |
770 | ||
771 | /** | |
772 | * <p> | |
773 | * Returns true if this <code>Element</code> has text only content. | |
774 | * </p> | |
775 | * | |
776 | * @return true if this element is empty or only contains text content. | |
777 | */ | |
778 | boolean isTextOnly(); | |
779 | ||
780 | /** | |
781 | * Appends the attributes of the given element to me. This method behaves | |
782 | * like the {@link java.util.Collection#addAll(java.util.Collection)} | |
783 | * method. | |
784 | * | |
785 | * @param element | |
786 | * is the element whose attributes will be added to me. | |
787 | */ | |
788 | void appendAttributes(Element element); | |
789 | ||
790 | /** | |
791 | * <p> | |
792 | * Creates a deep copy of this element The new element is detached from its | |
793 | * parent, and getParent() on the clone will return null. | |
794 | * </p> | |
795 | * | |
796 | * @return a new deep copy Element | |
797 | */ | |
798 | Element createCopy(); | |
799 | ||
800 | /** | |
801 | * <p> | |
802 | * Creates a deep copy of this element with the given local name The new | |
803 | * element is detached from its parent, and getParent() on the clone will | |
804 | * return null. | |
805 | * </p> | |
806 | * | |
807 | * @param name | |
808 | * DOCUMENT ME! | |
809 | * | |
810 | * @return a new deep copy Element | |
811 | */ | |
812 | Element createCopy(String name); | |
813 | ||
814 | /** | |
815 | * <p> | |
816 | * Creates a deep copy of this element with the given fully qualified name. | |
817 | * The new element is detached from its parent, and getParent() on the clone | |
818 | * will return null. | |
819 | * </p> | |
820 | * | |
821 | * @param qName | |
822 | * DOCUMENT ME! | |
823 | * | |
824 | * @return a new deep copy Element | |
825 | */ | |
826 | Element createCopy(QName qName); | |
827 | ||
828 | String elementText(String name); | |
829 | ||
830 | String elementText(QName qname); | |
831 | ||
832 | String elementTextTrim(String name); | |
833 | ||
834 | String elementTextTrim(QName qname); | |
835 | ||
836 | /** | |
837 | * Returns a node at the given index suitable for an XPath result set. This | |
838 | * means the resulting Node will either be null or it will support the | |
839 | * parent relationship. | |
840 | * | |
841 | * @param index | |
842 | * DOCUMENT ME! | |
843 | * | |
844 | * @return the Node for the given index which will support the parent | |
845 | * relationship or null if there is not a node at the given index. | |
846 | */ | |
847 | Node getXPathResult(int index); | |
848 | } | |
849 | ||
850 | /* | |
851 | * Redistribution and use of this software and associated documentation | |
852 | * ("Software"), with or without modification, are permitted provided that the | |
853 | * following conditions are met: | |
854 | * | |
855 | * 1. Redistributions of source code must retain copyright statements and | |
856 | * notices. Redistributions must also contain a copy of this document. | |
857 | * | |
858 | * 2. Redistributions in binary form must reproduce the above copyright notice, | |
859 | * this list of conditions and the following disclaimer in the documentation | |
860 | * and/or other materials provided with the distribution. | |
861 | * | |
862 | * 3. The name "DOM4J" must not be used to endorse or promote products derived | |
863 | * from this Software without prior written permission of MetaStuff, Ltd. For | |
864 | * written permission, please contact dom4j-info@metastuff.com. | |
865 | * | |
866 | * 4. Products derived from this Software may not be called "DOM4J" nor may | |
867 | * "DOM4J" appear in their names without prior written permission of MetaStuff, | |
868 | * Ltd. DOM4J is a registered trademark of MetaStuff, Ltd. | |
869 | * | |
870 | * 5. Due credit should be given to the DOM4J Project - http://www.dom4j.org | |
871 | * | |
872 | * THIS SOFTWARE IS PROVIDED BY METASTUFF, LTD. AND CONTRIBUTORS ``AS IS'' AND | |
873 | * ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
874 | * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
875 | * ARE DISCLAIMED. IN NO EVENT SHALL METASTUFF, LTD. OR ITS CONTRIBUTORS BE | |
876 | * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR | |
877 | * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF | |
878 | * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS | |
879 | * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN | |
880 | * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) | |
881 | * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE | |
882 | * POSSIBILITY OF SUCH DAMAGE. | |
883 | * | |
884 | * Copyright 2001-2005 (C) MetaStuff, Ltd. All Rights Reserved. | |
885 | */ |
|