001/* ----------------------------------------------------------------------------
002 * This file was automatically generated by SWIG (http://www.swig.org).
003 * Version 3.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 *  File and text-string SBML reader.
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 * The {@link SBMLReader} class provides the main interface for reading SBML content
023 * from files and strings.  The methods for reading SBML all return an
024 * {@link SBMLDocument} object representing the results.  In the case of failures
025 * (such as if the SBML contains errors or a file cannot be read), the errors
026 * will be recorded with the {@link SBMLErrorLog} object kept in the {@link SBMLDocument}
027 * returned by {@link SBMLReader}.  Consequently, immediately after calling a method
028 * on {@link SBMLReader}, callers should always check for errors and warnings using
029 * the methods for this purpose provided by {@link SBMLDocument}.
030 <p>
031 * For convenience as well as easy access from other languages besides C++,
032 * this file also defines two global functions,
033 * @sbmlglobalfunction{readSBML, String}global and
034 * @sbmlglobalfunction{readSBMLFromString, String}global.  They are
035 * equivalent to creating an {@link SBMLReader} object and then calling the
036 * {@link SBMLReader#readSBML(String)} and
037 * {@link SBMLReader#readSBMLFromString(String)} methods, respectively.
038 <p>
039 * <h2>Support for reading compressed files</h2>
040 <p>
041 * LibSBML provides support for reading (as well as writing) compressed
042 * SBML files.  The process is transparent to the calling
043 * application&mdash;the application does not need to do anything
044 * deliberate to invoke the functionality.  If a given SBML filename ends
045 * with an extension for the <em>gzip</em>, <em>zip</em> or <em>bzip2</em> compression
046 * formats (respectively, <code>.gz</code>, <code>.zip</code>, or <code>.bz2</code>), then the methods
047 * @link {@link SBMLReader#readSBML(String)} {@link SBMLReader}.readSBML(String)@endlink and
048 * @link {@link SBMLWriter#writeSBML(String)} {@link SBMLWriter}.writeSBML(String)@endlink
049 * will automatically decompress and compress the file while reading and
050 * writing it.  If the filename has no such extension, it will be read and
051 * written uncompressed as normal.
052 <p>
053 * The compression feature requires that the <em>zlib</em> (for <em>gzip</em> and 
054 * <em>zip</em> formats) and/or <em>bzip2</em> (for <em>bzip2</em> format) be available on the
055 * system running libSBML, and that libSBML was configured with their
056 * support compiled-in.  Please see the libSBML
057 * <a href='../../../libsbml-installation.html'>installation instructions</a> 
058 * for more information about this.  The methods
059 * {@link SBMLReader#hasZlib()} and
060 * {@link SBMLReader#hasBzip2()}
061 * can be used by an application to query at run-time whether support
062 * for the compression libraries is available in the present copy of
063 * libSBML.
064 <p>
065 * Support for compression is not mandated by the SBML standard, but
066 * applications may find it helpful, particularly when large SBML models
067 * are being communicated across data links of limited bandwidth.
068 */
069
070public class SBMLReader {
071   private long swigCPtr;
072   protected boolean swigCMemOwn;
073
074   protected SBMLReader(long cPtr, boolean cMemoryOwn)
075   {
076     swigCMemOwn = cMemoryOwn;
077     swigCPtr    = cPtr;
078   }
079
080   protected static long getCPtr(SBMLReader obj)
081   {
082     return (obj == null) ? 0 : obj.swigCPtr;
083   }
084
085   protected static long getCPtrAndDisown (SBMLReader obj)
086   {
087     long ptr = 0;
088
089     if (obj != null)
090     {
091       ptr             = obj.swigCPtr;
092       obj.swigCMemOwn = false;
093     }
094
095     return ptr;
096   }
097
098  protected void finalize() {
099    delete();
100  }
101
102  public synchronized void delete() {
103    if (swigCPtr != 0) {
104      if (swigCMemOwn) {
105        swigCMemOwn = false;
106        libsbmlJNI.delete_SBMLReader(swigCPtr);
107      }
108      swigCPtr = 0;
109    }
110  }
111
112  /**
113   * Equality comparison method for SBMLReader.
114   * <p>
115   * Because the Java methods for libSBML are actually wrappers around code
116   * implemented in C++ and C, certain operations will not behave as
117   * expected.  Equality comparison is one such case.  An instance of a
118   * libSBML object class is actually a <em>proxy object</em>
119   * wrapping the real underlying C/C++ object.  The normal <code>==</code>
120   * equality operator in Java will <em>only compare the Java proxy objects</em>,
121   * not the underlying native object.  The result is almost never what you
122   * want in practical situations.  Unfortunately, Java does not provide a
123   * way to override <code>==</code>.
124   *  <p>
125   * The alternative that must be followed is to use the
126   * <code>equals()</code> method.  The <code>equals</code> method on this
127   * class overrides the default java.lang.Object one, and performs an
128   * intelligent comparison of instances of objects of this class.  The
129   * result is an assessment of whether two libSBML Java objects are truly 
130   * the same underlying native-code objects.
131   *  <p>
132   * The use of this method in practice is the same as the use of any other
133   * Java <code>equals</code> method.  For example,
134   * <em>a</em><code>.equals(</code><em>b</em><code>)</code> returns
135   * <code>true</code> if <em>a</em> and <em>b</em> are references to the
136   * same underlying object.
137   *
138   * @param sb a reference to an object to which the current object
139   * instance will be compared
140   *
141   * @return <code>true</code> if <code>sb</code> refers to the same underlying 
142   * native object as this one, <code>false</code> otherwise
143   */
144  public boolean equals(Object sb)
145  {
146    if ( this == sb ) 
147    {
148      return true;
149    }
150    return swigCPtr == getCPtr((SBMLReader)(sb));
151  }
152
153  /**
154   * Returns a hashcode for this SBMLReader object.
155   *
156   * @return a hash code usable by Java methods that need them.
157   */
158  public int hashCode()
159  {
160    return (int)(swigCPtr^(swigCPtr>>>32));
161  }
162
163  
164/**
165   * Creates a new {@link SBMLReader} object and returns it.
166   <p>
167   * The libSBML {@link SBMLReader} object offers methods for reading SBML in
168   * XML form from files and text strings.
169   */ public
170 SBMLReader() {
171    this(libsbmlJNI.new_SBMLReader(), true);
172  }
173
174  
175/**
176   * <p>
177 * Reads an SBML document from the given file.
178 <p>
179 * If the file named <code>filename</code> does not exist or its content is not valid
180 * SBML, one or more errors will be logged with the {@link SBMLDocument} object
181 * returned by this method.  Callers can use the methods on {@link SBMLDocument} such
182 * as
183 * ,
184 * {@link SBMLDocument#getNumErrors()}
185 * and
186 <p>
187 * {@link SBMLDocument#getError(long)}
188 <p>
189 * to get the errors.  The object returned by
190 <p>
191 * {@link SBMLDocument#getError(long)}
192 <p>
193 * is an {@link SBMLError} object, and it has methods to get the error code,
194 * category, and severity level of the problem, as well as a textual
195 * description of the problem.  The possible severity levels range from
196 * informational messages to fatal errors; see the documentation for
197 * {@link SBMLError}
198 * for more information.
199 <p>
200 * If the file <code>filename</code> could not be read, the file-reading error will
201 * appear first.  The error code  can provide a clue about what
202 * happened.  For example, a file might be unreadable (either because it does
203 * not actually exist or because the user does not have the necessary access
204 * privileges to read it) or some sort of file operation error may have been
205 * reported by the underlying operating system.  Callers can check for these
206 * situations using a program fragment such as the following:
207 <p>
208<pre class='fragment'>
209{@link SBMLReader} reader = new {@link SBMLReader}();
210{@link SBMLDocument} doc  = reader.readSBMLFromFile(filename);
211
212if (doc.getNumErrors() &gt; 0)
213{
214    if (doc.getError(0).getErrorId() == libsbmlConstants.XMLFileUnreadable)
215    {
216        // Handle case of unreadable file here.
217    }
218    else if (doc.getError(0).getErrorId() == libsbmlConstants.XMLFileOperationError)
219    {
220        // Handle case of other file operation error here.
221    }
222    else
223    {
224        // Handle other error cases.
225    }
226}
227</pre>
228<p>
229 * <p>
230 * If the given filename ends with the suffix <code>'.gz'</code> (for example,
231 * <code>'myfile.xml.gz'</code>), the file is assumed to be compressed in <em>gzip</em>
232 * format and will be automatically decompressed upon reading.
233 * Similarly, if the given filename ends with <code>'.zip'</code> or <code>'.bz2'</code>, the
234 * file is assumed to be compressed in <em>zip</em> or <em>bzip2</em> format
235 * (respectively).  Files whose names lack these suffixes will be read
236 * uncompressed.  Note that if the file is in <em>zip</em> format but the
237 * archive contains more than one file, only the first file in the
238 * archive will be read and the rest ignored.
239 <p>
240 * <p>
241 * To read a gzip/zip file, libSBML needs to be configured and linked with the
242 * <a target='_blank' href='http://www.zlib.net/'>zlib</a> library at compile
243 * time.  It also needs to be linked with the <a target='_blank'
244 * href=''>bzip2</a> library to read files in <em>bzip2</em> format.  (Both of
245 * these are the default configurations for libSBML.)  Errors about unreadable
246 * files will be logged if a compressed filename is given and libSBML was
247 * <em>not</em> linked with the corresponding required library.
248   <p>
249   * This method is identical to
250   * @link {@link SBMLReader#readSBMLFromFile(String)} {@link SBMLReader}.readSBMLFromFile(String)@endlink.
251   <p>
252   * @param filename the name or full pathname of the file to be read.
253   <p>
254   * @return a pointer to the {@link SBMLDocument} object created from the SBML
255   * content in <code>filename</code>.
256   <p>
257   * <p>
258 * @note LibSBML versions 2.x and later versions behave differently in
259 * error handling in several respects.  One difference is how early some
260 * errors are caught and whether libSBML continues processing a file in
261 * the face of some early errors.  In general, libSBML versions after 2.x
262 * stop parsing SBML inputs sooner than libSBML version 2.x in the face
263 * of XML errors, because the errors may invalidate any further SBML
264 * content.  For example, a missing XML declaration at the beginning of
265 * the file was ignored by libSBML 2.x but in version 3.x and later, it
266 * will cause libSBML to stop parsing the rest of the input altogether.
267 * While this behavior may seem more severe and intolerant, it was
268 * necessary in order to provide uniform behavior regardless of which
269 * underlying XML parser (Expat, Xerces, libxml2) is being used by
270 * libSBML.  The XML parsers themselves behave differently in their error
271 * reporting, and sometimes libSBML has to resort to the lowest common
272 * denominator.
273   <p>
274   * @see #readSBMLFromString(String)
275   * @see SBMLError
276   * @see SBMLDocument
277   */ public
278 SBMLDocument readSBML(String filename) {
279    long cPtr = libsbmlJNI.SBMLReader_readSBML(swigCPtr, this, libsbml.getAbsolutePath(filename));
280    return (cPtr == 0) ? null : new SBMLDocument(cPtr, true);
281  }
282
283  
284/**
285   * <p>
286 * Reads an SBML document from the given file.
287 <p>
288 * If the file named <code>filename</code> does not exist or its content is not valid
289 * SBML, one or more errors will be logged with the {@link SBMLDocument} object
290 * returned by this method.  Callers can use the methods on {@link SBMLDocument} such
291 * as
292 * ,
293 * {@link SBMLDocument#getNumErrors()}
294 * and
295 <p>
296 * {@link SBMLDocument#getError(long)}
297 <p>
298 * to get the errors.  The object returned by
299 <p>
300 * {@link SBMLDocument#getError(long)}
301 <p>
302 * is an {@link SBMLError} object, and it has methods to get the error code,
303 * category, and severity level of the problem, as well as a textual
304 * description of the problem.  The possible severity levels range from
305 * informational messages to fatal errors; see the documentation for
306 * {@link SBMLError}
307 * for more information.
308 <p>
309 * If the file <code>filename</code> could not be read, the file-reading error will
310 * appear first.  The error code  can provide a clue about what
311 * happened.  For example, a file might be unreadable (either because it does
312 * not actually exist or because the user does not have the necessary access
313 * privileges to read it) or some sort of file operation error may have been
314 * reported by the underlying operating system.  Callers can check for these
315 * situations using a program fragment such as the following:
316 <p>
317<pre class='fragment'>
318{@link SBMLReader} reader = new {@link SBMLReader}();
319{@link SBMLDocument} doc  = reader.readSBMLFromFile(filename);
320
321if (doc.getNumErrors() &gt; 0)
322{
323    if (doc.getError(0).getErrorId() == libsbmlConstants.XMLFileUnreadable)
324    {
325        // Handle case of unreadable file here.
326    }
327    else if (doc.getError(0).getErrorId() == libsbmlConstants.XMLFileOperationError)
328    {
329        // Handle case of other file operation error here.
330    }
331    else
332    {
333        // Handle other error cases.
334    }
335}
336</pre>
337<p>
338 * <p>
339 * If the given filename ends with the suffix <code>'.gz'</code> (for example,
340 * <code>'myfile.xml.gz'</code>), the file is assumed to be compressed in <em>gzip</em>
341 * format and will be automatically decompressed upon reading.
342 * Similarly, if the given filename ends with <code>'.zip'</code> or <code>'.bz2'</code>, the
343 * file is assumed to be compressed in <em>zip</em> or <em>bzip2</em> format
344 * (respectively).  Files whose names lack these suffixes will be read
345 * uncompressed.  Note that if the file is in <em>zip</em> format but the
346 * archive contains more than one file, only the first file in the
347 * archive will be read and the rest ignored.
348 <p>
349 * <p>
350 * To read a gzip/zip file, libSBML needs to be configured and linked with the
351 * <a target='_blank' href='http://www.zlib.net/'>zlib</a> library at compile
352 * time.  It also needs to be linked with the <a target='_blank'
353 * href=''>bzip2</a> library to read files in <em>bzip2</em> format.  (Both of
354 * these are the default configurations for libSBML.)  Errors about unreadable
355 * files will be logged if a compressed filename is given and libSBML was
356 * <em>not</em> linked with the corresponding required library.
357   <p>
358   * This method is identical to
359   * @link {@link SBMLReader#readSBML(String)} {@link SBMLReader}.readSBML(String)@endlink.
360   <p>
361   * @param filename the name or full pathname of the file to be read.
362   <p>
363   * @return a pointer to the {@link SBMLDocument} object created from the SBML
364   * content in <code>filename</code>.
365   <p>
366   * <p>
367 * @note LibSBML versions 2.x and later versions behave differently in
368 * error handling in several respects.  One difference is how early some
369 * errors are caught and whether libSBML continues processing a file in
370 * the face of some early errors.  In general, libSBML versions after 2.x
371 * stop parsing SBML inputs sooner than libSBML version 2.x in the face
372 * of XML errors, because the errors may invalidate any further SBML
373 * content.  For example, a missing XML declaration at the beginning of
374 * the file was ignored by libSBML 2.x but in version 3.x and later, it
375 * will cause libSBML to stop parsing the rest of the input altogether.
376 * While this behavior may seem more severe and intolerant, it was
377 * necessary in order to provide uniform behavior regardless of which
378 * underlying XML parser (Expat, Xerces, libxml2) is being used by
379 * libSBML.  The XML parsers themselves behave differently in their error
380 * reporting, and sometimes libSBML has to resort to the lowest common
381 * denominator.
382   <p>
383   * @see #readSBMLFromString(String)
384   * @see SBMLError
385   * @see SBMLDocument
386   */ public
387 SBMLDocument readSBMLFromFile(String filename) {
388    long cPtr = libsbmlJNI.SBMLReader_readSBMLFromFile(swigCPtr, this, libsbml.getAbsolutePath(filename));
389    return (cPtr == 0) ? null : new SBMLDocument(cPtr, true);
390  }
391
392  
393/**
394   * <p>
395 * Reads an SBML document from a text string.
396 <p>
397 * This method is flexible with respect to the presence of an XML
398 * declaration at the beginning of the string.  In particular, if the
399 * string in <code>xml</code> does not begin with the XML declaration
400 * <pre class='fragment'>
401&lt;?xml version='1.0' encoding='UTF-8'?&gt;
402</pre>
403 * then this method will automatically prepend the declaration
404 * to <code>xml</code>.
405 <p>
406 * This method will log a fatal error if the content given in the parameter
407 * <code>xml</code> is not in SBML format.  See the method documentation for
408 * {@link SBMLReader#readSBML()}
409 <p>
410 * for an example of code for testing the returned error code.
411   <p>
412   * @param xml a string containing a full SBML model.
413   <p>
414   * @return a pointer to the {@link SBMLDocument} created from the SBML content,
415   * or a null pointer if <code>xml</code> is <code>null.</code>
416   <p>
417   * <p>
418 * @note When using this method to read an {@link SBMLDocument} that uses the SBML
419 * Level&nbsp;3 Hierarchical Model Composition package (comp) the document
420 * location cannot be set automatically. Thus, if the model contains
421 * references to {@link ExternalModelDefinition} objects, it will be necessary to
422 * manually set the document URI location
423 * ({@link SBMLDocument#setLocationURI()}
424 <p>
425 * ) in order to facilitate resolving these models.
426   <p>
427   * @see SBMLReader#readSBML(String)
428   */ public
429 SBMLDocument readSBMLFromString(String xml) {
430    long cPtr = libsbmlJNI.SBMLReader_readSBMLFromString(swigCPtr, this, xml);
431    return (cPtr == 0) ? null : new SBMLDocument(cPtr, true);
432  }
433
434  
435/**
436   * Static method; returns <code>true</code> if this copy of libSBML supports
437   * <i>gzip</I> and <i>zip</i> format compression.
438   <p>
439   * @return <code>true</code> if libSBML has been linked with the <i>zlib</i>
440   * library, <code>false</code> otherwise.
441   <p>
442   * 
443   <p>
444   * @see SBMLReader#hasBzip2()
445   */ public
446 static boolean hasZlib() {
447    return libsbmlJNI.SBMLReader_hasZlib();
448  }
449
450  
451/**
452   * Static method; returns <code>true</code> if this copy of libSBML supports
453   * <i>bzip2</i> format compression.
454   <p>
455   * @return <code>true</code> if libSBML is linked with the <i>bzip2</i>
456   * libraries, <code>false</code> otherwise.
457   <p>
458   * 
459   <p>
460   * @see SBMLReader#hasZlib()
461   */ public
462 static boolean hasBzip2() {
463    return libsbmlJNI.SBMLReader_hasBzip2();
464  }
465
466}