Trigger (LibSBML Java API)

java.lang.Object
- org.sbml.libsbml.SBase
- - org.sbml.libsbml.Trigger

```
public class Trigger
extends SBase
```
The trigger expression for an SBML event.
An Event object defines when the event can occur, the variables that are affected by the event, and how the variables are affected. The Trigger construct in SBML is used to define a mathematical expression that determines when an Event is triggered.
A Trigger object in SBML Level 2 and Level 3 contains one subelement named 'math' containing a MathML expression. The expression must evaluate to a value of type boolean. The exact moment at which the expression evaluates to true is the time point when the Event is triggered. In SBML Level 3, Trigger has additional attributes that must be assigned values they are discussed in a separate section below.
An event only triggers when its Trigger expression makes the transition in value from false to true. The event will also trigger at any subsequent time points when the trigger makes this transition in other words, an event can be triggered multiple times during a simulation if its trigger condition makes the transition from false to true more than once. In SBML Level 3, the behavior at the very start of simulation (i.e., at t = 0, where t stands for time) is determined in part by the boolean flag 'initialValue'. This and other additional features introduced in SBML Level 3 are discussed further below.

Version differences

SBML Level 3 Version 1 introduces two required attributes on the Trigger object: 'persistent' and 'initialValue'. The rest of this introduction describes these two attributes.

The 'persistent' attribute on Trigger

In the interval between when an Event object triggers (i.e., its Trigger object expression transitions in value from false to true) and when its assignments are to be executed, conditions in the model may change such that the trigger expression transitions back from true to false. Should the event's assignments still be made if this happens? Answering this question is the purpose of the 'persistent' attribute on Trigger.
If the boolean attribute 'persistent' has a value of true, then once the event is triggered, all of its assignments are always performed when the time of execution is reached. The name persistent is meant to evoke the idea that the trigger expression does not have to be re-checked after it triggers if 'persistent'=true. Conversely, if the attribute value is false, then the trigger expression is not assumed to persist: if the expression transitions in value back to false at any time between when the event triggered and when it is to be executed, the event is no longer considered to have triggered and its assignments are not executed. (If the trigger expression transitions once more to true after that point, then the event is triggered, but this then constitutes a whole new event trigger-and-execute sequence.)
The 'persistent' attribute can be especially useful when Event objects contain Delay objects, but it is relevant even in a model without delays if the model contains two or more events. As explained in the introduction to this section, the operation of all events in SBML (delayed or not) is conceptually divided into two phases, triggering and execution however, unless events have priorities associated with them, SBML does not mandate a particular ordering of event execution in the case of simultaneous events. Models with multiple events can lead to situations where the execution of one event affects another event's trigger expression value. If that other event has 'persistent'=false, and its trigger expression evaluates to false before it is to be executed, the event must not be executed after all.

The 'initialValue' attribute on Trigger

As mentioned above, an event triggers when the mathematical expression in its Trigger object transitions in value from false to true. An unanswered question concerns what happens at the start of a simulation: can event triggers make this transition at t = 0, where t stands for time?
In order to determine whether an event may trigger at t = 0, it is necessary to know what value the Trigger object's 'math' expression had immediately prior to t = 0. This starting value of the trigger expression is determined by the value of the boolean attribute 'initialValue'. A value of true means the trigger expression is taken to have the value true immediately prior to t = 0. In that case, the trigger cannot transition in value from false to true at the moment simulation begins (because it has the value true both before and after t = 0), and can only make the transition from false to true sometime after t = 0. (To do that, it would also first have to transition to false before it could make the transition from false back to true.) Conversely, if 'initialValue'=false, then the trigger expression is assumed to start with the value false, and therefore may trigger at t = 0 if the expression evaluates to true at that moment.

See Also:

Event, Delay, EventAssignment

Constructor Summary

