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 * A reference to an SBML species in a reaction. 013 <p> 014 * The {@link Reaction} structure provides a way to express which species act as 015 * reactants and which species act as products in a reaction. In a given 016 * reaction, references to those species acting as reactants and/or 017 * products are made using instances of {@link SpeciesReference} structures in a 018 * {@link Reaction} object's lists of reactants and products. 019 <p> 020 * A species can occur more than once in the lists of reactants and 021 * products of a given {@link Reaction} instance. The effective stoichiometry for 022 * a species in a reaction is the sum of the stoichiometry values given on 023 * the {@link SpeciesReference} object in the list of products minus the sum of 024 * stoichiometry values given on the {@link SpeciesReference} objects in the list 025 * of reactants. A positive value indicates the species is effectively a 026 * product and a negative value indicates the species is effectively a 027 * reactant. SBML places no restrictions on the effective stoichiometry of 028 * a species in a reaction; for example, it can be zero. In the following 029 * SBML fragment, the two reactions have the same effective stoichiometry 030 * for all their species: 031 * <pre class='fragment'> 032 <reaction id='x'> 033 <listOfReactants> 034 <speciesReference species='a'/> 035 <speciesReference species='a'/> 036 <speciesReference species='b'/> 037 </listOfReactants> 038 <listOfProducts> 039 <speciesReference species='c'/> 040 <speciesReference species='b'/> 041 </listProducts> 042 </reaction> 043 <reaction id='y'> 044 <listOfReactants> 045 <speciesReference species='a' stoichiometry='2'/> 046 </listOfReactants> 047 <listOfProducts> 048 <speciesReference species='c'/> 049 </listProducts> 050 </reaction> 051 </pre> 052 <p> 053 * The precise structure of {@link SpeciesReference} differs between SBML 054 * Level 2 and Level 3. We discuss the two variants in separate 055 * sections below. 056 <p> 057 * <h2>SpeciesReference in SBML Level 2</h2> 058 <p> 059 * The mandatory 'species' attribute of {@link SpeciesReference} must have as its 060 * value the identifier of an existing species defined in the enclosing 061 * {@link Model}. The species is thereby designated as a reactant or product in 062 * the reaction. Which one it is (i.e., reactant or product) is indicated 063 * by whether the {@link SpeciesReference} appears in the {@link Reaction}'s 'reactant' or 064 * 'product' lists. 065 <p> 066 * Product and reactant stoichiometries can be specified using 067 * <em>either</em> 'stoichiometry' or 'stoichiometryMath' in a 068 * {@link SpeciesReference} object. The 'stoichiometry' attribute is of type 069 * double and should contain values greater than zero (0). The 070 * 'stoichiometryMath' element is implemented as an element containing a 071 * MathML expression. These two are mutually exclusive; only one of 072 * 'stoichiometry' or 'stoichiometryMath' should be defined in a given 073 * {@link SpeciesReference} instance. When neither the attribute nor the element 074 * is present, the value of 'stoichiometry' in the {@link SpeciesReference} 075 * instance defaults to <code>1.</code> 076 <p> 077 * For maximum interoperability, the 'stoichiometry' attribute should be 078 * used in preference to 'stoichiometryMath' when a species' stoichiometry 079 * is a simple scalar number (integer or decimal). When the stoichiometry 080 * is a rational number, or when it is a more complicated formula, 081 * 'stoichiometryMath' must be used. The MathML expression in 082 * 'stoichiometryMath' may also refer to identifiers of entities in a model 083 * (except reaction identifiers). However, the only species identifiers 084 * that can be used in 'stoichiometryMath' are those referenced in the 085 * {@link Reaction} list of reactants, products and modifiers. 086 <p> 087 * The following is a simple example of a species reference for species 088 * <code>X0</code>, with stoichiometry <code>2</code>, in a list of reactants within a reaction 089 * having the identifier <code>J1:</code> 090 * <pre class='fragment'> 091 <model> 092 ... 093 <listOfReactions> 094 <reaction id='J1'> 095 <listOfReactants> 096 <speciesReference species='X0' stoichiometry='2'> 097 </listOfReactants> 098 ... 099 </reaction> 100 ... 101 </listOfReactions> 102 ... 103 </model> 104 </pre> 105 <p> 106 * The following is a more complex example of a species reference for 107 * species X0, with a stoichiometry formula consisting of the parameter 108 * <code>x:</code> 109 * <pre class='fragment'> 110 <model> 111 ... 112 <listOfReactions> 113 <reaction id='J1'> 114 <listOfReactants> 115 <speciesReference species='X0'> 116 <stoichiometryMath> 117 <math xmlns='http://www.w3.org/1998/Math/MathML'> 118 <ci>x</ci> 119 </math> 120 </stoichiometryMath> 121 </speciesReference> 122 </listOfReactants> 123 ... 124 </reaction> 125 ... 126 </listOfReactions> 127 ... 128 </model> 129 </pre> 130 <p> 131 * <h2>SpeciesReference in SBML Level 3</h2> 132 <p> 133 * In Level 2's definition of a reaction, the stoichiometry attribute of a 134 * {@link SpeciesReference} is actually a combination of two factors, the standard 135 * biochemical stoichiometry and a conversion factor that may be needed to 136 * translate the units of the species quantity to the units of the reaction 137 * rate. Unfortunately, Level 2 offers no direct way of decoupling 138 * these two factors, or for explicitly indicating the units. The only way 139 * to do it in Level 2 is to use the {@link StoichiometryMath} object 140 * associated with SpeciesReferences, and to reference SBML {@link Parameter} 141 * objects from within the {@link StoichiometryMath} formula. This works because 142 * {@link Parameter} offers a way to attach units to a numerical value, but the 143 * solution is indirect and awkward for something that should be a simple 144 * matter. Moreover, the question of how to properly encode 145 * stoichiometries in SBML reactions has caused much confusion among 146 * implementors of SBML software. 147 <p> 148 * SBML Level 3 approaches this problem differently. It (1) extends 149 * the the use of the {@link SpeciesReference} identifier to represent the value of 150 * the 'stoichiometry' attribute, (2) makes the 'stoichiometry' attribute 151 * optional, (3) removes {@link StoichiometryMath}, and (4) adds a new 'constant' 152 * boolean attribute on {@link SpeciesReference}. 153 <p> 154 * As in Level 2, the 'stoichiometry' attribute is of type 155 * <code>double</code> and should contain values greater than zero (<code>0</code>). A 156 * missing 'stoichiometry' implies that the stoichiometry is either 157 * unknown, or to be obtained from an external source, or determined by an 158 * {@link InitialAssignment} object or other SBML construct elsewhere in the model. 159 <p> 160 * A species reference's stoichiometry is set by its 'stoichiometry' 161 * attribute exactly once. If the {@link SpeciesReference} object's 'constant' 162 * attribute has the value <code>true</code>, then the stoichiometry is fixed and 163 * cannot be changed except by an {@link InitialAssignment} object. These two 164 * methods of setting the stoichiometry (i.e., using 'stoichiometry' 165 * directly, or using {@link InitialAssignment}) differ in that the 'stoichiometry' 166 * attribute can only be set to a literal floating-point number, whereas 167 * {@link InitialAssignment} allows the value to be set using an arbitrary 168 * mathematical expression. (As an example, the approach could be used to 169 * set the stoichiometry to a rational number of the form <em>p</em>/<em>q</em>, 170 * where <em>p</em> and <em>q</em> are integers, something that is occasionally 171 * useful in the context of biochemical reaction networks.) If the species 172 * reference's 'constant' attribute has the value <code>false</code>, the species 173 * reference's value may be overridden by an {@link InitialAssignment} or changed 174 * by {@link AssignmentRule} or {@link AlgebraicRule}, and in addition, for simulation time 175 * <em>t > 0</em>, it may also be changed by a {@link RateRule} or {@link Event} 176 * objects. (However, some of these constructs are mutually exclusive; see 177 * the SBML Level 3 Core specifiation for more 178 * details.) It is not an error to define 'stoichiometry' on a species 179 * reference and also redefine the stoichiometry using an 180 * {@link InitialAssignment}, but the 'stoichiometry' attribute in that case is 181 * ignored. 182 <p> 183 * The value of the 'id' attribute of a {@link SpeciesReference} can be used as the 184 * content of a <code><ci></code> element in MathML formulas 185 * elsewhere in the model. When the identifier appears in a MathML 186 * <code><ci></code> element, it represents the stoichiometry of the 187 * corresponding species in the reaction where the {@link SpeciesReference} object 188 * instance appears. More specifically, it represents the value of the 189 * 'stoichiometry' attribute on the {@link SpeciesReference} object. 190 <p> 191 * In SBML Level 3, the unit of measurement associated with the value of a 192 * species' stoichiometry is always considered to be <code>dimensionless.</code> 193 * This has the following implications: 194 * <ul> 195 <p> 196 * <li> When a species reference's identifier appears in mathematical 197 * formulas elsewhere in the model, the unit associated with that value is 198 * <code>dimensionless.</code> 199 <p> 200 * <li> The units of the 'math' elements of {@link AssignmentRule}, 201 * {@link InitialAssignment} and {@link EventAssignment} objects setting the stoichiometry 202 * of the species reference should be <code>dimensionless.</code> 203 <p> 204 * <li> If a species reference's identifier is the subject of a {@link RateRule}, 205 * the unit associated with the {@link RateRule} object's value should be 206 * <code>dimensionless</code>/<em>time</em>, where <em>time</em> is the 207 * model-wide unit of time set on the {@link Model} object. 208 <p> 209 * </ul> 210 */ 211 212public class SpeciesReference extends SimpleSpeciesReference { 213 private long swigCPtr; 214 215 protected SpeciesReference(long cPtr, boolean cMemoryOwn) 216 { 217 super(libsbmlJNI.SpeciesReference_SWIGUpcast(cPtr), cMemoryOwn); 218 swigCPtr = cPtr; 219 } 220 221 protected static long getCPtr(SpeciesReference obj) 222 { 223 return (obj == null) ? 0 : obj.swigCPtr; 224 } 225 226 protected static long getCPtrAndDisown (SpeciesReference obj) 227 { 228 long ptr = 0; 229 230 if (obj != null) 231 { 232 ptr = obj.swigCPtr; 233 obj.swigCMemOwn = false; 234 } 235 236 return ptr; 237 } 238 239 protected void finalize() { 240 delete(); 241 } 242 243 public synchronized void delete() { 244 if (swigCPtr != 0) { 245 if (swigCMemOwn) { 246 swigCMemOwn = false; 247 libsbmlJNI.delete_SpeciesReference(swigCPtr); 248 } 249 swigCPtr = 0; 250 } 251 super.delete(); 252 } 253 254 255/** 256 * Creates a new {@link SpeciesReference} using the given SBML <code>level</code> and <code>version</code> 257 * values. 258 <p> 259 * @param level a long integer, the SBML Level to assign to this {@link SpeciesReference}. 260 <p> 261 * @param version a long integer, the SBML Version to assign to this 262 * {@link SpeciesReference}. 263 <p> 264 * <p> 265 * @throws SBMLConstructorException 266 * Thrown if the given <code>level</code> and <code>version</code> combination are invalid 267 * or if this object is incompatible with the given level and version. 268 <p> 269 * <p> 270 * @note Attempting to add an object to an {@link SBMLDocument} having a different 271 * combination of SBML Level, Version and XML namespaces than the object 272 * itself will result in an error at the time a caller attempts to make the 273 * addition. A parent object must have compatible Level, Version and XML 274 * namespaces. (Strictly speaking, a parent may also have more XML 275 * namespaces than a child, but the reverse is not permitted.) The 276 * restriction is necessary to ensure that an SBML model has a consistent 277 * overall structure. This requires callers to manage their objects 278 * carefully, but the benefit is increased flexibility in how models can be 279 * created by permitting callers to create objects bottom-up if desired. In 280 * situations where objects are not yet attached to parents (e.g., 281 * {@link SBMLDocument}), knowledge of the intented SBML Level and Version help 282 * libSBML determine such things as whether it is valid to assign a 283 * particular value to an attribute. 284 */ public 285 SpeciesReference(long level, long version) throws org.sbml.libsbml.SBMLConstructorException { 286 this(libsbmlJNI.new_SpeciesReference__SWIG_0(level, version), true); 287 } 288 289 290/** 291 * Creates a new {@link SpeciesReference} using the given {@link SBMLNamespaces} object 292 * <code>sbmlns</code>. 293 <p> 294 * @param sbmlns an {@link SBMLNamespaces} object. 295 <p> 296 * <p> 297 * @throws SBMLConstructorException 298 * Thrown if the given <code>sbmlns</code> is inconsistent or incompatible 299 * with this object. 300 <p> 301 * <p> 302 * @note Attempting to add an object to an {@link SBMLDocument} having a different 303 * combination of SBML Level, Version and XML namespaces than the object 304 * itself will result in an error at the time a caller attempts to make the 305 * addition. A parent object must have compatible Level, Version and XML 306 * namespaces. (Strictly speaking, a parent may also have more XML 307 * namespaces than a child, but the reverse is not permitted.) The 308 * restriction is necessary to ensure that an SBML model has a consistent 309 * overall structure. This requires callers to manage their objects 310 * carefully, but the benefit is increased flexibility in how models can be 311 * created by permitting callers to create objects bottom-up if desired. In 312 * situations where objects are not yet attached to parents (e.g., 313 * {@link SBMLDocument}), knowledge of the intented SBML Level and Version help 314 * libSBML determine such things as whether it is valid to assign a 315 * particular value to an attribute. 316 */ public 317 SpeciesReference(SBMLNamespaces sbmlns) throws org.sbml.libsbml.SBMLConstructorException { 318 this(libsbmlJNI.new_SpeciesReference__SWIG_1(SBMLNamespaces.getCPtr(sbmlns), sbmlns), true); 319 } 320 321 322/** 323 * Copy constructor; creates a copy of this {@link SpeciesReference}. 324 <p> 325 * @param orig the {@link SpeciesReference} instance to copy. 326 */ public 327 SpeciesReference(SpeciesReference orig) throws org.sbml.libsbml.SBMLConstructorException { 328 this(libsbmlJNI.new_SpeciesReference__SWIG_2(SpeciesReference.getCPtr(orig), orig), true); 329 } 330 331 332/** 333 * Creates and returns a deep copy of this {@link SpeciesReference} object. 334 <p> 335 * @return the (deep) copy of this {@link SpeciesReference} object. 336 */ public 337 SpeciesReference cloneObject() { 338 long cPtr = libsbmlJNI.SpeciesReference_cloneObject(swigCPtr, this); 339 return (cPtr == 0) ? null : new SpeciesReference(cPtr, true); 340 } 341 342 343/** 344 * Initializes the fields of this {@link SpeciesReference} object to 'typical' 345 * default values. 346 <p> 347 * The SBML {@link SpeciesReference} component has slightly different aspects and 348 * default attribute values in different SBML Levels and Versions. 349 * This method sets the values to certain common defaults, based 350 * mostly on what they are in SBML Level 2. Specifically: 351 * <ul> 352 * <li> Sets attribute 'stoichiometry' to <code>1.0</code> 353 * <li> (Applies to Level 1 models only) Sets attribute 'denominator' to <code>1</code> 354 * </ul> 355 <p> 356 * @see #getDenominator() 357 * @see #setDenominator(int value) 358 * @see #getStoichiometry() 359 * @see #setStoichiometry(double value) 360 * @see #getStoichiometryMath() 361 * @see #setStoichiometryMath(StoichiometryMath math) 362 */ public 363 void initDefaults() { 364 libsbmlJNI.SpeciesReference_initDefaults(swigCPtr, this); 365 } 366 367 368/** 369 * Get the value of the 'stoichiometry' attribute. 370 <p> 371 * In SBML Level 2, product and reactant stoichiometries can be specified 372 * using <em>either</em> 'stoichiometry' or 'stoichiometryMath' in a 373 * {@link SpeciesReference} object. The former is to be used when a 374 * stoichiometry is simply a scalar number, while the latter is for 375 * occasions when it needs to be a rational number or it needs to 376 * reference other mathematical expressions. The 'stoichiometry' 377 * attribute is of type <code>double</code> and should contain values greater than 378 * zero (<code>0</code>). The 'stoichiometryMath' element is implemented as an 379 * element containing a MathML expression. These two are mutually 380 * exclusive; only one of 'stoichiometry' or 'stoichiometryMath' should 381 * be defined in a given {@link SpeciesReference} instance. When neither the 382 * attribute nor the element is present, the value of 'stoichiometry' in 383 * the {@link SpeciesReference} instance defaults to <code>1.</code> For maximum 384 * interoperability between different software tools, the 'stoichiometry' 385 * attribute should be used in preference to 'stoichiometryMath' when a 386 * species' stoichiometry is a simple scalar number (integer or 387 * decimal). 388 <p> 389 * In SBML Level 3, there is no {@link StoichiometryMath}, and {@link SpeciesReference} 390 * objects have only the 'stoichiometry' attribute. 391 <p> 392 * @return the value of the (scalar) 'stoichiometry' attribute of this 393 * {@link SpeciesReference}. 394 <p> 395 * @see #getStoichiometryMath() 396 */ public 397 double getStoichiometry() { 398 return libsbmlJNI.SpeciesReference_getStoichiometry(swigCPtr, this); 399 } 400 401 402/** 403 * Get the content of the 'stoichiometryMath' subelement as an {@link ASTNode} 404 * tree. 405 <p> 406 * The 'stoichiometryMath' element exists only in SBML Level 2. There, 407 * product and reactant stoichiometries can be specified using 408 * <em>either</em> 'stoichiometry' or 'stoichiometryMath' in a 409 * {@link SpeciesReference} object. The former is to be used when a 410 * stoichiometry is simply a scalar number, while the latter is for 411 * occasions when it needs to be a rational number or it needs to 412 * reference other mathematical expressions. The 'stoichiometry' 413 * attribute is of type <code>double</code> and should contain values greater than 414 * zero (<code>0</code>). The 'stoichiometryMath' element is implemented as an 415 * element containing a MathML expression. These two are mutually 416 * exclusive; only one of 'stoichiometry' or 'stoichiometryMath' should 417 * be defined in a given {@link SpeciesReference} instance. When neither the 418 * attribute nor the element is present, the value of 'stoichiometry' in 419 * the {@link SpeciesReference} instance defaults to <code>1.</code> For maximum 420 * interoperability between different software tools, the 'stoichiometry' 421 * attribute should be used in preference to 'stoichiometryMath' when a 422 * species' stoichiometry is a simple scalar number (integer or decimal). 423 <p> 424 * @return the content of the 'stoichiometryMath' subelement of this 425 * {@link SpeciesReference}. 426 */ public 427 StoichiometryMath getStoichiometryMath() { 428 long cPtr = libsbmlJNI.SpeciesReference_getStoichiometryMath__SWIG_0(swigCPtr, this); 429 return (cPtr == 0) ? null : new StoichiometryMath(cPtr, false); 430 } 431 432 433/** 434 * Get the value of the 'denominator' attribute, for the case of a 435 * rational-numbered stoichiometry or a model in SBML Level 1. 436 <p> 437 * The 'denominator' attribute is only actually written out in the case 438 * of an SBML Level 1 model. In SBML Level 2, rational-number 439 * stoichiometries are written as MathML elements in the 440 * 'stoichiometryMath' subelement. However, as a convenience to users, 441 * libSBML allows the creation and manipulation of rational-number 442 * stoichiometries by supplying the numerator and denominator directly 443 * rather than having to manually create an {@link ASTNode} object. LibSBML 444 * will write out the appropriate constructs (either a combination of 445 * 'stoichiometry' and 'denominator' in the case of SBML Level 1, or a 446 * 'stoichiometryMath' subelement in the case of SBML Level 2). 447 <p> 448 * @return the value of the 'denominator' attribute of this 449 * {@link SpeciesReference}. 450 */ public 451 int getDenominator() { 452 return libsbmlJNI.SpeciesReference_getDenominator(swigCPtr, this); 453 } 454 455 456/** 457 * Get the value of the 'constant' attribute. 458 <p> 459 * @return the value of the 'constant' attribute of this 460 * {@link SpeciesReference}. 461 */ public 462 boolean getConstant() { 463 return libsbmlJNI.SpeciesReference_getConstant(swigCPtr, this); 464 } 465 466 467/** 468 * Predicate returning <code>true</code> if this 469 * {@link SpeciesReference}'s 'stoichiometryMath' subelement is set 470 <p> 471 * @return <code>true</code> if the 'stoichiometryMath' subelement of this 472 * {@link SpeciesReference} is set, <code>false</code> otherwise. 473 */ public 474 boolean isSetStoichiometryMath() { 475 return libsbmlJNI.SpeciesReference_isSetStoichiometryMath(swigCPtr, this); 476 } 477 478 479/** 480 * Predicate returning <code>true</code> if this 481 * {@link SpeciesReference}'s 'constant' attribute is set 482 <p> 483 * @return <code>true</code> if the 'constant' attribute of this 484 * {@link SpeciesReference} is set, <code>false</code> otherwise. 485 */ public 486 boolean isSetConstant() { 487 return libsbmlJNI.SpeciesReference_isSetConstant(swigCPtr, this); 488 } 489 490 491/** 492 * Predicate returning <code>true</code> if this 493 * {@link SpeciesReference}'s 'stoichiometry' attribute is set. 494 <p> 495 * @return <code>true</code> if the 'stoichiometry' attribute of this 496 * {@link SpeciesReference} is set, <code>false</code> otherwise. 497 */ public 498 boolean isSetStoichiometry() { 499 return libsbmlJNI.SpeciesReference_isSetStoichiometry(swigCPtr, this); 500 } 501 502 503/** 504 * Sets the value of the 'stoichiometry' attribute of this 505 * {@link SpeciesReference}. 506 <p> 507 * In SBML Level 2, product and reactant stoichiometries can be specified 508 * using <em>either</em> 'stoichiometry' or 'stoichiometryMath' in a 509 * {@link SpeciesReference} object. The former is to be used when a 510 * stoichiometry is simply a scalar number, while the latter is for 511 * occasions when it needs to be a rational number or it needs to 512 * reference other mathematical expressions. The 'stoichiometry' 513 * attribute is of type <code>double</code> and should contain values greater than 514 * zero (<code>0</code>). The 'stoichiometryMath' element is implemented as an 515 * element containing a MathML expression. These two are mutually 516 * exclusive; only one of 'stoichiometry' or 'stoichiometryMath' should 517 * be defined in a given {@link SpeciesReference} instance. When neither the 518 * attribute nor the element is present, the value of 'stoichiometry' in 519 * the {@link SpeciesReference} instance defaults to <code>1.</code> For maximum 520 * interoperability between different software tools, the 'stoichiometry' 521 * attribute should be used in preference to 'stoichiometryMath' when a 522 * species' stoichiometry is a simple scalar number (integer or 523 * decimal). 524 <p> 525 * In SBML Level 3, there is no {@link StoichiometryMath}, and {@link SpeciesReference} 526 * objects have only the 'stoichiometry' attribute. 527 <p> 528 * @param value the new value of the 'stoichiometry' attribute. 529 <p> 530 * @note In SBML Level 2, the 'stoichiometryMath' subelement of this 531 * {@link SpeciesReference} object will be unset because the 'stoichiometry' 532 * attribute and the stoichiometryMath' subelement are mutually 533 * exclusive. 534 <p> 535 * <p> 536 * @return integer value indicating success/failure of the 537 * function. The possible values 538 * returned by this function are: 539 * <ul> 540 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 541 * </ul> 542 */ public 543 int setStoichiometry(double value) { 544 return libsbmlJNI.SpeciesReference_setStoichiometry(swigCPtr, this, value); 545 } 546 547 548/** 549 * Sets the 'stoichiometryMath' subelement of this {@link SpeciesReference}. 550 <p> 551 * The Abstract Syntax Tree in <code>math</code> is copied. 552 <p> 553 * In SBML Level 2, product and reactant stoichiometries can be specified 554 * using <em>either</em> 'stoichiometry' or 'stoichiometryMath' in a 555 * {@link SpeciesReference} object. The former is to be used when a 556 * stoichiometry is simply a scalar number, while the latter is for 557 * occasions when it needs to be a rational number or it needs to 558 * reference other mathematical expressions. The 'stoichiometry' 559 * attribute is of type <code>double</code> and should contain values greater than 560 * zero (<code>0</code>). The 'stoichiometryMath' element is implemented as an 561 * element containing a MathML expression. These two are mutually 562 * exclusive; only one of 'stoichiometry' or 'stoichiometryMath' should 563 * be defined in a given {@link SpeciesReference} instance. When neither the 564 * attribute nor the element is present, the value of 'stoichiometry' in 565 * the {@link SpeciesReference} instance defaults to <code>1.</code> For maximum 566 * interoperability between different software tools, the 'stoichiometry' 567 * attribute should be used in preference to 'stoichiometryMath' when a 568 * species' stoichiometry is a simple scalar number (integer or 569 * decimal). 570 <p> 571 * In SBML Level 3, there is no {@link StoichiometryMath}, and {@link SpeciesReference} 572 * objects have only the 'stoichiometry' attribute. 573 <p> 574 * @param math the {@link StoichiometryMath} expression that is to be copied as the 575 * content of the 'stoichiometryMath' subelement. 576 <p> 577 * @note In SBML Level 2, the 'stoichiometry' attribute of this 578 * {@link SpeciesReference} object will be unset (isSetStoichiometry() will 579 * return <code>false</code> although getStoichiometry() will return <code>1.0</code>) if the 580 * given math is not null because the 'stoichiometry' attribute and the 581 * stoichiometryMath' subelement are mutually exclusive. 582 <p> 583 * <p> 584 * @return integer value indicating success/failure of the 585 * function. The possible values 586 * returned by this function are: 587 * <ul> 588 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 589 * <li> {@link libsbmlConstants#LIBSBML_UNEXPECTED_ATTRIBUTE LIBSBML_UNEXPECTED_ATTRIBUTE} 590 * <li> {@link libsbmlConstants#LIBSBML_LEVEL_MISMATCH LIBSBML_LEVEL_MISMATCH} 591 * <li> {@link libsbmlConstants#LIBSBML_VERSION_MISMATCH LIBSBML_VERSION_MISMATCH} 592 * </ul> 593 */ public 594 int setStoichiometryMath(StoichiometryMath math) { 595 return libsbmlJNI.SpeciesReference_setStoichiometryMath(swigCPtr, this, StoichiometryMath.getCPtr(math), math); 596 } 597 598 599/** 600 * Set the value of the 'denominator' attribute, for the case of a 601 * rational-numbered stoichiometry or a model in SBML Level 1. 602 <p> 603 * The 'denominator' attribute is only actually written out in the case 604 * of an SBML Level 1 model. In SBML Level 2, rational-number 605 * stoichiometries are written as MathML elements in the 606 * 'stoichiometryMath' subelement. However, as a convenience to users, 607 * libSBML allows the creation and manipulation of rational-number 608 * stoichiometries by supplying the numerator and denominator directly 609 * rather than having to manually create an {@link ASTNode} object. LibSBML 610 * will write out the appropriate constructs (either a combination of 611 * 'stoichiometry' and 'denominator' in the case of SBML Level 1, or 612 * a 'stoichiometryMath' subelement in the case of SBML Level 2). 613 <p> 614 * @param value the scalar value. 615 <p> 616 * <p> 617 * @return integer value indicating success/failure of the 618 * function. The possible values 619 * returned by this function are: 620 * <ul> 621 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 622 * </ul> 623 */ public 624 int setDenominator(int value) { 625 return libsbmlJNI.SpeciesReference_setDenominator(swigCPtr, this, value); 626 } 627 628 629/** 630 * Sets the 'constant' attribute of this {@link SpeciesReference} to the given boolean 631 * <code>flag</code>. 632 <p> 633 * @param flag a boolean, the value for the 'constant' attribute of this 634 * {@link SpeciesReference} instance. 635 <p> 636 * <p> 637 * @return integer value indicating success/failure of the 638 * function. The possible values 639 * returned by this function are: 640 * <ul> 641 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 642 * <li> {@link libsbmlConstants#LIBSBML_UNEXPECTED_ATTRIBUTE LIBSBML_UNEXPECTED_ATTRIBUTE} 643 * </ul> 644 */ public 645 int setConstant(boolean flag) { 646 return libsbmlJNI.SpeciesReference_setConstant(swigCPtr, this, flag); 647 } 648 649 650/** 651 * Unsets the 'stoichiometryMath' subelement of this {@link SpeciesReference}. 652 <p> 653 * <p> 654 * @return integer value indicating success/failure of the 655 * function. The possible values 656 * returned by this function are: 657 * <ul> 658 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 659 * <li> {@link libsbmlConstants#LIBSBML_UNEXPECTED_ATTRIBUTE LIBSBML_UNEXPECTED_ATTRIBUTE} 660 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED} 661 * 662 * </ul> <p> 663 * In SBML Level 2, product and reactant stoichiometries can be specified 664 * using <em>either</em> 'stoichiometry' or 'stoichiometryMath' in a 665 * {@link SpeciesReference} object. The former is to be used when a 666 * stoichiometry is simply a scalar number, while the latter is for 667 * occasions when it needs to be a rational number or it needs to 668 * reference other mathematical expressions. The 'stoichiometry' 669 * attribute is of type <code>double</code> and should contain values greater than 670 * zero (<code>0</code>). The 'stoichiometryMath' element is implemented as an 671 * element containing a MathML expression. These two are mutually 672 * exclusive; only one of 'stoichiometry' or 'stoichiometryMath' should 673 * be defined in a given {@link SpeciesReference} instance. When neither the 674 * attribute nor the element is present, the value of 'stoichiometry' in 675 * the {@link SpeciesReference} instance defaults to <code>1.</code> For maximum 676 * interoperability between different software tools, the 'stoichiometry' 677 * attribute should be used in preference to 'stoichiometryMath' when a 678 * species' stoichiometry is a simple scalar number (integer or 679 * decimal). 680 <p> 681 * In SBML Level 3, there is no {@link StoichiometryMath}, and {@link SpeciesReference} 682 * objects have only the 'stoichiometry' attribute. 683 <p> 684 * @note In SBML Level 2, the 'stoichiometry' attribute of this 685 * {@link SpeciesReference} object will be reset to a default value (<code>1.0</code>) if 686 * the 'stoichiometry' attribute has not been set. 687 */ public 688 int unsetStoichiometryMath() { 689 return libsbmlJNI.SpeciesReference_unsetStoichiometryMath(swigCPtr, this); 690 } 691 692 693/** 694 * Unsets the 'stoichiometry' attribute of this {@link SpeciesReference}. 695 <p> 696 * <p> 697 * @return integer value indicating success/failure of the 698 * function. The possible values 699 * returned by this function are: 700 * <ul> 701 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 702 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED} 703 * 704 * </ul> <p> 705 * @note In SBML Level 1, the 'stoichiometry' attribute of this 706 * {@link SpeciesReference} object will be just reset to a default value (<code>1.0</code>) 707 * and isSetStoichiometry() will still return <code>true.</code> In SBML 708 * Level 2, the 'stoichiometry' attribute of this object will be 709 * unset (which will result in isSetStoichiometry() returning <code>false</code>, 710 * although getStoichiometry() will return <code>1.0</code>) if the 711 * 'stoichiometryMath' subelement is set, otherwise the attribute 712 * will be just reset to the default value (<code>1.0</code>) (and 713 * isSetStoichiometry() will still return <code>true</code>). In SBML 714 * Level 3, the 'stoichiometry' attribute of this object will be set 715 * to <code>NaN</code> and isSetStoichiometry() will return <code>false.</code> 716 */ public 717 int unsetStoichiometry() { 718 return libsbmlJNI.SpeciesReference_unsetStoichiometry(swigCPtr, this); 719 } 720 721 722/** 723 * Unsets the 'constant' attribute of this {@link SpeciesReference}. 724 <p> 725 * <p> 726 * @return integer value indicating success/failure of the 727 * function. The possible values 728 * returned by this function are: 729 * <ul> 730 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 731 * <li> {@link libsbmlConstants#LIBSBML_UNEXPECTED_ATTRIBUTE LIBSBML_UNEXPECTED_ATTRIBUTE} 732 * </ul> 733 */ public 734 int unsetConstant() { 735 return libsbmlJNI.SpeciesReference_unsetConstant(swigCPtr, this); 736 } 737 738 739/** 740 * Creates a new, empty {@link StoichiometryMath} object, adds it to this 741 * {@link SpeciesReference}, and returns it. 742 <p> 743 * @return the newly created {@link StoichiometryMath} object instance. 744 <p> 745 * @see Reaction#addReactant(SpeciesReference sr) 746 * @see Reaction#addProduct(SpeciesReference sr) 747 */ public 748 StoichiometryMath createStoichiometryMath() { 749 long cPtr = libsbmlJNI.SpeciesReference_createStoichiometryMath(swigCPtr, this); 750 return (cPtr == 0) ? null : new StoichiometryMath(cPtr, false); 751 } 752 753 754/** 755 * Sets the value of the 'annotation' subelement of this SBML object to a 756 * copy of <code>annotation</code>. 757 <p> 758 * Any existing content of the 'annotation' subelement is discarded. 759 * Unless you have taken steps to first copy and reconstitute any 760 * existing annotations into the <code>annotation</code> that is about to be 761 * assigned, it is likely that performing such wholesale replacement is 762 * unfriendly towards other software applications whose annotations are 763 * discarded. An alternative may be to use appendAnnotation(). 764 <p> 765 * @param annotation an XML structure that is to be used as the content 766 * of the 'annotation' subelement of this object. 767 <p> 768 * <p> 769 * @return integer value indicating success/failure of the 770 * function. This particular 771 * function only does one thing irrespective of user input or 772 * object state, and thus will only return a single value: 773 * <ul> 774 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 775 * 776 * </ul> <p> 777 * @see #appendAnnotation(XMLNode annotation) 778 * @see #appendAnnotation(String annotation) 779 */ public 780 int setAnnotation(XMLNode annotation) { 781 return libsbmlJNI.SpeciesReference_setAnnotation__SWIG_0(swigCPtr, this, XMLNode.getCPtr(annotation), annotation); 782 } 783 784 785/** 786 * Sets the value of the 'annotation' subelement of this SBML object to a 787 * copy of <code>annotation</code>. 788 <p> 789 * Any existing content of the 'annotation' subelement is discarded. 790 * Unless you have taken steps to first copy and reconstitute any 791 * existing annotations into the <code>annotation</code> that is about to be 792 * assigned, it is likely that performing such wholesale replacement is 793 * unfriendly towards other software applications whose annotations are 794 * discarded. An alternative may be to use appendAnnotation(). 795 <p> 796 * @param annotation an XML string that is to be used as the content 797 * of the 'annotation' subelement of this object. 798 <p> 799 * <p> 800 * @return integer value indicating success/failure of the 801 * function. The possible values 802 * returned by this function are: 803 * <ul> 804 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 805 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED} 806 * 807 * </ul> <p> 808 * @see #appendAnnotation(XMLNode annotation) 809 * @see #appendAnnotation(String annotation) 810 */ public 811 int setAnnotation(String annotation) { 812 return libsbmlJNI.SpeciesReference_setAnnotation__SWIG_1(swigCPtr, this, annotation); 813 } 814 815 816/** 817 * Appends annotation content to any existing content in the 'annotation' 818 * subelement of this object. 819 <p> 820 * The content in <code>annotation</code> is copied. Unlike 821 * {@link SpeciesReference#setAnnotation(String)}, 822 * this method allows other annotations to be preserved when an application 823 * adds its own data. 824 <p> 825 * @param annotation an XML structure that is to be copied and appended 826 * to the content of the 'annotation' subelement of this object. 827 <p> 828 * <p> 829 * @return integer value indicating success/failure of the 830 * function. The possible values 831 * returned by this function are: 832 * <ul> 833 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 834 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED} 835 * 836 * </ul> <p> 837 * @see #setAnnotation(String annotation) 838 * @see #setAnnotation(XMLNode annotation) 839 */ public 840 int appendAnnotation(XMLNode annotation) { 841 return libsbmlJNI.SpeciesReference_appendAnnotation__SWIG_0(swigCPtr, this, XMLNode.getCPtr(annotation), annotation); 842 } 843 844 845/** 846 * Appends annotation content to any existing content in the 'annotation' 847 * subelement of this object. 848 <p> 849 * The content in <code>annotation</code> is copied. Unlike 850 * {@link SpeciesReference#setAnnotation(String)}, this 851 * method allows other annotations to be preserved when an application 852 * adds its own data. 853 <p> 854 * @param annotation an XML string that is to be copied and appended 855 * to the content of the 'annotation' subelement of this object. 856 <p> 857 * <p> 858 * @return integer value indicating success/failure of the 859 * function. The possible values 860 * returned by this function are: 861 * <ul> 862 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 863 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED} 864 * 865 * </ul> <p> 866 * @see #setAnnotation(String annotation) 867 * @see #setAnnotation(XMLNode annotation) 868 */ public 869 int appendAnnotation(String annotation) { 870 return libsbmlJNI.SpeciesReference_appendAnnotation__SWIG_1(swigCPtr, this, annotation); 871 } 872 873 874/** 875 * Returns the libSBML type code for this SBML object. 876 <p> 877 * <p> 878 * LibSBML attaches an identifying code to every kind of SBML object. These 879 * are integer constants known as <em>SBML type codes</em>. The names of all 880 * the codes begin with the characters <code>SBML_</code>. 881 * In the Java language interface for libSBML, the 882 * type codes are defined as static integer constants in the interface class 883 * {@link libsbmlConstants}. Note that different Level 3 884 * package plug-ins may use overlapping type codes; to identify the package 885 * to which a given object belongs, call the <code>getPackageName()</code> 886 * method on the object. 887 <p> 888 * @return the SBML type code for this object: 889 * {@link libsbmlConstants#SBML_SPECIES_REFERENCE SBML_SPECIES_REFERENCE} (default). 890 <p> 891 * @see #getElementName() 892 * @see #getPackageName() 893 */ public 894 int getTypeCode() { 895 return libsbmlJNI.SpeciesReference_getTypeCode(swigCPtr, this); 896 } 897 898 899/** 900 * Returns the XML element name of this object, which for 901 * {@link SpeciesReference}, is always <code>'speciesReference'.</code> 902 <p> 903 * @return the name of this element, i.e., <code>'speciesReference'.</code> 904 */ public 905 String getElementName() { 906 return libsbmlJNI.SpeciesReference_getElementName(swigCPtr, this); 907 } 908 909 910/** 911 * Predicate returning <code>true</code> if 912 * all the required attributes for this {@link SpeciesReference} object 913 * have been set. 914 <p> 915 * The required attributes for a {@link SpeciesReference} object are: 916 * <ul> 917 * <li> 'species' 918 * <li> 'constant' (only available SBML Level 3) 919 * 920 * </ul> <p> 921 * @return <code>true</code> if the required attributes have been set, <code>false</code> 922 * otherwise. 923 */ public 924 boolean hasRequiredAttributes() { 925 return libsbmlJNI.SpeciesReference_hasRequiredAttributes(swigCPtr, this); 926 } 927 928}