public class Event extends SBase
An SBML Event
object defines when the event can occur, the variables
that are affected by it, how the variables are affected, and the event's
relationship to other events. The effect of the event can optionally be
delayed after the occurrence of the condition which invokes it.
The operation of Event
is divided into two phases (even when the event
is not delayed): one when the event is triggered, and the other when
the event is executed. Trigger
objects define the conditions for
triggering an event, Delay
objects define when the event is actually
executed, EventAssignment
objects define the effects of executing the
event, and (in SBML Level 3) Priority
objects influence the order
of EventAssignment
performance in cases of simultaneous events. Please
consult the descriptions of Trigger
, Delay
, EventAssignment
and Priority
for more information.
SBML Level 3 introduces several changes to the structure and components of Events compared to SBML Level 2. These changes fall into two main categories: changes to what is optional or required, and additions of new attributes and elements.
Event
is mandatory (it
was optional in Level 2)
Event
's 'listOfEventAssignments' element (of class
ListOfEventAssignments
) is optional (it was mandatory in Level 2)
Event
's 'priority' element (of class Priority
) is new in
Level 3 and
Trigger
object gains new mandatory attributes (described as part
of the definition of Trigger
).
The changes to the attributes of Event
are described below the changes
to Trigger
and Priority
are described in their respective sections.
In SBML Level 2 versions before Version 4, the semantics of
Event
time delays were defined such that the expressions in the event's
assignments were always evaluated at the time the event was
triggered. This definition made it difficult to define an event
whose assignment formulas were meant to be evaluated at the time the
event was executed (i.e., after the time period defined by the
value of the Delay
element). In SBML Level 2 Version 4 and in
Level 3, the attribute 'useValuesFromTriggerTime' on Event
allows a
model to indicate the time at which the event's assignments are intended
the values of the assignment formulas are computed at the moment the
event is triggered, not after the delay. If 'useValuesFromTriggerTime'=
false
, it means that the formulas in the event's assignments are to be
computed after the delay, at the time the event is executed.
The definition of Event
in SBML Level 2 Versions 1 and 2 includes
an additional attribute called 'timeUnits', which allowed the time units
of the Delay
to be set explicitly. Later Versions of SBML Level 2
as well as SBML Level 3 do not define this attribute. LibSBML
supports this attribute for compatibility with previous versions of SBML
Level 2 however, if a model in SBML Level 3 or Level 2
Versions 3&ndash4 format sets the attribute, the
consistency-checking method SBMLDocument.checkConsistency()
will report
an error.
The attribute 'useValuesFromTriggerTime' was introduced in SBML
Level 2 Version 4. Models defined in prior Versions of SBML
Level 2 cannot use this attribute, and
SBMLDocument.checkConsistency()
will report an error if they do.
The detailed semantics of events are described in the specification
documents for each SBML Level/Version. Here we include the description
from the SBML Level 1 Version 1.
Any transition of a Trigger
object's 'math' formula from the value
false
to true
will cause the enclosing Event
object to
trigger. Such a transition is not possible at the very start
of a simulation (i.e., at time t = 0) unless the Trigger
object's 'initialValue' attribute has a value of false
this defines
the value of the trigger formula to be false
immediately prior to the
start of simulation, thereby giving it the potential to change in value
from false
to true
when the formula is evaluated at t =
0. If 'initialValue'=true
, then the trigger expression cannot
transition from false
to true
at t = 0 but may do so at
some time t > 0.
Consider an Event
object definition E with delay d in
which the Trigger
object's 'math' formula makes a transition in value
from false
to true
at times t1 and
t2. The EventAssignment
within the Event
object
will have effect at t1 + d and
t2 + d irrespective of the relative times of
t1 and t2. For example, events
can 'overlap' so that t1 < t2 <
t1 + d still causes an event assignments to occur at
t1 + d and t2 + d.
It is entirely possible for two events to be executed simultaneously, and it is possible for events to trigger other events (i.e., an event assignment can cause an event to trigger). This leads to several points:
false
to
true.
This check should be made after each individual Event
object's
execution, even when several events are to be executed simultaneously.
Event
object whose Trigger
'persistent' attribute has the value
false
must have its trigger expression reevaluated continuously
between when the event is triggered and when it is executed. If
its trigger expression ever evaluates to false
, it must be removed
from the queue of events pending execution and treated as any other
event whose trigger expression evaluates to false.
Priority
subobject.
Priority
'math' formula values, with events having higher
priorities being executed ahead of events with lower priorities, and
events with identical priorities being executed in a random order with
respect to one another (as determined at run-time by some random
algorithm equivalent to coin-flipping). Newly-triggered events that are
to be executed immediately (i.e., if they define no delays) should be
inserted into the queue of events pending execution according to their
priorities: events with higher priority values value must be inserted
ahead of events with lower priority values and after any pending events
with even higher priorities, and inserted randomly among pending events
with the same priority values. Events without Priority
objects must be
inserted into the queue in some fashion, but the algorithm used to place
it in the queue is undefined. Similarly, there is no restriction on the
order of a newly-inserted event with a defined Priority
with respect to
any other pending Event
without a defined Priority
.
Trigger
,
Priority
,
Delay
,
EventAssignment
Constructor and Description |
---|
Event(Event orig)
Copy constructor creates a copy of this
Event . |
Event(long level,
long version)
|
Event(SBMLNamespaces sbmlns)
|
Modifier and Type | Method and Description |
---|---|
int |
addEventAssignment(EventAssignment ea)
Appends a copy of the given
EventAssignment to this Event . |
Event |
cloneObject()
Creates and returns a deep copy of this
Event . |
Delay |
createDelay()
|
EventAssignment |
createEventAssignment()
Creates a new, empty
EventAssignment , adds it to this Event 's list of
event assignments and returns the EventAssignment . |
Priority |
createPriority()
|
Trigger |
createTrigger()
|
void |
delete()
Explicitly deletes the underlying native object.
|
Delay |
getDelay()
Get the assignment delay portion of this
Event , if there is one. |
SBase |
getElementByMetaId(java.lang.String metaid)
Returns the first child element it can find with the given
metaid , or
null if no such object is found. |
SBase |
getElementBySId(java.lang.String id)
Returns the first child element found that has the given
id in the
model-wide SId namespace, or null if no such object is found. |
java.lang.String |
getElementName()
Returns the XML element name of this object, which for
Event , is
always 'event'. |
EventAssignment |
getEventAssignment(long n)
Return a specific
EventAssignment object of this Event . |
EventAssignment |
getEventAssignment(java.lang.String variable)
Return the event assignment indicated by the given
variable . |
java.lang.String |
getId()
Returns the value of the 'id' attribute of this
Event . |
ListOfEventAssignments |
getListOfEventAssignments()
Returns the list of event assignments for this
Event . |
java.lang.String |
getName()
Returns the value of the 'name' attribute of this
Event . |
long |
getNumEventAssignments()
Returns the number of
EventAssignment objects attached to this
Event . |
Priority |
getPriority()
(SBML Level 3 only) Get the event priority portion of this
Event . |
java.lang.String |
getTimeUnits()
Get the value of the 'timeUnits' attribute of this
Event , if it has one. |
Trigger |
getTrigger()
Get the event trigger portion of this
Event . |
int |
getTypeCode()
Returns the libSBML type code of this object instance.
|
boolean |
getUseValuesFromTriggerTime()
Get the value of the 'useValuesFromTriggerTime' attribute of this
Event . |
boolean |
hasRequiredAttributes()
Predicate returning
true if all the required attributes for this
Event object have been set. |
boolean |
hasRequiredElements()
Predicate returning
true if
all the required elements for the given Event_t structure
have been set. |
boolean |
isSetDelay()
Predicate for testing whether the delay for this
Event is set. |
boolean |
isSetId()
Predicate returning
true if this
Event 's 'id' attribute is set. |
boolean |
isSetName()
Predicate returning
true if this
Event 's 'name' attribute is set. |
boolean |
isSetPriority()
(SBML Level 3 only) Predicate for testing whether the priority
for this
Event is set. |
boolean |
isSetTimeUnits()
Predicate for testing whether the 'timeUnits' attribute of this
Event
is set. |
boolean |
isSetTrigger()
Predicate for testing whether the trigger for this
Event is set. |
boolean |
isSetUseValuesFromTriggerTime()
Predicate for testing whether the 'useValuesFromTriggerTime' attribute of this
Event
is set. |
EventAssignment |
removeEventAssignment(long n)
Removes the nth
EventAssignment object from this Event object and
returns a pointer to it. |
EventAssignment |
removeEventAssignment(java.lang.String variable)
Removes the
EventAssignment object with the given 'variable' attribute
from this Event object and returns a pointer to it. |
int |
setDelay(Delay delay)
|
int |
setId(java.lang.String sid)
Sets the value of the 'id' attribute of this
Event . |
int |
setName(java.lang.String name)
Sets the value of the 'name' attribute of this
Event . |
int |
setPriority(Priority priority)
|
int |
setTimeUnits(java.lang.String sid)
Sets the 'timeUnits' attribute of this
Event to a copy of sid . |
int |
setTrigger(Trigger trigger)
|
int |
setUseValuesFromTriggerTime(boolean value)
Sets the 'useValuesFromTriggerTime' attribute of this
Event to a value . |
int |
unsetDelay()
|
int |
unsetId()
Unsets the value of the 'id' attribute of this
Event . |
int |
unsetName()
Unsets the value of the 'name' attribute of this
Event . |
int |
unsetPriority()
|
int |
unsetTimeUnits()
Unsets the 'timeUnits' attribute of this
Event . |
int |
unsetTrigger()
|
addCVTerm, addCVTerm, appendAnnotation, appendAnnotation, appendNotes, appendNotes, disablePackage, enablePackage, equals, getAncestorOfType, getAncestorOfType, getAnnotation, getAnnotationString, getColumn, getCVTerm, getCVTerms, getLevel, getLine, getListOfAllElements, getListOfAllElements, getListOfAllElementsFromPlugins, getListOfAllElementsFromPlugins, getMetaId, getModel, getModelHistory, getNamespaces, getNotes, getNotesString, getNumCVTerms, getNumPlugins, getPackageName, getPackageVersion, getParentSBMLObject, getPlugin, getPlugin, getPrefix, getResourceBiologicalQualifier, getResourceModelQualifier, getSBMLDocument, getSBOTerm, getSBOTermAsURL, getSBOTermID, getURI, getVersion, hashCode, hasValidLevelVersionNamespaceCombination, isPackageEnabled, isPackageURIEnabled, isSetAnnotation, isSetMetaId, isSetModelHistory, isSetNotes, isSetSBOTerm, matchesRequiredSBMLNamespacesForAddition, matchesSBMLNamespaces, removeFromParentAndDelete, removeTopLevelAnnotationElement, removeTopLevelAnnotationElement, removeTopLevelAnnotationElement, renameMetaIdRefs, renameSIdRefs, renameUnitSIdRefs, replaceTopLevelAnnotationElement, replaceTopLevelAnnotationElement, setAnnotation, setAnnotation, setMetaId, setModelHistory, setNamespaces, setNotes, setNotes, setNotes, setSBOTerm, setSBOTerm, toSBML, toXMLNode, unsetAnnotation, unsetCVTerms, unsetMetaId, unsetModelHistory, unsetNotes, unsetSBOTerm
public Event(Event orig) throws SBMLConstructorException
Event
.
orig
- the object to copy.
SBMLConstructorException
- Thrown if the argument orig
is null.
public Event(long level, long version) throws SBMLConstructorException
level
- a long integer, the SBML Level to assign to this Event
version
- a long integer, the SBML Version to assign to this
Event
SBMLConstructorException
- Thrown if the given level
and version
combination, or this kind
of SBML object, are either invalid or mismatched with respect to the
parent SBMLDocument
object.
Event
object to an SBMLDocument
(e.g., using
Model.addEvent(Event e)
), the SBML Level, SBML Version and
XML namespace of the document override the values used when creating
the Event
object via this constructor. This is necessary to ensure that
an SBML document is a consistent structure. Nevertheless, the ability to
supply the values at the time of creation of an Event
is an important aid
to producing valid SBML. Knowledge of the intented SBML Level and Version
determine whether it is valid to assign a particular value to an
attribute, or whether it is valid to add an object to an existing
SBMLDocument
.public Event(SBMLNamespaces sbmlns) throws SBMLConstructorException
Event
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.
sbmlns
- an SBMLNamespaces
object.
SBMLConstructorException
- Thrown if the given level
and version
combination, or this kind
of SBML object, are either invalid or mismatched with respect to the
parent SBMLDocument
object.
Event
object to an SBMLDocument
(e.g., using
Model.addEvent(Event e)
), the SBML Level, SBML Version and
XML namespace of the document override the values used when creating
the Event
object via this constructor. This is necessary to ensure that
an SBML document is a consistent structure. Nevertheless, the ability to
supply the values at the time of creation of an Event
is an important aid
to producing valid SBML. Knowledge of the intented SBML Level and Version
determine whether it is valid to assign a particular value to an
attribute, or whether it is valid to add an object to an existing
SBMLDocument
.public int addEventAssignment(EventAssignment ea)
EventAssignment
to this Event
.
ea
- the EventAssignment
object to add.
LIBSBML_OPERATION_SUCCESS
LIBSBML_LEVEL_MISMATCH
LIBSBML_VERSION_MISMATCH
LIBSBML_DUPLICATE_OBJECT_ID
LIBSBML_OPERATION_FAILED
Event.createEventAssignment()
create
)
for alternatives that do not lead to these issues.
public Event cloneObject()
Event
.
cloneObject
 in class SBase