Constructors
Constructor and Description
`Trigger(long level, long version)` Creates a new `Trigger` using the given SBML `level` and `version` values.
`Trigger(SBMLNamespaces sbmlns)` Creates a new `Trigger` using the given `SBMLNamespaces` object `sbmlns`.
`Trigger(Trigger orig)` Copy constructor creates a copy of this `Trigger`.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`Trigger`	`cloneObject()` Creates and returns a deep copy of this `Trigger` object.
`void`	`delete()` Explicitly deletes the underlying native object.
`java.lang.String`	`getElementName()` Returns the XML element name of this object, which for `Trigger`, is always `'trigger'.`
`boolean`	`getInitialValue()` (SBML Level 3 only) Get the value of the 'initialValue' attribute of this `Trigger`.
`ASTNode`	`getMath()` Get the mathematical formula for the trigger and return it as an AST.
`boolean`	`getPersistent()` (SBML Level 3 only) Get the value of the 'persistent' attribute of this `Trigger`.
`int`	`getTypeCode()` Returns the libSBML type code of this object instance.
`boolean`	`hasRequiredAttributes()` Predicate returning `true` if all the required attributes for this `Trigger` object have been set.
`boolean`	`hasRequiredElements()` Predicate returning `true` if all the required elements for this `Trigger` object have been set.
`boolean`	`isSetInitialValue()` (SBML Level 3 only) Predicate to test whether the 'initialValue' attribute for this trigger is set.
`boolean`	`isSetMath()` Predicate to test whether the math for this trigger is set.
`boolean`	`isSetPersistent()` (SBML Level 3 only) Predicate to test whether the 'persistent' attribute for this trigger is set.
`int`	`removeFromParentAndDelete()` Finds this `Trigger`'s `Event` parent and calls unsetTrigger() on it, indirectly deleting itself.
`void`	`renameSIdRefs(java.lang.String oldid, java.lang.String newid)` Replaces all uses of a given `SIdRef` type attribute value with another value.
`void`	`renameUnitSIdRefs(java.lang.String oldid, java.lang.String newid)` Replaces all uses of a given `UnitSIdRef` type attribute value with another value.
`int`	`setInitialValue(boolean initialValue)` (SBML Level 3 only) Sets the 'initialValue' attribute of this `Trigger` instance.
`int`	`setMath(ASTNode math)` Sets the trigger expression of this `Trigger` instance to a copy of the given `ASTNode`.
`int`	`setPersistent(boolean persistent)` (SBML Level 3 only) Sets the 'persistent' attribute of this `Trigger` instance.
`int`	`unsetInitialValue()` (SBML Level 3 only) Unsets the 'initialValue' attribute of this `Trigger` instance.
`int`	`unsetPersistent()` (SBML Level 3 only) Unsets the 'persistent' attribute of this `Trigger` instance.

Methods inherited from class org.sbml.libsbml.SBase
addCVTerm, addCVTerm, appendAnnotation, appendAnnotation, appendNotes, appendNotes, connectToChild, deleteDisabledPlugins, deleteDisabledPlugins, disablePackage, enablePackage, equals, getAncestorOfType, getAncestorOfType, getAnnotation, getAnnotationString, getColumn, getCVTerm, getCVTerms, getDisabledPlugin, getElementByMetaId, getElementBySId, getLevel, getLine, getListOfAllElements, getListOfAllElements, getListOfAllElementsFromPlugins, getListOfAllElementsFromPlugins, getMetaId, getModel, getModelHistory, getNamespaces, getNotes, getNotesString, getNumCVTerms, getNumDisabledPlugins, getNumPlugins, getPackageName, getPackageVersion, getParentSBMLObject, getPlugin, getPlugin, getPrefix, getResourceBiologicalQualifier, getResourceModelQualifier, getSBMLDocument, getSBOTerm, getSBOTermAsURL, getSBOTermID, getURI, getVersion, hashCode, hasValidLevelVersionNamespaceCombination, isPackageEnabled, isPackageURIEnabled, isPkgEnabled, isPkgURIEnabled, isSetAnnotation, isSetMetaId, isSetModelHistory, isSetNotes, isSetSBOTerm, isSetUserData, matchesRequiredSBMLNamespacesForAddition, matchesSBMLNamespaces, removeTopLevelAnnotationElement, removeTopLevelAnnotationElement, removeTopLevelAnnotationElement, renameMetaIdRefs, replaceTopLevelAnnotationElement, replaceTopLevelAnnotationElement, setAnnotation, setAnnotation, setMetaId, setModelHistory, setNamespaces, setNotes, setNotes, setNotes, setSBOTerm, setSBOTerm, toSBML, toXMLNode, unsetAnnotation, unsetCVTerms, unsetId, unsetMetaId, unsetModelHistory, unsetName, unsetNotes, unsetSBOTerm, unsetUserData

