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 * The priority of execution of an SBML <em>event</em>. 013 <p> 014 * The {@link Priority} object class (which was introduced in SBML Level 3 015 * Version 1), like {@link Delay}, is derived from {@link SBase} and contains a MathML 016 * formula stored in the element 'math'. This formula is used to compute a 017 * dimensionless numerical value that influences the order in which a 018 * simulator is to perform the assignments of two or more events that 019 * happen to be executed simultaneously. The formula may evaluate to any 020 * <code>double</code> value (and thus may be a positive or negative number, or 021 * zero), with positive numbers taken to signifying a higher priority than 022 * zero or negative numbers. If no {@link Priority} object is present on a given 023 * {@link Event} object, no priority is defined for that event. 024 <p> 025 * <h2>The interpretation of priorities on events in a model</h2> 026 <p> 027 * For the purposes of SBML, <em>simultaneous event execution</em> is 028 * defined as the situation in which multiple events have identical 029 * times of execution. The time of execution is calculated as the 030 * sum of the time at which a given event's {@link Trigger} is <em>triggered</em> 031 * plus its {@link Delay} duration, if any. Here, <em>identical times</em> means 032 * <em>mathematically equal</em> instants in time. (In practice, 033 * simulation software adhering to this specification may have to 034 * rely on numerical equality instead of strict mathematical 035 * equality; robust models will ensure that this difference will not 036 * cause significant discrepancies from expected behavior.) 037 <p> 038 * If no {@link Priority} subobjects are defined for two or more {@link Event} objects, 039 * then those events are still executed simultaneously but their order of 040 * execution is <em>undefined by the SBML Level 3 041 * specification</em>. A software implementation may choose to execute 042 * such simultaneous events in any order, as long as each event is executed 043 * only once and the requirements of checking the 'persistent' attribute 044 * (and acting accordingly) are satisfied. 045 <p> 046 * If {@link Priority} subobjects are defined for two or more 047 * simultaneously-triggered events, the order in which those particular 048 * events must be executed is dictated by their {@link Priority} objects, 049 * as follows. If the values calculated using the two {@link Priority} 050 * objects' 'math' expressions differ, then the event having 051 * the higher priority value must be executed before the event with 052 * the lower value. If, instead, the two priority values are 053 * mathematically equal, then the two events must be triggered in a 054 * <em>random</em> order. It is important to note that a <em>random 055 * order is not the same as an undefined order</em>: given multiple 056 * runs of the same model with identical conditions, an undefined 057 * ordering would permit a system to execute the events in (for 058 * example) the same order every time (according to whatever scheme 059 * may have been implemented by the system), whereas the explicit 060 * requirement for random ordering means that the order of execution 061 * in different simulation runs depends on random chance. In other 062 * words, given two events <em>A</em> and <em>B</em>, a randomly-determined 063 * order must lead to an equal chance of executing <em>A</em> first or 064 * <em>B</em> first, every time those two events are executed 065 * simultaneously. 066 <p> 067 * A model may contain a mixture of events, some of which have 068 * {@link Priority} subobjects and some do not. Should a combination of 069 * simultaneous events arise in which some events have priorities 070 * defined and others do not, the set of events with defined 071 * priorities must trigger in the order determined by their {@link Priority} 072 * objects, and the set of events without {@link Priority} objects must be 073 * executed in an <em>undefined</em> order with respect to each other 074 * and with respect to the events with {@link Priority} subobjects. (Note 075 * that <em>undefined order</em> does not necessarily mean random 076 * order, although a random ordering would be a valid implementation 077 * of this requirement.) 078 <p> 079 * The following example may help further clarify these points. 080 * Suppose a model contains four events that should be executed 081 * simultaneously, with two of the events having {@link Priority} objects 082 * with the same value and the other two events having {@link Priority} 083 * objects with the same, but different, value. The two events with 084 * the higher priorities must be executed first, in a random order 085 * with respect to each other, and the remaining two events must be 086 * executed after them, again in a random order, for a total of four 087 * possible and equally-likely event executions: A-B-C-D, A-B-D-C, 088 * B-A-C-D, and B-A-D-C. If, instead, the model contains four events 089 * all having the same {@link Priority} values, there are 4! or 24 090 * possible orderings, each of which must be equally likely to be 091 * chosen. Finally, if none of the four events has a {@link Priority} 092 * subobject defined, or even if exactly one of the four events has a 093 * defined {@link Priority}, there are again 24 possible orderings, but the 094 * likelihood of choosing any particular ordering is undefined; the 095 * simulator can choose between events as it wishes. (The SBML 096 * specification only defines the effects of priorities on {@link Event} 097 * objects with respect to <em>other</em> {@link Event} objects with 098 * priorities. Putting a priority on a <em>single</em> {@link Event} object 099 * in a model does not cause it to fall within that scope.) 100 <p> 101 * <h2>Evaluation of {@link Priority} expressions</h2> 102 <p> 103 * An event's {@link Priority} object 'math' expression must be 104 * evaluated at the time the {@link Event} is to be <em>executed</em>. During 105 * a simulation, all simultaneous events have their {@link Priority} values 106 * calculated, and the event with the highest priority is selected for 107 * next execution. Note that it is possible for the execution of one 108 * {@link Event} object to cause the {@link Priority} value of another 109 * simultaneously-executing {@link Event} object to change (as well as to 110 * trigger other events, as already noted). Thus, after executing 111 * one event, and checking whether any other events in the model have 112 * been triggered, all remaining simultaneous events that 113 * <em>either</em> (i) have {@link Trigger} objects with attributes 114 * 'persistent'=<code>false</code> <em>or</em> (ii) have {@link Trigger} 115 * expressions that did not transition from <code>true</code> to 116 * <code>false</code>, must have their {@link Priority} expression reevaluated. 117 * The highest-priority remaining event must then be selected for 118 * execution next. 119 <p> 120 * <h2>Units of {@link Priority} object's mathematical expressions</h2> 121 <p> 122 * The unit associated with the value of a {@link Priority} object's 123 * 'math' expression should be <code>dimensionless.</code> This is 124 * because the priority expression only serves to provide a relative 125 * ordering between different events, and only has meaning with 126 * respect to other {@link Priority} object expressions. The value of 127 * {@link Priority} objects is not comparable to any other kind of object in 128 * an SBML model. 129 <p> 130 * @note The {@link Priority} construct exists only in SBML Level 3; it cannot 131 * be used in SBML Level 2 or Level 1 models. 132 <p> 133 * <h2>Restrictions relaxed in SBML Level 3 Version 2</h2> 134 <p> 135 * In SBML Level 3 Version 2, the requirement that a {@link Priority} 136 * have a 'math' subelement was relaxed, making it optional. In 137 * this case, the {@link Priority} remains undefined, and unless that information 138 * is provided in some other form (such as with an SBML Level 3 139 * package), the {@link Event} behaves as if it had no {@link Priority}. 140 <p> 141 * @see Event 142 * @see Delay 143 * @see EventAssignment 144 */ 145 146public class Priority extends SBase { 147 private long swigCPtr; 148 149 protected Priority(long cPtr, boolean cMemoryOwn) 150 { 151 super(libsbmlJNI.Priority_SWIGUpcast(cPtr), cMemoryOwn); 152 swigCPtr = cPtr; 153 } 154 155 protected static long getCPtr(Priority obj) 156 { 157 return (obj == null) ? 0 : obj.swigCPtr; 158 } 159 160 protected static long getCPtrAndDisown (Priority obj) 161 { 162 long ptr = 0; 163 164 if (obj != null) 165 { 166 ptr = obj.swigCPtr; 167 obj.swigCMemOwn = false; 168 } 169 170 return ptr; 171 } 172 173 protected void finalize() { 174 delete(); 175 } 176 177 public synchronized void delete() { 178 if (swigCPtr != 0) { 179 if (swigCMemOwn) { 180 swigCMemOwn = false; 181 libsbmlJNI.delete_Priority(swigCPtr); 182 } 183 swigCPtr = 0; 184 } 185 super.delete(); 186 } 187 188 189/** 190 * Creates a new {@link Priority} object using the given SBML <code>level</code> and 191 * <code>version</code> values. 192 <p> 193 * @param level a long integer, the SBML Level to assign to this {@link Priority}. 194 <p> 195 * @param version a long integer, the SBML Version to assign to this 196 * {@link Priority}. 197 <p> 198 * <p> 199 * @throws SBMLConstructorException 200 * Thrown if the given <code>level</code> and <code>version</code> combination are invalid 201 * or if this object is incompatible with the given level and version. 202 <p> 203 * <p> 204 * @note Attempting to add an object to an {@link SBMLDocument} having a different 205 * combination of SBML Level, Version and XML namespaces than the object 206 * itself will result in an error at the time a caller attempts to make the 207 * addition. A parent object must have compatible Level, Version and XML 208 * namespaces. (Strictly speaking, a parent may also have more XML 209 * namespaces than a child, but the reverse is not permitted.) The 210 * restriction is necessary to ensure that an SBML model has a consistent 211 * overall structure. This requires callers to manage their objects 212 * carefully, but the benefit is increased flexibility in how models can be 213 * created by permitting callers to create objects bottom-up if desired. In 214 * situations where objects are not yet attached to parents (e.g., 215 * {@link SBMLDocument}), knowledge of the intented SBML Level and Version help 216 * libSBML determine such things as whether it is valid to assign a 217 * particular value to an attribute. 218 <p> 219 * <p> 220 * @note The {@link Priority} construct exists only in SBML Level 3; it 221 * cannot be used in SBML Level 2 or Level 1 models. 222 */ public 223 Priority(long level, long version) throws org.sbml.libsbml.SBMLConstructorException { 224 this(libsbmlJNI.new_Priority__SWIG_0(level, version), true); 225 } 226 227 228/** 229 * Creates a new {@link Priority} object using the given {@link SBMLNamespaces} object 230 * <code>sbmlns</code>. 231 <p> 232 * <p> 233 * The {@link SBMLNamespaces} object encapsulates SBML Level/Version/namespaces 234 * information. It is used to communicate the SBML Level, Version, and (in 235 * Level 3) packages used in addition to SBML Level 3 Core. A 236 * common approach to using libSBML's {@link SBMLNamespaces} facilities is to create an 237 * {@link SBMLNamespaces} object somewhere in a program once, then hand that object 238 * as needed to object constructors that accept {@link SBMLNamespaces} as arguments. 239 <p> 240 * @param sbmlns an {@link SBMLNamespaces} object. 241 <p> 242 * <p> 243 * @throws SBMLConstructorException 244 * Thrown if the given <code>sbmlns</code> is inconsistent or incompatible 245 * with this object. 246 <p> 247 * <p> 248 * @note Attempting to add an object to an {@link SBMLDocument} having a different 249 * combination of SBML Level, Version and XML namespaces than the object 250 * itself will result in an error at the time a caller attempts to make the 251 * addition. A parent object must have compatible Level, Version and XML 252 * namespaces. (Strictly speaking, a parent may also have more XML 253 * namespaces than a child, but the reverse is not permitted.) The 254 * restriction is necessary to ensure that an SBML model has a consistent 255 * overall structure. This requires callers to manage their objects 256 * carefully, but the benefit is increased flexibility in how models can be 257 * created by permitting callers to create objects bottom-up if desired. In 258 * situations where objects are not yet attached to parents (e.g., 259 * {@link SBMLDocument}), knowledge of the intented SBML Level and Version help 260 * libSBML determine such things as whether it is valid to assign a 261 * particular value to an attribute. 262 <p> 263 * <p> 264 * @note The {@link Priority} construct exists only in SBML Level 3; it 265 * cannot be used in SBML Level 2 or Level 1 models. 266 */ public 267 Priority(SBMLNamespaces sbmlns) throws org.sbml.libsbml.SBMLConstructorException { 268 this(libsbmlJNI.new_Priority__SWIG_1(SBMLNamespaces.getCPtr(sbmlns), sbmlns), true); 269 } 270 271 272/** 273 * Copy constructor; creates a copy of this {@link Priority}. 274 <p> 275 * @param orig the object to copy. 276 */ public 277 Priority(Priority orig) throws org.sbml.libsbml.SBMLConstructorException { 278 this(libsbmlJNI.new_Priority__SWIG_2(Priority.getCPtr(orig), orig), true); 279 } 280 281 282/** 283 * Creates and returns a deep copy of this {@link Priority} object. 284 <p> 285 * @return the (deep) copy of this {@link Priority} object. 286 */ public 287 Priority cloneObject() { 288 long cPtr = libsbmlJNI.Priority_cloneObject(swigCPtr, this); 289 return (cPtr == 0) ? null : new Priority(cPtr, true); 290 } 291 292 293/** 294 * Get the mathematical formula for the priority and return it 295 * as an AST. 296 <p> 297 * @return the math of this {@link Priority}, or <code>null</code> if the math is not set. 298 */ public 299 ASTNode getMath() { 300 long cPtr = libsbmlJNI.Priority_getMath(swigCPtr, this); 301 return (cPtr == 0) ? null : new ASTNode(cPtr, false); 302 } 303 304 305/** 306 * Predicate to test whether the formula for this delay is set. 307 <p> 308 * @return <code>true</code> if the formula (meaning the <code>math</code> subelement) of 309 * this {@link Priority} is set, <code>false</code> otherwise. 310 */ public 311 boolean isSetMath() { 312 return libsbmlJNI.Priority_isSetMath(swigCPtr, this); 313 } 314 315 316/** 317 * Sets the math expression of this {@link Priority} instance to a copy of the given 318 * {@link ASTNode}. 319 <p> 320 * @param math an {@link ASTNode} representing a formula tree. 321 <p> 322 * <p> 323 * @return integer value indicating success/failure of the 324 * function. The possible values 325 * returned by this function are: 326 * <ul> 327 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 328 * <li> {@link libsbmlConstants#LIBSBML_INVALID_OBJECT LIBSBML_INVALID_OBJECT} 329 * </ul> 330 */ public 331 int setMath(ASTNode math) { 332 return libsbmlJNI.Priority_setMath(swigCPtr, this, ASTNode.getCPtr(math), math); 333 } 334 335 336/** 337 * Returns the libSBML type code of this object instance. 338 <p> 339 * <p> 340 * LibSBML attaches an identifying code to every kind of SBML object. These 341 * are integer constants known as <em>SBML type codes</em>. The names of all 342 * the codes begin with the characters <code>SBML_</code>. 343 * In the Java language interface for libSBML, the 344 * type codes are defined as static integer constants in the interface class 345 * {@link libsbmlConstants}. Note that different Level 3 346 * package plug-ins may use overlapping type codes; to identify the package 347 * to which a given object belongs, call the <code>getPackageName()</code> 348 * method on the object. 349 <p> 350 * @return the SBML type code for this object: 351 * {@link libsbmlConstants#SBML_PRIORITY SBML_PRIORITY} (default). <p> 352 * <p> 353 * @warning <span class='warning'>The specific integer values of the possible 354 * type codes may be reused by different libSBML plug-ins for SBML Level 3. 355 * packages, To fully identify the correct code, <strong>it is necessary to 356 * invoke both getTypeCode() and getPackageName()</strong>.</span> 357 <p> 358 * @see #getElementName() 359 * @see #getPackageName() 360 */ public 361 int getTypeCode() { 362 return libsbmlJNI.Priority_getTypeCode(swigCPtr, this); 363 } 364 365 366/** 367 * Returns the XML element name of this object, which for {@link Priority}, is 368 * always <code>'priority'.</code> 369 <p> 370 * @return the name of this element, i.e., <code>'priority'.</code> 371 <p> 372 * @see #getTypeCode() 373 */ public 374 String getElementName() { 375 return libsbmlJNI.Priority_getElementName(swigCPtr, this); 376 } 377 378 379/** 380 * Predicate returning <code>true</code> if all the required elements for this 381 * {@link Priority} object have been set. 382 <p> 383 * @note The required elements for a {@link Priority} object are: 384 * <ul> 385 * <li> 'math' inSBML Level 2 and Level 3 Version 1. 386 * (In SBML Level 3 Version 2+, it is no longer required.) 387 * 388 * </ul> <p> 389 * @return a boolean value indicating whether all the required 390 * elements for this object have been defined. 391 */ public 392 boolean hasRequiredElements() { 393 return libsbmlJNI.Priority_hasRequiredElements(swigCPtr, this); 394 } 395 396 397/** 398 * Finds this {@link Priority}'s {@link Event} parent and calls unsetPriority() on it, 399 * indirectly deleting itself. 400 <p> 401 * Overridden from the {@link SBase} function since the parent is not a {@link ListOf}. 402 <p> 403 * <p> 404 * @return integer value indicating success/failure of the 405 * function. The possible values 406 * returned by this function are: 407 * <ul> 408 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 409 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED} 410 * </ul> 411 */ public 412 int removeFromParentAndDelete() { 413 return libsbmlJNI.Priority_removeFromParentAndDelete(swigCPtr, this); 414 } 415 416 417/** 418 * <p> 419 * Replaces all uses of a given <code>SIdRef</code> type attribute value with another 420 * value. 421 <p> 422 * <p> 423 * In SBML, object identifiers are of a data type called <code>SId</code>. 424 * In SBML Level 3, an explicit data type called <code>SIdRef</code> was 425 * introduced for attribute values that refer to <code>SId</code> values; in 426 * previous Levels of SBML, this data type did not exist and attributes were 427 * simply described to as 'referring to an identifier', but the effective 428 * data type was the same as <code>SIdRef</code> in Level 3. These and 429 * other methods of libSBML refer to the type <code>SIdRef</code> for all 430 * Levels of SBML, even if the corresponding SBML specification did not 431 * explicitly name the data type. 432 <p> 433 * This method works by looking at all attributes and (if appropriate) 434 * mathematical formulas in MathML content, comparing the referenced 435 * identifiers to the value of <code>oldid</code>. If any matches are found, the 436 * matching values are replaced with <code>newid</code>. The method does <em>not</em> 437 * descend into child elements. 438 <p> 439 * @param oldid the old identifier. 440 * @param newid the new identifier. 441 */ public 442 void renameSIdRefs(String oldid, String newid) { 443 libsbmlJNI.Priority_renameSIdRefs(swigCPtr, this, oldid, newid); 444 } 445 446 447/** 448 * <p> 449 * Replaces all uses of a given <code>UnitSIdRef</code> type attribute value with 450 * another value. 451 <p> 452 * <p> 453 * In SBML, unit definitions have identifiers of type <code>UnitSId</code>. In 454 * SBML Level 3, an explicit data type called <code>UnitSIdRef</code> was 455 * introduced for attribute values that refer to <code>UnitSId</code> values; in 456 * previous Levels of SBML, this data type did not exist and attributes were 457 * simply described to as 'referring to a unit identifier', but the effective 458 * data type was the same as <code>UnitSIdRef</code> in Level 3. These and 459 * other methods of libSBML refer to the type <code>UnitSIdRef</code> for all 460 * Levels of SBML, even if the corresponding SBML specification did not 461 * explicitly name the data type. 462 <p> 463 * This method works by looking at all unit identifier attribute values 464 * (including, if appropriate, inside mathematical formulas), comparing the 465 * referenced unit identifiers to the value of <code>oldid</code>. If any matches 466 * are found, the matching values are replaced with <code>newid</code>. The method 467 * does <em>not</em> descend into child elements. 468 <p> 469 * @param oldid the old identifier. 470 * @param newid the new identifier. 471 */ public 472 void renameUnitSIdRefs(String oldid, String newid) { 473 libsbmlJNI.Priority_renameUnitSIdRefs(swigCPtr, this, oldid, newid); 474 } 475 476 477/** * @internal */ public 478 void replaceSIDWithFunction(String id, ASTNode function) { 479 libsbmlJNI.Priority_replaceSIDWithFunction(swigCPtr, this, id, ASTNode.getCPtr(function), function); 480 } 481 482}