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 * &ldquo;comp&rdquo; package.
015 <p>
016 * The {@link ReplacedElement} class was introduced by the SBML Level&nbsp;3
017 *  'Hierarchical Model Composition'  package
018 * (&ldquo;comp&rdquo;) 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>&lt;cn&gt;</code> element within the
047 * <code>&lt;math&gt;</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>&lt;cn&gt;</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 &ldquo;<code>SBML_</code>&rdquo;. 
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&nbsp;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&nbsp;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}