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 * Converter that sorts SBML rules and assignments. 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 converter reorders assignments in a model. Specifically, it sorts 022 * the list of assignment rules (i.e., the {@link AssignmentRule} objects contained 023 * in the ListOfAssignmentRules within the {@link Model} object) and the initial 024 * assignments (i.e., the {@link InitialAssignment} objects contained in the 025 * {@link ListOfInitialAssignments}) such that, within each set, assignments that 026 * depend on <em>prior</em> values are placed <em>after</em> the values are set. For 027 * example, if there is an assignment rule stating <i>a = b + 1</i>, and 028 * another rule stating <i>b = 3</i>, the list of rules is sorted and the 029 * rules are arranged so that the rule for <i>b = 3</i> appears <em>before</em> 030 * the rule for <i>a = b + 1</i>. Similarly, if dependencies of this 031 * sort exist in the list of initial assignments in the model, the initial 032 * assignments are sorted as well. 033 <p> 034 * Beginning with SBML Level 2, assignment rules have no ordering 035 * required—the order in which the rules appear in an SBML file has 036 * no significance. Software tools, however, may need to reorder 037 * assignments for purposes of evaluating them. For example, for 038 * simulators that use time integration methods, it would be a good idea to 039 * reorder assignment rules such as the following, 040 <p> 041 * <i>b = a + 10 seconds</i><br> 042 * <i>a = time</i> 043 <p> 044 * so that the evaluation of the rules is independent of integrator 045 * step sizes. (This is due to the fact that, in this case, the order in 046 * which the rules are evaluated changes the result.) {@link SBMLRuleConverter} 047 * can be used to reorder the SBML objects regardless of whether the 048 * input file contained them in the desired order. 049 <p> 050 * Note that the two sets of SBML assignments (list of assignment rules on 051 * the one hand, and list of initial assignments on the other hand) are 052 * handled <em>independently</em>. In an SBML model, these entities are treated 053 * differently and no amount of sorting can deal with inter-dependencies 054 * between assignments of the two kinds. 055<p> 056 * <h2>Configuration and use of {@link SBMLRuleConverter}</h2> 057 <p> 058 * {@link SBMLRuleConverter} is enabled by creating a {@link ConversionProperties} object 059 * with the option <code>'sortRules'</code>, and passing this properties object to 060 * {@link SBMLDocument#convert(ConversionProperties)}. This 061 * converter offers no other options. 062 <p> 063 * <p> 064 * <h2>General information about the use of SBML converters</h2> 065 <p> 066 * The use of all the converters follows a similar approach. First, one 067 * creates a {@link ConversionProperties} object and calls 068 * {@link ConversionProperties#addOption(ConversionOption)} 069 * on this object with one argument: a text string that identifies the desired 070 * converter. (The text string is specific to each converter; consult the 071 * documentation for a given converter to find out how it should be enabled.) 072 <p> 073 * Next, for some converters, the caller can optionally set some 074 * converter-specific properties using additional calls to 075 * {@link ConversionProperties#addOption(ConversionOption)}. 076 * Many converters provide the ability to 077 * configure their behavior to some extent; this is realized through the use 078 * of properties that offer different options. The default property values 079 * for each converter can be interrogated using the method 080 * {@link SBMLConverter#getDefaultProperties()} on the converter class in question . 081 <p> 082 * Finally, the caller should invoke the method 083 * {@link SBMLDocument#convert(ConversionProperties)} 084 * with the {@link ConversionProperties} object as an argument. 085 <p> 086 * <h3>Example of invoking an SBML converter</h3> 087 <p> 088 * The following code fragment illustrates an example using 089 * {@link SBMLReactionConverter}, which is invoked using the option string 090 * <code>'replaceReactions':</code> 091 <p> 092<pre class='fragment'> 093{@link ConversionProperties} props = new {@link ConversionProperties}(); 094if (props != null) { 095 props.addOption('replaceReactions'); 096} else { 097 // Deal with error. 098} 099</pre> 100<p> 101 * In the case of {@link SBMLReactionConverter}, there are no options to affect 102 * its behavior, so the next step is simply to invoke the converter on 103 * an {@link SBMLDocument} object. Continuing the example code: 104 <p> 105<pre class='fragment'> 106 // Assume that the variable 'document' has been set to an {@link SBMLDocument} object. 107 status = document.convert(config); 108 if (status != libsbml.LIBSBML_OPERATION_SUCCESS) 109 { 110 // Handle error somehow. 111 System.out.println('Error: conversion failed due to the following:'); 112 document.printErrors(); 113 } 114</pre> 115<p> 116 * Here is an example of using a converter that offers an option. The 117 * following code invokes {@link SBMLStripPackageConverter} to remove the 118 * SBML Level 3 <em>Layout</em> package from a model. It sets the name 119 * of the package to be removed by adding a value for the option named 120 * <code>'package'</code> defined by that converter: 121 <p> 122<pre class='fragment'> 123{@link ConversionProperties} config = new {@link ConversionProperties}(); 124if (config != None) { 125 config.addOption('stripPackage'); 126 config.addOption('package', 'layout'); 127 status = document.convert(config); 128 if (status != LIBSBML_OPERATION_SUCCESS) { 129 // Handle error somehow. 130 System.out.println('Error: unable to strip the {@link Layout} package'); 131 document.printErrors(); 132 } 133} else { 134 // Handle error somehow. 135 System.out.println('Error: unable to create {@link ConversionProperties} object'); 136} 137</pre> 138<p> 139 * <h3>Available SBML converters in libSBML</h3> 140 <p> 141 * LibSBML provides a number of built-in converters; by convention, their 142 * names end in <em>Converter</em>. The following are the built-in converters 143 * provided by libSBML 5.15.2 144: 145 <p> 146 * <p> 147 * <ul> 148 * <li> ArraysFlatteningConverter 149 * <li> {@link CobraToFbcConverter} 150 * <li> {@link CompFlatteningConverter} 151 * <li> {@link FbcToCobraConverter} 152 * <li> {@link FbcV1ToV2Converter} 153 * <li> {@link FbcV2ToV1Converter} 154 * <li> {@link SBMLFunctionDefinitionConverter} 155 * <li> {@link SBMLIdConverter} 156 * <li> {@link SBMLInferUnitsConverter} 157 * <li> {@link SBMLInitialAssignmentConverter} 158 * <li> {@link SBMLLevel1Version1Converter} 159 * <li> {@link SBMLLevelVersionConverter} 160 * <li> {@link SBMLLocalParameterConverter} 161 * <li> SBMLRateOfConverter 162 * <li> {@link SBMLReactionConverter} 163 * <li> {@link SBMLRuleConverter} 164 * <li> {@link SBMLStripPackageConverter} 165 * <li> {@link SBMLUnitsConverter} 166 * 167 * </ul> 168 */ 169 170public class SBMLRuleConverter extends SBMLConverter { 171 private long swigCPtr; 172 173 protected SBMLRuleConverter(long cPtr, boolean cMemoryOwn) 174 { 175 super(libsbmlJNI.SBMLRuleConverter_SWIGUpcast(cPtr), cMemoryOwn); 176 swigCPtr = cPtr; 177 } 178 179 protected static long getCPtr(SBMLRuleConverter obj) 180 { 181 return (obj == null) ? 0 : obj.swigCPtr; 182 } 183 184 protected static long getCPtrAndDisown (SBMLRuleConverter obj) 185 { 186 long ptr = 0; 187 188 if (obj != null) 189 { 190 ptr = obj.swigCPtr; 191 obj.swigCMemOwn = false; 192 } 193 194 return ptr; 195 } 196 197 protected void finalize() { 198 delete(); 199 } 200 201 public synchronized void delete() { 202 if (swigCPtr != 0) { 203 if (swigCMemOwn) { 204 swigCMemOwn = false; 205 libsbmlJNI.delete_SBMLRuleConverter(swigCPtr); 206 } 207 swigCPtr = 0; 208 } 209 super.delete(); 210 } 211 212 213/** * @internal */ public 214 static void init() { 215 libsbmlJNI.SBMLRuleConverter_init(); 216 } 217 218 219/** 220 * Creates a new {@link SBMLLevelVersionConverter} object. 221 */ public 222 SBMLRuleConverter() { 223 this(libsbmlJNI.new_SBMLRuleConverter__SWIG_0(), true); 224 } 225 226 227/** 228 * Copy constructor; creates a copy of an {@link SBMLLevelVersionConverter} 229 * object. 230 <p> 231 * @param obj the {@link SBMLLevelVersionConverter} object to copy. 232 */ public 233 SBMLRuleConverter(SBMLRuleConverter obj) { 234 this(libsbmlJNI.new_SBMLRuleConverter__SWIG_1(SBMLRuleConverter.getCPtr(obj), obj), true); 235 } 236 237 238/** 239 * Creates and returns a deep copy of this {@link SBMLLevelVersionConverter} 240 * object. 241 <p> 242 * @return a (deep) copy of this converter. 243 */ public 244 SBMLConverter cloneObject() { 245 long cPtr = libsbmlJNI.SBMLRuleConverter_cloneObject(swigCPtr, this); 246 return (cPtr == 0) ? null : new SBMLRuleConverter(cPtr, true); 247 } 248 249 250/** 251 * Returns <code>true</code> if this converter object's properties match the given 252 * properties. 253 <p> 254 * A typical use of this method involves creating a {@link ConversionProperties} 255 * object, setting the options desired, and then calling this method on 256 * an {@link SBMLLevelVersionConverter} object to find out if the object's 257 * property values match the given ones. This method is also used by 258 * {@link SBMLConverterRegistry#getConverterFor(ConversionProperties)} 259 * to search across all registered converters for one matching particular 260 * properties. 261 <p> 262 * @param props the properties to match. 263 <p> 264 * @return <code>true</code> if this converter's properties match, <code>false</code> 265 * otherwise. 266 */ public 267 boolean matchesProperties(ConversionProperties props) { 268 return libsbmlJNI.SBMLRuleConverter_matchesProperties(swigCPtr, this, ConversionProperties.getCPtr(props), props); 269 } 270 271 272/** 273 * Perform the conversion. 274 <p> 275 * This method causes the converter to do the actual conversion work, 276 * that is, to convert the {@link SBMLDocument} object set by 277 * {@link SBMLConverter#setDocument(SBMLDocument)} and 278 * with the configuration options set by 279 * {@link SBMLConverter#setProperties(ConversionProperties)}. 280 <p> 281 * <p> 282 * @return integer value indicating success/failure of the 283 * function. The possible values 284 * returned by this function are: 285 * <ul> 286 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 287 * <li> {@link libsbmlConstants#LIBSBML_INVALID_OBJECT LIBSBML_INVALID_OBJECT} 288 * <li> {@link libsbmlConstants#LIBSBML_CONV_INVALID_SRC_DOCUMENT LIBSBML_CONV_INVALID_SRC_DOCUMENT} 289 * </ul> 290 */ public 291 int convert() { 292 return libsbmlJNI.SBMLRuleConverter_convert(swigCPtr, this); 293 } 294 295 296/** 297 * Returns the default properties of this converter. 298 <p> 299 * A given converter exposes one or more properties that can be adjusted 300 * in order to influence the behavior of the converter. This method 301 * returns the <em>default</em> property settings for this converter. It is 302 * meant to be called in order to discover all the settings for the 303 * converter object. 304 <p> 305 * @return the {@link ConversionProperties} object describing the default properties 306 * for this converter. 307 */ public 308 ConversionProperties getDefaultProperties() { 309 return new ConversionProperties(libsbmlJNI.SBMLRuleConverter_getDefaultProperties(swigCPtr, this), true); 310 } 311 312}