Methods inherited from class java.lang.Object
getClass, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - Trigger
```
public Trigger(long level,
               long version)
        throws SBMLConstructorException
```
    Creates a new Trigger using the given SBML level and version values.
    
    Parameters:
    
    level - a long integer, the SBML Level to assign to this Trigger
    
    version - a long integer, the SBML Version to assign to this Trigger
    
    Throws:
    
    SBMLConstructorException - Thrown if the given level and version combination are invalid or if this object is incompatible with the given level and version.
    
    "Note:"
    
    Attempting to add an object to an SBMLDocument having a different combination of SBML Level, Version and XML namespaces than the object itself will result in an error at the time a caller attempts to make the addition. A parent object must have compatible Level, Version and XML namespaces. (Strictly speaking, a parent may also have more XML namespaces than a child, but the reverse is not permitted.) The restriction is necessary to ensure that an SBML model has a consistent overall structure. This requires callers to manage their objects carefully, but the benefit is increased flexibility in how models can be created by permitting callers to create objects bottom-up if desired. In situations where objects are not yet attached to parents (e.g., SBMLDocument), knowledge of the intented SBML Level and Version help libSBML determine such things as whether it is valid to assign a particular value to an attribute.
  - Trigger
```
public Trigger(SBMLNamespaces sbmlns)
        throws SBMLConstructorException
```
    Creates a new Trigger using the given SBMLNamespaces object sbmlns.
    
    The SBMLNamespaces object encapsulates SBML Level/Version/namespaces information. It is used to communicate the SBML Level, Version, and (in Level 3) packages used in addition to SBML Level 3 Core. A common approach to using libSBML's SBMLNamespaces facilities is to create an SBMLNamespaces object somewhere in a program once, then hand that object as needed to object constructors that accept SBMLNamespaces as arguments.
    
    Parameters:
    
    sbmlns - an SBMLNamespaces object.
    
    Throws:
    
    SBMLConstructorException - Thrown if the given sbmlns is inconsistent or incompatible with this object.
    
    "Note:"
    
    Attempting to add an object to an SBMLDocument having a different combination of SBML Level, Version and XML namespaces than the object itself will result in an error at the time a caller attempts to make the addition. A parent object must have compatible Level, Version and XML namespaces. (Strictly speaking, a parent may also have more XML namespaces than a child, but the reverse is not permitted.) The restriction is necessary to ensure that an SBML model has a consistent overall structure. This requires callers to manage their objects carefully, but the benefit is increased flexibility in how models can be created by permitting callers to create objects bottom-up if desired. In situations where objects are not yet attached to parents (e.g., SBMLDocument), knowledge of the intented SBML Level and Version help libSBML determine such things as whether it is valid to assign a particular value to an attribute.
  - Trigger
```
public Trigger(Trigger orig)
        throws SBMLConstructorException
```
    Copy constructor creates a copy of this Trigger.
    
    Parameters:
    
    orig - the object to copy.
    
    Throws:
    
    SBMLConstructorException
