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