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.
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, or after any other simultaneous
event may have been executed and changed the model state).
In SBML Level 2 Version 4 and in
Level 3, the attribute 'useValuesFromTriggerTime' on Event
was added
to allow a model to indicate the time at which the event's assignments
are to be calculated, whether at the moment the event is triggered (if
the value of the attribute is true
), or at the moment of execution
(if 'useValuesFromTriggerTime'=false
). If the event has a delay,
the 'useValuesFromTriggerTime' is likely to make a significant difference
in the values used in the assignment, but the possibility of simultaneous
events mean that even zero-delay events can have different results
depending on the value of this attribute.
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.
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 and had a default value of true
)
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
).
Trigger
object became
optional. An Event
with no Trigger
will simply not fire.
The changes to the attributes of Event
are described below the changes
to Trigger
and Priority
are described in their respective sections.
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
.
In SBML Level 3 Version 2, several restrictions were lifted that have the potential to affect the semantics of an Event:
Trigger
subobject of an Event
is optional. If missing,
an Event
is never triggered, unless an alternate triggering
scheme is introduced by an SBML Level 3 package.
Event
Trigger, Delay
, Priority
,
and EventAssignment
are all optional. If any of these elements lack
a 'math' subelement, and that information is not supplied in an SBML
Level 3 package, it is mathematically equivalent to the Trigger
,
Delay
, Priority
, or EventAssignment
not being present at all.
ListOfEventAssignments
may be empty, which is mathematically
equivalent to the Event
not having a ListOfEventAssignments
at all.
false
, and all other values are
interpreted as true.
If a Boolean value is used in a numeric
context, a true
is interpreted as a 1, and a false
is
interpreted as a 0. This means (for example) that a Trigger
value
that changes from 0.0 to anything else is equivalent to changing
from false
to true.
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 object. |
void |
connectToChild()   |
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 this Event
object have been set. |
void |
initDefaults()
Initializes the fields of this
Event object to 'typical' default
values. |
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()
|
int |
unsetUseValuesFromTriggerTime()
Unsets the value of the 'useValuesFromTriggerTime' attribute of this
Event . |
addCVTerm, addCVTerm, appendAnnotation, appendAnnotation, appendNotes, appendNotes, deleteDisabledPlugins, deleteDisabledPlugins, disablePackage, enablePackage, equals, getAncestorOfType, getAncestorOfType, getAnnotation, getAnnotationString, getColumn, getCVTerm, getCVTerms, getDisabledPlugin, getIdAttribute, getLevel, getLine, getListOfAllElements, getListOfAllElements, getListOfAllElementsFromPlugins, getListOfAllElementsFromPlugins, getMetaId, getModel, getModelHistory, getNamespaces, getNotes, getNotesString, getNumCVTerms, getNumDisabledPlugins, getNumPlugins, getObjectVersion, getPackageName, getPackageVersion, getParentSBMLObject, getPlugin, getPlugin, getPrefix, getResourceBiologicalQualifier, getResourceModelQualifier, getSBMLDocument, getSBOTerm, getSBOTermAsURL, getSBOTermID, getURI, getVersion, hashCode, hasValidLevelVersionNamespaceCombination, isPackageEnabled, isPackageURIEnabled, isPkgEnabled, isPkgURIEnabled, isSetAnnotation, isSetIdAttribute, isSetMetaId, isSetModelHistory, isSetNotes, isSetSBOTerm, isSetUserData, matchesRequiredSBMLNamespacesForAddition, matchesSBMLNamespaces, removeFromParentAndDelete, removeTopLevelAnnotationElement, removeTopLevelAnnotationElement, removeTopLevelAnnotationElement, renameMetaIdRefs, renameSIdRefs, renameUnitSIdRefs, replaceTopLevelAnnotationElement, replaceTopLevelAnnotationElement, setAnnotation, setAnnotation, setIdAttribute, setMetaId, setModelHistory, setNamespaces, setNotes, setNotes, setNotes, setSBOTerm, setSBOTerm, toSBML, toXMLNode, unsetAnnotation, unsetCVTerms, unsetIdAttribute, unsetMetaId, unsetModelHistory, unsetNotes, unsetSBOTerm, unsetUserData
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 are invalid
or if this object is incompatible with the given level and version.
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.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 sbmlns
is inconsistent or incompatible
with this object.
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.public Event(Event orig) throws SBMLConstructorException
Event
.
orig
- the object to copy.SBMLConstructorException
public 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 Event cloneObject()
Event
object.
cloneObject
 in class SBase
