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<Namespace> 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<Namespace> 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<Namespace> 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<Attribute> attributes();
493
494 /**
495 * Sets the attributes that this element contains
496 *
497 * @param attributes
498 * DOCUMENT ME!
499 */
500 void setAttributes(List<Attribute> 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<Attribute> 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 // Content methods
618 // -------------------------------------------------------------------------
619
620 /**
621 * Returns the first element for the given local name and any namespace.
622 *
623 * @param name
624 * DOCUMENT ME!
625 *
626 * @return the first element with the given local name
627 */
628 Element element(String name);
629
630 /**
631 * Returns the first element for the given fully qualified name.
632 *
633 * @param qName
634 * is the fully qualified name to search for
635 *
636 * @return the first element with the given fully qualified name
637 */
638 Element element(QName qName);
639
640 /**
641 * <p>
642 * Returns the elements contained in this element. If this element does not
643 * contain any elements then this method returns an empty list. The list is
644 * backed by the element such that changes to the list will be reflected in
645 * the element though the reverse is not the case.
646 * </p>
647 *
648 * @return a list of all the elements in this element.
649 */
650 List<Element> elements();
651
652 /**
653 * <p>
654 * Returns the elements contained in this element with the given local name
655 * and any namespace. If no elements are found then this method returns an
656 * empty list. The list is backed by the element such that changes to the
657 * list will be reflected in the element though the reverse is not the case.
658 * </p>
659 *
660 * @param name
661 * DOCUMENT ME!
662 *
663 * @return a list of all the elements in this element for the given local
664 * name
665 */
666 List<Element> elements(String name);
667
668 /**
669 * <p>
670 * Returns the elements contained in this element with the given fully
671 * qualified name. If no elements are found then this method returns an
672 * empty list. The list is backed by the element such that changes to the
673 * list will be reflected in the element though the reverse is not the case.
674 * </p>
675 *
676 * @param qName
677 * is the fully qualified name to search for
678 *
679 * @return a list of all the elements in this element for the given fully
680 * qualified name.
681 */
682 List<Element> elements(QName qName);
683
684 /**
685 * Returns an iterator over all this elements child elements.
686 *
687 * @return an iterator over the contained elements
688 */
689 Iterator<Element> elementIterator();
690
691 /**
692 * Returns an iterator over the elements contained in this element which
693 * match the given local name and any namespace.
694 *
695 * @param name
696 * DOCUMENT ME!
697 *
698 * @return an iterator over the contained elements matching the given local
699 * name
700 */
701 Iterator<Element> elementIterator(String name);
702
703 /**
704 * Returns an iterator over the elements contained in this element which
705 * match the given fully qualified name.
706 *
707 * @param qName
708 * is the fully qualified name to search for
709 *
710 * @return an iterator over the contained elements matching the given fully
711 * qualified name
712 */
713 Iterator<Element> elementIterator(QName qName);
714
715 // Helper methods
716 // -------------------------------------------------------------------------
717
718 /**
719 * DOCUMENT ME!
720 *
721 * @return true if this element is the root element of a document and this
722 * element supports the parent relationship else false.
723 */
724 boolean isRootElement();
725
726 /**
727 * <p>
728 * Returns true if this <code>Element</code> has mixed content. Mixed
729 * content means that an element contains both textual data and child
730 * elements.
731 * </p>
732 *
733 * @return true if this element contains mixed content.
734 */
735 boolean hasMixedContent();
736
737 /**
738 * <p>
739 * Returns true if this <code>Element</code> has text only content.
740 * </p>
741 *
742 * @return true if this element is empty or only contains text content.
743 */
744 boolean isTextOnly();
745
746 /**
747 * Appends the attributes of the given element to me. This method behaves
748 * like the {@link java.util.Collection#addAll(java.util.Collection)}
749 * method.
750 *
751 * @param element
752 * is the element whose attributes will be added to me.
753 */
754 void appendAttributes(Element element);
755
756 /**
757 * <p>
758 * Creates a deep copy of this element The new element is detached from its
759 * parent, and getParent() on the clone will return null.
760 * </p>
761 *
762 * @return a new deep copy Element
763 */
764 Element createCopy();
765
766 /**
767 * <p>
768 * Creates a deep copy of this element with the given local name The new
769 * element is detached from its parent, and getParent() on the clone will
770 * return null.
771 * </p>
772 *
773 * @param name
774 * DOCUMENT ME!
775 *
776 * @return a new deep copy Element
777 */
778 Element createCopy(String name);
779
780 /**
781 * <p>
782 * Creates a deep copy of this element with the given fully qualified name.
783 * The new element is detached from its parent, and getParent() on the clone
784 * will return null.
785 * </p>
786 *
787 * @param qName
788 * DOCUMENT ME!
789 *
790 * @return a new deep copy Element
791 */
792 Element createCopy(QName qName);
793
794 String elementText(String name);
795
796 String elementText(QName qname);
797
798 String elementTextTrim(String name);
799
800 String elementTextTrim(QName qname);
801
802 /**
803 * Returns a node at the given index suitable for an XPath result set. This
804 * means the resulting Node will either be null or it will support the
805 * parent relationship.
806 *
807 * @param index
808 * DOCUMENT ME!
809 *
810 * @return the Node for the given index which will support the parent
811 * relationship or null if there is not a node at the given index.
812 */
813 Node getXPathResult(int index);
814 }
815
816 /*
817 * Redistribution and use of this software and associated documentation
818 * ("Software"), with or without modification, are permitted provided that the
819 * following conditions are met:
820 *
821 * 1. Redistributions of source code must retain copyright statements and
822 * notices. Redistributions must also contain a copy of this document.
823 *
824 * 2. Redistributions in binary form must reproduce the above copyright notice,
825 * this list of conditions and the following disclaimer in the documentation
826 * and/or other materials provided with the distribution.
827 *
828 * 3. The name "DOM4J" must not be used to endorse or promote products derived
829 * from this Software without prior written permission of MetaStuff, Ltd. For
830 * written permission, please contact dom4j-info@metastuff.com.
831 *
832 * 4. Products derived from this Software may not be called "DOM4J" nor may
833 * "DOM4J" appear in their names without prior written permission of MetaStuff,
834 * Ltd. DOM4J is a registered trademark of MetaStuff, Ltd.
835 *
836 * 5. Due credit should be given to the DOM4J Project - http://www.dom4j.org
837 *
838 * THIS SOFTWARE IS PROVIDED BY METASTUFF, LTD. AND CONTRIBUTORS ``AS IS'' AND
839 * ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
840 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
841 * ARE DISCLAIMED. IN NO EVENT SHALL METASTUFF, LTD. OR ITS CONTRIBUTORS BE
842 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
843 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
844 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
845 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
846 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
847 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
848 * POSSIBILITY OF SUCH DAMAGE.
849 *
850 * Copyright 2001-2005 (C) MetaStuff, Ltd. All Rights Reserved.
851 */