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&mdash;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>&quot;.gz&quot;</code>,
037 * <code>&quot;.zip&quot;</code>, or <code>&quot;.bz2&quot;</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 &lt;!-- Created by &lt;program name&gt; version &lt;program version&gt;
176 on yyyy-MM-dd HH:mm with libSBML version &lt;{@link libsbml} version&gt;. --&gt;
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 &lt;!-- Created by &lt;program name&gt; version &lt;program version&gt;
209 on yyyy-MM-dd HH:mm with libSBML version &lt;{@link libsbml} version&gt;. --&gt;
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>&quot;.gz&quot;</code>
236(for example, <code>&quot;myfile.xml.gz&quot;</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>&quot;.zip&quot;</code> or
239<code>&quot;.bz2&quot;</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>&quot;.zip&quot;</code>, the file placed in the zip archive
244will have the suffix <code>&quot;.xml&quot;</code> or
245<code>&quot;.sbml&quot;</code>.  For example, the file in the zip archive
246will be named <code>&quot;test.xml&quot;</code> if the given filename is
247<code>&quot;test.xml.zip&quot;</code> or <code>&quot;test.zip&quot;</code>.
248Similarly, the filename in the archive will be
249<code>&quot;test.sbml&quot;</code> if the given filename is
250<code>&quot;test.sbml.zip&quot;</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>&quot;.gz&quot;</code>
322(for example, <code>&quot;myfile.xml.gz&quot;</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>&quot;.zip&quot;</code> or
325<code>&quot;.bz2&quot;</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>&quot;.zip&quot;</code>, the file placed in the zip archive
330will have the suffix <code>&quot;.xml&quot;</code> or
331<code>&quot;.sbml&quot;</code>.  For example, the file in the zip archive
332will be named <code>&quot;test.xml&quot;</code> if the given filename is
333<code>&quot;test.xml.zip&quot;</code> or <code>&quot;test.zip&quot;</code>.
334Similarly, the filename in the archive will be
335<code>&quot;test.sbml&quot;</code> if the given filename is
336<code>&quot;test.sbml.zip&quot;</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}