001/* ---------------------------------------------------------------------------- 002 * This file was automatically generated by SWIG (http://www.swig.org). 003 * Version 3.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 * 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} object representing the results. In the case of failures 025 * (such as if the SBML contains errors or a file cannot be read), the errors 026 * will be recorded with the {@link SBMLErrorLog} object kept in the {@link SBMLDocument} 027 * returned by {@link SBMLReader}. Consequently, immediately after calling a method 028 * on {@link SBMLReader}, callers should always check for errors and warnings using 029 * the methods for this purpose provided by {@link SBMLDocument}. 030 <p> 031 * For convenience as well as easy access from other languages besides C++, 032 * this file also defines two global functions, 033 * @sbmlglobalfunction{readSBML, String}global and 034 * @sbmlglobalfunction{readSBMLFromString, String}global. 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 valid 180 * SBML, one or more errors will be logged with the {@link SBMLDocument} object 181 * returned by this method. Callers can use the methods on {@link SBMLDocument} such 182 * as 183 * , 184 * {@link SBMLDocument#getNumErrors()} 185 * and 186 <p> 187 * {@link SBMLDocument#getError(long)} 188 <p> 189 * to get the errors. The object returned by 190 <p> 191 * {@link SBMLDocument#getError(long)} 192 <p> 193 * is an {@link SBMLError} object, and it has methods to get the error code, 194 * category, and severity level of the problem, as well as a textual 195 * description of the problem. The possible severity levels range from 196 * informational messages to fatal errors; see the documentation for 197 * {@link SBMLError} 198 * for more information. 199 <p> 200 * If the file <code>filename</code> could not be read, the file-reading error will 201 * appear first. The error code can provide a clue about what 202 * happened. For example, a file might be unreadable (either because it does 203 * not actually exist or because the user does not have the necessary access 204 * privileges to read it) or some sort of file operation error may have been 205 * reported by the underlying operating system. Callers can check for these 206 * situations using a program fragment such as the following: 207 <p> 208<pre class='fragment'> 209{@link SBMLReader} reader = new {@link SBMLReader}(); 210{@link SBMLDocument} doc = reader.readSBMLFromFile(filename); 211 212if (doc.getNumErrors() > 0) 213{ 214 if (doc.getError(0).getErrorId() == libsbmlConstants.XMLFileUnreadable) 215 { 216 // Handle case of unreadable file here. 217 } 218 else if (doc.getError(0).getErrorId() == libsbmlConstants.XMLFileOperationError) 219 { 220 // Handle case of other file operation error here. 221 } 222 else 223 { 224 // Handle other error cases. 225 } 226} 227</pre> 228<p> 229 * <p> 230 * If the given filename ends with the suffix <code>'.gz'</code> (for example, 231 * <code>'myfile.xml.gz'</code>), the file is assumed to be compressed in <em>gzip</em> 232 * format and will be automatically decompressed upon reading. 233 * Similarly, if the given filename ends with <code>'.zip'</code> or <code>'.bz2'</code>, the 234 * file is assumed to be compressed in <em>zip</em> or <em>bzip2</em> format 235 * (respectively). Files whose names lack these suffixes will be read 236 * uncompressed. Note that if the file is in <em>zip</em> format but the 237 * archive contains more than one file, only the first file in the 238 * archive will be read and the rest ignored. 239 <p> 240 * <p> 241 * To read a gzip/zip file, libSBML needs to be configured and linked with the 242 * <a target='_blank' href='http://www.zlib.net/'>zlib</a> library at compile 243 * time. It also needs to be linked with the <a target='_blank' 244 * href=''>bzip2</a> library to read files in <em>bzip2</em> format. (Both of 245 * these are the default configurations for libSBML.) Errors about unreadable 246 * files will be logged if a compressed filename is given and libSBML was 247 * <em>not</em> linked with the corresponding required library. 248 <p> 249 * This method is identical to 250 * @link {@link SBMLReader#readSBMLFromFile(String)} {@link SBMLReader}.readSBMLFromFile(String)@endlink. 251 <p> 252 * @param filename the name or full pathname of the file to be read. 253 <p> 254 * @return a pointer to the {@link SBMLDocument} object created from the SBML 255 * content in <code>filename</code>. 256 <p> 257 * <p> 258 * @note LibSBML versions 2.x and later versions behave differently in 259 * error handling in several respects. One difference is how early some 260 * errors are caught and whether libSBML continues processing a file in 261 * the face of some early errors. In general, libSBML versions after 2.x 262 * stop parsing SBML inputs sooner than libSBML version 2.x in the face 263 * of XML errors, because the errors may invalidate any further SBML 264 * content. For example, a missing XML declaration at the beginning of 265 * the file was ignored by libSBML 2.x but in version 3.x and later, it 266 * will cause libSBML to stop parsing the rest of the input altogether. 267 * While this behavior may seem more severe and intolerant, it was 268 * necessary in order to provide uniform behavior regardless of which 269 * underlying XML parser (Expat, Xerces, libxml2) is being used by 270 * libSBML. The XML parsers themselves behave differently in their error 271 * reporting, and sometimes libSBML has to resort to the lowest common 272 * denominator. 273 <p> 274 * @see #readSBMLFromString(String) 275 * @see SBMLError 276 * @see SBMLDocument 277 */ public 278 SBMLDocument readSBML(String filename) { 279 long cPtr = libsbmlJNI.SBMLReader_readSBML(swigCPtr, this, libsbml.getAbsolutePath(filename)); 280 return (cPtr == 0) ? null : new SBMLDocument(cPtr, true); 281 } 282 283 284/** 285 * <p> 286 * Reads an SBML document from the given file. 287 <p> 288 * If the file named <code>filename</code> does not exist or its content is not valid 289 * SBML, one or more errors will be logged with the {@link SBMLDocument} object 290 * returned by this method. Callers can use the methods on {@link SBMLDocument} such 291 * as 292 * , 293 * {@link SBMLDocument#getNumErrors()} 294 * and 295 <p> 296 * {@link SBMLDocument#getError(long)} 297 <p> 298 * to get the errors. The object returned by 299 <p> 300 * {@link SBMLDocument#getError(long)} 301 <p> 302 * is an {@link SBMLError} object, and it has methods to get the error code, 303 * category, and severity level of the problem, as well as a textual 304 * description of the problem. The possible severity levels range from 305 * informational messages to fatal errors; see the documentation for 306 * {@link SBMLError} 307 * for more information. 308 <p> 309 * If the file <code>filename</code> could not be read, the file-reading error will 310 * appear first. The error code can provide a clue about what 311 * happened. For example, a file might be unreadable (either because it does 312 * not actually exist or because the user does not have the necessary access 313 * privileges to read it) or some sort of file operation error may have been 314 * reported by the underlying operating system. Callers can check for these 315 * situations using a program fragment such as the following: 316 <p> 317<pre class='fragment'> 318{@link SBMLReader} reader = new {@link SBMLReader}(); 319{@link SBMLDocument} doc = reader.readSBMLFromFile(filename); 320 321if (doc.getNumErrors() > 0) 322{ 323 if (doc.getError(0).getErrorId() == libsbmlConstants.XMLFileUnreadable) 324 { 325 // Handle case of unreadable file here. 326 } 327 else if (doc.getError(0).getErrorId() == libsbmlConstants.XMLFileOperationError) 328 { 329 // Handle case of other file operation error here. 330 } 331 else 332 { 333 // Handle other error cases. 334 } 335} 336</pre> 337<p> 338 * <p> 339 * If the given filename ends with the suffix <code>'.gz'</code> (for example, 340 * <code>'myfile.xml.gz'</code>), the file is assumed to be compressed in <em>gzip</em> 341 * format and will be automatically decompressed upon reading. 342 * Similarly, if the given filename ends with <code>'.zip'</code> or <code>'.bz2'</code>, the 343 * file is assumed to be compressed in <em>zip</em> or <em>bzip2</em> format 344 * (respectively). Files whose names lack these suffixes will be read 345 * uncompressed. Note that if the file is in <em>zip</em> format but the 346 * archive contains more than one file, only the first file in the 347 * archive will be read and the rest ignored. 348 <p> 349 * <p> 350 * To read a gzip/zip file, libSBML needs to be configured and linked with the 351 * <a target='_blank' href='http://www.zlib.net/'>zlib</a> library at compile 352 * time. It also needs to be linked with the <a target='_blank' 353 * href=''>bzip2</a> library to read files in <em>bzip2</em> format. (Both of 354 * these are the default configurations for libSBML.) Errors about unreadable 355 * files will be logged if a compressed filename is given and libSBML was 356 * <em>not</em> linked with the corresponding required library. 357 <p> 358 * This method is identical to 359 * @link {@link SBMLReader#readSBML(String)} {@link SBMLReader}.readSBML(String)@endlink. 360 <p> 361 * @param filename the name or full pathname of the file to be read. 362 <p> 363 * @return a pointer to the {@link SBMLDocument} object created from the SBML 364 * content in <code>filename</code>. 365 <p> 366 * <p> 367 * @note LibSBML versions 2.x and later versions behave differently in 368 * error handling in several respects. One difference is how early some 369 * errors are caught and whether libSBML continues processing a file in 370 * the face of some early errors. In general, libSBML versions after 2.x 371 * stop parsing SBML inputs sooner than libSBML version 2.x in the face 372 * of XML errors, because the errors may invalidate any further SBML 373 * content. For example, a missing XML declaration at the beginning of 374 * the file was ignored by libSBML 2.x but in version 3.x and later, it 375 * will cause libSBML to stop parsing the rest of the input altogether. 376 * While this behavior may seem more severe and intolerant, it was 377 * necessary in order to provide uniform behavior regardless of which 378 * underlying XML parser (Expat, Xerces, libxml2) is being used by 379 * libSBML. The XML parsers themselves behave differently in their error 380 * reporting, and sometimes libSBML has to resort to the lowest common 381 * denominator. 382 <p> 383 * @see #readSBMLFromString(String) 384 * @see SBMLError 385 * @see SBMLDocument 386 */ public 387 SBMLDocument readSBMLFromFile(String filename) { 388 long cPtr = libsbmlJNI.SBMLReader_readSBMLFromFile(swigCPtr, this, libsbml.getAbsolutePath(filename)); 389 return (cPtr == 0) ? null : new SBMLDocument(cPtr, true); 390 } 391 392 393/** 394 * <p> 395 * Reads an SBML document from a text string. 396 <p> 397 * This method is flexible with respect to the presence of an XML 398 * declaration at the beginning of the string. In particular, if the 399 * string in <code>xml</code> does not begin with the XML declaration 400 * <pre class='fragment'> 401<?xml version='1.0' encoding='UTF-8'?> 402</pre> 403 * then this method will automatically prepend the declaration 404 * to <code>xml</code>. 405 <p> 406 * This method will log a fatal error if the content given in the parameter 407 * <code>xml</code> is not in SBML format. See the method documentation for 408 * {@link SBMLReader#readSBML()} 409 <p> 410 * for an example of code for testing the returned error code. 411 <p> 412 * @param xml a string containing a full SBML model. 413 <p> 414 * @return a pointer to the {@link SBMLDocument} created from the SBML content, 415 * or a null pointer if <code>xml</code> is <code>null.</code> 416 <p> 417 * <p> 418 * @note When using this method to read an {@link SBMLDocument} that uses the SBML 419 * Level 3 Hierarchical Model Composition package (comp) the document 420 * location cannot be set automatically. Thus, if the model contains 421 * references to {@link ExternalModelDefinition} objects, it will be necessary to 422 * manually set the document URI location 423 * ({@link SBMLDocument#setLocationURI()} 424 <p> 425 * ) in order to facilitate resolving these models. 426 <p> 427 * @see SBMLReader#readSBML(String) 428 */ public 429 SBMLDocument readSBMLFromString(String xml) { 430 long cPtr = libsbmlJNI.SBMLReader_readSBMLFromString(swigCPtr, this, xml); 431 return (cPtr == 0) ? null : new SBMLDocument(cPtr, true); 432 } 433 434 435/** 436 * Static method; returns <code>true</code> if this copy of libSBML supports 437 * <i>gzip</I> and <i>zip</i> format compression. 438 <p> 439 * @return <code>true</code> if libSBML has been linked with the <i>zlib</i> 440 * library, <code>false</code> otherwise. 441 <p> 442 * 443 <p> 444 * @see SBMLReader#hasBzip2() 445 */ public 446 static boolean hasZlib() { 447 return libsbmlJNI.SBMLReader_hasZlib(); 448 } 449 450 451/** 452 * Static method; returns <code>true</code> if this copy of libSBML supports 453 * <i>bzip2</i> format compression. 454 <p> 455 * @return <code>true</code> if libSBML is linked with the <i>bzip2</i> 456 * libraries, <code>false</code> otherwise. 457 <p> 458 * 459 <p> 460 * @see SBMLReader#hasZlib() 461 */ public 462 static boolean hasBzip2() { 463 return libsbmlJNI.SBMLReader_hasBzip2(); 464 } 465 466}