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 *  Base class for SBML converters.
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 * The {@link SBMLConverter} class is the base class for the various SBML 
022 * <em>converters</em>: classes of objects that transform or convert SBML documents.
023 * These transformations can involve essentially anything that can be
024 * written algorithmically; examples include converting the units of
025 * measurement in a model, or converting from one Level+Version combination
026 * of SBML to another.
027 <p>
028 * LibSBML provides a number of built-in converters, and applications can
029 * create their own by subclassing {@link SBMLConverter} and following the examples
030 * of the existing converters.  The following are the built-in converters
031 * in libSBML 5.10.0
032:
033 * <ul>
034 * <li> {@link SBMLFunctionDefinitionConverter}
035 * <li> {@link SBMLInitialAssignmentConverter}
036 * <li> {@link SBMLLevelVersionConverter}
037 * <li> {@link SBMLRuleConverter}
038 * <li> {@link SBMLStripPackageConverter}
039 * <li> {@link SBMLUnitsConverter}
040 *
041 * </ul> <p>
042 * Many converters provide the ability to configure their behavior to some
043 * extent.  This is realized through the use of <em>properties</em> that offer
044 * different <em>options</em>.  Two related classes implement these features:
045 * {@link ConversionProperties} and ConversionOptions.  The default property values
046 * for each converter can be interrogated using the method
047 * {@link SBMLConverter#getDefaultProperties()} on the converter class.
048 */
049
050public class SBMLConverter {
051   private long swigCPtr;
052   protected boolean swigCMemOwn;
053
054   protected SBMLConverter(long cPtr, boolean cMemoryOwn)
055   {
056     swigCMemOwn = cMemoryOwn;
057     swigCPtr    = cPtr;
058   }
059
060   protected static long getCPtr(SBMLConverter obj)
061   {
062     return (obj == null) ? 0 : obj.swigCPtr;
063   }
064
065   protected static long getCPtrAndDisown (SBMLConverter obj)
066   {
067     long ptr = 0;
068
069     if (obj != null)
070     {
071       ptr             = obj.swigCPtr;
072       obj.swigCMemOwn = false;
073     }
074
075     return ptr;
076   }
077
078  protected void finalize() {
079    delete();
080  }
081
082  public synchronized void delete() {
083    if (swigCPtr != 0) {
084      if (swigCMemOwn) {
085        swigCMemOwn = false;
086        libsbmlJNI.delete_SBMLConverter(swigCPtr);
087      }
088      swigCPtr = 0;
089    }
090  }
091
092  protected void swigDirectorDisconnect() {
093    swigCMemOwn = false;
094    delete();
095  }
096
097  public void swigReleaseOwnership() {
098    swigCMemOwn = false;
099    libsbmlJNI.SBMLConverter_change_ownership(this, swigCPtr, false);
100  }
101
102  public void swigTakeOwnership() {
103    swigCMemOwn = true;
104    libsbmlJNI.SBMLConverter_change_ownership(this, swigCPtr, true);
105  }
106
107  
108/**
109   * Creates a new {@link SBMLConverter} object.
110   */ public
111 SBMLConverter() {
112    this(libsbmlJNI.new_SBMLConverter__SWIG_0(), true);
113    libsbmlJNI.SBMLConverter_director_connect(this, swigCPtr, swigCMemOwn, true);
114  }
115
116  
117/**
118   * Copy constructor; creates a copy of an {@link SBMLConverter} object.
119   <p>
120   * @param c the {@link SBMLConverter} object to copy.
121   <p>
122   * @throws SBMLConstructorException 
123   * Thrown if the argument <code>orig</code> is <code>null.</code>
124   */ public
125 SBMLConverter(SBMLConverter c) {
126    this(libsbmlJNI.new_SBMLConverter__SWIG_1(SBMLConverter.getCPtr(c), c), true);
127    libsbmlJNI.SBMLConverter_director_connect(this, swigCPtr, swigCMemOwn, true);
128  }
129
130  
131/**
132   * Creates and returns a deep copy of this {@link SBMLConverter} object.
133   <p>
134   * @return a (deep) copy of this {@link SBMLConverter} object.
135   */ public
136 SBMLConverter cloneObject() {
137    long cPtr = (getClass() == SBMLConverter.class) ? libsbmlJNI.SBMLConverter_cloneObject(swigCPtr, this) : libsbmlJNI.SBMLConverter_cloneObjectSwigExplicitSBMLConverter(swigCPtr, this);
138    return (cPtr == 0) ? null : new SBMLConverter(cPtr, true);
139  }
140
141  
142/**
143   * Returns the SBML document that is the subject of the conversions.
144   <p>
145   * @return the current {@link SBMLDocument} object.
146   */ public
147 SBMLDocument getDocument() {
148    long cPtr = (getClass() == SBMLConverter.class) ? libsbmlJNI.SBMLConverter_getDocument__SWIG_0(swigCPtr, this) : libsbmlJNI.SBMLConverter_getDocumentSwigExplicitSBMLConverter__SWIG_0(swigCPtr, this);
149    return (cPtr == 0) ? null : new SBMLDocument(cPtr, false);
150  }
151
152  
153/**
154   * Returns the default properties of this converter.
155   <p>
156   * A given converter exposes one or more properties that can be adjusted
157   * in order to influence the behavior of the converter.  This method
158   * returns the <em>default</em> property settings for this converter.  It is
159   * meant to be called in order to discover all the settings for the
160   * converter object.  The run-time properties of the converter object can
161   * be adjusted by using the method
162   * {@link SBMLConverter#setProperties(ConversionProperties props)}.
163   <p>
164   * @return the default properties for the converter.
165   <p>
166   * @see #setProperties(ConversionProperties props)
167   * @see #matchesProperties(ConversionProperties props)
168   */ public
169 ConversionProperties getDefaultProperties() {
170    return new ConversionProperties((getClass() == SBMLConverter.class) ? libsbmlJNI.SBMLConverter_getDefaultProperties(swigCPtr, this) : libsbmlJNI.SBMLConverter_getDefaultPropertiesSwigExplicitSBMLConverter(swigCPtr, this), true);
171  }
172
173  
174/**
175   * Returns the target SBML namespaces of the currently set properties.
176   <p>
177   * SBML namespaces are used by libSBML to express the Level+Version of
178   * the SBML document (and, possibly, any SBML Level&nbsp;3 packages in
179   * use). Some converters' behavior is affected by the SBML namespace
180   * configured in the converter.  For example, the actions of
181   * {@link SBMLLevelVersionConverter}, the converter for converting SBML documents
182   * from one Level+Version combination to another, are fundamentally
183   * dependent on the SBML namespaces being targeted.
184   <p>
185   * @return the {@link SBMLNamespaces} object that describes the SBML namespaces
186   * in effect.
187   */ public
188 SBMLNamespaces getTargetNamespaces() {
189  return libsbml.DowncastSBMLNamespaces((getClass() == SBMLConverter.class) ? libsbmlJNI.SBMLConverter_getTargetNamespaces(swigCPtr, this) : libsbmlJNI.SBMLConverter_getTargetNamespacesSwigExplicitSBMLConverter(swigCPtr, this), false);
190}
191
192  
193/**
194   * Predicate returning <code>true</code> if this converter's properties matches a
195   * given set of configuration properties.
196   <p>
197   * @param props the configuration properties to match.
198   <p>
199   * @return <code>true</code> if this converter's properties match, <code>false</code>
200   * otherwise.
201   */ public
202 boolean matchesProperties(ConversionProperties props) {
203    return (getClass() == SBMLConverter.class) ? libsbmlJNI.SBMLConverter_matchesProperties(swigCPtr, this, ConversionProperties.getCPtr(props), props) : libsbmlJNI.SBMLConverter_matchesPropertiesSwigExplicitSBMLConverter(swigCPtr, this, ConversionProperties.getCPtr(props), props);
204  }
205
206  
207/**
208   * Sets the current SBML document to the given {@link SBMLDocument} object.
209   <p>
210   * @param doc the document to use for this conversion.
211   <p>
212   * @warning Even though the <code>doc</code> is 'const', it is immediately cast 
213   * to a non-const version, which is then usually changed by the 
214   * converter upon a successful conversion.  This function is here 
215   * solely to preserve backwards compatibility.
216   <p>
217   * @return integer value indicating the success/failure of the operation.
218   *  The set of possible values that may
219   * be returned ultimately depends on the specific subclass of
220   * {@link SBMLConverter} being used, but the default method can return the
221   * following values:
222   * <ul>
223   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS }
224   * </ul>
225   */ public
226 int setDocument(SBMLDocument doc) {
227    return (getClass() == SBMLConverter.class) ? libsbmlJNI.SBMLConverter_setDocument__SWIG_0(swigCPtr, this, SBMLDocument.getCPtr(doc), doc) : libsbmlJNI.SBMLConverter_setDocumentSwigExplicitSBMLConverter__SWIG_0(swigCPtr, this, SBMLDocument.getCPtr(doc), doc);
228  }
229
230  
231/**
232   * Sets the configuration properties to be used by this converter.
233   <p>
234   * A given converter exposes one or more properties that can be adjusted
235   * in order to influence the behavior of the converter.  This method sets
236   * the current properties for this converter.
237   <p>
238   * @param props the {@link ConversionProperties} object defining the properties
239   * to set.
240   <p>
241   * @return integer value indicating the success/failure of the operation.
242   *  The set of possible values that may
243   * be returned ultimately depends on the specific subclass of
244   * {@link SBMLConverter} being used, but the default method can return the
245   * following values:
246   * <ul>
247   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS }
248   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED }
249   *
250   * </ul> <p>
251   * @see #getProperties()
252   * @see #matchesProperties(ConversionProperties props)
253   */ public
254 int setProperties(ConversionProperties props) {
255    return (getClass() == SBMLConverter.class) ? libsbmlJNI.SBMLConverter_setProperties(swigCPtr, this, ConversionProperties.getCPtr(props), props) : libsbmlJNI.SBMLConverter_setPropertiesSwigExplicitSBMLConverter(swigCPtr, this, ConversionProperties.getCPtr(props), props);
256  }
257
258  
259/**
260   * Returns the current properties in effect for this converter.
261   <p>
262   * A given converter exposes one or more properties that can be adjusted
263   * in order to influence the behavior of the converter.  This method
264   * returns the current properties for this converter; in other words, the
265   * settings in effect at this moment.  To change the property values, you
266   * can use {@link SBMLConverter#setProperties(ConversionProperties props)}.
267   <p>
268   * @return the currently set configuration properties.
269   <p>
270   * @see #setProperties(ConversionProperties props)
271   * @see #matchesProperties(ConversionProperties props)
272   */ public
273 ConversionProperties getProperties() {
274    long cPtr = (getClass() == SBMLConverter.class) ? libsbmlJNI.SBMLConverter_getProperties(swigCPtr, this) : libsbmlJNI.SBMLConverter_getPropertiesSwigExplicitSBMLConverter(swigCPtr, this);
275    return (cPtr == 0) ? null : new ConversionProperties(cPtr, false);
276  }
277
278  
279/**
280   * Perform the conversion.
281   <p>
282   * This method causes the converter to do the actual conversion work,
283   * that is, to convert the {@link SBMLDocument} object set by
284   * {@link SBMLConverter#setDocument(SBMLDocument doc)} and
285   * with the configuration options set by
286   * {@link SBMLConverter#setProperties(ConversionProperties props)}.
287   <p>
288   * @return  integer value indicating the success/failure of the operation.
289   *  The set of possible values that may
290   * be returned depends on the converter subclass; please consult
291   * the documentation for the relevant class to find out what the
292   * possibilities are.
293   */ public
294 int convert() {
295    return (getClass() == SBMLConverter.class) ? libsbmlJNI.SBMLConverter_convert(swigCPtr, this) : libsbmlJNI.SBMLConverter_convertSwigExplicitSBMLConverter(swigCPtr, this);
296  }
297
298}