1
2
3
4
5
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
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
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
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
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
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
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
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
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885