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