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