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 2 versions before Version 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 2 Version 4 as well as SBML 039 * Level 3 Version 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 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<model> 058 ... 059 <listOfEvents> 060 <event useValuesFromTriggerTime='true'> 061 ... 062 <delay> 063 <math xmlns='http://www.w3.org/1998/Math/MathML'> 064 <cn> 1 </cn> 065 </math> 066 </delay> 067 ... 068 </event> 069 </listOfEvents> 070 ... 071</model> 072</pre></div> 073 <p> 074 * The <code><cn> 1 </cn></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<model> 082 ... 083 <listOfParameters> 084 <parameter id='transcriptionDelay' value='10' units='second'/> 085 </listOfParameters> 086 ... 087 <listOfEvents> 088 <event useValuesFromTriggerTime='true'> 089 ... 090 <delay> 091 <math xmlns='http://www.w3.org/1998/Math/MathML'> 092 <ci> transcriptionDelay </ci> 093 </math> 094 </delay> 095 ... 096 </event> 097 </listOfEvents> 098 ... 099</model> 100</pre></div> 101 <p> 102 * In SBML Level 3, an alternative approach is available in the form 103 * of the <code>units</code> attribute, which SBML Level 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 3 Version 1 110 * namespace. The following is an example of this approach: 111 * <div class='fragment'><pre class='fragment'> 112<model timeUnits='second' ...> 113 ... 114 <listOfEvents> 115 <event useValuesFromTriggerTime='true'> 116 ... 117 <delay> 118 <math xmlns='http://www.w3.org/1998/Math/MathML' 119 xmlns:sbml='http://www.sbml.org/sbml/level3/version1/core'> 120 <cn sbml:units='second'> 10 </cn> 121 </math> 122 </delay> 123 ... 124 </event> 125 </listOfEvents> 126 ... 127</model> 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 3) packages used in addition to SBML Level 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 2 Version 2, the units of that time are 314 * calculated based on the mathematical expression and the model quantities 315 * referenced by <code><ci></code> elements used within that 316 * expression. (In SBML Level 2 Version 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 2 Version 2, the units of that time are 361 * calculated based on the mathematical expression and the model quantities 362 * referenced by <code><ci></code> elements used within that 363 * expression. (In SBML Level 2 Version 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 “<code>SBML_</code>”. 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 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 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 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 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 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 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}