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