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&mdash;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>&quot;.gz&quot;</code>,
036 * <code>&quot;.zip&quot;</code>, or <code>&quot;.bz2&quot;</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 &lt;!-- Created by &lt;program name&gt; version &lt;program version&gt;
175 on yyyy-MM-dd HH:mm with libSBML version &lt;libsbml version&gt;. --&gt;
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 &lt;!-- Created by &lt;program name&gt; version &lt;program version&gt;
208 on yyyy-MM-dd HH:mm with libSBML version &lt;libsbml version&gt;. --&gt;
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>&quot;.gz&quot;</code>
235(for example, <code>&quot;myfile.xml.gz&quot;</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>&quot;.zip&quot;</code> or
238<code>&quot;.bz2&quot;</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>&quot;.zip&quot;</code>, the file placed in the zip archive
243will have the suffix <code>&quot;.xml&quot;</code> or
244<code>&quot;.sbml&quot;</code>.  For example, the file in the zip archive
245will be named <code>&quot;test.xml&quot;</code> if the given filename is
246<code>&quot;test.xml.zip&quot;</code> or <code>&quot;test.zip&quot;</code>.
247Similarly, the filename in the archive will be
248<code>&quot;test.sbml&quot;</code> if the given filename is
249<code>&quot;test.sbml.zip&quot;</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>&quot;.gz&quot;</code>
321(for example, <code>&quot;myfile.xml.gz&quot;</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>&quot;.zip&quot;</code> or
324<code>&quot;.bz2&quot;</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>&quot;.zip&quot;</code>, the file placed in the zip archive
329will have the suffix <code>&quot;.xml&quot;</code> or
330<code>&quot;.sbml&quot;</code>.  For example, the file in the zip archive
331will be named <code>&quot;test.xml&quot;</code> if the given filename is
332<code>&quot;test.xml.zip&quot;</code> or <code>&quot;test.zip&quot;</code>.
333Similarly, the filename in the archive will be
334<code>&quot;test.sbml&quot;</code> if the given filename is
335<code>&quot;test.sbml.zip&quot;</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}