001/* ---------------------------------------------------------------------------- 002 * This file was automatically generated by SWIG (http://www.swig.org). 003 * Version 3.0.7 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. This converter 024 * (SBMLLevel1Version1Converter) converts models to SBML Level 1 025 * Version 1, to the extent possible by the limited features of 026 * that Level/Version combination of SBML. 027 <p> 028 * <h2>Configuration and use of {@link SBMLLevel1Version1Converter}</h2> 029 <p> 030 * {@link SBMLLevel1Version1Converter} is enabled by creating a {@link ConversionProperties} 031 * object with the option <code>'convertToL1V1'</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>'changePow':</code> Mathematical expressions for exponentiation of 041 * the form <code>pow(s1, 2)</code> will be converted to the expression 042 * <code>s1^2</code>. 043 <p> 044 * <li> <code>'inlineCompartmentSizes':</code> Back in the days of SBML Level 1 045 * Version 1, many software tools assumed that the 'kinetic laws' of 046 * SBML were written in terms of units of 047 * <em>concentration</em>/<em>time</em>. These tools would not expect (and 048 * thus not handle) rate expressions such as 049 * <code>CompartmentOfS1 * k * S1</code>. 050 * When the option <code>'inlineCompartmentSizes'</code> is enabled, libSBML will 051 * replace the references to compartments (such as <code>'CompartmentOfS1'</code> in 052 * this example) with their initial sizes. This is not strictly correct in 053 * all cases; in particular, if the compartment volume varies during 054 * simulation, this conversion will not reflect the expected behavior. 055 * However, many models do not have time-varying compartment sizes, so this 056 * option makes it easy to get modern SBML rate expressions into a form that 057 * old software tools may better understand. 058 * 059 * </ul> <p> 060 * <p> 061 * <h2>General information about the use of SBML converters</h2> 062 <p> 063 * The use of all the converters follows a similar approach. First, one 064 * creates a {@link ConversionProperties} object and calls 065 * {@link ConversionProperties#addOption(ConversionOption)} 066 * on this object with one arguments: a text string that identifies the desired 067 * converter. (The text string is specific to each converter; consult the 068 * documentation for a given converter to find out how it should be enabled.) 069 <p> 070 * Next, for some converters, the caller can optionally set some 071 * converter-specific properties using additional calls to 072 * {@link ConversionProperties#addOption(ConversionOption)}. 073 * Many converters provide the ability to 074 * configure their behavior to some extent; this is realized through the use 075 * of properties that offer different options. The default property values 076 * for each converter can be interrogated using the method 077 * {@link SBMLConverter#getDefaultProperties()} on the converter class in question . 078 <p> 079 * Finally, the caller should invoke the method 080 * {@link SBMLDocument#convert(ConversionProperties)} 081 * with the {@link ConversionProperties} object as an argument. 082 <p> 083 * <h3>Example of invoking an SBML converter</h3> 084 <p> 085 * The following code fragment illustrates an example using 086 * {@link SBMLReactionConverter}, which is invoked using the option string 087 * <code>'replaceReactions':</code> 088 <p> 089<pre class='fragment'> 090{@link ConversionProperties} props = new {@link ConversionProperties}(); 091if (props != null) { 092 props.addOption('replaceReactions'); 093} else { 094 // Deal with error. 095} 096</pre> 097<p> 098 * In the case of {@link SBMLReactionConverter}, there are no options to affect 099 * its behavior, so the next step is simply to invoke the converter on 100 * an {@link SBMLDocument} object. Continuing the example code: 101 <p> 102<pre class='fragment'> 103 // Assume that the variable 'document' has been set to an {@link SBMLDocument} object. 104 status = document.convert(config); 105 if (status != libsbml.LIBSBML_OPERATION_SUCCESS) 106 { 107 // Handle error somehow. 108 System.out.println('Error: conversion failed due to the following:'); 109 document.printErrors(); 110 } 111</pre> 112<p> 113 * Here is an example of using a converter that offers an option. The 114 * following code invokes {@link SBMLStripPackageConverter} to remove the 115 * SBML Level 3 <em>Layout</em> package from a model. It sets the name 116 * of the package to be removed by adding a value for the option named 117 * <code>'package'</code> defined by that converter: 118 <p> 119<pre class='fragment'> 120{@link ConversionProperties} config = new {@link ConversionProperties}(); 121if (config != None) { 122 config.addOption('stripPackage'); 123 config.addOption('package', 'layout'); 124 status = document.convert(config); 125 if (status != LIBSBML_OPERATION_SUCCESS) { 126 // Handle error somehow. 127 System.out.println('Error: unable to strip the {@link Layout} package'); 128 document.printErrors(); 129 } 130} else { 131 // Handle error somehow. 132 System.out.println('Error: unable to create {@link ConversionProperties} object'); 133} 134</pre> 135<p> 136 * <h3>Available SBML converters in libSBML</h3> 137 <p> 138 * LibSBML provides a number of built-in converters; by convention, their 139 * names end in <em>Converter</em>. The following are the built-in converters 140 * provided by libSBML 5.12.0 141: 142 <p> 143 * <p> 144 * <ul> 145 * <li> {@link CobraToFbcConverter} 146 * <li> {@link CompFlatteningConverter} 147 * <li> {@link FbcToCobraConverter} 148 * <li> {@link FbcV1ToV2Converter} 149 * <li> {@link FbcV2ToV1Converter} 150 * <li> {@link SBMLFunctionDefinitionConverter} 151 * <li> {@link SBMLIdConverter} 152 * <li> {@link SBMLInferUnitsConverter} 153 * <li> {@link SBMLInitialAssignmentConverter} 154 * <li> {@link SBMLLevel1Version1Converter} 155 * <li> {@link SBMLLevelVersionConverter} 156 * <li> {@link SBMLLocalParameterConverter} 157 * <li> {@link SBMLReactionConverter} 158 * <li> {@link SBMLRuleConverter} 159 * <li> {@link SBMLStripPackageConverter} 160 * <li> {@link SBMLUnitsConverter} 161 * 162 * </ul> 163 */ 164 165public class SBMLLevel1Version1Converter extends SBMLConverter { 166 private long swigCPtr; 167 168 protected SBMLLevel1Version1Converter(long cPtr, boolean cMemoryOwn) 169 { 170 super(libsbmlJNI.SBMLLevel1Version1Converter_SWIGUpcast(cPtr), cMemoryOwn); 171 swigCPtr = cPtr; 172 } 173 174 protected static long getCPtr(SBMLLevel1Version1Converter obj) 175 { 176 return (obj == null) ? 0 : obj.swigCPtr; 177 } 178 179 protected static long getCPtrAndDisown (SBMLLevel1Version1Converter obj) 180 { 181 long ptr = 0; 182 183 if (obj != null) 184 { 185 ptr = obj.swigCPtr; 186 obj.swigCMemOwn = false; 187 } 188 189 return ptr; 190 } 191 192 protected void finalize() { 193 delete(); 194 } 195 196 public synchronized void delete() { 197 if (swigCPtr != 0) { 198 if (swigCMemOwn) { 199 swigCMemOwn = false; 200 libsbmlJNI.delete_SBMLLevel1Version1Converter(swigCPtr); 201 } 202 swigCPtr = 0; 203 } 204 super.delete(); 205 } 206 207 208/** * @internal */ public 209 static void init() { 210 libsbmlJNI.SBMLLevel1Version1Converter_init(); 211 } 212 213 214/** 215 * Creates a new {@link SBMLLevel1Version1Converter} object. 216 */ public 217 SBMLLevel1Version1Converter() { 218 this(libsbmlJNI.new_SBMLLevel1Version1Converter__SWIG_0(), true); 219 } 220 221 222/** 223 * Copy constructor; creates a copy of an {@link SBMLLevel1Version1Converter} 224 * object. 225 <p> 226 * @param obj the {@link SBMLLevel1Version1Converter} object to copy. 227 */ public 228 SBMLLevel1Version1Converter(SBMLLevel1Version1Converter obj) { 229 this(libsbmlJNI.new_SBMLLevel1Version1Converter__SWIG_1(SBMLLevel1Version1Converter.getCPtr(obj), obj), true); 230 } 231 232 233/** 234 * Creates and returns a deep copy of this {@link SBMLLevel1Version1Converter} 235 * object. 236 <p> 237 * @return a (deep) copy of this converter. 238 */ public 239 SBMLConverter cloneObject() { 240 long cPtr = libsbmlJNI.SBMLLevel1Version1Converter_cloneObject(swigCPtr, this); 241 return (cPtr == 0) ? null : new SBMLLevel1Version1Converter(cPtr, true); 242 } 243 244 245/** 246 * Returns <code>true</code> if this converter object's properties match the given 247 * properties. 248 <p> 249 * A typical use of this method involves creating a {@link ConversionProperties} 250 * object, setting the options desired, and then calling this method on 251 * an {@link SBMLLevel1Version1Converter} object to find out if the object's 252 * property values match the given ones. This method is also used by 253 * {@link SBMLConverterRegistry#getConverterFor(ConversionProperties)} 254 * to search across all registered converters for one matching particular 255 * properties. 256 <p> 257 * @param props the properties to match. 258 <p> 259 * @return <code>true</code> if this converter's properties match, <code>false</code> 260 * otherwise. 261 */ public 262 boolean matchesProperties(ConversionProperties props) { 263 return libsbmlJNI.SBMLLevel1Version1Converter_matchesProperties(swigCPtr, this, ConversionProperties.getCPtr(props), props); 264 } 265 266 267/** 268 * Perform the conversion. 269 <p> 270 * This method causes the converter to do the actual conversion work, 271 * that is, to convert the {@link SBMLDocument} object set by 272 * {@link SBMLConverter#setDocument(SBMLDocument)} and 273 * with the configuration options set by 274 * {@link SBMLConverter#setProperties(ConversionProperties)}. 275 <p> 276 * <p> 277 * @return integer value indicating success/failure of the 278 * function. The possible values 279 * returned by this function are: 280 * <ul> 281 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 282 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED} 283 * <li> {@link libsbmlConstants#LIBSBML_CONV_INVALID_TARGET_NAMESPACE LIBSBML_CONV_INVALID_TARGET_NAMESPACE} 284 * <li> {@link libsbmlConstants#LIBSBML_CONV_PKG_CONVERSION_NOT_AVAILABLE LIBSBML_CONV_PKG_CONVERSION_NOT_AVAILABLE} 285 * <li> {@link libsbmlConstants#LIBSBML_CONV_INVALID_SRC_DOCUMENT LIBSBML_CONV_INVALID_SRC_DOCUMENT} 286 * </ul> 287 */ public 288 int convert() { 289 return libsbmlJNI.SBMLLevel1Version1Converter_convert(swigCPtr, this); 290 } 291 292 293/** 294 * Returns the default properties of this converter. 295 <p> 296 * A given converter exposes one or more properties that can be adjusted 297 * in order to influence the behavior of the converter. This method 298 * returns the <em>default</em> property settings for this converter. It is 299 * meant to be called in order to discover all the settings for the 300 * converter object. 301 <p> 302 * @return the {@link ConversionProperties} object describing the default properties 303 * for this converter. 304 */ public 305 ConversionProperties getDefaultProperties() { 306 return new ConversionProperties(libsbmlJNI.SBMLLevel1Version1Converter_getDefaultProperties(swigCPtr, this), true); 307 } 308 309}