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 Trigger construct for Event. 014 * <p> 015 * An {@link Event} object defines when the event can occur, the variables that are 016 * affected by the event, and how the variables are affected. The {@link Trigger} 017 * construct in SBML is used to define a mathematical expression that 018 * determines when an {@link Event} is <em>triggered</em>. 019 * <p> 020 * A {@link Trigger} object in SBML Level 2 and Level 3 contains one 021 * subelement named 'math' containing a MathML expression. The expression 022 * must evaluate to a value of type <code>boolean.</code> The exact moment at which 023 * the expression evaluates to <code>true</code> is the time point when the {@link Event} is 024 * <em>triggered</em>. In SBML Level 3, {@link Trigger} has additional attributes 025 * that must be assigned values; they are discussed in a separate section 026 * below. 027 * <p> 028 * An event only <em>triggers</em> when its {@link Trigger} expression makes the 029 * transition in value from <code>false</code> to <code>true.</code> The event will also 030 * trigger at any subsequent time points when the trigger makes this 031 * transition; in other words, an event can be triggered multiple times 032 * during a simulation if its trigger condition makes the transition from 033 * <code>false</code> to <code>true</code> more than once. In SBML Level 3, the behavior 034 * at the very start of simulation (i.e., at <em>t = 0</em>, where 035 * <em>t</em> stands for time) is determined in part by the boolean flag 036 * 'initialValue'. This and other additional features introduced in SBML 037 * Level 3 are discussed further below. 038 * <p> 039 * <h2>Version differences</h2> 040 * <p> 041 * SBML Level 3 Version 1 introduces two required attributes 042 * on the {@link Trigger} object: 'persistent' and 'initialValue'. The rest of 043 * this introduction describes these two attributes. 044 * <p> 045 * <h3>The 'persistent' attribute on {@link Trigger}</h3> 046 * <p> 047 * In the interval between when an {@link Event} object <em>triggers</em> (i.e., 048 * its {@link Trigger} object expression transitions in value from <code>false</code> to 049 * <code>true</code>) and when its assignments are to be <em>executed</em>, conditions 050 * in the model may change such that the trigger expression transitions 051 * back from <code>true</code> to <code>false.</code> Should the event's assignments still be 052 * made if this happens? Answering this question is the purpose of the 053 * 'persistent' attribute on {@link Trigger}. 054 * <p> 055 * If the boolean attribute 'persistent' has a value of <code>true</code>, then once 056 * the event is triggered, all of its assignments are always performed when 057 * the time of execution is reached. The name <em>persistent</em> is meant to 058 * evoke the idea that the trigger expression does not have to be 059 * re-checked after it triggers if 'persistent'=<code>true.</code> Conversely, if 060 * the attribute value is <code>false</code>, then the trigger expression is not 061 * assumed to persist: if the expression transitions in value back to 062 * <code>false</code> at any time between when the event triggered and when it is to be 063 * executed, the event is no longer considered to have triggered and its 064 * assignments are not executed. (If the trigger expression transitions 065 * once more to <code>true</code> after that point, then the event is triggered, but 066 * this then constitutes a whole new event trigger-and-execute sequence.) 067 * <p> 068 * The 'persistent' attribute can be especially useful when {@link Event} objects 069 * contain {@link Delay} objects, but it is relevant even in a model without delays 070 * if the model contains two or more events. As explained in the 071 * introduction to this section, the operation of all events in SBML 072 * (delayed or not) is conceptually divided into two phases, 073 * <em>triggering</em> and <em>execution</em>; however, unless events have 074 * priorities associated with them, SBML does not mandate a particular 075 * ordering of event execution in the case of simultaneous events. Models 076 * with multiple events can lead to situations where the execution of one 077 * event affects another event's trigger expression value. If that other 078 * event has 'persistent'=<code>false</code>, and its trigger expression evaluates to 079 * <code>false</code> before it is to be executed, the event must not be executed 080 * after all. 081 * <p> 082 * <h3>The 'initialValue' attribute on {@link Trigger}</h3> 083 * <p> 084 * As mentioned above, an event <em>triggers</em> when the mathematical 085 * expression in its {@link Trigger} object transitions in value from <code>false</code> to 086 * <code>true.</code> An unanswered question concerns what happens at the start of a 087 * simulation: can event triggers make this transition at <em>t = 0</em>, 088 * where <em>t</em> stands for time? 089 * <p> 090 * In order to determine whether an event may trigger at <em>t = 0</em>, it 091 * is necessary to know what value the {@link Trigger} object's 'math' expression 092 * had immediately prior to <em>t = 0</em>. This starting value of the 093 * trigger expression is determined by the value of the boolean attribute 094 * 'initialValue'. A value of <code>true</code> means the trigger expression is 095 * taken to have the value <code>true</code> immediately prior to <em>t = 0</em>. In 096 * that case, the trigger cannot transition in value from <code>false</code> to 097 * <code>true</code> at the moment simulation begins (because it has the value <code>true</code> 098 * both before and after <em>t = 0</em>), and can only make the transition 099 * from <code>false</code> to <code>true</code> sometime <em>after</em> <em>t = 0</em>. (To do 100 * that, it would also first have to transition to <code>false</code> before it could 101 * make the transition from <code>false</code> back to <code>true.</code>) Conversely, if 102 * 'initialValue'=<code>false</code>, then the trigger expression is assumed to start 103 * with the value <code>false</code>, and therefore may trigger at <em>t = 0</em> if 104 * the expression evaluates to <code>true</code> at that moment. 105 * <p> 106 * <p> 107 * @see Event 108 * @see Delay 109 * @see EventAssignment 110 */ 111 112public class Trigger extends SBase { 113 private long swigCPtr; 114 115 protected Trigger(long cPtr, boolean cMemoryOwn) 116 { 117 super(libsbmlJNI.Trigger_SWIGUpcast(cPtr), cMemoryOwn); 118 swigCPtr = cPtr; 119 } 120 121 protected static long getCPtr(Trigger obj) 122 { 123 return (obj == null) ? 0 : obj.swigCPtr; 124 } 125 126 protected static long getCPtrAndDisown (Trigger obj) 127 { 128 long ptr = 0; 129 130 if (obj != null) 131 { 132 ptr = obj.swigCPtr; 133 obj.swigCMemOwn = false; 134 } 135 136 return ptr; 137 } 138 139 protected void finalize() { 140 delete(); 141 } 142 143 public synchronized void delete() { 144 if (swigCPtr != 0) { 145 if (swigCMemOwn) { 146 swigCMemOwn = false; 147 libsbmlJNI.delete_Trigger(swigCPtr); 148 } 149 swigCPtr = 0; 150 } 151 super.delete(); 152 } 153 154 155/** 156 * Creates a new {@link Trigger} using the given SBML <code>level</code> and <code>version</code> 157 * values. 158 * <p> 159 * @param level a long integer, the SBML Level to assign to this {@link Trigger} 160 * <p> 161 * @param version a long integer, the SBML Version to assign to this 162 * {@link Trigger} 163 * <p> 164 * @throws SBMLConstructorException 165 * Thrown if the given <code>level</code> and <code>version</code> combination, or this kind 166 * of SBML object, are either invalid or mismatched with respect to the 167 * parent {@link SBMLDocument} object. 168 */ public 169 Trigger(long level, long version) throws org.sbml.libsbml.SBMLConstructorException { 170 this(libsbmlJNI.new_Trigger__SWIG_0(level, version), true); 171 } 172 173 174/** 175 * Creates a new {@link Trigger} using the given {@link SBMLNamespaces} object 176 * <code>sbmlns</code>. 177 * <p> 178 * The {@link SBMLNamespaces} object encapsulates SBML Level/Version/namespaces 179 * information. It is used to communicate the SBML Level, Version, and 180 * (in Level 3) packages used in addition to SBML Level 3 Core. 181 * A common approach to using this class constructor is to create an 182 * {@link SBMLNamespaces} object somewhere in a program, once, then pass it to 183 * object constructors such as this one when needed. 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 * </ul> 335 * <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 * </ul> 356 * <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 * LibSBML attaches an identifying code to every 369 * kind of SBML object. These are known as <em>SBML type codes</em>. In 370 * other languages, the set of type codes is stored in an enumeration; in 371 * the Java language interface for libSBML, the type codes are defined as 372 * static integer constants in the interface class {@link 373 * libsbmlConstants}. The names of the type codes all begin with the 374 * characters <code>SBML_.</code> 375 * <p> 376 * @return the SBML type code for this object, or {@link libsbmlConstants#SBML_UNKNOWN SBML_UNKNOWN} (default). 377 * <p> 378 * @see #getElementName() 379 */ public 380 int getTypeCode() { 381 return libsbmlJNI.Trigger_getTypeCode(swigCPtr, this); 382 } 383 384 385/** 386 * Returns the XML element name of this object, which for {@link Trigger}, is 387 * always <code>'trigger'.</code> 388 * <p> 389 * @return the name of this element, i.e., <code>'trigger'.</code> 390 */ public 391 String getElementName() { 392 return libsbmlJNI.Trigger_getElementName(swigCPtr, this); 393 } 394 395 396/** 397 * Renames all the SIdRef attributes on this element, including any found in MathML 398 */ public 399 void renameSIdRefs(String oldid, String newid) { 400 libsbmlJNI.Trigger_renameSIdRefs(swigCPtr, this, oldid, newid); 401 } 402 403 404/** 405 * Renames all the UnitSIdRef attributes on this element 406 */ public 407 void renameUnitSIdRefs(String oldid, String newid) { 408 libsbmlJNI.Trigger_renameUnitSIdRefs(swigCPtr, this, oldid, newid); 409 } 410 411 412/** 413 * Replace all nodes with the name 'id' from the child 'math' object with the provided function. 414 * <p> 415 * @internal 416 */ public 417 void replaceSIDWithFunction(String id, ASTNode function) { 418 libsbmlJNI.Trigger_replaceSIDWithFunction(swigCPtr, this, id, ASTNode.getCPtr(function), function); 419 } 420 421 422/** 423 * Predicate returning <code>true</code> if 424 * all the required elements for this {@link Trigger} object 425 * have been set. 426 * <p> 427 * @note The required elements for a {@link Trigger} object are: 428 * <ul> 429 * <li> 'math' 430 * </ul> 431 * <p> 432 * @return a boolean value indicating whether all the required 433 * elements for this object have been defined. 434 */ public 435 boolean hasRequiredElements() { 436 return libsbmlJNI.Trigger_hasRequiredElements(swigCPtr, this); 437 } 438 439 440/** 441 * Predicate returning <code>true</code> if 442 * all the required attributes for this {@link Trigger} object 443 * have been set. 444 * <p> 445 * @note The required attributes for a {@link Trigger} object are: 446 * <ul> 447 * <li> 'persistent' (required in SBML Level 3) 448 * <li> 'initialValue' (required in SBML Level 3) 449 * </ul> 450 * <p> 451 * @return a boolean value indicating whether all the required 452 * attributes for this object have been defined. 453 */ public 454 boolean hasRequiredAttributes() { 455 return libsbmlJNI.Trigger_hasRequiredAttributes(swigCPtr, this); 456 } 457 458 459/** 460 * 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}. 461 * <p> 462 * @return integer value indicating success/failure of the 463 * function. The possible values 464 * returned by this function are: 465 * <ul> 466 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS } 467 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED } 468 * </ul> 469 */ public 470 int removeFromParentAndDelete() { 471 return libsbmlJNI.Trigger_removeFromParentAndDelete(swigCPtr, this); 472 } 473 474}