Event
object.public void initDefaults()
Event
object to 'typical' default
values.
The SBML Event
component has slightly different aspects and
default attribute values in different SBML Levels and Versions.
This method sets the values to certain common defaults, based
mostly on what they are in SBML Level 2. Specifically:
true
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 the object to find.
id
.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 the object to find.
metaid
.public java.lang.String getId()
Event
.
getId
 in class SBase
Event
.
SBase.getIdAttribute()
,
SBase.setIdAttribute(String sid)
,
SBase.isSetIdAttribute()
,
SBase.unsetIdAttribute()
The identifier given by an object's 'id' attribute value
is used to identify the object within the SBML model definition.
Other objects can refer to the component using this identifier. The
data type of 'id' is always SId
or a type derived
from that, such as UnitSId
, depending on the object in
question. All data types are defined as follows:
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. This applies to all uses of SId
,
SIdRef
, and derived types.
In SBML Level 3 Version 2, the 'id' and 'name' attributes were
moved to SBase
directly, instead of being defined individually for many
(but not all) objects. Libsbml has for a long time provided functions
defined on SBase
itself to get, set, check, and unset those attributes, which
would fail or otherwise return empty strings if executed on any object
for which those attributes were not defined. Now that all SBase
objects
define those attributes, those functions now succeed for any object with
the appropriate level and version.
The exception to this rule is that for InitialAssignment
, EventAssignment
,
AssignmentRule
, and RateRule
objects, the getId() function and the isSetId()
functions (though not the setId() or unsetId() functions) would instead
reference the value of the 'variable' attribute (for the rules and event
assignments) or the 'symbol' attribute (for initial assignments).
The AlgebraicRule
fell into this category as well, though because it
contained neither a 'variable' nor a 'symbol' attribute, getId() would
always return an empty string, and isSetId() would always return false.
For this reason, four new functions are now provided
(getIdAttribute(), setIdAttribute(String),
isSetIdAttribute(), and unsetIdAttribute()) that will always
act on the actual 'id' attribute, regardless of the object's type. The
new functions should be used instead of the old ones unless the old behavior
is somehow necessary.
Regardless of the level and version of the SBML, these functions allow client applications to use more generalized code in some situations (for instance, when manipulating objects that are all known to have identifiers). If the object in question does not posess an 'id' attribute according to the SBML specification for the Level and Version in use, libSBML will not allow the identifier to be set, nor will it read or write 'id' attributes for those objects.
public java.lang.String getName()
Event
.
In SBML Level 3 Version 2, the 'id' and 'name' attributes were
moved to SBase
directly, instead of being defined individually for many
(but not all) objects. Libsbml has for a long time provided functions
defined on SBase
itself to get, set, and unset those attributes, which
would fail or otherwise return empty strings if executed on any object
for which those attributes were not defined. Now that all SBase
objects
define those attributes, those functions now succeed for any object with
the appropriate level and version.
The 'name' attribute is
optional and is not intended to be used for cross-referencing purposes
within a model. Its purpose instead is to provide a human-readable
label for the component. The data type of 'name' is the type
string
defined in XML Schema. SBML imposes no
restrictions as to the content of 'name' attributes beyond those
restrictions defined by the string
type in XML Schema.
The recommended practice for handling 'name' is as follows. If a software tool has the capability for displaying the content of 'name' attributes, it should display this content to the user as a component's label instead of the component's 'id'. If the user interface does not have this capability (e.g., because it cannot display or use special characters in symbol names), or if the 'name' attribute is missing on a given component, then the user interface should display the value of the 'id' attribute instead. (Script language interpreters are especially likely to display 'id' instead of 'name'.)
As a consequence of the above, authors of systems that automatically generate the values of 'id' attributes should be aware some systems may display the 'id''s to the user. Authors therefore may wish to take some care to have their software create 'id' values that are: (a) reasonably easy for humans to type and read and (b) likely to be meaningful, for example by making the 'id' attribute be an abbreviated form of the name attribute value.
An additional point worth mentioning is although there are restrictions on the uniqueness of 'id' values, there are no restrictions on the uniqueness of 'name' values in a model. This allows software applications leeway in assigning component identifiers.
Regardless of the level and version of the SBML, these functions allow client applications to use more generalized code in some situations (for instance, when manipulating objects that are all known to have names). If the object in question does not posess a 'name' attribute according to the SBML specification for the Level and Version in use, libSBML will not allow the name to be set, nor will it read or write 'name' attributes for those objects.
getName
 in class SBase
