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 *  Converts a model's existing units to SI units.
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 converts the units in a model to base SI units, that
022 * is, using only the units metre, kilogram, second, ampere, kelvin, mole and
023 * candela.
024 <p>
025 * {@link Unit} conversion will only be performed on models that are fully unit
026 * consistent, meaning that all objects have units associated with them and
027 * there are no literal numbers with unspecified units.  In the case of an
028 * SBML Level&nbsp;3 model involving math expressions, this means that the
029 * <code>timeUnits</code> attribute on the {@link Model} object must be set, and if there are any
030 * reactions in the model, the <code>extentUnits</code> attribute on the {@link Model} object
031 * must also be set.
032 <p>
033 * <h2>Configuration and use of {@link SBMLUnitsConverter}</h2>
034 <p>
035 * {@link SBMLUnitsConverter} is enabled by creating a {@link ConversionProperties} object
036 * with the option <code>'units'</code>, and passing this properties object to
037 * {@link SBMLDocument#convert(ConversionProperties)}.  This
038 * converter takes one optional option:
039 <p>
040 * <ul>
041 * <li> <code>'removeUnusedUnits':</code> the value of this property should be a
042 * Boolean.  If it is <code>true</code>, it tells the unit convert to remove any unused
043 * {@link UnitDefinition} objects after conversion is complete.  ('Unused' units are
044 * units that are not referenced by any object in the model.)  If the value
045 * is <code>false</code>, unused {@link UnitDefinition} objects are not removed from the model.
046 * The default is <code>true.</code>
047 *
048 * </ul> <p>
049 * <p>
050 * <h2>General information about the use of SBML converters</h2>
051 <p>
052 * The use of all the converters follows a similar approach.  First, one
053 * creates a {@link ConversionProperties} object and calls
054 * {@link ConversionProperties#addOption(ConversionOption)}
055 * on this object with one argument: a text string that identifies the desired
056 * converter.  (The text string is specific to each converter; consult the
057 * documentation for a given converter to find out how it should be enabled.)
058 <p>
059 * Next, for some converters, the caller can optionally set some
060 * converter-specific properties using additional calls to
061 * {@link ConversionProperties#addOption(ConversionOption)}.
062 * Many converters provide the ability to
063 * configure their behavior to some extent; this is realized through the use
064 * of properties that offer different options.  The default property values
065 * for each converter can be interrogated using the method
066 * {@link SBMLConverter#getDefaultProperties()} on the converter class in question .
067 <p>
068 * Finally, the caller should invoke the method
069 * {@link SBMLDocument#convert(ConversionProperties)}
070 * with the {@link ConversionProperties} object as an argument.
071 <p>
072 * <h3>Example of invoking an SBML converter</h3>
073 <p>
074 * The following code fragment illustrates an example using
075 * {@link SBMLReactionConverter}, which is invoked using the option string
076 * <code>'replaceReactions':</code>
077 <p>
078<pre class='fragment'>
079{@link ConversionProperties} props = new {@link ConversionProperties}();
080if (props != null) {
081  props.addOption('replaceReactions');
082} else {
083  // Deal with error.
084}
085</pre>
086<p>
087 * In the case of {@link SBMLReactionConverter}, there are no options to affect
088 * its behavior, so the next step is simply to invoke the converter on
089 * an {@link SBMLDocument} object.  Continuing the example code:
090 <p>
091<pre class='fragment'>
092  // Assume that the variable 'document' has been set to an {@link SBMLDocument} object.
093  status = document.convert(config);
094  if (status != libsbml.LIBSBML_OPERATION_SUCCESS)
095  {
096    // Handle error somehow.
097    System.out.println('Error: conversion failed due to the following:');
098    document.printErrors();
099  }
100</pre>
101<p>
102 * Here is an example of using a converter that offers an option. The
103 * following code invokes {@link SBMLStripPackageConverter} to remove the
104 * SBML Level&nbsp;3 <em>Layout</em> package from a model.  It sets the name
105 * of the package to be removed by adding a value for the option named
106 * <code>'package'</code> defined by that converter:
107 <p>
108<pre class='fragment'>
109{@link ConversionProperties} config = new {@link ConversionProperties}();
110if (config != None) {
111  config.addOption('stripPackage');
112  config.addOption('package', 'layout');
113  status = document.convert(config);
114  if (status != LIBSBML_OPERATION_SUCCESS) {
115    // Handle error somehow.
116    System.out.println('Error: unable to strip the {@link Layout} package');
117    document.printErrors();
118  }
119} else {
120  // Handle error somehow.
121  System.out.println('Error: unable to create {@link ConversionProperties} object');
122}
123</pre>
124<p>
125 * <h3>Available SBML converters in libSBML</h3>
126 <p>
127 * LibSBML provides a number of built-in converters; by convention, their
128 * names end in <em>Converter</em>. The following are the built-in converters
129 * provided by libSBML 5.16.0
130:
131 <p>
132 * <p>
133 * <ul>
134 * <li> ArraysFlatteningConverter
135 * <li> {@link CobraToFbcConverter}
136 * <li> {@link CompFlatteningConverter}
137 * <li> {@link FbcToCobraConverter}
138 * <li> {@link FbcV1ToV2Converter}
139 * <li> {@link FbcV2ToV1Converter}
140 * <li> {@link SBMLFunctionDefinitionConverter}
141 * <li> {@link SBMLIdConverter}
142 * <li> {@link SBMLInferUnitsConverter}
143 * <li> {@link SBMLInitialAssignmentConverter}
144 * <li> {@link SBMLLevel1Version1Converter}
145 * <li> {@link SBMLLevelVersionConverter}
146 * <li> {@link SBMLLocalParameterConverter}
147 * <li> SBMLRateOfConverter
148 * <li> {@link SBMLReactionConverter}
149 * <li> {@link SBMLRuleConverter}
150 * <li> {@link SBMLStripPackageConverter}
151 * <li> {@link SBMLUnitsConverter}
152 *
153 * </ul>
154 */
155
156public class SBMLUnitsConverter extends SBMLConverter {
157   private long swigCPtr;
158
159   protected SBMLUnitsConverter(long cPtr, boolean cMemoryOwn)
160   {
161     super(libsbmlJNI.SBMLUnitsConverter_SWIGUpcast(cPtr), cMemoryOwn);
162     swigCPtr = cPtr;
163   }
164
165   protected static long getCPtr(SBMLUnitsConverter obj)
166   {
167     return (obj == null) ? 0 : obj.swigCPtr;
168   }
169
170   protected static long getCPtrAndDisown (SBMLUnitsConverter obj)
171   {
172     long ptr = 0;
173
174     if (obj != null)
175     {
176       ptr             = obj.swigCPtr;
177       obj.swigCMemOwn = false;
178     }
179
180     return ptr;
181   }
182
183  protected void finalize() {
184    delete();
185  }
186
187  public synchronized void delete() {
188    if (swigCPtr != 0) {
189      if (swigCMemOwn) {
190        swigCMemOwn = false;
191        libsbmlJNI.delete_SBMLUnitsConverter(swigCPtr);
192      }
193      swigCPtr = 0;
194    }
195    super.delete();
196  }
197
198  
199/** * @internal */ public
200 static void init() {
201    libsbmlJNI.SBMLUnitsConverter_init();
202  }
203
204  
205/**
206   * Creates a new {@link SBMLUnitsConverter} object.
207   */ public
208 SBMLUnitsConverter() {
209    this(libsbmlJNI.new_SBMLUnitsConverter__SWIG_0(), true);
210  }
211
212  
213/**
214   * Copy constructor; creates a copy of an {@link SBMLUnitsConverter}
215   * object.
216   <p>
217   * @param obj the {@link SBMLUnitsConverter} object to copy.
218   */ public
219 SBMLUnitsConverter(SBMLUnitsConverter obj) {
220    this(libsbmlJNI.new_SBMLUnitsConverter__SWIG_1(SBMLUnitsConverter.getCPtr(obj), obj), true);
221  }
222
223  
224/**
225   * Creates and returns a deep copy of this {@link SBMLUnitsConverter}
226   * object.
227   <p>
228   * @return a (deep) copy of this converter.
229   */ public
230 SBMLConverter cloneObject() {
231    long cPtr = libsbmlJNI.SBMLUnitsConverter_cloneObject(swigCPtr, this);
232    return (cPtr == 0) ? null : new SBMLUnitsConverter(cPtr, true);
233  }
234
235  
236/**
237   * Returns <code>true</code> if this converter object's properties match the given
238   * properties.
239   <p>
240   * A typical use of this method involves creating a {@link ConversionProperties}
241   * object, setting the options desired, and then calling this method on
242   * an {@link SBMLUnitsConverter} object to find out if the object's
243   * property values match the given ones.  This method is also used by
244   * {@link SBMLConverterRegistry#getConverterFor(ConversionProperties)}
245   * to search across all registered converters for one matching particular
246   * properties.
247   <p>
248   * @param props the properties to match.
249   <p>
250   * @return <code>true</code> if this converter's properties match, <code>false</code>
251   * otherwise.
252   */ public
253 boolean matchesProperties(ConversionProperties props) {
254    return libsbmlJNI.SBMLUnitsConverter_matchesProperties(swigCPtr, this, ConversionProperties.getCPtr(props), props);
255  }
256
257  
258/**
259   * Perform the conversion.
260   <p>
261   * This method causes the converter to do the actual conversion work,
262   * that is, to convert the {@link SBMLDocument} object set by
263   * {@link SBMLConverter#setDocument(SBMLDocument)} and
264   * with the configuration options set by
265   * {@link SBMLConverter#setProperties(ConversionProperties)}.
266   <p>
267   * <p>
268 * @return integer value indicating success/failure of the
269 * function.   The possible values
270 * returned by this function are:
271   * <ul>
272   * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS}
273   * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED}
274   * <li> {@link libsbmlConstants#LIBSBML_INVALID_OBJECT LIBSBML_INVALID_OBJECT}
275   * <li> {@link libsbmlConstants#LIBSBML_CONV_CONVERSION_NOT_AVAILABLE LIBSBML_CONV_CONVERSION_NOT_AVAILABLE}
276   * <li> {@link libsbmlConstants#LIBSBML_CONV_INVALID_SRC_DOCUMENT LIBSBML_CONV_INVALID_SRC_DOCUMENT}
277   * </ul>
278   */ public
279 int convert() {
280    return libsbmlJNI.SBMLUnitsConverter_convert(swigCPtr, this);
281  }
282
283  
284/**
285   * Returns the default properties of this converter.
286   <p>
287   * A given converter exposes one or more properties that can be adjusted
288   * in order to influence the behavior of the converter.  This method
289   * returns the <em>default</em> property settings for this converter.  It is
290   * meant to be called in order to discover all the settings for the
291   * converter object.
292   <p>
293   * @return the {@link ConversionProperties} object describing the default properties
294   * for this converter.
295   */ public
296 ConversionProperties getDefaultProperties() {
297    return new ConversionProperties(libsbmlJNI.SBMLUnitsConverter_getDefaultProperties(swigCPtr, this), true);
298  }
299
300}