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 writing SBML to 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 SBMLWriter} class is the converse of {@link SBMLReader}, and provides the 024 * main interface for serializing SBML models into XML and writing the 025 * result to files and text strings. The methods for writing SBML all take 026 * an {@link SBMLDocument} object and a destination. They return a boolean or 027 * integer value to indicate success or failure. 028 * <p> 029 * <h2>Support for writing compressed files</h2> 030 * <p> 031 * LibSBML provides support for writing (as well as reading) compressed 032 * SBML files. The process is transparent to the calling 033 * application—the application does not need to do anything 034 * deliberate to invoke the functionality. If a given SBML filename ends 035 * with an extension for the <em>gzip</em>, <em>zip</em> or <em>bzip2</em> compression 036 * formats (respectively, <code>".gz"</code>, 037 * <code>".zip"</code>, or <code>".bz2"</code>), 038 * then the methods 039 * {@link SBMLWriter#writeSBML(SBMLDocument d, String filename)} 040 * and {@link SBMLReader#readSBML(String filename)} 041 * will automatically compress and decompress the file while writing and 042 * reading it. If the filename has no such extension, it 043 * will be written and read uncompressed as normal. 044 * <p> 045 * The compression feature requires that the <em>zlib</em> (for <em>gzip</em> and 046 * <em>zip</em> formats) and/or <em>bzip2</em> (for <em>bzip2</em> format) be available on the 047 * system running libSBML, and that libSBML was configured with their 048 * support compiled-in. Please see the libSBML <a href='../../../{@link libsbml}-installation.html'>installation instructions</a> for 049 * more information about this. The methods 050 * {@link SBMLWriter#hasZlib()} and 051 * {@link SBMLWriter#hasBzip2()} 052 * can be used by an application to query at run-time whether support 053 * for the compression libraries is available in the present copy of 054 * libSBML. 055 * <p> 056 * Support for compression is not mandated by the SBML standard, but 057 * applications may find it helpful, particularly when large SBML models 058 * are being communicated across data links of limited bandwidth. 059 */ 060 061public class SBMLWriter { 062 private long swigCPtr; 063 protected boolean swigCMemOwn; 064 065 protected SBMLWriter(long cPtr, boolean cMemoryOwn) 066 { 067 swigCMemOwn = cMemoryOwn; 068 swigCPtr = cPtr; 069 } 070 071 protected static long getCPtr(SBMLWriter obj) 072 { 073 return (obj == null) ? 0 : obj.swigCPtr; 074 } 075 076 protected static long getCPtrAndDisown (SBMLWriter obj) 077 { 078 long ptr = 0; 079 080 if (obj != null) 081 { 082 ptr = obj.swigCPtr; 083 obj.swigCMemOwn = false; 084 } 085 086 return ptr; 087 } 088 089 protected void finalize() { 090 delete(); 091 } 092 093 public synchronized void delete() { 094 if (swigCPtr != 0) { 095 if (swigCMemOwn) { 096 swigCMemOwn = false; 097 libsbmlJNI.delete_SBMLWriter(swigCPtr); 098 } 099 swigCPtr = 0; 100 } 101 } 102 103 /** 104 * Equality comparison method for SBMLWriter. 105 * <p> 106 * Because the Java methods for libSBML are actually wrappers around code 107 * implemented in C++ and C, certain operations will not behave as 108 * expected. Equality comparison is one such case. An instance of a 109 * libSBML object class is actually a <em>proxy object</em> 110 * wrapping the real underlying C/C++ object. The normal <code>==</code> 111 * equality operator in Java will <em>only compare the Java proxy objects</em>, 112 * not the underlying native object. The result is almost never what you 113 * want in practical situations. Unfortunately, Java does not provide a 114 * way to override <code>==</code>. 115 * <p> 116 * The alternative that must be followed is to use the 117 * <code>equals()</code> method. The <code>equals</code> method on this 118 * class overrides the default java.lang.Object one, and performs an 119 * intelligent comparison of instances of objects of this class. The 120 * result is an assessment of whether two libSBML Java objects are truly 121 * the same underlying native-code objects. 122 * <p> 123 * The use of this method in practice is the same as the use of any other 124 * Java <code>equals</code> method. For example, 125 * <em>a</em><code>.equals(</code><em>b</em><code>)</code> returns 126 * <code>true</code> if <em>a</em> and <em>b</em> are references to the 127 * same underlying object. 128 * 129 * @param sb a reference to an object to which the current object 130 * instance will be compared 131 * 132 * @return <code>true</code> if <code>sb</code> refers to the same underlying 133 * native object as this one, <code>false</code> otherwise 134 */ 135 public boolean equals(Object sb) 136 { 137 if ( this == sb ) 138 { 139 return true; 140 } 141 return swigCPtr == getCPtr((SBMLWriter)(sb)); 142 } 143 144 /** 145 * Returns a hashcode for this SBMLWriter object. 146 * 147 * @return a hash code usable by Java methods that need them. 148 */ 149 public int hashCode() 150 { 151 return (int)(swigCPtr^(swigCPtr>>>32)); 152 } 153 154 155/** 156 * Creates a new {@link SBMLWriter}. 157 * <p> 158 * The libSBML {@link SBMLWriter} objects offer methods for writing SBML in 159 * XML form to files and text strings. 160 */ public 161 SBMLWriter() { 162 this(libsbmlJNI.new_SBMLWriter(), true); 163 } 164 165 166/** 167 * Sets the name of this program, i.e., the program that is about to 168 * write out the {@link SBMLDocument}. 169 * <p> 170 * If the program name and version are set (see 171 * {@link SBMLWriter#setProgramVersion(String version)}), the 172 * following XML comment, intended for human consumption, will be written 173 * at the beginning of the XML document: 174 * <div class='fragment'><pre> 175 <!-- Created by <program name> version <program version> 176 on yyyy-MM-dd HH:mm with libSBML version <{@link libsbml} version>. --> 177 </pre></div> 178 * <p> 179 * If the program name and version are not set at some point before 180 * calling the writeSBML() methods, no such comment is written out. 181 * <p> 182 * @param name the name of this program (where 'this program' refers to 183 * program in which libSBML is embedded, not libSBML itself!) 184 * <p> 185 * @return integer value indicating success/failure of the 186 * function. The possible values 187 * returned by this function are: 188 * <ul> 189 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS } 190 * </ul> 191 * <p> 192 * @see #setProgramVersion(String version) 193 */ public 194 int setProgramName(String name) { 195 return libsbmlJNI.SBMLWriter_setProgramName(swigCPtr, this, name); 196 } 197 198 199/** 200 * Sets the version of this program, i.e., the program that is about to 201 * write out the {@link SBMLDocument}. 202 * <p> 203 * If the program version and name are set (see 204 * {@link SBMLWriter#setProgramName(String name)}), the 205 * following XML comment, intended for human consumption, will be written 206 * at the beginning of the document: 207 * <div class='fragment'><pre> 208 <!-- Created by <program name> version <program version> 209 on yyyy-MM-dd HH:mm with libSBML version <{@link libsbml} version>. --> 210 </pre></div> 211 * <p> 212 * If the program version and name are not set at some point before 213 * calling the writeSBML() methods, no such comment is written out. 214 * <p> 215 * @param version the version of this program (where 'this program' 216 * refers to program in which libSBML is embedded, not libSBML itself!) 217 * <p> 218 * @return integer value indicating success/failure of the 219 * function. The possible values 220 * returned by this function are: 221 * <ul> 222 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS } 223 * </ul> 224 * <p> 225 * @see #setProgramName(String name) 226 */ public 227 int setProgramVersion(String version) { 228 return libsbmlJNI.SBMLWriter_setProgramVersion(swigCPtr, this, version); 229 } 230 231 232/** 233 * Writes the given SBML document to filename. 234 * <p> 235 * If the given filename ends with the suffix <code>".gz"</code> 236(for example, <code>"myfile.xml.gz"</code>), libSBML assumes the 237caller wants the file to be written compressed in <em>gzip</em> format. 238Similarly, if the given filename ends with <code>".zip"</code> or 239<code>".bz2"</code>, libSBML assumes the caller wants the file to 240be compressed in <em>zip</em> or <em>bzip2</em> format (respectively). 241Files whose names lack these suffixes will be written uncompressed. 242<em>Special considerations for the zip format</em>: If the given filename 243ends with <code>".zip"</code>, the file placed in the zip archive 244will have the suffix <code>".xml"</code> or 245<code>".sbml"</code>. For example, the file in the zip archive 246will be named <code>"test.xml"</code> if the given filename is 247<code>"test.xml.zip"</code> or <code>"test.zip"</code>. 248Similarly, the filename in the archive will be 249<code>"test.sbml"</code> if the given filename is 250<code>"test.sbml.zip"</code>. 251 252 * <p> 253 * @param d the SBML document to be written 254 * <p> 255 * @param filename the name or full pathname of the file where the SBML 256 * is to be written. 257 * <p> 258 * @return <code>true</code> on success and <code>false</code> if the filename could not be 259 * opened for writing. 260 * <p> 261 * @note To write a gzip/zip file, libSBML needs to be configured and linked with 262the <a target='_blank' href='http://www.zlib.net/'>zlib</a> library at 263compile time. It also needs to be linked with the <a target='_blank' 264href=''>bzip2</a> library to write files in <em>bzip2</em> format. (Both 265of these are the default configurations for libSBML.) Errors about 266unreadable files will be logged and this method will return 267<code>false</code> if a compressed filename is given and libSBML was 268<em>not</em> linked with the corresponding required library. 269 270 * <p> 271 * @see #setProgramVersion(String version) 272 * @see #setProgramName(String name) 273 */ public 274 boolean writeSBML(SBMLDocument d, String filename) { 275 return libsbmlJNI.SBMLWriter_writeSBML__SWIG_0(swigCPtr, this, SBMLDocument.getCPtr(d), d, libsbml.getAbsolutePath(filename)); 276 } 277 278 279/** 280 * Writes the given SBML document to the output stream. 281 * <p> 282 * @param d the SBML document to be written 283 * <p> 284 * @param stream the stream object where the SBML is to be written. 285 * <p> 286 * @return <code>true</code> on success and <code>false</code> if one of the underlying 287 * parser components fail (rare). 288 * <p> 289 * @see #setProgramVersion(String version) 290 * @see #setProgramName(String name) 291 */ public 292 boolean writeSBML(SBMLDocument d, OStream stream) { 293 return libsbmlJNI.SBMLWriter_writeSBML__SWIG_1(swigCPtr, this, SBMLDocument.getCPtr(d), d, SWIGTYPE_p_std__ostream.getCPtr(stream.get_ostream()), stream); 294 } 295 296 297/** 298 * Writes the given SBML document to an in-memory string and returns a 299 * pointer to it. 300 * <p> 301 * The string is owned by the caller and should be freed (with <code>free</code>()) 302 * when no longer needed. 303 * <p> 304 * @param d the SBML document to be written 305 * <p> 306 * @return the string on success and <code>0</code> if one of the underlying parser 307 * components fail. 308 * <p> 309 * @see #setProgramVersion(String version) 310 * @see #setProgramName(String name) 311 * @internal 312 */ public 313 String writeToString(SBMLDocument d) { 314 return libsbmlJNI.SBMLWriter_writeToString(swigCPtr, this, SBMLDocument.getCPtr(d), d); 315 } 316 317 318/** 319 * Writes the given SBML document to filename. 320 * <p> 321 * If the given filename ends with the suffix <code>".gz"</code> 322(for example, <code>"myfile.xml.gz"</code>), libSBML assumes the 323caller wants the file to be written compressed in <em>gzip</em> format. 324Similarly, if the given filename ends with <code>".zip"</code> or 325<code>".bz2"</code>, libSBML assumes the caller wants the file to 326be compressed in <em>zip</em> or <em>bzip2</em> format (respectively). 327Files whose names lack these suffixes will be written uncompressed. 328<em>Special considerations for the zip format</em>: If the given filename 329ends with <code>".zip"</code>, the file placed in the zip archive 330will have the suffix <code>".xml"</code> or 331<code>".sbml"</code>. For example, the file in the zip archive 332will be named <code>"test.xml"</code> if the given filename is 333<code>"test.xml.zip"</code> or <code>"test.zip"</code>. 334Similarly, the filename in the archive will be 335<code>"test.sbml"</code> if the given filename is 336<code>"test.sbml.zip"</code>. 337 338 * <p> 339 * @param d the SBML document to be written 340 * <p> 341 * @param filename the name or full pathname of the file where the SBML 342 * is to be written. 343 * <p> 344 * @return <code>true</code> on success and <code>false</code> if the filename could not be 345 * opened for writing. 346 * <p> 347 * @note To write a gzip/zip file, libSBML needs to be configured and linked with 348the <a target='_blank' href='http://www.zlib.net/'>zlib</a> library at 349compile time. It also needs to be linked with the <a target='_blank' 350href=''>bzip2</a> library to write files in <em>bzip2</em> format. (Both 351of these are the default configurations for libSBML.) Errors about 352unreadable files will be logged and this method will return 353<code>false</code> if a compressed filename is given and libSBML was 354<em>not</em> linked with the corresponding required library. 355 356 * <p> 357 * @see #setProgramVersion(String version) 358 * @see #setProgramName(String name) 359 */ public 360 boolean writeSBMLToFile(SBMLDocument d, String filename) { 361 return libsbmlJNI.SBMLWriter_writeSBMLToFile(swigCPtr, this, SBMLDocument.getCPtr(d), d, libsbml.getAbsolutePath(filename)); 362 } 363 364 365/** 366 * Writes the given SBML document to an in-memory string and returns a 367 * pointer to it. 368 * <p> 369 * The string is owned by the caller and should be freed (with <code>free</code>()) 370 * when no longer needed. 371 * <p> 372 * @param d the SBML document to be written 373 * <p> 374 * @return the string on success and <code>0</code> if one of the underlying parser 375 * components fail. 376 * <p> 377 * @see #setProgramVersion(String version) 378 * @see #setProgramName(String name) 379 */ public 380 String writeSBMLToString(SBMLDocument d) { 381 return libsbmlJNI.SBMLWriter_writeSBMLToString(swigCPtr, this, SBMLDocument.getCPtr(d), d); 382 } 383 384 385/** 386 * Predicate returning <code>true</code> if this copy of libSBML has been linked 387 * with the <em>zlib</em> library. 388 * <p> 389 * LibSBML supports reading and writing files compressed with either 390 * bzip2 or zip/gzip compression. The facility depends on libSBML having 391 * been compiled with the necessary support libraries. This method 392 * allows a calling program to inquire whether that is the case for the 393 * copy of libSBML it is using. 394 * <p> 395 * @note Because this is a <em>static</em> method, the 396 * non-C++ language interfaces for libSBML will contain two variants. One 397 * will be a static method on the class (i.e., {@link SBMLWriter}), and the other 398 * will be a standalone top-level function with the name 399 * SBMLWriter_hasZlib(). They are functionally identical. 400 * <p> 401 * @return <code>true</code> if libSBML is linked with zlib, <code>false</code> otherwise. 402 * <p> 403 * @see SBMLWriter#hasBzip2() 404 */ public 405 static boolean hasZlib() { 406 return libsbmlJNI.SBMLWriter_hasZlib(); 407 } 408 409 410/** 411 * Predicate returning <code>true</code> if this copy of libSBML has been linked 412 * with the <em>bzip2</em> library. 413 * <p> 414 * LibSBML supports reading and writing files compressed with either 415 * bzip2 or zip/gzip compression. The facility depends on libSBML having 416 * been compiled with the necessary support libraries. This method 417 * allows a calling program to inquire whether that is the case for the 418 * copy of libSBML it is using. 419 * <p> 420 * @note Because this is a <em>static</em> method, the 421 * non-C++ language interfaces for libSBML will contain two variants. One 422 * will be a static method on the class (i.e., {@link SBMLWriter}), and the other 423 * will be a standalone top-level function with the name 424 * SBMLWriter_hasZlib(). They are functionally identical. 425 * <p> 426 * @return <code>true</code> if libSBML is linked with bzip2, <code>false</code> otherwise. 427 * <p> 428 * @see SBMLWriter#hasZlib() 429 */ public 430 static boolean hasBzip2() { 431 return libsbmlJNI.SBMLWriter_hasBzip2(); 432 } 433 434}