SBase.getIdAttribute()
,
Event.isSetName()
,
Event.setName(String sid)
,
Event.unsetName()
public Trigger getTrigger()
Event
.
public Delay getDelay()
Event
, if there is one.
Event
if one is defined, or null
if none
is defined.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 boolean getUseValuesFromTriggerTime()
Event
.
The optional Delay
on Event
and the fact that multiple events may be
simultaneously executed 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, or after any other simultaneous
event may have been executed and changed the model state).
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 isSetId()
isSetId
 in class SBase
true
if the 'id' attribute of this SBML object is
set, false
otherwise.
SBase.getIdAttribute()
,
SBase.setIdAttribute(String sid)
,
SBase.unsetIdAttribute()
,
SBase.isSetIdAttribute()
The identifier given by an object's 'id' attribute value
is used to identify the object within the SBML model definition.
Other objects can refer to the component using this identifier. The
data type of 'id' is always SId
or a type derived
from that, such as UnitSId
, depending on the object in
question. All data types are defined as follows:
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. This applies to all uses of SId
,
SIdRef
, and derived types.
In SBML Level 3 Version 2, the 'id' and 'name' attributes were
moved to SBase
directly, instead of being defined individually for many
(but not all) objects. Libsbml has for a long time provided functions
defined on SBase
itself to get, set, check, and unset those attributes, which
would fail or otherwise return empty strings if executed on any object
for which those attributes were not defined. Now that all SBase
objects
define those attributes, those functions now succeed for any object with
the appropriate level and version.
The exception to this rule is that for InitialAssignment
, EventAssignment
,
AssignmentRule
, and RateRule
objects, the getId() function and the isSetId()
functions (though not the setId() or unsetId() functions) would instead
reference the value of the 'variable' attribute (for the rules and event
assignments) or the 'symbol' attribute (for initial assignments).
The AlgebraicRule
fell into this category as well, though because it
contained neither a 'variable' nor a 'symbol' attribute, getId() would
always return an empty string, and isSetId() would always return false.
For this reason, four new functions are now provided
(getIdAttribute(), setIdAttribute(String),
isSetIdAttribute(), and unsetIdAttribute()) that will always
act on the actual 'id' attribute, regardless of the object's type. The
new functions should be used instead of the old ones unless the old behavior
is somehow necessary.
Regardless of the level and version of the SBML, these functions allow client applications to use more generalized code in some situations (for instance, when manipulating objects that are all known to have identifiers). If the object in question does not posess an 'id' attribute according to the SBML specification for the Level and Version in use, libSBML will not allow the identifier to be set, nor will it read or write 'id' attributes for those objects.
public boolean isSetName()
true
if this
Event
's 'name' attribute is set.
In SBML Level 3 Version 2, the 'id' and 'name' attributes were
moved to SBase
directly, instead of being defined individually for many
(but not all) objects. Libsbml has for a long time provided functions
defined on SBase
itself to get, set, and unset those attributes, which
would fail or otherwise return empty strings if executed on any object
for which those attributes were not defined. Now that all SBase
objects
define those attributes, those functions now succeed for any object with
the appropriate level and version.
The 'name' attribute is
optional and is not intended to be used for cross-referencing purposes
within a model. Its purpose instead is to provide a human-readable
label for the component. The data type of 'name' is the type
string
defined in XML Schema. SBML imposes no
restrictions as to the content of 'name' attributes beyond those
restrictions defined by the string
type in XML Schema.
The recommended practice for handling 'name' is as follows. If a software tool has the capability for displaying the content of 'name' attributes, it should display this content to the user as a component's label instead of the component's 'id'. If the user interface does not have this capability (e.g., because it cannot display or use special characters in symbol names), or if the 'name' attribute is missing on a given component, then the user interface should display the value of the 'id' attribute instead. (Script language interpreters are especially likely to display 'id' instead of 'name'.)
As a consequence of the above, authors of systems that automatically generate the values of 'id' attributes should be aware some systems may display the 'id''s to the user. Authors therefore may wish to take some care to have their software create 'id' values that are: (a) reasonably easy for humans to type and read and (b) likely to be meaningful, for example by making the 'id' attribute be an abbreviated form of the name attribute value.
An additional point worth mentioning is although there are restrictions on the uniqueness of 'id' values, there are no restrictions on the uniqueness of 'name' values in a model. This allows software applications leeway in assigning component identifiers.
Regardless of the level and version of the SBML, these functions allow client applications to use more generalized code in some situations (for instance, when manipulating objects that are all known to have names). If the object in question does not posess a 'name' attribute according to the SBML specification for the Level and Version in use, libSBML will not allow the name to be set, nor will it read or write 'name' attributes for those objects.
isSetName
 in class SBase
