1
2
3
4
5
6
7
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
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
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
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
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
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
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
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
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692