001/* ----------------------------------------------------------------------------
002 * This file was automatically generated by SWIG (http://www.swig.org).
003 * Version 2.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 *  SBML converter for reordering rules and assignments in a
013 * model.
014 <p>
015 * <p style='color: #777; font-style: italic'>
016This class of objects is defined by libSBML only and has no direct
017equivalent in terms of SBML components.  It is a class used in
018the implementation of extra functionality provided by libSBML.
019</p>
020
021 <p>
022 * This converter reorders assignments in a model.  Specifically, it sorts
023 * the list of assignment rules (i.e., the {@link AssignmentRule} objects contained
024 * in the ListOfAssignmentRules within the {@link Model} object) and the initial
025 * assignments (i.e., the {@link InitialAssignment} objects contained in the
026 * {@link ListOfInitialAssignments}) such that, within each set, assignments that
027 * depend on prior values are placed after the values are set.  For
028 * example, if there is an assignment rule stating <i>a = b + 1</i>, and
029 * another rule stating <i>b = 3</i>, the list of rules is sorted and the
030 * rules are arranged so that the rule for <i>b = 3</i> appears <em>before</em>
031 * the rule for <i>a = b + 1</i>.  Similarly, if dependencies of this
032 * sort exist in the list of initial assignments in the model, the initial
033 * assignments are sorted as well.
034 <p>
035 * Beginning with SBML Level 2, assignment rules have no ordering
036 * required&mdash;the order in which the rules appear in an SBML file has
037 * no significance.  Software tools, however, may need to reorder
038 * assignments for purposes of evaluating them.  For example, for
039 * simulators that use time integration methods, it would be a good idea to
040 * reorder assignment rules such as the following,
041 <p>
042 * <i>b = a + 10 seconds</i><br>
043 * <i>a = time</i>
044 <p>
045 * so that the evaluation of the rules is independent of integrator
046 * step sizes. (This is due to the fact that, in this case, the order in
047 * which the rules are evaluated changes the result.)  This converter
048 * can be used to reorder the SBML objects regardless of whether the
049 * input file contained them in the desired order.  Here is a code
050 * fragment to illustrate how to do that:
051 * <div class='fragment'><pre class='fragment'>
052{@link ConversionProperties} props;
053props.addOption('sortRules', true, 'sort rules');
054
055{@link SBMLConverter} converter;
056converter.setProperties(&props);
057converter.setDocument(&doc);
058converter.convert(); 
059</pre></div>
060 <p>
061 * @note The two sets of assignments (list of assignment rules on the one
062 * hand, and list of initial assignments on the other hand) are handled 
063 * <em>independently</em>.  In an SBML model, these entities are treated differently
064 * and no amount of sorting can deal with inter-dependencies between
065 * assignments of the two kinds.
066 <p>
067 * @see SBMLFunctionDefinitionConverter
068 * @see SBMLInitialAssignmentConverter
069 * @see SBMLLevelVersionConverter
070 * @see SBMLStripPackageConverter
071 * @see SBMLUnitsConverter
072 */
073
074public class SBMLRuleConverter extends SBMLConverter {
075   private long swigCPtr;
076
077   protected SBMLRuleConverter(long cPtr, boolean cMemoryOwn)
078   {
079     super(libsbmlJNI.SBMLRuleConverter_SWIGUpcast(cPtr), cMemoryOwn);
080     swigCPtr = cPtr;
081   }
082
083   protected static long getCPtr(SBMLRuleConverter obj)
084   {
085     return (obj == null) ? 0 : obj.swigCPtr;
086   }
087
088   protected static long getCPtrAndDisown (SBMLRuleConverter obj)
089   {
090     long ptr = 0;
091
092     if (obj != null)
093     {
094       ptr             = obj.swigCPtr;
095       obj.swigCMemOwn = false;
096     }
097
098     return ptr;
099   }
100
101  protected void finalize() {
102    delete();
103  }
104
105  public synchronized void delete() {
106    if (swigCPtr != 0) {
107      if (swigCMemOwn) {
108        swigCMemOwn = false;
109        libsbmlJNI.delete_SBMLRuleConverter(swigCPtr);
110      }
111      swigCPtr = 0;
112    }
113    super.delete();
114  }
115
116  public static void init() {
117    libsbmlJNI.SBMLRuleConverter_init();
118  }
119
120  
121/**
122   * Creates a new {@link SBMLLevelVersionConverter} object.
123   */ public
124 SBMLRuleConverter() {
125    this(libsbmlJNI.new_SBMLRuleConverter__SWIG_0(), true);
126  }
127
128  
129/**
130   * Copy constructor; creates a copy of an {@link SBMLLevelVersionConverter}
131   * object.
132   <p>
133   * @param obj the {@link SBMLLevelVersionConverter} object to copy.
134   */ public
135 SBMLRuleConverter(SBMLRuleConverter obj) {
136    this(libsbmlJNI.new_SBMLRuleConverter__SWIG_1(SBMLRuleConverter.getCPtr(obj), obj), true);
137  }
138
139  
140/**
141   * Creates and returns a deep copy of this {@link SBMLLevelVersionConverter}
142   * object.
143   <p>
144   * @return a (deep) copy of this converter.
145   */ public
146 SBMLConverter cloneObject() {
147    long cPtr = libsbmlJNI.SBMLRuleConverter_cloneObject(swigCPtr, this);
148    return (cPtr == 0) ? null : new SBMLConverter(cPtr, true);
149  }
150
151  
152/**
153   * Returns <code>true</code> if this converter object's properties match the given
154   * properties.
155   <p>
156   * A typical use of this method involves creating a {@link ConversionProperties}
157   * object, setting the options desired, and then calling this method on
158   * an {@link SBMLLevelVersionConverter} object to find out if the object's
159   * property values match the given ones.  This method is also used by
160   * {@link SBMLConverterRegistry#getConverterFor(ConversionProperties props)}
161   * to search across all registered converters for one matching particular
162   * properties.
163   <p>
164   * @param props the properties to match.
165   <p>
166   * @return <code>true</code> if this converter's properties match, <code>false</code>
167   * otherwise.
168   */ public
169 boolean matchesProperties(ConversionProperties props) {
170    return libsbmlJNI.SBMLRuleConverter_matchesProperties(swigCPtr, this, ConversionProperties.getCPtr(props), props);
171  }
172
173  
174/** 
175   * Perform the conversion.
176   <p>
177   * This method causes the converter to do the actual conversion work,
178   * that is, to convert the {@link SBMLDocument} object set by
179   * {@link SBMLConverter#setDocument(SBMLDocument doc)} and
180   * with the configuration options set by
181   * {@link SBMLConverter#setProperties(ConversionProperties props)}.
182   <p>
183   * @return  integer value indicating the success/failure of the operation.
184   *  The possible values are:
185   * <ul>
186   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS }
187   * <li> {@link  libsbmlConstants#LIBSBML_INVALID_OBJECT LIBSBML_INVALID_OBJECT }
188   * <li> {@link  libsbmlConstants#LIBSBML_CONV_INVALID_SRC_DOCUMENT LIBSBML_CONV_INVALID_SRC_DOCUMENT }
189   * </ul>
190   */ public
191 int convert() {
192    return libsbmlJNI.SBMLRuleConverter_convert(swigCPtr, this);
193  }
194
195  
196/**
197   * Returns the default properties of this converter.
198   <p>
199   * A given converter exposes one or more properties that can be adjusted
200   * in order to influence the behavior of the converter.  This method
201   * returns the <em>default</em> property settings for this converter.  It is
202   * meant to be called in order to discover all the settings for the
203   * converter object.
204   <p>
205   * @return the {@link ConversionProperties} object describing the default properties
206   * for this converter.
207   */ public
208 ConversionProperties getDefaultProperties() {
209    return new ConversionProperties(libsbmlJNI.SBMLRuleConverter_getDefaultProperties(swigCPtr, this), true);
210  }
211
212}