true
if the 'name' attribute of this SBML object is
set, false
otherwise.
Event.getName()
,
Event.setName(String sid)
,
Event.unsetName()
public boolean isSetTrigger()
Event
is set.
true
if the trigger of this Event
is set, false
otherwise.public boolean isSetDelay()
Event
is set.
true
if the delay of this Event
is set, false
otherwise.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 isSetUseValuesFromTriggerTime()
Event
is set.
true
if the 'useValuesFromTriggerTime' attribute of this Event
is
set, false
otherwise.
true
, whereas in Level 3, this optional is mandatory and
has no default value.public int setId(java.lang.String sid)
Event
.
The string sid
is copied.
The identifier given by an object's 'id' attribute value
is used to identify the object within the SBML model definition.
Other objects can refer to the component using this identifier. The
data type of 'id' is always SId
or a type derived
from that, such as UnitSId
, depending on the object in
question. All data types are defined as follows:
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. This applies to all uses of SId
,
SIdRef
, and derived types.
In SBML Level 3 Version 2, the 'id' and 'name' attributes were
moved to SBase
directly, instead of being defined individually for many
(but not all) objects. Libsbml has for a long time provided functions
defined on SBase
itself to get, set, check, and unset those attributes, which
would fail or otherwise return empty strings if executed on any object
for which those attributes were not defined. Now that all SBase
objects
define those attributes, those functions now succeed for any object with
the appropriate level and version.
The exception to this rule is that for InitialAssignment
, EventAssignment
,
AssignmentRule
, and RateRule
objects, the getId() function and the isSetId()
functions (though not the setId() or unsetId() functions) would instead
reference the value of the 'variable' attribute (for the rules and event
assignments) or the 'symbol' attribute (for initial assignments).
The AlgebraicRule
fell into this category as well, though because it
contained neither a 'variable' nor a 'symbol' attribute, getId() would
always return an empty string, and isSetId() would always return false.
For this reason, four new functions are now provided
(getIdAttribute(), setIdAttribute(String),
isSetIdAttribute(), and unsetIdAttribute()) that will always
act on the actual 'id' attribute, regardless of the object's type. The
new functions should be used instead of the old ones unless the old behavior
is somehow necessary.
Regardless of the level and version of the SBML, these functions allow client applications to use more generalized code in some situations (for instance, when manipulating objects that are all known to have identifiers). If the object in question does not posess an 'id' attribute according to the SBML specification for the Level and Version in use, libSBML will not allow the identifier to be set, nor will it read or write 'id' attributes for those objects.
setId
 in class SBase
sid
- the string to use as the identifier of this object.
SBase.getIdAttribute()
,
SBase.setIdAttribute(String sid)
,
SBase.isSetIdAttribute()
,
SBase.unsetIdAttribute()
public int setName(java.lang.String name)
public int setTrigger(Trigger trigger)
trigger
- the Trigger
object instance to use.
public int setDelay(Delay delay)
delay
- the Delay
object instance to use.
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 setUseValuesFromTriggerTime(boolean value)
Event
to a value
.
The optional Delay
on Event
and the fact that multiple events may be
simultaneously executed 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, or after any other simultaneous
event may have been executed and changed the model state).
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 unsetId()
Event
.
The identifier given by an object's 'id' attribute value
is used to identify the object within the SBML model definition.
Other objects can refer to the component using this identifier. The
data type of 'id' is always SId
or a type derived
from that, such as UnitSId
, depending on the object in
question. All data types are defined as follows:
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. This applies to all uses of SId
,
SIdRef
, and derived types.
In SBML Level 3 Version 2, the 'id' and 'name' attributes were
moved to SBase
directly, instead of being defined individually for many
(but not all) objects. Libsbml has for a long time provided functions
defined on SBase
itself to get, set, check, and unset those attributes, which
would fail or otherwise return empty strings if executed on any object
for which those attributes were not defined. Now that all SBase
objects
define those attributes, those functions now succeed for any object with
the appropriate level and version.
The exception to this rule is that for InitialAssignment
, EventAssignment
,
AssignmentRule
, and RateRule
objects, the getId() function and the isSetId()
functions (though not the setId() or unsetId() functions) would instead
reference the value of the 'variable' attribute (for the rules and event
assignments) or the 'symbol' attribute (for initial assignments).
The AlgebraicRule
fell into this category as well, though because it
contained neither a 'variable' nor a 'symbol' attribute, getId() would
always return an empty string, and isSetId() would always return false.
For this reason, four new functions are now provided
(getIdAttribute(), setIdAttribute(String),
isSetIdAttribute(), and unsetIdAttribute()) that will always
act on the actual 'id' attribute, regardless of the object's type. The
new functions should be used instead of the old ones unless the old behavior
is somehow necessary.
Regardless of the level and version of the SBML, these functions allow client applications to use more generalized code in some situations (for instance, when manipulating objects that are all known to have identifiers). If the object in question does not posess an 'id' attribute according to the SBML specification for the Level and Version in use, libSBML will not allow the identifier to be set, nor will it read or write 'id' attributes for those objects.
unsetId
 in class SBase
