001: /* IXMLElement.java NanoXML/Java
002: *
003: * $Revision: 1.4 $
004: * $Date: 2002/01/04 21:03:28 $
005: * $Name: RELEASE_2_2_1 $
006: *
007: * This file is part of NanoXML 2 for Java.
008: * Copyright (C) 2000-2002 Marc De Scheemaecker, All Rights Reserved.
009: *
010: * This software is provided 'as-is', without any express or implied warranty.
011: * In no event will the authors be held liable for any damages arising from the
012: * use of this software.
013: *
014: * Permission is granted to anyone to use this software for any purpose,
015: * including commercial applications, and to alter it and redistribute it
016: * freely, subject to the following restrictions:
017: *
018: * 1. The origin of this software must not be misrepresented; you must not
019: * claim that you wrote the original software. If you use this software in
020: * a product, an acknowledgment in the product documentation would be
021: * appreciated but is not required.
022: *
023: * 2. Altered source versions must be plainly marked as such, and must not be
024: * misrepresented as being the original software.
025: *
026: * 3. This notice may not be removed or altered from any source distribution.
027: */
028:
029: package net.n3.nanoxml;
030:
031: import java.io.Serializable;
032: import java.util.Enumeration;
033: import java.util.Hashtable;
034: import java.util.Properties;
035: import java.util.Vector;
036:
037: /**
038: * IXMLElement is an XML element. It provides an easy to use generic interface
039: * on top of an XML like data structure like e.g. a DOM like structure.
040: * Elements returned by StdXMLBuilder also implement this interface.
041: *
042: * @see net.n3.nanoxml.StdXMLBuilder
043: *
044: * @author Marc De Scheemaecker
045: * @version $Name: RELEASE_2_2_1 $, $Revision: 1.4 $
046: */
047: public interface IXMLElement {
048:
049: /**
050: * No line number defined.
051: */
052: public static final int NO_LINE = -1;
053:
054: /**
055: * Creates an element to be used for #PCDATA content.
056: */
057: public IXMLElement createPCDataElement();
058:
059: /**
060: * Creates an empty element.
061: *
062: * @param fullName the name of the element.
063: */
064: public IXMLElement createElement(String fullName);
065:
066: /**
067: * Creates an empty element.
068: *
069: * @param fullName the name of the element.
070: * @param systemID the system ID of the XML data where the element starts.
071: * @param lineNr the line in the XML data where the element starts.
072: */
073: public IXMLElement createElement(String fullName, String systemID,
074: int lineNr);
075:
076: /**
077: * Creates an empty element.
078: *
079: * @param fullName the full name of the element
080: * @param namespace the namespace URI.
081: */
082: public IXMLElement createElement(String fullName, String namespace);
083:
084: /**
085: * Creates an empty element.
086: *
087: * @param fullName the full name of the element
088: * @param namespace the namespace URI.
089: * @param systemID the system ID of the XML data where the element starts.
090: * @param lineNr the line in the XML data where the element starts.
091: */
092: public IXMLElement createElement(String fullName, String namespace,
093: String systemID, int lineNr);
094:
095: /**
096: * Returns the parent element. This method returns null for the root
097: * element.
098: */
099: public IXMLElement getParent();
100:
101: /**
102: * Returns the full name (i.e. the name including an eventual namespace
103: * prefix) of the element.
104: *
105: * @return the name, or null if the element only contains #PCDATA.
106: */
107: public String getFullName();
108:
109: /**
110: * Returns the name of the element.
111: *
112: * @return the name, or null if the element only contains #PCDATA.
113: */
114: public String getName();
115:
116: /**
117: * Returns the namespace of the element.
118: *
119: * @return the namespace, or null if no namespace is associated with the
120: * element.
121: */
122: public String getNamespace();
123:
124: /**
125: * Sets the full name. This method also sets the short name and clears the
126: * namespace URI.
127: *
128: * @param name the non-null name.
129: */
130: public void setName(String name);
131:
132: /**
133: * Sets the name.
134: *
135: * @param fullName the non-null full name.
136: * @param namespace the namespace URI, which may be null.
137: */
138: public void setName(String fullName, String namespace);
139:
140: /**
141: * Adds a child element.
142: *
143: * @param child the non-null child to add.
144: */
145: public void addChild(IXMLElement child);
146:
147: /**
148: * Removes a child element.
149: *
150: * @param child the non-null child to remove.
151: */
152: public void removeChild(IXMLElement child);
153:
154: /**
155: * Removes the child located at a certain index.
156: *
157: * @param index the index of the child, where the first child has index 0.
158: */
159: public void removeChildAtIndex(int index);
160:
161: /**
162: * Returns an enumeration of all child elements.
163: *
164: * @return the non-null enumeration
165: */
166: public Enumeration enumerateChildren();
167:
168: /**
169: * Returns whether the element is a leaf element.
170: *
171: * @return true if the element has no children.
172: */
173: public boolean isLeaf();
174:
175: /**
176: * Returns whether the element has children.
177: *
178: * @return true if the element has children.
179: */
180: public boolean hasChildren();
181:
182: /**
183: * Returns the number of children.
184: *
185: * @return the count.
186: */
187: public int getChildrenCount();
188:
189: /**
190: * Returns a vector containing all the child elements.
191: *
192: * @return the vector.
193: */
194: public Vector getChildren();
195:
196: /**
197: * Returns the child at a specific index.
198: *
199: * @param index the index of the child
200: *
201: * @return the non-null child
202: *
203: * @throws java.lang.ArrayIndexOutOfBoundsException
204: * if the index is out of bounds.
205: */
206: public IXMLElement getChildAtIndex(int index)
207: throws ArrayIndexOutOfBoundsException;
208:
209: /**
210: * Searches a child element.
211: *
212: * @param name the full name of the child to search for.
213: *
214: * @return the child element, or null if no such child was found.
215: */
216: public IXMLElement getFirstChildNamed(String name);
217:
218: /**
219: * Searches a child element.
220: *
221: * @param name the name of the child to search for.
222: * @param namespace the namespace, which may be null.
223: *
224: * @return the child element, or null if no such child was found.
225: */
226: public IXMLElement getFirstChildNamed(String name, String namespace);
227:
228: /**
229: * Returns a vector of all child elements named <I>name</I>.
230: *
231: * @param name the full name of the children to search for.
232: *
233: * @return the non-null vector of child elements.
234: */
235: public Vector getChildrenNamed(String name);
236:
237: /**
238: * Returns a vector of all child elements named <I>name</I>.
239: *
240: * @param name the name of the children to search for.
241: * @param namespace the namespace, which may be null.
242: *
243: * @return the non-null vector of child elements.
244: */
245: public Vector getChildrenNamed(String name, String namespace);
246:
247: /**
248: * Returns the number of attributes.
249: */
250: public int getAttributeCount();
251:
252: /**
253: * @deprecated As of NanoXML/Java 2.0.1, replaced by
254: * {@link #getAttribute(java.lang.String,java.lang.String)}
255: * Returns the value of an attribute.
256: *
257: * @param name the non-null name of the attribute.
258: *
259: * @return the value, or null if the attribute does not exist.
260: */
261: public String getAttribute(String name);
262:
263: /**
264: * Returns the value of an attribute.
265: *
266: * @param name the non-null full name of the attribute.
267: * @param defaultValue the default value of the attribute.
268: *
269: * @return the value, or defaultValue if the attribute does not exist.
270: */
271: public String getAttribute(String name, String defaultValue);
272:
273: /**
274: * Returns the value of an attribute.
275: *
276: * @param name the non-null name of the attribute.
277: * @param namespace the namespace URI, which may be null.
278: * @param defaultValue the default value of the attribute.
279: *
280: * @return the value, or defaultValue if the attribute does not exist.
281: */
282: public String getAttribute(String name, String namespace,
283: String defaultValue);
284:
285: /**
286: * Returns the value of an attribute.
287: *
288: * @param name the non-null full name of the attribute.
289: * @param defaultValue the default value of the attribute.
290: *
291: * @return the value, or defaultValue if the attribute does not exist.
292: */
293: public int getAttribute(String name, int defaultValue);
294:
295: /**
296: * Returns the value of an attribute.
297: *
298: * @param name the non-null name of the attribute.
299: * @param namespace the namespace URI, which may be null.
300: * @param defaultValue the default value of the attribute.
301: *
302: * @return the value, or defaultValue if the attribute does not exist.
303: */
304: public int getAttribute(String name, String namespace,
305: int defaultValue);
306:
307: /**
308: * Returns the type of an attribute.
309: *
310: * @param name the non-null full name of the attribute.
311: *
312: * @return the type, or null if the attribute does not exist.
313: */
314: public String getAttributeType(String name);
315:
316: /**
317: * Returns the namespace of an attribute.
318: *
319: * @param name the non-null full name of the attribute.
320: *
321: * @return the namespace, or null if there is none associated.
322: */
323: public String getAttributeNamespace(String name);
324:
325: /**
326: * Returns the type of an attribute.
327: *
328: * @param name the non-null name of the attribute.
329: * @param namespace the namespace URI, which may be null.
330: *
331: * @return the type, or null if the attribute does not exist.
332: */
333: public String getAttributeType(String name, String namespace);
334:
335: /**
336: * Sets an attribute.
337: *
338: * @param name the non-null full name of the attribute.
339: * @param value the non-null value of the attribute.
340: */
341: public void setAttribute(String name, String value);
342:
343: /**
344: * Sets an attribute.
345: *
346: * @param fullName the non-null full name of the attribute.
347: * @param namespace the namespace URI of the attribute, which may be null.
348: * @param value the non-null value of the attribute.
349: */
350: public void setAttribute(String fullName, String namespace,
351: String value);
352:
353: /**
354: * Removes an attribute.
355: *
356: * @param name the non-null name of the attribute.
357: */
358: public void removeAttribute(String name);
359:
360: /**
361: * Removes an attribute.
362: *
363: * @param name the non-null name of the attribute.
364: * @param namespace the namespace URI of the attribute, which may be null.
365: */
366: public void removeAttribute(String name, String namespace);
367:
368: /**
369: * Returns an enumeration of all attribute names.
370: *
371: * @return the non-null enumeration.
372: */
373: public Enumeration enumerateAttributeNames();
374:
375: /**
376: * Returns whether an attribute exists.
377: *
378: * @param name the non-null name of the attribute.
379: *
380: * @return true if the attribute exists.
381: */
382: public boolean hasAttribute(String name);
383:
384: /**
385: * Returns whether an attribute exists.
386: *
387: * @param name the non-null name of the attribute.
388: * @param namespace the namespace URI of the attribute, which may be null.
389: *
390: * @return true if the attribute exists.
391: */
392: public boolean hasAttribute(String name, String namespace);
393:
394: /**
395: * Returns all attributes as a Properties object.
396: *
397: * @return the non-null set.
398: */
399: public Properties getAttributes();
400:
401: /**
402: * Returns all attributes in a specific namespace as a Properties object.
403: *
404: * @param namespace the namespace URI of the attributes, which may be null.
405: *
406: * @return the non-null set.
407: */
408: public Properties getAttributesInNamespace(String namespace);
409:
410: /**
411: * Returns the system ID of the data where the element started.
412: *
413: * @return the system ID, or null if unknown.
414: *
415: * @see #getLineNr
416: */
417: public String getSystemID();
418:
419: /**
420: * Returns the line number in the data where the element started.
421: *
422: * @return the line number, or NO_LINE if unknown.
423: *
424: * @see #NO_LINE
425: * @see #getSystemID
426: */
427: public int getLineNr();
428:
429: /**
430: * Return the #PCDATA content of the element. If the element has a
431: * combination of #PCDATA content and child elements, the #PCDATA
432: * sections can be retrieved as unnamed child objects. In this case,
433: * this method returns null.
434: *
435: * @return the content.
436: */
437: public String getContent();
438:
439: /**
440: * Sets the #PCDATA content. It is an error to call this method with a
441: * non-null value if there are child objects.
442: *
443: * @param content the (possibly null) content.
444: */
445: public void setContent(String content);
446:
447: /**
448: * Returns true if the element equals another element.
449: *
450: * @param rawElement the element to compare to
451: */
452: public boolean equals(Object rawElement);
453:
454: /**
455: * Returns true if the element equals another element.
456: *
457: * @param rawElement the element to compare to
458: */
459: public boolean equalsXMLElement(IXMLElement elt);
460:
461: }
|