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 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 * <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 the SBML Level 3 Version 1 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 */ 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 3) packages used in addition to SBML Level 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 2 Version 2, the units of that time are 320 * calculated based on the mathematical expression and the model quantities 321 * referenced by <code><ci></code> elements used within that 322 * expression. (In SBML Level 2 Version 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 2 Version 2, the units of that time are 367 * calculated based on the mathematical expression and the model quantities 368 * referenced by <code><ci></code> elements used within that 369 * expression. (In SBML Level 2 Version 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 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 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 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 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 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 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}