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