/* ----------------------------------------------------------------------------
 * This file was automatically generated by SWIG (http://www.swig.org).
 * Version 3.0.10
 *
 * Do not make changes to this file unless you know what you are doing--modify
 * the SWIG interface file instead.
 * ----------------------------------------------------------------------------- */

package org.sbml.libsbml;

/** 
 *  A discontinuous SBML <em>event</em>.
 <p>
 * An SBML {@link 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.
 <p>
 * The operation of {@link Event} is divided into two phases (even when the event
 * is not delayed): one when the event is <em>triggered</em>, and the other when
 * the event is <em>executed</em>.  {@link Trigger} objects define the conditions for
 * triggering an event, {@link Delay} objects define when the event is actually
 * executed, {@link EventAssignment} objects define the effects of executing the
 * event, and (in SBML Level&nbsp;3) {@link Priority} objects influence the order
 * of {@link EventAssignment} performance in cases of simultaneous events.  Please
 * consult the descriptions of {@link Trigger}, {@link Delay}, {@link EventAssignment} and {@link Priority}
 * for more information.
 <p>
 * <h2>SBML Level/Version differences</h2>
 <p>
 * <h3>SBML Level 3</h3>
 <p>
 * SBML Level 3 introduces several changes to the structure and components
 * of Events compared to SBML Level&nbsp;2.  These changes fall into two
 * main categories: changes to what is optional or required, and additions
 * of new attributes and elements.
 * <ul>
 * <li> The attribute 'useValuesFromTriggerTime' on {@link Event} is mandatory (it
 * was optional in Level&nbsp;2);
 * <li> {@link Event}'s 'listOfEventAssignments' element (of class
 * {@link ListOfEventAssignments}) is optional (it was mandatory in Level&nbsp;2);
 * <li> {@link Event}'s 'priority' element (of class {@link Priority}) is new in
 * Level&nbsp;3; and
 * <li> The {@link Trigger} object gains new mandatory attributes (described as part
 * of the definition of {@link Trigger}).
 * </ul>
 <p>
 * The changes to the attributes of {@link Event} are described below; the changes
 * to {@link Trigger} and {@link Priority} are described in their respective sections.
 <p>
 * <h3>SBML Level 2</h3>
 <p>
 * In SBML Level&nbsp;2 versions before Version&nbsp;4, the semantics of
 * {@link Event} time delays were defined such that the expressions in the event's
 * assignments were always evaluated at the time the event was
 * <em>triggered</em>.  This definition made it difficult to define an event
 * whose assignment formulas were meant to be evaluated at the time the
 * event was <em>executed</em> (i.e., after the time period defined by the
 * value of the {@link Delay} element).  In SBML Level&nbsp;2 Version&nbsp;4 and in
 * Level&nbsp;3, the attribute 'useValuesFromTriggerTime' on {@link 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'=
 * <code>false</code>, it means that the formulas in the event's assignments are to be
 * computed <em>after</em> the delay, at the time the event is executed.
 <p>
 * The definition of {@link Event} in SBML Level&nbsp;2 Versions 1 and 2 includes
 * an additional attribute called 'timeUnits', which allowed the time units
 * of the {@link Delay} to be set explicitly.  Later Versions of SBML Level&nbsp;2
 * as well as SBML Level&nbsp;3 do not define this attribute.  LibSBML
 * supports this attribute for compatibility with previous versions of SBML
 * Level&nbsp;2; however, if a model in SBML Level&nbsp;3 or Level&nbsp;2
 * Versions&nbsp;3&ndash;4 format sets the attribute, the
 * consistency-checking method {@link SBMLDocument#checkConsistency()} will report
 * an error.
 <p>
 * The attribute 'useValuesFromTriggerTime' was introduced in SBML
 * Level&nbsp;2 Version&nbsp;4.  Models defined in prior Versions of SBML
 * Level&nbsp;2 cannot use this attribute, and
 * {@link SBMLDocument#checkConsistency()} will report an error if they do.
 <p>
 * <h2>Semantics of events in SBML Level 3 Version&nbsp;1</h2>
 <p>
 * 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&nbsp;1 Version&nbsp;1.
 * Any transition of a {@link Trigger} object's 'math' formula from the value 
 * <code>false</code> to <code>true</code> will cause the enclosing {@link Event} object to
 * <em>trigger</em>.  Such a transition is not possible at the very start
 * of a simulation (i.e., at time <em>t = 0</em>) unless the {@link Trigger}
 * object's 'initialValue' attribute has a value of <code>false</code>; this defines
 * the value of the trigger formula to be <code>false</code> immediately prior to the
 * start of simulation, thereby giving it the potential to change in value
 * from <code>false</code> to <code>true</code> when the formula is evaluated at <em>t =
 * 0</em>.  If 'initialValue'=<code>true</code>, then the trigger expression cannot
 * transition from <code>false</code> to <code>true</code> at <em>t = 0</em> but may do so at
 * some time <em>t > 0</em>.
 <p>
 * Consider an {@link Event} object definition <EM>E</EM> with delay <em>d</em> in
 * which the {@link Trigger} object's 'math' formula makes a transition in value
 * from <code>false</code> to <code>true</code> at times <em>t<sub>1</sub></em> and
 * <em>t<sub>2</sub></em>.  The {@link EventAssignment} within the {@link Event} object
 * will have effect at <em>t<sub>1</sub> + d</em> and
 * <em>t<sub>2</sub> + d</em> irrespective of the relative times of
 * <em>t<sub>1</sub></em> and <em>t<sub>2</sub></em>.  For example, events
 * can 'overlap' so that <em>t<sub>1</sub> < t<sub>2</sub> <
 * t<sub>1</sub> + d</em> still causes an event assignments to occur at
 * <em>t<sub>1</sub> + d</em> and <em>t<sub>2</sub> + d</em>.
 <p>
 * 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:
 * <ul>
 <p>
 * <li> A software package should retest all event triggers after executing
 * an event assignment in order to account for the possibility that the
 * assignment causes another event trigger to transition from <code>false</code> to
 * <code>true.</code>  This check should be made after each individual {@link Event} object's
 * execution, even when several events are to be executed simultaneously.
 <p>
 * <li> Any {@link Event} object whose {@link Trigger} 'persistent' attribute has the value
 * <code>false</code> 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 <code>false</code>, it must be removed
 * from the queue of events pending execution and treated as any other
 * event whose trigger expression evaluates to <code>false.</code>
 <p>
 * <li> Although the precise time at which events are executed is not
 * resolved beyond the given execution point in simulated time, it is
 * assumed that the order in which the events occur <em>is</em> resolved.
 * This order can be significant in determining the overall outcome of a
 * given simulation.  When an event <EM>X</EM> <em>triggers</em> another
 * event <EM>Y</EM> and event <EM>Y</EM> has zero delay, then event
 * <EM>Y</EM> is added to the existing set of simultaneous events that are
 * pending <em>execution</em>.  Events <EM>X</EM> and <EM>Y</EM> form a
 * cascade of events at the same point in simulation time.  An event such
 * as <EM>Y</EM> may have a special priority if it contains a {@link Priority}
 * subobject.
 <p>
 * <li> All events in a model are open to being in a cascade.  The position
 * of an event in the event queue does not affect whether it can be in the
 * cascade: event <EM>Y</EM> can be triggered whether it is before or after
 * <EM>X</EM> in the queue of events pending execution.  A cascade of
 * events can be potentially infinite (never terminate); when this occurs a
 * simulator should indicate this has occurred&mdash;it is incorrect for a
 * simulator to break a cascade arbitrarily and continue the simulation
 * without at least indicating that the infinite cascade occurred.
 <p>
 * <li> Simultaneous events having no defined priorities are executed in an
 * undefined order.  This does not mean that the behavior of the simulation
 * is completely undefined; merely that the <em>order</em> of execution of
 * these particular events is undefined.  A given simulator may use any
 * algorithm to choose an order as long as every event is executed exactly
 * once.
 <p>
 * <li> Events with defined priorities are executed in the order implied by
 * their {@link 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 {@link 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 {@link Priority} with respect to
 * any other pending {@link Event} without a defined {@link Priority}.
 <p>
 * <li> A model variable that is the target of one or more event
 * assignments can change more than once when simultaneous events are
 * processed at some time point <em>t</em>.  The model's behavior (output)
 * for such a variable is the value of the variable at the end of
 * processing all the simultaneous events at time <em>t</em>.
 <p>
 * </ul>
 <p>
 * @see Trigger
 * @see Priority
 * @see Delay
 * @see EventAssignment
 */

