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