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 EventAssignment construct for Event. 014 * <p> 015 * {@link Event} contains an optional element called 'listOfEventAssignments', of 016 * class {@link ListOfEventAssignments}. In every instance of an event definition 017 * in a model, the object's 'listOfEventAssignments' element must have a 018 * non-empty list of one or more 'eventAssignment' elements of class 019 * {@link EventAssignment}. The object class {@link EventAssignment} has one required 020 * attribute, 'variable', and a required element, 'math'. Being derived 021 * from {@link SBase}, it also has all the usual attributes and elements of its 022 * parent class. 023 * <p> 024 * An {@link Event} object defines when the event can occur, the variables that are 025 * affected by the event, and how the variables are affected. The purpose 026 * of the {@link EventAssignment} object class is to define how variables are 027 * affected by an {@link Event}. In SBML Level 2, every {@link Event} object instance 028 * must have a nonempty list of event assignments; in SBML Level 3, 029 * the list of assignments is optional. 030 * <p> 031 * The operation of an {@link Event} is divided into two phases (regardless of 032 * whether a delay is involved): one phase when the event is <em>triggered</em>, 033 * and the other when the event is <em>executed</em>. {@link EventAssignment} objects 034 * are interpreted when an event is executed. The effects are described 035 * below. 036 * <p> 037 * <h2>The attribute 'variable'</h2> 038 * <p> 039 * The {@link EventAssignment} attribute 'variable' must be the identifier of an 040 * existing {@link Compartment}, {@link Species}, {@link SpeciesReference}, or {@link Parameter} 041 * instance defined in the model. When the event is executed, the value of 042 * the model component identified by 'variable' is changed by the 043 * {@link EventAssignment} to the value computed by the 'math' element; that is, a 044 * species' quantity, species reference's stoichiometry, compartment's size 045 * or parameter's value are reset to the value computed by 'math'. 046 * <p> 047 * Certain restrictions are placed on what can appear in 'variable': 048 * <ul> 049 * <li> The object identified by the value of the {@link EventAssignment} attribute 050 * 'variable' must not have its 'constant' attribute set to or default to 051 * <code>true.</code> (Constants cannot be affected by events.) 052 * <p> 053 * <li> The 'variable' attribute must not contain the identifier of a 054 * reaction; only species, species references, compartment and parameter 055 * values may be set by an {@link Event}. 056 * <p> 057 * <li> The value of every 'variable' attribute must be unique among the set 058 * of {@link EventAssignment} structures within a given {@link Event} structure. In other 059 * words, a single event cannot have multiple {@link EventAssignment} objects 060 * assigning the same variable. (All of them would be performed at the 061 * same time when that particular {@link Event} triggers, resulting in 062 * indeterminacy.) However, <em>separate</em> {@link Event} instances can refer to the 063 * same variable. 064 * <p> 065 * <li> A variable cannot be assigned a value in an {@link EventAssignment} object 066 * instance and also be assigned a value by an {@link AssignmentRule}; i.e., the 067 * value of an {@link EventAssignment}'s 'variable' attribute cannot be the same as 068 * the value of a {@link AssignmentRule}' 'variable' attribute. (Assignment rules 069 * hold at all times, therefore it would be inconsistent to also define an 070 * event that reassigns the value of the same variable.) 071 * </ul> 072 * <p> 073 * Note that the time of assignment of the object identified by the 074 * value of the 'variable' attribute is always the time at which the {@link Event} 075 * is <em>executed</em>, not when it is <em>triggered</em>. The timing is 076 * controlled by the optional {@link Delay} in an {@link Event}. The time of 077 * assignment is not affected by the 'useValuesFromTriggerTime' 078 * attribute on Eventmdash;that attribute affects the time at which the 079 * {@link EventAssignment}'s 'math' expression is <em>evaluated</em>. In other 080 * words, SBML allows decoupling the time at which the 081 * 'variable' is assigned from the time at which its value 082 * expression is calculated. 083 * <p> 084 * <h2>The 'math' subelement in an {@link EventAssignment}</h2> 085 * <p> 086 * The MathML expression contained in an {@link EventAssignment} defines the new 087 * value of the variable being assigned by the {@link Event}. 088 * <p> 089 * As mentioned above, the time at which the expression in 'math' is 090 * evaluated is determined by the attribute 'useValuesFromTriggerTime' on 091 * {@link Event}. If the attribute value is <code>true</code>, the expression must be 092 * evaluated when the event is <em>triggered</em>; more precisely, the values of 093 * identifiers occurring in MathML <code><ci></code> elements in the 094 * {@link EventAssignment}'s 'math' expression are the values they have at the 095 * point when the event <em>triggered</em>. If, instead, 096 * 'useValuesFromTriggerTime''s value is <code>false</code>, it means the values at 097 * <em>execution</em> time should be used; that is, the values of identifiers 098 * occurring in MathML <code><ci></code> elements in the 099 * {@link EventAssignment}'s 'math' expression are the values they have at the 100 * point when the event <em>executed</em>. 101 * <p> 102 * <h2>SBML Level/Version differences</h2> 103 * <p> 104 * Between Version 4 and previous versions of SBML Level 2, the 105 * requirements regarding the matching of units between an 106 * EvengAssignment's formula and the units of the object identified by the 107 * 'variable' attribute changed. Previous versions required consistency, 108 * but in SBML Level 2 Version 4 and in SBML Level 3, unit 109 * consistency is only <em>recommended</em>. More precisely: 110 * <ul> 111 * <p> 112 * <li> In the case of a species, an {@link EventAssignment} sets the referenced 113 * species' quantity (concentration or amount of substance) to the value 114 * determined by the formula in the {@link EventAssignment}'s 'math' subelement. 115 * The units of the 'math' formula should (in SBML Level 2 116 * Version 4 and in Level 3) or must (in previous Versions of 117 * Level 2) be identical to the units of the species. 118 * <p> 119 * <li> (SBML Level 3 only.) In the case of a species reference, an 120 * {@link EventAssignment} sets the stoichiometry of the reactant or product 121 * referenced by the {@link SpeciesReference} object to the value determined by the 122 * formula in the 'math' element. The unit associated with the value 123 * produced by the 'math' formula should be <code>dimensionless</code>, because 124 * reactant and product stoichiometries in reactions are dimensionless 125 * quantities. 126 * <p> 127 * <li> In the case of a compartment, an {@link EventAssignment} sets the 128 * referenced compartment's size to the size determined by the formula in 129 * the 'math' subelement of the {@link EventAssignment}. The overall units of the 130 * formula should (in SBML Level 2 Version 4 and in Level 3) 131 * or must (in previous Versions of Level 2) be identical to the units 132 * specified for the size of the compartment identified by the 133 * {@link EventAssignment}'s 'variable' attribute. 134 * <p> 135 * <li> In the case of a parameter, an {@link EventAssignment} sets the referenced 136 * parameter's value to that determined by the formula in 'math'. The 137 * overall units of the formula should (in SBML Level 2 Version 4 138 * and Level 3) or must (in previous Versions of Level 2) be 139 * identical to the units defined for the parameter. 140 * </ul> 141 * <p> 142 * Note that the formula placed in the 'math' element <em>has no assumed 143 * units</em>. The consistency of the units of the formula, and the units 144 * of the entity which the assignment affects, must be explicitly 145 * established just as in the case of the value of the {@link Delay} subelement. 146 * An approach similar to the one discussed in the context of {@link Delay} may be 147 * used for the formula of an {@link EventAssignment}. 148 * <p> 149 * @see Event 150 * <p> 151 * <p> 152 */ 153 154public class EventAssignment extends SBase { 155 private long swigCPtr; 156 157 protected EventAssignment(long cPtr, boolean cMemoryOwn) 158 { 159 super(libsbmlJNI.EventAssignment_SWIGUpcast(cPtr), cMemoryOwn); 160 swigCPtr = cPtr; 161 } 162 163 protected static long getCPtr(EventAssignment obj) 164 { 165 return (obj == null) ? 0 : obj.swigCPtr; 166 } 167 168 protected static long getCPtrAndDisown (EventAssignment obj) 169 { 170 long ptr = 0; 171 172 if (obj != null) 173 { 174 ptr = obj.swigCPtr; 175 obj.swigCMemOwn = false; 176 } 177 178 return ptr; 179 } 180 181 protected void finalize() { 182 delete(); 183 } 184 185 public synchronized void delete() { 186 if (swigCPtr != 0) { 187 if (swigCMemOwn) { 188 swigCMemOwn = false; 189 libsbmlJNI.delete_EventAssignment(swigCPtr); 190 } 191 swigCPtr = 0; 192 } 193 super.delete(); 194 } 195 196 197/** 198 * Creates a new {@link EventAssignment} using the given SBML <code>level</code> and <code>version</code> 199 * values. 200 * <p> 201 * @param level a long integer, the SBML Level to assign to this {@link EventAssignment} 202 * <p> 203 * @param version a long integer, the SBML Version to assign to this 204 * {@link EventAssignment} 205 * <p> 206 * @throws SBMLConstructorException 207 * Thrown if the given <code>level</code> and <code>version</code> combination, or this kind 208 * of SBML object, are either invalid or mismatched with respect to the 209 * parent {@link SBMLDocument} object. 210 * <p> 211 * @note Upon the addition of a {@link EventAssignment} object to an {@link SBMLDocument} 212 * (e.g., using {@link Event#addEventAssignment(EventAssignment ea)}), 213 * the SBML Level, SBML Version and XML namespace of the document 214 * <em>override</em> the values used when creating the {@link EventAssignment} object via 215 * this constructor. This is necessary to ensure that an SBML document 216 * is a consistent structure. Nevertheless, the ability to supply the 217 * values at the time of creation of a {@link EventAssignment} is an important 218 * aid to producing valid SBML. Knowledge of the intented SBML Level and 219 * Version determine whether it is valid to assign a particular value to 220 * an attribute, or whether it is valid to add an object to an existing 221 * {@link SBMLDocument}. 222 */ public 223 EventAssignment(long level, long version) throws org.sbml.libsbml.SBMLConstructorException { 224 this(libsbmlJNI.new_EventAssignment__SWIG_0(level, version), true); 225 } 226 227 228/** 229 * Creates a new {@link EventAssignment} using the given {@link SBMLNamespaces} object 230 * <code>sbmlns</code>. 231 * <p> 232 * The {@link SBMLNamespaces} object encapsulates SBML Level/Version/namespaces 233 * information. It is used to communicate the SBML Level, Version, and 234 * (in Level 3) packages used in addition to SBML Level 3 Core. 235 * A common approach to using this class constructor is to create an 236 * {@link SBMLNamespaces} object somewhere in a program, once, then pass it to 237 * object constructors such as this one when needed. 238 * <p> 239 * @param sbmlns an {@link SBMLNamespaces} object. 240 * <p> 241 * @throws SBMLConstructorException 242 * Thrown if the given <code>level</code> and <code>version</code> combination, or this kind 243 * of SBML object, are either invalid or mismatched with respect to the 244 * parent {@link SBMLDocument} object. 245 * <p> 246 * @note Upon the addition of a {@link EventAssignment} object to an {@link SBMLDocument} 247 * (e.g., using {@link Event#addEventAssignment(EventAssignment ea)}), 248 * the SBML XML namespace of the document <em>overrides</em> the value used 249 * when creating the {@link EventAssignment} object via this constructor. This 250 * is necessary to ensure that an SBML document is a consistent 251 * structure. Nevertheless, the ability to supply the values at the time 252 * of creation of a {@link EventAssignment} is an important aid to producing 253 * valid SBML. Knowledge of the intented SBML Level and Version 254 * determine whether it is valid to assign a particular value to an 255 * attribute, or whether it is valid to add an object to an existing 256 * {@link SBMLDocument}. 257 */ public 258 EventAssignment(SBMLNamespaces sbmlns) throws org.sbml.libsbml.SBMLConstructorException { 259 this(libsbmlJNI.new_EventAssignment__SWIG_1(SBMLNamespaces.getCPtr(sbmlns), sbmlns), true); 260 } 261 262 263/** 264 * Copy constructor; creates a copy of this {@link EventAssignment}. 265 * <p> 266 * @param orig the object to copy. 267 * <p> 268 * @throws SBMLConstructorException 269 * Thrown if the argument <code>orig</code> is <code>null.</code> 270 */ public 271 EventAssignment(EventAssignment orig) throws org.sbml.libsbml.SBMLConstructorException { 272 this(libsbmlJNI.new_EventAssignment__SWIG_2(EventAssignment.getCPtr(orig), orig), true); 273 } 274 275 276/** 277 * Creates and returns a deep copy of this {@link EventAssignment}. 278 * <p> 279 * @return a (deep) copy of this {@link EventAssignment}. 280 */ public 281 EventAssignment cloneObject() { 282 long cPtr = libsbmlJNI.EventAssignment_cloneObject(swigCPtr, this); 283 return (cPtr == 0) ? null : new EventAssignment(cPtr, true); 284 } 285 286 287/** 288 * Get the value of this {@link EventAssignment}'s 'variable' attribute. 289 * <p> 290 * @return the identifier stored in the 'variable' attribute of this 291 * {@link EventAssignment}. 292 */ public 293 String getVariable() { 294 return libsbmlJNI.EventAssignment_getVariable(swigCPtr, this); 295 } 296 297 298/** 299 * Get the mathematical expression in this {@link EventAssignment}'s 'math' 300 * subelement. 301 * <p> 302 * @return the top {@link ASTNode} of an abstract syntax tree representing the 303 * mathematical formula in this {@link EventAssignment}. 304 */ public 305 ASTNode getMath() { 306 long cPtr = libsbmlJNI.EventAssignment_getMath(swigCPtr, this); 307 return (cPtr == 0) ? null : new ASTNode(cPtr, false); 308 } 309 310 311/** 312 * Predicate for testing whether the attribute 'variable' of this 313 * {@link EventAssignment} is set. 314 * <p> 315 * @return <code>true</code> if the 'variable' attribute of this {@link EventAssignment} 316 * is set, <code>false</code> otherwise. 317 */ public 318 boolean isSetVariable() { 319 return libsbmlJNI.EventAssignment_isSetVariable(swigCPtr, this); 320 } 321 322 323/** 324 * Predicate for testing whether the 'math' subelement of this 325 * {@link EventAssignment} is set. 326 * <p> 327 * @return <code>true</code> if this {@link EventAssignment} has a 'math' subelement, 328 * <code>false</code> otherwise. 329 */ public 330 boolean isSetMath() { 331 return libsbmlJNI.EventAssignment_isSetMath(swigCPtr, this); 332 } 333 334 335/** 336 * Sets the attribute 'variable' of this {@link EventAssignment} to a copy of 337 * the given identifier string. 338 * <p> 339 * @param sid the identifier of a {@link Compartment}, {@link Species} or (global) 340 * {@link Parameter} defined in this model. 341 * <p> 342 * @return integer value indicating success/failure of the 343 * function. The possible values 344 * returned by this function are: 345 * <ul> 346 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS } 347 * <li> {@link libsbmlConstants#LIBSBML_INVALID_ATTRIBUTE_VALUE LIBSBML_INVALID_ATTRIBUTE_VALUE } 348 * </ul> 349 */ public 350 int setVariable(String sid) { 351 return libsbmlJNI.EventAssignment_setVariable(swigCPtr, this, sid); 352 } 353 354 355/** 356 * Sets the 'math' subelement of this {@link EventAssignment} to a copy of the 357 * given {@link ASTNode}. 358 * <p> 359 * @param math an {@link ASTNode} that will be copied and stored as the 360 * mathematical formula for this {@link EventAssignment}. 361 * <p> 362 * @return integer value indicating success/failure of the 363 * function. The possible values 364 * returned by this function are: 365 * <ul> 366 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS } 367 * <li> {@link libsbmlConstants#LIBSBML_INVALID_OBJECT LIBSBML_INVALID_OBJECT } 368 * </ul> 369 */ public 370 int setMath(ASTNode math) { 371 return libsbmlJNI.EventAssignment_setMath(swigCPtr, this, ASTNode.getCPtr(math), math); 372 } 373 374 375/** 376 * Calculates and returns a {@link UnitDefinition} that expresses the units 377 * of measurement assumed for the 'math' expression of this 378 * {@link EventAssignment}. 379 * <p> 380 * The units are calculated based on the mathematical expression in the 381 * {@link EventAssignment} and the model quantities referenced by 382 * <code><ci></code> elements used within that expression. The 383 * {@link EventAssignment#getDerivedUnitDefinition()} method returns the 384 * calculated units. 385 * <p> 386 * Note that the functionality that facilitates unit analysis depends 387 * on the model as a whole. Thus, in cases where the object has not 388 * been added to a model or the model itself is incomplete, 389 * unit analysis is not possible and this method will return <code>null.</code> 390 * <p> 391 * @warning Note that it is possible the 'math' expression in the 392 * {@link EventAssignment} contains literal numbers or parameters with undeclared 393 * units. In those cases, it is not possible to calculate the units of 394 * the overall expression without making assumptions. LibSBML does not 395 * make assumptions about the units, and 396 * {@link EventAssignment#getDerivedUnitDefinition()} only returns the units as 397 * far as it is able to determine them. For example, in an expression 398 * <em>X + Y</em>, if <em>X</em> has unambiguously-defined units and 399 * <em>Y</em> does not, it will return the units of <em>X</em>. When 400 * using this method, <strong>it is critical that callers also invoke the 401 * method</strong> {@link EventAssignment#containsUndeclaredUnits()} <strong>to 402 * determine whether this situation holds</strong>. Callers should take 403 * suitable action in those situations. 404 * <p> 405 * @return a {@link UnitDefinition} that expresses the units of the math 406 * expression of this {@link EventAssignment}, or <code>null</code> if one cannot be constructed. 407 * <p> 408 * @see #containsUndeclaredUnits() 409 */ public 410 UnitDefinition getDerivedUnitDefinition() { 411 long cPtr = libsbmlJNI.EventAssignment_getDerivedUnitDefinition__SWIG_0(swigCPtr, this); 412 return (cPtr == 0) ? null : new UnitDefinition(cPtr, false); 413 } 414 415 416/** 417 * Predicate returning <code>true</code> if the math 418 * expression of this {@link EventAssignment} contains literal numbers or 419 * parameters with undeclared units. 420 * <p> 421 * The {@link EventAssignment#getDerivedUnitDefinition()} method returns what 422 * libSBML computes to be the units of the 'math', to the extent that 423 * libSBML can compute them. However, if the expression contains literal 424 * numbers or parameters with undeclared units, libSBML may not be able 425 * to compute the full units of the expression and will only return what 426 * it can compute. Callers should always use 427 * {@link EventAssignment#containsUndeclaredUnits()} when using 428 * {@link EventAssignment#getDerivedUnitDefinition()} to decide whether the 429 * returned units may be incomplete. 430 * <p> 431 * @return <code>true</code> if the math expression of this {@link EventAssignment} 432 * includes parameters/numbers 433 * with undeclared units, <code>false</code> otherwise. 434 * <p> 435 * @note A return value of <code>true</code> indicates that the {@link UnitDefinition} 436 * returned by {@link EventAssignment#getDerivedUnitDefinition()} may not 437 * accurately represent the units of the expression. 438 * <p> 439 * @see #getDerivedUnitDefinition() 440 */ public 441 boolean containsUndeclaredUnits() { 442 return libsbmlJNI.EventAssignment_containsUndeclaredUnits__SWIG_0(swigCPtr, this); 443 } 444 445 446/** 447 * Returns the libSBML type code of this object instance. 448 * <p> 449 * LibSBML attaches an identifying code to every 450 * kind of SBML object. These are known as <em>SBML type codes</em>. In 451 * other languages, the set of type codes is stored in an enumeration; in 452 * the Java language interface for libSBML, the type codes are defined as 453 * static integer constants in the interface class {@link 454 * libsbmlConstants}. The names of the type codes all begin with the 455 * characters <code>SBML_.</code> 456 * <p> 457 * @return the SBML type code for this object, or {@link libsbmlConstants#SBML_UNKNOWN SBML_UNKNOWN} (default). 458 * <p> 459 * @see #getElementName() 460 */ public 461 int getTypeCode() { 462 return libsbmlJNI.EventAssignment_getTypeCode(swigCPtr, this); 463 } 464 465 466/** 467 * Returns the XML element name of this object, which for 468 * {@link EventAssignment}, is always <code>'eventAssignment'.</code> 469 * <p> 470 * @return the name of this element, i.e., <code>'eventAssignment'.</code> 471 */ public 472 String getElementName() { 473 return libsbmlJNI.EventAssignment_getElementName(swigCPtr, this); 474 } 475 476 477/** 478 * Predicate returning <code>true</code> if 479 * all the required attributes for this {@link EventAssignment} object 480 * have been set. 481 * <p> 482 * @note The required attributes for a {@link EventAssignment} object are: 483 * <ul> 484 * <li> 'variable' 485 * </ul> 486 * <p> 487 * @return a boolean value indicating whether all the required 488 * attributes for this object have been defined. 489 */ public 490 boolean hasRequiredAttributes() { 491 return libsbmlJNI.EventAssignment_hasRequiredAttributes(swigCPtr, this); 492 } 493 494 495/** 496 * Predicate returning <code>true</code> if 497 * all the required elements for this {@link EventAssignment} object 498 * have been set. 499 * <p> 500 * @note The required elements for a {@link EventAssignment} object are: 501 * <ul> 502 * <li> 'math' 503 * </ul> 504 * <p> 505 * @return a boolean value indicating whether all the required 506 * elements for this object have been defined. 507 */ public 508 boolean hasRequiredElements() { 509 return libsbmlJNI.EventAssignment_hasRequiredElements(swigCPtr, this); 510 } 511 512 513/** 514 * Predicate returning <code>true</code> if 515 * all the required elements for this {@link EventAssignment} object 516 * have been set. 517 * <p> 518 * @note The required elements for a {@link EventAssignment} object are: 519 * <ul> 520 * <li> 'math' 521 * </ul> 522 * <p> 523 * @return a boolean value indicating whether all the required 524 * elements for this object have been defined. 525 * @internal 526 */ public 527 String getId() { 528 return libsbmlJNI.EventAssignment_getId(swigCPtr, this); 529 } 530 531 532/** 533 * Renames all the SIdRef attributes on this element, including any found in MathML 534 */ public 535 void renameSIdRefs(String oldid, String newid) { 536 libsbmlJNI.EventAssignment_renameSIdRefs(swigCPtr, this, oldid, newid); 537 } 538 539 540/** 541 * Renames all the UnitSIdRef attributes on this element 542 */ public 543 void renameUnitSIdRefs(String oldid, String newid) { 544 libsbmlJNI.EventAssignment_renameUnitSIdRefs(swigCPtr, this, oldid, newid); 545 } 546 547 548/** 549 * Replace all nodes with the name 'id' from the child 'math' object with the provided function. 550 * @internal 551 */ public 552 void replaceSIDWithFunction(String id, ASTNode function) { 553 libsbmlJNI.EventAssignment_replaceSIDWithFunction(swigCPtr, this, id, ASTNode.getCPtr(function), function); 554 } 555 556 557/** 558 * If this assignment assigns a value to the 'id' element, replace the 'math' object with the function (existing/function). 559 * @internal 560 */ public 561 void divideAssignmentsToSIdByFunction(String id, ASTNode function) { 562 libsbmlJNI.EventAssignment_divideAssignmentsToSIdByFunction(swigCPtr, this, id, ASTNode.getCPtr(function), function); 563 } 564 565 566/** 567 * If this assignment assigns a value to the 'id' element, replace the 'math' object with the function (existing*function). 568 * @internal 569 */ public 570 void multiplyAssignmentsToSIdByFunction(String id, ASTNode function) { 571 libsbmlJNI.EventAssignment_multiplyAssignmentsToSIdByFunction(swigCPtr, this, id, ASTNode.getCPtr(function), function); 572 } 573 574}