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