001/* ----------------------------------------------------------------------------
002 * This file was automatically generated by SWIG (http://www.swig.org).
003 * Version 3.0.7
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 *  A delay on the time of execution of an SBML <em>event</em>.
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 * <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>
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 * <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>
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 * <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>
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   * <p>
184 * @throws SBMLConstructorException
185 * Thrown if the given <code>level</code> and <code>version</code> combination are invalid
186 * or if this object is incompatible with the given level and version.
187   <p>
188   * <p>
189 * @note Attempting to add an object to an {@link SBMLDocument} having a different
190 * combination of SBML Level, Version and XML namespaces than the object
191 * itself will result in an error at the time a caller attempts to make the
192 * addition.  A parent object must have compatible Level, Version and XML
193 * namespaces.  (Strictly speaking, a parent may also have more XML
194 * namespaces than a child, but the reverse is not permitted.)  The
195 * restriction is necessary to ensure that an SBML model has a consistent
196 * overall structure.  This requires callers to manage their objects
197 * carefully, but the benefit is increased flexibility in how models can be
198 * created by permitting callers to create objects bottom-up if desired.  In
199 * situations where objects are not yet attached to parents (e.g.,
200 * {@link SBMLDocument}), knowledge of the intented SBML Level and Version help
201 * libSBML determine such things as whether it is valid to assign a
202 * particular value to an attribute.
203   */ public
204 Delay(long level, long version) throws org.sbml.libsbml.SBMLConstructorException {
205    this(libsbmlJNI.new_Delay__SWIG_0(level, version), true);
206  }
207
208  
209/**
210   * Creates a new {@link Delay} using the given {@link SBMLNamespaces} object
211   * <code>sbmlns</code>.
212   <p>
213   * <p>
214 * The {@link SBMLNamespaces} object encapsulates SBML Level/Version/namespaces
215 * information.  It is used to communicate the SBML Level, Version, and (in
216 * Level&nbsp;3) packages used in addition to SBML Level&nbsp;3 Core.  A
217 * common approach to using libSBML's {@link SBMLNamespaces} facilities is to create an
218 * {@link SBMLNamespaces} object somewhere in a program once, then hand that object
219 * as needed to object constructors that accept {@link SBMLNamespaces} as arguments.
220   <p>
221   * @param sbmlns an {@link SBMLNamespaces} object.
222   <p>
223   * <p>
224 * @throws SBMLConstructorException
225 * Thrown if the given <code>sbmlns</code> is inconsistent or incompatible
226 * with this object.
227   <p>
228   * <p>
229 * @note Attempting to add an object to an {@link SBMLDocument} having a different
230 * combination of SBML Level, Version and XML namespaces than the object
231 * itself will result in an error at the time a caller attempts to make the
232 * addition.  A parent object must have compatible Level, Version and XML
233 * namespaces.  (Strictly speaking, a parent may also have more XML
234 * namespaces than a child, but the reverse is not permitted.)  The
235 * restriction is necessary to ensure that an SBML model has a consistent
236 * overall structure.  This requires callers to manage their objects
237 * carefully, but the benefit is increased flexibility in how models can be
238 * created by permitting callers to create objects bottom-up if desired.  In
239 * situations where objects are not yet attached to parents (e.g.,
240 * {@link SBMLDocument}), knowledge of the intented SBML Level and Version help
241 * libSBML determine such things as whether it is valid to assign a
242 * particular value to an attribute.
243   */ public
244 Delay(SBMLNamespaces sbmlns) throws org.sbml.libsbml.SBMLConstructorException {
245    this(libsbmlJNI.new_Delay__SWIG_1(SBMLNamespaces.getCPtr(sbmlns), sbmlns), true);
246  }
247
248  
249/**
250   * Copy constructor; creates a copy of this {@link Delay}.
251   <p>
252   * @param orig the object to copy.
253   */ public
254 Delay(Delay orig) throws org.sbml.libsbml.SBMLConstructorException {
255    this(libsbmlJNI.new_Delay__SWIG_2(Delay.getCPtr(orig), orig), true);
256  }
257
258  
259/**
260   * Creates and returns a deep copy of this {@link Delay} object.
261   <p>
262   * @return the (deep) copy of this {@link Delay} object.
263   */ public
264 Delay cloneObject() {
265    long cPtr = libsbmlJNI.Delay_cloneObject(swigCPtr, this);
266    return (cPtr == 0) ? null : new Delay(cPtr, true);
267  }
268
269  
270/**
271   * Get the mathematical formula for the delay and return it
272   * as an AST.
273   <p>
274   * @return the math of this {@link Delay}.
275   */ public
276 ASTNode getMath() {
277    long cPtr = libsbmlJNI.Delay_getMath(swigCPtr, this);
278    return (cPtr == 0) ? null : new ASTNode(cPtr, false);
279  }
280
281  
282/**
283   * Predicate to test whether the formula for this delay is set.
284   <p>
285   * @return <code>true</code> if the formula (meaning the <code>math</code> subelement) of
286   * this {@link Delay} is set, <code>false</code> otherwise.
287   */ public
288 boolean isSetMath() {
289    return libsbmlJNI.Delay_isSetMath(swigCPtr, this);
290  }
291
292  
293/**
294   * Sets the delay expression of this {@link Delay} instance to a copy of the given
295   * {@link ASTNode}.
296   <p>
297   * @param math an {@link ASTNode} representing a formula tree.
298   <p>
299   * <p>
300 * @return integer value indicating success/failure of the
301 * function.   The possible values
302 * returned by this function are:
303   * <ul>
304   * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS}
305   * <li> {@link libsbmlConstants#LIBSBML_INVALID_OBJECT LIBSBML_INVALID_OBJECT}
306   * </ul>
307   */ public
308 int setMath(ASTNode math) {
309    return libsbmlJNI.Delay_setMath(swigCPtr, this, ASTNode.getCPtr(math), math);
310  }
311
312  
313/**
314   * Calculates and returns a {@link UnitDefinition} that expresses the units
315   * of measurement assumed for the 'math' expression of this {@link Delay}.
316   <p>
317   * <p>
318 * {@link Delay} elements in SBML express a time delay for an {@link Event}.  Beginning
319 * with SBML Level&nbsp;2 Version&nbsp;2, the units of that time are
320 * calculated based on the mathematical expression and the model quantities
321 * referenced by <code>&lt;ci&gt;</code> elements used within that
322 * expression.  (In SBML Level &nbsp;2 Version&nbsp;1, there exists an
323 * attribute on {@link Event} called 'timeUnits'.  This attribute can be used to set
324 * the units of the {@link Delay} expression explicitly.)  The method
325 * {@link Delay#getDerivedUnitDefinition()} returns what libSBML computes the units
326 * to be, to the extent that libSBML can compute them.
327   <p>
328   * <p>
329 * @note The functionality that facilitates unit analysis depends on the
330 * model as a whole.  Thus, in cases where the object has not been added to
331 * a model or the model itself is incomplete, unit analysis is not possible
332 * and this method will return <code>null.</code> 
333   <p>
334   * <p>
335 * @warning <span class='warning'>Note that it is possible the 'math'
336 * expression in the {@link Delay} contains literal numbers or parameters with
337 * undeclared units.  In those cases, it is not possible to calculate the
338 * units of the overall expression without making assumptions.  LibSBML does
339 * not make assumptions about the units, and
340 * {@link Delay#getDerivedUnitDefinition()} only returns the units as far as it is
341 * able to determine them.  For example, in an expression <em>X + Y</em>, if
342 * <em>X</em> has unambiguously-defined units and <em>Y</em> does not, it
343 * will return the units of <em>X</em>.  When using this method, <strong>it
344 * is critical that callers also invoke the method</strong>
345 * {@link Delay#containsUndeclaredUnits()} <strong>to determine whether this
346 * situation holds</strong>.  Callers should take suitable action in those
347 * situations.</span>
348   <p>
349   * @return a {@link UnitDefinition} that expresses the units of the math 
350   * expression of this {@link Delay}, or <code>null</code> if one cannot be constructed.
351   <p>
352   * @see #containsUndeclaredUnits()
353   */ public
354 UnitDefinition getDerivedUnitDefinition() {
355    long cPtr = libsbmlJNI.Delay_getDerivedUnitDefinition__SWIG_0(swigCPtr, this);
356    return (cPtr == 0) ? null : new UnitDefinition(cPtr, false);
357  }
358
359  
360/**
361   * Predicate returning <code>true</code> if the 'math' expression in this {@link Delay}
362   * instance contains parameters with undeclared units or literal numbers.
363   <p>
364   * <p>
365 * {@link Delay} elements in SBML express a time delay for an {@link Event}.  Beginning
366 * with SBML Level&nbsp;2 Version&nbsp;2, the units of that time are
367 * calculated based on the mathematical expression and the model quantities
368 * referenced by <code>&lt;ci&gt;</code> elements used within that
369 * expression.  (In SBML Level &nbsp;2 Version&nbsp;1, there exists an
370 * attribute on {@link Event} called 'timeUnits'.  This attribute can be used to set
371 * the units of the {@link Delay} expression explicitly.)  The method
372 * {@link Delay#getDerivedUnitDefinition()} returns what libSBML computes the units
373 * to be, to the extent that libSBML can compute them.
374   <p>
375   * If the expression contains literal numbers or parameters with undeclared
376   * units, <strong>libSBML may not be able to compute the full units of the
377   * expression</strong> and will only return what it can compute.  Callers
378   * should always use {@link Delay#containsUndeclaredUnits()} when using
379   * {@link Delay#getDerivedUnitDefinition()} to decide whether the returned units
380   * may be incomplete.
381   <p>
382   * @return <code>true</code> if the math expression of this {@link Delay} includes
383   * numbers/parameters with undeclared units, <code>false</code> otherwise.
384   <p>
385   * @note A return value of <code>true</code> indicates that the {@link UnitDefinition}
386   * returned by {@link Delay#getDerivedUnitDefinition()} may not accurately
387   * represent the units of the expression.
388   <p>
389   * @see #getDerivedUnitDefinition()
390   */ public
391 boolean containsUndeclaredUnits() {
392    return libsbmlJNI.Delay_containsUndeclaredUnits__SWIG_0(swigCPtr, this);
393  }
394
395  
396/**
397   * Returns the libSBML type code of this object instance.
398   <p>
399   * <p>
400 * LibSBML attaches an identifying code to every kind of SBML object.  These
401 * are integer constants known as <em>SBML type codes</em>.  The names of all
402 * the codes begin with the characters <code>SBML_</code>.
403 * In the Java language interface for libSBML, the
404 * type codes are defined as static integer constants in the interface class
405 * {@link libsbmlConstants}.    Note that different Level&nbsp;3
406 * package plug-ins may use overlapping type codes; to identify the package
407 * to which a given object belongs, call the <code>getPackageName()</code>
408 * method on the object.
409   <p>
410   * @return the SBML type code for this object:
411   * {@link libsbmlConstants#SBML_DELAY SBML_DELAY} (default).
412   <p>
413   * <p>
414 * @warning <span class='warning'>The specific integer values of the possible
415 * type codes may be reused by different Level&nbsp;3 package plug-ins.
416 * Thus, to identifiy the correct code, <strong>it is necessary to invoke
417 * both getTypeCode() and getPackageName()</strong>.</span>
418   <p>
419   * @see #getElementName()
420   * @see #getPackageName()
421   */ public
422 int getTypeCode() {
423    return libsbmlJNI.Delay_getTypeCode(swigCPtr, this);
424  }
425
426  
427/**
428   * Returns the XML element name of this object, which for {@link Delay}, is
429   * always <code>'delay'.</code>
430   <p>
431   * @return the name of this element, i.e., <code>'delay'.</code>
432   <p>
433   * @see #getTypeCode()
434   */ public
435 String getElementName() {
436    return libsbmlJNI.Delay_getElementName(swigCPtr, this);
437  }
438
439  
440/**
441   * Predicate returning <code>true</code> if
442   * all the required elements for this {@link Delay} object
443   * have been set.
444   <p>
445   * @note The required elements for a {@link Delay} object are:
446   * <ul>
447   * <li> 'math'
448   *
449   * </ul> <p>
450   * @return a boolean value indicating whether all the required
451   * elements for this object have been defined.
452   */ public
453 boolean hasRequiredElements() {
454    return libsbmlJNI.Delay_hasRequiredElements(swigCPtr, this);
455  }
456
457  
458/**
459   * Finds this {@link Delay}'s {@link Event} parent and calls unsetDelay() on it, indirectly
460   * deleting itself.
461   <p>
462   * Overridden from the {@link SBase} function since the parent is not a {@link ListOf}.
463   <p>
464   * <p>
465 * @return integer value indicating success/failure of the
466 * function.   The possible values
467 * returned by this function are:
468   * <ul>
469   * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS}
470   * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED}
471   * </ul>
472   */ public
473 int removeFromParentAndDelete() {
474    return libsbmlJNI.Delay_removeFromParentAndDelete(swigCPtr, this);
475  }
476
477  
478/**
479   * <p>
480 * Replaces all uses of a given <code>SIdRef</code> type attribute value with another
481 * value.
482 <p>
483 * <p>
484 * In SBML, object identifiers are of a data type called <code>SId</code>.
485 * In SBML Level&nbsp;3, an explicit data type called <code>SIdRef</code> was
486 * introduced for attribute values that refer to <code>SId</code> values; in
487 * previous Levels of SBML, this data type did not exist and attributes were
488 * simply described to as 'referring to an identifier', but the effective
489 * data type was the same as <code>SIdRef</code>in Level&nbsp;3.  These and
490 * other methods of libSBML refer to the type <code>SIdRef</code> for all
491 * Levels of SBML, even if the corresponding SBML specification did not
492 * explicitly name the data type.
493 <p>
494 * This method works by looking at all attributes and (if appropriate)
495 * mathematical formulas in MathML content, comparing the referenced
496 * identifiers to the value of <code>oldid</code>.  If any matches are found, the
497 * matching values are replaced with <code>newid</code>.  The method does <em>not</em>
498 * descend into child elements.
499 <p>
500 * @param oldid the old identifier
501 * @param newid the new identifier
502   */ public
503 void renameSIdRefs(String oldid, String newid) {
504    libsbmlJNI.Delay_renameSIdRefs(swigCPtr, this, oldid, newid);
505  }
506
507  
508/**
509   * <p>
510 * Replaces all uses of a given <code>UnitSIdRef</code> type attribute value with
511 * another value.
512 <p>
513 * <p>
514 * In SBML, unit definitions have identifiers of type <code>UnitSId</code>.  In
515 * SBML Level&nbsp;3, an explicit data type called <code>UnitSIdRef</code> was
516 * introduced for attribute values that refer to <code>UnitSId</code> values; in
517 * previous Levels of SBML, this data type did not exist and attributes were
518 * simply described to as 'referring to a unit identifier', but the effective
519 * data type was the same as <code>UnitSIdRef</code> in Level&nbsp;3.  These and
520 * other methods of libSBML refer to the type <code>UnitSIdRef</code> for all
521 * Levels of SBML, even if the corresponding SBML specification did not
522 * explicitly name the data type.
523 <p>
524 * This method works by looking at all unit identifier attribute values
525 * (including, if appropriate, inside mathematical formulas), comparing the
526 * referenced unit identifiers to the value of <code>oldid</code>.  If any matches
527 * are found, the matching values are replaced with <code>newid</code>.  The method
528 * does <em>not</em> descend into child elements.
529 <p>
530 * @param oldid the old identifier
531 * @param newid the new identifier
532   */ public
533 void renameUnitSIdRefs(String oldid, String newid) {
534    libsbmlJNI.Delay_renameUnitSIdRefs(swigCPtr, this, oldid, newid);
535  }
536
537  
538/** * @internal */ public
539 void replaceSIDWithFunction(String id, ASTNode function) {
540    libsbmlJNI.Delay_replaceSIDWithFunction(swigCPtr, this, id, ASTNode.getCPtr(function), function);
541  }
542
543}