001/* ---------------------------------------------------------------------------- 002 * This file was automatically generated by SWIG (http://www.swig.org). 003 * Version 3.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 * <span class="pkg-marker pkg-color-comp"><a href="group__comp.html">comp</a></span> 013 Indicates an object replaces another. 014 <p> 015 * The {@link ReplacedElement} class was introduced by the SBML Level 3 <a href='../../../extensions-summary.html#comp'>Hierarchical Model Composition</a> (“comp”) package to allow submodel elements to be 016 * replaced, but still allow references to those elements to be valid. A 017 * {@link ReplacedElement} object is essentially a pointer to a submodel object that 018 * should be considered 'replaced'. The object holding the {@link ReplacedElement} 019 * instance is the one doing the replacing; the object pointed to by the 020 * {@link ReplacedElement} object is the object being replaced. 021 <p> 022 * A replacement implies that dependencies involving the replaced object 023 * must be updated: all references to the replaced object elsewhere in the 024 * model are taken to refer to the replacement object instead. For 025 * example, if one species replaces another, then any reference to the 026 * original species in mathematical formulas, or lists of reactants or 027 * products or modifiers in reactions, or initial assignments, or any other 028 * SBML construct, are taken to refer to the replacement species, with its 029 * value possibly modified by either this object's 'conversionFactor' 030 * attribute or the relevant submodel's conversion factors. Moreover, any 031 * annotations that refer to the 032 * replaced species' 'metaid' value must be made to refer to the 033 * replacement species' 'metaid' value instead; and anything else 034 * that referred either to an object identifier (i.e., attributes such as 035 * the 'id' attribute whose types inherit from the SId 036 * primitive data type) or the meta identifier (i.e., the 'metaid' 037 * attribute or any other attribute that inherits from the ID primitive 038 * data type) must be made to refer to the replacement species object 039 * instead. 040 <p> 041 * It is worth noting that local parameters (inside {@link Reaction} objects) pose an 042 * interesting edge case for these rules. In order to determine which element 043 * is pointed to by a <code><cn></code> element within the 044 * <code><math></code> element of a {@link KineticLaw} object, it is necessary 045 * to examine the local parameters of that kinetic law's parent {@link Reaction} 046 * object. Whether the <code><cn></code> element is considered to 047 * point to something new, then, depends on whether it pointed to the local 048 * parameter and whether that local parameter was replaced, even if the text 049 * of the element matched the SId value of another element in the model. 050 * Note that local parameters may only effectively be replaced by global 051 * parameters, since references to its SId are only valid from within the 052 * {@link Reaction} element to which it belongs. 053 <p> 054 * When referencing an element within the {@link Submodel} pointed to by the 055 * 'submodelRef' attribute (defined in libSBML in the {@link Replacing} class), 056 * any of the four attributes inherited from 057 * {@link SBaseRef} for the purpose may be used (portRef, idRef, unitRef, or 058 * metaIdRef), or a new optional attribute 'deletion' may be used. This 059 * attribute must be the identifier of a {@link Deletion} 060 * object in the parent {@link Model} of the {@link ReplacedElement} (i.e., the value of 061 * some {@link Deletion} object's 'id' attribute). When 'deletion' is 062 * set, it means the {@link ReplacedElement} object is actually an annotation to 063 * indicate that the replacement object replaces something deleted 064 * from a submodel. The use of the 'deletion' attribute overrides 065 * the use of the attributes inherited from SBaseRef: instead of using, 066 * e.g., 'portRef' or 'idRef', the {@link ReplacedElement} instance 067 * sets 'deletion' to the identifier of the {@link Deletion} object. In 068 * addition, the referenced {@link Deletion} must be a child of the {@link Submodel} 069 * referenced by the 'submodelRef' attribute. 070 <p> 071 * The use of {@link ReplacedElement} objects to refer to deletions has no effect 072 * on the composition of models or the mathematical properties of the 073 * result. It serves instead to help record the decision-making process 074 * that lead to a given model. It can be particularly useful for 075 * visualization purposes, as well as to serve as scaffolding where other 076 * types of annotations can be added using the normal Annotation 077 * subcomponents available on all {@link SBase} objects in SBML. 078 <p> 079 * As with the {@link Submodel} class, it may be that the units of the replaced 080 * element may not match the units of the replacement element. In this case, 081 * the optional 'conversionFactor' attribute may be used. This attribute, if 082 * present, defines how to transform or rescale the replaced object's value 083 * so that it is appropriate for the new contexts in which the object 084 * appears. This attribute takes a value of type SIdRef, and 085 * the value must refer to a {@link Parameter} object instance defined in the 086 * model. This parameter then acts as a conversion factor. 087 <p> 088 * The value of the conversion factor should be defined such that a single 089 * unit of the replaced element multiplied by the conversion factor should 090 * equal a single unit of the replacement element, and the units of the 091 * conversion factor should be commensurate with that transformation. The 092 * referenced {@link Parameter} may be non-constant, particularly if a {@link Species} is 093 * replaced by a {@link Species} with a different 'hasOnlySubstanceUnits' 094 * attribute value, thus changing amount to concentration, or visa versa. 095 */ 096 097public class ReplacedElement extends Replacing { 098 private long swigCPtr; 099 100 protected ReplacedElement(long cPtr, boolean cMemoryOwn) 101 { 102 super(libsbmlJNI.ReplacedElement_SWIGUpcast(cPtr), cMemoryOwn); 103 swigCPtr = cPtr; 104 } 105 106 protected static long getCPtr(ReplacedElement obj) 107 { 108 return (obj == null) ? 0 : obj.swigCPtr; 109 } 110 111 protected static long getCPtrAndDisown (ReplacedElement obj) 112 { 113 long ptr = 0; 114 115 if (obj != null) 116 { 117 ptr = obj.swigCPtr; 118 obj.swigCMemOwn = false; 119 } 120 121 return ptr; 122 } 123 124 protected void finalize() { 125 delete(); 126 } 127 128 public synchronized void delete() { 129 if (swigCPtr != 0) { 130 if (swigCMemOwn) { 131 swigCMemOwn = false; 132 libsbmlJNI.delete_ReplacedElement(swigCPtr); 133 } 134 swigCPtr = 0; 135 } 136 super.delete(); 137 } 138 139 140/** 141 * Creates a new {@link ReplacedElement} with the given level, version, and package 142 * version. 143 <p> 144 * @param level the SBML Level. 145 * @param version the Version within the SBML Level. 146 * @param pkgVersion the version of the package. 147 <p> 148 * <p> 149 * @note Attempting to add an object to an {@link SBMLDocument} having a different 150 * combination of SBML Level, Version and XML namespaces than the object 151 * itself will result in an error at the time a caller attempts to make the 152 * addition. A parent object must have compatible Level, Version and XML 153 * namespaces. (Strictly speaking, a parent may also have more XML 154 * namespaces than a child, but the reverse is not permitted.) The 155 * restriction is necessary to ensure that an SBML model has a consistent 156 * overall structure. This requires callers to manage their objects 157 * carefully, but the benefit is increased flexibility in how models can be 158 * created by permitting callers to create objects bottom-up if desired. In 159 * situations where objects are not yet attached to parents (e.g., 160 * {@link SBMLDocument}), knowledge of the intented SBML Level and Version help 161 * libSBML determine such things as whether it is valid to assign a 162 * particular value to an attribute. For packages, this means that the 163 * parent object to which this package element is being added must have 164 * been created with the package namespace, or that the package namespace 165 * was added to it, even if that parent is not a package object itself. 166 */ public 167 ReplacedElement(long level, long version, long pkgVersion) throws org.sbml.libsbml.SBMLConstructorException { 168 this(libsbmlJNI.new_ReplacedElement__SWIG_0(level, version, pkgVersion), true); 169 } 170 171 172/** 173 * Creates a new {@link ReplacedElement} with the given level, version, and package 174 * version. 175 <p> 176 * @param level the SBML Level. 177 * @param version the Version within the SBML Level. 178 * @param pkgVersion the version of the package. 179 <p> 180 * <p> 181 * @note Attempting to add an object to an {@link SBMLDocument} having a different 182 * combination of SBML Level, Version and XML namespaces than the object 183 * itself will result in an error at the time a caller attempts to make the 184 * addition. A parent object must have compatible Level, Version and XML 185 * namespaces. (Strictly speaking, a parent may also have more XML 186 * namespaces than a child, but the reverse is not permitted.) The 187 * restriction is necessary to ensure that an SBML model has a consistent 188 * overall structure. This requires callers to manage their objects 189 * carefully, but the benefit is increased flexibility in how models can be 190 * created by permitting callers to create objects bottom-up if desired. In 191 * situations where objects are not yet attached to parents (e.g., 192 * {@link SBMLDocument}), knowledge of the intented SBML Level and Version help 193 * libSBML determine such things as whether it is valid to assign a 194 * particular value to an attribute. For packages, this means that the 195 * parent object to which this package element is being added must have 196 * been created with the package namespace, or that the package namespace 197 * was added to it, even if that parent is not a package object itself. 198 */ public 199 ReplacedElement(long level, long version) throws org.sbml.libsbml.SBMLConstructorException { 200 this(libsbmlJNI.new_ReplacedElement__SWIG_1(level, version), true); 201 } 202 203 204/** 205 * Creates a new {@link ReplacedElement} with the given level, version, and package 206 * version. 207 <p> 208 * @param level the SBML Level. 209 * @param version the Version within the SBML Level. 210 * @param pkgVersion the version of the package. 211 <p> 212 * <p> 213 * @note Attempting to add an object to an {@link SBMLDocument} having a different 214 * combination of SBML Level, Version and XML namespaces than the object 215 * itself will result in an error at the time a caller attempts to make the 216 * addition. A parent object must have compatible Level, Version and XML 217 * namespaces. (Strictly speaking, a parent may also have more XML 218 * namespaces than a child, but the reverse is not permitted.) The 219 * restriction is necessary to ensure that an SBML model has a consistent 220 * overall structure. This requires callers to manage their objects 221 * carefully, but the benefit is increased flexibility in how models can be 222 * created by permitting callers to create objects bottom-up if desired. In 223 * situations where objects are not yet attached to parents (e.g., 224 * {@link SBMLDocument}), knowledge of the intented SBML Level and Version help 225 * libSBML determine such things as whether it is valid to assign a 226 * particular value to an attribute. For packages, this means that the 227 * parent object to which this package element is being added must have 228 * been created with the package namespace, or that the package namespace 229 * was added to it, even if that parent is not a package object itself. 230 */ public 231 ReplacedElement(long level) throws org.sbml.libsbml.SBMLConstructorException { 232 this(libsbmlJNI.new_ReplacedElement__SWIG_2(level), true); 233 } 234 235 236/** 237 * Creates a new {@link ReplacedElement} with the given level, version, and package 238 * version. 239 <p> 240 * @param level the SBML Level. 241 * @param version the Version within the SBML Level. 242 * @param pkgVersion the version of the package. 243 <p> 244 * <p> 245 * @note Attempting to add an object to an {@link SBMLDocument} having a different 246 * combination of SBML Level, Version and XML namespaces than the object 247 * itself will result in an error at the time a caller attempts to make the 248 * addition. A parent object must have compatible Level, Version and XML 249 * namespaces. (Strictly speaking, a parent may also have more XML 250 * namespaces than a child, but the reverse is not permitted.) The 251 * restriction is necessary to ensure that an SBML model has a consistent 252 * overall structure. This requires callers to manage their objects 253 * carefully, but the benefit is increased flexibility in how models can be 254 * created by permitting callers to create objects bottom-up if desired. In 255 * situations where objects are not yet attached to parents (e.g., 256 * {@link SBMLDocument}), knowledge of the intented SBML Level and Version help 257 * libSBML determine such things as whether it is valid to assign a 258 * particular value to an attribute. For packages, this means that the 259 * parent object to which this package element is being added must have 260 * been created with the package namespace, or that the package namespace 261 * was added to it, even if that parent is not a package object itself. 262 */ public 263 ReplacedElement() throws org.sbml.libsbml.SBMLConstructorException { 264 this(libsbmlJNI.new_ReplacedElement__SWIG_3(), true); 265 } 266 267 268/** 269 * Creates a new {@link ReplacedElement} with the given {@link CompPkgNamespaces} object. 270 <p> 271 * <p> 272 * The package namespaces object used in this constructor is derived from a 273 * {@link SBMLNamespaces} object, which encapsulates SBML Level/Version/namespaces 274 * information. It is used to communicate the SBML Level, Version, and 275 * package version and name information used in addition to SBML Level 3 Core. A 276 * common approach to using libSBML's {@link SBMLNamespaces} facilities is to create an 277 * package namespace object somewhere in a program once, then hand that object 278 * as needed to object constructors of that package that accept it as and 279 * argument, such as this one. 280 <p> 281 * @param compns the {@link CompPkgNamespaces} object. 282 <p> 283 * <p> 284 * @note Attempting to add an object to an {@link SBMLDocument} having a different 285 * combination of SBML Level, Version and XML namespaces than the object 286 * itself will result in an error at the time a caller attempts to make the 287 * addition. A parent object must have compatible Level, Version and XML 288 * namespaces. (Strictly speaking, a parent may also have more XML 289 * namespaces than a child, but the reverse is not permitted.) The 290 * restriction is necessary to ensure that an SBML model has a consistent 291 * overall structure. This requires callers to manage their objects 292 * carefully, but the benefit is increased flexibility in how models can be 293 * created by permitting callers to create objects bottom-up if desired. In 294 * situations where objects are not yet attached to parents (e.g., 295 * {@link SBMLDocument}), knowledge of the intented SBML Level and Version help 296 * libSBML determine such things as whether it is valid to assign a 297 * particular value to an attribute. For packages, this means that the 298 * parent object to which this package element is being added must have 299 * been created with the package namespace, or that the package namespace 300 * was added to it, even if that parent is not a package object itself. 301 */ public 302 ReplacedElement(CompPkgNamespaces compns) throws org.sbml.libsbml.SBMLConstructorException { 303 this(libsbmlJNI.new_ReplacedElement__SWIG_4(CompPkgNamespaces.getCPtr(compns), compns), true); 304 } 305 306 307/** 308 * Copy constructor. 309 <p> 310 * @param source the instance to copy. 311 */ public 312 ReplacedElement(ReplacedElement source) throws org.sbml.libsbml.SBMLConstructorException { 313 this(libsbmlJNI.new_ReplacedElement__SWIG_5(ReplacedElement.getCPtr(source), source), true); 314 } 315 316 317/** 318 * Creates and returns a deep copy of this {@link ReplacedElement} object. 319 <p> 320 * @return a (deep) copy of this {@link ReplacedElement} object. 321 */ public 322 SBase cloneObject() { 323 long cPtr = libsbmlJNI.ReplacedElement_cloneObject(swigCPtr, this); 324 return (cPtr == 0) ? null : new ReplacedElement(cPtr, true); 325 } 326 327 328/** 329 * Returns the value of the 'conversionFactor' attribute of this {@link ReplacedElement}. 330 <p> 331 * @return the value of the 'conversionFactor' attribute of this {@link ReplacedElement}. 332 */ public 333 String getConversionFactor() { 334 return libsbmlJNI.ReplacedElement_getConversionFactor(swigCPtr, this); 335 } 336 337 338/** 339 * Predicate returning <code>true</code> or <code>false</code> depending on whether this 340 * {@link ReplacedElement}'s 'conversionFactor' attribute has been set. 341 <p> 342 * @return <code>true</code> if this {@link ReplacedElement}'s 'conversionFactor' attribute has been set, 343 * otherwise <code>false</code> is returned. 344 */ public 345 boolean isSetConversionFactor() { 346 return libsbmlJNI.ReplacedElement_isSetConversionFactor(swigCPtr, this); 347 } 348 349 350/** 351 * Sets the value of the 'conversionFactor' attribute of this {@link ReplacedElement}. 352 <p> 353 * <p> 354 * @return integer value indicating success/failure of the 355 * function. The possible values 356 * returned by this function are: 357 * <ul> 358 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 359 * <li> {@link libsbmlConstants#LIBSBML_INVALID_ATTRIBUTE_VALUE LIBSBML_INVALID_ATTRIBUTE_VALUE} 360 * </ul> 361 */ public 362 int setConversionFactor(String id) { 363 return libsbmlJNI.ReplacedElement_setConversionFactor(swigCPtr, this, id); 364 } 365 366 367/** 368 * Unsets the value of the 'conversionFactor' attribute of this {@link ReplacedElement}. 369 <p> 370 * <p> 371 * @return integer value indicating success/failure of the 372 * function. The possible values 373 * returned by this function are: 374 * <ul> 375 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 376 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED} 377 * </ul> 378 */ public 379 int unsetConversionFactor() { 380 return libsbmlJNI.ReplacedElement_unsetConversionFactor(swigCPtr, this); 381 } 382 383 384/** 385 * Returns the value of the 'deletion' attribute of this {@link ReplacedElement}. 386 <p> 387 * @return the value of the 'deletion' attribute of this {@link ReplacedElement}. 388 */ public 389 String getDeletion() { 390 return libsbmlJNI.ReplacedElement_getDeletion(swigCPtr, this); 391 } 392 393 394/** 395 * Predicate returning <code>true</code> or <code>false</code> depending on whether this 396 * {@link SBaseRef}'s 'deletion' attribute has been set. 397 <p> 398 * @return <code>true</code> if this {@link ReplacedElement}'s 'deletion' attribute has been set, 399 * otherwise <code>false</code> is returned. 400 */ public 401 boolean isSetDeletion() { 402 return libsbmlJNI.ReplacedElement_isSetDeletion(swigCPtr, this); 403 } 404 405 406/** 407 * Sets the value of the 'deletion' attribute of this {@link ReplacedElement}. 408 <p> 409 * This method fails if the id is not a valid syntax for an SIdRef ({@link libsbmlConstants#LIBSBML_INVALID_ATTRIBUTE_VALUE LIBSBML_INVALID_ATTRIBUTE_VALUE}), or if the {@link SBaseRef} already 410 * points to an element of the submodel using a different interface ({@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED}). A {@link ReplacedElement} must use exactly 411 * one method to point to a submodel element: deletion, port, idRef, 412 * unitRef, or metaIdRef. 413 <p> 414 * <p> 415 * @return integer value indicating success/failure of the 416 * function. The possible values 417 * returned by this function are: 418 * <ul> 419 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 420 * <li> {@link libsbmlConstants#LIBSBML_INVALID_ATTRIBUTE_VALUE LIBSBML_INVALID_ATTRIBUTE_VALUE} 421 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED} 422 * </ul> 423 */ public 424 int setDeletion(String id) { 425 return libsbmlJNI.ReplacedElement_setDeletion(swigCPtr, this, id); 426 } 427 428 429/** 430 * Unsets the value of the 'deletion' attribute of this {@link ReplacedElement}. 431 <p> 432 * <p> 433 * @return integer value indicating success/failure of the 434 * function. The possible values 435 * returned by this function are: 436 * <ul> 437 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 438 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED} 439 * </ul> 440 */ public 441 int unsetDeletion() { 442 return libsbmlJNI.ReplacedElement_unsetDeletion(swigCPtr, this); 443 } 444 445 446/** 447 * Returns the XML element name of 448 * this SBML object. 449 <p> 450 * @return the name of this element, as a text string. 451 */ public 452 String getElementName() { 453 return libsbmlJNI.ReplacedElement_getElementName(swigCPtr, this); 454 } 455 456 457/** 458 * Returns how many elements are being referred to by this {@link ReplacedElement}. A 459 * valid {@link ReplacedElement} will have exactly one. Possible referents are deletion, 460 * port, idRef, unitRef, and metaIdRef. 461 <p> 462 * @return integer value between 0 and 5: the number of different ways this 463 * element points to its referent. 464 */ public 465 int getNumReferents() { 466 return libsbmlJNI.ReplacedElement_getNumReferents(swigCPtr, this); 467 } 468 469 470/** 471 * Returns the libSBML type code of this object instance. 472 <p> 473 * <p> 474 * LibSBML attaches an identifying code to every kind of SBML object. These 475 * are integer constants known as <em>SBML type codes</em>. The names of all 476 * the codes begin with the characters <code>SBML_</code>. 477 * In the Java language interface for libSBML, the 478 * type codes are defined as static integer constants in the interface class 479 * {@link libsbmlConstants}. Note that different Level 3 480 * package plug-ins may use overlapping type codes; to identify the package 481 * to which a given object belongs, call the 482 * <code>{@link SBase#getPackageName()} 483 * </code> 484 * method on the object. 485 <p> 486 * @return the SBML type code for this object: 487 * {@link libsbmlConstants#SBML_COMP_REPLACEDELEMENT SBML_COMP_REPLACEDELEMENT}. 488 <p> 489 * <p> 490 * @warning <span class='warning'>The specific integer values of the possible 491 * type codes may be reused by different libSBML plug-ins for SBML Level 3. 492 * packages, To fully identify the correct code, <strong>it is necessary to 493 * invoke both getTypeCode() and getPackageName()</strong>.</span> 494 <p> 495 * @see #getElementName() 496 * @see #getPackageName() 497 */ public 498 int getTypeCode() { 499 return libsbmlJNI.ReplacedElement_getTypeCode(swigCPtr, this); 500 } 501 502 503/** 504 * <p> 505 * Replaces all uses of a given <code>SIdRef</code> type attribute value with another 506 * value. 507 <p> 508 * <p> 509 * In SBML, object identifiers are of a data type called <code>SId</code>. 510 * In SBML Level 3, an explicit data type called <code>SIdRef</code> was 511 * introduced for attribute values that refer to <code>SId</code> values; in 512 * previous Levels of SBML, this data type did not exist and attributes were 513 * simply described to as 'referring to an identifier', but the effective 514 * data type was the same as <code>SIdRef</code> in Level 3. These and 515 * other methods of libSBML refer to the type <code>SIdRef</code> for all 516 * Levels of SBML, even if the corresponding SBML specification did not 517 * explicitly name the data type. 518 <p> 519 * This method works by looking at all attributes and (if appropriate) 520 * mathematical formulas in MathML content, comparing the referenced 521 * identifiers to the value of <code>oldid</code>. If any matches are found, the 522 * matching values are replaced with <code>newid</code>. The method does <em>not</em> 523 * descend into child elements. 524 <p> 525 * @param oldid the old identifier. 526 * @param newid the new identifier. 527 */ public 528 void renameSIdRefs(String oldid, String newid) { 529 libsbmlJNI.ReplacedElement_renameSIdRefs(swigCPtr, this, oldid, newid); 530 } 531 532 533/** 534 * Finds the {@link SBase} object this {@link ReplacedElement} object points to, if any. 535 */ public 536 SBase getReferencedElementFrom(Model model) { 537 return libsbml.DowncastSBase(libsbmlJNI.ReplacedElement_getReferencedElementFrom(swigCPtr, this, Model.getCPtr(model), model), false); 538} 539 540}