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 * <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&nbsp;3 <a href='../../../extensions-summary.html#comp'>Hierarchical Model Composition</a> (&ldquo;comp&rdquo;) 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>&lt;cn&gt;</code> element within the
044 * <code>&lt;math&gt;</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>&lt;cn&gt;</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   */ public
148 ReplacedElement(long level, long version, long pkgVersion) throws org.sbml.libsbml.SBMLConstructorException {
149    this(libsbmlJNI.new_ReplacedElement__SWIG_0(level, version, pkgVersion), true);
150  }
151
152  
153/**
154   * Creates a new {@link ReplacedElement} with the given level, version, and package
155   * version.
156   <p>
157   * @param level the SBML Level
158   * @param version the Version within the SBML Level
159   * @param pkgVersion the version of the package
160   */ public
161 ReplacedElement(long level, long version) throws org.sbml.libsbml.SBMLConstructorException {
162    this(libsbmlJNI.new_ReplacedElement__SWIG_1(level, version), true);
163  }
164
165  
166/**
167   * Creates a new {@link ReplacedElement} with the given level, version, and package
168   * version.
169   <p>
170   * @param level the SBML Level
171   * @param version the Version within the SBML Level
172   * @param pkgVersion the version of the package
173   */ public
174 ReplacedElement(long level) throws org.sbml.libsbml.SBMLConstructorException {
175    this(libsbmlJNI.new_ReplacedElement__SWIG_2(level), true);
176  }
177
178  
179/**
180   * Creates a new {@link ReplacedElement} with the given level, version, and package
181   * version.
182   <p>
183   * @param level the SBML Level
184   * @param version the Version within the SBML Level
185   * @param pkgVersion the version of the package
186   */ public
187 ReplacedElement() throws org.sbml.libsbml.SBMLConstructorException {
188    this(libsbmlJNI.new_ReplacedElement__SWIG_3(), true);
189  }
190
191  
192/**
193   * Creates a new {@link ReplacedElement} with the given {@link CompPkgNamespaces} object.
194   <p>
195   * @param compns the namespace to use
196   */ public
197 ReplacedElement(CompPkgNamespaces compns) throws org.sbml.libsbml.SBMLConstructorException {
198    this(libsbmlJNI.new_ReplacedElement__SWIG_4(CompPkgNamespaces.getCPtr(compns), compns), true);
199  }
200
201  
202/**
203   * Copy constructor.
204   */ public
205 ReplacedElement(ReplacedElement source) throws org.sbml.libsbml.SBMLConstructorException {
206    this(libsbmlJNI.new_ReplacedElement__SWIG_5(ReplacedElement.getCPtr(source), source), true);
207  }
208
209  
210/**
211   * Creates and returns a deep copy of this {@link ReplacedElement} object.
212   <p>
213   * @return a (deep) copy of this {@link ReplacedElement} object
214   */ public
215 SBase cloneObject() {
216    long cPtr = libsbmlJNI.ReplacedElement_cloneObject(swigCPtr, this);
217    return (cPtr == 0) ? null : new ReplacedElement(cPtr, true);
218  }
219
220  
221/**
222   * Returns the value of the 'conversionFactor' attribute of this {@link ReplacedElement}.
223   <p>
224   * @return the value of the 'conversionFactor' attribute of this {@link ReplacedElement}.
225   */ public
226 String getConversionFactor() {
227    return libsbmlJNI.ReplacedElement_getConversionFactor(swigCPtr, this);
228  }
229
230  
231/**
232   * Predicate returning <code>true</code> or <code>false</code> depending on whether this
233   * {@link ReplacedElement}'s 'conversionFactor' attribute has been set.
234   <p>
235   * @return <code>true</code> if this {@link ReplacedElement}'s 'conversionFactor' attribute has been set, 
236   * otherwise <code>false</code> is returned.
237   */ public
238 boolean isSetConversionFactor() {
239    return libsbmlJNI.ReplacedElement_isSetConversionFactor(swigCPtr, this);
240  }
241
242  
243/**
244   * Sets the value of the 'conversionFactor' attribute of this {@link ReplacedElement}.
245   <p>
246   * <p>
247 * @return integer value indicating success/failure of the
248 * function.   The possible values
249 * returned by this function are:
250   * <ul>
251   * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS}
252   * <li> {@link libsbmlConstants#LIBSBML_INVALID_ATTRIBUTE_VALUE LIBSBML_INVALID_ATTRIBUTE_VALUE}
253   * </ul>
254   */ public
255 int setConversionFactor(String id) {
256    return libsbmlJNI.ReplacedElement_setConversionFactor(swigCPtr, this, id);
257  }
258
259  
260/**
261   * Unsets the value of the 'conversionFactor' attribute of this {@link ReplacedElement}.
262   <p>
263   * <p>
264 * @return integer value indicating success/failure of the
265 * function.   The possible values
266 * returned by this function are:
267   * <ul>
268   * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS}
269   * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED}
270   * </ul>
271   */ public
272 int unsetConversionFactor() {
273    return libsbmlJNI.ReplacedElement_unsetConversionFactor(swigCPtr, this);
274  }
275
276  
277/**
278   * Returns the value of the 'deletion' attribute of this {@link ReplacedElement}.
279   <p>
280   * @return the value of the 'deletion' attribute of this {@link ReplacedElement}.
281   */ public
282 String getDeletion() {
283    return libsbmlJNI.ReplacedElement_getDeletion(swigCPtr, this);
284  }
285
286  
287/**
288   * Predicate returning <code>true</code> or <code>false</code> depending on whether this
289   * {@link SBaseRef}'s 'deletion' attribute has been set.
290   <p>
291   * @return <code>true</code> if this {@link ReplacedElement}'s 'deletion' attribute has been set, 
292   * otherwise <code>false</code> is returned.
293   */ public
294 boolean isSetDeletion() {
295    return libsbmlJNI.ReplacedElement_isSetDeletion(swigCPtr, this);
296  }
297
298  
299/**
300   * Sets the value of the 'deletion' attribute of this {@link ReplacedElement}.
301   <p>
302   * 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
303   * 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
304   * one method to point to a submodel element: deletion, port, idRef,
305   * unitRef, or metaIdRef.
306   <p>
307   * <p>
308 * @return integer value indicating success/failure of the
309 * function.   The possible values
310 * returned by this function are:
311   * <ul>
312   * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS}
313   * <li> {@link libsbmlConstants#LIBSBML_INVALID_ATTRIBUTE_VALUE LIBSBML_INVALID_ATTRIBUTE_VALUE}
314   * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED}
315   * </ul>
316   */ public
317 int setDeletion(String id) {
318    return libsbmlJNI.ReplacedElement_setDeletion(swigCPtr, this, id);
319  }
320
321  
322/**
323   * Unsets the value of the 'deletion' attribute of this {@link ReplacedElement}.
324   <p>
325   * <p>
326 * @return integer value indicating success/failure of the
327 * function.   The possible values
328 * returned by this function are:
329   * <ul>
330   * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS}
331   * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED}
332   * </ul>
333   */ public
334 int unsetDeletion() {
335    return libsbmlJNI.ReplacedElement_unsetDeletion(swigCPtr, this);
336  }
337
338  
339/**
340   * Returns the XML element name of
341   * this SBML object.
342   <p>
343   * @return the name of this element, as a text string.
344   */ public
345 String getElementName() {
346    return libsbmlJNI.ReplacedElement_getElementName(swigCPtr, this);
347  }
348
349  
350/**
351   * Returns how many elements are being referred to by this {@link ReplacedElement}.  A
352   * valid {@link ReplacedElement} will have exactly one.  Possible referents are deletion,
353   * port, idRef, unitRef, and metaIdRef.
354   <p>
355   * @return integer value between 0 and 5: the number of different ways this
356   * element points to its referent.
357   */ public
358 int getNumReferents() {
359    return libsbmlJNI.ReplacedElement_getNumReferents(swigCPtr, this);
360  }
361
362  
363/**
364   * Returns the libSBML type code of this object instance.
365   <p>
366   * <p>
367 * LibSBML attaches an identifying code to every kind of SBML object.  These
368 * are integer constants known as <em>SBML type codes</em>.  The names of all
369 * the codes begin with the characters <code>SBML_</code>.
370 * In the Java language interface for libSBML, the
371 * type codes are defined as static integer constants in the interface class
372 * {@link libsbmlConstants}.    Note that different Level&nbsp;3
373 * package plug-ins may use overlapping type codes; to identify the package
374 * to which a given object belongs, call the <code>getPackageName()</code>
375 * method on the object.
376   <p>
377   * @return the SBML type code for this object:
378   * {@link libsbmlConstants#SBML_COMP_REPLACEDELEMENT SBML_COMP_REPLACEDELEMENT}
379   <p>
380   * <p>
381 * @warning <span class='warning'>The specific integer values of the possible
382 * type codes may be reused by different libSBML plug-ins for SBML Level&nbsp;3.
383 * packages,  To fully identify the correct code, <strong>it is necessary to
384 * invoke both getTypeCode() and getPackageName()</strong>.</span>
385   <p>
386   * @see #getElementName()
387   * @see #getPackageName()
388   */ public
389 int getTypeCode() {
390    return libsbmlJNI.ReplacedElement_getTypeCode(swigCPtr, this);
391  }
392
393  
394/**
395   * <p>
396 * Replaces all uses of a given <code>SIdRef</code> type attribute value with another
397 * value.
398 <p>
399 * <p>
400 * In SBML, object identifiers are of a data type called <code>SId</code>.
401 * In SBML Level&nbsp;3, an explicit data type called <code>SIdRef</code> was
402 * introduced for attribute values that refer to <code>SId</code> values; in
403 * previous Levels of SBML, this data type did not exist and attributes were
404 * simply described to as 'referring to an identifier', but the effective
405 * data type was the same as <code>SIdRef</code>in Level&nbsp;3.  These and
406 * other methods of libSBML refer to the type <code>SIdRef</code> for all
407 * Levels of SBML, even if the corresponding SBML specification did not
408 * explicitly name the data type.
409 <p>
410 * This method works by looking at all attributes and (if appropriate)
411 * mathematical formulas in MathML content, comparing the referenced
412 * identifiers to the value of <code>oldid</code>.  If any matches are found, the
413 * matching values are replaced with <code>newid</code>.  The method does <em>not</em>
414 * descend into child elements.
415 <p>
416 * @param oldid the old identifier
417 * @param newid the new identifier
418   */ public
419 void renameSIdRefs(String oldid, String newid) {
420    libsbmlJNI.ReplacedElement_renameSIdRefs(swigCPtr, this, oldid, newid);
421  }
422
423  
424/**
425   * Finds the {@link SBase} object this {@link ReplacedElement} object points to, if any.
426   */ public
427 SBase getReferencedElementFrom(Model model) {
428  return libsbml.DowncastSBase(libsbmlJNI.ReplacedElement_getReferencedElementFrom(swigCPtr, this, Model.getCPtr(model), model), false);
429}
430
431}