- Method Detail
  - delete
```
public void delete()
```
    Explicitly deletes the underlying native object.
    In general, application software will not need to call this method directly. The Java language binding for libSBML is implemented as a language wrapper that provides a Java interface to libSBML's underlying C++/C code. Some of the Java methods return objects that are linked to objects created not by Java code, but by C++ code. The Java objects wrapped around them will be deleted when the garbage collector invokes the corresponding C++ finalize() methods for the objects. The finalize() methods in turn call the Trigger.delete() method on the libSBML object.
    This method is exposed in case calling programs want to ensure that the underlying object is freed immediately, and not at some arbitrary time determined by the Java garbage collector. In normal usage, callers do not need to invoke Trigger.delete() themselves.
    
    Overrides:
    
    delete in class SBase
  - cloneObject
```
public Trigger cloneObject()
```
    Creates and returns a deep copy of this Trigger object.
    
    Overrides:
    
    cloneObject in class SBase
    
    Returns:
    
    the (deep) copy of this Trigger object.
  - getMath
```
public ASTNode getMath()
```
    Get the mathematical formula for the trigger and return it as an AST.
    
    Returns:
    
    the math of this Trigger.
  - getInitialValue
```
public boolean getInitialValue()
```
    (SBML Level 3 only) Get the value of the 'initialValue' attribute of this Trigger.
    
    Returns:
    
    the boolean value stored as the 'initialValue' attribute value in this Trigger.
    
    "Note:"
    
    The attribute 'initialValue' is available in SBML Level 3 Version 1 Core, but is not present in lower Levels of SBML.
  - getPersistent
```
public boolean getPersistent()
```
    (SBML Level 3 only) Get the value of the 'persistent' attribute of this Trigger.
    
    Returns:
    
    the boolean value stored as the 'persistent' attribute value in this Trigger.
    
    "Note:"
    
    The attribute 'persistent' is available in SBML Level 3 Version 1 Core, but is not present in lower Levels of SBML.
  - isSetMath
```
public boolean isSetMath()
```
    Predicate to test whether the math for this trigger is set.
    
    Returns:
    
    true if the formula (meaning the 'math' subelement) of this Trigger is set, false otherwise.
  - isSetInitialValue
```
public boolean isSetInitialValue()
```
    (SBML Level 3 only) Predicate to test whether the 'initialValue' attribute for this trigger is set.
    
    Returns:
    
    true if the initialValue attribute of this Trigger is set, false otherwise.
    
    "Note:"
    
    The attribute 'initialValue' is available in SBML Level 3 Version 1 Core, but is not present in lower Levels of SBML.
  - isSetPersistent
```
public boolean isSetPersistent()
```
    (SBML Level 3 only) Predicate to test whether the 'persistent' attribute for this trigger is set.
    
    Returns:
    
    true if the persistent attribute of this Trigger is set, false otherwise.
    
    "Note:"
    
    The attribute 'persistent' is available in SBML Level 3 Version 1 Core, but is not present in lower Levels of SBML.
  - setMath
```
public int setMath(ASTNode math)
```
    Sets the trigger expression of this Trigger instance to a copy of the given ASTNode.
    Parameters:
    
    math - an ASTNode representing a formula tree.
    
    Returns:
    integer value indicating success/failure of the function. The possible values returned by this function are:
    
    LIBSBML_OPERATION_SUCCESS
    LIBSBML_INVALID_OBJECT
  - setInitialValue
```
public int setInitialValue(boolean initialValue)
```
    (SBML Level 3 only) Sets the 'initialValue' attribute of this Trigger instance.
    Parameters:
    
    initialValue - a boolean representing the initialValue to be set.
    
    Returns:
    integer value indicating success/failure of the function. The possible values returned by this function are:
    
    LIBSBML_OPERATION_SUCCESS
    LIBSBML_UNEXPECTED_ATTRIBUTE
    "Note:"
    
    The attribute 'initialValue' is available in SBML Level 3 Version 1 Core, but is not present in lower Levels of SBML.
  - setPersistent
