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—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() > 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() > 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<?xml version='1.0' encoding='UTF-8'?> 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 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}