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