```
public int setPersistent(boolean persistent)
```
    (SBML Level 3 only) Sets the 'persistent' attribute of this Trigger instance.
    Parameters:
    
    persistent - a boolean representing the persistent value to be set.
    
    Returns:
    integer value indicating success/failure of the function. The possible values returned by this function are:
    
    LIBSBML_OPERATION_SUCCESS
    LIBSBML_UNEXPECTED_ATTRIBUTE
    "Note:"
    
    The attribute 'persistent' is available in SBML Level 3 Version 1 Core, but is not present in lower Levels of SBML.
  - unsetInitialValue
```
public int unsetInitialValue()
```
    (SBML Level 3 only) Unsets the 'initialValue' attribute of this Trigger instance.
    Returns:
    integer value indicating success/failure of the function. The possible values returned by this function are:
    
    LIBSBML_OPERATION_SUCCESS
    LIBSBML_UNEXPECTED_ATTRIBUTE
    "Note:"
    
    The attribute 'initialValue' is available in SBML Level 3 Version 1 Core, but is not present in lower Levels of SBML.
  - unsetPersistent
```
public int unsetPersistent()
```
    (SBML Level 3 only) Unsets the 'persistent' attribute of this Trigger instance.
    Returns:
    integer value indicating success/failure of the function. The possible values returned by this function are:
    
    LIBSBML_OPERATION_SUCCESS
    LIBSBML_UNEXPECTED_ATTRIBUTE
    "Note:"
    
    The attribute 'persistent' is available in SBML Level 3 Version 1 Core, but is not present in lower Levels of SBML.
  - getTypeCode
```
public int getTypeCode()
```
    Returns the libSBML type code of this object instance.
    
    LibSBML attaches an identifying code to every kind of SBML object. These are integer constants known as SBML type codes. The names of all the codes begin with the characters SBML_. In the Java language interface for libSBML, the type codes are defined as static integer constants in the interface class libsbmlConstants. Note that different Level 3 package plug-ins may use overlapping type codes to identify the package to which a given object belongs, call the getPackageName() method on the object.
    
    Overrides:
    
    getTypeCode in class SBase
    
    Returns:
    
    the SBML type code for this object: SBML_TRIGGER (default).
    
    See Also:
    
    Trigger.getElementName(), SBase.getPackageName()
    
    "Warning:"
    
    The specific integer values of the possible type codes may be reused by different Level 3 package plug-ins. Thus, to identifiy the correct code, it is necessary to invoke both getTypeCode() and getPackageName().
  - getElementName
```
public java.lang.String getElementName()
```
    Returns the XML element name of this object, which for Trigger, is always 'trigger'.
    
    Overrides:
    
    getElementName in class SBase
    
    Returns:
    
    the name of this element, i.e., 'trigger'.
  - renameSIdRefs
```
public void renameSIdRefs(java.lang.String oldid,
                          java.lang.String newid)
```
    Replaces all uses of a given SIdRef type attribute value with another value.
    
    In SBML, object identifiers are of a data type called SId. In SBML Level 3, an explicit data type called SIdRef was introduced for attribute values that refer to SId values in previous Levels of SBML, this data type did not exist and attributes were simply described to as 'referring to an identifier', but the effective data type was the same as SIdRefin Level 3. These and other methods of libSBML refer to the type SIdRef for all Levels of SBML, even if the corresponding SBML specification did not explicitly name the data type.
    This method works by looking at all attributes and (if appropriate) mathematical formulas in MathML content, comparing the referenced identifiers to the value of oldid. If any matches are found, the matching values are replaced with newid. The method does not descend into child elements.
    
    Overrides:
    
    renameSIdRefs in class SBase
    
    Parameters:
    
    oldid - the old identifier
    
    newid - the new identifier
  - renameUnitSIdRefs
