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 *  A reference to an SBML species in a reaction.
013 <p>
014 * The {@link Reaction} structure provides a way to express which species act as
015 * reactants and which species act as products in a reaction.  In a given
016 * reaction, references to those species acting as reactants and/or
017 * products are made using instances of {@link SpeciesReference} structures in a
018 * {@link Reaction} object's lists of reactants and products.
019 <p>
020 * A species can occur more than once in the lists of reactants and
021 * products of a given {@link Reaction} instance.  The effective stoichiometry for
022 * a species in a reaction is the sum of the stoichiometry values given on
023 * the {@link SpeciesReference} object in the list of products minus the sum of
024 * stoichiometry values given on the {@link SpeciesReference} objects in the list
025 * of reactants.  A positive value indicates the species is effectively a
026 * product and a negative value indicates the species is effectively a
027 * reactant.  SBML places no restrictions on the effective stoichiometry of
028 * a species in a reaction; for example, it can be zero.  In the following
029 * SBML fragment, the two reactions have the same effective stoichiometry
030 * for all their species:
031 * <pre class='fragment'>
032 &lt;reaction id='x'&gt;
033     &lt;listOfReactants&gt;
034         &lt;speciesReference species='a'/&gt;
035         &lt;speciesReference species='a'/&gt;
036         &lt;speciesReference species='b'/&gt;
037     &lt;/listOfReactants&gt;
038     &lt;listOfProducts&gt;
039         &lt;speciesReference species='c'/&gt;
040         &lt;speciesReference species='b'/&gt;
041     &lt;/listProducts&gt;
042 &lt;/reaction&gt;
043 &lt;reaction id='y'&gt;
044     &lt;listOfReactants&gt;
045         &lt;speciesReference species='a' stoichiometry='2'/&gt;
046     &lt;/listOfReactants&gt;
047     &lt;listOfProducts&gt;
048         &lt;speciesReference species='c'/&gt;
049     &lt;/listProducts&gt;
050 &lt;/reaction&gt;
051 </pre>
052 <p>
053 * The precise structure of {@link SpeciesReference} differs between SBML
054 * Level&nbsp;2 and Level&nbsp;3.  We discuss the two variants in separate
055 * sections below.
056 <p>
057 * <h2>SpeciesReference in SBML Level 2</h2>
058 <p>
059 * The mandatory 'species' attribute of {@link SpeciesReference} must have as its
060 * value the identifier of an existing species defined in the enclosing
061 * {@link Model}.  The species is thereby designated as a reactant or product in
062 * the reaction.  Which one it is (i.e., reactant or product) is indicated
063 * by whether the {@link SpeciesReference} appears in the {@link Reaction}'s 'reactant' or
064 * 'product' lists.
065 <p>
066 * Product and reactant stoichiometries can be specified using
067 * <em>either</em> 'stoichiometry' or 'stoichiometryMath' in a
068 * {@link SpeciesReference} object.  The 'stoichiometry' attribute is of type
069 * double and should contain values greater than <code>0</code> (false).  The
070 * 'stoichiometryMath' element is implemented as an element containing a
071 * MathML expression.  These two are mutually exclusive; only one of
072 * 'stoichiometry' or 'stoichiometryMath' should be defined in a given
073 * {@link SpeciesReference} instance.  When neither the attribute nor the element
074 * is present, the value of 'stoichiometry' in the {@link SpeciesReference}
075 * instance defaults to <code>1.</code>
076 <p>
077 * For maximum interoperability, the 'stoichiometry' attribute should be
078 * used in preference to 'stoichiometryMath' when a species' stoichiometry
079 * is a simple scalar number (integer or decimal).  When the stoichiometry
080 * is a rational number, or when it is a more complicated formula,
081 * 'stoichiometryMath' must be used.  The MathML expression in
082 * 'stoichiometryMath' may also refer to identifiers of entities in a model
083 * (except reaction identifiers).  However, the only species identifiers
084 * that can be used in 'stoichiometryMath' are those referenced in the
085 * {@link Reaction} list of reactants, products and modifiers.
086 <p>
087 * The following is a simple example of a species reference for species
088 * <code>X0</code>, with stoichiometry <code>2</code>, in a list of reactants within a reaction
089 * having the identifier <code>J1:</code>
090 * <pre class='fragment'>
091 &lt;model&gt;
092     ...
093     &lt;listOfReactions&gt;
094         &lt;reaction id='J1'&gt;
095             &lt;listOfReactants&gt;
096                 &lt;speciesReference species='X0' stoichiometry='2'&gt;
097             &lt;/listOfReactants&gt;
098             ...
099         &lt;/reaction&gt;
100         ...
101     &lt;/listOfReactions&gt;
102     ...
103 &lt;/model&gt;
104 </pre>
105 <p>
106 * The following is a more complex example of a species reference for
107 * species X0, with a stoichiometry formula consisting of the parameter
108 * <code>x:</code>
109 * <pre class='fragment'>
110 &lt;model&gt;
111     ...
112     &lt;listOfReactions&gt;
113         &lt;reaction id='J1'&gt;
114             &lt;listOfReactants&gt;
115                 &lt;speciesReference species='X0'&gt;
116                     &lt;stoichiometryMath&gt;
117                         &lt;math xmlns='http://www.w3.org/1998/Math/MathML'&gt;
118                             &lt;ci&gt;x&lt;/ci&gt;
119                         &lt;/math&gt;
120                     &lt;/stoichiometryMath&gt;
121                 &lt;/speciesReference&gt;
122             &lt;/listOfReactants&gt;
123             ...
124         &lt;/reaction&gt;
125         ...
126     &lt;/listOfReactions&gt;
127     ...
128 &lt;/model&gt;
129 </pre>
130 <p>
131 * <h2>SpeciesReference in SBML Level 3</h2>
132 <p>
133 * In Level 2's definition of a reaction, the stoichiometry attribute of a
134 * {@link SpeciesReference} is actually a combination of two factors, the standard
135 * biochemical stoichiometry and a conversion factor that may be needed to
136 * translate the units of the species quantity to the units of the reaction
137 * rate. Unfortunately, Level&nbsp;2 offers no direct way of decoupling
138 * these two factors, or for explicitly indicating the units. The only way
139 * to do it in Level&nbsp;2 is to use the {@link StoichiometryMath} object
140 * associated with SpeciesReferences, and to reference SBML {@link Parameter}
141 * objects from within the {@link StoichiometryMath} formula. This works because
142 * {@link Parameter} offers a way to attach units to a numerical value, but the
143 * solution is indirect and awkward for something that should be a simple
144 * matter.  Moreover, the question of how to properly encode
145 * stoichiometries in SBML reactions has caused much confusion among
146 * implementors of SBML software.
147 <p>
148 * SBML Level&nbsp;3 approaches this problem differently.  It (1) extends
149 * the the use of the {@link SpeciesReference} identifier to represent the value of
150 * the 'stoichiometry' attribute, (2) makes the 'stoichiometry' attribute
151 * optional, (3) removes {@link StoichiometryMath}, and (4) adds a new 'constant'
152 * boolean attribute on {@link SpeciesReference}.
153 <p>
154 * As in Level&nbsp;2, the 'stoichiometry' attribute is of type
155 * <code>double</code> and should contain values greater than zero (<code>0</code>).  A
156 * missing 'stoichiometry' implies that the stoichiometry is either
157 * unknown, or to be obtained from an external source, or determined by an
158 * {@link InitialAssignment} object or other SBML construct elsewhere in the model.
159 <p>
160 * A species reference's stoichiometry is set by its 'stoichiometry'
161 * attribute exactly once.  If the {@link SpeciesReference} object's 'constant'
162 * attribute has the value <code>true</code>, then the stoichiometry is fixed and
163 * cannot be changed except by an {@link InitialAssignment} object.  These two
164 * methods of setting the stoichiometry (i.e., using 'stoichiometry'
165 * directly, or using {@link InitialAssignment}) differ in that the 'stoichiometry'
166 * attribute can only be set to a literal floating-point number, whereas
167 * {@link InitialAssignment} allows the value to be set using an arbitrary
168 * mathematical expression.  (As an example, the approach could be used to
169 * set the stoichiometry to a rational number of the form <em>p</em>/<em>q</em>,
170 * where <em>p</em> and <em>q</em> are integers, something that is occasionally
171 * useful in the context of biochemical reaction networks.)  If the species
172 * reference's 'constant' attribute has the value <code>false</code>, the species
173 * reference's value may be overridden by an {@link InitialAssignment} or changed
174 * by {@link AssignmentRule} or {@link AlgebraicRule}, and in addition, for simulation time
175 * <em>t &gt; 0</em>, it may also be changed by a {@link RateRule} or {@link Event}
176 * objects.  (However, some of these constructs are mutually exclusive; see
177 * the SBML Level&nbsp;3 Core specifiation for more
178 * details.)  It is not an error to define 'stoichiometry' on a species
179 * reference and also redefine the stoichiometry using an
180 * {@link InitialAssignment}, but the 'stoichiometry' attribute in that case is
181 * ignored.
182 <p>
183 * The value of the 'id' attribute of a {@link SpeciesReference} can be used as the
184 * content of a <code>&lt;ci&gt;</code> element in MathML formulas
185 * elsewhere in the model.  When the identifier appears in a MathML
186 * <code>&lt;ci&gt;</code> element, it represents the stoichiometry of the
187 * corresponding species in the reaction where the {@link SpeciesReference} object
188 * instance appears.  More specifically, it represents the value of the
189 * 'stoichiometry' attribute on the {@link SpeciesReference} object.
190 <p>
191 * In SBML Level 3, the unit of measurement associated with the value of a
192 * species' stoichiometry is always considered to be <code>dimensionless.</code>
193 * This has the following implications:
194 * <ul>
195 <p>
196 * <li> When a species reference's identifier appears in mathematical
197 * formulas elsewhere in the model, the unit associated with that value is
198 * <code>dimensionless.</code>
199 <p>
200 * <li> The units of the 'math' elements of {@link AssignmentRule},
201 * {@link InitialAssignment} and {@link EventAssignment} objects setting the stoichiometry
202 * of the species reference should be <code>dimensionless.</code>
203 <p>
204 * <li> If a species reference's identifier is the subject of a {@link RateRule},
205 * the unit associated with the {@link RateRule} object's value should be
206 * <code>dimensionless</code>/<em>time</em>, where <em>time</em> is the
207 * model-wide unit of time set on the {@link Model} object.
208 <p>
209 * </ul>
210 */
211
212public class SpeciesReference extends SimpleSpeciesReference {
213   private long swigCPtr;
214
215   protected SpeciesReference(long cPtr, boolean cMemoryOwn)
216   {
217     super(libsbmlJNI.SpeciesReference_SWIGUpcast(cPtr), cMemoryOwn);
218     swigCPtr = cPtr;
219   }
220
221   protected static long getCPtr(SpeciesReference obj)
222   {
223     return (obj == null) ? 0 : obj.swigCPtr;
224   }
225
226   protected static long getCPtrAndDisown (SpeciesReference obj)
227   {
228     long ptr = 0;
229
230     if (obj != null)
231     {
232       ptr             = obj.swigCPtr;
233       obj.swigCMemOwn = false;
234     }
235
236     return ptr;
237   }
238
239  protected void finalize() {
240    delete();
241  }
242
243  public synchronized void delete() {
244    if (swigCPtr != 0) {
245      if (swigCMemOwn) {
246        swigCMemOwn = false;
247        libsbmlJNI.delete_SpeciesReference(swigCPtr);
248      }
249      swigCPtr = 0;
250    }
251    super.delete();
252  }
253
254  
255/**
256   * Creates a new {@link SpeciesReference} using the given SBML <code>level</code> and <code>version</code>
257   * values.
258   <p>
259   * @param level a long integer, the SBML Level to assign to this {@link SpeciesReference}.
260   <p>
261   * @param version a long integer, the SBML Version to assign to this
262   * {@link SpeciesReference}.
263   <p>
264   * <p>
265 * @throws SBMLConstructorException
266 * Thrown if the given <code>level</code> and <code>version</code> combination are invalid
267 * or if this object is incompatible with the given level and version.
268   <p>
269   * <p>
270 * @note Attempting to add an object to an {@link SBMLDocument} having a different
271 * combination of SBML Level, Version and XML namespaces than the object
272 * itself will result in an error at the time a caller attempts to make the
273 * addition.  A parent object must have compatible Level, Version and XML
274 * namespaces.  (Strictly speaking, a parent may also have more XML
275 * namespaces than a child, but the reverse is not permitted.)  The
276 * restriction is necessary to ensure that an SBML model has a consistent
277 * overall structure.  This requires callers to manage their objects
278 * carefully, but the benefit is increased flexibility in how models can be
279 * created by permitting callers to create objects bottom-up if desired.  In
280 * situations where objects are not yet attached to parents (e.g.,
281 * {@link SBMLDocument}), knowledge of the intented SBML Level and Version help
282 * libSBML determine such things as whether it is valid to assign a
283 * particular value to an attribute.
284   */ public
285 SpeciesReference(long level, long version) throws org.sbml.libsbml.SBMLConstructorException {
286    this(libsbmlJNI.new_SpeciesReference__SWIG_0(level, version), true);
287  }
288
289  
290/**
291   * Creates a new {@link SpeciesReference} using the given {@link SBMLNamespaces} object
292   * <code>sbmlns</code>.
293   <p>
294   * @param sbmlns an {@link SBMLNamespaces} object.
295   <p>
296   * <p>
297 * @throws SBMLConstructorException
298 * Thrown if the given <code>sbmlns</code> is inconsistent or incompatible
299 * with this object.
300   <p>
301   * <p>
302 * @note Attempting to add an object to an {@link SBMLDocument} having a different
303 * combination of SBML Level, Version and XML namespaces than the object
304 * itself will result in an error at the time a caller attempts to make the
305 * addition.  A parent object must have compatible Level, Version and XML
306 * namespaces.  (Strictly speaking, a parent may also have more XML
307 * namespaces than a child, but the reverse is not permitted.)  The
308 * restriction is necessary to ensure that an SBML model has a consistent
309 * overall structure.  This requires callers to manage their objects
310 * carefully, but the benefit is increased flexibility in how models can be
311 * created by permitting callers to create objects bottom-up if desired.  In
312 * situations where objects are not yet attached to parents (e.g.,
313 * {@link SBMLDocument}), knowledge of the intented SBML Level and Version help
314 * libSBML determine such things as whether it is valid to assign a
315 * particular value to an attribute.
316   */ public
317 SpeciesReference(SBMLNamespaces sbmlns) throws org.sbml.libsbml.SBMLConstructorException {
318    this(libsbmlJNI.new_SpeciesReference__SWIG_1(SBMLNamespaces.getCPtr(sbmlns), sbmlns), true);
319  }
320
321  
322/**
323   * Copy constructor; creates a copy of this {@link SpeciesReference}.
324   <p>
325   * @param orig the {@link SpeciesReference} instance to copy.
326   */ public
327 SpeciesReference(SpeciesReference orig) throws org.sbml.libsbml.SBMLConstructorException {
328    this(libsbmlJNI.new_SpeciesReference__SWIG_2(SpeciesReference.getCPtr(orig), orig), true);
329  }
330
331  
332/**
333   * Creates and returns a deep copy of this {@link SpeciesReference} object.
334   <p>
335   * @return the (deep) copy of this {@link SpeciesReference} object.
336   */ public
337 SpeciesReference cloneObject() {
338    long cPtr = libsbmlJNI.SpeciesReference_cloneObject(swigCPtr, this);
339    return (cPtr == 0) ? null : new SpeciesReference(cPtr, true);
340  }
341
342  
343/**
344   * Initializes the fields of this {@link SpeciesReference} object to 'typical'
345   * default values.
346   <p>
347   * The SBML {@link SpeciesReference} component has slightly different aspects and
348   * default attribute values in different SBML Levels and Versions.
349   * This method sets the values to certain common defaults, based
350   * mostly on what they are in SBML Level&nbsp;2.  Specifically:
351   * <ul>
352   * <li> Sets attribute 'stoichiometry' to <code>1.0</code>
353   * <li> (Applies to Level&nbsp;1 models only) Sets attribute 'denominator' to <code>1</code>
354   * </ul>
355   <p>
356   * @see #getDenominator()
357   * @see #setDenominator(int value)
358   * @see #getStoichiometry()
359   * @see #setStoichiometry(double value)
360   * @see #getStoichiometryMath()
361   * @see #setStoichiometryMath(StoichiometryMath math)
362   */ public
363 void initDefaults() {
364    libsbmlJNI.SpeciesReference_initDefaults(swigCPtr, this);
365  }
366
367  
368/**
369   * Get the value of the 'stoichiometry' attribute.
370   <p>
371   * In SBML Level 2, product and reactant stoichiometries can be specified
372   * using <em>either</em> 'stoichiometry' or 'stoichiometryMath' in a
373   * {@link SpeciesReference} object.  The former is to be used when a
374   * stoichiometry is simply a scalar number, while the latter is for
375   * occasions when it needs to be a rational number or it needs to
376   * reference other mathematical expressions.  The 'stoichiometry'
377   * attribute is of type <code>double</code> and should contain values greater than
378   * zero (<code>0</code>).  The 'stoichiometryMath' element is implemented as an
379   * element containing a MathML expression.  These two are mutually
380   * exclusive; only one of 'stoichiometry' or 'stoichiometryMath' should
381   * be defined in a given {@link SpeciesReference} instance.  When neither the
382   * attribute nor the element is present, the value of 'stoichiometry' in
383   * the {@link SpeciesReference} instance defaults to <code>1.</code>  For maximum
384   * interoperability between different software tools, the 'stoichiometry'
385   * attribute should be used in preference to 'stoichiometryMath' when a
386   * species' stoichiometry is a simple scalar number (integer or
387   * decimal).
388   <p>
389   * In SBML Level 3, there is no {@link StoichiometryMath}, and {@link SpeciesReference}
390   * objects have only the 'stoichiometry' attribute.
391   <p>
392   * @return the value of the (scalar) 'stoichiometry' attribute of this
393   * {@link SpeciesReference}.
394   <p>
395   * @see #getStoichiometryMath()
396   */ public
397 double getStoichiometry() {
398    return libsbmlJNI.SpeciesReference_getStoichiometry(swigCPtr, this);
399  }
400
401  
402/**
403   * Get the content of the 'stoichiometryMath' subelement as an {@link ASTNode}
404   * tree.
405   <p>
406   * The 'stoichiometryMath' element exists only in SBML Level 2.  There,
407   * product and reactant stoichiometries can be specified using
408   * <em>either</em> 'stoichiometry' or 'stoichiometryMath' in a
409   * {@link SpeciesReference} object.  The former is to be used when a
410   * stoichiometry is simply a scalar number, while the latter is for
411   * occasions when it needs to be a rational number or it needs to
412   * reference other mathematical expressions.  The 'stoichiometry'
413   * attribute is of type <code>double</code> and should contain values greater than
414   * zero (<code>0</code>).  The 'stoichiometryMath' element is implemented as an
415   * element containing a MathML expression.  These two are mutually
416   * exclusive; only one of 'stoichiometry' or 'stoichiometryMath' should
417   * be defined in a given {@link SpeciesReference} instance.  When neither the
418   * attribute nor the element is present, the value of 'stoichiometry' in
419   * the {@link SpeciesReference} instance defaults to <code>1.</code>  For maximum
420   * interoperability between different software tools, the 'stoichiometry'
421   * attribute should be used in preference to 'stoichiometryMath' when a
422   * species' stoichiometry is a simple scalar number (integer or decimal).
423   <p>
424   * @return the content of the 'stoichiometryMath' subelement of this
425   * {@link SpeciesReference}.
426   */ public
427 StoichiometryMath getStoichiometryMath() {
428    long cPtr = libsbmlJNI.SpeciesReference_getStoichiometryMath__SWIG_0(swigCPtr, this);
429    return (cPtr == 0) ? null : new StoichiometryMath(cPtr, false);
430  }
431
432  
433/**
434   * Get the value of the 'denominator' attribute, for the case of a
435   * rational-numbered stoichiometry or a model in SBML Level&nbsp;1.
436   <p>
437   * The 'denominator' attribute is only actually written out in the case
438   * of an SBML Level&nbsp;1 model.  In SBML Level&nbsp;2, rational-number
439   * stoichiometries are written as MathML elements in the
440   * 'stoichiometryMath' subelement.  However, as a convenience to users,
441   * libSBML allows the creation and manipulation of rational-number
442   * stoichiometries by supplying the numerator and denominator directly
443   * rather than having to manually create an {@link ASTNode} object.  LibSBML
444   * will write out the appropriate constructs (either a combination of
445   * 'stoichiometry' and 'denominator' in the case of SBML Level&nbsp;1, or a
446   * 'stoichiometryMath' subelement in the case of SBML Level&nbsp;2).
447   * However, as the 'stoichiometryMath' subelement was removed in SBML
448   * Level&nbsp;3, automatic translation of the 'denominator'
449   * attribute is no longer supported for that level.
450   <p>
451   * @return the value of the 'denominator' attribute of this
452   * {@link SpeciesReference}.
453   */ public
454 int getDenominator() {
455    return libsbmlJNI.SpeciesReference_getDenominator(swigCPtr, this);
456  }
457
458  
459/**
460   * Get the value of the 'constant' attribute.
461   <p>
462   * @return the value of the 'constant' attribute of this
463   * {@link SpeciesReference}.
464   */ public
465 boolean getConstant() {
466    return libsbmlJNI.SpeciesReference_getConstant(swigCPtr, this);
467  }
468
469  
470/**
471   * Predicate returning <code>true</code> if this
472   * {@link SpeciesReference}'s 'stoichiometryMath' subelement is set
473   <p>
474   * @return <code>true</code> if the 'stoichiometryMath' subelement of this
475   * {@link SpeciesReference} is set, <code>false</code> otherwise.
476   */ public
477 boolean isSetStoichiometryMath() {
478    return libsbmlJNI.SpeciesReference_isSetStoichiometryMath(swigCPtr, this);
479  }
480
481  
482/**
483   * Predicate returning <code>true</code> if this
484   * {@link SpeciesReference}'s 'constant' attribute is set
485   <p>
486   * @return <code>true</code> if the 'constant' attribute of this
487   * {@link SpeciesReference} is set, <code>false</code> otherwise.
488   */ public
489 boolean isSetConstant() {
490    return libsbmlJNI.SpeciesReference_isSetConstant(swigCPtr, this);
491  }
492
493  
494/**
495   * Predicate returning <code>true</code> if this
496   * {@link SpeciesReference}'s 'stoichiometry' attribute is set.
497   <p>
498   * @return <code>true</code> if the 'stoichiometry' attribute of this
499   * {@link SpeciesReference} is set, <code>false</code> otherwise.
500   */ public
501 boolean isSetStoichiometry() {
502    return libsbmlJNI.SpeciesReference_isSetStoichiometry(swigCPtr, this);
503  }
504
505  
506/**
507   * Sets the value of the 'stoichiometry' attribute of this
508   * {@link SpeciesReference}.
509   <p>
510   * In SBML Level 2, product and reactant stoichiometries can be specified
511   * using <em>either</em> 'stoichiometry' or 'stoichiometryMath' in a
512   * {@link SpeciesReference} object.  The former is to be used when a
513   * stoichiometry is simply a scalar number, while the latter is for
514   * occasions when it needs to be a rational number or it needs to
515   * reference other mathematical expressions.  The 'stoichiometry'
516   * attribute is of type <code>double</code> and should contain values greater than
517   * zero (<code>0</code>).  The 'stoichiometryMath' element is implemented as an
518   * element containing a MathML expression.  These two are mutually
519   * exclusive; only one of 'stoichiometry' or 'stoichiometryMath' should
520   * be defined in a given {@link SpeciesReference} instance.  When neither the
521   * attribute nor the element is present, the value of 'stoichiometry' in
522   * the {@link SpeciesReference} instance defaults to <code>1.</code>  For maximum
523   * interoperability between different software tools, the 'stoichiometry'
524   * attribute should be used in preference to 'stoichiometryMath' when a
525   * species' stoichiometry is a simple scalar number (integer or
526   * decimal).
527   <p>
528   * In SBML Level 3, there is no {@link StoichiometryMath}, and {@link SpeciesReference}
529   * objects have only the 'stoichiometry' attribute.
530   <p>
531   * @param value the new value of the 'stoichiometry' attribute.
532   <p>
533   * @note In SBML Level&nbsp;2, the 'stoichiometryMath' subelement of this
534   * {@link SpeciesReference} object will be unset because the 'stoichiometry'
535   * attribute and the stoichiometryMath' subelement are mutually
536   * exclusive.
537   <p>
538   * <p>
539 * @return integer value indicating success/failure of the
540 * function.   The possible values
541 * returned by this function are:
542   * <ul>
543   * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS}
544   * </ul>
545   */ public
546 int setStoichiometry(double value) {
547    return libsbmlJNI.SpeciesReference_setStoichiometry(swigCPtr, this, value);
548  }
549
550  
551/**
552   * Sets the 'stoichiometryMath' subelement of this {@link SpeciesReference}.
553   <p>
554   * The Abstract Syntax Tree in <code>math</code> is copied.
555   <p>
556   * In SBML Level 2, product and reactant stoichiometries can be specified
557   * using <em>either</em> 'stoichiometry' or 'stoichiometryMath' in a
558   * {@link SpeciesReference} object.  The former is to be used when a
559   * stoichiometry is simply a scalar number, while the latter is for
560   * occasions when it needs to be a rational number or it needs to
561   * reference other mathematical expressions.  The 'stoichiometry'
562   * attribute is of type <code>double</code> and should contain values greater than
563   * zero (<code>0</code>).  The 'stoichiometryMath' element is implemented as an
564   * element containing a MathML expression.  These two are mutually
565   * exclusive; only one of 'stoichiometry' or 'stoichiometryMath' should
566   * be defined in a given {@link SpeciesReference} instance.  When neither the
567   * attribute nor the element is present, the value of 'stoichiometry' in
568   * the {@link SpeciesReference} instance defaults to <code>1.</code>  For maximum
569   * interoperability between different software tools, the 'stoichiometry'
570   * attribute should be used in preference to 'stoichiometryMath' when a
571   * species' stoichiometry is a simple scalar number (integer or
572   * decimal).
573   <p>
574   * In SBML Level 3, there is no {@link StoichiometryMath}, and {@link SpeciesReference}
575   * objects have only the 'stoichiometry' attribute.
576   <p>
577   * @param math the {@link StoichiometryMath} expression that is to be copied as the
578   * content of the 'stoichiometryMath' subelement.
579   <p>
580   * @note In SBML Level&nbsp;2, the 'stoichiometry' attribute of this
581   * {@link SpeciesReference} object will be unset (isSetStoichiometry() will
582   * return <code>false</code> although getStoichiometry() will return <code>1.0</code>) if the
583   * given math is not null because the 'stoichiometry' attribute and the
584   * stoichiometryMath' subelement are mutually exclusive.
585   <p>
586   * <p>
587 * @return integer value indicating success/failure of the
588 * function.   The possible values
589 * returned by this function are:
590   * <ul>
591   * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS}
592   * <li> {@link libsbmlConstants#LIBSBML_UNEXPECTED_ATTRIBUTE LIBSBML_UNEXPECTED_ATTRIBUTE}
593   * <li> {@link libsbmlConstants#LIBSBML_LEVEL_MISMATCH LIBSBML_LEVEL_MISMATCH}
594   * <li> {@link libsbmlConstants#LIBSBML_VERSION_MISMATCH LIBSBML_VERSION_MISMATCH}
595   * </ul>
596   */ public
597 int setStoichiometryMath(StoichiometryMath math) {
598    return libsbmlJNI.SpeciesReference_setStoichiometryMath(swigCPtr, this, StoichiometryMath.getCPtr(math), math);
599  }
600
601  
602/**
603   * Set the value of the 'denominator' attribute, for the case of a
604   * rational-numbered stoichiometry or a model in SBML Level&nbsp;1.
605   <p>
606   * The 'denominator' attribute is only actually written out in the case
607   * of an SBML Level&nbsp;1 model.  In SBML Level&nbsp;2, rational-number
608   * stoichiometries are written as MathML elements in the
609   * 'stoichiometryMath' subelement.  However, as a convenience to users,
610   * libSBML allows the creation and manipulation of rational-number
611   * stoichiometries by supplying the numerator and denominator directly
612   * rather than having to manually create an {@link ASTNode} object.  LibSBML
613   * will write out the appropriate constructs (either a combination of
614   * 'stoichiometry' and 'denominator' in the case of SBML Level&nbsp;1, or
615   * a 'stoichiometryMath' subelement in the case of SBML Level&nbsp;2).
616   * However, as the 'stoichiometryMath' subelement was removed in SBML
617   * Level&nbsp;3, automatic translation of the 'denominator' 
618   * attribute is no longer supported for that level.
619   <p>
620   * @param value the scalar value.
621   <p>
622   * <p>
623 * @return integer value indicating success/failure of the
624 * function.   The possible values
625 * returned by this function are:
626   * <ul>
627   * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS}
628   * <li> {@link libsbmlConstants#LIBSBML_UNEXPECTED_ATTRIBUTE LIBSBML_UNEXPECTED_ATTRIBUTE}
629   * </ul>
630   */ public
631 int setDenominator(int value) {
632    return libsbmlJNI.SpeciesReference_setDenominator(swigCPtr, this, value);
633  }
634
635  
636/**
637   * Sets the 'constant' attribute of this {@link SpeciesReference} to the given boolean
638   * <code>flag</code>.
639   <p>
640   * @param flag a boolean, the value for the 'constant' attribute of this
641   * {@link SpeciesReference} instance.
642   <p>
643   * <p>
644 * @return integer value indicating success/failure of the
645 * function.   The possible values
646 * returned by this function are:
647   * <ul>
648   * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS}
649   * <li> {@link libsbmlConstants#LIBSBML_UNEXPECTED_ATTRIBUTE LIBSBML_UNEXPECTED_ATTRIBUTE}
650   * </ul>
651   */ public
652 int setConstant(boolean flag) {
653    return libsbmlJNI.SpeciesReference_setConstant(swigCPtr, this, flag);
654  }
655
656  
657/**
658   * Unsets the 'stoichiometryMath' subelement of this {@link SpeciesReference}.
659   <p>
660   * <p>
661 * @return integer value indicating success/failure of the
662 * function.   The possible values
663 * returned by this function are:
664   * <ul>
665   * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS}
666   * <li> {@link libsbmlConstants#LIBSBML_UNEXPECTED_ATTRIBUTE LIBSBML_UNEXPECTED_ATTRIBUTE}
667   * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED}
668   *
669   * </ul> <p>
670   * In SBML Level 2, product and reactant stoichiometries can be specified
671   * using <em>either</em> 'stoichiometry' or 'stoichiometryMath' in a
672   * {@link SpeciesReference} object.  The former is to be used when a
673   * stoichiometry is simply a scalar number, while the latter is for
674   * occasions when it needs to be a rational number or it needs to
675   * reference other mathematical expressions.  The 'stoichiometry'
676   * attribute is of type <code>double</code> and should contain values greater than
677   * zero (<code>0</code>).  The 'stoichiometryMath' element is implemented as an
678   * element containing a MathML expression.  These two are mutually
679   * exclusive; only one of 'stoichiometry' or 'stoichiometryMath' should
680   * be defined in a given {@link SpeciesReference} instance.  When neither the
681   * attribute nor the element is present, the value of 'stoichiometry' in
682   * the {@link SpeciesReference} instance defaults to <code>1.</code>  For maximum
683   * interoperability between different software tools, the 'stoichiometry'
684   * attribute should be used in preference to 'stoichiometryMath' when a
685   * species' stoichiometry is a simple scalar number (integer or
686   * decimal).
687   <p>
688   * In SBML Level 3, there is no {@link StoichiometryMath}, and {@link SpeciesReference}
689   * objects have only the 'stoichiometry' attribute.
690   <p>
691   * @note In SBML Level&nbsp;2, the 'stoichiometry' attribute of this
692   * {@link SpeciesReference} object will be reset to a default value (<code>1.0</code>) if
693   * the 'stoichiometry' attribute has not been set.
694   */ public
695 int unsetStoichiometryMath() {
696    return libsbmlJNI.SpeciesReference_unsetStoichiometryMath(swigCPtr, this);
697  }
698
699  
700/**
701   * Unsets the 'stoichiometry' attribute of this {@link SpeciesReference}.
702   <p>
703   * <p>
704 * @return integer value indicating success/failure of the
705 * function.   The possible values
706 * returned by this function are:
707   * <ul>
708   * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS}
709   * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED}
710   *
711   * </ul> <p>
712   * @note In SBML Level&nbsp;1, the 'stoichiometry' attribute of this
713   * {@link SpeciesReference} object will be just reset to a default value (<code>1.0</code>)
714   * and isSetStoichiometry() will still return <code>true.</code>  In SBML
715   * Level&nbsp;2, the 'stoichiometry' attribute of this object will be
716   * unset (which will result in isSetStoichiometry() returning <code>false</code>,
717   * although getStoichiometry() will return <code>1.0</code>) if the
718   * 'stoichiometryMath' subelement is set, otherwise the attribute
719   * will be just reset to the default value (<code>1.0</code>) (and
720   * isSetStoichiometry() will still return <code>true</code>).  In SBML
721   * Level&nbsp;3, the 'stoichiometry' attribute of this object will be set
722   * to <code>NaN</code> and isSetStoichiometry() will return <code>false.</code>
723   */ public
724 int unsetStoichiometry() {
725    return libsbmlJNI.SpeciesReference_unsetStoichiometry(swigCPtr, this);
726  }
727
728  
729/**
730   * Unsets the 'constant' attribute of this {@link SpeciesReference}.
731   <p>
732   * <p>
733 * @return integer value indicating success/failure of the
734 * function.   The possible values
735 * returned by this function are:
736   * <ul>
737   * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS}
738   * <li> {@link libsbmlConstants#LIBSBML_UNEXPECTED_ATTRIBUTE LIBSBML_UNEXPECTED_ATTRIBUTE}
739   * </ul>
740   */ public
741 int unsetConstant() {
742    return libsbmlJNI.SpeciesReference_unsetConstant(swigCPtr, this);
743  }
744
745  
746/**
747   * Creates a new, empty {@link StoichiometryMath} object, adds it to this
748   * {@link SpeciesReference}, and returns it.
749   <p>
750   * @return the newly created {@link StoichiometryMath} object instance.
751   <p>
752   * @note This function has no effect on SBML Level 1 or Level 3 
753   * {@link SpeciesReference} objects, neither of which have
754   * {@link StoichiometryMath} children.
755   <p>
756   * @see Reaction#addReactant(SpeciesReference sr)
757   * @see Reaction#addProduct(SpeciesReference sr)
758   */ public
759 StoichiometryMath createStoichiometryMath() {
760    long cPtr = libsbmlJNI.SpeciesReference_createStoichiometryMath(swigCPtr, this);
761    return (cPtr == 0) ? null : new StoichiometryMath(cPtr, false);
762  }
763
764  
765/**
766   * Sets the value of the 'annotation' subelement of this SBML object to a
767   * copy of <code>annotation</code>.
768   <p>
769   * Any existing content of the 'annotation' subelement is discarded.
770   * Unless you have taken steps to first copy and reconstitute any
771   * existing annotations into the <code>annotation</code> that is about to be
772   * assigned, it is likely that performing such wholesale replacement is
773   * unfriendly towards other software applications whose annotations are
774   * discarded.  An alternative may be to use appendAnnotation().
775   <p>
776   * @param annotation an XML structure that is to be used as the content
777   * of the 'annotation' subelement of this object.
778   <p>
779   * <p>
780 * @return integer value indicating success/failure of the
781 * function.   This particular
782 * function only does one thing irrespective of user input or 
783 * object state, and thus will only return a single value:
784   * <ul>
785   * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS}
786   *
787   * </ul> <p>
788   * @see #appendAnnotation(XMLNode annotation)
789   * @see #appendAnnotation(String annotation)
790   */ public
791 int setAnnotation(XMLNode annotation) {
792    return libsbmlJNI.SpeciesReference_setAnnotation__SWIG_0(swigCPtr, this, XMLNode.getCPtr(annotation), annotation);
793  }
794
795  
796/**
797   * Sets the value of the 'annotation' subelement of this SBML object to a
798   * copy of <code>annotation</code>.
799   <p>
800   * Any existing content of the 'annotation' subelement is discarded.
801   * Unless you have taken steps to first copy and reconstitute any
802   * existing annotations into the <code>annotation</code> that is about to be
803   * assigned, it is likely that performing such wholesale replacement is
804   * unfriendly towards other software applications whose annotations are
805   * discarded.  An alternative may be to use appendAnnotation().
806   <p>
807   * @param annotation an XML string that is to be used as the content
808   * of the 'annotation' subelement of this object.
809   <p>
810   * <p>
811 * @return integer value indicating success/failure of the
812 * function.   The possible values
813 * returned by this function are:
814   * <ul>
815   * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS}
816   * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED}
817   *
818   * </ul> <p>
819   * @see #appendAnnotation(XMLNode annotation)
820   * @see #appendAnnotation(String annotation)
821   */ public
822 int setAnnotation(String annotation) {
823    return libsbmlJNI.SpeciesReference_setAnnotation__SWIG_1(swigCPtr, this, annotation);
824  }
825
826  
827/**
828   * Appends annotation content to any existing content in the 'annotation'
829   * subelement of this object.
830   <p>
831   * The content in <code>annotation</code> is copied.  Unlike
832   * {@link SpeciesReference#setAnnotation(String)},
833   * this method allows other annotations to be preserved when an application
834   * adds its own data.
835   <p>
836   * @param annotation an XML structure that is to be copied and appended
837   * to the content of the 'annotation' subelement of this object.
838   <p>
839   * <p>
840 * @return integer value indicating success/failure of the
841 * function.   The possible values
842 * returned by this function are:
843   * <ul>
844   * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS}
845   * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED}
846   *
847   * </ul> <p>
848   * @see #setAnnotation(String annotation)
849   * @see #setAnnotation(XMLNode annotation)
850   */ public
851 int appendAnnotation(XMLNode annotation) {
852    return libsbmlJNI.SpeciesReference_appendAnnotation__SWIG_0(swigCPtr, this, XMLNode.getCPtr(annotation), annotation);
853  }
854
855  
856/**
857   * Appends annotation content to any existing content in the 'annotation'
858   * subelement of this object.
859   <p>
860   * The content in <code>annotation</code> is copied.  Unlike
861   * {@link SpeciesReference#setAnnotation(String)}, this
862   * method allows other annotations to be preserved when an application
863   * adds its own data.
864   <p>
865   * @param annotation an XML string that is to be copied and appended
866   * to the content of the 'annotation' subelement of this object.
867   <p>
868   * <p>
869 * @return integer value indicating success/failure of the
870 * function.   The possible values
871 * returned by this function are:
872   * <ul>
873   * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS}
874   * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED}
875   *
876   * </ul> <p>
877   * @see #setAnnotation(String annotation)
878   * @see #setAnnotation(XMLNode annotation)
879   */ public
880 int appendAnnotation(String annotation) {
881    return libsbmlJNI.SpeciesReference_appendAnnotation__SWIG_1(swigCPtr, this, annotation);
882  }
883
884  
885/**
886   * Returns the libSBML type code for this SBML object.
887   <p>
888   * <p>
889 * LibSBML attaches an identifying code to every kind of SBML object.  These
890 * are integer constants known as <em>SBML type codes</em>.  The names of all
891 * the codes begin with the characters <code>SBML_</code>.
892 * In the Java language interface for libSBML, the
893 * type codes are defined as static integer constants in the interface class
894 * {@link libsbmlConstants}.    Note that different Level&nbsp;3
895 * package plug-ins may use overlapping type codes; to identify the package
896 * to which a given object belongs, call the 
897 * <code>{@link SBase#getPackageName()}
898 * </code>
899 * method on the object.
900   <p>
901   * @return the SBML type code for this object:
902   * {@link libsbmlConstants#SBML_SPECIES_REFERENCE SBML_SPECIES_REFERENCE} (default).
903   <p>
904   * @see #getElementName()
905   * @see #getPackageName()
906   */ public
907 int getTypeCode() {
908    return libsbmlJNI.SpeciesReference_getTypeCode(swigCPtr, this);
909  }
910
911  
912/**
913   * Returns the XML element name of this object, which for
914   * {@link SpeciesReference}, is always <code>'speciesReference'.</code>
915   <p>
916   * @return the name of this element, i.e., <code>'speciesReference'.</code>
917   */ public
918 String getElementName() {
919    return libsbmlJNI.SpeciesReference_getElementName(swigCPtr, this);
920  }
921
922  
923/**
924   * Predicate returning <code>true</code> if
925   * all the required attributes for this {@link SpeciesReference} object
926   * have been set.
927   <p>
928   * The required attributes for a {@link SpeciesReference} object are:
929   * <ul>
930   * <li> 'species'
931   * <li> 'constant' (only available SBML Level&nbsp;3)
932   *
933   * </ul> <p>
934   * @return <code>true</code> if the required attributes have been set, <code>false</code>
935   * otherwise.
936   */ public
937 boolean hasRequiredAttributes() {
938    return libsbmlJNI.SpeciesReference_hasRequiredAttributes(swigCPtr, this);
939  }
940
941}