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