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