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