dom4j - 1.6.1

Clover coverage report - dom4j - 1.6.1
Coverage timestamp: ma mei 16 2005 14:23:01 GMT+01:00
FRAMES NO FRAMES

file stats: | LOC: | 885 |  | Methods: | 0
| NCLOC: | 75 |  | Classes: | 1

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() + &quot;:&quot; + 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 &gt;= 0 and
523 |  | * index &lt; 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 |  | */