001/* ----------------------------------------------------------------------------
002 * This file was automatically generated by SWIG (http://www.swig.org).
003 * Version 3.0.10
004 *
005 * Do not make changes to this file unless you know what you are doing--modify
006 * the SWIG interface file instead.
007 * ----------------------------------------------------------------------------- */
008
009package org.sbml.libsbml;
010
011/** 
012 *  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 zero (0).  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 Version&nbsp;1 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   <p>
448   * @return the value of the 'denominator' attribute of this
449   * {@link SpeciesReference}.
450   */ public
451 int getDenominator() {
452    return libsbmlJNI.SpeciesReference_getDenominator(swigCPtr, this);
453  }
454
455  
456/**
457   * Get the value of the 'constant' attribute.
458   <p>
459   * @return the value of the 'constant' attribute of this
460   * {@link SpeciesReference}.
461   */ public
462 boolean getConstant() {
463    return libsbmlJNI.SpeciesReference_getConstant(swigCPtr, this);
464  }
465
466  
467/**
468   * Predicate returning <code>true</code> if this
469   * {@link SpeciesReference}'s 'stoichiometryMath' subelement is set
470   <p>
471   * @return <code>true</code> if the 'stoichiometryMath' subelement of this
472   * {@link SpeciesReference} is set, <code>false</code> otherwise.
473   */ public
474 boolean isSetStoichiometryMath() {
475    return libsbmlJNI.SpeciesReference_isSetStoichiometryMath(swigCPtr, this);
476  }
477
478  
479/**
480   * Predicate returning <code>true</code> if this
481   * {@link SpeciesReference}'s 'constant' attribute is set
482   <p>
483   * @return <code>true</code> if the 'constant' attribute of this
484   * {@link SpeciesReference} is set, <code>false</code> otherwise.
485   */ public
486 boolean isSetConstant() {
487    return libsbmlJNI.SpeciesReference_isSetConstant(swigCPtr, this);
488  }
489
490  
491/**
492   * Predicate returning <code>true</code> if this
493   * {@link SpeciesReference}'s 'stoichiometry' attribute is set.
494   <p>
495   * @return <code>true</code> if the 'stoichiometry' attribute of this
496   * {@link SpeciesReference} is set, <code>false</code> otherwise.
497   */ public
498 boolean isSetStoichiometry() {
499    return libsbmlJNI.SpeciesReference_isSetStoichiometry(swigCPtr, this);
500  }
501
502  
503/**
504   * Sets the value of the 'stoichiometry' attribute of this
505   * {@link SpeciesReference}.
506   <p>
507   * In SBML Level 2, product and reactant stoichiometries can be specified
508   * using <em>either</em> 'stoichiometry' or 'stoichiometryMath' in a
509   * {@link SpeciesReference} object.  The former is to be used when a
510   * stoichiometry is simply a scalar number, while the latter is for
511   * occasions when it needs to be a rational number or it needs to
512   * reference other mathematical expressions.  The 'stoichiometry'
513   * attribute is of type <code>double</code> and should contain values greater than
514   * zero (<code>0</code>).  The 'stoichiometryMath' element is implemented as an
515   * element containing a MathML expression.  These two are mutually
516   * exclusive; only one of 'stoichiometry' or 'stoichiometryMath' should
517   * be defined in a given {@link SpeciesReference} instance.  When neither the
518   * attribute nor the element is present, the value of 'stoichiometry' in
519   * the {@link SpeciesReference} instance defaults to <code>1.</code>  For maximum
520   * interoperability between different software tools, the 'stoichiometry'
521   * attribute should be used in preference to 'stoichiometryMath' when a
522   * species' stoichiometry is a simple scalar number (integer or
523   * decimal).
524   <p>
525   * In SBML Level 3, there is no {@link StoichiometryMath}, and {@link SpeciesReference}
526   * objects have only the 'stoichiometry' attribute.
527   <p>
528   * @param value the new value of the 'stoichiometry' attribute
529   <p>
530   * @note In SBML Level&nbsp;2, the 'stoichiometryMath' subelement of this
531   * {@link SpeciesReference} object will be unset because the 'stoichiometry'
532   * attribute and the stoichiometryMath' subelement are mutually
533   * exclusive.
534   <p>
535   * <p>
536 * @return integer value indicating success/failure of the
537 * function.   The possible values
538 * returned by this function are:
539   * <ul>
540   * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS}
541   * </ul>
542   */ public
543 int setStoichiometry(double value) {
544    return libsbmlJNI.SpeciesReference_setStoichiometry(swigCPtr, this, value);
545  }
546
547  
548/**
549   * Sets the 'stoichiometryMath' subelement of this {@link SpeciesReference}.
550   <p>
551   * The Abstract Syntax Tree in <code>math</code> is copied.
552   <p>
553   * In SBML Level 2, product and reactant stoichiometries can be specified
554   * using <em>either</em> 'stoichiometry' or 'stoichiometryMath' in a
555   * {@link SpeciesReference} object.  The former is to be used when a
556   * stoichiometry is simply a scalar number, while the latter is for
557   * occasions when it needs to be a rational number or it needs to
558   * reference other mathematical expressions.  The 'stoichiometry'
559   * attribute is of type <code>double</code> and should contain values greater than
560   * zero (<code>0</code>).  The 'stoichiometryMath' element is implemented as an
561   * element containing a MathML expression.  These two are mutually
562   * exclusive; only one of 'stoichiometry' or 'stoichiometryMath' should
563   * be defined in a given {@link SpeciesReference} instance.  When neither the
564   * attribute nor the element is present, the value of 'stoichiometry' in
565   * the {@link SpeciesReference} instance defaults to <code>1.</code>  For maximum
566   * interoperability between different software tools, the 'stoichiometry'
567   * attribute should be used in preference to 'stoichiometryMath' when a
568   * species' stoichiometry is a simple scalar number (integer or
569   * decimal).
570   <p>
571   * In SBML Level 3, there is no {@link StoichiometryMath}, and {@link SpeciesReference}
572   * objects have only the 'stoichiometry' attribute.
573   <p>
574   * @param math the {@link StoichiometryMath} expression that is to be copied as the
575   * content of the 'stoichiometryMath' subelement.
576   <p>
577   * @note In SBML Level&nbsp;2, the 'stoichiometry' attribute of this
578   * {@link SpeciesReference} object will be unset (isSetStoichiometry() will
579   * return <code>false</code> although getStoichiometry() will return <code>1.0</code>) if the
580   * given math is not null because the 'stoichiometry' attribute and the
581   * stoichiometryMath' subelement are mutually exclusive.
582   <p>
583   * <p>
584 * @return integer value indicating success/failure of the
585 * function.   The possible values
586 * returned by this function are:
587   * <ul>
588   * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS}
589   * <li> {@link libsbmlConstants#LIBSBML_UNEXPECTED_ATTRIBUTE LIBSBML_UNEXPECTED_ATTRIBUTE}
590   * <li> {@link libsbmlConstants#LIBSBML_LEVEL_MISMATCH LIBSBML_LEVEL_MISMATCH}
591   * <li> {@link libsbmlConstants#LIBSBML_VERSION_MISMATCH LIBSBML_VERSION_MISMATCH}
592   * </ul>
593   */ public
594 int setStoichiometryMath(StoichiometryMath math) {
595    return libsbmlJNI.SpeciesReference_setStoichiometryMath(swigCPtr, this, StoichiometryMath.getCPtr(math), math);
596  }
597
598  
599/**
600   * Set the value of the 'denominator' attribute, for the case of a
601   * rational-numbered stoichiometry or a model in SBML Level&nbsp;1.
602   <p>
603   * The 'denominator' attribute is only actually written out in the case
604   * of an SBML Level&nbsp;1 model.  In SBML Level&nbsp;2, rational-number
605   * stoichiometries are written as MathML elements in the
606   * 'stoichiometryMath' subelement.  However, as a convenience to users,
607   * libSBML allows the creation and manipulation of rational-number
608   * stoichiometries by supplying the numerator and denominator directly
609   * rather than having to manually create an {@link ASTNode} object.  LibSBML
610   * will write out the appropriate constructs (either a combination of
611   * 'stoichiometry' and 'denominator' in the case of SBML Level&nbsp;1, or
612   * a 'stoichiometryMath' subelement in the case of SBML Level&nbsp;2).
613   <p>
614   * @param value the scalar value 
615   <p>
616   * <p>
617 * @return integer value indicating success/failure of the
618 * function.   The possible values
619 * returned by this function are:
620   * <ul>
621   * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS}
622   * </ul>
623   */ public
624 int setDenominator(int value) {
625    return libsbmlJNI.SpeciesReference_setDenominator(swigCPtr, this, value);
626  }
627
628  
629/**
630   * Sets the 'constant' attribute of this {@link SpeciesReference} to the given boolean
631   * <code>flag</code>.
632   <p>
633   * @param flag a boolean, the value for the 'constant' attribute of this
634   * {@link SpeciesReference} instance
635   <p>
636   * <p>
637 * @return integer value indicating success/failure of the
638 * function.   The possible values
639 * returned by this function are:
640   * <ul>
641   * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS}
642   * <li> {@link libsbmlConstants#LIBSBML_UNEXPECTED_ATTRIBUTE LIBSBML_UNEXPECTED_ATTRIBUTE}
643   * </ul>
644   */ public
645 int setConstant(boolean flag) {
646    return libsbmlJNI.SpeciesReference_setConstant(swigCPtr, this, flag);
647  }
648
649  
650/**
651   * Unsets the 'stoichiometryMath' subelement of this {@link SpeciesReference}.
652   <p>
653   * <p>
654 * @return integer value indicating success/failure of the
655 * function.   The possible values
656 * returned by this function are:
657   * <ul>
658   * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS}
659   * <li> {@link libsbmlConstants#LIBSBML_UNEXPECTED_ATTRIBUTE LIBSBML_UNEXPECTED_ATTRIBUTE}
660   * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED}
661   *
662   * </ul> <p>
663   * In SBML Level 2, product and reactant stoichiometries can be specified
664   * using <em>either</em> 'stoichiometry' or 'stoichiometryMath' in a
665   * {@link SpeciesReference} object.  The former is to be used when a
666   * stoichiometry is simply a scalar number, while the latter is for
667   * occasions when it needs to be a rational number or it needs to
668   * reference other mathematical expressions.  The 'stoichiometry'
669   * attribute is of type <code>double</code> and should contain values greater than
670   * zero (<code>0</code>).  The 'stoichiometryMath' element is implemented as an
671   * element containing a MathML expression.  These two are mutually
672   * exclusive; only one of 'stoichiometry' or 'stoichiometryMath' should
673   * be defined in a given {@link SpeciesReference} instance.  When neither the
674   * attribute nor the element is present, the value of 'stoichiometry' in
675   * the {@link SpeciesReference} instance defaults to <code>1.</code>  For maximum
676   * interoperability between different software tools, the 'stoichiometry'
677   * attribute should be used in preference to 'stoichiometryMath' when a
678   * species' stoichiometry is a simple scalar number (integer or
679   * decimal).
680   <p>
681   * In SBML Level 3, there is no {@link StoichiometryMath}, and {@link SpeciesReference}
682   * objects have only the 'stoichiometry' attribute.
683   <p>
684   * @note In SBML Level&nbsp;2, the 'stoichiometry' attribute of this
685   * {@link SpeciesReference} object will be reset to a default value (<code>1.0</code>) if
686   * the 'stoichiometry' attribute has not been set.
687   */ public
688 int unsetStoichiometryMath() {
689    return libsbmlJNI.SpeciesReference_unsetStoichiometryMath(swigCPtr, this);
690  }
691
692  
693/**
694   * Unsets the 'stoichiometry' attribute of this {@link SpeciesReference}.
695   <p>
696   * <p>
697 * @return integer value indicating success/failure of the
698 * function.   The possible values
699 * returned by this function are:
700   * <ul>
701   * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS}
702   * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED}
703   *
704   * </ul> <p>
705   * @note In SBML Level&nbsp;1, the 'stoichiometry' attribute of this
706   * {@link SpeciesReference} object will be just reset to a default value (<code>1.0</code>)
707   * and isSetStoichiometry() will still return <code>true.</code>  In SBML
708   * Level&nbsp;2, the 'stoichiometry' attribute of this object will be
709   * unset (which will result in isSetStoichiometry() returning <code>false</code>,
710   * although getStoichiometry() will return <code>1.0</code>) if the
711   * 'stoichiometryMath' subelement is set, otherwise the attribute
712   * will be just reset to the default value (<code>1.0</code>) (and
713   * isSetStoichiometry() will still return <code>true</code>).  In SBML
714   * Level&nbsp;3, the 'stoichiometry' attribute of this object will be set
715   * to <code>NaN</code> and isSetStoichiometry() will return <code>false.</code>
716   */ public
717 int unsetStoichiometry() {
718    return libsbmlJNI.SpeciesReference_unsetStoichiometry(swigCPtr, this);
719  }
720
721  
722/**
723   * Unsets the 'constant' attribute of this {@link SpeciesReference}.
724   <p>
725   * <p>
726 * @return integer value indicating success/failure of the
727 * function.   The possible values
728 * returned by this function are:
729   * <ul>
730   * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS}
731   * <li> {@link libsbmlConstants#LIBSBML_UNEXPECTED_ATTRIBUTE LIBSBML_UNEXPECTED_ATTRIBUTE}
732   * </ul>
733   */ public
734 int unsetConstant() {
735    return libsbmlJNI.SpeciesReference_unsetConstant(swigCPtr, this);
736  }
737
738  
739/**
740   * Creates a new, empty {@link StoichiometryMath} object, adds it to this
741   * {@link SpeciesReference}, and returns it.
742   <p>
743   * @return the newly created {@link StoichiometryMath} object instance
744   <p>
745   * @see Reaction#addReactant(SpeciesReference sr)
746   * @see Reaction#addProduct(SpeciesReference sr)
747   */ public
748 StoichiometryMath createStoichiometryMath() {
749    long cPtr = libsbmlJNI.SpeciesReference_createStoichiometryMath(swigCPtr, this);
750    return (cPtr == 0) ? null : new StoichiometryMath(cPtr, false);
751  }
752
753  
754/**
755   * Sets the value of the 'annotation' subelement of this SBML object to a
756   * copy of <code>annotation</code>.
757   <p>
758   * Any existing content of the 'annotation' subelement is discarded.
759   * Unless you have taken steps to first copy and reconstitute any
760   * existing annotations into the <code>annotation</code> that is about to be
761   * assigned, it is likely that performing such wholesale replacement is
762   * unfriendly towards other software applications whose annotations are
763   * discarded.  An alternative may be to use appendAnnotation().
764   <p>
765   * @param annotation an XML structure that is to be used as the content
766   * of the 'annotation' subelement of this object
767   <p>
768   * <p>
769 * @return integer value indicating success/failure of the
770 * function.   The possible values
771 * returned by this function are:
772   * <ul>
773   * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS}
774   *
775   * </ul> <p>
776   * @see #appendAnnotation(XMLNode annotation)
777   * @see #appendAnnotation(String annotation)
778   */ public
779 int setAnnotation(XMLNode annotation) {
780    return libsbmlJNI.SpeciesReference_setAnnotation__SWIG_0(swigCPtr, this, XMLNode.getCPtr(annotation), annotation);
781  }
782
783  
784/**
785   * Sets the value of the 'annotation' subelement of this SBML object to a
786   * copy of <code>annotation</code>.
787   <p>
788   * Any existing content of the 'annotation' subelement is discarded.
789   * Unless you have taken steps to first copy and reconstitute any
790   * existing annotations into the <code>annotation</code> that is about to be
791   * assigned, it is likely that performing such wholesale replacement is
792   * unfriendly towards other software applications whose annotations are
793   * discarded.  An alternative may be to use appendAnnotation().
794   <p>
795   * @param annotation an XML string that is to be used as the content
796   * of the 'annotation' subelement of this object
797   <p>
798   * <p>
799 * @return integer value indicating success/failure of the
800 * function.   The possible values
801 * returned by this function are:
802   * <ul>
803   * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS}
804   * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED}
805   *
806   * </ul> <p>
807   * @see #appendAnnotation(XMLNode annotation)
808   * @see #appendAnnotation(String annotation)
809   */ public
810 int setAnnotation(String annotation) {
811    return libsbmlJNI.SpeciesReference_setAnnotation__SWIG_1(swigCPtr, this, annotation);
812  }
813
814  
815/**
816   * Appends annotation content to any existing content in the 'annotation'
817   * subelement of this object.
818   <p>
819   * The content in <code>annotation</code> is copied.  Unlike
820   * {@link SpeciesReference#setAnnotation(String)},
821   * this method allows other annotations to be preserved when an application
822   * adds its own data.
823   <p>
824   * @param annotation an XML structure that is to be copied and appended
825   * to the content of the 'annotation' subelement of this object
826   <p>
827   * <p>
828 * @return integer value indicating success/failure of the
829 * function.   The possible values
830 * returned by this function are:
831   * <ul>
832   * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS}
833   * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED}
834   *
835   * </ul> <p>
836   * @see #setAnnotation(String annotation)
837   * @see #setAnnotation(XMLNode annotation)
838   */ public
839 int appendAnnotation(XMLNode annotation) {
840    return libsbmlJNI.SpeciesReference_appendAnnotation__SWIG_0(swigCPtr, this, XMLNode.getCPtr(annotation), annotation);
841  }
842
843  
844/**
845   * Appends annotation content to any existing content in the 'annotation'
846   * subelement of this object.
847   <p>
848   * The content in <code>annotation</code> is copied.  Unlike
849   * {@link SpeciesReference#setAnnotation(String)}, this
850   * method allows other annotations to be preserved when an application
851   * adds its own data.
852   <p>
853   * @param annotation an XML string that is to be copied and appended
854   * to the content of the 'annotation' subelement of this object
855   <p>
856   * <p>
857 * @return integer value indicating success/failure of the
858 * function.   The possible values
859 * returned by this function are:
860   * <ul>
861   * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS}
862   * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED}
863   *
864   * </ul> <p>
865   * @see #setAnnotation(String annotation)
866   * @see #setAnnotation(XMLNode annotation)
867   */ public
868 int appendAnnotation(String annotation) {
869    return libsbmlJNI.SpeciesReference_appendAnnotation__SWIG_1(swigCPtr, this, annotation);
870  }
871
872  
873/**
874   * Returns the libSBML type code for this SBML object.
875   <p>
876   * <p>
877 * LibSBML attaches an identifying code to every kind of SBML object.  These
878 * are integer constants known as <em>SBML type codes</em>.  The names of all
879 * the codes begin with the characters <code>SBML_</code>.
880 * In the Java language interface for libSBML, the
881 * type codes are defined as static integer constants in the interface class
882 * {@link libsbmlConstants}.    Note that different Level&nbsp;3
883 * package plug-ins may use overlapping type codes; to identify the package
884 * to which a given object belongs, call the <code>getPackageName()</code>
885 * method on the object.
886   <p>
887   * @return the SBML type code for this object:
888   * {@link libsbmlConstants#SBML_SPECIES_REFERENCE SBML_SPECIES_REFERENCE} (default).
889   <p>
890   * @see #getElementName()
891   * @see #getPackageName()
892   */ public
893 int getTypeCode() {
894    return libsbmlJNI.SpeciesReference_getTypeCode(swigCPtr, this);
895  }
896
897  
898/**
899   * Returns the XML element name of this object, which for
900   * {@link SpeciesReference}, is always <code>'speciesReference'.</code>
901   <p>
902   * @return the name of this element, i.e., <code>'speciesReference'.</code>
903   */ public
904 String getElementName() {
905    return libsbmlJNI.SpeciesReference_getElementName(swigCPtr, this);
906  }
907
908  
909/**
910   * Predicate returning <code>true</code> if
911   * all the required attributes for this {@link SpeciesReference} object
912   * have been set.
913   <p>
914   * The required attributes for a {@link SpeciesReference} object are:
915   * <ul>
916   * <li> 'species'
917   * <li> 'constant' (only available SBML Level&nbsp;3)
918   *
919   * </ul> <p>
920   * @return <code>true</code> if the required attributes have been set, <code>false</code>
921   * otherwise.
922   */ public
923 boolean hasRequiredAttributes() {
924    return libsbmlJNI.SpeciesReference_hasRequiredAttributes(swigCPtr, this);
925  }
926
927}