001/* ----------------------------------------------------------------------------
002 * This file was automatically generated by SWIG (http://www.swig.org).
003 * Version 2.0.12
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 *  Implementation of SBML's Delay construct for Event.
013 <p>
014 * An {@link Event} object defines when the event can occur, the variables that
015 * are affected by the event, and how the variables are affected.  The
016 * effect of the event can optionally be delayed after the occurrence of
017 * the condition which invokes it.  An event delay is defined using an
018 * object of class {@link Delay}.
019 <p>
020 * The object class {@link Delay} is derived from {@link SBase} and adds a single
021 * subelement called 'math'.  This subelement is used to hold MathML
022 * content.  The mathematical formula represented by 'math' must evaluate
023 * to a numerical value.  It is used as the length of time between when the
024 * event is <em>triggered</em> and when the event's assignments are
025 * actually <em>executed</em>.  If no delay is present on a given {@link Event}, a time
026 * delay of zero is assumed.
027 <p>
028 * The expression in 'math' must be evaluated at the time the event is 
029 * <em>triggered</em>.  The expression must always evaluate to a nonnegative number
030 * (otherwise, a nonsensical situation could arise where an event is
031 * defined to execute before it is triggered!).
032 <p>
033 * <h2>The units of the mathematical expression in a {@link Delay}</h2>
034 <p>
035 * In SBML Level&nbsp;2 versions before Version&nbsp;4, the units of the
036 * numerical value computed by the {@link Delay}'s 'math' expression are 
037 * <em>required</em> to be in units of time, or the model is considered to have a
038 * unit consistency error.  In Level&nbsp;2 Version&nbsp;4 as well as SBML
039 * Level&nbsp;3 Version&nbsp;1 Core, this requirement is relaxed; these
040 * specifications only stipulate that the units of the numerical value
041 * computed by a {@link Delay} instance's 'math' expression <em>should</em> match the
042 * model's units of time (meaning the definition of the <code>time</code> units in
043 * the model).  LibSBML respects these requirements, and depending on
044 * whether an earlier Version of SBML Level&nbsp;2 is in use, libSBML may
045 * or may not flag unit inconsistencies as errors or merely warnings.
046 <p>
047 * Note that <em>units are not predefined or assumed</em> for the contents
048 * of 'math' in a {@link Delay} object; rather, they must be defined explicitly for
049 * each instance of a {@link Delay} object in a model.  This is an important point
050 * to bear in mind when literal numbers are used in delay expressions.  For
051 * example, the following {@link Event} instance would result in a warning logged
052 * by {@link SBMLDocument#checkConsistency()} about the fact that libSBML cannot
053 * verify the consistency of the units of the expression.  The reason is
054 * that the formula inside the 'math' element does not have any declared
055 * units, whereas what is expected in this context is units of time:
056 * <div class='fragment'><pre class='fragment'>
057&lt;model&gt;
058    ...
059    &lt;listOfEvents&gt;
060        &lt;event useValuesFromTriggerTime='true'&gt;
061            ...
062            &lt;delay&gt;
063                &lt;math xmlns='http://www.w3.org/1998/Math/MathML'&gt;
064                    &lt;cn&gt; 1 &lt;/cn&gt;
065                &lt;/math&gt;
066            &lt;/delay&gt;
067            ...
068        &lt;/event&gt;
069    &lt;/listOfEvents&gt;
070    ...
071&lt;/model&gt;
072</pre></div>
073 <p>
074 * The <code>&lt;cn&gt; 1 &lt;/cn&gt;</code> within the mathematical formula
075 * of the <code>delay</code> above has <em>no units declared</em>.  To make the
076 * expression have the needed units of time, literal numbers should be
077 * avoided in favor of defining {@link Parameter} objects for each quantity, and
078 * declaring units for the {@link Parameter} values.  The following fragment of
079 * SBML illustrates this approach:
080 * <div class='fragment'><pre class='fragment'>
081&lt;model&gt;
082    ...
083    &lt;listOfParameters&gt;
084        &lt;parameter id='transcriptionDelay' value='10' units='second'/&gt;
085    &lt;/listOfParameters&gt;
086    ...
087    &lt;listOfEvents&gt;
088        &lt;event useValuesFromTriggerTime='true'&gt;
089            ...
090            &lt;delay&gt;
091                &lt;math xmlns='http://www.w3.org/1998/Math/MathML'&gt;
092                    &lt;ci&gt; transcriptionDelay &lt;/ci&gt;
093                &lt;/math&gt;
094            &lt;/delay&gt;
095            ...
096        &lt;/event&gt;
097    &lt;/listOfEvents&gt;
098    ...
099&lt;/model&gt;
100</pre></div>
101 <p>
102 * In SBML Level&nbsp;3, an alternative approach is available in the form
103 * of the <code>units</code> attribute, which SBML Level&nbsp;3 allows to appear on
104 * MathML <code>cn</code> elements.  The value of this attribute can be used to
105 * indicate the unit of measurement to be associated with the number in the
106 * content of a <code>cn</code> element.  The attribute is named <code>units</code> but,
107 * because it appears inside MathML element (which is in the XML namespace
108 * for MathML and not the namespace for SBML), it must always be prefixed
109 * with an XML namespace prefix for the SBML Level&nbsp;3 Version&nbsp;1
110 * namespace.  The following is an example of this approach:
111 * <div class='fragment'><pre class='fragment'>
112&lt;model timeUnits='second' ...&gt;
113    ...
114    &lt;listOfEvents&gt;
115        &lt;event useValuesFromTriggerTime='true'&gt;
116            ...
117            &lt;delay&gt;
118                &lt;math xmlns='http://www.w3.org/1998/Math/MathML'
119                      xmlns:sbml='http://www.sbml.org/sbml/level3/version1/core'&gt;
120                    &lt;cn sbml:units='second'&gt; 10 &lt;/cn&gt;
121                &lt;/math&gt;
122            &lt;/delay&gt;
123            ...
124        &lt;/event&gt;
125    &lt;/listOfEvents&gt;
126    ...
127&lt;/model&gt;
128</pre></div>
129 */
130
131public class Delay extends SBase {
132   private long swigCPtr;
133
134   protected Delay(long cPtr, boolean cMemoryOwn)
135   {
136     super(libsbmlJNI.Delay_SWIGUpcast(cPtr), cMemoryOwn);
137     swigCPtr = cPtr;
138   }
139
140   protected static long getCPtr(Delay obj)
141   {
142     return (obj == null) ? 0 : obj.swigCPtr;
143   }
144
145   protected static long getCPtrAndDisown (Delay obj)
146   {
147     long ptr = 0;
148
149     if (obj != null)
150     {
151       ptr             = obj.swigCPtr;
152       obj.swigCMemOwn = false;
153     }
154
155     return ptr;
156   }
157
158  protected void finalize() {
159    delete();
160  }
161
162  public synchronized void delete() {
163    if (swigCPtr != 0) {
164      if (swigCMemOwn) {
165        swigCMemOwn = false;
166        libsbmlJNI.delete_Delay(swigCPtr);
167      }
168      swigCPtr = 0;
169    }
170    super.delete();
171  }
172
173  
174/**
175   * Creates a new {@link Delay} using the given SBML <code>level</code> and <code>version</code>
176   * values.
177   <p>
178   * @param level a long integer, the SBML Level to assign to this {@link Delay}
179   <p>
180   * @param version a long integer, the SBML Version to assign to this
181   * {@link Delay}
182   <p>
183   * @throws SBMLConstructorException 
184   * Thrown if the given <code>level</code> and <code>version</code> combination, or this kind
185   * of SBML object, are either invalid or mismatched with respect to the
186   * parent {@link SBMLDocument} object.
187   <p>
188   * <p>
189 * @note Upon the addition of a {@link Delay} object to an {@link Event} (e.g., using
190 * {@link Event#setDelay(Delay d)}), the SBML Level, SBML Version
191 * and XML namespace of the document <em>override</em> the values used when
192 * creating the {@link Delay} object via this constructor.  This is necessary to
193 * ensure that an SBML document is a consistent structure.  Nevertheless,
194 * the ability to supply the values at the time of creation of a {@link Delay} is
195 * an important aid to producing valid SBML.  Knowledge of the intented
196 * SBML Level and Version determine whether it is valid to assign a
197 * particular value to an attribute, or whether it is valid to add a
198 * particular {@link Delay} object to an existing {@link Event}.
199   */ public
200 Delay(long level, long version) throws org.sbml.libsbml.SBMLConstructorException {
201    this(libsbmlJNI.new_Delay__SWIG_0(level, version), true);
202  }
203
204  
205/**
206   * Creates a new {@link Delay} using the given {@link SBMLNamespaces} object
207   * <code>sbmlns</code>.
208   <p>
209   * <p>
210 * The {@link SBMLNamespaces} object encapsulates SBML Level/Version/namespaces
211 * information.  It is used to communicate the SBML Level, Version, and (in
212 * Level&nbsp;3) packages used in addition to SBML Level&nbsp;3 Core.  A
213 * common approach to using libSBML's {@link SBMLNamespaces} facilities is to create an
214 * {@link SBMLNamespaces} object somewhere in a program once, then hand that object
215 * as needed to object constructors that accept {@link SBMLNamespaces} as arguments.
216   <p>
217   * @param sbmlns an {@link SBMLNamespaces} object.
218   <p>
219   * @throws SBMLConstructorException 
220   * Thrown if the given <code>level</code> and <code>version</code> combination, or this kind
221   * of SBML object, are either invalid or mismatched with respect to the
222   * parent {@link SBMLDocument} object.
223   <p>
224   * <p>
225 * @note Upon the addition of a {@link Delay} object to an {@link Event} (e.g., using
226 * {@link Event#setDelay(Delay d)}), the SBML Level, SBML Version
227 * and XML namespace of the document <em>override</em> the values used when
228 * creating the {@link Delay} object via this constructor.  This is necessary to
229 * ensure that an SBML document is a consistent structure.  Nevertheless,
230 * the ability to supply the values at the time of creation of a {@link Delay} is
231 * an important aid to producing valid SBML.  Knowledge of the intented
232 * SBML Level and Version determine whether it is valid to assign a
233 * particular value to an attribute, or whether it is valid to add a
234 * particular {@link Delay} object to an existing {@link Event}.
235   */ public
236 Delay(SBMLNamespaces sbmlns) throws org.sbml.libsbml.SBMLConstructorException {
237    this(libsbmlJNI.new_Delay__SWIG_1(SBMLNamespaces.getCPtr(sbmlns), sbmlns), true);
238  }
239
240  
241/**
242   * Copy constructor; creates a copy of this {@link Delay}.
243   <p>
244   * @param orig the object to copy.
245   <p>
246   * @throws SBMLConstructorException 
247   * Thrown if the argument <code>orig</code> is <code>null.</code>
248   */ public
249 Delay(Delay orig) throws org.sbml.libsbml.SBMLConstructorException {
250    this(libsbmlJNI.new_Delay__SWIG_2(Delay.getCPtr(orig), orig), true);
251  }
252
253  
254/**
255   * Creates and returns a deep copy of this {@link Delay}.
256   <p>
257   * @return a (deep) copy of this {@link Delay}.
258   */ public
259 Delay cloneObject() {
260    long cPtr = libsbmlJNI.Delay_cloneObject(swigCPtr, this);
261    return (cPtr == 0) ? null : new Delay(cPtr, true);
262  }
263
264  
265/**
266   * Get the mathematical formula for the delay and return it
267   * as an AST.
268   <p>
269   * @return the math of this {@link Delay}.
270   */ public
271 ASTNode getMath() {
272    long cPtr = libsbmlJNI.Delay_getMath(swigCPtr, this);
273    return (cPtr == 0) ? null : new ASTNode(cPtr, false);
274  }
275
276  
277/**
278   * Predicate to test whether the formula for this delay is set.
279   <p>
280   * @return <code>true</code> if the formula (meaning the <code>math</code> subelement) of
281   * this {@link Delay} is set, <code>false</code> otherwise.
282   */ public
283 boolean isSetMath() {
284    return libsbmlJNI.Delay_isSetMath(swigCPtr, this);
285  }
286
287  
288/**
289   * Sets the delay expression of this {@link Delay} instance to a copy of the given
290   * {@link ASTNode}.
291   <p>
292   * @param math an {@link ASTNode} representing a formula tree.
293   <p>
294   * @return integer value indicating success/failure of the
295   * function.   The possible values
296   * returned by this function are:
297   * <ul>
298   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS }
299   * <li> {@link  libsbmlConstants#LIBSBML_INVALID_OBJECT LIBSBML_INVALID_OBJECT }
300   * </ul>
301   */ public
302 int setMath(ASTNode math) {
303    return libsbmlJNI.Delay_setMath(swigCPtr, this, ASTNode.getCPtr(math), math);
304  }
305
306  
307/**
308   * Calculates and returns a {@link UnitDefinition} that expresses the units
309   * of measurement assumed for the 'math' expression of this {@link Delay}.
310   <p>
311   * <p>
312 * {@link Delay} elements in SBML express a time delay for an {@link Event}.  Beginning
313 * with SBML Level&nbsp;2 Version&nbsp;2, the units of that time are
314 * calculated based on the mathematical expression and the model quantities
315 * referenced by <code>&lt;ci&gt;</code> elements used within that
316 * expression.  (In SBML Level &nbsp;2 Version&nbsp;1, there exists an
317 * attribute on {@link Event} called 'timeUnits'.  This attribute can be used to set
318 * the units of the {@link Delay} expression explicitly.)  The method
319 * {@link Delay#getDerivedUnitDefinition()} returns what libSBML computes the units
320 * to be, to the extent that libSBML can compute them.
321   <p>
322   * <p>
323 * @note The functionality that facilitates unit analysis depends on the
324 * model as a whole.  Thus, in cases where the object has not been added to
325 * a model or the model itself is incomplete, unit analysis is not possible
326 * and this method will return <code>null.</code> 
327   <p>
328   * <p>
329 * @warning <span class='warning'>Note that it is possible the 'math'
330 * expression in the {@link Delay} contains literal numbers or parameters with
331 * undeclared units.  In those cases, it is not possible to calculate the
332 * units of the overall expression without making assumptions.  LibSBML does
333 * not make assumptions about the units, and
334 * {@link Delay#getDerivedUnitDefinition()} only returns the units as far as it is
335 * able to determine them.  For example, in an expression <em>X + Y</em>, if
336 * <em>X</em> has unambiguously-defined units and <em>Y</em> does not, it
337 * will return the units of <em>X</em>.  When using this method, <strong>it
338 * is critical that callers also invoke the method</strong>
339 * {@link Delay#containsUndeclaredUnits()} <strong>to determine whether this
340 * situation holds</strong>.  Callers should take suitable action in those
341 * situations.</span>
342   <p>
343   * @return a {@link UnitDefinition} that expresses the units of the math 
344   * expression of this {@link Delay}, or <code>null</code> if one cannot be constructed.
345   <p>
346   * @see #containsUndeclaredUnits()
347   */ public
348 UnitDefinition getDerivedUnitDefinition() {
349    long cPtr = libsbmlJNI.Delay_getDerivedUnitDefinition__SWIG_0(swigCPtr, this);
350    return (cPtr == 0) ? null : new UnitDefinition(cPtr, false);
351  }
352
353  
354/**
355   * Predicate returning <code>true</code> if the 'math' expression in this {@link Delay}
356   * instance contains parameters with undeclared units or literal numbers.
357   <p>
358   * <p>
359 * {@link Delay} elements in SBML express a time delay for an {@link Event}.  Beginning
360 * with SBML Level&nbsp;2 Version&nbsp;2, the units of that time are
361 * calculated based on the mathematical expression and the model quantities
362 * referenced by <code>&lt;ci&gt;</code> elements used within that
363 * expression.  (In SBML Level &nbsp;2 Version&nbsp;1, there exists an
364 * attribute on {@link Event} called 'timeUnits'.  This attribute can be used to set
365 * the units of the {@link Delay} expression explicitly.)  The method
366 * {@link Delay#getDerivedUnitDefinition()} returns what libSBML computes the units
367 * to be, to the extent that libSBML can compute them.
368   <p>
369   * If the expression contains literal numbers or parameters with undeclared
370   * units, <strong>libSBML may not be able to compute the full units of the
371   * expression</strong> and will only return what it can compute.  Callers
372   * should always use {@link Delay#containsUndeclaredUnits()} when using
373   * {@link Delay#getDerivedUnitDefinition()} to decide whether the returned units
374   * may be incomplete.
375   <p>
376   * @return <code>true</code> if the math expression of this {@link Delay} includes
377   * numbers/parameters with undeclared units, <code>false</code> otherwise.
378   <p>
379   * @note A return value of <code>true</code> indicates that the {@link UnitDefinition}
380   * returned by {@link Delay#getDerivedUnitDefinition()} may not accurately
381   * represent the units of the expression.
382   <p>
383   * @see #getDerivedUnitDefinition()
384   */ public
385 boolean containsUndeclaredUnits() {
386    return libsbmlJNI.Delay_containsUndeclaredUnits__SWIG_0(swigCPtr, this);
387  }
388
389  
390/**
391   * Returns the libSBML type code of this object instance.
392   <p>
393   * <p>
394 * LibSBML attaches an identifying code to every kind of SBML object.  These
395 * are integer constants known as <em>SBML type codes</em>.  The names of all
396 * the codes begin with the characters &ldquo;<code>SBML_</code>&rdquo;. 
397 * In the Java language interface for libSBML, the
398 * type codes are defined as static integer constants in the interface class
399 * {@link libsbmlConstants}.    Note that different Level&nbsp;3 
400 * package plug-ins may use overlapping type codes; to identify the package
401 * to which a given object belongs, call the <code>getPackageName()</code>
402 * method on the object.
403   <p>
404   * @return the SBML type code for this object:
405   * {@link  libsbmlConstants#SBML_DELAY SBML_DELAY} (default).
406   <p>
407   * <p>
408 * @warning <span class='warning'>The specific integer values of the possible
409 * type codes may be reused by different Level&nbsp;3 package plug-ins.
410 * Thus, to identifiy the correct code, <strong>it is necessary to invoke
411 * both getTypeCode() and getPackageName()</strong>.</span>
412   <p>
413   * @see #getElementName()
414   * @see #getPackageName()
415   */ public
416 int getTypeCode() {
417    return libsbmlJNI.Delay_getTypeCode(swigCPtr, this);
418  }
419
420  
421/**
422   * Returns the XML element name of this object, which for {@link Delay}, is
423   * always <code>'delay'.</code>
424   <p>
425   * @return the name of this element, i.e., <code>'delay'.</code>
426   <p>
427   * @see #getTypeCode()
428   */ public
429 String getElementName() {
430    return libsbmlJNI.Delay_getElementName(swigCPtr, this);
431  }
432
433  
434/**
435   * Predicate returning <code>true</code> if
436   * all the required elements for this {@link Delay} object
437   * have been set.
438   <p>
439   * @note The required elements for a {@link Delay} object are:
440   * <ul>
441   * <li> 'math'
442   *
443   * </ul> <p>
444   * @return a boolean value indicating whether all the required
445   * elements for this object have been defined.
446   */ public
447 boolean hasRequiredElements() {
448    return libsbmlJNI.Delay_hasRequiredElements(swigCPtr, this);
449  }
450
451  
452/**
453   * Finds this {@link Delay}'s {@link Event} parent and calls unsetDelay() on it, indirectly
454   * deleting itself.
455   <p>
456   * Overridden from the {@link SBase} function since the parent is not a {@link ListOf}.
457   <p>
458   * @return integer value indicating success/failure of the
459   * function.   The possible values
460   * returned by this function are:
461   * <ul>
462   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS }
463   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED }
464   * </ul>
465   */ public
466 int removeFromParentAndDelete() {
467    return libsbmlJNI.Delay_removeFromParentAndDelete(swigCPtr, this);
468  }
469
470  
471/**
472   * Renames all the <code>SIdRef</code> attributes on this element, including any
473   * found in MathML.
474   <p>
475   * <p>
476 * In SBML, object identifiers are of a data type called <code>SId</code>.
477 * In SBML Level&nbsp;3, an explicit data type called <code>SIdRef</code> was
478 * introduced for attribute values that refer to <code>SId</code> values; in
479 * previous Levels of SBML, this data type did not exist and attributes were
480 * simply described to as 'referring to an identifier', but the effective
481 * data type was the same as <code>SIdRef</code>in Level&nbsp;3.  These and
482 * other methods of libSBML refer to the type <code>SIdRef</code> for all
483 * Levels of SBML, even if the corresponding SBML specification did not
484 * explicitly name the data type.
485   <p>
486   * This method works by looking at all attributes and (if appropriate)
487   * mathematical formulas, comparing the identifiers to the value of 
488   * <code>oldid</code>.  If any matches are found, the matching identifiers are replaced
489   * with <code>newid</code>.  The method does <em>not</em> descend into child elements.
490   <p>
491   * @param oldid the old identifier
492   * @param newid the new identifier
493   */ public
494 void renameSIdRefs(String oldid, String newid) {
495    libsbmlJNI.Delay_renameSIdRefs(swigCPtr, this, oldid, newid);
496  }
497
498  
499/**
500   * Renames all the <code>UnitSIdRef</code> attributes on this element
501   <p>
502   * <p>
503 * In SBML, unit definitions have identifiers of type <code>UnitSId</code>.  In
504 * SBML Level&nbsp;3, an explicit data type called <code>UnitSIdRef</code> was
505 * introduced for attribute values that refer to <code>UnitSId</code> values; in
506 * previous Levels of SBML, this data type did not exist and attributes were
507 * simply described to as 'referring to a unit identifier', but the effective
508 * data type was the same as <code>UnitSIdRef</code> in Level&nbsp;3.  These and
509 * other methods of libSBML refer to the type <code>UnitSIdRef</code> for all
510 * Levels of SBML, even if the corresponding SBML specification did not
511 * explicitly name the data type.
512   <p>
513   * This method works by looking at all unit identifier attribute values
514   * (including, if appropriate, inside mathematical formulas), comparing the
515   * unit identifiers to the value of <code>oldid</code>.  If any matches are found,
516   * the matching identifiers are replaced with <code>newid</code>.  The method does
517   * <em>not</em> descend into child elements.
518   <p>
519   * @param oldid the old identifier
520   * @param newid the new identifier
521   */ public
522 void renameUnitSIdRefs(String oldid, String newid) {
523    libsbmlJNI.Delay_renameUnitSIdRefs(swigCPtr, this, oldid, newid);
524  }
525
526  
527/**
528   * Replace all nodes with the name 'id' from the child 'math' object with the provided function. 
529   <p>
530   * @internal
531   */ public
532 void replaceSIDWithFunction(String id, ASTNode function) {
533    libsbmlJNI.Delay_replaceSIDWithFunction(swigCPtr, this, id, ASTNode.getCPtr(function), function);
534  }
535
536}