XMLElement


1   /* XMLElement.java                                                 NanoXML/Java
2    *
3    * $Revision: 1421 $
4    * $Date: 2006-03-12 17:32:32 +0100 (Sun, 12 Mar 2006) $
5    * $Name$
6    *
7    * This file is part of NanoXML 2 for Java.
8    * Copyright (C) 2001 Marc De Scheemaecker, All Rights Reserved.
9    *
10   * This software is provided 'as-is', without any express or implied warranty.
11   * In no event will the authors be held liable for any damages arising from the
12   * use of this software.
13   *
14   * Permission is granted to anyone to use this software for any purpose,
15   * including commercial applications, and to alter it and redistribute it
16   * freely, subject to the following restrictions:
17   *
18   *  1. The origin of this software must not be misrepresented; you must not
19   *     claim that you wrote the original software. If you use this software in
20   *     a product, an acknowledgment in the product documentation would be
21   *     appreciated but is not required.
22   *
23   *  2. Altered source versions must be plainly marked as such, and must not be
24   *     misrepresented as being the original software.
25   *
26   *  3. This notice may not be removed or altered from any source distribution.
27   */
28  
29  package net.n3.nanoxml;
30  
31  import java.io.Serializable  ;
32  import java.util.Enumeration  ;
33  import java.util.Properties  ;
34  import java.util.Vector  ;
35  
36  /**
37   * XMLElement is an XML element. The standard NanoXML builder generates a tree of such elements.
38   * 
39   * @see net.n3.nanoxml.StdXMLBuilder
40   * 
41   * @author Marc De Scheemaecker
42   * @version $Name$, $Revision: 1421 $
43   */
44  public class XMLElement implements Serializable  
45  {
46  
47      /**
48       * Necessary for serialization.
49       */
50      static final long serialVersionUID = -2383376380548624920L;
51  
52      /**
53       * No line number defined.
54       */
55      public static final int NO_LINE = -1;
56  
57      /**
58       * The attributes of the element.
59       */
60      private Properties   attributes;
61  
62      /**
63       * The child elements.
64       */
65      private Vector   children;
66  
67      /**
68       * The name of the element.
69       */
70      private String   name;
71  
72      /**
73       * The content of the element.
74       */
75      private String   content;
76  
77      /**
78       * The system ID of the source data where this element is located.
79       */
80      private String   systemID;
81  
82      /**
83       * The line in the source data where this element starts.
84       */
85      private int lineNr;
86  
87      /**
88       * Creates an empty element to be used for #PCDATA content.
89       */
90      public XMLElement()
91      {
92          this(null, null, NO_LINE);
93      }
94  
95      /**
96       * Creates an empty element.
97       * 
98       * @param name the name of the element.
99       */
100     public XMLElement(String   name)
101     {
102         this(name, null, NO_LINE);
103     }
104 
105     /**
106      * Creates an empty element.
107      * 
108      * @param name the name of the element.
109      * @param systemID the system ID of the XML data where the element starts.
110      * @param lineNr the line in the XML data where the element starts.
111      */
112     public XMLElement(String   name, String   systemID, int lineNr)
113     {
114         this.attributes = new Properties  ();
115         this.children = new Vector  (8);
116         this.name = name;
117         this.content = null;
118         this.lineNr = lineNr;
119         this.systemID = systemID;
120     }
121 
122     /**
123      * Cleans up the object when it's destroyed.
124      */
125     protected void finalize() throws Throwable  
126     {
127         this.attributes = null;
128         this.children = null;
129         this.name = null;
130         this.content = null;
131         this.systemID = null;
132         super.finalize();
133     }
134 
135     /**
136      * Returns the name of the element.
137      * 
138      * @return the name, or null if the element only contains #PCDATA.
139      */
140     public String   getName()
141     {
142         return this.name;
143     }
144 
145     /**
146      * Sets the name.
147      * 
148      * @param name the non-null name.
149      */
150     public void setName(String   name)
151     {
152         if (name == null) { throw new IllegalArgumentException  ("name must not be null"); }
153 
154         this.name = name;
155     }
156 
157     /**
158      * Adds a child element.
159      * 
160      * @param child the non-null child to add.
161      */
162     public void addChild(XMLElement child)
163     {
164         if (child == null) { throw new IllegalArgumentException  ("child must not be null"); }
165 
166         if ((child.getName() == null) && (!this.children.isEmpty()))
167         {
168             XMLElement lastChild = (XMLElement) this.children.lastElement();
169 
170             if (lastChild.getName() == null)
171             {
172                 lastChild.setContent(lastChild.getContent() + child.getContent());
173                 return;
174             }
175         }
176 
177         this.children.addElement(child);
178     }
179 
180     /**
181      * Removes a child element.
182      * 
183      * @param child the non-null child to remove.
184      */
185     public void removeChild(XMLElement child)
186     {
187         if (child == null) { throw new IllegalArgumentException  ("child must not be null"); }
188 
189         this.children.removeElement(child);
190     }
191 
192     /**
193      * Removes the child located at a certain index.
194      * 
195      * @param index the index of the child, where the first child has index 0.
196      */
197     public void removeChildAtIndex(int index)
198     {
199         this.children.removeElementAt(index);
200     }
201 
202     /**
203      * Returns an enumeration of all child elements.
204      * 
205      * @return the non-null enumeration
206      */
207     public Enumeration   enumerateChildren()
208     {
209         return this.children.elements();
210     }
211 
212     /**
213      * Returns whether the element is a leaf element.
214      * 
215      * @return true if the element has no children.
216      */
217     public boolean isLeaf()
218     {
219         return this.children.isEmpty();
220     }
221 
222     /**
223      * Returns whether the element has children.
224      * 
225      * @return true if the element has children.
226      */
227     public boolean hasChildren()
228     {
229         return (!this.children.isEmpty());
230     }
231 
232     /**
233      * Returns the number of children.
234      * 
235      * @return the count.
236      */
237     public int getChildrenCount()
238     {
239         return this.children.size();
240     }
241 
242     /**
243      * Returns a vector containing all the child elements.
244      * 
245      * @return the vector.
246      */
247     public Vector   getChildren()
248     {
249         return this.children;
250     }
251 
252     /**
253      * Returns the child at a specific index.
254      * 
255      * @return the non-null child
256      * 
257      * @throws java.lang.ArrayIndexOutOfBoundsException if the index is out of bounds.
258      */
259     public XMLElement getChildAtIndex(int index) throws ArrayIndexOutOfBoundsException  
260     {
261         return (XMLElement) this.children.elementAt(index);
262     }
263 
264     /**
265      * Searches a child element.
266      * 
267      * @param name the name of the child to search for.
268      * 
269      * @return the child element, or null if no such child was found.
270      */
271     public XMLElement getFirstChildNamed(String   name)
272     {
273         Enumeration   enumeration = this.children.elements();
274 
275         while (enumeration.hasMoreElements())
276         {
277             XMLElement child = (XMLElement) enumeration.nextElement();
278             String   cName = child.getName();
279 
280             if (cName != null && cName.equals(name)) { return child; }
281         }
282 
283         return null;
284     }
285 
286     /**
287      * Returns a vector of all child elements named <I>name</I>.
288      * 
289      * @param name the name of the children to search for.
290      * 
291      * @return the non-null vector of child elements.
292      */
293     public Vector   getChildrenNamed(String   name)
294     {
295         Vector   result = new Vector  (this.children.size());
296         Enumeration   enumeration = this.children.elements();
297 
298         while (enumeration.hasMoreElements())
299         {
300             XMLElement child = (XMLElement) enumeration.nextElement();
301             String   cName = child.getName();
302 
303             if (cName != null && cName.equals(name))
304             {
305                 result.addElement(child);
306             }
307         }
308 
309         return result;
310     }
311 
312     /**
313      * Returns the value of an attribute.
314      * 
315      * @param name the non-null name of the attribute.
316      * 
317      * @return the value, or null if the attribute does not exist.
318      */
319     public String   getAttribute(String   name)
320     {
321         return this.getAttribute(name, null);
322     }
323 
324     /**
325      * Returns the value of an attribute.
326      * 
327      * @param name the non-null name of the attribute.
328      * @param defaultValue the default value of the attribute.
329      * 
330      * @return the value, or defaultValue if the attribute does not exist.
331      */
332     public String   getAttribute(String   name, String   defaultValue)
333     {
334         return this.attributes.getProperty(name, defaultValue);
335     }
336 
337     /**
338      * Sets an attribute.
339      * 
340      * @param name the non-null name of the attribute.
341      * @param value the non-null value of the attribute.
342      */
343     public void setAttribute(String   name, String   value)
344     {
345         this.attributes.put(name, value);
346     }
347 
348     /**
349      * Removes an attribute.
350      * 
351      * @param name the non-null name of the attribute.
352      */
353     public void removeAttribute(String   name)
354     {
355         this.attributes.remove(name);
356     }
357 
358     /**
359      * Returns an enumeration of all attribute names.
360      * 
361      * @return the non-null enumeration.
362      */
363     public Enumeration   enumerateAttributeNames()
364     {
365         return this.attributes.keys();
366     }
367 
368     /**
369      * Returns whether an attribute exists.
370      * 
371      * @return true if the attribute exists.
372      */
373     public boolean hasAttribute(String   name)
374     {
375         return this.attributes.containsKey(name);
376     }
377 
378     /**
379      * Returns all attributes as a Properties object.
380      * 
381      * @return the non-null set.
382      */
383     public Properties   getAttributes()
384     {
385         return this.attributes;
386     }
387 
388     /**
389      * Returns the system ID of the data where the element started.
390      * 
391      * @return the system ID, or null if unknown.
392      * 
393      * @see #getLineNr
394      */
395     public String   getSystemID()
396     {
397         return this.systemID;
398     }
399 
400     /**
401      * Returns the line number in the data where the element started.
402      * 
403      * @return the line number, or NO_LINE if unknown.
404      * 
405      * @see #NO_LINE
406      * @see #getSystemID
407      */
408     public int getLineNr()
409     {
410         return this.lineNr;
411     }
412 
413     /**
414      * Return the #PCDATA content of the element. If the element has a combination of #PCDATA
415      * content and child elements, the #PCDATA sections can be retrieved as unnamed child objects.
416      * In this case, this method returns null.
417      * 
418      * @return the content.
419      */
420     public String   getContent()
421     {
422         return this.content;
423     }
424 
425     /**
426      * Sets the #PCDATA content. It is an error to call this method with a non-null value if there
427      * are child objects.
428      * 
429      * @param content the (possibly null) content.
430      */
431     public void setContent(String   content)
432     {
433         this.content = content;
434     }
435 
436 }
437
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags