001/* ---------------------------------------------------------------------------- 002 * This file was automatically generated by SWIG (http://www.swig.org). 003 * Version 3.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 * 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 <code>0</code> (false). 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 * However, as the 'stoichiometryMath' subelement was removed in SBML 448 * Level 3, automatic translation of the 'denominator' 449 * attribute is no longer supported for that level. 450 <p> 451 * @return the value of the 'denominator' attribute of this 452 * {@link SpeciesReference}. 453 */ public 454 int getDenominator() { 455 return libsbmlJNI.SpeciesReference_getDenominator(swigCPtr, this); 456 } 457 458 459/** 460 * Get the value of the 'constant' attribute. 461 <p> 462 * @return the value of the 'constant' attribute of this 463 * {@link SpeciesReference}. 464 */ public 465 boolean getConstant() { 466 return libsbmlJNI.SpeciesReference_getConstant(swigCPtr, this); 467 } 468 469 470/** 471 * Predicate returning <code>true</code> if this 472 * {@link SpeciesReference}'s 'stoichiometryMath' subelement is set 473 <p> 474 * @return <code>true</code> if the 'stoichiometryMath' subelement of this 475 * {@link SpeciesReference} is set, <code>false</code> otherwise. 476 */ public 477 boolean isSetStoichiometryMath() { 478 return libsbmlJNI.SpeciesReference_isSetStoichiometryMath(swigCPtr, this); 479 } 480 481 482/** 483 * Predicate returning <code>true</code> if this 484 * {@link SpeciesReference}'s 'constant' attribute is set 485 <p> 486 * @return <code>true</code> if the 'constant' attribute of this 487 * {@link SpeciesReference} is set, <code>false</code> otherwise. 488 */ public 489 boolean isSetConstant() { 490 return libsbmlJNI.SpeciesReference_isSetConstant(swigCPtr, this); 491 } 492 493 494/** 495 * Predicate returning <code>true</code> if this 496 * {@link SpeciesReference}'s 'stoichiometry' attribute is set. 497 <p> 498 * @return <code>true</code> if the 'stoichiometry' attribute of this 499 * {@link SpeciesReference} is set, <code>false</code> otherwise. 500 */ public 501 boolean isSetStoichiometry() { 502 return libsbmlJNI.SpeciesReference_isSetStoichiometry(swigCPtr, this); 503 } 504 505 506/** 507 * Sets the value of the 'stoichiometry' attribute of this 508 * {@link SpeciesReference}. 509 <p> 510 * In SBML Level 2, product and reactant stoichiometries can be specified 511 * using <em>either</em> 'stoichiometry' or 'stoichiometryMath' in a 512 * {@link SpeciesReference} object. The former is to be used when a 513 * stoichiometry is simply a scalar number, while the latter is for 514 * occasions when it needs to be a rational number or it needs to 515 * reference other mathematical expressions. The 'stoichiometry' 516 * attribute is of type <code>double</code> and should contain values greater than 517 * zero (<code>0</code>). The 'stoichiometryMath' element is implemented as an 518 * element containing a MathML expression. These two are mutually 519 * exclusive; only one of 'stoichiometry' or 'stoichiometryMath' should 520 * be defined in a given {@link SpeciesReference} instance. When neither the 521 * attribute nor the element is present, the value of 'stoichiometry' in 522 * the {@link SpeciesReference} instance defaults to <code>1.</code> For maximum 523 * interoperability between different software tools, the 'stoichiometry' 524 * attribute should be used in preference to 'stoichiometryMath' when a 525 * species' stoichiometry is a simple scalar number (integer or 526 * decimal). 527 <p> 528 * In SBML Level 3, there is no {@link StoichiometryMath}, and {@link SpeciesReference} 529 * objects have only the 'stoichiometry' attribute. 530 <p> 531 * @param value the new value of the 'stoichiometry' attribute. 532 <p> 533 * @note In SBML Level 2, the 'stoichiometryMath' subelement of this 534 * {@link SpeciesReference} object will be unset because the 'stoichiometry' 535 * attribute and the stoichiometryMath' subelement are mutually 536 * exclusive. 537 <p> 538 * <p> 539 * @return integer value indicating success/failure of the 540 * function. The possible values 541 * returned by this function are: 542 * <ul> 543 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 544 * </ul> 545 */ public 546 int setStoichiometry(double value) { 547 return libsbmlJNI.SpeciesReference_setStoichiometry(swigCPtr, this, value); 548 } 549 550 551/** 552 * Sets the 'stoichiometryMath' subelement of this {@link SpeciesReference}. 553 <p> 554 * The Abstract Syntax Tree in <code>math</code> is copied. 555 <p> 556 * In SBML Level 2, product and reactant stoichiometries can be specified 557 * using <em>either</em> 'stoichiometry' or 'stoichiometryMath' in a 558 * {@link SpeciesReference} object. The former is to be used when a 559 * stoichiometry is simply a scalar number, while the latter is for 560 * occasions when it needs to be a rational number or it needs to 561 * reference other mathematical expressions. The 'stoichiometry' 562 * attribute is of type <code>double</code> and should contain values greater than 563 * zero (<code>0</code>). The 'stoichiometryMath' element is implemented as an 564 * element containing a MathML expression. These two are mutually 565 * exclusive; only one of 'stoichiometry' or 'stoichiometryMath' should 566 * be defined in a given {@link SpeciesReference} instance. When neither the 567 * attribute nor the element is present, the value of 'stoichiometry' in 568 * the {@link SpeciesReference} instance defaults to <code>1.</code> For maximum 569 * interoperability between different software tools, the 'stoichiometry' 570 * attribute should be used in preference to 'stoichiometryMath' when a 571 * species' stoichiometry is a simple scalar number (integer or 572 * decimal). 573 <p> 574 * In SBML Level 3, there is no {@link StoichiometryMath}, and {@link SpeciesReference} 575 * objects have only the 'stoichiometry' attribute. 576 <p> 577 * @param math the {@link StoichiometryMath} expression that is to be copied as the 578 * content of the 'stoichiometryMath' subelement. 579 <p> 580 * @note In SBML Level 2, the 'stoichiometry' attribute of this 581 * {@link SpeciesReference} object will be unset (isSetStoichiometry() will 582 * return <code>false</code> although getStoichiometry() will return <code>1.0</code>) if the 583 * given math is not null because the 'stoichiometry' attribute and the 584 * stoichiometryMath' subelement are mutually exclusive. 585 <p> 586 * <p> 587 * @return integer value indicating success/failure of the 588 * function. The possible values 589 * returned by this function are: 590 * <ul> 591 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 592 * <li> {@link libsbmlConstants#LIBSBML_UNEXPECTED_ATTRIBUTE LIBSBML_UNEXPECTED_ATTRIBUTE} 593 * <li> {@link libsbmlConstants#LIBSBML_LEVEL_MISMATCH LIBSBML_LEVEL_MISMATCH} 594 * <li> {@link libsbmlConstants#LIBSBML_VERSION_MISMATCH LIBSBML_VERSION_MISMATCH} 595 * </ul> 596 */ public 597 int setStoichiometryMath(StoichiometryMath math) { 598 return libsbmlJNI.SpeciesReference_setStoichiometryMath(swigCPtr, this, StoichiometryMath.getCPtr(math), math); 599 } 600 601 602/** 603 * Set the value of the 'denominator' attribute, for the case of a 604 * rational-numbered stoichiometry or a model in SBML Level 1. 605 <p> 606 * The 'denominator' attribute is only actually written out in the case 607 * of an SBML Level 1 model. In SBML Level 2, rational-number 608 * stoichiometries are written as MathML elements in the 609 * 'stoichiometryMath' subelement. However, as a convenience to users, 610 * libSBML allows the creation and manipulation of rational-number 611 * stoichiometries by supplying the numerator and denominator directly 612 * rather than having to manually create an {@link ASTNode} object. LibSBML 613 * will write out the appropriate constructs (either a combination of 614 * 'stoichiometry' and 'denominator' in the case of SBML Level 1, or 615 * a 'stoichiometryMath' subelement in the case of SBML Level 2). 616 * However, as the 'stoichiometryMath' subelement was removed in SBML 617 * Level 3, automatic translation of the 'denominator' 618 * attribute is no longer supported for that level. 619 <p> 620 * @param value the scalar value. 621 <p> 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 setDenominator(int value) { 632 return libsbmlJNI.SpeciesReference_setDenominator(swigCPtr, this, value); 633 } 634 635 636/** 637 * Sets the 'constant' attribute of this {@link SpeciesReference} to the given boolean 638 * <code>flag</code>. 639 <p> 640 * @param flag a boolean, the value for the 'constant' attribute of this 641 * {@link SpeciesReference} instance. 642 <p> 643 * <p> 644 * @return integer value indicating success/failure of the 645 * function. The possible values 646 * returned by this function are: 647 * <ul> 648 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 649 * <li> {@link libsbmlConstants#LIBSBML_UNEXPECTED_ATTRIBUTE LIBSBML_UNEXPECTED_ATTRIBUTE} 650 * </ul> 651 */ public 652 int setConstant(boolean flag) { 653 return libsbmlJNI.SpeciesReference_setConstant(swigCPtr, this, flag); 654 } 655 656 657/** 658 * Unsets the 'stoichiometryMath' subelement of this {@link SpeciesReference}. 659 <p> 660 * <p> 661 * @return integer value indicating success/failure of the 662 * function. The possible values 663 * returned by this function are: 664 * <ul> 665 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 666 * <li> {@link libsbmlConstants#LIBSBML_UNEXPECTED_ATTRIBUTE LIBSBML_UNEXPECTED_ATTRIBUTE} 667 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED} 668 * 669 * </ul> <p> 670 * In SBML Level 2, product and reactant stoichiometries can be specified 671 * using <em>either</em> 'stoichiometry' or 'stoichiometryMath' in a 672 * {@link SpeciesReference} object. The former is to be used when a 673 * stoichiometry is simply a scalar number, while the latter is for 674 * occasions when it needs to be a rational number or it needs to 675 * reference other mathematical expressions. The 'stoichiometry' 676 * attribute is of type <code>double</code> and should contain values greater than 677 * zero (<code>0</code>). The 'stoichiometryMath' element is implemented as an 678 * element containing a MathML expression. These two are mutually 679 * exclusive; only one of 'stoichiometry' or 'stoichiometryMath' should 680 * be defined in a given {@link SpeciesReference} instance. When neither the 681 * attribute nor the element is present, the value of 'stoichiometry' in 682 * the {@link SpeciesReference} instance defaults to <code>1.</code> For maximum 683 * interoperability between different software tools, the 'stoichiometry' 684 * attribute should be used in preference to 'stoichiometryMath' when a 685 * species' stoichiometry is a simple scalar number (integer or 686 * decimal). 687 <p> 688 * In SBML Level 3, there is no {@link StoichiometryMath}, and {@link SpeciesReference} 689 * objects have only the 'stoichiometry' attribute. 690 <p> 691 * @note In SBML Level 2, the 'stoichiometry' attribute of this 692 * {@link SpeciesReference} object will be reset to a default value (<code>1.0</code>) if 693 * the 'stoichiometry' attribute has not been set. 694 */ public 695 int unsetStoichiometryMath() { 696 return libsbmlJNI.SpeciesReference_unsetStoichiometryMath(swigCPtr, this); 697 } 698 699 700/** 701 * Unsets the 'stoichiometry' attribute of this {@link SpeciesReference}. 702 <p> 703 * <p> 704 * @return integer value indicating success/failure of the 705 * function. The possible values 706 * returned by this function are: 707 * <ul> 708 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 709 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED} 710 * 711 * </ul> <p> 712 * @note In SBML Level 1, the 'stoichiometry' attribute of this 713 * {@link SpeciesReference} object will be just reset to a default value (<code>1.0</code>) 714 * and isSetStoichiometry() will still return <code>true.</code> In SBML 715 * Level 2, the 'stoichiometry' attribute of this object will be 716 * unset (which will result in isSetStoichiometry() returning <code>false</code>, 717 * although getStoichiometry() will return <code>1.0</code>) if the 718 * 'stoichiometryMath' subelement is set, otherwise the attribute 719 * will be just reset to the default value (<code>1.0</code>) (and 720 * isSetStoichiometry() will still return <code>true</code>). In SBML 721 * Level 3, the 'stoichiometry' attribute of this object will be set 722 * to <code>NaN</code> and isSetStoichiometry() will return <code>false.</code> 723 */ public 724 int unsetStoichiometry() { 725 return libsbmlJNI.SpeciesReference_unsetStoichiometry(swigCPtr, this); 726 } 727 728 729/** 730 * Unsets the 'constant' attribute of this {@link SpeciesReference}. 731 <p> 732 * <p> 733 * @return integer value indicating success/failure of the 734 * function. The possible values 735 * returned by this function are: 736 * <ul> 737 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 738 * <li> {@link libsbmlConstants#LIBSBML_UNEXPECTED_ATTRIBUTE LIBSBML_UNEXPECTED_ATTRIBUTE} 739 * </ul> 740 */ public 741 int unsetConstant() { 742 return libsbmlJNI.SpeciesReference_unsetConstant(swigCPtr, this); 743 } 744 745 746/** 747 * Creates a new, empty {@link StoichiometryMath} object, adds it to this 748 * {@link SpeciesReference}, and returns it. 749 <p> 750 * @return the newly created {@link StoichiometryMath} object instance. 751 <p> 752 * @note This function has no effect on SBML Level 1 or Level 3 753 * {@link SpeciesReference} objects, neither of which have 754 * {@link StoichiometryMath} children. 755 <p> 756 * @see Reaction#addReactant(SpeciesReference sr) 757 * @see Reaction#addProduct(SpeciesReference sr) 758 */ public 759 StoichiometryMath createStoichiometryMath() { 760 long cPtr = libsbmlJNI.SpeciesReference_createStoichiometryMath(swigCPtr, this); 761 return (cPtr == 0) ? null : new StoichiometryMath(cPtr, false); 762 } 763 764 765/** 766 * Sets the value of the 'annotation' subelement of this SBML object to a 767 * copy of <code>annotation</code>. 768 <p> 769 * Any existing content of the 'annotation' subelement is discarded. 770 * Unless you have taken steps to first copy and reconstitute any 771 * existing annotations into the <code>annotation</code> that is about to be 772 * assigned, it is likely that performing such wholesale replacement is 773 * unfriendly towards other software applications whose annotations are 774 * discarded. An alternative may be to use appendAnnotation(). 775 <p> 776 * @param annotation an XML structure that is to be used as the content 777 * of the 'annotation' subelement of this object. 778 <p> 779 * <p> 780 * @return integer value indicating success/failure of the 781 * function. This particular 782 * function only does one thing irrespective of user input or 783 * object state, and thus will only return a single value: 784 * <ul> 785 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 786 * 787 * </ul> <p> 788 * @see #appendAnnotation(XMLNode annotation) 789 * @see #appendAnnotation(String annotation) 790 */ public 791 int setAnnotation(XMLNode annotation) { 792 return libsbmlJNI.SpeciesReference_setAnnotation__SWIG_0(swigCPtr, this, XMLNode.getCPtr(annotation), annotation); 793 } 794 795 796/** 797 * Sets the value of the 'annotation' subelement of this SBML object to a 798 * copy of <code>annotation</code>. 799 <p> 800 * Any existing content of the 'annotation' subelement is discarded. 801 * Unless you have taken steps to first copy and reconstitute any 802 * existing annotations into the <code>annotation</code> that is about to be 803 * assigned, it is likely that performing such wholesale replacement is 804 * unfriendly towards other software applications whose annotations are 805 * discarded. An alternative may be to use appendAnnotation(). 806 <p> 807 * @param annotation an XML string that is to be used as the content 808 * of the 'annotation' subelement of this object. 809 <p> 810 * <p> 811 * @return integer value indicating success/failure of the 812 * function. The possible values 813 * returned by this function are: 814 * <ul> 815 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 816 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED} 817 * 818 * </ul> <p> 819 * @see #appendAnnotation(XMLNode annotation) 820 * @see #appendAnnotation(String annotation) 821 */ public 822 int setAnnotation(String annotation) { 823 return libsbmlJNI.SpeciesReference_setAnnotation__SWIG_1(swigCPtr, this, annotation); 824 } 825 826 827/** 828 * Appends annotation content to any existing content in the 'annotation' 829 * subelement of this object. 830 <p> 831 * The content in <code>annotation</code> is copied. Unlike 832 * {@link SpeciesReference#setAnnotation(String)}, 833 * this method allows other annotations to be preserved when an application 834 * adds its own data. 835 <p> 836 * @param annotation an XML structure that is to be copied and appended 837 * to the content of the 'annotation' subelement of this object. 838 <p> 839 * <p> 840 * @return integer value indicating success/failure of the 841 * function. The possible values 842 * returned by this function are: 843 * <ul> 844 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 845 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED} 846 * 847 * </ul> <p> 848 * @see #setAnnotation(String annotation) 849 * @see #setAnnotation(XMLNode annotation) 850 */ public 851 int appendAnnotation(XMLNode annotation) { 852 return libsbmlJNI.SpeciesReference_appendAnnotation__SWIG_0(swigCPtr, this, XMLNode.getCPtr(annotation), annotation); 853 } 854 855 856/** 857 * Appends annotation content to any existing content in the 'annotation' 858 * subelement of this object. 859 <p> 860 * The content in <code>annotation</code> is copied. Unlike 861 * {@link SpeciesReference#setAnnotation(String)}, this 862 * method allows other annotations to be preserved when an application 863 * adds its own data. 864 <p> 865 * @param annotation an XML string that is to be copied and appended 866 * to the content of the 'annotation' subelement of this object. 867 <p> 868 * <p> 869 * @return integer value indicating success/failure of the 870 * function. The possible values 871 * returned by this function are: 872 * <ul> 873 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 874 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED} 875 * 876 * </ul> <p> 877 * @see #setAnnotation(String annotation) 878 * @see #setAnnotation(XMLNode annotation) 879 */ public 880 int appendAnnotation(String annotation) { 881 return libsbmlJNI.SpeciesReference_appendAnnotation__SWIG_1(swigCPtr, this, annotation); 882 } 883 884 885/** 886 * Returns the libSBML type code for this SBML object. 887 <p> 888 * <p> 889 * LibSBML attaches an identifying code to every kind of SBML object. These 890 * are integer constants known as <em>SBML type codes</em>. The names of all 891 * the codes begin with the characters <code>SBML_</code>. 892 * In the Java language interface for libSBML, the 893 * type codes are defined as static integer constants in the interface class 894 * {@link libsbmlConstants}. Note that different Level 3 895 * package plug-ins may use overlapping type codes; to identify the package 896 * to which a given object belongs, call the 897 * <code>{@link SBase#getPackageName()} 898 * </code> 899 * method on the object. 900 <p> 901 * @return the SBML type code for this object: 902 * {@link libsbmlConstants#SBML_SPECIES_REFERENCE SBML_SPECIES_REFERENCE} (default). 903 <p> 904 * @see #getElementName() 905 * @see #getPackageName() 906 */ public 907 int getTypeCode() { 908 return libsbmlJNI.SpeciesReference_getTypeCode(swigCPtr, this); 909 } 910 911 912/** 913 * Returns the XML element name of this object, which for 914 * {@link SpeciesReference}, is always <code>'speciesReference'.</code> 915 <p> 916 * @return the name of this element, i.e., <code>'speciesReference'.</code> 917 */ public 918 String getElementName() { 919 return libsbmlJNI.SpeciesReference_getElementName(swigCPtr, this); 920 } 921 922 923/** 924 * Predicate returning <code>true</code> if 925 * all the required attributes for this {@link SpeciesReference} object 926 * have been set. 927 <p> 928 * The required attributes for a {@link SpeciesReference} object are: 929 * <ul> 930 * <li> 'species' 931 * <li> 'constant' (only available SBML Level 3) 932 * 933 * </ul> <p> 934 * @return <code>true</code> if the required attributes have been set, <code>false</code> 935 * otherwise. 936 */ public 937 boolean hasRequiredAttributes() { 938 return libsbmlJNI.SpeciesReference_hasRequiredAttributes(swigCPtr, this); 939 } 940 941}