001/* ---------------------------------------------------------------------------- 002 * This file was automatically generated by SWIG (http://www.swig.org). 003 * Version 3.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 * Whole-document SBML Level/Version converter. 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 having one SBML Level+Version 022 * combination, and attempts to convert it to an SBML document having a 023 * different Level+Version combination. 024 <p> 025 * This class is also the basis for 026 * {@link SBMLDocument#setLevelAndVersion(long, long, boolean)}. 027 <p> 028 * <h2>Configuration and use of {@link SBMLLevelVersionConverter}</h2> 029 <p> 030 * {@link SBMLLevelVersionConverter} is enabled by creating a {@link ConversionProperties} 031 * object with the option <code>'setLevelAndVersion'</code>, and passing this 032 * properties object to {@link SBMLDocument#convert(ConversionProperties)}. The target SBML Level and Version 033 * combination are determined by the value of the SBML namespace set on the 034 * {@link ConversionProperties} object (using 035 * {@link ConversionProperties#setTargetNamespaces(SBMLNamespaces targetNS)}). 036 <p> 037 * In addition, this converter offers the following options: 038 <p> 039 * <ul> 040 * <li> <code>'strict':</code> If this option has the value <code>true</code>, then the validity 041 * of the SBML document will be strictly preserved. This means that SBML 042 * validation will be performed, and if the original model is not valid or 043 * semantics cannot be preserved in the converted model, then conversion will 044 * not be performed. Conversely, if this option is set to <code>false</code>, model 045 * conversion will always be performed; if any errors are detected related to 046 * altered semantics, the errors will be logged in the usual way (i.e., the 047 * error log on the {@link SBMLDocument} object). 048 <p> 049 * <li> <code>'addDefaultUnits':</code> By default, a conversion from SBML Level 2 050 * to Level 3 will explicitly add {@link UnitDefinition} objects and unit 051 * attributes on the {@link Model} object to define units that are implicitly defined 052 * in SBML Level 2. This is usually desirable because in SBML 053 * Level 3, there are no default units and a conversion from 054 * Level 2 that did <em>not</em> add unit definitions would actually result 055 * in a loss of information. However, some users or software tools may not 056 * need or want this, or worse, may be fooled into thinking that libSBML has 057 * somehow inferred the proper units for model quantities. (It has not; it 058 * merely adds generic predefined units.) This option lets callers control 059 * this behavior. 060 * 061 * </ul> <p> 062 * <p> 063 * <h2>General information about the use of SBML converters</h2> 064 <p> 065 * The use of all the converters follows a similar approach. First, one 066 * creates a {@link ConversionProperties} object and calls 067 * {@link ConversionProperties#addOption(ConversionOption)} 068 * on this object with one argument: a text string that identifies the desired 069 * converter. (The text string is specific to each converter; consult the 070 * documentation for a given converter to find out how it should be enabled.) 071 <p> 072 * Next, for some converters, the caller can optionally set some 073 * converter-specific properties using additional calls to 074 * {@link ConversionProperties#addOption(ConversionOption)}. 075 * Many converters provide the ability to 076 * configure their behavior to some extent; this is realized through the use 077 * of properties that offer different options. The default property values 078 * for each converter can be interrogated using the method 079 * {@link SBMLConverter#getDefaultProperties()} on the converter class in question . 080 <p> 081 * Finally, the caller should invoke the method 082 * {@link SBMLDocument#convert(ConversionProperties)} 083 * with the {@link ConversionProperties} object as an argument. 084 <p> 085 * <h3>Example of invoking an SBML converter</h3> 086 <p> 087 * The following code fragment illustrates an example using 088 * {@link SBMLReactionConverter}, which is invoked using the option string 089 * <code>'replaceReactions':</code> 090 <p> 091<pre class='fragment'> 092{@link ConversionProperties} props = new {@link ConversionProperties}(); 093if (props != null) { 094 props.addOption('replaceReactions'); 095} else { 096 // Deal with error. 097} 098</pre> 099<p> 100 * In the case of {@link SBMLReactionConverter}, there are no options to affect 101 * its behavior, so the next step is simply to invoke the converter on 102 * an {@link SBMLDocument} object. Continuing the example code: 103 <p> 104<pre class='fragment'> 105 // Assume that the variable 'document' has been set to an {@link SBMLDocument} object. 106 status = document.convert(config); 107 if (status != libsbml.LIBSBML_OPERATION_SUCCESS) 108 { 109 // Handle error somehow. 110 System.out.println('Error: conversion failed due to the following:'); 111 document.printErrors(); 112 } 113</pre> 114<p> 115 * Here is an example of using a converter that offers an option. The 116 * following code invokes {@link SBMLStripPackageConverter} to remove the 117 * SBML Level 3 <em>Layout</em> package from a model. It sets the name 118 * of the package to be removed by adding a value for the option named 119 * <code>'package'</code> defined by that converter: 120 <p> 121<pre class='fragment'> 122{@link ConversionProperties} config = new {@link ConversionProperties}(); 123if (config != None) { 124 config.addOption('stripPackage'); 125 config.addOption('package', 'layout'); 126 status = document.convert(config); 127 if (status != LIBSBML_OPERATION_SUCCESS) { 128 // Handle error somehow. 129 System.out.println('Error: unable to strip the {@link Layout} package'); 130 document.printErrors(); 131 } 132} else { 133 // Handle error somehow. 134 System.out.println('Error: unable to create {@link ConversionProperties} object'); 135} 136</pre> 137<p> 138 * <h3>Available SBML converters in libSBML</h3> 139 <p> 140 * LibSBML provides a number of built-in converters; by convention, their 141 * names end in <em>Converter</em>. The following are the built-in converters 142 * provided by libSBML 5.16.0 143: 144 <p> 145 * <p> 146 * <ul> 147 * <li> ArraysFlatteningConverter 148 * <li> {@link CobraToFbcConverter} 149 * <li> {@link CompFlatteningConverter} 150 * <li> {@link FbcToCobraConverter} 151 * <li> {@link FbcV1ToV2Converter} 152 * <li> {@link FbcV2ToV1Converter} 153 * <li> {@link SBMLFunctionDefinitionConverter} 154 * <li> {@link SBMLIdConverter} 155 * <li> {@link SBMLInferUnitsConverter} 156 * <li> {@link SBMLInitialAssignmentConverter} 157 * <li> {@link SBMLLevel1Version1Converter} 158 * <li> {@link SBMLLevelVersionConverter} 159 * <li> {@link SBMLLocalParameterConverter} 160 * <li> SBMLRateOfConverter 161 * <li> {@link SBMLReactionConverter} 162 * <li> {@link SBMLRuleConverter} 163 * <li> {@link SBMLStripPackageConverter} 164 * <li> {@link SBMLUnitsConverter} 165 * 166 * </ul> 167 */ 168 169public class SBMLLevelVersionConverter extends SBMLConverter { 170 private long swigCPtr; 171 172 protected SBMLLevelVersionConverter(long cPtr, boolean cMemoryOwn) 173 { 174 super(libsbmlJNI.SBMLLevelVersionConverter_SWIGUpcast(cPtr), cMemoryOwn); 175 swigCPtr = cPtr; 176 } 177 178 protected static long getCPtr(SBMLLevelVersionConverter obj) 179 { 180 return (obj == null) ? 0 : obj.swigCPtr; 181 } 182 183 protected static long getCPtrAndDisown (SBMLLevelVersionConverter obj) 184 { 185 long ptr = 0; 186 187 if (obj != null) 188 { 189 ptr = obj.swigCPtr; 190 obj.swigCMemOwn = false; 191 } 192 193 return ptr; 194 } 195 196 protected void finalize() { 197 delete(); 198 } 199 200 public synchronized void delete() { 201 if (swigCPtr != 0) { 202 if (swigCMemOwn) { 203 swigCMemOwn = false; 204 libsbmlJNI.delete_SBMLLevelVersionConverter(swigCPtr); 205 } 206 swigCPtr = 0; 207 } 208 super.delete(); 209 } 210 211 212/** * @internal */ public 213 static void init() { 214 libsbmlJNI.SBMLLevelVersionConverter_init(); 215 } 216 217 218/** 219 * Creates a new {@link SBMLLevelVersionConverter} object. 220 */ public 221 SBMLLevelVersionConverter() { 222 this(libsbmlJNI.new_SBMLLevelVersionConverter__SWIG_0(), true); 223 } 224 225 226/** 227 * Copy constructor; creates a copy of an {@link SBMLLevelVersionConverter} 228 * object. 229 <p> 230 * @param obj the {@link SBMLLevelVersionConverter} object to copy. 231 */ public 232 SBMLLevelVersionConverter(SBMLLevelVersionConverter obj) { 233 this(libsbmlJNI.new_SBMLLevelVersionConverter__SWIG_1(SBMLLevelVersionConverter.getCPtr(obj), obj), true); 234 } 235 236 237/** 238 * Creates and returns a deep copy of this {@link SBMLLevelVersionConverter} 239 * object. 240 <p> 241 * @return a (deep) copy of this converter. 242 */ public 243 SBMLConverter cloneObject() { 244 long cPtr = libsbmlJNI.SBMLLevelVersionConverter_cloneObject(swigCPtr, this); 245 return (cPtr == 0) ? null : new SBMLLevelVersionConverter(cPtr, true); 246 } 247 248 249/** 250 * Returns <code>true</code> if this converter object's properties match the given 251 * properties. 252 <p> 253 * A typical use of this method involves creating a {@link ConversionProperties} 254 * object, setting the options desired, and then calling this method on 255 * an {@link SBMLLevelVersionConverter} object to find out if the object's 256 * property values match the given ones. This method is also used by 257 * {@link SBMLConverterRegistry#getConverterFor(ConversionProperties)} 258 * to search across all registered converters for one matching particular 259 * properties. 260 <p> 261 * @param props the properties to match. 262 <p> 263 * @return <code>true</code> if this converter's properties match, <code>false</code> 264 * otherwise. 265 */ public 266 boolean matchesProperties(ConversionProperties props) { 267 return libsbmlJNI.SBMLLevelVersionConverter_matchesProperties(swigCPtr, this, ConversionProperties.getCPtr(props), props); 268 } 269 270 271/** 272 * Perform the conversion. 273 <p> 274 * This method causes the converter to do the actual conversion work, 275 * that is, to convert the {@link SBMLDocument} object set by 276 * {@link SBMLConverter#setDocument(SBMLDocument)} and 277 * with the configuration options set by 278 * {@link SBMLConverter#setProperties(ConversionProperties)}. 279 <p> 280 * <p> 281 * @return integer value indicating success/failure of the 282 * function. The possible values 283 * returned by this function are: 284 * <ul> 285 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 286 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED} 287 * <li> {@link libsbmlConstants#LIBSBML_CONV_INVALID_TARGET_NAMESPACE LIBSBML_CONV_INVALID_TARGET_NAMESPACE} 288 * <li> {@link libsbmlConstants#LIBSBML_CONV_PKG_CONVERSION_NOT_AVAILABLE LIBSBML_CONV_PKG_CONVERSION_NOT_AVAILABLE} 289 * <li> {@link libsbmlConstants#LIBSBML_CONV_INVALID_SRC_DOCUMENT LIBSBML_CONV_INVALID_SRC_DOCUMENT} 290 * </ul> 291 */ public 292 int convert() { 293 return libsbmlJNI.SBMLLevelVersionConverter_convert(swigCPtr, this); 294 } 295 296 297/** 298 * Returns the default properties of this converter. 299 <p> 300 * A given converter exposes one or more properties that can be adjusted 301 * in order to influence the behavior of the converter. This method 302 * returns the <em>default</em> property settings for this converter. It is 303 * meant to be called in order to discover all the settings for the 304 * converter object. 305 <p> 306 * @return the {@link ConversionProperties} object describing the default properties 307 * for this converter. 308 */ public 309 ConversionProperties getDefaultProperties() { 310 return new ConversionProperties(libsbmlJNI.SBMLLevelVersionConverter_getDefaultProperties(swigCPtr, this), true); 311 } 312 313 314/** 315 * Returns the target SBML Level for the conversion. 316 <p> 317 * @return an integer indicating the SBML Level. 318 */ public 319 long getTargetLevel() { 320 return libsbmlJNI.SBMLLevelVersionConverter_getTargetLevel(swigCPtr, this); 321 } 322 323 324/** 325 * Returns the target SBML Version for the conversion. 326 <p> 327 * @return an integer indicating the Version within the SBML Level. 328 */ public 329 long getTargetVersion() { 330 return libsbmlJNI.SBMLLevelVersionConverter_getTargetVersion(swigCPtr, this); 331 } 332 333 334/** 335 * Returns the flag indicating whether the conversion has been set to 'strict'. 336 <p> 337 * @return <code>true</code> if strict validity has been requested, <code>false</code> 338 * otherwise. 339 */ public 340 boolean getValidityFlag() { 341 return libsbmlJNI.SBMLLevelVersionConverter_getValidityFlag(swigCPtr, this); 342 } 343 344 345/** 346 * Returns the flag indicating whether default units should be added when 347 * converting to L3 or not. 348 <p> 349 * @return <code>true</code> if default units should be added, <code>false</code> 350 * otherwise. 351 */ public 352 boolean getAddDefaultUnits() { 353 return libsbmlJNI.SBMLLevelVersionConverter_getAddDefaultUnits(swigCPtr, this); 354 } 355 356}