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