001/* ----------------------------------------------------------------------------
002 * This file was automatically generated by SWIG (http://www.swig.org).
003 * Version 2.0.11
004 *
005 * Do not make changes to this file unless you know what you are doing--modify
006 * the SWIG interface file instead.
007 * ----------------------------------------------------------------------------- */
008
009package org.sbml.libsbml;
010
011/** 
012 * 
013 * Implementation of SBML Level 3's Priority construct
014 * for {@link Event}.
015 * <p>
016 * The {@link Priority} object class (which was introduced in SBML Level&nbsp;3
017 * Version&nbsp;1), like {@link Delay}, is derived from {@link SBase} and contains a MathML
018 * formula stored in the element 'math'.  This formula is used to compute a
019 * dimensionless numerical value that influences the order in which a
020 * simulator is to perform the assignments of two or more events that
021 * happen to be executed simultaneously.  The formula may evaluate to any
022 * <code>double</code> value (and thus may be a positive or negative number, or
023 * zero), with positive numbers taken to signifying a higher priority than
024 * zero or negative numbers.  If no {@link Priority} object is present on a given
025 * {@link Event} object, no priority is defined for that event.
026 * <p>
027 * <h2>The interpretation of priorities on events in a model</h2>
028 * <p>
029 * For the purposes of SBML, <em>simultaneous event execution</em> is
030 * defined as the situation in which multiple events have identical
031 * times of execution.  The time of execution is calculated as the
032 * sum of the time at which a given event's {@link Trigger} is <em>triggered</em>
033 * plus its {@link Delay} duration, if any.  Here, <em>identical times</em> means
034 * <em>mathematically equal</em> instants in time.  (In practice,
035 * simulation software adhering to this specification may have to
036 * rely on numerical equality instead of strict mathematical
037 * equality; robust models will ensure that this difference will not
038 * cause significant discrepancies from expected behavior.)
039 * <p>
040 * If no {@link Priority} subobjects are defined for two or more {@link Event} objects,
041 * then those events are still executed simultaneously but their order of
042 * execution is <em>undefined by the SBML Level&nbsp;3 Version&nbsp;1
043 * specification</em>.  A software implementation may choose to execute
044 * such simultaneous events in any order, as long as each event is executed
045 * only once and the requirements of checking the 'persistent' attribute
046 * (and acting accordingly) are satisfied.
047 * <p>
048 * If {@link Priority} subobjects are defined for two or more
049 * simultaneously-triggered events, the order in which those particular
050 * events must be executed is dictated by their {@link Priority} objects,
051 * as follows.  If the values calculated using the two {@link Priority}
052 * objects' 'math' expressions differ, then the event having
053 * the higher priority value must be executed before the event with
054 * the lower value.  If, instead, the two priority values are
055 * mathematically equal, then the two events must be triggered in a
056 * <em>random</em> order.  It is important to note that a <em>random
057 *   order is not the same as an undefined order</em>: given multiple
058 * runs of the same model with identical conditions, an undefined
059 * ordering would permit a system to execute the events in (for
060 * example) the same order every time (according to whatever scheme
061 * may have been implemented by the system), whereas the explicit
062 * requirement for random ordering means that the order of execution
063 * in different simulation runs depends on random chance.  In other
064 * words, given two events <em>A</em> and <em>B</em>, a randomly-determined
065 * order must lead to an equal chance of executing <em>A</em> first or
066 * <em>B</em> first, every time those two events are executed
067 * simultaneously.
068 * <p>
069 * A model may contain a mixture of events, some of which have
070 * {@link Priority} subobjects and some do not.  Should a combination of
071 * simultaneous events arise in which some events have priorities
072 * defined and others do not, the set of events with defined
073 * priorities must trigger in the order determined by their {@link Priority}
074 * objects, and the set of events without {@link Priority} objects must be
075 * executed in an <em>undefined</em> order with respect to each other
076 * and with respect to the events with {@link Priority} subobjects.  (Note
077 * that <em>undefined order</em> does not necessarily mean random
078 * order, although a random ordering would be a valid implementation
079 * of this requirement.)
080 * <p>
081 * The following example may help further clarify these points.
082 * Suppose a model contains four events that should be executed
083 * simultaneously, with two of the events having {@link Priority} objects
084 * with the same value and the other two events having {@link Priority}
085 * objects with the same, but different, value.  The two events with
086 * the higher priorities must be executed first, in a random order
087 * with respect to each other, and the remaining two events must be
088 * executed after them, again in a random order, for a total of four
089 * possible and equally-likely event executions: A-B-C-D, A-B-D-C,
090 * B-A-C-D, and B-A-D-C.  If, instead, the model contains four events
091 * all having the same {@link Priority} values, there are 4! or 24
092 * possible orderings, each of which must be equally likely to be
093 * chosen.  Finally, if none of the four events has a {@link Priority}
094 * subobject defined, or even if exactly one of the four events has a
095 * defined {@link Priority}, there are again 24 possible orderings, but the
096 * likelihood of choosing any particular ordering is undefined; the
097 * simulator can choose between events as it wishes.  (The SBML
098 * specification only defines the effects of priorities on {@link Event}
099 * objects with respect to <em>other</em> {@link Event} objects with
100 * priorities.  Putting a priority on a <em>single</em> {@link Event} object
101 * in a model does not cause it to fall within that scope.)
102 * <p>
103 * <h2>Evaluation of {@link Priority} expressions</h2>
104 * <p>
105 * An event's {@link Priority} object 'math' expression must be
106 * evaluated at the time the {@link Event} is to be <em>executed</em>.  During
107 * a simulation, all simultaneous events have their {@link Priority} values
108 * calculated, and the event with the highest priority is selected for
109 * next execution.  Note that it is possible for the execution of one
110 * {@link Event} object to cause the {@link Priority} value of another
111 * simultaneously-executing {@link Event} object to change (as well as to
112 * trigger other events, as already noted).  Thus, after executing
113 * one event, and checking whether any other events in the model have
114 * been triggered, all remaining simultaneous events that
115 * <em>either</em> (i) have {@link Trigger} objects with attributes
116 * 'persistent'=<code>false</code> <em>or</em> (ii) have {@link Trigger}
117 * expressions that did not transition from <code>true</code> to
118 * <code>false</code>, must have their {@link Priority} expression reevaluated.
119 * The highest-priority remaining event must then be selected for 
120 * execution next.
121 * <p>
122 * <h2>Units of {@link Priority} object's mathematical expressions</h2>
123 * <p>
124 * The unit associated with the value of a {@link Priority} object's
125 * 'math' expression should be <code>dimensionless.</code>  This is
126 * because the priority expression only serves to provide a relative
127 * ordering between different events, and only has meaning with
128 * respect to other {@link Priority} object expressions.  The value of
129 * {@link Priority} objects is not comparable to any other kind of object in
130 * an SBML model.
131 * <p>
132 * @note The {@link Priority} construct exists only in SBML Level&nbsp;3; it cannot
133 * be used in SBML Level&nbsp;2 or Level&nbsp;1 models.
134 * <p>
135 * @see Event
136 * @see Delay
137 * @see EventAssignment
138 */
139
140public class Priority extends SBase {
141   private long swigCPtr;
142
143   protected Priority(long cPtr, boolean cMemoryOwn)
144   {
145     super(libsbmlJNI.Priority_SWIGUpcast(cPtr), cMemoryOwn);
146     swigCPtr = cPtr;
147   }
148
149   protected static long getCPtr(Priority obj)
150   {
151     return (obj == null) ? 0 : obj.swigCPtr;
152   }
153
154   protected static long getCPtrAndDisown (Priority obj)
155   {
156     long ptr = 0;
157
158     if (obj != null)
159     {
160       ptr             = obj.swigCPtr;
161       obj.swigCMemOwn = false;
162     }
163
164     return ptr;
165   }
166
167  protected void finalize() {
168    delete();
169  }
170
171  public synchronized void delete() {
172    if (swigCPtr != 0) {
173      if (swigCMemOwn) {
174        swigCMemOwn = false;
175        libsbmlJNI.delete_Priority(swigCPtr);
176      }
177      swigCPtr = 0;
178    }
179    super.delete();
180  }
181
182  
183/**
184   * Creates a new {@link Priority} object using the given SBML <code>level</code> and 
185   * <code>version</code> values.
186   * <p>
187   * @param level a long integer, the SBML Level to assign to this {@link Priority}
188   * <p>
189   * @param version a long integer, the SBML Version to assign to this
190   * {@link Priority}
191   * <p>
192   * @throws SBMLConstructorException 
193   * Thrown if the given <code>level</code> and <code>version</code> combination, or this kind
194   * of SBML object, are either invalid or mismatched with respect to the
195   * parent {@link SBMLDocument} object.
196   * <p>
197   * @note Upon the addition of a {@link Priority} object to an {@link Event} (e.g., using
198   * {@link Event#setPriority(Priority d)}), the SBML Level, SBML Version
199   * and XML namespace of the document <em>override</em> the values used when
200   * creating the {@link Priority} object via this constructor.  This is necessary to
201   * ensure that an SBML document is a consistent structure.  Nevertheless,
202   * the ability to supply the values at the time of creation of a {@link Priority} is
203   * an important aid to producing valid SBML.  Knowledge of the intented
204   * SBML Level and Version determine whether it is valid to assign a
205   * particular value to an attribute, or whether it is valid to add a
206   * particular {@link Priority} object to an existing {@link Event}.<br><br>
207   * <p>
208   * @note The {@link Priority} construct exists only in SBML Level&nbsp;3; it
209   * cannot be used in SBML Level&nbsp;2 or Level&nbsp;1 models.
210   */ public
211 Priority(long level, long version) throws org.sbml.libsbml.SBMLConstructorException {
212    this(libsbmlJNI.new_Priority__SWIG_0(level, version), true);
213  }
214
215  
216/**
217   * Creates a new {@link Priority} object using the given {@link SBMLNamespaces} object
218   * <code>sbmlns</code>.
219   * <p>
220   * The {@link SBMLNamespaces} object encapsulates SBML Level/Version/namespaces
221   * information.  It is used to communicate the SBML Level, Version, and
222   * (in Level&nbsp;3) packages used in addition to SBML Level&nbsp;3 Core.
223   * A common approach to using this class constructor is to create an
224   * {@link SBMLNamespaces} object somewhere in a program, once, then pass it to
225   * object constructors such as this one when needed.
226   * <p>
227   * @param sbmlns an {@link SBMLNamespaces} object.
228   * <p>
229   * @throws SBMLConstructorException  
230   * Thrown if the given <code>level</code> and <code>version</code> combination, or this kind
231   * of SBML object, are either invalid or mismatched with respect to the
232   * parent {@link SBMLDocument} object.
233   * <p>
234   * @note Upon the addition of a {@link Priority} object to an {@link Event} (e.g., using
235   * {@link Event#setPriority(Priority d)}), the SBML XML namespace of
236   * the document <em>overrides</em> the value used when creating the {@link Priority}
237   * object via this constructor.  This is necessary to ensure that an SBML
238   * document is a consistent structure.  Nevertheless, the ability to
239   * supply the values at the time of creation of a {@link Priority} is an important
240   * aid to producing valid SBML.  Knowledge of the intented SBML Level and
241   * Version determine whether it is valid to assign a particular value to
242   * an attribute, or whether it is valid to add a particular {@link Priority} object
243   * to an existing {@link Event}.<br><br>
244   * <p>
245   * @note The {@link Priority} construct exists only in SBML Level&nbsp;3; it
246   * cannot be used in SBML Level&nbsp;2 or Level&nbsp;1 models.
247   */ public
248 Priority(SBMLNamespaces sbmlns) throws org.sbml.libsbml.SBMLConstructorException {
249    this(libsbmlJNI.new_Priority__SWIG_1(SBMLNamespaces.getCPtr(sbmlns), sbmlns), true);
250  }
251
252  
253/**
254   * Copy constructor; creates a copy of this {@link Priority}.
255   * <p>
256   * @param orig the object to copy.
257   * <p>
258   * @throws SBMLConstructorException 
259   * Thrown if the argument <code>orig</code> is <code>null.</code>
260   */ public
261 Priority(Priority orig) throws org.sbml.libsbml.SBMLConstructorException {
262    this(libsbmlJNI.new_Priority__SWIG_2(Priority.getCPtr(orig), orig), true);
263  }
264
265  
266/**
267   * Creates and returns a deep copy of this {@link Priority}.
268   * <p>
269   * @return a (deep) copy of this {@link Priority}.
270   */ public
271 Priority cloneObject() {
272    long cPtr = libsbmlJNI.Priority_cloneObject(swigCPtr, this);
273    return (cPtr == 0) ? null : new Priority(cPtr, true);
274  }
275
276  
277/**
278   * Get the mathematical formula for the priority and return it
279   * as an AST.
280   * <p>
281   * @return the math of this {@link Priority}.
282   */ public
283 ASTNode getMath() {
284    long cPtr = libsbmlJNI.Priority_getMath(swigCPtr, this);
285    return (cPtr == 0) ? null : new ASTNode(cPtr, false);
286  }
287
288  
289/**
290   * Predicate to test whether the formula for this delay is set.
291   * <p>
292   * @return <code>true</code> if the formula (meaning the <code>math</code> subelement) of
293   * this {@link Priority} is set, <code>false</code> otherwise.
294   */ public
295 boolean isSetMath() {
296    return libsbmlJNI.Priority_isSetMath(swigCPtr, this);
297  }
298
299  
300/**
301   * Sets the math expression of this {@link Priority} instance to a copy of the given
302   * {@link ASTNode}.
303   * <p>
304   * @param math an {@link ASTNode} representing a formula tree.
305   * <p>
306   * @return integer value indicating success/failure of the
307   * function.   The possible values
308   * returned by this function are:
309   * <ul>
310   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS }
311   * <li> {@link  libsbmlConstants#LIBSBML_INVALID_OBJECT LIBSBML_INVALID_OBJECT }
312   * </ul>
313   */ public
314 int setMath(ASTNode math) {
315    return libsbmlJNI.Priority_setMath(swigCPtr, this, ASTNode.getCPtr(math), math);
316  }
317
318  
319/**
320   * Returns the libSBML type code of this object instance.
321   * <p>
322   * LibSBML attaches an identifying code to every
323   * kind of SBML object.  These are known as <em>SBML type codes</em>.  In
324   * other languages, the set of type codes is stored in an enumeration; in
325   * the Java language interface for libSBML, the type codes are defined as
326   * static integer constants in the interface class {@link
327   * libsbmlConstants}.  The names of the type codes all begin with the
328   * characters <code>SBML_.</code> 
329   * <p>
330   * @return the SBML type code for this object, or {@link  libsbmlConstants#SBML_UNKNOWN SBML_UNKNOWN} (default).
331   * <p>
332   * @see #getElementName()
333   */ public
334 int getTypeCode() {
335    return libsbmlJNI.Priority_getTypeCode(swigCPtr, this);
336  }
337
338  
339/**
340   * Returns the XML element name of this object, which for {@link Priority}, is
341   * always <code>'priority'.</code>
342   * <p>
343   * @return the name of this element, i.e., <code>'priority'.</code>
344   * <p>
345   * @see #getTypeCode()
346   */ public
347 String getElementName() {
348    return libsbmlJNI.Priority_getElementName(swigCPtr, this);
349  }
350
351  
352/**
353   * Predicate returning <code>true</code> if
354   * all the required elements for this {@link Priority} object
355   * have been set.
356   * <p>
357   * @note The required elements for a {@link Priority} object are:
358   * <ul>
359   * <li> 'math'
360   * </ul>
361   * <p>
362   * @return a boolean value indicating whether all the required
363   * elements for this object have been defined.
364   */ public
365 boolean hasRequiredElements() {
366    return libsbmlJNI.Priority_hasRequiredElements(swigCPtr, this);
367  }
368
369  
370/**
371   * Finds this {@link Priority}'s {@link Event} parent and calls unsetPriority() on it, indirectly deleting itself.  Overridden from the {@link SBase} function since the parent is not a {@link ListOf}.
372   * <p>
373   * @return integer value indicating success/failure of the
374   * function.   The possible values
375   * returned by this function are:
376   * <ul>
377   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS }
378   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED }
379   * </ul>
380   */ public
381 int removeFromParentAndDelete() {
382    return libsbmlJNI.Priority_removeFromParentAndDelete(swigCPtr, this);
383  }
384
385  
386/**
387   * Renames all the SIdRef attributes on this element, including any found in MathML.
388   */ public
389 void renameSIdRefs(String oldid, String newid) {
390    libsbmlJNI.Priority_renameSIdRefs(swigCPtr, this, oldid, newid);
391  }
392
393  
394/**
395   * Renames all the UnitSIdRef attributes on this element.
396   */ public
397 void renameUnitSIdRefs(String oldid, String newid) {
398    libsbmlJNI.Priority_renameUnitSIdRefs(swigCPtr, this, oldid, newid);
399  }
400
401  
402/**
403   * Replace all nodes with the name 'id' from the child 'math' object with the provided function. 
404   * <p>
405   * @internal
406   */ public
407 void replaceSIDWithFunction(String id, ASTNode function) {
408    libsbmlJNI.Priority_replaceSIDWithFunction(swigCPtr, this, id, ASTNode.getCPtr(function), function);
409  }
410
411}