Event
.public Delay createDelay()
Delay
object instancepublic EventAssignment createEventAssignment()
EventAssignment
, adds it to this Event
's list of
event assignments and returns the EventAssignment
.
EventAssignment
object instance
Event.addEventAssignment(EventAssignment ea)
public Priority createPriority()
Priority
, adds it to this
Event
and returns the Priority
.
Priority
object instance
public Trigger createTrigger()
Trigger
object instancepublic void delete()
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 Event.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 Event.delete()
themselves.
public Delay getDelay()
Event
, if there is one.
Event
if one is defined, or null
if none
is defined.public SBase getElementByMetaId(java.lang.String metaid)
metaid
, or
null
if no such object is found.
getElementByMetaId
 in class SBase
metaid
- string representing the metaid of objects to find
metaid
.public SBase getElementBySId(java.lang.String id)
id
in the
model-wide SId namespace, or null
if no such object is found.
getElementBySId
 in class SBase
id
- string representing the id of objects to find
id
.public java.lang.String getElementName()
Event
, is
always 'event'.
getElementName
 in class SBase
'event'.
public EventAssignment getEventAssignment(long n)
EventAssignment
object of this Event
.
n
- an integer, the index of the EventAssignment
object to return
n
th EventAssignment
of this Event
.public EventAssignment getEventAssignment(java.lang.String variable)
variable
.
variable
- a string, the identifier of the variable whose
EventAssignment
is being sought.
EventAssignment
for the given variable
, or null
if
no such EventAssignment
exits.public java.lang.String getId()
Event
.
public ListOfEventAssignments getListOfEventAssignments()
Event
.
Event
.public java.lang.String getName()
Event
.
public long getNumEventAssignments()
EventAssignment
objects attached to this
Event
.
Event
.public Priority getPriority()
Event
.
public java.lang.String getTimeUnits()
Event
, if it has one.
Event
in SBML Level 2
Versions 1 and 2 included the additional attribute called
'timeUnits', but it was removed in SBML Level 2 Version 3.
LibSBML supports this attribute for compatibility with previous versions
of SBML Level 2, but its use is discouraged since models in
Level 2 Versions 3 and 4 cannot contain it. If a
Version 3 or 4 model sets the attribute, the
consistency-checking method SBMLDocument.checkConsistency()
will report
an error.public Trigger getTrigger()
Event
.
public int getTypeCode()
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 &ldquoSBML_
&rdquo.
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.
getTypeCode
 in class SBase
