001/* ----------------------------------------------------------------------------
002 * This file was automatically generated by SWIG (http://www.swig.org).
003 * Version 2.0.11
004 *
005 * Do not make changes to this file unless you know what you are doing--modify
006 * the SWIG interface file instead.
007 * ----------------------------------------------------------------------------- */
008
009package org.sbml.libsbml;
010
011/** 
012 * 
013 * Representation of a node in an XML document tree.
014 * <p>
015 * Beginning with version 3.0.0, libSBML implements an XML abstraction
016 * layer.  This layer presents a uniform XML interface to calling programs
017 * regardless of which underlying XML parser libSBML has actually been
018 * configured to use.  The basic data object in the XML abstraction is a
019 * <em>node</em>, represented by {@link XMLNode}.
020 * <p>
021 * An {@link XMLNode} can contain any number of children.  Each child is another
022 * {@link XMLNode}, thereby forming a tree.  The methods {@link XMLNode#getNumChildren()}
023 * and {@link XMLNode#getChild(long n)} can be used to access the tree
024 * structure starting from a given node.
025 * <p>
026 * Each {@link XMLNode} is subclassed from {@link XMLToken}, and thus has the same methods
027 * available as {@link XMLToken}.  These methods include {@link XMLToken#getNamespaces()},
028 * {@link XMLToken#getPrefix()}, {@link XMLToken#getName()}, {@link XMLToken#getURI()}, and
029 * {@link XMLToken#getAttributes()}.
030 * <p>
031 * <h2>Conversion between an XML string and an {@link XMLNode}</h2>
032 * <p>
033 * LibSBML provides the following utility functions for converting an XML
034 * string (e.g., <code>&lt;annotation&gt;...&lt;/annotation&gt;</code>)
035 * to/from an {@link XMLNode} object.
036 * <ul>
037 * <li> {@link XMLNode#toXMLString()} returns a string representation of the {@link XMLNode} object. 
038 * <p>
039 * <li> {@link XMLNode#convertXMLNodeToString(XMLNode node)}
040 * (static function) returns a string representation 
041 * of the given {@link XMLNode} object.
042 * <p>
043 * <li> {@link XMLNode#convertStringToXMLNode(String xml)}
044 * (static function) returns an {@link XMLNode} object converted 
045 * from the given XML string.
046 * </ul>
047 * <p>
048 * The returned {@link XMLNode} object by {@link XMLNode#convertStringToXMLNode(String xml)}
049 * is a dummy root (container) {@link XMLNode} if the given XML string has two or
050 * more top-level elements (e.g.,
051 * &quot;<code>&lt;p&gt;...&lt;/p&gt;&lt;p&gt;...&lt;/p&gt;</code>&quot;). In the
052 * dummy root node, each top-level element in the given XML string is
053 * contained as a child {@link XMLNode}. {@link XMLToken#isEOF()} can be used to identify
054 * if the returned {@link XMLNode} object is a dummy node or not.  Here is an
055 * example: <div class='fragment'><pre>
056// Checks if the returned {@link XMLNode} object is a dummy root node:
057
058String str = '...';
059{@link XMLNode} xn = {@link XMLNode}.convertStringToXMLNode(str);
060if ( xn == null )
061{
062  // returned value is null (error)
063  ...
064}
065else if ( xn.isEOF() )
066{
067  // root node is a dummy node
068  for ( int i = 0; i &lt; xn.getNumChildren(); i++ )
069  {
070    // access to each child node of the dummy node.
071    {@link XMLNode} xnChild = xn.getChild(i);
072    ...
073  }
074}
075else
076{
077  // root node is NOT a dummy node
078  ...
079}
080</pre></div>
081 * <p>
082 */
083
084public class XMLNode extends XMLToken {
085   private long swigCPtr;
086
087   protected XMLNode(long cPtr, boolean cMemoryOwn)
088   {
089     super(libsbmlJNI.XMLNode_SWIGUpcast(cPtr), cMemoryOwn);
090     swigCPtr = cPtr;
091   }
092
093   protected static long getCPtr(XMLNode obj)
094   {
095     return (obj == null) ? 0 : obj.swigCPtr;
096   }
097
098   protected static long getCPtrAndDisown (XMLNode obj)
099   {
100     long ptr = 0;
101
102     if (obj != null)
103     {
104       ptr             = obj.swigCPtr;
105       obj.swigCMemOwn = false;
106     }
107
108     return ptr;
109   }
110
111  protected void finalize() {
112    delete();
113  }
114
115  public synchronized void delete() {
116    if (swigCPtr != 0) {
117      if (swigCMemOwn) {
118        swigCMemOwn = false;
119        libsbmlJNI.delete_XMLNode(swigCPtr);
120      }
121      swigCPtr = 0;
122    }
123    super.delete();
124  }
125
126  /**
127   * Equality comparison method for XMLNode.
128   * <p>
129   * Because the Java methods for libSBML are actually wrappers around code
130   * implemented in C++ and C, certain operations will not behave as
131   * expected.  Equality comparison is one such case.  An instance of a
132   * libSBML object class is actually a <em>proxy object</em>
133   * wrapping the real underlying C/C++ object.  The normal <code>==</code>
134   * equality operator in Java will <em>only compare the Java proxy objects</em>,
135   * not the underlying native object.  The result is almost never what you
136   * want in practical situations.  Unfortunately, Java does not provide a
137   * way to override <code>==</code>.
138   *  <p>
139   * The alternative that must be followed is to use the
140   * <code>equals()</code> method.  The <code>equals</code> method on this
141   * class overrides the default java.lang.Object one, and performs an
142   * intelligent comparison of instances of objects of this class.  The
143   * result is an assessment of whether two libSBML Java objects are truly 
144   * the same underlying native-code objects.
145   *  <p>
146   * The use of this method in practice is the same as the use of any other
147   * Java <code>equals</code> method.  For example,
148   * <em>a</em><code>.equals(</code><em>b</em><code>)</code> returns
149   * <code>true</code> if <em>a</em> and <em>b</em> are references to the
150   * same underlying object.
151   *
152   * @param sb a reference to an object to which the current object
153   * instance will be compared
154   *
155   * @return <code>true</code> if <code>sb</code> refers to the same underlying 
156   * native object as this one, <code>false</code> otherwise
157   */
158  public boolean equals(Object sb)
159  {
160    if ( this == sb ) 
161    {
162      return true;
163    }
164    return swigCPtr == getCPtr((XMLNode)(sb));
165  }
166
167  /**
168   * Returns a hashcode for this XMLNode object.
169   *
170   * @return a hash code usable by Java methods that need them.
171   */
172  public int hashCode()
173  {
174    return (int)(swigCPtr^(swigCPtr>>>32));
175  }
176
177  
178/**
179   * Creates a new empty {@link XMLNode} with no children.
180   */ public
181 XMLNode() throws org.sbml.libsbml.XMLConstructorException {
182    this(libsbmlJNI.new_XMLNode__SWIG_0(), true);
183  }
184
185  
186/**
187   * Creates a new {@link XMLNode} by copying token.
188   * <p>
189   * @param token {@link XMLToken} to be copied to {@link XMLNode}
190   */ public
191 XMLNode(XMLToken token) throws org.sbml.libsbml.XMLConstructorException {
192    this(libsbmlJNI.new_XMLNode__SWIG_1(XMLToken.getCPtr(token), token), true);
193  }
194
195  
196/**
197   * Creates a new start element {@link XMLNode} with the given set of attributes and
198   * namespace declarations.
199   * <p>
200   * @param triple {@link XMLTriple}.
201   * @param attributes {@link XMLAttributes}, the attributes to set.
202   * @param namespaces {@link XMLNamespaces}, the namespaces to set.
203   * @param line a long integer, the line number (default = 0).
204   * @param column a long integer, the column number (default = 0).
205   * <p>
206   * <!-- Don't remove the leading </dl> below. It's a hack for javadoc. -->
207</dl><dl class='docnote'><dt><b>Documentation note:</b></dt><dd>
208The native C++ implementation of this method defines a default argument
209value. In the documentation generated for different libSBML language
210bindings, you may or may not see corresponding arguments in the method
211declarations. For example, in Java and C#, a default argument is handled by
212declaring two separate methods, with one of them having the argument and
213the other one lacking the argument. However, the libSBML documentation will
214be <em>identical</em> for both methods. Consequently, if you are reading
215this and do not see an argument even though one is described, please look
216for descriptions of other variants of this method near where this one
217appears in the documentation.
218</dd></dl>
219 
220   */ public
221 XMLNode(XMLTriple triple, XMLAttributes attributes, XMLNamespaces namespaces, long line, long column) throws org.sbml.libsbml.XMLConstructorException {
222    this(libsbmlJNI.new_XMLNode__SWIG_2(XMLTriple.getCPtr(triple), triple, XMLAttributes.getCPtr(attributes), attributes, XMLNamespaces.getCPtr(namespaces), namespaces, line, column), true);
223  }
224
225  
226/**
227   * Creates a new start element {@link XMLNode} with the given set of attributes and
228   * namespace declarations.
229   * <p>
230   * @param triple {@link XMLTriple}.
231   * @param attributes {@link XMLAttributes}, the attributes to set.
232   * @param namespaces {@link XMLNamespaces}, the namespaces to set.
233   * @param line a long integer, the line number (default = 0).
234   * @param column a long integer, the column number (default = 0).
235   * <p>
236   * <!-- Don't remove the leading </dl> below. It's a hack for javadoc. -->
237</dl><dl class='docnote'><dt><b>Documentation note:</b></dt><dd>
238The native C++ implementation of this method defines a default argument
239value. In the documentation generated for different libSBML language
240bindings, you may or may not see corresponding arguments in the method
241declarations. For example, in Java and C#, a default argument is handled by
242declaring two separate methods, with one of them having the argument and
243the other one lacking the argument. However, the libSBML documentation will
244be <em>identical</em> for both methods. Consequently, if you are reading
245this and do not see an argument even though one is described, please look
246for descriptions of other variants of this method near where this one
247appears in the documentation.
248</dd></dl>
249 
250   */ public
251 XMLNode(XMLTriple triple, XMLAttributes attributes, XMLNamespaces namespaces, long line) throws org.sbml.libsbml.XMLConstructorException {
252    this(libsbmlJNI.new_XMLNode__SWIG_3(XMLTriple.getCPtr(triple), triple, XMLAttributes.getCPtr(attributes), attributes, XMLNamespaces.getCPtr(namespaces), namespaces, line), true);
253  }
254
255  
256/**
257   * Creates a new start element {@link XMLNode} with the given set of attributes and
258   * namespace declarations.
259   * <p>
260   * @param triple {@link XMLTriple}.
261   * @param attributes {@link XMLAttributes}, the attributes to set.
262   * @param namespaces {@link XMLNamespaces}, the namespaces to set.
263   * @param line a long integer, the line number (default = 0).
264   * @param column a long integer, the column number (default = 0).
265   * <p>
266   * <!-- Don't remove the leading </dl> below. It's a hack for javadoc. -->
267</dl><dl class='docnote'><dt><b>Documentation note:</b></dt><dd>
268The native C++ implementation of this method defines a default argument
269value. In the documentation generated for different libSBML language
270bindings, you may or may not see corresponding arguments in the method
271declarations. For example, in Java and C#, a default argument is handled by
272declaring two separate methods, with one of them having the argument and
273the other one lacking the argument. However, the libSBML documentation will
274be <em>identical</em> for both methods. Consequently, if you are reading
275this and do not see an argument even though one is described, please look
276for descriptions of other variants of this method near where this one
277appears in the documentation.
278</dd></dl>
279 
280   */ public
281 XMLNode(XMLTriple triple, XMLAttributes attributes, XMLNamespaces namespaces) throws org.sbml.libsbml.XMLConstructorException {
282    this(libsbmlJNI.new_XMLNode__SWIG_4(XMLTriple.getCPtr(triple), triple, XMLAttributes.getCPtr(attributes), attributes, XMLNamespaces.getCPtr(namespaces), namespaces), true);
283  }
284
285  
286/**
287   * Creates a start element {@link XMLNode} with the given set of attributes.
288   * <p>
289   * @param triple {@link XMLTriple}.
290   * @param attributes {@link XMLAttributes}, the attributes to set.
291   * @param line a long integer, the line number (default = 0).
292   * @param column a long integer, the column number (default = 0).
293   * <p>
294   * <!-- Don't remove the leading </dl> below. It's a hack for javadoc. -->
295</dl><dl class='docnote'><dt><b>Documentation note:</b></dt><dd>
296The native C++ implementation of this method defines a default argument
297value. In the documentation generated for different libSBML language
298bindings, you may or may not see corresponding arguments in the method
299declarations. For example, in Java and C#, a default argument is handled by
300declaring two separate methods, with one of them having the argument and
301the other one lacking the argument. However, the libSBML documentation will
302be <em>identical</em> for both methods. Consequently, if you are reading
303this and do not see an argument even though one is described, please look
304for descriptions of other variants of this method near where this one
305appears in the documentation.
306</dd></dl>
307 
308  */ public
309 XMLNode(XMLTriple triple, XMLAttributes attributes, long line, long column) throws org.sbml.libsbml.XMLConstructorException {
310    this(libsbmlJNI.new_XMLNode__SWIG_5(XMLTriple.getCPtr(triple), triple, XMLAttributes.getCPtr(attributes), attributes, line, column), true);
311  }
312
313  
314/**
315   * Creates a start element {@link XMLNode} with the given set of attributes.
316   * <p>
317   * @param triple {@link XMLTriple}.
318   * @param attributes {@link XMLAttributes}, the attributes to set.
319   * @param line a long integer, the line number (default = 0).
320   * @param column a long integer, the column number (default = 0).
321   * <p>
322   * <!-- Don't remove the leading </dl> below. It's a hack for javadoc. -->
323</dl><dl class='docnote'><dt><b>Documentation note:</b></dt><dd>
324The native C++ implementation of this method defines a default argument
325value. In the documentation generated for different libSBML language
326bindings, you may or may not see corresponding arguments in the method
327declarations. For example, in Java and C#, a default argument is handled by
328declaring two separate methods, with one of them having the argument and
329the other one lacking the argument. However, the libSBML documentation will
330be <em>identical</em> for both methods. Consequently, if you are reading
331this and do not see an argument even though one is described, please look
332for descriptions of other variants of this method near where this one
333appears in the documentation.
334</dd></dl>
335 
336  */ public
337 XMLNode(XMLTriple triple, XMLAttributes attributes, long line) throws org.sbml.libsbml.XMLConstructorException {
338    this(libsbmlJNI.new_XMLNode__SWIG_6(XMLTriple.getCPtr(triple), triple, XMLAttributes.getCPtr(attributes), attributes, line), true);
339  }
340
341  
342/**
343   * Creates a start element {@link XMLNode} with the given set of attributes.
344   * <p>
345   * @param triple {@link XMLTriple}.
346   * @param attributes {@link XMLAttributes}, the attributes to set.
347   * @param line a long integer, the line number (default = 0).
348   * @param column a long integer, the column number (default = 0).
349   * <p>
350   * <!-- Don't remove the leading </dl> below. It's a hack for javadoc. -->
351</dl><dl class='docnote'><dt><b>Documentation note:</b></dt><dd>
352The native C++ implementation of this method defines a default argument
353value. In the documentation generated for different libSBML language
354bindings, you may or may not see corresponding arguments in the method
355declarations. For example, in Java and C#, a default argument is handled by
356declaring two separate methods, with one of them having the argument and
357the other one lacking the argument. However, the libSBML documentation will
358be <em>identical</em> for both methods. Consequently, if you are reading
359this and do not see an argument even though one is described, please look
360for descriptions of other variants of this method near where this one
361appears in the documentation.
362</dd></dl>
363 
364  */ public
365 XMLNode(XMLTriple triple, XMLAttributes attributes) throws org.sbml.libsbml.XMLConstructorException {
366    this(libsbmlJNI.new_XMLNode__SWIG_7(XMLTriple.getCPtr(triple), triple, XMLAttributes.getCPtr(attributes), attributes), true);
367  }
368
369  
370/**
371   * Creates an end element {@link XMLNode}.
372   * <p>
373   * @param triple {@link XMLTriple}.
374   * @param line a long integer, the line number (default = 0).
375   * @param column a long integer, the column number (default = 0).
376   * <p>
377   * <!-- Don't remove the leading </dl> below. It's a hack for javadoc. -->
378</dl><dl class='docnote'><dt><b>Documentation note:</b></dt><dd>
379The native C++ implementation of this method defines a default argument
380value. In the documentation generated for different libSBML language
381bindings, you may or may not see corresponding arguments in the method
382declarations. For example, in Java and C#, a default argument is handled by
383declaring two separate methods, with one of them having the argument and
384the other one lacking the argument. However, the libSBML documentation will
385be <em>identical</em> for both methods. Consequently, if you are reading
386this and do not see an argument even though one is described, please look
387for descriptions of other variants of this method near where this one
388appears in the documentation.
389</dd></dl>
390 
391   */ public
392 XMLNode(XMLTriple triple, long line, long column) throws org.sbml.libsbml.XMLConstructorException {
393    this(libsbmlJNI.new_XMLNode__SWIG_8(XMLTriple.getCPtr(triple), triple, line, column), true);
394  }
395
396  
397/**
398   * Creates an end element {@link XMLNode}.
399   * <p>
400   * @param triple {@link XMLTriple}.
401   * @param line a long integer, the line number (default = 0).
402   * @param column a long integer, the column number (default = 0).
403   * <p>
404   * <!-- Don't remove the leading </dl> below. It's a hack for javadoc. -->
405</dl><dl class='docnote'><dt><b>Documentation note:</b></dt><dd>
406The native C++ implementation of this method defines a default argument
407value. In the documentation generated for different libSBML language
408bindings, you may or may not see corresponding arguments in the method
409declarations. For example, in Java and C#, a default argument is handled by
410declaring two separate methods, with one of them having the argument and
411the other one lacking the argument. However, the libSBML documentation will
412be <em>identical</em> for both methods. Consequently, if you are reading
413this and do not see an argument even though one is described, please look
414for descriptions of other variants of this method near where this one
415appears in the documentation.
416</dd></dl>
417 
418   */ public
419 XMLNode(XMLTriple triple, long line) throws org.sbml.libsbml.XMLConstructorException {
420    this(libsbmlJNI.new_XMLNode__SWIG_9(XMLTriple.getCPtr(triple), triple, line), true);
421  }
422
423  
424/**
425   * Creates an end element {@link XMLNode}.
426   * <p>
427   * @param triple {@link XMLTriple}.
428   * @param line a long integer, the line number (default = 0).
429   * @param column a long integer, the column number (default = 0).
430   * <p>
431   * <!-- Don't remove the leading </dl> below. It's a hack for javadoc. -->
432</dl><dl class='docnote'><dt><b>Documentation note:</b></dt><dd>
433The native C++ implementation of this method defines a default argument
434value. In the documentation generated for different libSBML language
435bindings, you may or may not see corresponding arguments in the method
436declarations. For example, in Java and C#, a default argument is handled by
437declaring two separate methods, with one of them having the argument and
438the other one lacking the argument. However, the libSBML documentation will
439be <em>identical</em> for both methods. Consequently, if you are reading
440this and do not see an argument even though one is described, please look
441for descriptions of other variants of this method near where this one
442appears in the documentation.
443</dd></dl>
444 
445   */ public
446 XMLNode(XMLTriple triple) throws org.sbml.libsbml.XMLConstructorException {
447    this(libsbmlJNI.new_XMLNode__SWIG_10(XMLTriple.getCPtr(triple), triple), true);
448  }
449
450  
451/**
452   * Creates a text {@link XMLNode}.
453   * <p>
454   * @param chars a string, the text to be added to the {@link XMLToken}
455   * @param line a long integer, the line number (default = 0).
456   * @param column a long integer, the column number (default = 0).
457   * <p>
458   * <!-- Don't remove the leading </dl> below. It's a hack for javadoc. -->
459</dl><dl class='docnote'><dt><b>Documentation note:</b></dt><dd>
460The native C++ implementation of this method defines a default argument
461value. In the documentation generated for different libSBML language
462bindings, you may or may not see corresponding arguments in the method
463declarations. For example, in Java and C#, a default argument is handled by
464declaring two separate methods, with one of them having the argument and
465the other one lacking the argument. However, the libSBML documentation will
466be <em>identical</em> for both methods. Consequently, if you are reading
467this and do not see an argument even though one is described, please look
468for descriptions of other variants of this method near where this one
469appears in the documentation.
470</dd></dl>
471 
472   */ public
473 XMLNode(String chars, long line, long column) throws org.sbml.libsbml.XMLConstructorException {
474    this(libsbmlJNI.new_XMLNode__SWIG_11(chars, line, column), true);
475  }
476
477  
478/**
479   * Creates a text {@link XMLNode}.
480   * <p>
481   * @param chars a string, the text to be added to the {@link XMLToken}
482   * @param line a long integer, the line number (default = 0).
483   * @param column a long integer, the column number (default = 0).
484   * <p>
485   * <!-- Don't remove the leading </dl> below. It's a hack for javadoc. -->
486</dl><dl class='docnote'><dt><b>Documentation note:</b></dt><dd>
487The native C++ implementation of this method defines a default argument
488value. In the documentation generated for different libSBML language
489bindings, you may or may not see corresponding arguments in the method
490declarations. For example, in Java and C#, a default argument is handled by
491declaring two separate methods, with one of them having the argument and
492the other one lacking the argument. However, the libSBML documentation will
493be <em>identical</em> for both methods. Consequently, if you are reading
494this and do not see an argument even though one is described, please look
495for descriptions of other variants of this method near where this one
496appears in the documentation.
497</dd></dl>
498 
499   */ public
500 XMLNode(String chars, long line) throws org.sbml.libsbml.XMLConstructorException {
501    this(libsbmlJNI.new_XMLNode__SWIG_12(chars, line), true);
502  }
503
504  
505/**
506   * Creates a text {@link XMLNode}.
507   * <p>
508   * @param chars a string, the text to be added to the {@link XMLToken}
509   * @param line a long integer, the line number (default = 0).
510   * @param column a long integer, the column number (default = 0).
511   * <p>
512   * <!-- Don't remove the leading </dl> below. It's a hack for javadoc. -->
513</dl><dl class='docnote'><dt><b>Documentation note:</b></dt><dd>
514The native C++ implementation of this method defines a default argument
515value. In the documentation generated for different libSBML language
516bindings, you may or may not see corresponding arguments in the method
517declarations. For example, in Java and C#, a default argument is handled by
518declaring two separate methods, with one of them having the argument and
519the other one lacking the argument. However, the libSBML documentation will
520be <em>identical</em> for both methods. Consequently, if you are reading
521this and do not see an argument even though one is described, please look
522for descriptions of other variants of this method near where this one
523appears in the documentation.
524</dd></dl>
525 
526   */ public
527 XMLNode(String chars) throws org.sbml.libsbml.XMLConstructorException {
528    this(libsbmlJNI.new_XMLNode__SWIG_13(chars), true);
529  }
530
531  
532/**
533   * Creates a new {@link XMLNode} by reading XMLTokens from stream.  
534   * <p>
535   * The stream must be positioned on a start element
536   * (<code>stream.peek().isStart() == true</code>) and will be read until
537   * the matching end element is found.
538   * <p>
539   * @param stream XMLInputStream from which {@link XMLNode} is to be created.
540   * @internal
541   */ public
542 XMLNode(XMLInputStream stream) throws org.sbml.libsbml.XMLConstructorException {
543    this(libsbmlJNI.new_XMLNode__SWIG_14(XMLInputStream.getCPtr(stream), stream), true);
544  }
545
546  
547/**
548   * Copy constructor; creates a copy of this {@link XMLNode}.
549   * <p>
550   * @param orig the {@link XMLNode} instance to copy.
551   * <p>
552   * @throws XMLConstructorException 
553   * Thrown if the argument <code>orig</code> is <code>null.</code>
554   */ public
555 XMLNode(XMLNode orig) throws org.sbml.libsbml.XMLConstructorException {
556    this(libsbmlJNI.new_XMLNode__SWIG_15(XMLNode.getCPtr(orig), orig), true);
557  }
558
559  
560/**
561   * Creates and returns a deep copy of this {@link XMLNode}.
562   * <p>
563   * @return a (deep) copy of this {@link XMLNode}.
564   */ public
565 XMLNode cloneObject() {
566    long cPtr = libsbmlJNI.XMLNode_cloneObject(swigCPtr, this);
567    return (cPtr == 0) ? null : new XMLNode(cPtr, true);
568  }
569
570  
571/**
572   * Adds a copy of <code>node</code> as a child of this {@link XMLNode}.
573   * <p>
574   * The given <code>node</code> is added at the end of the list of children.
575   * <p>
576   * @param node the {@link XMLNode} to be added as child.
577   * <p>
578   * @return integer value indicating success/failure of the
579   * function.   The possible values
580   * returned by this function are:
581   * <ul>
582   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS }
583   * <li> {@link  libsbmlConstants#LIBSBML_INVALID_XML_OPERATION LIBSBML_INVALID_XML_OPERATION }
584   * </ul>
585   * <p>
586   * @note The given node is added at the end of the children list.
587   */ public
588 int addChild(XMLNode node) {
589    return libsbmlJNI.XMLNode_addChild(swigCPtr, this, XMLNode.getCPtr(node), node);
590  }
591
592  
593/**
594   * Inserts a copy of the given node as the <code>n</code>th child of this
595   * {@link XMLNode}.
596   * <p>
597   * If the given index <code>n</code> is out of range for this {@link XMLNode} instance,
598   * the <code>node</code> is added at the end of the list of children.  Even in
599   * that situation, this method does not throw an error.
600   * <p>
601   * @param n an integer, the index at which the given node is inserted
602   * @param node an {@link XMLNode} to be inserted as <code>n</code>th child.
603   * <p>
604   * @return a reference to the newly-inserted child <code>node</code>
605   */ public
606 XMLNode insertChild(long n, XMLNode node) {
607    return new XMLNode(libsbmlJNI.XMLNode_insertChild(swigCPtr, this, n, XMLNode.getCPtr(node), node), false);
608  }
609
610  
611/**
612   * Removes the <code>n</code>th child of this {@link XMLNode} and returns the
613   * removed node.
614   * <p>
615   * It is important to keep in mind that a given {@link XMLNode} may have more
616   * than one child.  Calling this method erases all existing references to
617   * child nodes <em>after</em> the given position <code>n</code>.  If the index <code>n</code> is
618   * greater than the number of child nodes in this {@link XMLNode}, this method
619   * takes no action (and returns <code>null</code>).
620   * <p>
621   * @param n an integer, the index of the node to be removed
622   * <p>
623   * @return the removed child, or <code>null</code> if <code>n</code> is greater than the number
624   * of children in this node
625   * <p>
626   * @note The caller owns the returned node and is responsible for deleting it.
627   */ public
628 XMLNode removeChild(long n) {
629    long cPtr = libsbmlJNI.XMLNode_removeChild(swigCPtr, this, n);
630    return (cPtr == 0) ? null : new XMLNode(cPtr, true);
631  }
632
633  
634/**
635   * Removes all children from this node.
636   * @return integer value indicating success/failure of the
637   * function.   The possible values
638   * returned by this function are:
639   * <ul>
640   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS }
641   * </ul>
642   */ public
643 int removeChildren() {
644    return libsbmlJNI.XMLNode_removeChildren(swigCPtr, this);
645  }
646
647  
648/**
649   * Returns the <code>n</code>th child of this {@link XMLNode}.
650   * <p>
651   * If the index <code>n</code> is greater than the number of child nodes, or it is
652   * 0 or less, this method returns an empty node.
653   * <p>
654   * @param n the index of the node to return
655   * <p>
656   * @return the  <code>n</code>th child of this {@link XMLNode}.
657   */ public
658 XMLNode getChild(long n) {
659    return new XMLNode(libsbmlJNI.XMLNode_getChild__SWIG_0(swigCPtr, this, n), false);
660  }
661
662  
663/**
664   * Returns the first child of this {@link XMLNode} with the corresponding name.
665   * <p>
666   * If no child with corrsponding name can be found, 
667   * this method returns an empty node.
668   * <p>
669   * @param name the name of the node to return
670   * <p>
671   * @return the first child of this {@link XMLNode} with given name.
672   */ public
673 XMLNode getChild(String name) {
674    return new XMLNode(libsbmlJNI.XMLNode_getChild__SWIG_2(swigCPtr, this, name), false);
675  }
676
677  
678/**
679   * Return the index of the first child of this {@link XMLNode} with the given name.
680   * <p>
681   * @param name a string, the name of the child for which the 
682   * index is required.
683   * <p>
684   * @return the index of the first child of this {@link XMLNode} with the given
685   * name, or -1 if not present.
686   */ public
687 int getIndex(String name) {
688    return libsbmlJNI.XMLNode_getIndex(swigCPtr, this, name);
689  }
690
691  
692/**
693   * Return a boolean indicating whether this {@link XMLNode} has a child with the
694   * given name.
695   * <p>
696   * @param name a string, the name of the child to be checked.
697   * <p>
698   * @return boolean indicating whether this {@link XMLNode} has a child with the
699   * given name.
700   */ public
701 boolean hasChild(String name) {
702    return libsbmlJNI.XMLNode_hasChild(swigCPtr, this, name);
703  }
704
705  
706/**
707   * Compare this {@link XMLNode} against another {@link XMLNode} returning true if both
708   * nodes represent the same XML tree, or false otherwise.
709   * <p>
710   * @param other another {@link XMLNode} to compare against.
711   * <p>
712   * @param ignoreURI whether to ignore the namespace URI when doing the
713   * comparison.
714   * <p>
715   * @return boolean indicating whether this {@link XMLNode} represents the same XML
716   * tree as another.
717   */ public
718 boolean xmlEquals(XMLNode other, boolean ignoreURI) {
719    return libsbmlJNI.XMLNode_xmlEquals__SWIG_0(swigCPtr, this, XMLNode.getCPtr(other), other, ignoreURI);
720  }
721
722  
723/**
724   * Compare this {@link XMLNode} against another {@link XMLNode} returning true if both
725   * nodes represent the same XML tree, or false otherwise.
726   * <p>
727   * @param other another {@link XMLNode} to compare against.
728   * <p>
729   * @param ignoreURI whether to ignore the namespace URI when doing the
730   * comparison.
731   * <p>
732   * @return boolean indicating whether this {@link XMLNode} represents the same XML
733   * tree as another.
734   */ public
735 boolean xmlEquals(XMLNode other) {
736    return libsbmlJNI.XMLNode_xmlEquals__SWIG_1(swigCPtr, this, XMLNode.getCPtr(other), other);
737  }
738
739  
740/**
741   * Returns the number of children for this {@link XMLNode}.
742   * <p>
743   * @return the number of children for this {@link XMLNode}.
744   */ public
745 long getNumChildren() {
746    return libsbmlJNI.XMLNode_getNumChildren(swigCPtr, this);
747  }
748
749  
750/**
751   * Returns a string representation of this {@link XMLNode}. 
752   * <p>
753   * @return a string derived from this {@link XMLNode}.
754   */ public
755 String toXMLString() {
756    return libsbmlJNI.XMLNode_toXMLString(swigCPtr, this);
757  }
758
759  
760/**
761   * Returns a string representation of a given {@link XMLNode}. 
762   * <p>
763   * @param node the {@link XMLNode} to be represented as a string
764   * <p>
765   * @return a string-form representation of <code>node</code>
766   */ public
767 static String convertXMLNodeToString(XMLNode node) {
768    return libsbmlJNI.XMLNode_convertXMLNodeToString(XMLNode.getCPtr(node), node);
769  }
770
771  
772/**
773   * Returns an {@link XMLNode} which is derived from a string containing XML
774   * content.
775   * <p>
776   * The XML namespace must be defined using argument <code>xmlns</code> if the
777   * corresponding XML namespace attribute is not part of the string of the
778   * first argument.
779   * <p>
780   * @param xmlstr string to be converted to a XML node.
781   * @param xmlns {@link XMLNamespaces} the namespaces to set (default value is <code>null</code>).
782   * <p>
783   * @note The caller owns the returned {@link XMLNode} and is reponsible for
784   * deleting it.  The returned {@link XMLNode} object is a dummy root (container)
785   * {@link XMLNode} if the top-level element in the given XML string is NOT
786   * <code>&lt;html&gt;</code>, <code>&lt;body&gt;</code>,
787   * <code>&lt;annotation&gt;</code>, or <code>&lt;notes&gt;</code>.  In
788   * the dummy root node, each top-level element in the given XML string is
789   * contained as a child {@link XMLNode}. {@link XMLToken#isEOF()} can be used to
790   * identify if the returned {@link XMLNode} object is a dummy node.
791   * <p>
792   * @return a {@link XMLNode} which is converted from string <code>xmlstr</code>.  If the
793   * conversion failed, this method returns <code>null.</code>
794   * <p>
795   * <!-- Don't remove the leading </dl> below. It's a hack for javadoc. -->
796</dl><dl class='docnote'><dt><b>Documentation note:</b></dt><dd>
797The native C++ implementation of this method defines a default argument
798value. In the documentation generated for different libSBML language
799bindings, you may or may not see corresponding arguments in the method
800declarations. For example, in Java and C#, a default argument is handled by
801declaring two separate methods, with one of them having the argument and
802the other one lacking the argument. However, the libSBML documentation will
803be <em>identical</em> for both methods. Consequently, if you are reading
804this and do not see an argument even though one is described, please look
805for descriptions of other variants of this method near where this one
806appears in the documentation.
807</dd></dl>
808 
809   */ public
810 static XMLNode convertStringToXMLNode(String xmlstr, XMLNamespaces xmlns) {
811    long cPtr = libsbmlJNI.XMLNode_convertStringToXMLNode__SWIG_0(xmlstr, XMLNamespaces.getCPtr(xmlns), xmlns);
812    return (cPtr == 0) ? null : new XMLNode(cPtr, true);
813  }
814
815  
816/**
817   * Returns an {@link XMLNode} which is derived from a string containing XML
818   * content.
819   * <p>
820   * The XML namespace must be defined using argument <code>xmlns</code> if the
821   * corresponding XML namespace attribute is not part of the string of the
822   * first argument.
823   * <p>
824   * @param xmlstr string to be converted to a XML node.
825   * @param xmlns {@link XMLNamespaces} the namespaces to set (default value is <code>null</code>).
826   * <p>
827   * @note The caller owns the returned {@link XMLNode} and is reponsible for
828   * deleting it.  The returned {@link XMLNode} object is a dummy root (container)
829   * {@link XMLNode} if the top-level element in the given XML string is NOT
830   * <code>&lt;html&gt;</code>, <code>&lt;body&gt;</code>,
831   * <code>&lt;annotation&gt;</code>, or <code>&lt;notes&gt;</code>.  In
832   * the dummy root node, each top-level element in the given XML string is
833   * contained as a child {@link XMLNode}. {@link XMLToken#isEOF()} can be used to
834   * identify if the returned {@link XMLNode} object is a dummy node.
835   * <p>
836   * @return a {@link XMLNode} which is converted from string <code>xmlstr</code>.  If the
837   * conversion failed, this method returns <code>null.</code>
838   * <p>
839   * <!-- Don't remove the leading </dl> below. It's a hack for javadoc. -->
840</dl><dl class='docnote'><dt><b>Documentation note:</b></dt><dd>
841The native C++ implementation of this method defines a default argument
842value. In the documentation generated for different libSBML language
843bindings, you may or may not see corresponding arguments in the method
844declarations. For example, in Java and C#, a default argument is handled by
845declaring two separate methods, with one of them having the argument and
846the other one lacking the argument. However, the libSBML documentation will
847be <em>identical</em> for both methods. Consequently, if you are reading
848this and do not see an argument even though one is described, please look
849for descriptions of other variants of this method near where this one
850appears in the documentation.
851</dd></dl>
852 
853   */ public
854 static XMLNode convertStringToXMLNode(String xmlstr) {
855    long cPtr = libsbmlJNI.XMLNode_convertStringToXMLNode__SWIG_1(xmlstr);
856    return (cPtr == 0) ? null : new XMLNode(cPtr, true);
857  }
858
859}