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