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&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   <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&nbsp;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&nbsp;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&nbsp;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&nbsp;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&nbsp;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}