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