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 * Converts a model's existing units to SI units. 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 converts the units in a model to base SI units, that 022 * is, using only the units metre, kilogram, second, ampere, kelvin, mole and 023 * candela. 024 <p> 025 * {@link Unit} conversion will only be performed on models that are fully unit 026 * consistent, meaning that all objects have units associated with them and 027 * there are no literal numbers with unspecified units. In the case of an 028 * SBML Level 3 model involving math expressions, this means that the 029 * <code>timeUnits</code> attribute on the {@link Model} object must be set, and if there are any 030 * reactions in the model, the <code>extentUnits</code> attribute on the {@link Model} object 031 * must also be set. 032 <p> 033 * <h2>Configuration and use of {@link SBMLUnitsConverter}</h2> 034 <p> 035 * {@link SBMLUnitsConverter} is enabled by creating a {@link ConversionProperties} object 036 * with the option <code>'units'</code>, and passing this properties object to 037 * {@link SBMLDocument#convert(ConversionProperties)}. This 038 * converter takes one optional option: 039 <p> 040 * <ul> 041 * <li> <code>'removeUnusedUnits':</code> the value of this property should be a 042 * Boolean. If it is <code>true</code>, it tells the unit convert to remove any unused 043 * {@link UnitDefinition} objects after conversion is complete. ('Unused' units are 044 * units that are not referenced by any object in the model.) If the value 045 * is <code>false</code>, unused {@link UnitDefinition} objects are not removed from the model. 046 * The default is <code>true.</code> 047 * 048 * </ul> <p> 049 * <p> 050 * <h2>General information about the use of SBML converters</h2> 051 <p> 052 * The use of all the converters follows a similar approach. First, one 053 * creates a {@link ConversionProperties} object and calls 054 * {@link ConversionProperties#addOption(ConversionOption)} 055 * on this object with one argument: a text string that identifies the desired 056 * converter. (The text string is specific to each converter; consult the 057 * documentation for a given converter to find out how it should be enabled.) 058 <p> 059 * Next, for some converters, the caller can optionally set some 060 * converter-specific properties using additional calls to 061 * {@link ConversionProperties#addOption(ConversionOption)}. 062 * Many converters provide the ability to 063 * configure their behavior to some extent; this is realized through the use 064 * of properties that offer different options. The default property values 065 * for each converter can be interrogated using the method 066 * {@link SBMLConverter#getDefaultProperties()} on the converter class in question . 067 <p> 068 * Finally, the caller should invoke the method 069 * {@link SBMLDocument#convert(ConversionProperties)} 070 * with the {@link ConversionProperties} object as an argument. 071 <p> 072 * <h3>Example of invoking an SBML converter</h3> 073 <p> 074 * The following code fragment illustrates an example using 075 * {@link SBMLReactionConverter}, which is invoked using the option string 076 * <code>'replaceReactions':</code> 077 <p> 078<pre class='fragment'> 079{@link ConversionProperties} props = new {@link ConversionProperties}(); 080if (props != null) { 081 props.addOption('replaceReactions'); 082} else { 083 // Deal with error. 084} 085</pre> 086<p> 087 * In the case of {@link SBMLReactionConverter}, there are no options to affect 088 * its behavior, so the next step is simply to invoke the converter on 089 * an {@link SBMLDocument} object. Continuing the example code: 090 <p> 091<pre class='fragment'> 092 // Assume that the variable 'document' has been set to an {@link SBMLDocument} object. 093 status = document.convert(config); 094 if (status != libsbml.LIBSBML_OPERATION_SUCCESS) 095 { 096 // Handle error somehow. 097 System.out.println('Error: conversion failed due to the following:'); 098 document.printErrors(); 099 } 100</pre> 101<p> 102 * Here is an example of using a converter that offers an option. The 103 * following code invokes {@link SBMLStripPackageConverter} to remove the 104 * SBML Level 3 <em>Layout</em> package from a model. It sets the name 105 * of the package to be removed by adding a value for the option named 106 * <code>'package'</code> defined by that converter: 107 <p> 108<pre class='fragment'> 109{@link ConversionProperties} config = new {@link ConversionProperties}(); 110if (config != None) { 111 config.addOption('stripPackage'); 112 config.addOption('package', 'layout'); 113 status = document.convert(config); 114 if (status != LIBSBML_OPERATION_SUCCESS) { 115 // Handle error somehow. 116 System.out.println('Error: unable to strip the {@link Layout} package'); 117 document.printErrors(); 118 } 119} else { 120 // Handle error somehow. 121 System.out.println('Error: unable to create {@link ConversionProperties} object'); 122} 123</pre> 124<p> 125 * <h3>Available SBML converters in libSBML</h3> 126 <p> 127 * LibSBML provides a number of built-in converters; by convention, their 128 * names end in <em>Converter</em>. The following are the built-in converters 129 * provided by libSBML 5.15.2 130: 131 <p> 132 * <p> 133 * <ul> 134 * <li> ArraysFlatteningConverter 135 * <li> {@link CobraToFbcConverter} 136 * <li> {@link CompFlatteningConverter} 137 * <li> {@link FbcToCobraConverter} 138 * <li> {@link FbcV1ToV2Converter} 139 * <li> {@link FbcV2ToV1Converter} 140 * <li> {@link SBMLFunctionDefinitionConverter} 141 * <li> {@link SBMLIdConverter} 142 * <li> {@link SBMLInferUnitsConverter} 143 * <li> {@link SBMLInitialAssignmentConverter} 144 * <li> {@link SBMLLevel1Version1Converter} 145 * <li> {@link SBMLLevelVersionConverter} 146 * <li> {@link SBMLLocalParameterConverter} 147 * <li> SBMLRateOfConverter 148 * <li> {@link SBMLReactionConverter} 149 * <li> {@link SBMLRuleConverter} 150 * <li> {@link SBMLStripPackageConverter} 151 * <li> {@link SBMLUnitsConverter} 152 * 153 * </ul> 154 */ 155 156public class SBMLUnitsConverter extends SBMLConverter { 157 private long swigCPtr; 158 159 protected SBMLUnitsConverter(long cPtr, boolean cMemoryOwn) 160 { 161 super(libsbmlJNI.SBMLUnitsConverter_SWIGUpcast(cPtr), cMemoryOwn); 162 swigCPtr = cPtr; 163 } 164 165 protected static long getCPtr(SBMLUnitsConverter obj) 166 { 167 return (obj == null) ? 0 : obj.swigCPtr; 168 } 169 170 protected static long getCPtrAndDisown (SBMLUnitsConverter obj) 171 { 172 long ptr = 0; 173 174 if (obj != null) 175 { 176 ptr = obj.swigCPtr; 177 obj.swigCMemOwn = false; 178 } 179 180 return ptr; 181 } 182 183 protected void finalize() { 184 delete(); 185 } 186 187 public synchronized void delete() { 188 if (swigCPtr != 0) { 189 if (swigCMemOwn) { 190 swigCMemOwn = false; 191 libsbmlJNI.delete_SBMLUnitsConverter(swigCPtr); 192 } 193 swigCPtr = 0; 194 } 195 super.delete(); 196 } 197 198 199/** * @internal */ public 200 static void init() { 201 libsbmlJNI.SBMLUnitsConverter_init(); 202 } 203 204 205/** 206 * Creates a new {@link SBMLUnitsConverter} object. 207 */ public 208 SBMLUnitsConverter() { 209 this(libsbmlJNI.new_SBMLUnitsConverter__SWIG_0(), true); 210 } 211 212 213/** 214 * Copy constructor; creates a copy of an {@link SBMLUnitsConverter} 215 * object. 216 <p> 217 * @param obj the {@link SBMLUnitsConverter} object to copy. 218 */ public 219 SBMLUnitsConverter(SBMLUnitsConverter obj) { 220 this(libsbmlJNI.new_SBMLUnitsConverter__SWIG_1(SBMLUnitsConverter.getCPtr(obj), obj), true); 221 } 222 223 224/** 225 * Creates and returns a deep copy of this {@link SBMLUnitsConverter} 226 * object. 227 <p> 228 * @return a (deep) copy of this converter. 229 */ public 230 SBMLConverter cloneObject() { 231 long cPtr = libsbmlJNI.SBMLUnitsConverter_cloneObject(swigCPtr, this); 232 return (cPtr == 0) ? null : new SBMLUnitsConverter(cPtr, true); 233 } 234 235 236/** 237 * Returns <code>true</code> if this converter object's properties match the given 238 * properties. 239 <p> 240 * A typical use of this method involves creating a {@link ConversionProperties} 241 * object, setting the options desired, and then calling this method on 242 * an {@link SBMLUnitsConverter} object to find out if the object's 243 * property values match the given ones. This method is also used by 244 * {@link SBMLConverterRegistry#getConverterFor(ConversionProperties)} 245 * to search across all registered converters for one matching particular 246 * properties. 247 <p> 248 * @param props the properties to match. 249 <p> 250 * @return <code>true</code> if this converter's properties match, <code>false</code> 251 * otherwise. 252 */ public 253 boolean matchesProperties(ConversionProperties props) { 254 return libsbmlJNI.SBMLUnitsConverter_matchesProperties(swigCPtr, this, ConversionProperties.getCPtr(props), props); 255 } 256 257 258/** 259 * Perform the conversion. 260 <p> 261 * This method causes the converter to do the actual conversion work, 262 * that is, to convert the {@link SBMLDocument} object set by 263 * {@link SBMLConverter#setDocument(SBMLDocument)} and 264 * with the configuration options set by 265 * {@link SBMLConverter#setProperties(ConversionProperties)}. 266 <p> 267 * <p> 268 * @return integer value indicating success/failure of the 269 * function. The possible values 270 * returned by this function are: 271 * <ul> 272 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 273 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED} 274 * <li> {@link libsbmlConstants#LIBSBML_INVALID_OBJECT LIBSBML_INVALID_OBJECT} 275 * <li> {@link libsbmlConstants#LIBSBML_CONV_CONVERSION_NOT_AVAILABLE LIBSBML_CONV_CONVERSION_NOT_AVAILABLE} 276 * <li> {@link libsbmlConstants#LIBSBML_CONV_INVALID_SRC_DOCUMENT LIBSBML_CONV_INVALID_SRC_DOCUMENT} 277 * </ul> 278 */ public 279 int convert() { 280 return libsbmlJNI.SBMLUnitsConverter_convert(swigCPtr, this); 281 } 282 283 284/** 285 * Returns the default properties of this converter. 286 <p> 287 * A given converter exposes one or more properties that can be adjusted 288 * in order to influence the behavior of the converter. This method 289 * returns the <em>default</em> property settings for this converter. It is 290 * meant to be called in order to discover all the settings for the 291 * converter object. 292 <p> 293 * @return the {@link ConversionProperties} object describing the default properties 294 * for this converter. 295 */ public 296 ConversionProperties getDefaultProperties() { 297 return new ConversionProperties(libsbmlJNI.SBMLUnitsConverter_getDefaultProperties(swigCPtr, this), true); 298 } 299 300}