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