SBML_EVENT
(default).
Event.getElementName()
,
SBase.getPackageName()
public boolean getUseValuesFromTriggerTime()
Event
.
The optional Delay
on Event
means there are two times to consider when
computing the results of an event: the time at which the event is
triggered, and the time at which assignments are
executed. It is also possible to distinguish between the
time at which the EventAssignment
's expression is calculated, and the
time at which the assignment is made: the expression could be
evaluated at the same time the assignments are performed, i.e., when
the event is executed, but it could also be defined to be
evaluated at the time the event is triggered.
In SBML Level 2 versions prior to Version 4, the semantics
of Event
time delays were defined such that the expressions in the
event's assignments were always evaluated at the time the event was
triggered. This definition made it difficult to define an
event whose assignment formulas were meant to be evaluated at the time
the event was executed (i.e., after the time period defined
by the value of the Delay
element). In SBML Level 2
Version 4, the attribute 'useValuesFromTriggerTime' on Event
allows a model to indicate the time at which the event's assignments
are intended to be evaluated. In SBML Level 2, the attribute has
a default value of true
, which corresponds to the interpretation of
event assignments prior to Version 4: the values of the
assignment formulas are computed at the moment the event is triggered,
not after the delay. If 'useValuesFromTriggerTime'=false
, it means
that the formulas in the event's assignments are to be computed after
the delay, at the time the event is executed. In SBML Level 3,
the attribute is mandatory, not optional, and all events must specify
a value for it.
SBMLDocument.checkConsistency()
will report
an error.public boolean hasRequiredAttributes()
true
if all the required attributes for this
Event
object have been set.
hasRequiredAttributes
 in class SBase
Event
object are:
public boolean hasRequiredElements()
true
if
all the required elements for the given Event_t structure
have been set.
hasRequiredElements
 in class SBase
Event
object are:
public boolean isSetDelay()
Event
is set.
true
if the delay of this Event
is set, false
otherwise.public boolean isSetId()
true
if this
Event
's 'id' attribute is set.
public boolean isSetName()
true
if this
Event
's 'name' attribute is set.
public boolean isSetPriority()
Event
is set.
true
if the priority of this Event
is set, false
otherwise.
public boolean isSetTimeUnits()
Event
is set.
true
if the 'timeUnits' attribute of this Event
is
set, false
otherwise.
Event
in SBML Level 2
Versions 1 and 2 included the additional attribute called
'timeUnits', but it was removed in SBML Level 2 Version 3.
LibSBML supports this attribute for compatibility with previous versions
of SBML Level 2, but its use is discouraged since models in
Level 2 Versions 3 and 4 cannot contain it. If a
Version 3 or 4 model sets the attribute, the
consistency-checking method SBMLDocument.checkConsistency()
will report
an error.public boolean isSetTrigger()
Event
is set.
true
if the trigger of this Event
is set, false
otherwise.public boolean isSetUseValuesFromTriggerTime()
Event
is set.
true
if the 'useValuesFromTriggerTime' attribute of this Event
is
set, false
otherwise.
true
, whereas in Level 3 Version 1, this optional is mandatory and
has no default value.public EventAssignment removeEventAssignment(long n)
EventAssignment
object from this Event
object and
returns a pointer to it.
The caller owns the returned object and is responsible for deleting it.
n
- the index of the EventAssignment
object to remove
EventAssignment
object removed. As mentioned above,
the caller owns the returned item. null
is returned if the given index
is out of range.public EventAssignment removeEventAssignment(java.lang.String variable)
EventAssignment
object with the given 'variable' attribute
from this Event
object and returns a pointer to it.
The caller owns the returned object and is responsible for deleting it.
If none of the EventAssignment
objects in this Event
object have the
'variable' attribute variable
, then null
is returned.
variable
- the 'variable' attribute of the EventAssignment
object
to remove
EventAssignment
object removed. As mentioned above, the
caller owns the returned object. null
is returned if no EventAssignment
object with the 'variable' attribute exists in this Event
object.public int setDelay(Delay delay)
delay
- the Delay
object instance to use
public int setId(java.lang.String sid)
Event
.
The string sid
is copied.
SBML has strict requirements for the syntax of identifiers, that is, the
values of the 'id' attribute present on most types of SBML objects.
The following is a summary of the definition of the SBML identifier type
SId
, which defines the permitted syntax of identifiers. We
express the syntax using an extended form of BNF notation:
letter .= 'a'..'z','A'..'Z' digit .= '0'..'9' idChar .= letter | digit | '_' SId .= ( letter | '_' ) idChar*The characters
(
and )
are used for grouping, the
character *
'zero or more times', and the character
|
indicates logical 'or'. The equality of SBML identifiers is
determined by an exact character sequence match i.e., comparisons must be
performed in a case-sensitive manner. In addition, there are a few
conditions for the uniqueness of identifiers in an SBML model. Please
consult the SBML specifications for the exact details of the uniqueness
requirements.
public int setName(java.lang.String name)
Event
.
The string in name
is copied.
public int setPriority(Priority priority)
Event
to a copy of the given Priority
object instance.
priority
- the Priority
object instance to use
public int setTimeUnits(java.lang.String sid)
Event
to a copy of sid
.
sid
- the identifier of the time units to use.
Event
in SBML Level 2
Versions 1 and 2 included the additional attribute called
'timeUnits', but it was removed in SBML Level 2 Version 3.
LibSBML supports this attribute for compatibility with previous versions
of SBML Level 2, but its use is discouraged since models in
Level 2 Versions 3 and 4 cannot contain it. If a
Version 3 or 4 model sets the attribute, the
consistency-checking method SBMLDocument.checkConsistency()
will report
an error.public int setTrigger(Trigger trigger)
trigger
- the Trigger
object instance to use.
public int setUseValuesFromTriggerTime(boolean value)
Event
to a value
.
The optional Delay
on Event
means there are two times to consider when
computing the results of an event: the time at which the event is
triggered, and the time at which assignments are
executed. It is also possible to distinguish between the
time at which the EventAssignment
's expression is calculated, and the
time at which the assignment is made: the expression could be
evaluated at the same time the assignments are performed, i.e., when
the event is executed, but it could also be defined to be
evaluated at the time the event is triggered.
In SBML Level 2 versions prior to Version 4, the semantics
of Event
time delays were defined such that the expressions in the
event's assignments were always evaluated at the time the event was
triggered. This definition made it difficult to define an
event whose assignment formulas were meant to be evaluated at the time
the event was executed (i.e., after the time period defined
by the value of the Delay
element). In SBML Level 2
Version 4, the attribute 'useValuesFromTriggerTime' on Event
allows a model to indicate the time at which the event's assignments
are intended to be evaluated. In SBML Level 2, the attribute has
a default value of true
, which corresponds to the interpretation of
event assignments prior to Version 4: the values of the
assignment formulas are computed at the moment the event is triggered,
not after the delay. If 'useValuesFromTriggerTime'=false
, it means
that the formulas in the event's assignments are to be computed after
the delay, at the time the event is executed. In SBML Level 3,
the attribute is mandatory, not optional, and all events must specify
a value for it.
value
- the value of useValuesFromTriggerTime to use.
SBMLDocument.checkConsistency()
will report
an error.public int unsetDelay()
public int unsetId()
Event
.
public int unsetName()
Event
.
public int unsetPriority()
public int unsetTimeUnits()
Event
.
Event
in SBML Level 2
Versions 1 and 2 included the additional attribute called
'timeUnits', but it was removed in SBML Level 2 Version 3.
LibSBML supports this attribute for compatibility with previous versions
of SBML Level 2, but its use is discouraged since models in
Level 2 Versions 3 and 4 cannot contain it. If a
Version 3 or 4 model sets the attribute, the
consistency-checking method SBMLDocument.checkConsistency()
will report
an error.public int unsetTrigger()