```
public void renameUnitSIdRefs(java.lang.String oldid,
                              java.lang.String newid)
```
    Replaces all uses of a given UnitSIdRef type attribute value with another value.
    
    In SBML, unit definitions have identifiers of type UnitSId. In SBML Level 3, an explicit data type called UnitSIdRef was introduced for attribute values that refer to UnitSId values in previous Levels of SBML, this data type did not exist and attributes were simply described to as 'referring to a unit identifier', but the effective data type was the same as UnitSIdRef in Level 3. These and other methods of libSBML refer to the type UnitSIdRef for all Levels of SBML, even if the corresponding SBML specification did not explicitly name the data type.
    This method works by looking at all unit identifier attribute values (including, if appropriate, inside mathematical formulas), comparing the referenced unit identifiers to the value of oldid. If any matches are found, the matching values are replaced with newid. The method does not descend into child elements.
    
    Overrides:
    
    renameUnitSIdRefs in class SBase
    
    Parameters:
    
    oldid - the old identifier
    
    newid - the new identifier
  - hasRequiredElements
```
public boolean hasRequiredElements()
```
    Predicate returning true if all the required elements for this Trigger object have been set.
    Overrides:
    
    hasRequiredElements in class SBase
    
    Returns:
    
    a boolean value indicating whether all the required elements for this object have been defined.
    
    "Note:"
    The required elements for a Trigger object are:
    
    'math'
  - hasRequiredAttributes
```
public boolean hasRequiredAttributes()
```
    Predicate returning true if all the required attributes for this Trigger object have been set.
    The required attributes for a Trigger object are:
    - 'persistent' (required in SBML Level 3)
    - 'initialValue' (required in SBML Level 3)
    Overrides:
    
    hasRequiredAttributes in class SBase
    
    Returns:
    
    a boolean value indicating whether all the required attributes for this object have been defined.
  - removeFromParentAndDelete
```
public int removeFromParentAndDelete()
```
    Finds this Trigger's Event parent and calls unsetTrigger() on it, indirectly deleting itself. Overridden from the SBase function since the parent is not a ListOf.
    Overrides:
    
    removeFromParentAndDelete in class SBase
    
    Returns:
    integer value indicating success/failure of the function. The possible values returned by this function are:
    
    LIBSBML_OPERATION_SUCCESS
    LIBSBML_OPERATION_FAILED

Class Trigger

Version differences

The 'persistent' attribute on `Trigger`

The 'initialValue' attribute on `Trigger`

Constructor Summary

Method Summary

Methods inherited from class org.sbml.libsbml.SBase

Methods inherited from class java.lang.Object

Constructor Detail

Trigger

Trigger

Trigger

Method Detail

delete

cloneObject

getMath

getInitialValue

getPersistent

isSetMath

isSetInitialValue

isSetPersistent

setMath

setInitialValue

setPersistent

unsetInitialValue

unsetPersistent

getTypeCode

getElementName

renameSIdRefs

renameUnitSIdRefs

hasRequiredElements

hasRequiredAttributes

removeFromParentAndDelete

Class Trigger

Version differences

The 'persistent' attribute on Trigger

The 'initialValue' attribute on Trigger

Constructor Summary

Method Summary

Methods inherited from class org.sbml.libsbml.SBase

Methods inherited from class java.lang.Object

Constructor Detail

Trigger

Trigger

Trigger

Method Detail

delete

cloneObject

getMath

getInitialValue

getPersistent

isSetMath

isSetInitialValue

isSetPersistent

setMath

setInitialValue

setPersistent

unsetInitialValue

unsetPersistent

getTypeCode

getElementName

renameSIdRefs

renameUnitSIdRefs

hasRequiredElements

hasRequiredAttributes

removeFromParentAndDelete

The 'persistent' attribute on `Trigger`

The 'initialValue' attribute on `Trigger`