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