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&nbsp;2 and Level&nbsp;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&nbsp;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&nbsp;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&nbsp;3 are discussed further below.
037 <p>
038 * <h2>Version differences</h2>
039 <p>
040 * SBML Level&nbsp;3 Version&nbsp;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&nbsp;3) packages used in addition to SBML Level&nbsp;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&nbsp;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&nbsp;3
241   * Version&nbsp;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&nbsp;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&nbsp;3
256   * Version&nbsp;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&nbsp;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&nbsp;3
282   * Version&nbsp;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&nbsp;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&nbsp;3
297   * Version&nbsp;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&nbsp;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&nbsp;3
337   * Version&nbsp;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&nbsp;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&nbsp;3
358   * Version&nbsp;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 &ldquo;<code>SBML_</code>&rdquo;. 
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&nbsp;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&nbsp;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&nbsp;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&nbsp;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&nbsp;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&nbsp;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&nbsp;3)
499   * <li> 'initialValue' (required in SBML Level&nbsp;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}