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