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