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