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 KineticLaw construct. 014 * <p> 015 * An object of class {@link KineticLaw} is used to describe the rate at which the 016 * process defined by a given {@link Reaction} takes place. {@link KineticLaw} has 017 * subelements called 'math' (for MathML content) and 'listOfParameters' 018 * (of class {@link ListOfParameters}), in addition to the attributes and 019 * subelements it inherits from {@link SBase}. 020 * <p> 021 * {@link KineticLaw}'s 'math' subelement for holding a MathML formula defines the 022 * rate of the reaction. The formula may refer to other entities in a 023 * model as well as local parameter definitions within the scope of the 024 * {@link Reaction} (see below). It is important to keep in mind, however, that 025 * the only {@link Species} identifiers that can be used in this formula are those 026 * declared in the lists of reactants, products and modifiers in the 027 * {@link Reaction} structure. (In other words, before a species can be referenced 028 * in the {@link KineticLaw}, it must be declared in one of those lists.) 029 * <p> 030 * {@link KineticLaw} provides a way to define <em>local</em> parameters whose 031 * identifiers can be used in the 'math' formula of that {@link KineticLaw} 032 * instance. Prior to SBML Level 3, these parameter definitions are 033 * stored inside a 'listOfParameters' subelement containing {@link Parameter} 034 * objects; in SBML Level 3, this is achieved using a specialized 035 * object class called {@link LocalParameter} and the containing subelement is 036 * called 'listOfLocalParameters'. In both cases, the parameters so 037 * defined are only visible within the {@link KineticLaw}; they cannot be accessed 038 * outside. A local parameter within one reaction is not visible from 039 * within another reaction, nor is it visible to any other construct 040 * outside of the {@link KineticLaw} in which it is defined. In addition, another 041 * important feature is that if such a {@link Parameter} (or in Level 3, 042 * {@link LocalParameter}) object has the same identifier as another object in the 043 * scope of the enclosing {@link Model}, the definition inside the {@link KineticLaw} takes 044 * precedence. In other words, within the {@link KineticLaw}'s 'math' formula, 045 * references to local parameter identifiers <strong>shadow any identical 046 * global identifiers</strong>. 047 * <p> 048 * The values of local parameters defined within {@link KineticLaw} objects cannot 049 * change. In SBML Level 3, this quality is built into the 050 * {@link LocalParameter} construct. In Level 2, where the same kind of 051 * {@link Parameter} object class is used as for global parameters, the {@link Parameter} 052 * objects' 'constant' attribute must always have a value of <code>true</code> 053 * (either explicitly or left to its default value). 054 * <p> 055 * <p> 056 * <h2>A warning about identifier shadowing</h2> 057 * <p> 058 * A common misconception is that different classes of objects (e.g., 059 * species, compartments, parameters) in SBML have different identifier 060 * scopes. They do not. The implication is that if a {@link KineticLaw}'s local 061 * parameter definition uses an identifier identical to <em>any</em> other 062 * identifier defined in the model outside the {@link KineticLaw}, even if the 063 * other identifier does <em>not</em> belong to a parameter type of object, the 064 * local parameter's identifier takes precedence within that {@link KineticLaw}'s 065 * 'math' formula. It is not an error in SBML for identifiers to shadow 066 * each other this way, but can lead to confusing and subtle errors. 067 * <p> 068 * <p> 069 * <h2>SBML Level/Version differences</h2> 070 * <p> 071 * In SBML Level 2 Version 1, the SBML specification 072 * included two additional attributes on {@link KineticLaw} called 'substanceUnits' 073 * and 'timeUnits'. They were removed beginning with SBML Level 2 074 * Version 2 because further research determined they introduced many 075 * problems. The most significant problem was that their use could easily 076 * lead to the creation of valid models whose reactions nevertheless could 077 * not be integrated into a system of equations without outside knowledge 078 * for converting the quantities used. Examination of real-life models 079 * revealed that a common reason for using 'substanceUnits' on {@link KineticLaw} 080 * was to set the units of all reactions to the same set of substance 081 * units, something that is better achieved by using {@link UnitDefinition} to 082 * redefine <code>'substance'</code> for the whole {@link Model}. 083 * <p> 084 * As mentioned above, in SBML Level 2 Versions 2–4, local 085 * parameters are of class {@link Parameter}. In SBML Level 3, the class of 086 * object is {@link LocalParameter}. 087 */ 088 089public class KineticLaw extends SBase { 090 private long swigCPtr; 091 092 protected KineticLaw(long cPtr, boolean cMemoryOwn) 093 { 094 super(libsbmlJNI.KineticLaw_SWIGUpcast(cPtr), cMemoryOwn); 095 swigCPtr = cPtr; 096 } 097 098 protected static long getCPtr(KineticLaw obj) 099 { 100 return (obj == null) ? 0 : obj.swigCPtr; 101 } 102 103 protected static long getCPtrAndDisown (KineticLaw obj) 104 { 105 long ptr = 0; 106 107 if (obj != null) 108 { 109 ptr = obj.swigCPtr; 110 obj.swigCMemOwn = false; 111 } 112 113 return ptr; 114 } 115 116 protected void finalize() { 117 delete(); 118 } 119 120 public synchronized void delete() { 121 if (swigCPtr != 0) { 122 if (swigCMemOwn) { 123 swigCMemOwn = false; 124 libsbmlJNI.delete_KineticLaw(swigCPtr); 125 } 126 swigCPtr = 0; 127 } 128 super.delete(); 129 } 130 131 132/** 133 * Creates a new {@link KineticLaw} using the given SBML <code>level</code> and <code>version</code> 134 * values. 135 * <p> 136 * @param level a long integer, the SBML Level to assign to this {@link KineticLaw} 137 * <p> 138 * @param version a long integer, the SBML Version to assign to this 139 * {@link KineticLaw} 140 * <p> 141 * @throws SBMLConstructorException 142 * Thrown if the given <code>level</code> and <code>version</code> combination, or this kind 143 * of SBML object, are either invalid or mismatched with respect to the 144 * parent {@link SBMLDocument} object. 145 * <p> 146 * @note Upon the addition of a {@link KineticLaw} object to an {@link SBMLDocument} 147 * (e.g., using {@link Reaction#setKineticLaw(KineticLaw kl)}), the SBML Level, SBML Version 148 * and XML namespace of the document <em>override</em> the values used 149 * when creating the {@link KineticLaw} object via this constructor. This is 150 * necessary to ensure that an SBML document is a consistent structure. 151 * Nevertheless, the ability to supply the values at the time of creation 152 * of a {@link KineticLaw} is an important aid to producing valid SBML. Knowledge 153 * of the intented SBML Level and Version determine whether it is valid 154 * to assign a particular value to an attribute, or whether it is valid 155 * to add an object to an existing {@link SBMLDocument}. 156 */ public 157 KineticLaw(long level, long version) throws org.sbml.libsbml.SBMLConstructorException { 158 this(libsbmlJNI.new_KineticLaw__SWIG_0(level, version), true); 159 } 160 161 162/** 163 * Creates a new {@link KineticLaw} using the given {@link SBMLNamespaces} object 164 * <code>sbmlns</code>. 165 * <p> 166 * The {@link SBMLNamespaces} object encapsulates SBML Level/Version/namespaces 167 * information. It is used to communicate the SBML Level, Version, and 168 * (in Level 3) packages used in addition to SBML Level 3 Core. 169 * A common approach to using this class constructor is to create an 170 * {@link SBMLNamespaces} object somewhere in a program, once, then pass it to 171 * object constructors such as this one when needed. 172 * <p> 173 * @param sbmlns an {@link SBMLNamespaces} object. 174 * <p> 175 * @throws SBMLConstructorException 176 * Thrown if the given <code>level</code> and <code>version</code> combination, or this kind 177 * of SBML object, are either invalid or mismatched with respect to the 178 * parent {@link SBMLDocument} object. 179 * <p> 180 * @note Upon the addition of a {@link KineticLaw} object to an {@link SBMLDocument} 181 * (e.g., using {@link Reaction#setKineticLaw(KineticLaw kl)}), the SBML XML namespace of the 182 * document <em>overrides</em> the value used when creating the {@link KineticLaw} 183 * object via this constructor. This is necessary to ensure that an SBML 184 * document is a consistent structure. Nevertheless, the ability to 185 * supply the values at the time of creation of a {@link KineticLaw} is an 186 * important aid to producing valid SBML. Knowledge of the intented SBML 187 * Level and Version determine whether it is valid to assign a particular 188 * value to an attribute, or whether it is valid to add an object to an 189 * existing {@link SBMLDocument}. 190 */ public 191 KineticLaw(SBMLNamespaces sbmlns) throws org.sbml.libsbml.SBMLConstructorException { 192 this(libsbmlJNI.new_KineticLaw__SWIG_1(SBMLNamespaces.getCPtr(sbmlns), sbmlns), true); 193 } 194 195 196/** 197 * Copy constructor; creates a copy of this {@link KineticLaw}. 198 * <p> 199 * @param orig the object to copy. 200 * <p> 201 * @throws SBMLConstructorException 202 * Thrown if the argument <code>orig</code> is <code>null.</code> 203 */ public 204 KineticLaw(KineticLaw orig) throws org.sbml.libsbml.SBMLConstructorException { 205 this(libsbmlJNI.new_KineticLaw__SWIG_2(KineticLaw.getCPtr(orig), orig), true); 206 } 207 208 209/** 210 * Creates and returns a deep copy of this {@link KineticLaw} object. 211 * <p> 212 * @return a (deep) copy of this {@link KineticLaw}. 213 */ public 214 KineticLaw cloneObject() { 215 long cPtr = libsbmlJNI.KineticLaw_cloneObject(swigCPtr, this); 216 return (cPtr == 0) ? null : new KineticLaw(cPtr, true); 217 } 218 219 220/** 221 * Returns the first child element found that has the given <code>id</code> in the model-wide SId namespace, or <code>null</code> if no such object is found. 222 * <p> 223 * @param id string representing the id of objects to find. 224 * <p> 225 * @return pointer to the first element found with the given <code>id</code>. 226 */ public 227 SBase getElementBySId(String id) { 228 return libsbml.DowncastSBase(libsbmlJNI.KineticLaw_getElementBySId(swigCPtr, this, id), false); 229} 230 231 232/** 233 * Returns the first child element it can find with the given <code>metaid</code>, or <code>null</code> if no such object is found. 234 * <p> 235 * @param metaid string representing the metaid of objects to find 236 * <p> 237 * @return pointer to the first element found with the given <code>metaid</code>. 238 */ public 239 SBase getElementByMetaId(String metaid) { 240 return libsbml.DowncastSBase(libsbmlJNI.KineticLaw_getElementByMetaId(swigCPtr, this, metaid), false); 241} 242 243 244/** 245 * Returns the mathematical formula for this {@link KineticLaw} object and return 246 * it as as a text string. 247 * <p> 248 * This is fundamentally equivalent to 249 * {@link KineticLaw#getMath()}. 250 * This variant is provided principally for compatibility compatibility 251 * with SBML Level 1. 252 * <p> 253 * @return a string representing the formula of this {@link KineticLaw}. 254 * <p> 255 * @note SBML Level 1 uses a text-string format for mathematical formulas. 256SBML Level 2 uses MathML, an XML format for representing mathematical 257expressions. LibSBML provides an Abstract Syntax Tree API for working with 258mathematical expressions; this API is more powerful than working with 259formulas directly in text form, and ASTs can be translated into either 260MathML or the text-string syntax. The libSBML methods that accept 261text-string formulas directly (such as this constructor) are provided for 262SBML Level 1 compatibility, but developers are encouraged to use the 263AST mechanisms. 264 265 * <p> 266 * @see #getMath() 267 */ public 268 String getFormula() { 269 return libsbmlJNI.KineticLaw_getFormula(swigCPtr, this); 270 } 271 272 273/** 274 * Returns the mathematical formula for this {@link KineticLaw} object and return 275 * it as as an AST. 276 * <p> 277 * This is fundamentally equivalent to 278 * {@link KineticLaw#getFormula()}. 279 * The latter is provided principally for compatibility compatibility 280 * with SBML Level 1, which represented mathematical formulas in 281 * text-string form. 282 * <p> 283 * @return the {@link ASTNode} representation of the mathematical formula. 284 * <p> 285 * @see #getFormula() 286 */ public 287 ASTNode getMath() { 288 long cPtr = libsbmlJNI.KineticLaw_getMath(swigCPtr, this); 289 return (cPtr == 0) ? null : new ASTNode(cPtr, false); 290 } 291 292 293/** 294 * (SBML Level 2 Version 1 only) Returns the value of the 295 * 'timeUnits' attribute of this {@link KineticLaw} object. 296 * <p> 297 * @return the 'timeUnits' attribute value. 298 * <p> 299 * @note The attributes 'timeUnits' and 'substanceUnits' are present only 300 * in SBML Level 2 Version 1. In SBML Level 2 301 * Version 2, the 'timeUnits' and 'substanceUnits' attributes were 302 * removed. For compatibility with new versions of SBML, users are 303 * cautioned to avoid these attributes. 304 */ public 305 String getTimeUnits() { 306 return libsbmlJNI.KineticLaw_getTimeUnits(swigCPtr, this); 307 } 308 309 310/** 311 * (SBML Level 2 Version 1 only) Returns the value of the 312 * 'substanceUnits' attribute of this {@link KineticLaw} object. 313 * <p> 314 * @return the 'substanceUnits' attribute value. 315 * <p> 316 * @note The attributes 'timeUnits' and 'substanceUnits' are present only 317 * in SBML Level 2 Version 1. In SBML Level 2 318 * Version 2, the 'timeUnits' and 'substanceUnits' attributes were 319 * removed. For compatibility with new versions of SBML, users are 320 * cautioned to avoid these attributes. 321 */ public 322 String getSubstanceUnits() { 323 return libsbmlJNI.KineticLaw_getSubstanceUnits(swigCPtr, this); 324 } 325 326 327/** 328 * Predicate returning <code>true</code> if this 329 * {@link KineticLaw}'s 'formula' attribute is set. 330 * <p> 331 * This is functionally identical to the method 332 * {@link KineticLaw#isSetMath()}. It is 333 * provided in order to mirror the parallel between 334 * {@link KineticLaw#getFormula()} and 335 * {@link KineticLaw#getMath()}. 336 * <p> 337 * @return <code>true</code> if the formula (meaning the <code>math</code> subelement) of 338 * this {@link KineticLaw} is set, <code>false</code> otherwise. 339 * <p> 340 * @note SBML Level 1 uses a text-string format for mathematical formulas. 341SBML Level 2 uses MathML, an XML format for representing mathematical 342expressions. LibSBML provides an Abstract Syntax Tree API for working with 343mathematical expressions; this API is more powerful than working with 344formulas directly in text form, and ASTs can be translated into either 345MathML or the text-string syntax. The libSBML methods that accept 346text-string formulas directly (such as this constructor) are provided for 347SBML Level 1 compatibility, but developers are encouraged to use the 348AST mechanisms. 349 350 * <p> 351 * @see #isSetMath() 352 */ public 353 boolean isSetFormula() { 354 return libsbmlJNI.KineticLaw_isSetFormula(swigCPtr, this); 355 } 356 357 358/** 359 * Predicate returning <code>true</code> if this 360 * Kinetic's 'math' subelement is set. 361 * <p> 362 * This is identical to the method 363 * {@link KineticLaw#isSetFormula()}. 364 * It is provided in order to mirror the parallel between 365 * {@link KineticLaw#getFormula()} and 366 * {@link KineticLaw#getMath()}. 367 * <p> 368 * @return <code>true</code> if the formula (meaning the <code>math</code> subelement) of 369 * this {@link KineticLaw} is set, <code>false</code> otherwise. 370 * <p> 371 * @see #isSetFormula() 372 */ public 373 boolean isSetMath() { 374 return libsbmlJNI.KineticLaw_isSetMath(swigCPtr, this); 375 } 376 377 378/** 379 * (SBML Level 2 Version 1 only) Predicate returning <code>true</code> if 380 * this {@link SpeciesReference}'s 'timeUnits' attribute is set. 381 * <p> 382 * @return <code>true</code> if the 'timeUnits' attribute of this {@link KineticLaw} object 383 * is set, <code>false</code> otherwise. 384 * <p> 385 * @note The attributes 'timeUnits' and 'substanceUnits' are present only 386 * in SBML Level 2 Version 1. In SBML Level 2 387 * Version 2, the 'timeUnits' and 'substanceUnits' attributes were 388 * removed. For compatibility with new versions of SBML, users are 389 * cautioned to avoid these attributes. 390 */ public 391 boolean isSetTimeUnits() { 392 return libsbmlJNI.KineticLaw_isSetTimeUnits(swigCPtr, this); 393 } 394 395 396/** 397 * (SBML Level 2 Version 1 only) Predicate returning <code>true</code> if 398 * this {@link SpeciesReference}'s 'substanceUnits' attribute is set. 399 * <p> 400 * @return <code>true</code> if the 'substanceUnits' attribute of this {@link KineticLaw} 401 * object is set, <code>false</code> otherwise. 402 * <p> 403 * @note The attributes 'timeUnits' and 'substanceUnits' are present only 404 * in SBML Level 2 Version 1. In SBML Level 2 405 * Version 2, the 'timeUnits' and 'substanceUnits' attributes were 406 * removed. For compatibility with new versions of SBML, users are 407 * cautioned to avoid these attributes. 408 */ public 409 boolean isSetSubstanceUnits() { 410 return libsbmlJNI.KineticLaw_isSetSubstanceUnits(swigCPtr, this); 411 } 412 413 414/** 415 * Sets the mathematical expression of this {@link KineticLaw} instance to the 416 * given <code>formula</code>. 417 * <p> 418 * The given <code>formula</code> string is copied. Internally, libSBML stores the 419 * mathematical expression as an {@link ASTNode}. 420 * <p> 421 * @param formula the mathematical expression to use, represented in 422 * text-string form. 423 * <p> 424 * @return integer value indicating success/failure of the 425 * function. The possible values 426 * returned by this function are: 427 * <ul> 428 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS } 429 * <li> {@link libsbmlConstants#LIBSBML_INVALID_OBJECT LIBSBML_INVALID_OBJECT } 430 * </ul> 431 * <p> 432 * @note SBML Level 1 uses a text-string format for mathematical formulas. 433SBML Level 2 uses MathML, an XML format for representing mathematical 434expressions. LibSBML provides an Abstract Syntax Tree API for working with 435mathematical expressions; this API is more powerful than working with 436formulas directly in text form, and ASTs can be translated into either 437MathML or the text-string syntax. The libSBML methods that accept 438text-string formulas directly (such as this constructor) are provided for 439SBML Level 1 compatibility, but developers are encouraged to use the 440AST mechanisms. 441 442 * <p> 443 * @see #setMath(ASTNode math) 444 */ public 445 int setFormula(String formula) { 446 return libsbmlJNI.KineticLaw_setFormula(swigCPtr, this, formula); 447 } 448 449 450/** 451 * Sets the mathematical expression of this {@link KineticLaw} instance to a copy 452 * of the given {@link ASTNode}. 453 * <p> 454 * This is fundamentally identical to 455 * {@link KineticLaw#setFormula(String formula)}. 456 * The latter is provided principally for compatibility compatibility with 457 * SBML Level 1, which represented mathematical formulas in text-string 458 * form. 459 * <p> 460 * @param math an {@link ASTNode} representing a formula tree. 461 * <p> 462 * @return integer value indicating success/failure of the 463 * function. The possible values 464 * returned by this function are: 465 * <ul> 466 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS } 467 * <li> {@link libsbmlConstants#LIBSBML_INVALID_OBJECT LIBSBML_INVALID_OBJECT } 468 * </ul> 469 * <p> 470 * @see #setFormula(String formula) 471 */ public 472 int setMath(ASTNode math) { 473 return libsbmlJNI.KineticLaw_setMath(swigCPtr, this, ASTNode.getCPtr(math), math); 474 } 475 476 477/** 478 * (SBML Level 2 Version 1 only) Sets the 'timeUnits' attribute 479 * of this {@link KineticLaw} object to a copy of the identifier in <code>sid</code>. 480 * <p> 481 * @param sid the identifier of the units to use. 482 * <p> 483 * @return integer value indicating success/failure of the 484 * function. The possible values 485 * returned by this function are: 486 * <ul> 487 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS } 488 * <li> {@link libsbmlConstants#LIBSBML_INVALID_ATTRIBUTE_VALUE LIBSBML_INVALID_ATTRIBUTE_VALUE } 489 * <li> {@link libsbmlConstants#LIBSBML_UNEXPECTED_ATTRIBUTE LIBSBML_UNEXPECTED_ATTRIBUTE } 490 * </ul> 491 * <p> 492 * @note The attributes 'timeUnits' and 'substanceUnits' are present only 493 * in SBML Level 2 Version 1. In SBML Level 2 494 * Version 2, the 'timeUnits' and 'substanceUnits' attributes were 495 * removed. For compatibility with new versions of SBML, users are 496 * cautioned to avoid these attributes. 497 */ public 498 int setTimeUnits(String sid) { 499 return libsbmlJNI.KineticLaw_setTimeUnits(swigCPtr, this, sid); 500 } 501 502 503/** 504 * (SBML Level 2 Version 1 only) Sets the 'substanceUnits' 505 * attribute of this {@link KineticLaw} object to a copy of the identifier given 506 * in <code>sid</code>. 507 * <p> 508 * @param sid the identifier of the units to use. 509 * <p> 510 * @return integer value indicating success/failure of the 511 * function. The possible values 512 * returned by this function are: 513 * <ul> 514 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS } 515 * <li> {@link libsbmlConstants#LIBSBML_INVALID_ATTRIBUTE_VALUE LIBSBML_INVALID_ATTRIBUTE_VALUE } 516 * <li> {@link libsbmlConstants#LIBSBML_UNEXPECTED_ATTRIBUTE LIBSBML_UNEXPECTED_ATTRIBUTE } 517 * </ul> 518 * <p> 519 * @note The attributes 'timeUnits' and 'substanceUnits' are present only 520 * in SBML Level 2 Version 1. In SBML Level 2 521 * Version 2, the 'timeUnits' and 'substanceUnits' attributes were 522 * removed. For compatibility with new versions of SBML, users are 523 * cautioned to avoid these attributes. 524 */ public 525 int setSubstanceUnits(String sid) { 526 return libsbmlJNI.KineticLaw_setSubstanceUnits(swigCPtr, this, sid); 527 } 528 529 530/** 531 * (SBML Level 2 Version 1 only) Unsets the 'timeUnits' 532 * attribugte of this {@link KineticLaw} object. 533 * <p> 534 * @return integer value indicating success/failure of the 535 * function. The possible values 536 * returned by this function are: 537 * <ul> 538 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS } 539 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED } 540 * <li> {@link libsbmlConstants#LIBSBML_UNEXPECTED_ATTRIBUTE LIBSBML_UNEXPECTED_ATTRIBUTE } 541 * </ul> 542 * <p> 543 * @note The attributes 'timeUnits' and 'substanceUnits' are present only 544 * in SBML Level 2 Version 1. In SBML Level 2 545 * Version 2, the 'timeUnits' and 'substanceUnits' attributes were 546 * removed. For compatibility with new versions of SBML, users are 547 * cautioned to avoid these attributes. 548 */ public 549 int unsetTimeUnits() { 550 return libsbmlJNI.KineticLaw_unsetTimeUnits(swigCPtr, this); 551 } 552 553 554/** 555 * (SBML Level 2 Version 1 only) Unsets the 'substanceUnits' 556 * attribute of this {@link KineticLaw} object. 557 * <p> 558 * @return integer value indicating success/failure of the 559 * function. The possible values 560 * returned by this function are: 561 * <ul> 562 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS } 563 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED } 564 * <li> {@link libsbmlConstants#LIBSBML_UNEXPECTED_ATTRIBUTE LIBSBML_UNEXPECTED_ATTRIBUTE } 565 * </ul> 566 * <p> 567 * @note The attributes 'timeUnits' and 'substanceUnits' are present only 568 * in SBML Level 2 Version 1. In SBML Level 2 569 * Version 2, the 'timeUnits' and 'substanceUnits' attributes were 570 * removed. For compatibility with new versions of SBML, users are 571 * cautioned to avoid these attributes. 572 */ public 573 int unsetSubstanceUnits() { 574 return libsbmlJNI.KineticLaw_unsetSubstanceUnits(swigCPtr, this); 575 } 576 577 578/** 579 * Adds a copy of the given {@link Parameter} object to the list of local 580 * parameters in this {@link KineticLaw}. 581 * <p> 582 * @param p the {@link Parameter} to add 583 * <p> 584 * @return integer value indicating success/failure of the 585 * function. The possible values 586 * returned by this function are: 587 * <ul> 588 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS } 589 * <li> {@link libsbmlConstants#LIBSBML_LEVEL_MISMATCH LIBSBML_LEVEL_MISMATCH } 590 * <li> {@link libsbmlConstants#LIBSBML_VERSION_MISMATCH LIBSBML_VERSION_MISMATCH } 591 * <li> {@link libsbmlConstants#LIBSBML_DUPLICATE_OBJECT_ID LIBSBML_DUPLICATE_OBJECT_ID } 592 * <li> {@link libsbmlConstants#LIBSBML_INVALID_OBJECT LIBSBML_INVALID_OBJECT } 593 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED } 594 * </ul> 595 * <p> 596 * @note This method should be used with some caution. The fact that 597 * this method <em>copies</em> the object passed to it means that the caller 598 * will be left holding a physically different object instance than the 599 * one contained in this {@link KineticLaw}. Changes made to the original object 600 * instance (such as resetting attribute values) will <em>not affect the 601 * instance in the {@link KineticLaw}</em>. In addition, the caller should make 602 * sure to free the original object if it is no longer being used, or 603 * else a memory leak will result. Please see 604 * {@link KineticLaw#createParameter()} 605 * for a method that does not lead to these issues. 606 * <p> 607 * @see #createParameter() 608 */ public 609 int addParameter(Parameter p) { 610 return libsbmlJNI.KineticLaw_addParameter(swigCPtr, this, Parameter.getCPtr(p), p); 611 } 612 613 614/** 615 * Adds a copy of the given {@link LocalParameter} object to the list of local 616 * parameters in this {@link KineticLaw}. 617 * <p> 618 * @param p the {@link LocalParameter} to add 619 * <p> 620 * @return integer value indicating success/failure of the 621 * function. The possible values 622 * returned by this function are: 623 * <ul> 624 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS } 625 * <li> {@link libsbmlConstants#LIBSBML_LEVEL_MISMATCH LIBSBML_LEVEL_MISMATCH } 626 * <li> {@link libsbmlConstants#LIBSBML_VERSION_MISMATCH LIBSBML_VERSION_MISMATCH } 627 * <li> {@link libsbmlConstants#LIBSBML_DUPLICATE_OBJECT_ID LIBSBML_DUPLICATE_OBJECT_ID } 628 * <li> {@link libsbmlConstants#LIBSBML_INVALID_OBJECT LIBSBML_INVALID_OBJECT } 629 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED } 630 * </ul> 631 * <p> 632 * @note This method should be used with some caution. The fact that 633 * this method <em>copies</em> the object passed to it means that the caller 634 * will be left holding a physically different object instance than the 635 * one contained in this {@link KineticLaw}. Changes made to the original object 636 * instance (such as resetting attribute values) will <em>not affect the 637 * instance in the {@link KineticLaw}</em>. In addition, the caller should make 638 * sure to free the original object if it is no longer being used, or 639 * else a memory leak will result. Please see 640 * {@link KineticLaw#createParameter()} 641 * for a method that does not lead to these issues. 642 * <p> 643 * @see #createLocalParameter() 644 */ public 645 int addLocalParameter(LocalParameter p) { 646 return libsbmlJNI.KineticLaw_addLocalParameter(swigCPtr, this, LocalParameter.getCPtr(p), p); 647 } 648 649 650/** 651 * Creates a new {@link Parameter} object, adds it to this {@link KineticLaw}'s list of 652 * local parameters, and returns the {@link Parameter} object created. 653 * <p> 654 * @return a new {@link Parameter} object instance 655 * <p> 656 * @see #addParameter(Parameter p) 657 */ public 658 Parameter createParameter() { 659 long cPtr = libsbmlJNI.KineticLaw_createParameter(swigCPtr, this); 660 return (cPtr == 0) ? null : new Parameter(cPtr, false); 661 } 662 663 664/** 665 * Creates a new {@link LocalParameter} object, adds it to this {@link KineticLaw}'s list 666 * of local parameters, and returns the {@link LocalParameter} object created. 667 * <p> 668 * @return a new {@link LocalParameter} object instance 669 * <p> 670 * @see #addLocalParameter(LocalParameter p) 671 */ public 672 LocalParameter createLocalParameter() { 673 long cPtr = libsbmlJNI.KineticLaw_createLocalParameter(swigCPtr, this); 674 return (cPtr == 0) ? null : new LocalParameter(cPtr, false); 675 } 676 677 678/** 679 * Returns the list of local parameters in this {@link KineticLaw} object. 680 * <p> 681 * @return the list of Parameters for this {@link KineticLaw}. 682 */ public 683 ListOfParameters getListOfParameters() { 684 long cPtr = libsbmlJNI.KineticLaw_getListOfParameters__SWIG_0(swigCPtr, this); 685 return (cPtr == 0) ? null : new ListOfParameters(cPtr, false); 686 } 687 688 689/** 690 * Returns the list of local parameters in this {@link KineticLaw} object. 691 * <p> 692 * @return the list of LocalParameters for this {@link KineticLaw}. 693 */ public 694 ListOfLocalParameters getListOfLocalParameters() { 695 long cPtr = libsbmlJNI.KineticLaw_getListOfLocalParameters__SWIG_0(swigCPtr, this); 696 return (cPtr == 0) ? null : new ListOfLocalParameters(cPtr, false); 697 } 698 699 700/** 701 * Returns the nth {@link Parameter} object in the list of local parameters in 702 * this {@link KineticLaw} instance. 703 * <p> 704 * @param n the index of the {@link Parameter} object sought 705 * <p> 706 * @return the nth {@link Parameter} of this {@link KineticLaw}. 707 */ public 708 Parameter getParameter(long n) { 709 long cPtr = libsbmlJNI.KineticLaw_getParameter__SWIG_0(swigCPtr, this, n); 710 return (cPtr == 0) ? null : new Parameter(cPtr, false); 711 } 712 713 714/** 715 * Returns the nth {@link LocalParameter} object in the list of local parameters in 716 * this {@link KineticLaw} instance. 717 * <p> 718 * @param n the index of the {@link LocalParameter} object sought 719 * <p> 720 * @return the nth {@link LocalParameter} of this {@link KineticLaw}. 721 */ public 722 LocalParameter getLocalParameter(long n) { 723 long cPtr = libsbmlJNI.KineticLaw_getLocalParameter__SWIG_0(swigCPtr, this, n); 724 return (cPtr == 0) ? null : new LocalParameter(cPtr, false); 725 } 726 727 728/** 729 * Returns a local parameter based on its identifier. 730 * <p> 731 * @param sid the identifier of the {@link Parameter} being sought. 732 * <p> 733 * @return the {@link Parameter} object in this {@link KineticLaw} instace having the 734 * given 'id', or <code>null</code> if no such {@link Parameter} exists. 735 */ public 736 Parameter getParameter(String sid) { 737 long cPtr = libsbmlJNI.KineticLaw_getParameter__SWIG_2(swigCPtr, this, sid); 738 return (cPtr == 0) ? null : new Parameter(cPtr, false); 739 } 740 741 742/** 743 * Returns a local parameter based on its identifier. 744 * <p> 745 * @param sid the identifier of the {@link LocalParameter} being sought. 746 * <p> 747 * @return the {@link LocalParameter} object in this {@link KineticLaw} instace having the 748 * given 'id', or <code>null</code> if no such {@link LocalParameter} exists. 749 */ public 750 LocalParameter getLocalParameter(String sid) { 751 long cPtr = libsbmlJNI.KineticLaw_getLocalParameter__SWIG_2(swigCPtr, this, sid); 752 return (cPtr == 0) ? null : new LocalParameter(cPtr, false); 753 } 754 755 756/** 757 * Returns the number of local parameters in this {@link KineticLaw} instance. 758 * <p> 759 * @return the number of Parameters in this {@link KineticLaw}. 760 */ public 761 long getNumParameters() { 762 return libsbmlJNI.KineticLaw_getNumParameters(swigCPtr, this); 763 } 764 765 766/** 767 * Returns the number of local parameters in this {@link KineticLaw} instance. 768 * <p> 769 * @return the number of LocalParameters in this {@link KineticLaw}. 770 */ public 771 long getNumLocalParameters() { 772 return libsbmlJNI.KineticLaw_getNumLocalParameters(swigCPtr, this); 773 } 774 775 776/** 777 * Calculates and returns a {@link UnitDefinition} that expresses the units 778 * of measurement assumed for the 'math' expression of this 779 * {@link KineticLaw}. 780 * <p> 781 * The units are calculated based on the mathematical expression in the 782 * {@link KineticLaw} and the model quantities referenced by 783 * <code><ci></code> elements used within that expression. The 784 * {@link KineticLaw#getDerivedUnitDefinition()} 785 * method returns the calculated units. 786 * <p> 787 * Note that the functionality that facilitates unit analysis depends 788 * on the model as a whole. Thus, in cases where the object has not 789 * been added to a model or the model itself is incomplete, 790 * unit analysis is not possible and this method will return <code>null.</code> 791 * <p> 792 * @warning Note that it is possible the 'math' expression in the 793 * {@link KineticLaw} contains pure numbers or parameters with undeclared 794 * units. In those cases, it is not possible to calculate the units of 795 * the overall expression without making assumptions. LibSBML does not 796 * make assumptions about the units, and 797 * {@link KineticLaw#getDerivedUnitDefinition()} 798 * only returns the units as far as it is able to determine them. For 799 * example, in an expression <em>X + Y</em>, if <em>X</em> has 800 * unambiguously-defined units and <em>Y</em> does not, it will return 801 * the units of <em>X</em>. <strong>It is important that callers also 802 * invoke the method</strong> 803 * {@link KineticLaw#containsUndeclaredUnits()} 804 * <strong>to determine whether this situation holds</strong>. Callers may 805 * wish to take suitable actions in those scenarios. 806 * <p> 807 * @return a {@link UnitDefinition} that expresses the units of the math 808 * expression of this {@link KineticLaw}, or <code>null</code> if one cannot be constructed. 809 * <p> 810 * @see #containsUndeclaredUnits() 811 */ public 812 UnitDefinition getDerivedUnitDefinition() { 813 long cPtr = libsbmlJNI.KineticLaw_getDerivedUnitDefinition__SWIG_0(swigCPtr, this); 814 return (cPtr == 0) ? null : new UnitDefinition(cPtr, false); 815 } 816 817 818/** 819 * Predicate returning <code>true</code> if 820 * the math expression of this {@link KineticLaw} contains 821 * parameters/numbers with undeclared units. 822 * <p> 823 * @return <code>true</code> if the math expression of this {@link KineticLaw} 824 * includes parameters/numbers 825 * with undeclared units, <code>false</code> otherwise. 826 * <p> 827 * @note A return value of <code>true</code> indicates that the {@link UnitDefinition} 828 * returned by 829 * {@link KineticLaw#getDerivedUnitDefinition()} 830 * may not accurately represent the units of the expression. 831 * <p> 832 * @see #getDerivedUnitDefinition() 833 */ public 834 boolean containsUndeclaredUnits() { 835 return libsbmlJNI.KineticLaw_containsUndeclaredUnits__SWIG_0(swigCPtr, this); 836 } 837 838 839/** 840 * Removes the nth {@link Parameter} object in the list of local parameters 841 * in this {@link KineticLaw} instance and returns a pointer to it. 842 * <p> 843 * The caller owns the returned object and is responsible for deleting it. 844 * <p> 845 * @param n the index of the {@link Parameter} object to remove 846 * <p> 847 * @return the {@link Parameter} object removed. As mentioned above, 848 * the caller owns the returned item. <code>null</code> is returned if the given index 849 * is out of range. 850 */ public 851 Parameter removeParameter(long n) { 852 long cPtr = libsbmlJNI.KineticLaw_removeParameter__SWIG_0(swigCPtr, this, n); 853 return (cPtr == 0) ? null : new Parameter(cPtr, true); 854 } 855 856 857/** 858 * Removes the nth {@link LocalParameter} object in the list of local parameters 859 * in this {@link KineticLaw} instance and returns a pointer to it. 860 * <p> 861 * The caller owns the returned object and is responsible for deleting it. 862 * <p> 863 * @param n the index of the {@link LocalParameter} object to remove 864 * <p> 865 * @return the {@link LocalParameter} object removed. As mentioned above, 866 * the caller owns the returned item. <code>null</code> is returned if the given index 867 * is out of range. 868 */ public 869 LocalParameter removeLocalParameter(long n) { 870 long cPtr = libsbmlJNI.KineticLaw_removeLocalParameter__SWIG_0(swigCPtr, this, n); 871 return (cPtr == 0) ? null : new LocalParameter(cPtr, true); 872 } 873 874 875/** 876 * Removes a {@link Parameter} object with the given identifier in the list of 877 * local parameters in this {@link KineticLaw} instance and returns a pointer to it. 878 * <p> 879 * The caller owns the returned object and is responsible for deleting it. 880 * <p> 881 * @param sid the identifier of the {@link Parameter} to remove 882 * <p> 883 * @return the {@link Parameter} object removed. As mentioned above, the 884 * caller owns the returned object. <code>null</code> is returned if no {@link Parameter} 885 * object with the identifier exists in this {@link KineticLaw} instance. 886 */ public 887 Parameter removeParameter(String sid) { 888 long cPtr = libsbmlJNI.KineticLaw_removeParameter__SWIG_1(swigCPtr, this, sid); 889 return (cPtr == 0) ? null : new Parameter(cPtr, true); 890 } 891 892 893/** 894 * Removes a {@link LocalParameter} object with the given identifier in the list of 895 * local parameters in this {@link KineticLaw} instance and returns a pointer to it. 896 * <p> 897 * The caller owns the returned object and is responsible for deleting it. 898 * <p> 899 * @param sid the identifier of the {@link LocalParameter} to remove 900 * <p> 901 * @return the {@link LocalParameter} object removed. As mentioned above, the 902 * caller owns the returned object. <code>null</code> is returned if no {@link LocalParameter} 903 * object with the identifier exists in this {@link KineticLaw} instance. 904 */ public 905 LocalParameter removeLocalParameter(String sid) { 906 long cPtr = libsbmlJNI.KineticLaw_removeLocalParameter__SWIG_1(swigCPtr, this, sid); 907 return (cPtr == 0) ? null : new LocalParameter(cPtr, true); 908 } 909 910 911/** 912 * Sets this SBML object to child SBML objects (if any). 913 * (Creates a child-parent relationship by the parent) 914 * <p> 915 * Subclasses must override this function if they define 916 * one ore more child elements. 917 * Basically, this function needs to be called in 918 * constructor, copy constructor and assignment operator. 919 * <p> 920 * @see setSBMLDocument 921 * @see enablePackageInternal 922 * @internal 923 */ public 924 void connectToChild() { 925 libsbmlJNI.KineticLaw_connectToChild(swigCPtr, this); 926 } 927 928 929/** 930 * Enables/Disables the given package with this element and child 931 * elements (if any). 932 * (This is an internal implementation for enablePackage function) 933 * <p> 934 * @note Subclasses of the SBML Core package in which one or more child 935 * elements are defined must override this function. 936 * @internal 937 */ public 938 void enablePackageInternal(String pkgURI, String pkgPrefix, boolean flag) { 939 libsbmlJNI.KineticLaw_enablePackageInternal(swigCPtr, this, pkgURI, pkgPrefix, flag); 940 } 941 942 943/** 944 * Returns the libSBML type code for this SBML object. 945 * <p> 946 * LibSBML attaches an identifying code to every 947 * kind of SBML object. These are known as <em>SBML type codes</em>. In 948 * other languages, the set of type codes is stored in an enumeration; in 949 * the Java language interface for libSBML, the type codes are defined as 950 * static integer constants in the interface class {@link 951 * libsbmlConstants}. The names of the type codes all begin with the 952 * characters <code>SBML_.</code> 953 * <p> 954 * @return the SBML type code for this object, or {@link 955 * libsbmlConstants#SBML_UNKNOWN SBML_UNKNOWN} (default). 956 * <p> 957 * @see #getElementName() 958 */ public 959 int getTypeCode() { 960 return libsbmlJNI.KineticLaw_getTypeCode(swigCPtr, this); 961 } 962 963 964/** 965 * Returns the XML element name of this object, which for {@link Species}, is 966 * always <code>'kineticLaw'.</code> 967 * <p> 968 * @return the name of this element, i.e., <code>'kineticLaw'.</code> 969 */ public 970 String getElementName() { 971 return libsbmlJNI.KineticLaw_getElementName(swigCPtr, this); 972 } 973 974 975/** 976 * Predicate returning <code>true</code> if 977 * all the required attributes for this {@link KineticLaw} object 978 * have been set. 979 * <p> 980 * @note The required attributes for a {@link KineticLaw} object are: 981 * <ul> 982 * <li> 'formula' (SBML Level 1 only) 983 * </ul> 984 * <p> 985 * @return a boolean value indicating whether all the required 986 * attributes for this object have been defined. 987 */ public 988 boolean hasRequiredAttributes() { 989 return libsbmlJNI.KineticLaw_hasRequiredAttributes(swigCPtr, this); 990 } 991 992 993/** 994 * Predicate returning <code>true</code> if 995 * all the required elements for this {@link KineticLaw} object 996 * have been set. 997 * <p> 998 * @note The required elements for a {@link KineticLaw} object are: 999 * <ul> 1000 * <li> 'math' 1001 * </ul> 1002 * <p> 1003 * @return a boolean value indicating whether all the required 1004 * elements for this object have been defined. 1005 */ public 1006 boolean hasRequiredElements() { 1007 return libsbmlJNI.KineticLaw_hasRequiredElements(swigCPtr, this); 1008 } 1009 1010 1011/** 1012 * Finds this {@link KineticLaw}'s {@link Reaction} parent and calls unsetKineticLaw() on it, indirectly deleting itself. Overridden from the {@link SBase} function since the parent is not a {@link ListOf}. 1013 * <p> 1014 * @return integer value indicating success/failure of the 1015 * function. The possible values 1016 * returned by this function are: 1017 * <ul> 1018 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS } 1019 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED } 1020 * </ul> 1021 */ public 1022 int removeFromParentAndDelete() { 1023 return libsbmlJNI.KineticLaw_removeFromParentAndDelete(swigCPtr, this); 1024 } 1025 1026 1027/** 1028 * Renames all the SIdRef attributes on this element, including any found in MathML 1029 */ public 1030 void renameSIdRefs(String oldid, String newid) { 1031 libsbmlJNI.KineticLaw_renameSIdRefs(swigCPtr, this, oldid, newid); 1032 } 1033 1034 1035/** 1036 * Renames all the UnitSIdRef attributes on this element 1037 */ public 1038 void renameUnitSIdRefs(String oldid, String newid) { 1039 libsbmlJNI.KineticLaw_renameUnitSIdRefs(swigCPtr, this, oldid, newid); 1040 } 1041 1042 1043/** 1044 * Replace all nodes with the name 'id' from the child 'math' object with the provided function. 1045 * <p> 1046 * @internal 1047 */ public 1048 void replaceSIDWithFunction(String id, ASTNode function) { 1049 libsbmlJNI.KineticLaw_replaceSIDWithFunction(swigCPtr, this, id, ASTNode.getCPtr(function), function); 1050 } 1051 1052 1053/** 1054 * If this reaction id matches the provided 'id' string, replace the 'math' object with the function (existing/function). 1055 * @internal 1056 */ public 1057 void divideAssignmentsToSIdByFunction(String id, ASTNode function) { 1058 libsbmlJNI.KineticLaw_divideAssignmentsToSIdByFunction(swigCPtr, this, id, ASTNode.getCPtr(function), function); 1059 } 1060 1061 1062/** 1063 * If this assignment assigns a value to the 'id' element, replace the 'math' object with the function (existing*function). 1064 * @internal 1065 */ public 1066 void multiplyAssignmentsToSIdByFunction(String id, ASTNode function) { 1067 libsbmlJNI.KineticLaw_multiplyAssignmentsToSIdByFunction(swigCPtr, this, id, ASTNode.getCPtr(function), function); 1068 } 1069 1070}