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