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