001/* ----------------------------------------------------------------------------
002 * This file was automatically generated by SWIG (http://www.swig.org).
003 * Version 3.0.10
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}
025 * object representing the results.  In the case of failures (such as if the
026 * SBML contains errors or a file cannot be read), the errors will be
027 * recorded with the {@link SBMLErrorLog} object kept in the
028 * {@link SBMLDocument}
029 * returned by {@link SBMLReader}.  Consequently, immediately after calling a method
030 * on {@link SBMLReader}, callers should always check for errors and warnings using
031 * the methods for this purpose provided by {@link SBMLDocument}.
032 <p>
033 * For convenience as well as easy access from other languages besides C++,
034 * this file also defines two global functions, <a href='libsbml.html#readSBML(java.lang.String)'><code>libsbml.readSBML(String)</code></a> and <a href='libsbml.html#readSBMLFromString(java.lang.String)'><code>libsbml.readSBMLFromString(String)</code></a>.  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
180 * valid SBML, one or more errors will be logged with the
181 * {@link SBMLDocument}
182 * object returned by this method.  Callers can use the methods on
183 * {@link SBMLDocument} such as
184 * {@link SBMLDocument#getNumErrors()}
185 * and
186 * {@link SBMLDocument#getError(long)}
187 * to get the errors.  The object returned by
188 * {@link SBMLDocument#getError(long)}
189 * is an {@link SBMLError} object, and it has methods to get the error code,
190 * category, and severity level of the problem, as well as a textual
191 * description of the problem.  The possible severity levels range from
192 * informational messages to fatal errors; see the documentation for
193 * {@link SBMLError}
194 * for more information.
195 <p>
196 * If the file <code>filename</code> could not be read, the file-reading error will
197 * appear first.  The error code  can provide a clue about what
198 * happened.  For example, a file might be unreadable (either because it does
199 * not actually exist or because the user does not have the necessary access
200 * privileges to read it) or some sort of file operation error may have been
201 * reported by the underlying operating system.  Callers can check for these
202 * situations using a program fragment such as the following:
203 <p>
204<pre class='fragment'>
205{@link SBMLReader} reader = new {@link SBMLReader}();
206{@link SBMLDocument} doc  = reader.readSBMLFromFile(filename);
207
208if (doc.getNumErrors() &gt; 0)
209{
210    if (doc.getError(0).getErrorId() == libsbmlConstants.XMLFileUnreadable)
211    {
212        // Handle case of unreadable file here.
213    }
214    else if (doc.getError(0).getErrorId() == libsbmlConstants.XMLFileOperationError)
215    {
216        // Handle case of other file operation error here.
217    }
218    else
219    {
220        // Handle other error cases.
221    }
222}
223</pre>
224<p>
225 * <p>
226 * If the given filename ends with the suffix <code>'.gz'</code> (for example, 
227 * <code>'myfile.xml.gz'</code>), the file is assumed to be compressed in <em>gzip</em>
228 * format and will be automatically decompressed upon reading.
229 * Similarly, if the given filename ends with <code>'.zip'</code> or <code>'.bz2'</code>, the
230 * file is assumed to be compressed in <em>zip</em> or <em>bzip2</em> format
231 * (respectively).  Files whose names lack these suffixes will be read
232 * uncompressed.  Note that if the file is in <em>zip</em> format but the
233 * archive contains more than one file, only the first file in the
234 * archive will be read and the rest ignored.
235 <p>
236 * <p>
237 * To read a gzip/zip file, libSBML needs to be configured and linked with the
238 * <a target='_blank' href='http://www.zlib.net/'>zlib</a> library at compile
239 * time.  It also needs to be linked with the <a target='_blank'
240 * href=''>bzip2</a> library to read files in <em>bzip2</em> format.  (Both of
241 * these are the default configurations for libSBML.)  Errors about unreadable
242 * files will be logged if a compressed filename is given and libSBML was
243 * <em>not</em> linked with the corresponding required library.
244   <p>
245   * This method is identical to
246   * @link {@link SBMLReader#readSBMLFromFile(String)} {@link SBMLReader}.readSBMLFromFile(String)@endlink.
247   <p>
248   * @param filename the name or full pathname of the file to be read.
249   <p>
250   * @return a pointer to the {@link SBMLDocument} object created from the SBML
251   * content in <code>filename</code>.
252   <p>
253   * <p>
254 * @note LibSBML versions 2.x and later versions behave differently in
255 * error handling in several respects.  One difference is how early some
256 * errors are caught and whether libSBML continues processing a file in
257 * the face of some early errors.  In general, libSBML versions after 2.x
258 * stop parsing SBML inputs sooner than libSBML version 2.x in the face
259 * of XML errors, because the errors may invalidate any further SBML
260 * content.  For example, a missing XML declaration at the beginning of
261 * the file was ignored by libSBML 2.x but in version 3.x and later, it
262 * will cause libSBML to stop parsing the rest of the input altogether.
263 * While this behavior may seem more severe and intolerant, it was
264 * necessary in order to provide uniform behavior regardless of which
265 * underlying XML parser (Expat, Xerces, libxml2) is being used by
266 * libSBML.  The XML parsers themselves behave differently in their error
267 * reporting, and sometimes libSBML has to resort to the lowest common
268 * denominator.
269   <p>
270   * @see #readSBMLFromString(String)
271   * @see SBMLError
272   * @see SBMLDocument
273   */ public
274 SBMLDocument readSBML(String filename) {
275    long cPtr = libsbmlJNI.SBMLReader_readSBML(swigCPtr, this, libsbml.getAbsolutePath(filename));
276    return (cPtr == 0) ? null : new SBMLDocument(cPtr, true);
277  }
278
279  
280/**
281   * <p>
282 * Reads an SBML document from the given file.
283 <p>
284 * If the file named <code>filename</code> does not exist or its content is not
285 * valid SBML, one or more errors will be logged with the
286 * {@link SBMLDocument}
287 * object returned by this method.  Callers can use the methods on
288 * {@link SBMLDocument} such as
289 * {@link SBMLDocument#getNumErrors()}
290 * and
291 * {@link SBMLDocument#getError(long)}
292 * to get the errors.  The object returned by
293 * {@link SBMLDocument#getError(long)}
294 * is an {@link SBMLError} object, and it has methods to get the error code,
295 * category, and severity level of the problem, as well as a textual
296 * description of the problem.  The possible severity levels range from
297 * informational messages to fatal errors; see the documentation for
298 * {@link SBMLError}
299 * for more information.
300 <p>
301 * If the file <code>filename</code> could not be read, the file-reading error will
302 * appear first.  The error code  can provide a clue about what
303 * happened.  For example, a file might be unreadable (either because it does
304 * not actually exist or because the user does not have the necessary access
305 * privileges to read it) or some sort of file operation error may have been
306 * reported by the underlying operating system.  Callers can check for these
307 * situations using a program fragment such as the following:
308 <p>
309<pre class='fragment'>
310{@link SBMLReader} reader = new {@link SBMLReader}();
311{@link SBMLDocument} doc  = reader.readSBMLFromFile(filename);
312
313if (doc.getNumErrors() &gt; 0)
314{
315    if (doc.getError(0).getErrorId() == libsbmlConstants.XMLFileUnreadable)
316    {
317        // Handle case of unreadable file here.
318    }
319    else if (doc.getError(0).getErrorId() == libsbmlConstants.XMLFileOperationError)
320    {
321        // Handle case of other file operation error here.
322    }
323    else
324    {
325        // Handle other error cases.
326    }
327}
328</pre>
329<p>
330 * <p>
331 * If the given filename ends with the suffix <code>'.gz'</code> (for example, 
332 * <code>'myfile.xml.gz'</code>), the file is assumed to be compressed in <em>gzip</em>
333 * format and will be automatically decompressed upon reading.
334 * Similarly, if the given filename ends with <code>'.zip'</code> or <code>'.bz2'</code>, the
335 * file is assumed to be compressed in <em>zip</em> or <em>bzip2</em> format
336 * (respectively).  Files whose names lack these suffixes will be read
337 * uncompressed.  Note that if the file is in <em>zip</em> format but the
338 * archive contains more than one file, only the first file in the
339 * archive will be read and the rest ignored.
340 <p>
341 * <p>
342 * To read a gzip/zip file, libSBML needs to be configured and linked with the
343 * <a target='_blank' href='http://www.zlib.net/'>zlib</a> library at compile
344 * time.  It also needs to be linked with the <a target='_blank'
345 * href=''>bzip2</a> library to read files in <em>bzip2</em> format.  (Both of
346 * these are the default configurations for libSBML.)  Errors about unreadable
347 * files will be logged if a compressed filename is given and libSBML was
348 * <em>not</em> linked with the corresponding required library.
349   <p>
350   * This method is identical to
351   * @link {@link SBMLReader#readSBML(String)} {@link SBMLReader}.readSBML(String)@endlink.
352   <p>
353   * @param filename the name or full pathname of the file to be read.
354   <p>
355   * @return a pointer to the {@link SBMLDocument} object created from the SBML
356   * content in <code>filename</code>.
357   <p>
358   * <p>
359 * @note LibSBML versions 2.x and later versions behave differently in
360 * error handling in several respects.  One difference is how early some
361 * errors are caught and whether libSBML continues processing a file in
362 * the face of some early errors.  In general, libSBML versions after 2.x
363 * stop parsing SBML inputs sooner than libSBML version 2.x in the face
364 * of XML errors, because the errors may invalidate any further SBML
365 * content.  For example, a missing XML declaration at the beginning of
366 * the file was ignored by libSBML 2.x but in version 3.x and later, it
367 * will cause libSBML to stop parsing the rest of the input altogether.
368 * While this behavior may seem more severe and intolerant, it was
369 * necessary in order to provide uniform behavior regardless of which
370 * underlying XML parser (Expat, Xerces, libxml2) is being used by
371 * libSBML.  The XML parsers themselves behave differently in their error
372 * reporting, and sometimes libSBML has to resort to the lowest common
373 * denominator.
374   <p>
375   * @see #readSBMLFromString(String)
376   * @see SBMLError
377   * @see SBMLDocument
378   */ public
379 SBMLDocument readSBMLFromFile(String filename) {
380    long cPtr = libsbmlJNI.SBMLReader_readSBMLFromFile(swigCPtr, this, libsbml.getAbsolutePath(filename));
381    return (cPtr == 0) ? null : new SBMLDocument(cPtr, true);
382  }
383
384  
385/**
386   * <p>
387 * Reads an SBML document from a text string.
388 <p>
389 * This method is flexible with respect to the presence of an XML
390 * declaration at the beginning of the string.  In particular, if the
391 * string in <code>xml</code> does not begin with the XML declaration
392 * <pre class='fragment'>
393&lt;?xml version='1.0' encoding='UTF-8'?&gt;
394</pre>
395 * then this method will automatically prepend the declaration
396 * to <code>xml</code>.
397 <p>
398 * This method will log a fatal error if the content given in the parameter
399 * <code>xml</code> is not in SBML format.  See the method documentation for
400 * {@link SBMLReader#readSBML(String)} for an example of code for
401 * testing the returned error code.
402   <p>
403   * @param xml a string containing a full SBML model
404   <p>
405   * @return a pointer to the {@link SBMLDocument} created from the SBML content,
406   * or a null pointer if <code>xml</code> is null.
407   <p>
408   * <p>
409 * @note When using this method to read an {@link SBMLDocument} that uses the SBML
410 * Level&nbsp;3 Hierarchical Model Composition package (comp) the document
411 * location cannot be set automatically. Thus, if the model contains
412 * references to {@link ExternalModelDefinition} objects, it will be necessary to
413 * manually set the document URI location
414 * ({@link SBMLDocument#setLocationURI(String)} in order to facilitate
415 * resolving these models.
416   <p>
417   * @see SBMLReader#readSBML(String)
418   */ public
419 SBMLDocument readSBMLFromString(String xml) {
420    long cPtr = libsbmlJNI.SBMLReader_readSBMLFromString(swigCPtr, this, xml);
421    return (cPtr == 0) ? null : new SBMLDocument(cPtr, true);
422  }
423
424  
425/**
426   * Static method; returns <code>true</code> if this copy of libSBML supports
427   * <i>gzip</I> and <i>zip</i> format compression.
428   <p>
429   * @return <code>true</code> if libSBML has been linked with the <i>zlib</i>
430   * library, <code>false</code> otherwise.
431   <p>
432   * 
433   <p>
434   * @see SBMLReader#hasBzip2()
435   */ public
436 static boolean hasZlib() {
437    return libsbmlJNI.SBMLReader_hasZlib();
438  }
439
440  
441/**
442   * Static method; returns <code>true</code> if this copy of libSBML supports
443   * <i>bzip2</i> format compression.
444   <p>
445   * @return <code>true</code> if libSBML is linked with the <i>bzip2</i>
446   * libraries, <code>false</code> otherwise.
447   <p>
448   * 
449   <p>
450   * @see SBMLReader#hasZlib()
451   */ public
452 static boolean hasBzip2() {
453    return libsbmlJNI.SBMLReader_hasBzip2();
454  }
455
456}