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 *  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.
024 <p>
025 * This class is also the basis for
026 * {@link SBMLDocument#setLevelAndVersion(long, long, boolean)}.
027 <p>
028 * <h2>Configuration and use of {@link SBMLLevelVersionConverter}</h2>
029 <p>
030 * {@link SBMLLevelVersionConverter} is enabled by creating a {@link ConversionProperties}
031 * object with the option <code>'setLevelAndVersion'</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>'strict':</code> If this option has the value <code>true</code>, then the validity
041 * of the SBML document will be strictly preserved.  This means that SBML
042 * validation will be performed, and if the original model is not valid or
043 * semantics cannot be preserved in the converted model, then conversion will
044 * not be performed.  Conversely, if this option is set to <code>false</code>, model
045 * conversion will always be performed; if any errors are detected related to
046 * altered semantics, the errors will be logged in the usual way (i.e., the
047 * error log on the {@link SBMLDocument} object).
048 <p>
049 * <li> <code>'addDefaultUnits':</code> By default, a conversion from SBML Level&nbsp;2
050 * to Level&nbsp;3 will explicitly add {@link UnitDefinition} objects and unit
051 * attributes on the {@link Model} object to define units that are implicitly defined
052 * in SBML Level&nbsp;2.  This is usually desirable because in SBML
053 * Level&nbsp;3, there are no default units and a conversion from
054 * Level&nbsp;2 that did <em>not</em> add unit definitions would actually result
055 * in a loss of information.  However, some users or software tools may not
056 * need or want this, or worse, may be fooled into thinking that libSBML has
057 * somehow inferred the proper units for model quantities.  (It has not; it
058 * merely adds generic predefined units.)  This option lets callers control
059 * this behavior.
060 *
061 * </ul> <p>
062 * <p>
063 * <h2>General information about the use of SBML converters</h2>
064 <p>
065 * The use of all the converters follows a similar approach.  First, one
066 * creates a {@link ConversionProperties} object and calls
067 * {@link ConversionProperties#addOption(ConversionOption)}
068 * on this object with one argument: a text string that identifies the desired
069 * converter.  (The text string is specific to each converter; consult the
070 * documentation for a given converter to find out how it should be enabled.)
071 <p>
072 * Next, for some converters, the caller can optionally set some
073 * converter-specific properties using additional calls to
074 * {@link ConversionProperties#addOption(ConversionOption)}.
075 * Many converters provide the ability to
076 * configure their behavior to some extent; this is realized through the use
077 * of properties that offer different options.  The default property values
078 * for each converter can be interrogated using the method
079 * {@link SBMLConverter#getDefaultProperties()} on the converter class in question .
080 <p>
081 * Finally, the caller should invoke the method
082 * {@link SBMLDocument#convert(ConversionProperties)}
083 * with the {@link ConversionProperties} object as an argument.
084 <p>
085 * <h3>Example of invoking an SBML converter</h3>
086 <p>
087 * The following code fragment illustrates an example using
088 * {@link SBMLReactionConverter}, which is invoked using the option string
089 * <code>'replaceReactions':</code>
090 <p>
091<pre class='fragment'>
092{@link ConversionProperties} props = new {@link ConversionProperties}();
093if (props != null) {
094  props.addOption('replaceReactions');
095} else {
096  // Deal with error.
097}
098</pre>
099<p>
100 * In the case of {@link SBMLReactionConverter}, there are no options to affect
101 * its behavior, so the next step is simply to invoke the converter on
102 * an {@link SBMLDocument} object.  Continuing the example code:
103 <p>
104<pre class='fragment'>
105  // Assume that the variable 'document' has been set to an {@link SBMLDocument} object.
106  status = document.convert(config);
107  if (status != libsbml.LIBSBML_OPERATION_SUCCESS)
108  {
109    // Handle error somehow.
110    System.out.println('Error: conversion failed due to the following:');
111    document.printErrors();
112  }
113</pre>
114<p>
115 * Here is an example of using a converter that offers an option. The
116 * following code invokes {@link SBMLStripPackageConverter} to remove the
117 * SBML Level&nbsp;3 <em>Layout</em> package from a model.  It sets the name
118 * of the package to be removed by adding a value for the option named
119 * <code>'package'</code> defined by that converter:
120 <p>
121<pre class='fragment'>
122{@link ConversionProperties} config = new {@link ConversionProperties}();
123if (config != None) {
124  config.addOption('stripPackage');
125  config.addOption('package', 'layout');
126  status = document.convert(config);
127  if (status != LIBSBML_OPERATION_SUCCESS) {
128    // Handle error somehow.
129    System.out.println('Error: unable to strip the {@link Layout} package');
130    document.printErrors();
131  }
132} else {
133  // Handle error somehow.
134  System.out.println('Error: unable to create {@link ConversionProperties} object');
135}
136</pre>
137<p>
138 * <h3>Available SBML converters in libSBML</h3>
139 <p>
140 * LibSBML provides a number of built-in converters; by convention, their
141 * names end in <em>Converter</em>. The following are the built-in converters
142 * provided by libSBML 5.16.0
143:
144 <p>
145 * <p>
146 * <ul>
147 * <li> ArraysFlatteningConverter
148 * <li> {@link CobraToFbcConverter}
149 * <li> {@link CompFlatteningConverter}
150 * <li> {@link FbcToCobraConverter}
151 * <li> {@link FbcV1ToV2Converter}
152 * <li> {@link FbcV2ToV1Converter}
153 * <li> {@link SBMLFunctionDefinitionConverter}
154 * <li> {@link SBMLIdConverter}
155 * <li> {@link SBMLInferUnitsConverter}
156 * <li> {@link SBMLInitialAssignmentConverter}
157 * <li> {@link SBMLLevel1Version1Converter}
158 * <li> {@link SBMLLevelVersionConverter}
159 * <li> {@link SBMLLocalParameterConverter}
160 * <li> SBMLRateOfConverter
161 * <li> {@link SBMLReactionConverter}
162 * <li> {@link SBMLRuleConverter}
163 * <li> {@link SBMLStripPackageConverter}
164 * <li> {@link SBMLUnitsConverter}
165 *
166 * </ul>
167 */
168
169public class SBMLLevelVersionConverter extends SBMLConverter {
170   private long swigCPtr;
171
172   protected SBMLLevelVersionConverter(long cPtr, boolean cMemoryOwn)
173   {
174     super(libsbmlJNI.SBMLLevelVersionConverter_SWIGUpcast(cPtr), cMemoryOwn);
175     swigCPtr = cPtr;
176   }
177
178   protected static long getCPtr(SBMLLevelVersionConverter obj)
179   {
180     return (obj == null) ? 0 : obj.swigCPtr;
181   }
182
183   protected static long getCPtrAndDisown (SBMLLevelVersionConverter obj)
184   {
185     long ptr = 0;
186
187     if (obj != null)
188     {
189       ptr             = obj.swigCPtr;
190       obj.swigCMemOwn = false;
191     }
192
193     return ptr;
194   }
195
196  protected void finalize() {
197    delete();
198  }
199
200  public synchronized void delete() {
201    if (swigCPtr != 0) {
202      if (swigCMemOwn) {
203        swigCMemOwn = false;
204        libsbmlJNI.delete_SBMLLevelVersionConverter(swigCPtr);
205      }
206      swigCPtr = 0;
207    }
208    super.delete();
209  }
210
211  
212/** * @internal */ public
213 static void init() {
214    libsbmlJNI.SBMLLevelVersionConverter_init();
215  }
216
217  
218/**
219   * Creates a new {@link SBMLLevelVersionConverter} object.
220   */ public
221 SBMLLevelVersionConverter() {
222    this(libsbmlJNI.new_SBMLLevelVersionConverter__SWIG_0(), true);
223  }
224
225  
226/**
227   * Copy constructor; creates a copy of an {@link SBMLLevelVersionConverter}
228   * object.
229   <p>
230   * @param obj the {@link SBMLLevelVersionConverter} object to copy.
231   */ public
232 SBMLLevelVersionConverter(SBMLLevelVersionConverter obj) {
233    this(libsbmlJNI.new_SBMLLevelVersionConverter__SWIG_1(SBMLLevelVersionConverter.getCPtr(obj), obj), true);
234  }
235
236  
237/**
238   * Creates and returns a deep copy of this {@link SBMLLevelVersionConverter}
239   * object.
240   <p>
241   * @return a (deep) copy of this converter.
242   */ public
243 SBMLConverter cloneObject() {
244    long cPtr = libsbmlJNI.SBMLLevelVersionConverter_cloneObject(swigCPtr, this);
245    return (cPtr == 0) ? null : new SBMLLevelVersionConverter(cPtr, true);
246  }
247
248  
249/**
250   * Returns <code>true</code> if this converter object's properties match the given
251   * properties.
252   <p>
253   * A typical use of this method involves creating a {@link ConversionProperties}
254   * object, setting the options desired, and then calling this method on
255   * an {@link SBMLLevelVersionConverter} object to find out if the object's
256   * property values match the given ones.  This method is also used by
257   * {@link SBMLConverterRegistry#getConverterFor(ConversionProperties)}
258   * to search across all registered converters for one matching particular
259   * properties.
260   <p>
261   * @param props the properties to match.
262   <p>
263   * @return <code>true</code> if this converter's properties match, <code>false</code>
264   * otherwise.
265   */ public
266 boolean matchesProperties(ConversionProperties props) {
267    return libsbmlJNI.SBMLLevelVersionConverter_matchesProperties(swigCPtr, this, ConversionProperties.getCPtr(props), props);
268  }
269
270  
271/**
272   * Perform the conversion.
273   <p>
274   * This method causes the converter to do the actual conversion work,
275   * that is, to convert the {@link SBMLDocument} object set by
276   * {@link SBMLConverter#setDocument(SBMLDocument)} and
277   * with the configuration options set by
278   * {@link SBMLConverter#setProperties(ConversionProperties)}.
279   <p>
280   * <p>
281 * @return integer value indicating success/failure of the
282 * function.   The possible values
283 * returned by this function are:
284   * <ul>
285   * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS}
286   * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED}
287   * <li> {@link libsbmlConstants#LIBSBML_CONV_INVALID_TARGET_NAMESPACE LIBSBML_CONV_INVALID_TARGET_NAMESPACE}
288   * <li> {@link libsbmlConstants#LIBSBML_CONV_PKG_CONVERSION_NOT_AVAILABLE LIBSBML_CONV_PKG_CONVERSION_NOT_AVAILABLE}
289   * <li> {@link libsbmlConstants#LIBSBML_CONV_INVALID_SRC_DOCUMENT LIBSBML_CONV_INVALID_SRC_DOCUMENT}
290   * </ul>
291   */ public
292 int convert() {
293    return libsbmlJNI.SBMLLevelVersionConverter_convert(swigCPtr, this);
294  }
295
296  
297/**
298   * Returns the default properties of this converter.
299   <p>
300   * A given converter exposes one or more properties that can be adjusted
301   * in order to influence the behavior of the converter.  This method
302   * returns the <em>default</em> property settings for this converter.  It is
303   * meant to be called in order to discover all the settings for the
304   * converter object.
305   <p>
306   * @return the {@link ConversionProperties} object describing the default properties
307   * for this converter.
308   */ public
309 ConversionProperties getDefaultProperties() {
310    return new ConversionProperties(libsbmlJNI.SBMLLevelVersionConverter_getDefaultProperties(swigCPtr, this), true);
311  }
312
313  
314/**
315   * Returns the target SBML Level for the conversion.
316   <p>
317   * @return an integer indicating the SBML Level.
318   */ public
319 long getTargetLevel() {
320    return libsbmlJNI.SBMLLevelVersionConverter_getTargetLevel(swigCPtr, this);
321  }
322
323  
324/**
325   * Returns the target SBML Version for the conversion.
326   <p>
327   * @return an integer indicating the Version within the SBML Level.
328   */ public
329 long getTargetVersion() {
330    return libsbmlJNI.SBMLLevelVersionConverter_getTargetVersion(swigCPtr, this);
331  }
332
333  
334/**
335   * Returns the flag indicating whether the conversion has been set to 'strict'.
336   <p>
337   * @return <code>true</code> if strict validity has been requested, <code>false</code>
338   * otherwise.
339   */ public
340 boolean getValidityFlag() {
341    return libsbmlJNI.SBMLLevelVersionConverter_getValidityFlag(swigCPtr, this);
342  }
343
344  
345/**
346   * Returns the flag indicating whether default units should be added when
347   * converting to L3 or not.
348   <p>
349   * @return <code>true</code> if default units should be added, <code>false</code>
350   * otherwise.
351   */ public
352 boolean getAddDefaultUnits() {
353    return libsbmlJNI.SBMLLevelVersionConverter_getAddDefaultUnits(swigCPtr, this);
354  }
355
356}