001/* ---------------------------------------------------------------------------- 002 * This file was automatically generated by SWIG (http://www.swig.org). 003 * Version 2.0.12 004 * 005 * Do not make changes to this file unless you know what you are doing--modify 006 * the SWIG interface file instead. 007 * ----------------------------------------------------------------------------- */ 008 009package org.sbml.libsbml; 010 011/** 012 * Implementation of SBML's Trigger construct for Event. 013 <p> 014 * An {@link Event} object defines when the event can occur, the variables that are 015 * affected by the event, and how the variables are affected. The {@link Trigger} 016 * construct in SBML is used to define a mathematical expression that 017 * determines when an {@link Event} is <em>triggered</em>. 018 <p> 019 * A {@link Trigger} object in SBML Level 2 and Level 3 contains one 020 * subelement named 'math' containing a MathML expression. The expression 021 * must evaluate to a value of type <code>boolean.</code> The exact moment at which 022 * the expression evaluates to <code>true</code> is the time point when the {@link Event} is 023 * <em>triggered</em>. In SBML Level 3, {@link Trigger} has additional attributes 024 * that must be assigned values; they are discussed in a separate section 025 * below. 026 <p> 027 * An event only <em>triggers</em> when its {@link Trigger} expression makes the 028 * transition in value from <code>false</code> to <code>true.</code> The event will also 029 * trigger at any subsequent time points when the trigger makes this 030 * transition; in other words, an event can be triggered multiple times 031 * during a simulation if its trigger condition makes the transition from 032 * <code>false</code> to <code>true</code> more than once. In SBML Level 3, the behavior 033 * at the very start of simulation (i.e., at <em>t = 0</em>, where 034 * <em>t</em> stands for time) is determined in part by the boolean flag 035 * 'initialValue'. This and other additional features introduced in SBML 036 * Level 3 are discussed further below. 037 <p> 038 * <h2>Version differences</h2> 039 <p> 040 * SBML Level 3 Version 1 introduces two required attributes 041 * on the {@link Trigger} object: 'persistent' and 'initialValue'. The rest of 042 * this introduction describes these two attributes. 043 <p> 044 * <h3>The 'persistent' attribute on {@link Trigger}</h3> 045 <p> 046 * In the interval between when an {@link Event} object <em>triggers</em> (i.e., 047 * its {@link Trigger} object expression transitions in value from <code>false</code> to 048 * <code>true</code>) and when its assignments are to be <em>executed</em>, conditions 049 * in the model may change such that the trigger expression transitions 050 * back from <code>true</code> to <code>false.</code> Should the event's assignments still be 051 * made if this happens? Answering this question is the purpose of the 052 * 'persistent' attribute on {@link Trigger}. 053 <p> 054 * If the boolean attribute 'persistent' has a value of <code>true</code>, then once 055 * the event is triggered, all of its assignments are always performed when 056 * the time of execution is reached. The name <em>persistent</em> is meant to 057 * evoke the idea that the trigger expression does not have to be 058 * re-checked after it triggers if 'persistent'=<code>true.</code> Conversely, if 059 * the attribute value is <code>false</code>, then the trigger expression is not 060 * assumed to persist: if the expression transitions in value back to 061 * <code>false</code> at any time between when the event triggered and when it is to be 062 * executed, the event is no longer considered to have triggered and its 063 * assignments are not executed. (If the trigger expression transitions 064 * once more to <code>true</code> after that point, then the event is triggered, but 065 * this then constitutes a whole new event trigger-and-execute sequence.) 066 <p> 067 * The 'persistent' attribute can be especially useful when {@link Event} objects 068 * contain {@link Delay} objects, but it is relevant even in a model without delays 069 * if the model contains two or more events. As explained in the 070 * introduction to this section, the operation of all events in SBML 071 * (delayed or not) is conceptually divided into two phases, 072 * <em>triggering</em> and <em>execution</em>; however, unless events have 073 * priorities associated with them, SBML does not mandate a particular 074 * ordering of event execution in the case of simultaneous events. Models 075 * with multiple events can lead to situations where the execution of one 076 * event affects another event's trigger expression value. If that other 077 * event has 'persistent'=<code>false</code>, and its trigger expression evaluates to 078 * <code>false</code> before it is to be executed, the event must not be executed 079 * after all. 080 <p> 081 * <h3>The 'initialValue' attribute on {@link Trigger}</h3> 082 <p> 083 * As mentioned above, an event <em>triggers</em> when the mathematical 084 * expression in its {@link Trigger} object transitions in value from <code>false</code> to 085 * <code>true.</code> An unanswered question concerns what happens at the start of a 086 * simulation: can event triggers make this transition at <em>t = 0</em>, 087 * where <em>t</em> stands for time? 088 <p> 089 * In order to determine whether an event may trigger at <em>t = 0</em>, it 090 * is necessary to know what value the {@link Trigger} object's 'math' expression 091 * had immediately prior to <em>t = 0</em>. This starting value of the 092 * trigger expression is determined by the value of the boolean attribute 093 * 'initialValue'. A value of <code>true</code> means the trigger expression is 094 * taken to have the value <code>true</code> immediately prior to <em>t = 0</em>. In 095 * that case, the trigger cannot transition in value from <code>false</code> to 096 * <code>true</code> at the moment simulation begins (because it has the value <code>true</code> 097 * both before and after <em>t = 0</em>), and can only make the transition 098 * from <code>false</code> to <code>true</code> sometime <em>after</em> <em>t = 0</em>. (To do 099 * that, it would also first have to transition to <code>false</code> before it could 100 * make the transition from <code>false</code> back to <code>true.</code>) Conversely, if 101 * 'initialValue'=<code>false</code>, then the trigger expression is assumed to start 102 * with the value <code>false</code>, and therefore may trigger at <em>t = 0</em> if 103 * the expression evaluates to <code>true</code> at that moment. 104 <p> 105 <p> 106 * @see Event 107 * @see Delay 108 * @see EventAssignment 109 */ 110 111public class Trigger extends SBase { 112 private long swigCPtr; 113 114 protected Trigger(long cPtr, boolean cMemoryOwn) 115 { 116 super(libsbmlJNI.Trigger_SWIGUpcast(cPtr), cMemoryOwn); 117 swigCPtr = cPtr; 118 } 119 120 protected static long getCPtr(Trigger obj) 121 { 122 return (obj == null) ? 0 : obj.swigCPtr; 123 } 124 125 protected static long getCPtrAndDisown (Trigger obj) 126 { 127 long ptr = 0; 128 129 if (obj != null) 130 { 131 ptr = obj.swigCPtr; 132 obj.swigCMemOwn = false; 133 } 134 135 return ptr; 136 } 137 138 protected void finalize() { 139 delete(); 140 } 141 142 public synchronized void delete() { 143 if (swigCPtr != 0) { 144 if (swigCMemOwn) { 145 swigCMemOwn = false; 146 libsbmlJNI.delete_Trigger(swigCPtr); 147 } 148 swigCPtr = 0; 149 } 150 super.delete(); 151 } 152 153 154/** 155 * Creates a new {@link Trigger} using the given SBML <code>level</code> and <code>version</code> 156 * values. 157 <p> 158 * @param level a long integer, the SBML Level to assign to this {@link Trigger} 159 <p> 160 * @param version a long integer, the SBML Version to assign to this 161 * {@link Trigger} 162 <p> 163 * @throws SBMLConstructorException 164 * Thrown if the given <code>level</code> and <code>version</code> combination, or this kind 165 * of SBML object, are either invalid or mismatched with respect to the 166 * parent {@link SBMLDocument} object. 167 */ public 168 Trigger(long level, long version) throws org.sbml.libsbml.SBMLConstructorException { 169 this(libsbmlJNI.new_Trigger__SWIG_0(level, version), true); 170 } 171 172 173/** 174 * Creates a new {@link Trigger} using the given {@link SBMLNamespaces} object 175 * <code>sbmlns</code>. 176 <p> 177 * <p> 178 * The {@link SBMLNamespaces} object encapsulates SBML Level/Version/namespaces 179 * information. It is used to communicate the SBML Level, Version, and (in 180 * Level 3) packages used in addition to SBML Level 3 Core. A 181 * common approach to using libSBML's {@link SBMLNamespaces} facilities is to create an 182 * {@link SBMLNamespaces} object somewhere in a program once, then hand that object 183 * as needed to object constructors that accept {@link SBMLNamespaces} as arguments. 184 <p> 185 * @param sbmlns an {@link SBMLNamespaces} object. 186 <p> 187 * @throws SBMLConstructorException 188 * Thrown if the given <code>level</code> and <code>version</code> combination, or this kind 189 * of SBML object, are either invalid or mismatched with respect to the 190 * parent {@link SBMLDocument} object. 191 */ public 192 Trigger(SBMLNamespaces sbmlns) throws org.sbml.libsbml.SBMLConstructorException { 193 this(libsbmlJNI.new_Trigger__SWIG_1(SBMLNamespaces.getCPtr(sbmlns), sbmlns), true); 194 } 195 196 197/** 198 * Copy constructor; creates a copy of this {@link Trigger}. 199 <p> 200 * @param orig the object to copy. 201 <p> 202 * @throws SBMLConstructorException 203 * Thrown if the argument <code>orig</code> is <code>null.</code> 204 */ public 205 Trigger(Trigger orig) throws org.sbml.libsbml.SBMLConstructorException { 206 this(libsbmlJNI.new_Trigger__SWIG_2(Trigger.getCPtr(orig), orig), true); 207 } 208 209 210/** 211 * Creates and returns a deep copy of this {@link Trigger}. 212 <p> 213 * @return a (deep) copy of this {@link Trigger}. 214 */ public 215 Trigger cloneObject() { 216 long cPtr = libsbmlJNI.Trigger_cloneObject(swigCPtr, this); 217 return (cPtr == 0) ? null : new Trigger(cPtr, true); 218 } 219 220 221/** 222 * Get the mathematical formula for the trigger and return it 223 * as an AST. 224 <p> 225 * @return the math of this {@link Trigger}. 226 */ public 227 ASTNode getMath() { 228 long cPtr = libsbmlJNI.Trigger_getMath(swigCPtr, this); 229 return (cPtr == 0) ? null : new ASTNode(cPtr, false); 230 } 231 232 233/** 234 * (SBML Level 3 only) Get the value of the 'initialValue' attribute 235 * of this {@link Trigger}. 236 <p> 237 * @return the boolean value stored as the 'initialValue' attribute value 238 * in this {@link Trigger}. 239 <p> 240 * @note The attribute 'initialValue' is available in SBML Level 3 241 * Version 1 Core, but is not present in lower Levels of SBML. 242 */ public 243 boolean getInitialValue() { 244 return libsbmlJNI.Trigger_getInitialValue(swigCPtr, this); 245 } 246 247 248/** 249 * (SBML Level 3 only) Get the value of the 'persistent' attribute 250 * of this {@link Trigger}. 251 <p> 252 * @return the boolean value stored as the 'persistent' attribute value 253 * in this {@link Trigger}. 254 <p> 255 * @note The attribute 'persistent' is available in SBML Level 3 256 * Version 1 Core, but is not present in lower Levels of SBML. 257 */ public 258 boolean getPersistent() { 259 return libsbmlJNI.Trigger_getPersistent(swigCPtr, this); 260 } 261 262 263/** 264 * Predicate to test whether the math for this trigger is set. 265 <p> 266 * @return <code>true</code> if the formula (meaning the 'math' subelement) of 267 * this {@link Trigger} is set, <code>false</code> otherwise. 268 */ public 269 boolean isSetMath() { 270 return libsbmlJNI.Trigger_isSetMath(swigCPtr, this); 271 } 272 273 274/** 275 * (SBML Level 3 only) Predicate to test whether the 'initialValue' 276 * attribute for this trigger is set. 277 <p> 278 * @return <code>true</code> if the initialValue attribute of 279 * this {@link Trigger} is set, <code>false</code> otherwise. 280 <p> 281 * @note The attribute 'initialValue' is available in SBML Level 3 282 * Version 1 Core, but is not present in lower Levels of SBML. 283 */ public 284 boolean isSetInitialValue() { 285 return libsbmlJNI.Trigger_isSetInitialValue(swigCPtr, this); 286 } 287 288 289/** 290 * (SBML Level 3 only) Predicate to test whether the 'persistent' 291 * attribute for this trigger is set. 292 <p> 293 * @return <code>true</code> if the persistent attribute of 294 * this {@link Trigger} is set, <code>false</code> otherwise. 295 <p> 296 * @note The attribute 'persistent' is available in SBML Level 3 297 * Version 1 Core, but is not present in lower Levels of SBML. 298 */ public 299 boolean isSetPersistent() { 300 return libsbmlJNI.Trigger_isSetPersistent(swigCPtr, this); 301 } 302 303 304/** 305 * Sets the trigger expression of this {@link Trigger} instance to a copy of the given 306 * {@link ASTNode}. 307 <p> 308 * @param math an {@link ASTNode} representing a formula tree. 309 <p> 310 * @return integer value indicating success/failure of the 311 * function. The possible values 312 * returned by this function are: 313 * <ul> 314 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS } 315 * <li> {@link libsbmlConstants#LIBSBML_INVALID_OBJECT LIBSBML_INVALID_OBJECT } 316 * </ul> 317 */ public 318 int setMath(ASTNode math) { 319 return libsbmlJNI.Trigger_setMath(swigCPtr, this, ASTNode.getCPtr(math), math); 320 } 321 322 323/** 324 * (SBML Level 3 only) Sets the 'initialValue' attribute of this {@link Trigger} instance. 325 <p> 326 * @param initialValue a boolean representing the initialValue to be set. 327 <p> 328 * @return integer value indicating success/failure of the 329 * function. The possible values 330 * returned by this function are: 331 * <ul> 332 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS } 333 * <li> {@link libsbmlConstants#LIBSBML_UNEXPECTED_ATTRIBUTE LIBSBML_UNEXPECTED_ATTRIBUTE } 334 * 335 * </ul> <p> 336 * @note The attribute 'initialValue' is available in SBML Level 3 337 * Version 1 Core, but is not present in lower Levels of SBML. 338 */ public 339 int setInitialValue(boolean initialValue) { 340 return libsbmlJNI.Trigger_setInitialValue(swigCPtr, this, initialValue); 341 } 342 343 344/** 345 * (SBML Level 3 only) Sets the 'persistent' attribute of this {@link Trigger} instance. 346 <p> 347 * @param persistent a boolean representing the persistent value to be set. 348 <p> 349 * @return integer value indicating success/failure of the 350 * function. The possible values 351 * returned by this function are: 352 * <ul> 353 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS } 354 * <li> {@link libsbmlConstants#LIBSBML_UNEXPECTED_ATTRIBUTE LIBSBML_UNEXPECTED_ATTRIBUTE } 355 * 356 * </ul> <p> 357 * @note The attribute 'persistent' is available in SBML Level 3 358 * Version 1 Core, but is not present in lower Levels of SBML. 359 */ public 360 int setPersistent(boolean persistent) { 361 return libsbmlJNI.Trigger_setPersistent(swigCPtr, this, persistent); 362 } 363 364 365/** 366 * Returns the libSBML type code of this object instance. 367 <p> 368 * <p> 369 * LibSBML attaches an identifying code to every kind of SBML object. These 370 * are integer constants known as <em>SBML type codes</em>. The names of all 371 * the codes begin with the characters “<code>SBML_</code>”. 372 * In the Java language interface for libSBML, the 373 * type codes are defined as static integer constants in the interface class 374 * {@link libsbmlConstants}. Note that different Level 3 375 * package plug-ins may use overlapping type codes; to identify the package 376 * to which a given object belongs, call the <code>getPackageName()</code> 377 * method on the object. 378 <p> 379 * @return the SBML type code for this object: 380 * {@link libsbmlConstants#SBML_TRIGGER SBML_TRIGGER} (default). 381 <p> 382 * <p> 383 * @warning <span class='warning'>The specific integer values of the possible 384 * type codes may be reused by different Level 3 package plug-ins. 385 * Thus, to identifiy the correct code, <strong>it is necessary to invoke 386 * both getTypeCode() and getPackageName()</strong>.</span> 387 <p> 388 * @see #getElementName() 389 * @see #getPackageName() 390 */ public 391 int getTypeCode() { 392 return libsbmlJNI.Trigger_getTypeCode(swigCPtr, this); 393 } 394 395 396/** 397 * Returns the XML element name of this object, which for {@link Trigger}, is 398 * always <code>'trigger'.</code> 399 <p> 400 * @return the name of this element, i.e., <code>'trigger'.</code> 401 */ public 402 String getElementName() { 403 return libsbmlJNI.Trigger_getElementName(swigCPtr, this); 404 } 405 406 407/** 408 * Renames all the <code>SIdRef</code> attributes on this element, including any 409 * found in MathML. 410 <p> 411 * <p> 412 * In SBML, object identifiers are of a data type called <code>SId</code>. 413 * In SBML Level 3, an explicit data type called <code>SIdRef</code> was 414 * introduced for attribute values that refer to <code>SId</code> values; in 415 * previous Levels of SBML, this data type did not exist and attributes were 416 * simply described to as 'referring to an identifier', but the effective 417 * data type was the same as <code>SIdRef</code>in Level 3. These and 418 * other methods of libSBML refer to the type <code>SIdRef</code> for all 419 * Levels of SBML, even if the corresponding SBML specification did not 420 * explicitly name the data type. 421 <p> 422 * This method works by looking at all attributes and (if appropriate) 423 * mathematical formulas, comparing the identifiers to the value of 424 * <code>oldid</code>. If any matches are found, the matching identifiers are replaced 425 * with <code>newid</code>. The method does <em>not</em> descend into child elements. 426 <p> 427 * @param oldid the old identifier 428 * @param newid the new identifier 429 */ public 430 void renameSIdRefs(String oldid, String newid) { 431 libsbmlJNI.Trigger_renameSIdRefs(swigCPtr, this, oldid, newid); 432 } 433 434 435/** 436 * Renames all the <code>UnitSIdRef</code> attributes on this element. 437 <p> 438 * <p> 439 * In SBML, unit definitions have identifiers of type <code>UnitSId</code>. In 440 * SBML Level 3, an explicit data type called <code>UnitSIdRef</code> was 441 * introduced for attribute values that refer to <code>UnitSId</code> values; in 442 * previous Levels of SBML, this data type did not exist and attributes were 443 * simply described to as 'referring to a unit identifier', but the effective 444 * data type was the same as <code>UnitSIdRef</code> in Level 3. These and 445 * other methods of libSBML refer to the type <code>UnitSIdRef</code> for all 446 * Levels of SBML, even if the corresponding SBML specification did not 447 * explicitly name the data type. 448 <p> 449 * This method works by looking at all unit identifier attribute values 450 * (including, if appropriate, inside mathematical formulas), comparing the 451 * unit identifiers to the value of <code>oldid</code>. If any matches are found, 452 * the matching identifiers are replaced with <code>newid</code>. The method does 453 * <em>not</em> descend into child elements. 454 <p> 455 * @param oldid the old identifier 456 * @param newid the new identifier 457 */ public 458 void renameUnitSIdRefs(String oldid, String newid) { 459 libsbmlJNI.Trigger_renameUnitSIdRefs(swigCPtr, this, oldid, newid); 460 } 461 462 463/** 464 * Replace all nodes with the name 'id' from the child 'math' object with the provided function. 465 <p> 466 * @internal 467 */ public 468 void replaceSIDWithFunction(String id, ASTNode function) { 469 libsbmlJNI.Trigger_replaceSIDWithFunction(swigCPtr, this, id, ASTNode.getCPtr(function), function); 470 } 471 472 473/** 474 * Predicate returning <code>true</code> if 475 * all the required elements for this {@link Trigger} object 476 * have been set. 477 <p> 478 * @note The required elements for a {@link Trigger} object are: 479 * <ul> 480 * <li> 'math' 481 * 482 * </ul> <p> 483 * @return a boolean value indicating whether all the required 484 * elements for this object have been defined. 485 */ public 486 boolean hasRequiredElements() { 487 return libsbmlJNI.Trigger_hasRequiredElements(swigCPtr, this); 488 } 489 490 491/** 492 * Predicate returning <code>true</code> if 493 * all the required attributes for this {@link Trigger} object 494 * have been set. 495 <p> 496 * @note The required attributes for a {@link Trigger} object are: 497 * <ul> 498 * <li> 'persistent' (required in SBML Level 3) 499 * <li> 'initialValue' (required in SBML Level 3) 500 * 501 * </ul> <p> 502 * @return a boolean value indicating whether all the required 503 * attributes for this object have been defined. 504 */ public 505 boolean hasRequiredAttributes() { 506 return libsbmlJNI.Trigger_hasRequiredAttributes(swigCPtr, this); 507 } 508 509 510/** 511 * Finds this {@link Trigger}'s {@link Event} parent and calls unsetTrigger() on it, indirectly deleting itself. Overridden from the {@link SBase} function since the parent is not a {@link ListOf}. 512 <p> 513 * @return integer value indicating success/failure of the 514 * function. The possible values 515 * returned by this function are: 516 * <ul> 517 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS } 518 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED } 519 * </ul> 520 */ public 521 int removeFromParentAndDelete() { 522 return libsbmlJNI.Trigger_removeFromParentAndDelete(swigCPtr, this); 523 } 524 525}