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 sorts SBML rules and assignments.
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 converter reorders assignments in a model.  Specifically, it sorts
022 * the list of assignment rules (i.e., the {@link AssignmentRule} objects contained
023 * in the ListOfAssignmentRules within the {@link Model} object) and the initial
024 * assignments (i.e., the {@link InitialAssignment} objects contained in the
025 * {@link ListOfInitialAssignments}) such that, within each set, assignments that
026 * depend on <em>prior</em> values are placed <em>after</em> the values are set.  For
027 * example, if there is an assignment rule stating <i>a = b + 1</i>, and
028 * another rule stating <i>b = 3</i>, the list of rules is sorted and the
029 * rules are arranged so that the rule for <i>b = 3</i> appears <em>before</em>
030 * the rule for <i>a = b + 1</i>.  Similarly, if dependencies of this
031 * sort exist in the list of initial assignments in the model, the initial
032 * assignments are sorted as well.
033 <p>
034 * Beginning with SBML Level 2, assignment rules have no ordering
035 * required&mdash;the order in which the rules appear in an SBML file has
036 * no significance.  Software tools, however, may need to reorder
037 * assignments for purposes of evaluating them.  For example, for
038 * simulators that use time integration methods, it would be a good idea to
039 * reorder assignment rules such as the following,
040 <p>
041 * <i>b = a + 10 seconds</i><br>
042 * <i>a = time</i>
043 <p>
044 * so that the evaluation of the rules is independent of integrator
045 * step sizes. (This is due to the fact that, in this case, the order in
046 * which the rules are evaluated changes the result.)  {@link SBMLRuleConverter}
047 * can be used to reorder the SBML objects regardless of whether the
048 * input file contained them in the desired order.
049 <p>
050 * Note that the two sets of SBML assignments (list of assignment rules on
051 * the one hand, and list of initial assignments on the other hand) are
052 * handled <em>independently</em>.  In an SBML model, these entities are treated
053 * differently and no amount of sorting can deal with inter-dependencies
054 * between assignments of the two kinds.
055<p>
056 * <h2>Configuration and use of {@link SBMLRuleConverter}</h2>
057 <p>
058 * {@link SBMLRuleConverter} is enabled by creating a {@link ConversionProperties} object
059 * with the option <code>'sortRules'</code>, and passing this properties object to
060 * {@link SBMLDocument#convert(ConversionProperties)}.  This
061 * converter offers no other options.
062 <p>
063 * <p>
064 * <h2>General information about the use of SBML converters</h2>
065 <p>
066 * The use of all the converters follows a similar approach.  First, one
067 * creates a {@link ConversionProperties} object and calls
068 * {@link ConversionProperties#addOption(ConversionOption)}
069 * on this object with one argument: a text string that identifies the desired
070 * converter.  (The text string is specific to each converter; consult the
071 * documentation for a given converter to find out how it should be enabled.)
072 <p>
073 * Next, for some converters, the caller can optionally set some
074 * converter-specific properties using additional calls to
075 * {@link ConversionProperties#addOption(ConversionOption)}.
076 * Many converters provide the ability to
077 * configure their behavior to some extent; this is realized through the use
078 * of properties that offer different options.  The default property values
079 * for each converter can be interrogated using the method
080 * {@link SBMLConverter#getDefaultProperties()} on the converter class in question .
081 <p>
082 * Finally, the caller should invoke the method
083 * {@link SBMLDocument#convert(ConversionProperties)}
084 * with the {@link ConversionProperties} object as an argument.
085 <p>
086 * <h3>Example of invoking an SBML converter</h3>
087 <p>
088 * The following code fragment illustrates an example using
089 * {@link SBMLReactionConverter}, which is invoked using the option string
090 * <code>'replaceReactions':</code>
091 <p>
092<pre class='fragment'>
093{@link ConversionProperties} props = new {@link ConversionProperties}();
094if (props != null) {
095  props.addOption('replaceReactions');
096} else {
097  // Deal with error.
098}
099</pre>
100<p>
101 * In the case of {@link SBMLReactionConverter}, there are no options to affect
102 * its behavior, so the next step is simply to invoke the converter on
103 * an {@link SBMLDocument} object.  Continuing the example code:
104 <p>
105<pre class='fragment'>
106  // Assume that the variable 'document' has been set to an {@link SBMLDocument} object.
107  status = document.convert(config);
108  if (status != libsbml.LIBSBML_OPERATION_SUCCESS)
109  {
110    // Handle error somehow.
111    System.out.println('Error: conversion failed due to the following:');
112    document.printErrors();
113  }
114</pre>
115<p>
116 * Here is an example of using a converter that offers an option. The
117 * following code invokes {@link SBMLStripPackageConverter} to remove the
118 * SBML Level&nbsp;3 <em>Layout</em> package from a model.  It sets the name
119 * of the package to be removed by adding a value for the option named
120 * <code>'package'</code> defined by that converter:
121 <p>
122<pre class='fragment'>
123{@link ConversionProperties} config = new {@link ConversionProperties}();
124if (config != None) {
125  config.addOption('stripPackage');
126  config.addOption('package', 'layout');
127  status = document.convert(config);
128  if (status != LIBSBML_OPERATION_SUCCESS) {
129    // Handle error somehow.
130    System.out.println('Error: unable to strip the {@link Layout} package');
131    document.printErrors();
132  }
133} else {
134  // Handle error somehow.
135  System.out.println('Error: unable to create {@link ConversionProperties} object');
136}
137</pre>
138<p>
139 * <h3>Available SBML converters in libSBML</h3>
140 <p>
141 * LibSBML provides a number of built-in converters; by convention, their
142 * names end in <em>Converter</em>. The following are the built-in converters
143 * provided by libSBML 5.16.0
144:
145 <p>
146 * <p>
147 * <ul>
148 * <li> ArraysFlatteningConverter
149 * <li> {@link CobraToFbcConverter}
150 * <li> {@link CompFlatteningConverter}
151 * <li> {@link FbcToCobraConverter}
152 * <li> {@link FbcV1ToV2Converter}
153 * <li> {@link FbcV2ToV1Converter}
154 * <li> {@link SBMLFunctionDefinitionConverter}
155 * <li> {@link SBMLIdConverter}
156 * <li> {@link SBMLInferUnitsConverter}
157 * <li> {@link SBMLInitialAssignmentConverter}
158 * <li> {@link SBMLLevel1Version1Converter}
159 * <li> {@link SBMLLevelVersionConverter}
160 * <li> {@link SBMLLocalParameterConverter}
161 * <li> SBMLRateOfConverter
162 * <li> {@link SBMLReactionConverter}
163 * <li> {@link SBMLRuleConverter}
164 * <li> {@link SBMLStripPackageConverter}
165 * <li> {@link SBMLUnitsConverter}
166 *
167 * </ul>
168 */
169
170public class SBMLRuleConverter extends SBMLConverter {
171   private long swigCPtr;
172
173   protected SBMLRuleConverter(long cPtr, boolean cMemoryOwn)
174   {
175     super(libsbmlJNI.SBMLRuleConverter_SWIGUpcast(cPtr), cMemoryOwn);
176     swigCPtr = cPtr;
177   }
178
179   protected static long getCPtr(SBMLRuleConverter obj)
180   {
181     return (obj == null) ? 0 : obj.swigCPtr;
182   }
183
184   protected static long getCPtrAndDisown (SBMLRuleConverter obj)
185   {
186     long ptr = 0;
187
188     if (obj != null)
189     {
190       ptr             = obj.swigCPtr;
191       obj.swigCMemOwn = false;
192     }
193
194     return ptr;
195   }
196
197  protected void finalize() {
198    delete();
199  }
200
201  public synchronized void delete() {
202    if (swigCPtr != 0) {
203      if (swigCMemOwn) {
204        swigCMemOwn = false;
205        libsbmlJNI.delete_SBMLRuleConverter(swigCPtr);
206      }
207      swigCPtr = 0;
208    }
209    super.delete();
210  }
211
212  
213/** * @internal */ public
214 static void init() {
215    libsbmlJNI.SBMLRuleConverter_init();
216  }
217
218  
219/**
220   * Creates a new {@link SBMLLevelVersionConverter} object.
221   */ public
222 SBMLRuleConverter() {
223    this(libsbmlJNI.new_SBMLRuleConverter__SWIG_0(), true);
224  }
225
226  
227/**
228   * Copy constructor; creates a copy of an {@link SBMLLevelVersionConverter}
229   * object.
230   <p>
231   * @param obj the {@link SBMLLevelVersionConverter} object to copy.
232   */ public
233 SBMLRuleConverter(SBMLRuleConverter obj) {
234    this(libsbmlJNI.new_SBMLRuleConverter__SWIG_1(SBMLRuleConverter.getCPtr(obj), obj), true);
235  }
236
237  
238/**
239   * Creates and returns a deep copy of this {@link SBMLLevelVersionConverter}
240   * object.
241   <p>
242   * @return a (deep) copy of this converter.
243   */ public
244 SBMLConverter cloneObject() {
245    long cPtr = libsbmlJNI.SBMLRuleConverter_cloneObject(swigCPtr, this);
246    return (cPtr == 0) ? null : new SBMLRuleConverter(cPtr, true);
247  }
248
249  
250/**
251   * Returns <code>true</code> if this converter object's properties match the given
252   * properties.
253   <p>
254   * A typical use of this method involves creating a {@link ConversionProperties}
255   * object, setting the options desired, and then calling this method on
256   * an {@link SBMLLevelVersionConverter} object to find out if the object's
257   * property values match the given ones.  This method is also used by
258   * {@link SBMLConverterRegistry#getConverterFor(ConversionProperties)}
259   * to search across all registered converters for one matching particular
260   * properties.
261   <p>
262   * @param props the properties to match.
263   <p>
264   * @return <code>true</code> if this converter's properties match, <code>false</code>
265   * otherwise.
266   */ public
267 boolean matchesProperties(ConversionProperties props) {
268    return libsbmlJNI.SBMLRuleConverter_matchesProperties(swigCPtr, this, ConversionProperties.getCPtr(props), props);
269  }
270
271  
272/**
273   * Perform the conversion.
274   <p>
275   * This method causes the converter to do the actual conversion work,
276   * that is, to convert the {@link SBMLDocument} object set by
277   * {@link SBMLConverter#setDocument(SBMLDocument)} and
278   * with the configuration options set by
279   * {@link SBMLConverter#setProperties(ConversionProperties)}.
280   <p>
281   * <p>
282 * @return integer value indicating success/failure of the
283 * function.   The possible values
284 * returned by this function are:
285   * <ul>
286   * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS}
287   * <li> {@link libsbmlConstants#LIBSBML_INVALID_OBJECT LIBSBML_INVALID_OBJECT}
288   * <li> {@link libsbmlConstants#LIBSBML_CONV_INVALID_SRC_DOCUMENT LIBSBML_CONV_INVALID_SRC_DOCUMENT}
289   * </ul>
290   */ public
291 int convert() {
292    return libsbmlJNI.SBMLRuleConverter_convert(swigCPtr, this);
293  }
294
295  
296/**
297   * Returns the default properties of this converter.
298   <p>
299   * A given converter exposes one or more properties that can be adjusted
300   * in order to influence the behavior of the converter.  This method
301   * returns the <em>default</em> property settings for this converter.  It is
302   * meant to be called in order to discover all the settings for the
303   * converter object.
304   <p>
305   * @return the {@link ConversionProperties} object describing the default properties
306   * for this converter.
307   */ public
308 ConversionProperties getDefaultProperties() {
309    return new ConversionProperties(libsbmlJNI.SBMLRuleConverter_getDefaultProperties(swigCPtr, this), true);
310  }
311
312}