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