View Javadoc

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