001/* ----------------------------------------------------------------------------
002 * This file was automatically generated by SWIG (http://www.swig.org).
003 * Version 3.0.8
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 *  An interface to an XML input stream.
013 <p>
014 * <p style='color: #777; font-style: italic'>
015This class of objects is defined by libSBML only and has no direct
016equivalent in terms of SBML components.  This class is not prescribed by
017the SBML specifications, although it is used to implement features
018defined in SBML.
019</p>
020
021 <p>
022 * SBML content is serialized using XML; the resulting data can be stored and
023 * read to/from a file or data stream.  Low-level XML parsers such as Xerces
024 * provide facilities to read XML data.  To permit the use of different XML
025 * parsers (Xerces, Expat or libxml2), libSBML implements an abstraction
026 * layer.  {@link XMLInputStream} and {@link XMLOutputStream} are two parts of that
027 * abstraction layer.
028 <p>
029 * {@link XMLInputStream} is an interface to a file or text string containing XML.
030 * It wraps the content to be read, as well as the low-level XML parser to be
031 * used and an {@link XMLErrorLog} to record errors and other issues (if any arise).
032 * Internally, the content will be in the form of either a pointer to a file
033 * name or a character string; {@link XMLInputStream} knows the form of the content
034 * and acts appropriately.  Other libSBML object classes use {@link XMLInputStream}
035 * as their interface for all read operations on the XML data.
036 * {@link XMLInputStream} provides the functionality to extract data in the form of
037 * {@link XMLToken} objects.  It logs any errors encountered while reading.  It also
038 * keeps track of whether a read operation has failed irrecoverably or
039 * determines whether it is safe to continue reading.
040 <p>
041 * {@link SBMLNamespaces} objects can be associated with an {@link XMLInputStream}; this
042 * facilitates logging errors related to reading XML attributes and elements
043 * that may only be relevant to particular Level and Version combinations of
044 * SBML.
045 <p>
046 * @note The convenience of the {@link XMLInputStream} and {@link XMLOutputStream}
047 * abstraction may be useful for developers interested in creating parsers
048 * for other XML formats besides SBML.  It can provide developers with a
049 * layer above more basic XML parsers, as well as some useful programmatic
050 * elements such as {@link XMLToken}, {@link XMLError}, etc.
051 <p>
052 * @see XMLOutputStream
053 */
054
055public class XMLInputStream {
056   private long swigCPtr;
057   protected boolean swigCMemOwn;
058
059   protected XMLInputStream(long cPtr, boolean cMemoryOwn)
060   {
061     swigCMemOwn = cMemoryOwn;
062     swigCPtr    = cPtr;
063   }
064
065   protected static long getCPtr(XMLInputStream obj)
066   {
067     return (obj == null) ? 0 : obj.swigCPtr;
068   }
069
070   protected static long getCPtrAndDisown (XMLInputStream obj)
071   {
072     long ptr = 0;
073
074     if (obj != null)
075     {
076       ptr             = obj.swigCPtr;
077       obj.swigCMemOwn = false;
078     }
079
080     return ptr;
081   }
082
083  protected void finalize() {
084    delete();
085  }
086
087  public synchronized void delete() {
088    if (swigCPtr != 0) {
089      if (swigCMemOwn) {
090        swigCMemOwn = false;
091        libsbmlJNI.delete_XMLInputStream(swigCPtr);
092      }
093      swigCPtr = 0;
094    }
095  }
096
097  
098/**
099   * Creates a new {@link XMLInputStream}.
100   <p>
101   * @param content the source of the stream.
102   <p>
103   * @param isFile a boolean flag to indicate whether <code>content</code> is a file
104   * name.  If <code>true</code>, <code>content</code> is assumed to be the file from which the
105   * XML content is to be read.  If <code>false</code>, <code>content</code> is taken to be a
106   * string that <em>is</em> the content to be read.
107   <p>
108   * @param library the name of the parser library to use.
109   <p>
110   * @param errorLog the {@link XMLErrorLog} object to use.
111   <p>
112   * 
113</dl><dl class="docnote"><dt><b>Documentation note:</b></dt><dd>
114The native C++ implementation of this method defines a default argument
115value. In the documentation generated for different libSBML language
116bindings, you may or may not see corresponding arguments in the method
117declarations. For example, in Java and C#, a default argument is handled by
118declaring two separate methods, with one of them having the argument and
119the other one lacking the argument. However, the libSBML documentation will
120be <em>identical</em> for both methods. Consequently, if you are reading
121this and do not see an argument even though one is described, please look
122for descriptions of other variants of this method near where this one
123appears in the documentation.
124</dd></dl>
125 
126   */ public
127 XMLInputStream(String content, boolean isFile, String library, XMLErrorLog errorLog) {
128    this(libsbmlJNI.new_XMLInputStream__SWIG_0(content, isFile, library, XMLErrorLog.getCPtr(errorLog), errorLog), true);
129  }
130
131  
132/**
133   * Creates a new {@link XMLInputStream}.
134   <p>
135   * @param content the source of the stream.
136   <p>
137   * @param isFile a boolean flag to indicate whether <code>content</code> is a file
138   * name.  If <code>true</code>, <code>content</code> is assumed to be the file from which the
139   * XML content is to be read.  If <code>false</code>, <code>content</code> is taken to be a
140   * string that <em>is</em> the content to be read.
141   <p>
142   * @param library the name of the parser library to use.
143   <p>
144   * @param errorLog the {@link XMLErrorLog} object to use.
145   <p>
146   * 
147</dl><dl class="docnote"><dt><b>Documentation note:</b></dt><dd>
148The native C++ implementation of this method defines a default argument
149value. In the documentation generated for different libSBML language
150bindings, you may or may not see corresponding arguments in the method
151declarations. For example, in Java and C#, a default argument is handled by
152declaring two separate methods, with one of them having the argument and
153the other one lacking the argument. However, the libSBML documentation will
154be <em>identical</em> for both methods. Consequently, if you are reading
155this and do not see an argument even though one is described, please look
156for descriptions of other variants of this method near where this one
157appears in the documentation.
158</dd></dl>
159 
160   */ public
161 XMLInputStream(String content, boolean isFile, String library) {
162    this(libsbmlJNI.new_XMLInputStream__SWIG_1(content, isFile, library), true);
163  }
164
165  
166/**
167   * Creates a new {@link XMLInputStream}.
168   <p>
169   * @param content the source of the stream.
170   <p>
171   * @param isFile a boolean flag to indicate whether <code>content</code> is a file
172   * name.  If <code>true</code>, <code>content</code> is assumed to be the file from which the
173   * XML content is to be read.  If <code>false</code>, <code>content</code> is taken to be a
174   * string that <em>is</em> the content to be read.
175   <p>
176   * @param library the name of the parser library to use.
177   <p>
178   * @param errorLog the {@link XMLErrorLog} object to use.
179   <p>
180   * 
181</dl><dl class="docnote"><dt><b>Documentation note:</b></dt><dd>
182The native C++ implementation of this method defines a default argument
183value. In the documentation generated for different libSBML language
184bindings, you may or may not see corresponding arguments in the method
185declarations. For example, in Java and C#, a default argument is handled by
186declaring two separate methods, with one of them having the argument and
187the other one lacking the argument. However, the libSBML documentation will
188be <em>identical</em> for both methods. Consequently, if you are reading
189this and do not see an argument even though one is described, please look
190for descriptions of other variants of this method near where this one
191appears in the documentation.
192</dd></dl>
193 
194   */ public
195 XMLInputStream(String content, boolean isFile) {
196    this(libsbmlJNI.new_XMLInputStream__SWIG_2(content, isFile), true);
197  }
198
199  
200/**
201   * Creates a new {@link XMLInputStream}.
202   <p>
203   * @param content the source of the stream.
204   <p>
205   * @param isFile a boolean flag to indicate whether <code>content</code> is a file
206   * name.  If <code>true</code>, <code>content</code> is assumed to be the file from which the
207   * XML content is to be read.  If <code>false</code>, <code>content</code> is taken to be a
208   * string that <em>is</em> the content to be read.
209   <p>
210   * @param library the name of the parser library to use.
211   <p>
212   * @param errorLog the {@link XMLErrorLog} object to use.
213   <p>
214   * 
215</dl><dl class="docnote"><dt><b>Documentation note:</b></dt><dd>
216The native C++ implementation of this method defines a default argument
217value. In the documentation generated for different libSBML language
218bindings, you may or may not see corresponding arguments in the method
219declarations. For example, in Java and C#, a default argument is handled by
220declaring two separate methods, with one of them having the argument and
221the other one lacking the argument. However, the libSBML documentation will
222be <em>identical</em> for both methods. Consequently, if you are reading
223this and do not see an argument even though one is described, please look
224for descriptions of other variants of this method near where this one
225appears in the documentation.
226</dd></dl>
227 
228   */ public
229 XMLInputStream(String content) {
230    this(libsbmlJNI.new_XMLInputStream__SWIG_3(content), true);
231  }
232
233  
234/**
235   * Returns the encoding of the XML stream.
236   <p>
237   * <p>
238 The <em>encoding</em> is indicated by the <code>xml</code> declaration at the
239 * beginning of an XML document or data stream.  The form of this declaration
240 * is
241 * <pre class='fragment'>
242&lt;?xml version='1.0' encoding='UTF-8'?&gt;
243</pre>
244 * Note that the SBML specifications require the use of UTF-8 encoding, so
245 * for SBML documents, the value returned by this method will always be
246 * the string <code>'UTF-8'</code>. 
247   <p>
248   * @return the encoding of the XML stream.
249   <p>
250   * @see #getVersion()
251   */ public
252 String getEncoding() {
253    return libsbmlJNI.XMLInputStream_getEncoding(swigCPtr, this);
254  }
255
256  
257/**
258   * Returns the version of the XML stream.
259   <p>
260   * <p>
261 The <em>version</em> is indicated by the <code>xml</code> declaration at the
262 * beginning of an XML document or data stream.  The form of this declaration
263 * is
264 * <pre class='fragment'>
265 &lt;?xml version='1.0' encoding='UTF-8'?&gt;
266</pre>
267 * Note that the SBML specifications require the use of version 1.0, so
268 * for SBML documents, the value returned by this method will always be
269 * the string <code>'1.0'</code>. 
270   <p>
271   * @return the version of the XML stream.
272   <p>
273   * @see #getEncoding()
274   */ public
275 String getVersion() {
276    return libsbmlJNI.XMLInputStream_getVersion(swigCPtr, this);
277  }
278
279  
280/**
281   * Returns the {@link XMLErrorLog} used to log parsing problems.
282   <p>
283   * @return the {@link XMLErrorLog} used to log XML parse errors and other
284   * validation errors (and messages).
285   */ public
286 XMLErrorLog getErrorLog() {
287    long cPtr = libsbmlJNI.XMLInputStream_getErrorLog(swigCPtr, this);
288    return (cPtr == 0) ? null : new XMLErrorLog(cPtr, false);
289  }
290
291  
292/**
293   * Returns <code>true</code> if end of file (stream) has been reached.
294   <p>
295   * @return <code>true</code> if end of file (stream) has been reached, <code>false</code>
296   * otherwise.
297   */ public
298 boolean isEOF() {
299    return libsbmlJNI.XMLInputStream_isEOF(swigCPtr, this);
300  }
301
302  
303/**
304   * Returns <code>true</code> if a fatal error occurred while reading from this
305   * stream.
306   <p>
307   * @return <code>true</code> if a fatal error occurred while reading from this
308   * stream.
309   */ public
310 boolean isError() {
311    return libsbmlJNI.XMLInputStream_isError(swigCPtr, this);
312  }
313
314  
315/**
316   * Returns <code>true</code> if the stream is in a good state.
317   <p>
318   * The definition of 'good state' is that isEOF() and isError() both return
319   * <code>false.</code>
320   <p>
321   * @return <code>true</code> if the stream is in a good state, <code>false</code> otherwise.
322   */ public
323 boolean isGood() {
324    return libsbmlJNI.XMLInputStream_isGood(swigCPtr, this);
325  }
326
327  
328/**
329   * Returns the next token on this XML input stream.
330   <p>
331   * The token is consumed in the process.
332   <p>
333   * @return the next {@link XMLToken}, or an EOF token (i.e.,
334   * <code>XMLToken.isEOF() == true</code>).
335   <p>
336   * @see #peek()
337   */ public
338 XMLToken next() {
339    return new XMLToken(libsbmlJNI.XMLInputStream_next(swigCPtr, this), true);
340  }
341
342  
343/**
344   * Returns the next token <em>without</em> consuming it.
345   <p>
346   * A subsequent call to either peek() or next() will return the same token.
347   <p>
348   * @return the next {@link XMLToken} or EOF (XMLToken.isEOF() == true).
349   <p>
350   * @see #next()
351   */ public
352 XMLToken peek() {
353    return new XMLToken(libsbmlJNI.XMLInputStream_peek(swigCPtr, this), false);
354  }
355
356  
357/**
358   * Consume zero or more tokens up to and including the corresponding end
359   * element or EOF.
360   <p>
361   * @param element the element whose end will be sought in the input stream.
362   */ public
363 void skipPastEnd(XMLToken element) {
364    libsbmlJNI.XMLInputStream_skipPastEnd(swigCPtr, this, XMLToken.getCPtr(element), element);
365  }
366
367  
368/**
369   * Consume zero or more tokens up to but not including the next XML element
370   * or EOF.
371   */ public
372 void skipText() {
373    libsbmlJNI.XMLInputStream_skipText(swigCPtr, this);
374  }
375
376  
377/**
378   * Sets the {@link XMLErrorLog} this stream will use to log errors.
379   <p>
380   * <p>
381 * @return integer value indicating success/failure of the
382 * function.   The possible values
383 * returned by this function are:
384   * <ul>
385   * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS}
386   * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED}
387   * </ul>
388   */ public
389 int setErrorLog(XMLErrorLog log) {
390    return libsbmlJNI.XMLInputStream_setErrorLog(swigCPtr, this, XMLErrorLog.getCPtr(log), log);
391  }
392
393  
394/**
395   * Prints a string representation of the underlying token stream.
396   <p>
397   * @return a string representing the underlying XML token stream.
398   <p>
399   * @note This method is intended for debugging purposes.
400   */ public
401 String toString() {
402    return libsbmlJNI.XMLInputStream_toString(swigCPtr, this);
403  }
404
405  
406/**
407   * Returns the {@link SBMLNamespaces} object attached to this {@link XMLInputStream}.
408   <p>
409   * @return the {@link SBMLNamespaces} object or <code>null</code> if none has been set.
410   */ public
411 SBMLNamespaces getSBMLNamespaces() {
412  return libsbml.DowncastSBMLNamespaces(libsbmlJNI.XMLInputStream_getSBMLNamespaces(swigCPtr, this), false);
413}
414
415  
416/**
417   * Sets the SBML namespaces associated with this XML input stream.
418   <p>
419   * This allows this stream to reference the available SBML namespaces being
420   * read.
421   <p>
422   * @param sbmlns the list of namespaces to use.
423   */ public
424 void setSBMLNamespaces(SBMLNamespaces sbmlns) {
425    libsbmlJNI.XMLInputStream_setSBMLNamespaces(swigCPtr, this, SBMLNamespaces.getCPtr(sbmlns), sbmlns);
426  }
427
428  
429/**
430   * Returns the number of child tokens of the given element in this stream.
431   <p>
432   * This method allows information from the input stream to be determined
433   * without the need to actually read and consume the tokens in the stream.
434   * It returns the number of child elements of the element represented by
435   * the <code>elementName</code>, i.e., the number of child elements encountered
436   * before the closing tag for the <code>elementName</code> supplied.
437   <p>
438   * If no <code>elementName</code> is supplied or it is an empty string, then as a
439   * special case, this method assumes the element is a MathML
440   * <code>apply</code> element followed by a function name.
441   <p>
442   * @param elementName a string representing the name of the element for
443   * which the number of children are to be determined.
444   <p>
445   * @return a long integer giving the number of children of the 
446   * <code>elementName</code> specified.
447   <p>
448   * @note This method assumes the stream has been read up to and including
449   * the element <code>elementName</code>.
450   <p>
451   * 
452</dl><dl class="docnote"><dt><b>Documentation note:</b></dt><dd>
453The native C++ implementation of this method defines a default argument
454value. In the documentation generated for different libSBML language
455bindings, you may or may not see corresponding arguments in the method
456declarations. For example, in Java and C#, a default argument is handled by
457declaring two separate methods, with one of them having the argument and
458the other one lacking the argument. However, the libSBML documentation will
459be <em>identical</em> for both methods. Consequently, if you are reading
460this and do not see an argument even though one is described, please look
461for descriptions of other variants of this method near where this one
462appears in the documentation.
463</dd></dl>
464 
465   */ public
466 long determineNumberChildren(String elementName) {
467    return libsbmlJNI.XMLInputStream_determineNumberChildren__SWIG_0(swigCPtr, this, elementName);
468  }
469
470  
471/**
472   * Returns the number of child tokens of the given element in this stream.
473   <p>
474   * This method allows information from the input stream to be determined
475   * without the need to actually read and consume the tokens in the stream.
476   * It returns the number of child elements of the element represented by
477   * the <code>elementName</code>, i.e., the number of child elements encountered
478   * before the closing tag for the <code>elementName</code> supplied.
479   <p>
480   * If no <code>elementName</code> is supplied or it is an empty string, then as a
481   * special case, this method assumes the element is a MathML
482   * <code>apply</code> element followed by a function name.
483   <p>
484   * @param elementName a string representing the name of the element for
485   * which the number of children are to be determined.
486   <p>
487   * @return a long integer giving the number of children of the 
488   * <code>elementName</code> specified.
489   <p>
490   * @note This method assumes the stream has been read up to and including
491   * the element <code>elementName</code>.
492   <p>
493   * 
494</dl><dl class="docnote"><dt><b>Documentation note:</b></dt><dd>
495The native C++ implementation of this method defines a default argument
496value. In the documentation generated for different libSBML language
497bindings, you may or may not see corresponding arguments in the method
498declarations. For example, in Java and C#, a default argument is handled by
499declaring two separate methods, with one of them having the argument and
500the other one lacking the argument. However, the libSBML documentation will
501be <em>identical</em> for both methods. Consequently, if you are reading
502this and do not see an argument even though one is described, please look
503for descriptions of other variants of this method near where this one
504appears in the documentation.
505</dd></dl>
506 
507   */ public
508 long determineNumberChildren() {
509    return libsbmlJNI.XMLInputStream_determineNumberChildren__SWIG_1(swigCPtr, this);
510  }
511
512  
513/**
514   * Returns the number of child tokens of the specified type within a
515   * given container element.
516   <p>
517   * This method allows information from the input stream to be determined
518   * without the need to actually read and consume the tokens in the stream.
519   * It returns the number of child elements of the <code>childName</code> element
520   * within the element specified by <code>container</code>.  In other words, it counts
521   * the number of <code>childName</code> elements encountered before the closing tag
522   * for the <code>container</code> supplied.
523   <p>
524   * @param childName a string representing the name of the child
525   * element whose number is to be determined.
526   <p>
527   * @param container a string representing the name of the element
528   * for which the number of children are to be determined.
529   <p>
530   * @return a long integer giving the number of children of type 
531   * <code>childName</code> within the <code>container</code> element.
532   <p>
533   * @note This method assumes the stream has been read up to and including
534   * the element <code>container</code>.
535   */ public
536 long determineNumSpecificChildren(String childName, String container) {
537    return libsbmlJNI.XMLInputStream_determineNumSpecificChildren(swigCPtr, this, childName, container);
538  }
539
540  
541/**
542   * Predicate returning <code>true</code> if a child token of the specified type occurs 
543   * within a given container element.
544   <p>
545   * This method allows information from the input stream to be determined
546   * without the need to actually read and consume the tokens in the stream.
547   * It returns <code>true</code> if the <code>childName</code> element occurs at any point
548   * within the element specified by <code>container</code>.
549   <p>
550   * @param childName a string representing the name of the child
551   * element whose presence is to be determined.
552   <p>
553   * @param container a string representing the name of the element
554   * for which the presence of the child element is to be determined.
555   <p>
556   * @return boolean <code>true</code> if a child of type <code>childName</code> occurs within 
557   * the <code>container</code> element, <code>false</code> otherwise.
558   <p>
559   * @note This method assumes the stream has been read up to and including
560   * the element <code>container</code>.
561   */ public
562 boolean containsChild(String childName, String container) {
563    return libsbmlJNI.XMLInputStream_containsChild(swigCPtr, this, childName, container);
564  }
565
566}