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