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 *  Base class for SBML converters.
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.  It is a class used in
017the implementation of extra functionality provided by libSBML.
018</p>
019
020 <p>
021 * The {@link SBMLConverter} class is the base class for the various SBML 
022 * <em>converters</em>: classes of objects that transform or convert SBML documents.
023 * These transformations can involve essentially anything that can be written
024 * algorithmically; examples include converting the units of measurement in a
025 * model, or converting from one Level+Version combination of SBML to
026 * another.  Applications can also create their own converters by subclassing
027 * {@link SBMLConverter} and following the examples of the existing converters.
028 <p>
029 * <p>
030 * <h2>General information about the use of SBML converters</h2>
031 <p>
032 * The use of all the converters follows a similar approach.  First, one
033 * creates a {@link ConversionProperties} object and calls
034 * {@link ConversionProperties#addOption(ConversionOption)}
035 * on this object with one argument: a text string that identifies the desired
036 * converter.  (The text string is specific to each converter; consult the
037 * documentation for a given converter to find out how it should be enabled.)
038 <p>
039 * Next, for some converters, the caller can optionally set some
040 * converter-specific properties using additional calls to
041 * {@link ConversionProperties#addOption(ConversionOption)}.
042 * Many converters provide the ability to
043 * configure their behavior to some extent; this is realized through the use
044 * of properties that offer different options.  The default property values
045 * for each converter can be interrogated using the method
046 * {@link SBMLConverter#getDefaultProperties()} on the converter class in question .
047 <p>
048 * Finally, the caller should invoke the method
049 * {@link SBMLDocument#convert(ConversionProperties)}
050 * with the {@link ConversionProperties} object as an argument.
051 <p>
052 * <h3>Example of invoking an SBML converter</h3>
053 <p>
054 * The following code fragment illustrates an example using
055 * {@link SBMLReactionConverter}, which is invoked using the option string
056 * <code>'replaceReactions':</code>
057 <p>
058<pre class='fragment'>
059{@link ConversionProperties} props = new {@link ConversionProperties}();
060if (props != null) {
061  props.addOption('replaceReactions');
062} else {
063  // Deal with error.
064}
065</pre>
066<p>
067 * In the case of {@link SBMLReactionConverter}, there are no options to affect
068 * its behavior, so the next step is simply to invoke the converter on
069 * an {@link SBMLDocument} object.  Continuing the example code:
070 <p>
071<pre class='fragment'>
072  // Assume that the variable 'document' has been set to an {@link SBMLDocument} object.
073  status = document.convert(config);
074  if (status != libsbml.LIBSBML_OPERATION_SUCCESS)
075  {
076    // Handle error somehow.
077    System.out.println('Error: conversion failed due to the following:');
078    document.printErrors();
079  }
080</pre>
081<p>
082 * Here is an example of using a converter that offers an option. The
083 * following code invokes {@link SBMLStripPackageConverter} to remove the
084 * SBML Level&nbsp;3 <em>Layout</em> package from a model.  It sets the name
085 * of the package to be removed by adding a value for the option named
086 * <code>'package'</code> defined by that converter:
087 <p>
088<pre class='fragment'>
089{@link ConversionProperties} config = new {@link ConversionProperties}();
090if (config != None) {
091  config.addOption('stripPackage');
092  config.addOption('package', 'layout');
093  status = document.convert(config);
094  if (status != LIBSBML_OPERATION_SUCCESS) {
095    // Handle error somehow.
096    System.out.println('Error: unable to strip the {@link Layout} package');
097    document.printErrors();
098  }
099} else {
100  // Handle error somehow.
101  System.out.println('Error: unable to create {@link ConversionProperties} object');
102}
103</pre>
104<p>
105 * <h3>Available SBML converters in libSBML</h3>
106 <p>
107 * LibSBML provides a number of built-in converters; by convention, their
108 * names end in <em>Converter</em>. The following are the built-in converters
109 * provided by libSBML 5.16.0
110:
111 <p>
112 * <p>
113 * <ul>
114 * <li> ArraysFlatteningConverter
115 * <li> {@link CobraToFbcConverter}
116 * <li> {@link CompFlatteningConverter}
117 * <li> {@link FbcToCobraConverter}
118 * <li> {@link FbcV1ToV2Converter}
119 * <li> {@link FbcV2ToV1Converter}
120 * <li> {@link SBMLFunctionDefinitionConverter}
121 * <li> {@link SBMLIdConverter}
122 * <li> {@link SBMLInferUnitsConverter}
123 * <li> {@link SBMLInitialAssignmentConverter}
124 * <li> {@link SBMLLevel1Version1Converter}
125 * <li> {@link SBMLLevelVersionConverter}
126 * <li> {@link SBMLLocalParameterConverter}
127 * <li> SBMLRateOfConverter
128 * <li> {@link SBMLReactionConverter}
129 * <li> {@link SBMLRuleConverter}
130 * <li> {@link SBMLStripPackageConverter}
131 * <li> {@link SBMLUnitsConverter}
132 *
133 * </ul>
134 */
135
136public class SBMLConverter {
137   private long swigCPtr;
138   protected boolean swigCMemOwn;
139
140   protected SBMLConverter(long cPtr, boolean cMemoryOwn)
141   {
142     swigCMemOwn = cMemoryOwn;
143     swigCPtr    = cPtr;
144   }
145
146   protected static long getCPtr(SBMLConverter obj)
147   {
148     return (obj == null) ? 0 : obj.swigCPtr;
149   }
150
151   protected static long getCPtrAndDisown (SBMLConverter obj)
152   {
153     long ptr = 0;
154
155     if (obj != null)
156     {
157       ptr             = obj.swigCPtr;
158       obj.swigCMemOwn = false;
159     }
160
161     return ptr;
162   }
163
164  protected void finalize() {
165    delete();
166  }
167
168  public synchronized void delete() {
169    if (swigCPtr != 0) {
170      if (swigCMemOwn) {
171        swigCMemOwn = false;
172        libsbmlJNI.delete_SBMLConverter(swigCPtr);
173      }
174      swigCPtr = 0;
175    }
176  }
177
178  protected void swigDirectorDisconnect() {
179    swigCMemOwn = false;
180    delete();
181  }
182
183  public void swigReleaseOwnership() {
184    swigCMemOwn = false;
185    libsbmlJNI.SBMLConverter_change_ownership(this, swigCPtr, false);
186  }
187
188  public void swigTakeOwnership() {
189    swigCMemOwn = true;
190    libsbmlJNI.SBMLConverter_change_ownership(this, swigCPtr, true);
191  }
192
193  
194/**
195   * Creates a new {@link SBMLConverter} object.
196   */ public
197 SBMLConverter() {
198    this(libsbmlJNI.new_SBMLConverter__SWIG_0(), true);
199    libsbmlJNI.SBMLConverter_director_connect(this, swigCPtr, swigCMemOwn, true);
200  }
201
202  
203/**
204   * Creates a new {@link SBMLConverter} object with a given name.
205   <p>
206   * @param name the name for the converter to create.
207   */ public
208 SBMLConverter(String name) {
209    this(libsbmlJNI.new_SBMLConverter__SWIG_1(name), true);
210    libsbmlJNI.SBMLConverter_director_connect(this, swigCPtr, swigCMemOwn, true);
211  }
212
213  
214/**
215   * Copy constructor.
216   <p>
217   * This creates a copy of an {@link SBMLConverter} object.
218   <p>
219   * @param orig the {@link SBMLConverter} object to copy.
220   */ public
221 SBMLConverter(SBMLConverter orig) {
222    this(libsbmlJNI.new_SBMLConverter__SWIG_2(SBMLConverter.getCPtr(orig), orig), true);
223    libsbmlJNI.SBMLConverter_director_connect(this, swigCPtr, swigCMemOwn, true);
224  }
225
226  
227/**
228   * Creates and returns a deep copy of this {@link SBMLConverter} object.
229   <p>
230   * @return the (deep) copy of this {@link SBMLConverter} object.
231   */ public
232 SBMLConverter cloneObject() {
233    return libsbml.DowncastSBMLConverter((getClass() == SBMLConverter.class) ? libsbmlJNI.SBMLConverter_cloneObject(swigCPtr, this) : libsbmlJNI.SBMLConverter_cloneObjectSwigExplicitSBMLConverter(swigCPtr, this), true);
234}
235
236  
237/**
238   * Returns the SBML document that is the subject of the conversions.
239   <p>
240   * @return the current {@link SBMLDocument} object.
241   */ public
242 SBMLDocument getDocument() {
243    long cPtr = (getClass() == SBMLConverter.class) ? libsbmlJNI.SBMLConverter_getDocument__SWIG_0(swigCPtr, this) : libsbmlJNI.SBMLConverter_getDocumentSwigExplicitSBMLConverter__SWIG_0(swigCPtr, this);
244    return (cPtr == 0) ? null : new SBMLDocument(cPtr, false);
245  }
246
247  
248/**
249   * Returns the default properties of this converter.
250   <p>
251   * A given converter exposes one or more properties that can be adjusted
252   * in order to influence the behavior of the converter.  This method
253   * returns the <em>default</em> property settings for this converter.  It is
254   * meant to be called in order to discover all the settings for the
255   * converter object.  The run-time properties of the converter object can
256   * be adjusted by using the method
257   * {@link SBMLConverter#setProperties(ConversionProperties props)}.
258   <p>
259   * @return the default properties for the converter.
260   <p>
261   * @see #setProperties(ConversionProperties)
262   * @see #matchesProperties(ConversionProperties)
263   */ public
264 ConversionProperties getDefaultProperties() {
265    return new ConversionProperties((getClass() == SBMLConverter.class) ? libsbmlJNI.SBMLConverter_getDefaultProperties(swigCPtr, this) : libsbmlJNI.SBMLConverter_getDefaultPropertiesSwigExplicitSBMLConverter(swigCPtr, this), true);
266  }
267
268  
269/**
270   * Returns the target SBML namespaces of the currently set properties.
271   <p>
272   * SBML namespaces are used by libSBML to express the Level+Version of the
273   * SBML document (and, possibly, any SBML Level&nbsp;3 packages in
274   * use). Some converters' behavior is affected by the SBML namespace
275   * configured in the converter.  For example, in {@link SBMLLevelVersionConverter}
276   * (the converter for converting SBML documents from one Level+Version
277   * combination to another), the actions are fundamentally dependent on the
278   * SBML namespaces targeted.
279   <p>
280   * @return the {@link SBMLNamespaces} object that describes the SBML namespaces
281   * in effect, or <code>null</code> if none are set.
282   */ public
283 SBMLNamespaces getTargetNamespaces() {
284  return libsbml.DowncastSBMLNamespaces((getClass() == SBMLConverter.class) ? libsbmlJNI.SBMLConverter_getTargetNamespaces(swigCPtr, this) : libsbmlJNI.SBMLConverter_getTargetNamespacesSwigExplicitSBMLConverter(swigCPtr, this), false);
285}
286
287  
288/**
289   * Returns <code>true</code> if this converter matches the given properties.
290   <p>
291   * Given a {@link ConversionProperties} object <code>props</code>, this method checks that 
292   * <code>props</code> possesses an option value to enable this converter.  If it does,
293   * this method returns <code>true.</code>
294   <p>
295   * @param props the properties to match.
296   <p>
297   * @return <code>true</code> if the properties <code>props</code> would match the necessary
298   * properties for this type of converter, <code>false</code> otherwise.
299   */ public
300 boolean matchesProperties(ConversionProperties props) {
301    return (getClass() == SBMLConverter.class) ? libsbmlJNI.SBMLConverter_matchesProperties(swigCPtr, this, ConversionProperties.getCPtr(props), props) : libsbmlJNI.SBMLConverter_matchesPropertiesSwigExplicitSBMLConverter(swigCPtr, this, ConversionProperties.getCPtr(props), props);
302  }
303
304  
305/**
306   * Sets the SBML document to be converted.
307   <p>
308   * @param doc the document to use for this conversion.
309   <p>
310   * @return integer value indicating the success/failure of the operation.
311   *  The set of possible values that may
312   * be returned ultimately depends on the specific subclass of
313   * {@link SBMLConverter} being used, but the default method can return the
314   * following:
315   * <ul>
316   * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS}
317   * </ul>
318   */ public
319 int setDocument(SBMLDocument doc) {
320    return (getClass() == SBMLConverter.class) ? libsbmlJNI.SBMLConverter_setDocument(swigCPtr, this, SBMLDocument.getCPtr(doc), doc) : libsbmlJNI.SBMLConverter_setDocumentSwigExplicitSBMLConverter(swigCPtr, this, SBMLDocument.getCPtr(doc), doc);
321  }
322
323  
324/**
325   * Sets the configuration properties to be used by this converter.
326   <p>
327   * @param props the {@link ConversionProperties} object defining the properties
328   * to set.
329   <p>
330   * @return integer value indicating the success/failure of the operation.
331   *  The set of possible values that may
332   * be returned ultimately depends on the specific subclass of
333   * {@link SBMLConverter} being used, but the default method can return the
334   * following values:
335   * <ul>
336   * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS}
337   * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED}
338   *
339   * </ul> <p>
340   * @see #getProperties()
341   * @see #matchesProperties(ConversionProperties)
342   */ public
343 int setProperties(ConversionProperties props) {
344    return (getClass() == SBMLConverter.class) ? libsbmlJNI.SBMLConverter_setProperties(swigCPtr, this, ConversionProperties.getCPtr(props), props) : libsbmlJNI.SBMLConverter_setPropertiesSwigExplicitSBMLConverter(swigCPtr, this, ConversionProperties.getCPtr(props), props);
345  }
346
347  
348/**
349   * Returns the current properties in effect for this converter.
350   <p>
351   * A given converter exposes one or more properties that can be adjusted
352   * in order to influence the behavior of the converter.  This method
353   * returns the current properties for this converter; in other words, the
354   * settings in effect at this moment.  To change the property values, you
355   * can use {@link SBMLConverter#setProperties(ConversionProperties props)}.
356   <p>
357   * @return the currently set configuration properties.
358   <p>
359   * @see #setProperties(ConversionProperties)
360   * @see #matchesProperties(ConversionProperties)
361   */ public
362 ConversionProperties getProperties() {
363    long cPtr = (getClass() == SBMLConverter.class) ? libsbmlJNI.SBMLConverter_getProperties(swigCPtr, this) : libsbmlJNI.SBMLConverter_getPropertiesSwigExplicitSBMLConverter(swigCPtr, this);
364    return (cPtr == 0) ? null : new ConversionProperties(cPtr, false);
365  }
366
367  
368/**
369   * Perform the conversion.
370   <p>
371   * This method causes the converter to do the actual conversion work,
372   * that is, to convert the {@link SBMLDocument} object set by
373   * {@link SBMLConverter#setDocument(SBMLDocument)} and
374   * with the configuration options set by
375   * {@link SBMLConverter#setProperties(ConversionProperties)}.
376   <p>
377   * @return  integer value indicating the success/failure of the operation.
378   *  The set of possible values that may
379   * be returned depends on the converter subclass; please consult
380   * the documentation for the relevant class to find out what the
381   * possibilities are.
382   */ public
383 int convert() {
384    return (getClass() == SBMLConverter.class) ? libsbmlJNI.SBMLConverter_convert(swigCPtr, this) : libsbmlJNI.SBMLConverter_convertSwigExplicitSBMLConverter(swigCPtr, this);
385  }
386
387  
388/**
389   * Returns the name of this converter.
390   <p>
391   * @return a string, the name of this converter.
392   */ public
393 String getName() {
394    return libsbmlJNI.SBMLConverter_getName(swigCPtr, this);
395  }
396
397}