001/* ----------------------------------------------------------------------------
002 * This file was automatically generated by SWIG (http://www.swig.org).
003 * Version 3.0.10
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 *  Whole-document SBML Level/Version converter.
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 * This SBML converter takes an SBML document having one SBML Level+Version
022 * combination, and attempts to convert it to an SBML document having a
023 * different Level+Version combination.  This converter
024 * (SBMLLevel1Version1Converter) converts models to SBML Level&nbsp;1
025 * Version&nbsp;1, to the extent possible by the limited features of
026 * that Level/Version combination of SBML.
027 <p>
028 * <h2>Configuration and use of {@link SBMLLevel1Version1Converter}</h2>
029 <p>
030 * {@link SBMLLevel1Version1Converter} is enabled by creating a {@link ConversionProperties}
031 * object with the option <code>'convertToL1V1'</code>, and passing this
032 * properties object to {@link SBMLDocument#convert(ConversionProperties)}.  The target SBML Level and Version
033 * combination are determined by the value of the SBML namespace set on the
034 * {@link ConversionProperties} object (using
035 * {@link ConversionProperties#setTargetNamespaces(SBMLNamespaces targetNS)}).
036 <p>
037 * In addition, this converter offers the following options:
038 <p>
039 * <ul>
040 * <li> <code>'changePow':</code> Mathematical expressions for exponentiation of
041 * the form <code>pow(s1, 2)</code> will be converted to the expression
042 * <code>s1^2</code>.
043 <p>
044 * <li> <code>'inlineCompartmentSizes':</code> Back in the days of SBML Level&nbsp;1
045 * Version&nbsp;1, many software tools assumed that the 'kinetic laws' of
046 * SBML were written in terms of units of
047 * <em>concentration</em>/<em>time</em>.  These tools would not expect (and
048 * thus not handle) rate expressions such as
049 * <code>CompartmentOfS1 * k * S1</code>.
050 * When the option <code>'inlineCompartmentSizes'</code> is enabled, libSBML will
051 * replace the references to compartments (such as <code>'CompartmentOfS1'</code> in
052 * this example) with their initial sizes.  This is not strictly correct in
053 * all cases; in particular, if the compartment volume varies during
054 * simulation, this conversion will not reflect the expected behavior.
055 * However, many models do not have time-varying compartment sizes, so this
056 * option makes it easy to get modern SBML rate expressions into a form that
057 * old software tools may better understand.
058 *
059 * </ul> <p>
060 * <p>
061 * <h2>General information about the use of SBML converters</h2>
062 <p>
063 * The use of all the converters follows a similar approach.  First, one
064 * creates a {@link ConversionProperties} object and calls
065 * {@link ConversionProperties#addOption(ConversionOption)}
066 * on this object with one arguments: a text string that identifies the desired
067 * converter.  (The text string is specific to each converter; consult the
068 * documentation for a given converter to find out how it should be enabled.)
069 <p>
070 * Next, for some converters, the caller can optionally set some
071 * converter-specific properties using additional calls to
072 * {@link ConversionProperties#addOption(ConversionOption)}.
073 * Many converters provide the ability to
074 * configure their behavior to some extent; this is realized through the use
075 * of properties that offer different options.  The default property values
076 * for each converter can be interrogated using the method
077 * {@link SBMLConverter#getDefaultProperties()} on the converter class in question .
078 <p>
079 * Finally, the caller should invoke the method
080 * {@link SBMLDocument#convert(ConversionProperties)}
081 * with the {@link ConversionProperties} object as an argument.
082 <p>
083 * <h3>Example of invoking an SBML converter</h3>
084 <p>
085 * The following code fragment illustrates an example using
086 * {@link SBMLReactionConverter}, which is invoked using the option string 
087 * <code>'replaceReactions':</code>
088 <p>
089<pre class='fragment'>
090{@link ConversionProperties} props = new {@link ConversionProperties}();
091if (props != null) {
092  props.addOption('replaceReactions');
093} else {
094  // Deal with error.
095}
096</pre>
097<p>
098 * In the case of {@link SBMLReactionConverter}, there are no options to affect
099 * its behavior, so the next step is simply to invoke the converter on
100 * an {@link SBMLDocument} object.  Continuing the example code:
101 <p>
102<pre class='fragment'>
103  // Assume that the variable 'document' has been set to an {@link SBMLDocument} object.
104  status = document.convert(config);
105  if (status != libsbml.LIBSBML_OPERATION_SUCCESS)
106  {
107    // Handle error somehow.
108    System.out.println('Error: conversion failed due to the following:');
109    document.printErrors();
110  }
111</pre>
112<p>
113 * Here is an example of using a converter that offers an option. The
114 * following code invokes {@link SBMLStripPackageConverter} to remove the
115 * SBML Level&nbsp;3 <em>Layout</em> package from a model.  It sets the name
116 * of the package to be removed by adding a value for the option named
117 * <code>'package'</code> defined by that converter:
118 <p>
119<pre class='fragment'>
120{@link ConversionProperties} config = new {@link ConversionProperties}();
121if (config != None) {
122  config.addOption('stripPackage');
123  config.addOption('package', 'layout');
124  status = document.convert(config);
125  if (status != LIBSBML_OPERATION_SUCCESS) {
126    // Handle error somehow.
127    System.out.println('Error: unable to strip the {@link Layout} package');
128    document.printErrors();
129  }
130} else {
131  // Handle error somehow.
132  System.out.println('Error: unable to create {@link ConversionProperties} object');
133}
134</pre>
135<p>
136 * <h3>Available SBML converters in libSBML</h3>
137 <p>
138 * LibSBML provides a number of built-in converters; by convention, their
139 * names end in <em>Converter</em>. The following are the built-in converters
140 * provided by libSBML 5.13.0
141:
142 <p>
143 * <p>
144 * <ul>
145 * <li> {@link CobraToFbcConverter}
146 * <li> {@link CompFlatteningConverter}
147 * <li> {@link FbcToCobraConverter}
148 * <li> {@link FbcV1ToV2Converter}
149 * <li> {@link FbcV2ToV1Converter}
150 * <li> {@link SBMLFunctionDefinitionConverter}
151 * <li> {@link SBMLIdConverter}
152 * <li> {@link SBMLInferUnitsConverter}
153 * <li> {@link SBMLInitialAssignmentConverter}
154 * <li> {@link SBMLLevel1Version1Converter}
155 * <li> {@link SBMLLevelVersionConverter}
156 * <li> {@link SBMLLocalParameterConverter}
157 * <li> {@link SBMLReactionConverter}
158 * <li> {@link SBMLRuleConverter}
159 * <li> {@link SBMLStripPackageConverter}
160 * <li> {@link SBMLUnitsConverter}
161 *
162 * </ul>
163 */
164
165public class SBMLLevel1Version1Converter extends SBMLConverter {
166   private long swigCPtr;
167
168   protected SBMLLevel1Version1Converter(long cPtr, boolean cMemoryOwn)
169   {
170     super(libsbmlJNI.SBMLLevel1Version1Converter_SWIGUpcast(cPtr), cMemoryOwn);
171     swigCPtr = cPtr;
172   }
173
174   protected static long getCPtr(SBMLLevel1Version1Converter obj)
175   {
176     return (obj == null) ? 0 : obj.swigCPtr;
177   }
178
179   protected static long getCPtrAndDisown (SBMLLevel1Version1Converter obj)
180   {
181     long ptr = 0;
182
183     if (obj != null)
184     {
185       ptr             = obj.swigCPtr;
186       obj.swigCMemOwn = false;
187     }
188
189     return ptr;
190   }
191
192  protected void finalize() {
193    delete();
194  }
195
196  public synchronized void delete() {
197    if (swigCPtr != 0) {
198      if (swigCMemOwn) {
199        swigCMemOwn = false;
200        libsbmlJNI.delete_SBMLLevel1Version1Converter(swigCPtr);
201      }
202      swigCPtr = 0;
203    }
204    super.delete();
205  }
206
207  
208/** * @internal */ public
209 static void init() {
210    libsbmlJNI.SBMLLevel1Version1Converter_init();
211  }
212
213  
214/**
215   * Creates a new {@link SBMLLevel1Version1Converter} object.
216   */ public
217 SBMLLevel1Version1Converter() {
218    this(libsbmlJNI.new_SBMLLevel1Version1Converter__SWIG_0(), true);
219  }
220
221  
222/**
223   * Copy constructor; creates a copy of an {@link SBMLLevel1Version1Converter}
224   * object.
225   <p>
226   * @param obj the {@link SBMLLevel1Version1Converter} object to copy.
227   */ public
228 SBMLLevel1Version1Converter(SBMLLevel1Version1Converter obj) {
229    this(libsbmlJNI.new_SBMLLevel1Version1Converter__SWIG_1(SBMLLevel1Version1Converter.getCPtr(obj), obj), true);
230  }
231
232  
233/**
234   * Creates and returns a deep copy of this {@link SBMLLevel1Version1Converter}
235   * object.
236   <p>
237   * @return a (deep) copy of this converter.
238   */ public
239 SBMLConverter cloneObject() {
240    long cPtr = libsbmlJNI.SBMLLevel1Version1Converter_cloneObject(swigCPtr, this);
241    return (cPtr == 0) ? null : new SBMLLevel1Version1Converter(cPtr, true);
242  }
243
244  
245/**
246   * Returns <code>true</code> if this converter object's properties match the given
247   * properties.
248   <p>
249   * A typical use of this method involves creating a {@link ConversionProperties}
250   * object, setting the options desired, and then calling this method on
251   * an {@link SBMLLevel1Version1Converter} object to find out if the object's
252   * property values match the given ones.  This method is also used by
253   * {@link SBMLConverterRegistry#getConverterFor(ConversionProperties)}
254   * to search across all registered converters for one matching particular
255   * properties.
256   <p>
257   * @param props the properties to match.
258   <p>
259   * @return <code>true</code> if this converter's properties match, <code>false</code>
260   * otherwise.
261   */ public
262 boolean matchesProperties(ConversionProperties props) {
263    return libsbmlJNI.SBMLLevel1Version1Converter_matchesProperties(swigCPtr, this, ConversionProperties.getCPtr(props), props);
264  }
265
266  
267/**
268   * Perform the conversion.
269   <p>
270   * This method causes the converter to do the actual conversion work,
271   * that is, to convert the {@link SBMLDocument} object set by
272   * {@link SBMLConverter#setDocument(SBMLDocument)} and
273   * with the configuration options set by
274   * {@link SBMLConverter#setProperties(ConversionProperties)}.
275   <p>
276   * <p>
277 * @return integer value indicating success/failure of the
278 * function.   The possible values
279 * returned by this function are:
280   * <ul>
281   * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS}
282   * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED}
283   * <li> {@link libsbmlConstants#LIBSBML_CONV_INVALID_TARGET_NAMESPACE LIBSBML_CONV_INVALID_TARGET_NAMESPACE}
284   * <li> {@link libsbmlConstants#LIBSBML_CONV_PKG_CONVERSION_NOT_AVAILABLE LIBSBML_CONV_PKG_CONVERSION_NOT_AVAILABLE}
285   * <li> {@link libsbmlConstants#LIBSBML_CONV_INVALID_SRC_DOCUMENT LIBSBML_CONV_INVALID_SRC_DOCUMENT}
286   * </ul>
287   */ public
288 int convert() {
289    return libsbmlJNI.SBMLLevel1Version1Converter_convert(swigCPtr, this);
290  }
291
292  
293/**
294   * Returns the default properties of this converter.
295   <p>
296   * A given converter exposes one or more properties that can be adjusted
297   * in order to influence the behavior of the converter.  This method
298   * returns the <em>default</em> property settings for this converter.  It is
299   * meant to be called in order to discover all the settings for the
300   * converter object.
301   <p>
302   * @return the {@link ConversionProperties} object describing the default properties
303   * for this converter.
304   */ public
305 ConversionProperties getDefaultProperties() {
306    return new ConversionProperties(libsbmlJNI.SBMLLevel1Version1Converter_getDefaultProperties(swigCPtr, this), true);
307  }
308
309}