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