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 * <span class="pkg-marker pkg-color-comp"><a href="group__comp.html">comp</a></span> 013 Implementation of the ReplacedElement construct from the 014 * “comp” package. 015 <p> 016 * The {@link ReplacedElement} class was introduced by the SBML Level 3 017 * 'Hierarchical Model Composition' package 018 * (“comp”) to allow submodel elements to be replaced, but still 019 * allow references to those elements to be valid. A {@link ReplacedElement} object 020 * is essentially a pointer to a submodel object that should be considered 021 * 'replaced'. The object holding the {@link ReplacedElement} instance is the one 022 * doing the replacing; the object pointed to by the {@link ReplacedElement} object 023 * is the object being replaced. 024 <p> 025 * A replacement implies that dependencies involving the replaced object 026 * must be updated: all references to the replaced object elsewhere in the 027 * model are taken to refer to the replacement object instead. For 028 * example, if one species replaces another, then any reference to the 029 * original species in mathematical formulas, or lists of reactants or 030 * products or modifiers in reactions, or initial assignments, or any other 031 * SBML construct, are taken to refer to the replacement species, with its 032 * value possibly modified by either this object's 'conversionFactor' 033 * attribute or the relevant submodel's conversion factors. Moreover, any 034 * annotations that refer to the 035 * replaced species' 'metaid' value must be made to refer to the 036 * replacement species' 'metaid' value instead; and anything else 037 * that referred either to an object identifier (i.e., attributes such as 038 * the 'id' attribute whose types inherit from the SId 039 * primitive data type) or the meta identifier (i.e., the 'metaid' 040 * attribute or any other attribute that inherits from the ID primitive 041 * data type) must be made to refer to the replacement species object 042 * instead. 043 <p> 044 * It is worth noting that local parameters (inside {@link Reaction} objects) pose an 045 * interesting edge case for these rules. In order to determine which element 046 * is pointed to by a <code><cn></code> element within the 047 * <code><math></code> element of a {@link KineticLaw} object, it is necessary 048 * to examine the local parameters of that kinetic law's parent {@link Reaction} 049 * object. Whether the <code><cn></code> element is considered to 050 * point to something new, then, depends on whether it pointed to the local 051 * parameter and whether that local parameter was replaced, even if the text 052 * of the element matched the SId value of another element in the model. 053 * Note that local parameters may only effectively be replaced by global 054 * parameters, since references to its SId are only valid from within the 055 * {@link Reaction} element to which it belongs. 056 <p> 057 * When referencing an element within the {@link Submodel} pointed to by the 058 * 'submodelRef' attribute (defined in libSBML in the {@link Replacing} class), 059 * any of the four attributes inherited from 060 * {@link SBaseRef} for the purpose may be used (portRef, idRef, unitRef, or 061 * metaIdRef), or a new optional attribute 'deletion' may be used. This 062 * attribute must be the identifier of a {@link Deletion} 063 * object in the parent {@link Model} of the {@link ReplacedElement} (i.e., the value of 064 * some {@link Deletion} object's 'id' attribute). When 'deletion' is 065 * set, it means the {@link ReplacedElement} object is actually an annotation to 066 * indicate that the replacement object replaces something deleted 067 * from a submodel. The use of the 'deletion' attribute overrides 068 * the use of the attributes inherited from SBaseRef: instead of using, 069 * e.g., 'portRef' or 'idRef', the {@link ReplacedElement} instance 070 * sets 'deletion' to the identifier of the {@link Deletion} object. In 071 * addition, the referenced {@link Deletion} must be a child of the {@link Submodel} 072 * referenced by the 'submodelRef' attribute. 073 <p> 074 * The use of {@link ReplacedElement} objects to refer to deletions has no effect 075 * on the composition of models or the mathematical properties of the 076 * result. It serves instead to help record the decision-making process 077 * that lead to a given model. It can be particularly useful for 078 * visualization purposes, as well as to serve as scaffolding where other 079 * types of annotations can be added using the normal Annotation 080 * subcomponents available on all {@link SBase} objects in SBML. 081 <p> 082 * As with the {@link Submodel} class, it may be that the units of the replaced 083 * element may not match the units of the replacement element. In this case, 084 * the optional 'conversionFactor' attribute may be used. This attribute, if 085 * present, defines how to transform or rescale the replaced object's value 086 * so that it is appropriate for the new contexts in which the object 087 * appears. This attribute takes a value of type SIdRef, and 088 * the value must refer to a {@link Parameter} object instance defined in the 089 * model. This parameter then acts as a conversion factor. 090 <p> 091 * The value of the conversion factor should be defined such that a single 092 * unit of the replaced element multiplied by the conversion factor should 093 * equal a single unit of the replacement element, and the units of the 094 * conversion factor should be commensurate with that transformation. The 095 * referenced {@link Parameter} may be non-constant, particularly if a {@link Species} is 096 * replaced by a {@link Species} with a different 'hasOnlySubstanceUnits' 097 * attribute value, thus changing amount to concentration, or visa versa. 098 */ 099 100public class ReplacedElement extends Replacing { 101 private long swigCPtr; 102 103 protected ReplacedElement(long cPtr, boolean cMemoryOwn) 104 { 105 super(libsbmlJNI.ReplacedElement_SWIGUpcast(cPtr), cMemoryOwn); 106 swigCPtr = cPtr; 107 } 108 109 protected static long getCPtr(ReplacedElement obj) 110 { 111 return (obj == null) ? 0 : obj.swigCPtr; 112 } 113 114 protected static long getCPtrAndDisown (ReplacedElement obj) 115 { 116 long ptr = 0; 117 118 if (obj != null) 119 { 120 ptr = obj.swigCPtr; 121 obj.swigCMemOwn = false; 122 } 123 124 return ptr; 125 } 126 127 protected void finalize() { 128 delete(); 129 } 130 131 public synchronized void delete() { 132 if (swigCPtr != 0) { 133 if (swigCMemOwn) { 134 swigCMemOwn = false; 135 libsbmlJNI.delete_ReplacedElement(swigCPtr); 136 } 137 swigCPtr = 0; 138 } 139 super.delete(); 140 } 141 142 143/** 144 * Creates a new {@link ReplacedElement} with the given level, version, and package 145 * version. 146 <p> 147 * @param level the SBML Level 148 * @param version the Version within the SBML Level 149 * @param pkgVersion the version of the package 150 */ public 151 ReplacedElement(long level, long version, long pkgVersion) throws org.sbml.libsbml.SBMLConstructorException { 152 this(libsbmlJNI.new_ReplacedElement__SWIG_0(level, version, pkgVersion), true); 153 } 154 155 156/** 157 * Creates a new {@link ReplacedElement} with the given level, version, and package 158 * version. 159 <p> 160 * @param level the SBML Level 161 * @param version the Version within the SBML Level 162 * @param pkgVersion the version of the package 163 */ public 164 ReplacedElement(long level, long version) throws org.sbml.libsbml.SBMLConstructorException { 165 this(libsbmlJNI.new_ReplacedElement__SWIG_1(level, version), true); 166 } 167 168 169/** 170 * Creates a new {@link ReplacedElement} with the given level, version, and package 171 * version. 172 <p> 173 * @param level the SBML Level 174 * @param version the Version within the SBML Level 175 * @param pkgVersion the version of the package 176 */ public 177 ReplacedElement(long level) throws org.sbml.libsbml.SBMLConstructorException { 178 this(libsbmlJNI.new_ReplacedElement__SWIG_2(level), true); 179 } 180 181 182/** 183 * Creates a new {@link ReplacedElement} with the given level, version, and package 184 * version. 185 <p> 186 * @param level the SBML Level 187 * @param version the Version within the SBML Level 188 * @param pkgVersion the version of the package 189 */ public 190 ReplacedElement() throws org.sbml.libsbml.SBMLConstructorException { 191 this(libsbmlJNI.new_ReplacedElement__SWIG_3(), true); 192 } 193 194 195/** 196 * Creates a new {@link ReplacedElement} with the given {@link CompPkgNamespaces} object. 197 <p> 198 * @param compns the namespace to use 199 */ public 200 ReplacedElement(CompPkgNamespaces compns) throws org.sbml.libsbml.SBMLConstructorException { 201 this(libsbmlJNI.new_ReplacedElement__SWIG_4(CompPkgNamespaces.getCPtr(compns), compns), true); 202 } 203 204 205/** 206 * Copy constructor. 207 */ public 208 ReplacedElement(ReplacedElement source) throws org.sbml.libsbml.SBMLConstructorException { 209 this(libsbmlJNI.new_ReplacedElement__SWIG_5(ReplacedElement.getCPtr(source), source), true); 210 } 211 212 213/** 214 * Creates and returns a deep copy of this {@link ReplacedElement} object. 215 <p> 216 * @return a (deep) copy of this {@link ReplacedElement} object 217 */ public 218 SBase cloneObject() { 219 long cPtr = libsbmlJNI.ReplacedElement_cloneObject(swigCPtr, this); 220 return (cPtr == 0) ? null : new ReplacedElement(cPtr, true); 221 } 222 223 224/** 225 * Returns the value of the 'conversionFactor' attribute of this {@link ReplacedElement}. 226 <p> 227 * @return the value of the 'conversionFactor' attribute of this {@link ReplacedElement}. 228 */ public 229 String getConversionFactor() { 230 return libsbmlJNI.ReplacedElement_getConversionFactor(swigCPtr, this); 231 } 232 233 234/** 235 * Predicate returning <code>true</code> or <code>false</code> depending on whether this 236 * {@link ReplacedElement}'s 'conversionFactor' attribute has been set. 237 <p> 238 * @return <code>true</code> if this {@link ReplacedElement}'s 'conversionFactor' attribute has been set, 239 * otherwise <code>false</code> is returned. 240 */ public 241 boolean isSetConversionFactor() { 242 return libsbmlJNI.ReplacedElement_isSetConversionFactor(swigCPtr, this); 243 } 244 245 246/** 247 * Sets the value of the 'conversionFactor' attribute of this {@link ReplacedElement}. 248 <p> 249 * @return integer value indicating success/failure of the 250 * operation. The possible return values are: 251 * <ul> 252 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS } 253 * <li> {@link libsbmlConstants#LIBSBML_INVALID_ATTRIBUTE_VALUE LIBSBML_INVALID_ATTRIBUTE_VALUE } 254 * </ul> 255 */ public 256 int setConversionFactor(String id) { 257 return libsbmlJNI.ReplacedElement_setConversionFactor(swigCPtr, this, id); 258 } 259 260 261/** 262 * Unsets the value of the 'conversionFactor' attribute of this {@link ReplacedElement}. 263 <p> 264 * @return integer value indicating success/failure of the 265 * operation. The possible return values are: 266 * <ul> 267 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS } 268 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED } 269 * </ul> 270 */ public 271 int unsetConversionFactor() { 272 return libsbmlJNI.ReplacedElement_unsetConversionFactor(swigCPtr, this); 273 } 274 275 276/** 277 * Returns the value of the 'deletion' attribute of this {@link ReplacedElement}. 278 <p> 279 * @return the value of the 'deletion' attribute of this {@link ReplacedElement}. 280 */ public 281 String getDeletion() { 282 return libsbmlJNI.ReplacedElement_getDeletion(swigCPtr, this); 283 } 284 285 286/** 287 * Predicate returning <code>true</code> or <code>false</code> depending on whether this 288 * {@link SBaseRef}'s 'deletion' attribute has been set. 289 <p> 290 * @return <code>true</code> if this {@link ReplacedElement}'s 'deletion' attribute has been set, 291 * otherwise <code>false</code> is returned. 292 */ public 293 boolean isSetDeletion() { 294 return libsbmlJNI.ReplacedElement_isSetDeletion(swigCPtr, this); 295 } 296 297 298/** 299 * Sets the value of the 'deletion' attribute of this {@link ReplacedElement}. 300 <p> 301 * This method fails if the id is not a valid syntax for an SIdRef ({@link 302 * libsbmlConstants#LIBSBML_INVALID_ATTRIBUTE_VALUE 303 * LIBSBML_INVALID_ATTRIBUTE_VALUE }), or if the {@link SBaseRef} already 304 * points to an element of the submodel using a different interface ({@link 305 * libsbmlConstants#LIBSBML_OPERATION_FAILED 306 * LIBSBML_OPERATION_FAILED }). A {@link ReplacedElement} must use exactly 307 * one method to point to a submodel element: deletion, port, idRef, 308 * unitRef, or metaIdRef. 309 <p> 310 * @return integer value indicating success/failure of the 311 * operation. The possible return values are: 312 * <ul> 313 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS } 314 * <li> {@link libsbmlConstants#LIBSBML_INVALID_ATTRIBUTE_VALUE LIBSBML_INVALID_ATTRIBUTE_VALUE } 315 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED } 316 * </ul> 317 */ public 318 int setDeletion(String id) { 319 return libsbmlJNI.ReplacedElement_setDeletion(swigCPtr, this, id); 320 } 321 322 323/** 324 * Unsets the value of the 'deletion' attribute of this {@link ReplacedElement}. 325 <p> 326 * @return integer value indicating success/failure of the 327 * operation. The possible return values are: 328 * <ul> 329 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS } 330 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED } 331 * </ul> 332 */ public 333 int unsetDeletion() { 334 return libsbmlJNI.ReplacedElement_unsetDeletion(swigCPtr, this); 335 } 336 337 338/** 339 * Returns the XML element name of 340 * this SBML object. 341 <p> 342 * @return the string of the name of this element. 343 */ public 344 String getElementName() { 345 return libsbmlJNI.ReplacedElement_getElementName(swigCPtr, this); 346 } 347 348 349/** 350 * Returns how many elements are being referred to by this {@link ReplacedElement}. A 351 * valid {@link ReplacedElement} will have exactly one. Possible referents are deletion, 352 * port, idRef, unitRef, and metaIdRef. 353 <p> 354 * @return integer value between 0 and 5: the number of different ways this 355 * element points to its referent. 356 */ public 357 int getNumReferents() { 358 return libsbmlJNI.ReplacedElement_getNumReferents(swigCPtr, this); 359 } 360 361 362/** 363 * Returns the libSBML type code of this object instance. 364 <p> 365 * <p> 366 * LibSBML attaches an identifying code to every kind of SBML object. These 367 * are integer constants known as <em>SBML type codes</em>. The names of all 368 * the codes begin with the characters “<code>SBML_</code>”. 369 * In the Java language interface for libSBML, the 370 * type codes are defined as static integer constants in the interface class 371 * {@link libsbmlConstants}. Note that different Level 3 372 * package plug-ins may use overlapping type codes; to identify the package 373 * to which a given object belongs, call the <code>getPackageName()</code> 374 * method on the object. 375 <p> 376 * @return the SBML type code for this object: 377 * {@link libsbmlConstants#SBML_COMP_REPLACEDELEMENT SBML_COMP_REPLACEDELEMENT} 378 <p> 379 * <p> 380 * @warning <span class='warning'>The specific integer values of the possible 381 * type codes may be reused by different Level 3 package plug-ins. 382 * Thus, to identifiy the correct code, <strong>it is necessary to invoke 383 * both getTypeCode() and getPackageName()</strong>.</span> 384 <p> 385 * @see #getElementName() 386 * @see #getPackageName() 387 */ public 388 int getTypeCode() { 389 return libsbmlJNI.ReplacedElement_getTypeCode(swigCPtr, this); 390 } 391 392 393/** 394 * Renames all the SIdRef attributes on this element if they match 395 * <code>oldid</code>, but not any found in child or plugin elements. 396 */ public 397 void renameSIdRefs(String oldid, String newid) { 398 libsbmlJNI.ReplacedElement_renameSIdRefs(swigCPtr, this, oldid, newid); 399 } 400 401 402/** 403 * Finds the {@link SBase} object this {@link ReplacedElement} object points to, if any. 404 */ public 405 SBase getReferencedElementFrom(Model model) { 406 return libsbml.DowncastSBase(libsbmlJNI.ReplacedElement_getReferencedElementFrom(swigCPtr, this, Model.getCPtr(model), model), false); 407} 408 409}