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