public class Event extends SBase {
   private long swigCPtr;

   protected Event(long cPtr, boolean cMemoryOwn)
   {
     super(libsbmlJNI.Event_SWIGUpcast(cPtr), cMemoryOwn);
     swigCPtr = cPtr;
   }

   protected static long getCPtr(Event obj)
   {
     return (obj == null) ? 0 : obj.swigCPtr;
   }

   protected static long getCPtrAndDisown (Event obj)
   {
     long ptr = 0;

     if (obj != null)
     {
       ptr             = obj.swigCPtr;
       obj.swigCMemOwn = false;
     }

     return ptr;
   }

  protected void finalize() {
    delete();
  }

  public synchronized void delete() {
    if (swigCPtr != 0) {
      if (swigCMemOwn) {
        swigCMemOwn = false;
        libsbmlJNI.delete_Event(swigCPtr);
      }
      swigCPtr = 0;
    }
    super.delete();
  }

  
/**
   * Creates a new {@link Event} using the given SBML <code>level</code> and <code>version</code>
   * values.
   <p>
   * @param level a long integer, the SBML Level to assign to this {@link Event}
   <p>
   * @param version a long integer, the SBML Version to assign to this
   * {@link Event}
   <p>
   * <p>
 * @throws SBMLConstructorException
 * Thrown if the given <code>level</code> and <code>version</code> combination are invalid
 * or if this object is incompatible with the given level and version.
   <p>