SBase.getIdAttribute()
,
SBase.setIdAttribute(String sid)
,
SBase.isSetIdAttribute()
,
SBase.unsetIdAttribute()
public int unsetName()
Event
.
In SBML Level 3 Version 2, the 'id' and 'name' attributes were
moved to SBase
directly, instead of being defined individually for many
(but not all) objects. Libsbml has for a long time provided functions
defined on SBase
itself to get, set, and unset those attributes, which
would fail or otherwise return empty strings if executed on any object
for which those attributes were not defined. Now that all SBase
objects
define those attributes, those functions now succeed for any object with
the appropriate level and version.
The 'name' attribute is
optional and is not intended to be used for cross-referencing purposes
within a model. Its purpose instead is to provide a human-readable
label for the component. The data type of 'name' is the type
string
defined in XML Schema. SBML imposes no
restrictions as to the content of 'name' attributes beyond those
restrictions defined by the string
type in XML Schema.
The recommended practice for handling 'name' is as follows. If a software tool has the capability for displaying the content of 'name' attributes, it should display this content to the user as a component's label instead of the component's 'id'. If the user interface does not have this capability (e.g., because it cannot display or use special characters in symbol names), or if the 'name' attribute is missing on a given component, then the user interface should display the value of the 'id' attribute instead. (Script language interpreters are especially likely to display 'id' instead of 'name'.)
As a consequence of the above, authors of systems that automatically generate the values of 'id' attributes should be aware some systems may display the 'id''s to the user. Authors therefore may wish to take some care to have their software create 'id' values that are: (a) reasonably easy for humans to type and read and (b) likely to be meaningful, for example by making the 'id' attribute be an abbreviated form of the name attribute value.
An additional point worth mentioning is although there are restrictions on the uniqueness of 'id' values, there are no restrictions on the uniqueness of 'name' values in a model. This allows software applications leeway in assigning component identifiers.
Regardless of the level and version of the SBML, these functions allow client applications to use more generalized code in some situations (for instance, when manipulating objects that are all known to have names). If the object in question does not posess a 'name' attribute according to the SBML specification for the Level and Version in use, libSBML will not allow the name to be set, nor will it read or write 'name' attributes for those objects.
unsetName
 in class SBase
Event.getName()
,
Event.setName(String sid)
,
Event.isSetName()
public int unsetUseValuesFromTriggerTime()
Event
.
The optional Delay
on Event
and the fact that multiple events may be
simultaneously executed 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, or after any other simultaneous
event may have been executed and changed the model state).
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 int unsetDelay()
public int unsetPriority()
public int unsetTrigger()
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 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 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 Trigger createTrigger()
Trigger
object instance.public Delay createDelay()
Delay
object instance.public Priority createPriority()
public ListOfEventAssignments getListOfEventAssignments()
Event
.
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 long getNumEventAssignments()
EventAssignment
objects attached to this
Event
.
Event
.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 void connectToChild()
connectToChild
 in class SBase
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 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.
getTypeCode
 in class SBase
SBML_EVENT
(default).
Event.getElementName()
,
SBase.getPackageName()
public java.lang.String getElementName()
Event
, is
always 'event'.
getElementName
 in class SBase
'event'.
public boolean hasRequiredAttributes()
true
if all the required attributes for this
Event
object have been set.
The required attributes for an Event
object are:
hasRequiredAttributes
 in class SBase
true
if the required attributes have been set, false
otherwise.public boolean hasRequiredElements()
true
if all the required elements for this Event
object have been set.
hasRequiredElements
 in class SBase
Event
object are: