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 * 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 written 024 * algorithmically; examples include converting the units of measurement in a 025 * model, or converting from one Level+Version combination of SBML to 026 * another. Applications can also create their own converters by subclassing 027 * {@link SBMLConverter} and following the examples of the existing converters. 028 <p> 029 * <p> 030 * <h2>General information about the use of SBML converters</h2> 031 <p> 032 * The use of all the converters follows a similar approach. First, one 033 * creates a {@link ConversionProperties} object and calls 034 * {@link ConversionProperties#addOption(ConversionOption)} 035 * on this object with one argument: a text string that identifies the desired 036 * converter. (The text string is specific to each converter; consult the 037 * documentation for a given converter to find out how it should be enabled.) 038 <p> 039 * Next, for some converters, the caller can optionally set some 040 * converter-specific properties using additional calls to 041 * {@link ConversionProperties#addOption(ConversionOption)}. 042 * Many converters provide the ability to 043 * configure their behavior to some extent; this is realized through the use 044 * of properties that offer different options. The default property values 045 * for each converter can be interrogated using the method 046 * {@link SBMLConverter#getDefaultProperties()} on the converter class in question . 047 <p> 048 * Finally, the caller should invoke the method 049 * {@link SBMLDocument#convert(ConversionProperties)} 050 * with the {@link ConversionProperties} object as an argument. 051 <p> 052 * <h3>Example of invoking an SBML converter</h3> 053 <p> 054 * The following code fragment illustrates an example using 055 * {@link SBMLReactionConverter}, which is invoked using the option string 056 * <code>'replaceReactions':</code> 057 <p> 058<pre class='fragment'> 059{@link ConversionProperties} props = new {@link ConversionProperties}(); 060if (props != null) { 061 props.addOption('replaceReactions'); 062} else { 063 // Deal with error. 064} 065</pre> 066<p> 067 * In the case of {@link SBMLReactionConverter}, there are no options to affect 068 * its behavior, so the next step is simply to invoke the converter on 069 * an {@link SBMLDocument} object. Continuing the example code: 070 <p> 071<pre class='fragment'> 072 // Assume that the variable 'document' has been set to an {@link SBMLDocument} object. 073 status = document.convert(config); 074 if (status != libsbml.LIBSBML_OPERATION_SUCCESS) 075 { 076 // Handle error somehow. 077 System.out.println('Error: conversion failed due to the following:'); 078 document.printErrors(); 079 } 080</pre> 081<p> 082 * Here is an example of using a converter that offers an option. The 083 * following code invokes {@link SBMLStripPackageConverter} to remove the 084 * SBML Level 3 <em>Layout</em> package from a model. It sets the name 085 * of the package to be removed by adding a value for the option named 086 * <code>'package'</code> defined by that converter: 087 <p> 088<pre class='fragment'> 089{@link ConversionProperties} config = new {@link ConversionProperties}(); 090if (config != None) { 091 config.addOption('stripPackage'); 092 config.addOption('package', 'layout'); 093 status = document.convert(config); 094 if (status != LIBSBML_OPERATION_SUCCESS) { 095 // Handle error somehow. 096 System.out.println('Error: unable to strip the {@link Layout} package'); 097 document.printErrors(); 098 } 099} else { 100 // Handle error somehow. 101 System.out.println('Error: unable to create {@link ConversionProperties} object'); 102} 103</pre> 104<p> 105 * <h3>Available SBML converters in libSBML</h3> 106 <p> 107 * LibSBML provides a number of built-in converters; by convention, their 108 * names end in <em>Converter</em>. The following are the built-in converters 109 * provided by libSBML 5.15.2 110: 111 <p> 112 * <p> 113 * <ul> 114 * <li> ArraysFlatteningConverter 115 * <li> {@link CobraToFbcConverter} 116 * <li> {@link CompFlatteningConverter} 117 * <li> {@link FbcToCobraConverter} 118 * <li> {@link FbcV1ToV2Converter} 119 * <li> {@link FbcV2ToV1Converter} 120 * <li> {@link SBMLFunctionDefinitionConverter} 121 * <li> {@link SBMLIdConverter} 122 * <li> {@link SBMLInferUnitsConverter} 123 * <li> {@link SBMLInitialAssignmentConverter} 124 * <li> {@link SBMLLevel1Version1Converter} 125 * <li> {@link SBMLLevelVersionConverter} 126 * <li> {@link SBMLLocalParameterConverter} 127 * <li> SBMLRateOfConverter 128 * <li> {@link SBMLReactionConverter} 129 * <li> {@link SBMLRuleConverter} 130 * <li> {@link SBMLStripPackageConverter} 131 * <li> {@link SBMLUnitsConverter} 132 * 133 * </ul> 134 */ 135 136public class SBMLConverter { 137 private long swigCPtr; 138 protected boolean swigCMemOwn; 139 140 protected SBMLConverter(long cPtr, boolean cMemoryOwn) 141 { 142 swigCMemOwn = cMemoryOwn; 143 swigCPtr = cPtr; 144 } 145 146 protected static long getCPtr(SBMLConverter obj) 147 { 148 return (obj == null) ? 0 : obj.swigCPtr; 149 } 150 151 protected static long getCPtrAndDisown (SBMLConverter obj) 152 { 153 long ptr = 0; 154 155 if (obj != null) 156 { 157 ptr = obj.swigCPtr; 158 obj.swigCMemOwn = false; 159 } 160 161 return ptr; 162 } 163 164 protected void finalize() { 165 delete(); 166 } 167 168 public synchronized void delete() { 169 if (swigCPtr != 0) { 170 if (swigCMemOwn) { 171 swigCMemOwn = false; 172 libsbmlJNI.delete_SBMLConverter(swigCPtr); 173 } 174 swigCPtr = 0; 175 } 176 } 177 178 protected void swigDirectorDisconnect() { 179 swigCMemOwn = false; 180 delete(); 181 } 182 183 public void swigReleaseOwnership() { 184 swigCMemOwn = false; 185 libsbmlJNI.SBMLConverter_change_ownership(this, swigCPtr, false); 186 } 187 188 public void swigTakeOwnership() { 189 swigCMemOwn = true; 190 libsbmlJNI.SBMLConverter_change_ownership(this, swigCPtr, true); 191 } 192 193 194/** 195 * Creates a new {@link SBMLConverter} object. 196 */ public 197 SBMLConverter() { 198 this(libsbmlJNI.new_SBMLConverter__SWIG_0(), true); 199 libsbmlJNI.SBMLConverter_director_connect(this, swigCPtr, swigCMemOwn, true); 200 } 201 202 203/** 204 * Creates a new {@link SBMLConverter} object with a given name. 205 <p> 206 * @param name the name for the converter to create. 207 */ public 208 SBMLConverter(String name) { 209 this(libsbmlJNI.new_SBMLConverter__SWIG_1(name), true); 210 libsbmlJNI.SBMLConverter_director_connect(this, swigCPtr, swigCMemOwn, true); 211 } 212 213 214/** 215 * Copy constructor. 216 <p> 217 * This creates a copy of an {@link SBMLConverter} object. 218 <p> 219 * @param orig the {@link SBMLConverter} object to copy. 220 */ public 221 SBMLConverter(SBMLConverter orig) { 222 this(libsbmlJNI.new_SBMLConverter__SWIG_2(SBMLConverter.getCPtr(orig), orig), true); 223 libsbmlJNI.SBMLConverter_director_connect(this, swigCPtr, swigCMemOwn, true); 224 } 225 226 227/** 228 * Creates and returns a deep copy of this {@link SBMLConverter} object. 229 <p> 230 * @return the (deep) copy of this {@link SBMLConverter} object. 231 */ public 232 SBMLConverter cloneObject() { 233 return libsbml.DowncastSBMLConverter((getClass() == SBMLConverter.class) ? libsbmlJNI.SBMLConverter_cloneObject(swigCPtr, this) : libsbmlJNI.SBMLConverter_cloneObjectSwigExplicitSBMLConverter(swigCPtr, this), true); 234} 235 236 237/** 238 * Returns the SBML document that is the subject of the conversions. 239 <p> 240 * @return the current {@link SBMLDocument} object. 241 */ public 242 SBMLDocument getDocument() { 243 long cPtr = (getClass() == SBMLConverter.class) ? libsbmlJNI.SBMLConverter_getDocument__SWIG_0(swigCPtr, this) : libsbmlJNI.SBMLConverter_getDocumentSwigExplicitSBMLConverter__SWIG_0(swigCPtr, this); 244 return (cPtr == 0) ? null : new SBMLDocument(cPtr, false); 245 } 246 247 248/** 249 * Returns the default properties of this converter. 250 <p> 251 * A given converter exposes one or more properties that can be adjusted 252 * in order to influence the behavior of the converter. This method 253 * returns the <em>default</em> property settings for this converter. It is 254 * meant to be called in order to discover all the settings for the 255 * converter object. The run-time properties of the converter object can 256 * be adjusted by using the method 257 * {@link SBMLConverter#setProperties(ConversionProperties props)}. 258 <p> 259 * @return the default properties for the converter. 260 <p> 261 * @see #setProperties(ConversionProperties) 262 * @see #matchesProperties(ConversionProperties) 263 */ public 264 ConversionProperties getDefaultProperties() { 265 return new ConversionProperties((getClass() == SBMLConverter.class) ? libsbmlJNI.SBMLConverter_getDefaultProperties(swigCPtr, this) : libsbmlJNI.SBMLConverter_getDefaultPropertiesSwigExplicitSBMLConverter(swigCPtr, this), true); 266 } 267 268 269/** 270 * Returns the target SBML namespaces of the currently set properties. 271 <p> 272 * SBML namespaces are used by libSBML to express the Level+Version of the 273 * SBML document (and, possibly, any SBML Level 3 packages in 274 * use). Some converters' behavior is affected by the SBML namespace 275 * configured in the converter. For example, in {@link SBMLLevelVersionConverter} 276 * (the converter for converting SBML documents from one Level+Version 277 * combination to another), the actions are fundamentally dependent on the 278 * SBML namespaces targeted. 279 <p> 280 * @return the {@link SBMLNamespaces} object that describes the SBML namespaces 281 * in effect, or <code>null</code> if none are set. 282 */ public 283 SBMLNamespaces getTargetNamespaces() { 284 return libsbml.DowncastSBMLNamespaces((getClass() == SBMLConverter.class) ? libsbmlJNI.SBMLConverter_getTargetNamespaces(swigCPtr, this) : libsbmlJNI.SBMLConverter_getTargetNamespacesSwigExplicitSBMLConverter(swigCPtr, this), false); 285} 286 287 288/** 289 * Returns <code>true</code> if this converter matches the given properties. 290 <p> 291 * Given a {@link ConversionProperties} object <code>props</code>, this method checks that 292 * <code>props</code> possesses an option value to enable this converter. If it does, 293 * this method returns <code>true.</code> 294 <p> 295 * @param props the properties to match. 296 <p> 297 * @return <code>true</code> if the properties <code>props</code> would match the necessary 298 * properties for this type of converter, <code>false</code> otherwise. 299 */ public 300 boolean matchesProperties(ConversionProperties props) { 301 return (getClass() == SBMLConverter.class) ? libsbmlJNI.SBMLConverter_matchesProperties(swigCPtr, this, ConversionProperties.getCPtr(props), props) : libsbmlJNI.SBMLConverter_matchesPropertiesSwigExplicitSBMLConverter(swigCPtr, this, ConversionProperties.getCPtr(props), props); 302 } 303 304 305/** 306 * Sets the SBML document to be converted. 307 <p> 308 * @param doc the document to use for this conversion. 309 <p> 310 * @return integer value indicating the success/failure of the operation. 311 * The set of possible values that may 312 * be returned ultimately depends on the specific subclass of 313 * {@link SBMLConverter} being used, but the default method can return the 314 * following: 315 * <ul> 316 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 317 * </ul> 318 */ public 319 int setDocument(SBMLDocument doc) { 320 return (getClass() == SBMLConverter.class) ? libsbmlJNI.SBMLConverter_setDocument(swigCPtr, this, SBMLDocument.getCPtr(doc), doc) : libsbmlJNI.SBMLConverter_setDocumentSwigExplicitSBMLConverter(swigCPtr, this, SBMLDocument.getCPtr(doc), doc); 321 } 322 323 324/** 325 * Sets the configuration properties to be used by this converter. 326 <p> 327 * @param props the {@link ConversionProperties} object defining the properties 328 * to set. 329 <p> 330 * @return integer value indicating the success/failure of the operation. 331 * The set of possible values that may 332 * be returned ultimately depends on the specific subclass of 333 * {@link SBMLConverter} being used, but the default method can return the 334 * following values: 335 * <ul> 336 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 337 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED} 338 * 339 * </ul> <p> 340 * @see #getProperties() 341 * @see #matchesProperties(ConversionProperties) 342 */ public 343 int setProperties(ConversionProperties props) { 344 return (getClass() == SBMLConverter.class) ? libsbmlJNI.SBMLConverter_setProperties(swigCPtr, this, ConversionProperties.getCPtr(props), props) : libsbmlJNI.SBMLConverter_setPropertiesSwigExplicitSBMLConverter(swigCPtr, this, ConversionProperties.getCPtr(props), props); 345 } 346 347 348/** 349 * Returns the current properties in effect for this converter. 350 <p> 351 * A given converter exposes one or more properties that can be adjusted 352 * in order to influence the behavior of the converter. This method 353 * returns the current properties for this converter; in other words, the 354 * settings in effect at this moment. To change the property values, you 355 * can use {@link SBMLConverter#setProperties(ConversionProperties props)}. 356 <p> 357 * @return the currently set configuration properties. 358 <p> 359 * @see #setProperties(ConversionProperties) 360 * @see #matchesProperties(ConversionProperties) 361 */ public 362 ConversionProperties getProperties() { 363 long cPtr = (getClass() == SBMLConverter.class) ? libsbmlJNI.SBMLConverter_getProperties(swigCPtr, this) : libsbmlJNI.SBMLConverter_getPropertiesSwigExplicitSBMLConverter(swigCPtr, this); 364 return (cPtr == 0) ? null : new ConversionProperties(cPtr, false); 365 } 366 367 368/** 369 * Perform the conversion. 370 <p> 371 * This method causes the converter to do the actual conversion work, 372 * that is, to convert the {@link SBMLDocument} object set by 373 * {@link SBMLConverter#setDocument(SBMLDocument)} and 374 * with the configuration options set by 375 * {@link SBMLConverter#setProperties(ConversionProperties)}. 376 <p> 377 * @return integer value indicating the success/failure of the operation. 378 * The set of possible values that may 379 * be returned depends on the converter subclass; please consult 380 * the documentation for the relevant class to find out what the 381 * possibilities are. 382 */ public 383 int convert() { 384 return (getClass() == SBMLConverter.class) ? libsbmlJNI.SBMLConverter_convert(swigCPtr, this) : libsbmlJNI.SBMLConverter_convertSwigExplicitSBMLConverter(swigCPtr, this); 385 } 386 387 388/** 389 * Returns the name of this converter. 390 <p> 391 * @return a string, the name of this converter. 392 */ public 393 String getName() { 394 return libsbmlJNI.SBMLConverter_getName(swigCPtr, this); 395 } 396 397}