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 KineticLaw construct.
014 * <p>
015 * An object of class {@link KineticLaw} is used to describe the rate at which the
016 * process defined by a given {@link Reaction} takes place.  {@link KineticLaw} has
017 * subelements called 'math' (for MathML content) and 'listOfParameters'
018 * (of class {@link ListOfParameters}), in addition to the attributes and
019 * subelements it inherits from {@link SBase}.
020 * <p>
021 * {@link KineticLaw}'s 'math' subelement for holding a MathML formula defines the
022 * rate of the reaction.  The formula may refer to other entities in a
023 * model as well as local parameter definitions within the scope of the
024 * {@link Reaction} (see below).  It is important to keep in mind, however, that
025 * the only {@link Species} identifiers that can be used in this formula are those
026 * declared in the lists of reactants, products and modifiers in the
027 * {@link Reaction} structure.  (In other words, before a species can be referenced
028 * in the {@link KineticLaw}, it must be declared in one of those lists.)
029 * <p>
030 * {@link KineticLaw} provides a way to define <em>local</em> parameters whose
031 * identifiers can be used in the 'math' formula of that {@link KineticLaw}
032 * instance.  Prior to SBML Level&nbsp;3, these parameter definitions are
033 * stored inside a 'listOfParameters' subelement containing {@link Parameter}
034 * objects; in SBML Level&nbsp;3, this is achieved using a specialized
035 * object class called {@link LocalParameter} and the containing subelement is
036 * called 'listOfLocalParameters'.  In both cases, the parameters so
037 * defined are only visible within the {@link KineticLaw}; they cannot be accessed
038 * outside.  A local parameter within one reaction is not visible from
039 * within another reaction, nor is it visible to any other construct
040 * outside of the {@link KineticLaw} in which it is defined.  In addition, another
041 * important feature is that if such a {@link Parameter} (or in Level&nbsp;3,
042 * {@link LocalParameter}) object has the same identifier as another object in the
043 * scope of the enclosing {@link Model}, the definition inside the {@link KineticLaw} takes
044 * precedence.  In other words, within the {@link KineticLaw}'s 'math' formula,
045 * references to local parameter identifiers <strong>shadow any identical
046 * global identifiers</strong>.
047 * <p>
048 * The values of local parameters defined within {@link KineticLaw} objects cannot
049 * change.  In SBML Level&nbsp;3, this quality is built into the
050 * {@link LocalParameter} construct.  In Level&nbsp;2, where the same kind of
051 * {@link Parameter} object class is used as for global parameters, the {@link Parameter}
052 * objects' 'constant' attribute must always have a value of <code>true</code>
053 * (either explicitly or left to its default value).
054 * <p>
055 * <p>
056 * <h2>A warning about identifier shadowing</h2>
057 * <p>
058 * A common misconception is that different classes of objects (e.g.,
059 * species, compartments, parameters) in SBML have different identifier
060 * scopes.  They do not.  The implication is that if a {@link KineticLaw}'s local
061 * parameter definition uses an identifier identical to <em>any</em> other
062 * identifier defined in the model outside the {@link KineticLaw}, even if the
063 * other identifier does <em>not</em> belong to a parameter type of object, the
064 * local parameter's identifier takes precedence within that {@link KineticLaw}'s
065 * 'math' formula.  It is not an error in SBML for identifiers to shadow
066 * each other this way, but can lead to confusing and subtle errors.
067 * <p>
068 * <p>
069 * <h2>SBML Level/Version differences</h2>
070 * <p>
071 * In SBML Level&nbsp;2 Version&nbsp;1, the SBML specification
072 * included two additional attributes on {@link KineticLaw} called 'substanceUnits'
073 * and 'timeUnits'.  They were removed beginning with SBML Level&nbsp;2
074 * Version&nbsp;2 because further research determined they introduced many
075 * problems.  The most significant problem was that their use could easily
076 * lead to the creation of valid models whose reactions nevertheless could
077 * not be integrated into a system of equations without outside knowledge
078 * for converting the quantities used.  Examination of real-life models
079 * revealed that a common reason for using 'substanceUnits' on {@link KineticLaw}
080 * was to set the units of all reactions to the same set of substance
081 * units, something that is better achieved by using {@link UnitDefinition} to
082 * redefine <code>'substance'</code> for the whole {@link Model}.
083 * <p>
084 * As mentioned above, in SBML Level&nbsp;2 Versions 2&ndash;4, local
085 * parameters are of class {@link Parameter}.  In SBML Level&nbsp;3, the class of
086 * object is {@link LocalParameter}.
087 */
088
089public class KineticLaw extends SBase {
090   private long swigCPtr;
091
092   protected KineticLaw(long cPtr, boolean cMemoryOwn)
093   {
094     super(libsbmlJNI.KineticLaw_SWIGUpcast(cPtr), cMemoryOwn);
095     swigCPtr = cPtr;
096   }
097
098   protected static long getCPtr(KineticLaw obj)
099   {
100     return (obj == null) ? 0 : obj.swigCPtr;
101   }
102
103   protected static long getCPtrAndDisown (KineticLaw obj)
104   {
105     long ptr = 0;
106
107     if (obj != null)
108     {
109       ptr             = obj.swigCPtr;
110       obj.swigCMemOwn = false;
111     }
112
113     return ptr;
114   }
115
116  protected void finalize() {
117    delete();
118  }
119
120  public synchronized void delete() {
121    if (swigCPtr != 0) {
122      if (swigCMemOwn) {
123        swigCMemOwn = false;
124        libsbmlJNI.delete_KineticLaw(swigCPtr);
125      }
126      swigCPtr = 0;
127    }
128    super.delete();
129  }
130
131  
132/**
133   * Creates a new {@link KineticLaw} using the given SBML <code>level</code> and <code>version</code>
134   * values.
135   * <p>
136   * @param level a long integer, the SBML Level to assign to this {@link KineticLaw}
137   * <p>
138   * @param version a long integer, the SBML Version to assign to this
139   * {@link KineticLaw}
140   * <p>
141   * @throws SBMLConstructorException 
142   * Thrown if the given <code>level</code> and <code>version</code> combination, or this kind
143   * of SBML object, are either invalid or mismatched with respect to the
144   * parent {@link SBMLDocument} object.
145   * <p>
146   * @note Upon the addition of a {@link KineticLaw} object to an {@link SBMLDocument}
147   * (e.g., using {@link Reaction#setKineticLaw(KineticLaw kl)}), the SBML Level, SBML Version
148   * and XML namespace of the document <em>override</em> the values used
149   * when creating the {@link KineticLaw} object via this constructor.  This is
150   * necessary to ensure that an SBML document is a consistent structure.
151   * Nevertheless, the ability to supply the values at the time of creation
152   * of a {@link KineticLaw} is an important aid to producing valid SBML.  Knowledge
153   * of the intented SBML Level and Version determine whether it is valid
154   * to assign a particular value to an attribute, or whether it is valid
155   * to add an object to an existing {@link SBMLDocument}.
156   */ public
157 KineticLaw(long level, long version) throws org.sbml.libsbml.SBMLConstructorException {
158    this(libsbmlJNI.new_KineticLaw__SWIG_0(level, version), true);
159  }
160
161  
162/**
163   * Creates a new {@link KineticLaw} using the given {@link SBMLNamespaces} object
164   * <code>sbmlns</code>.
165   * <p>
166   * The {@link SBMLNamespaces} object encapsulates SBML Level/Version/namespaces
167   * information.  It is used to communicate the SBML Level, Version, and
168   * (in Level&nbsp;3) packages used in addition to SBML Level&nbsp;3 Core.
169   * A common approach to using this class constructor is to create an
170   * {@link SBMLNamespaces} object somewhere in a program, once, then pass it to
171   * object constructors such as this one when needed.
172   * <p>
173   * @param sbmlns an {@link SBMLNamespaces} object.
174   * <p>
175   * @throws SBMLConstructorException 
176   * Thrown if the given <code>level</code> and <code>version</code> combination, or this kind
177   * of SBML object, are either invalid or mismatched with respect to the
178   * parent {@link SBMLDocument} object.
179   * <p>
180   * @note Upon the addition of a {@link KineticLaw} object to an {@link SBMLDocument}
181   * (e.g., using {@link Reaction#setKineticLaw(KineticLaw kl)}), the SBML XML namespace of the
182   * document <em>overrides</em> the value used when creating the {@link KineticLaw}
183   * object via this constructor.  This is necessary to ensure that an SBML
184   * document is a consistent structure.  Nevertheless, the ability to
185   * supply the values at the time of creation of a {@link KineticLaw} is an
186   * important aid to producing valid SBML.  Knowledge of the intented SBML
187   * Level and Version determine whether it is valid to assign a particular
188   * value to an attribute, or whether it is valid to add an object to an
189   * existing {@link SBMLDocument}.
190   */ public
191 KineticLaw(SBMLNamespaces sbmlns) throws org.sbml.libsbml.SBMLConstructorException {
192    this(libsbmlJNI.new_KineticLaw__SWIG_1(SBMLNamespaces.getCPtr(sbmlns), sbmlns), true);
193  }
194
195  
196/**
197   * Copy constructor; creates a copy of this {@link KineticLaw}.
198   * <p>
199   * @param orig the object to copy.
200   * <p>
201   * @throws SBMLConstructorException 
202   * Thrown if the argument <code>orig</code> is <code>null.</code>
203   */ public
204 KineticLaw(KineticLaw orig) throws org.sbml.libsbml.SBMLConstructorException {
205    this(libsbmlJNI.new_KineticLaw__SWIG_2(KineticLaw.getCPtr(orig), orig), true);
206  }
207
208  
209/**
210   * Creates and returns a deep copy of this {@link KineticLaw} object.
211   * <p>
212   * @return a (deep) copy of this {@link KineticLaw}.
213   */ public
214 KineticLaw cloneObject() {
215    long cPtr = libsbmlJNI.KineticLaw_cloneObject(swigCPtr, this);
216    return (cPtr == 0) ? null : new KineticLaw(cPtr, true);
217  }
218
219  
220/**
221   * Returns the first child element found that has the given <code>id</code> in the model-wide SId namespace, or <code>null</code> if no such object is found.
222   * <p>
223   * @param id string representing the id of objects to find.
224   * <p>
225   * @return pointer to the first element found with the given <code>id</code>.
226   */ public
227 SBase getElementBySId(String id) {
228  return libsbml.DowncastSBase(libsbmlJNI.KineticLaw_getElementBySId(swigCPtr, this, id), false);
229}
230
231  
232/**
233   * Returns the first child element it can find with the given <code>metaid</code>, or <code>null</code> if no such object is found.
234   * <p>
235   * @param metaid string representing the metaid of objects to find
236   * <p>
237   * @return pointer to the first element found with the given <code>metaid</code>.
238   */ public
239 SBase getElementByMetaId(String metaid) {
240  return libsbml.DowncastSBase(libsbmlJNI.KineticLaw_getElementByMetaId(swigCPtr, this, metaid), false);
241}
242
243  
244/**
245   * Returns the mathematical formula for this {@link KineticLaw} object and return
246   * it as as a text string.
247   * <p>
248   * This is fundamentally equivalent to
249   * {@link KineticLaw#getMath()}.
250   * This variant is provided principally for compatibility compatibility
251   * with SBML Level&nbsp;1.
252   * <p>
253   * @return a string representing the formula of this {@link KineticLaw}.
254   * <p>
255   * @note SBML Level&nbsp;1 uses a text-string format for mathematical formulas.
256SBML Level&nbsp;2 uses MathML, an XML format for representing mathematical
257expressions.  LibSBML provides an Abstract Syntax Tree API for working with
258mathematical expressions; this API is more powerful than working with
259formulas directly in text form, and ASTs can be translated into either
260MathML or the text-string syntax.  The libSBML methods that accept
261text-string formulas directly (such as this constructor) are provided for
262SBML Level&nbsp;1 compatibility, but developers are encouraged to use the
263AST mechanisms.
264
265   * <p>
266   * @see #getMath()
267   */ public
268 String getFormula() {
269    return libsbmlJNI.KineticLaw_getFormula(swigCPtr, this);
270  }
271
272  
273/**
274   * Returns the mathematical formula for this {@link KineticLaw} object and return
275   * it as as an AST.
276   * <p>
277   * This is fundamentally equivalent to
278   * {@link KineticLaw#getFormula()}.
279   * The latter is provided principally for compatibility compatibility
280   * with SBML Level&nbsp;1, which represented mathematical formulas in
281   * text-string form.
282   * <p>
283   * @return the {@link ASTNode} representation of the mathematical formula.
284   * <p>
285   * @see #getFormula()
286   */ public
287 ASTNode getMath() {
288    long cPtr = libsbmlJNI.KineticLaw_getMath(swigCPtr, this);
289    return (cPtr == 0) ? null : new ASTNode(cPtr, false);
290  }
291
292  
293/**
294   * (SBML Level&nbsp;2 Version&nbsp;1 only) Returns the value of the
295   * 'timeUnits' attribute of this {@link KineticLaw} object.
296   * <p>
297   * @return the 'timeUnits' attribute value.
298   * <p>
299   * @note The attributes 'timeUnits' and 'substanceUnits' are present only
300   * in SBML Level&nbsp;2 Version&nbsp;1.  In SBML Level&nbsp;2
301   * Version&nbsp;2, the 'timeUnits' and 'substanceUnits' attributes were
302   * removed.  For compatibility with new versions of SBML, users are
303   * cautioned to avoid these attributes.
304   */ public
305 String getTimeUnits() {
306    return libsbmlJNI.KineticLaw_getTimeUnits(swigCPtr, this);
307  }
308
309  
310/**
311   * (SBML Level&nbsp;2 Version&nbsp;1 only) Returns the value of the
312   * 'substanceUnits' attribute of this {@link KineticLaw} object.
313   * <p>
314   * @return the 'substanceUnits' attribute value.
315   * <p>
316   * @note The attributes 'timeUnits' and 'substanceUnits' are present only
317   * in SBML Level&nbsp;2 Version&nbsp;1.  In SBML Level&nbsp;2
318   * Version&nbsp;2, the 'timeUnits' and 'substanceUnits' attributes were
319   * removed.  For compatibility with new versions of SBML, users are
320   * cautioned to avoid these attributes.
321   */ public
322 String getSubstanceUnits() {
323    return libsbmlJNI.KineticLaw_getSubstanceUnits(swigCPtr, this);
324  }
325
326  
327/**
328   * Predicate returning <code>true</code> if this
329   * {@link KineticLaw}'s 'formula' attribute is set.
330   * <p>
331   * This is functionally identical to the method
332   * {@link KineticLaw#isSetMath()}.  It is
333   * provided in order to mirror the parallel between
334   * {@link KineticLaw#getFormula()} and
335   * {@link KineticLaw#getMath()}.
336   * <p>
337   * @return <code>true</code> if the formula (meaning the <code>math</code> subelement) of
338   * this {@link KineticLaw} is set, <code>false</code> otherwise.
339   * <p>
340   * @note SBML Level&nbsp;1 uses a text-string format for mathematical formulas.
341SBML Level&nbsp;2 uses MathML, an XML format for representing mathematical
342expressions.  LibSBML provides an Abstract Syntax Tree API for working with
343mathematical expressions; this API is more powerful than working with
344formulas directly in text form, and ASTs can be translated into either
345MathML or the text-string syntax.  The libSBML methods that accept
346text-string formulas directly (such as this constructor) are provided for
347SBML Level&nbsp;1 compatibility, but developers are encouraged to use the
348AST mechanisms.
349
350   * <p>
351   * @see #isSetMath()
352   */ public
353 boolean isSetFormula() {
354    return libsbmlJNI.KineticLaw_isSetFormula(swigCPtr, this);
355  }
356
357  
358/**
359   * Predicate returning <code>true</code> if this
360   * Kinetic's 'math' subelement is set.
361   * <p>
362   * This is identical to the method
363   * {@link KineticLaw#isSetFormula()}.
364   * It is provided in order to mirror the parallel between
365   * {@link KineticLaw#getFormula()} and
366   * {@link KineticLaw#getMath()}.
367   * <p>
368   * @return <code>true</code> if the formula (meaning the <code>math</code> subelement) of
369   * this {@link KineticLaw} is set, <code>false</code> otherwise.
370   * <p>
371   * @see #isSetFormula()
372   */ public
373 boolean isSetMath() {
374    return libsbmlJNI.KineticLaw_isSetMath(swigCPtr, this);
375  }
376
377  
378/**
379   * (SBML Level&nbsp;2 Version&nbsp;1 only) Predicate returning <code>true</code> if
380   * this {@link SpeciesReference}'s 'timeUnits' attribute is set.
381   * <p>
382   * @return <code>true</code> if the 'timeUnits' attribute of this {@link KineticLaw} object
383   * is set, <code>false</code> otherwise.
384   * <p>
385   * @note The attributes 'timeUnits' and 'substanceUnits' are present only
386   * in SBML Level&nbsp;2 Version&nbsp;1.  In SBML Level&nbsp;2
387   * Version&nbsp;2, the 'timeUnits' and 'substanceUnits' attributes were
388   * removed.  For compatibility with new versions of SBML, users are
389   * cautioned to avoid these attributes.
390   */ public
391 boolean isSetTimeUnits() {
392    return libsbmlJNI.KineticLaw_isSetTimeUnits(swigCPtr, this);
393  }
394
395  
396/**
397   * (SBML Level&nbsp;2 Version&nbsp;1 only) Predicate returning <code>true</code> if
398   * this {@link SpeciesReference}'s 'substanceUnits' attribute is set.
399   * <p>
400   * @return <code>true</code> if the 'substanceUnits' attribute of this {@link KineticLaw}
401   * object is set, <code>false</code> otherwise.
402   * <p>
403   * @note The attributes 'timeUnits' and 'substanceUnits' are present only
404   * in SBML Level&nbsp;2 Version&nbsp;1.  In SBML Level&nbsp;2
405   * Version&nbsp;2, the 'timeUnits' and 'substanceUnits' attributes were
406   * removed.  For compatibility with new versions of SBML, users are
407   * cautioned to avoid these attributes.
408   */ public
409 boolean isSetSubstanceUnits() {
410    return libsbmlJNI.KineticLaw_isSetSubstanceUnits(swigCPtr, this);
411  }
412
413  
414/**
415   * Sets the mathematical expression of this {@link KineticLaw} instance to the
416   * given <code>formula</code>.
417   * <p>
418   * The given <code>formula</code> string is copied.  Internally, libSBML stores the
419   * mathematical expression as an {@link ASTNode}.
420   * <p>
421   * @param formula the mathematical expression to use, represented in
422   * text-string form.
423   * <p>
424   * @return integer value indicating success/failure of the
425   * function. The possible values
426   * returned by this function are:
427   * <ul>
428   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS }
429   * <li> {@link  libsbmlConstants#LIBSBML_INVALID_OBJECT LIBSBML_INVALID_OBJECT }
430   * </ul>
431   * <p>
432   * @note SBML Level&nbsp;1 uses a text-string format for mathematical formulas.
433SBML Level&nbsp;2 uses MathML, an XML format for representing mathematical
434expressions.  LibSBML provides an Abstract Syntax Tree API for working with
435mathematical expressions; this API is more powerful than working with
436formulas directly in text form, and ASTs can be translated into either
437MathML or the text-string syntax.  The libSBML methods that accept
438text-string formulas directly (such as this constructor) are provided for
439SBML Level&nbsp;1 compatibility, but developers are encouraged to use the
440AST mechanisms.
441
442   * <p>
443   * @see #setMath(ASTNode math)
444   */ public
445 int setFormula(String formula) {
446    return libsbmlJNI.KineticLaw_setFormula(swigCPtr, this, formula);
447  }
448
449  
450/**
451   * Sets the mathematical expression of this {@link KineticLaw} instance to a copy
452   * of the given {@link ASTNode}.
453   * <p>
454   * This is fundamentally identical to
455   * {@link KineticLaw#setFormula(String formula)}.
456   * The latter is provided principally for compatibility compatibility with
457   * SBML Level&nbsp;1, which represented mathematical formulas in text-string
458   * form.
459   * <p>
460   * @param math an {@link ASTNode} representing a formula tree.
461   * <p>
462   * @return integer value indicating success/failure of the
463   * function. The possible values
464   * returned by this function are:
465   * <ul>
466   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS }
467   * <li> {@link  libsbmlConstants#LIBSBML_INVALID_OBJECT LIBSBML_INVALID_OBJECT }
468   * </ul>
469   * <p>
470   * @see #setFormula(String formula)
471   */ public
472 int setMath(ASTNode math) {
473    return libsbmlJNI.KineticLaw_setMath(swigCPtr, this, ASTNode.getCPtr(math), math);
474  }
475
476  
477/**
478   * (SBML Level&nbsp;2 Version&nbsp;1 only) Sets the 'timeUnits' attribute
479   * of this {@link KineticLaw} object to a copy of the identifier in <code>sid</code>.
480   * <p>
481   * @param sid the identifier of the units to use.
482   * <p>
483   * @return integer value indicating success/failure of the
484   * function. The possible values
485   * returned by this function are:
486   * <ul>
487   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS }
488   * <li> {@link  libsbmlConstants#LIBSBML_INVALID_ATTRIBUTE_VALUE LIBSBML_INVALID_ATTRIBUTE_VALUE }
489   * <li> {@link  libsbmlConstants#LIBSBML_UNEXPECTED_ATTRIBUTE LIBSBML_UNEXPECTED_ATTRIBUTE }
490   * </ul>
491   * <p>
492   * @note The attributes 'timeUnits' and 'substanceUnits' are present only
493   * in SBML Level&nbsp;2 Version&nbsp;1.  In SBML Level&nbsp;2
494   * Version&nbsp;2, the 'timeUnits' and 'substanceUnits' attributes were
495   * removed.  For compatibility with new versions of SBML, users are
496   * cautioned to avoid these attributes.
497   */ public
498 int setTimeUnits(String sid) {
499    return libsbmlJNI.KineticLaw_setTimeUnits(swigCPtr, this, sid);
500  }
501
502  
503/**
504   * (SBML Level&nbsp;2 Version&nbsp;1 only) Sets the 'substanceUnits'
505   * attribute of this {@link KineticLaw} object to a copy of the identifier given
506   * in <code>sid</code>.
507   * <p>
508   * @param sid the identifier of the units to use.
509   * <p>
510   * @return integer value indicating success/failure of the
511   * function. The possible values
512   * returned by this function are:
513   * <ul>
514   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS }
515   * <li> {@link  libsbmlConstants#LIBSBML_INVALID_ATTRIBUTE_VALUE LIBSBML_INVALID_ATTRIBUTE_VALUE }
516   * <li> {@link  libsbmlConstants#LIBSBML_UNEXPECTED_ATTRIBUTE LIBSBML_UNEXPECTED_ATTRIBUTE }
517   * </ul>
518   * <p>
519   * @note The attributes 'timeUnits' and 'substanceUnits' are present only
520   * in SBML Level&nbsp;2 Version&nbsp;1.  In SBML Level&nbsp;2
521   * Version&nbsp;2, the 'timeUnits' and 'substanceUnits' attributes were
522   * removed.  For compatibility with new versions of SBML, users are
523   * cautioned to avoid these attributes.
524   */ public
525 int setSubstanceUnits(String sid) {
526    return libsbmlJNI.KineticLaw_setSubstanceUnits(swigCPtr, this, sid);
527  }
528
529  
530/**
531   * (SBML Level&nbsp;2 Version&nbsp;1 only) Unsets the 'timeUnits'
532   * attribugte of this {@link KineticLaw} object.
533   * <p>
534   * @return integer value indicating success/failure of the
535   * function. The possible values
536   * returned by this function are:
537   * <ul>
538   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS }
539   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED }
540   * <li> {@link  libsbmlConstants#LIBSBML_UNEXPECTED_ATTRIBUTE LIBSBML_UNEXPECTED_ATTRIBUTE }
541   * </ul>
542   * <p>
543   * @note The attributes 'timeUnits' and 'substanceUnits' are present only
544   * in SBML Level&nbsp;2 Version&nbsp;1.  In SBML Level&nbsp;2
545   * Version&nbsp;2, the 'timeUnits' and 'substanceUnits' attributes were
546   * removed.  For compatibility with new versions of SBML, users are
547   * cautioned to avoid these attributes.
548   */ public
549 int unsetTimeUnits() {
550    return libsbmlJNI.KineticLaw_unsetTimeUnits(swigCPtr, this);
551  }
552
553  
554/**
555   * (SBML Level&nbsp;2 Version&nbsp;1 only) Unsets the 'substanceUnits'
556   * attribute of this {@link KineticLaw} object.
557   * <p>
558   * @return integer value indicating success/failure of the
559   * function. The possible values
560   * returned by this function are:
561   * <ul>
562   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS }
563   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED }
564   * <li> {@link  libsbmlConstants#LIBSBML_UNEXPECTED_ATTRIBUTE LIBSBML_UNEXPECTED_ATTRIBUTE }
565   * </ul>
566   * <p>
567   * @note The attributes 'timeUnits' and 'substanceUnits' are present only
568   * in SBML Level&nbsp;2 Version&nbsp;1.  In SBML Level&nbsp;2
569   * Version&nbsp;2, the 'timeUnits' and 'substanceUnits' attributes were
570   * removed.  For compatibility with new versions of SBML, users are
571   * cautioned to avoid these attributes.
572   */ public
573 int unsetSubstanceUnits() {
574    return libsbmlJNI.KineticLaw_unsetSubstanceUnits(swigCPtr, this);
575  }
576
577  
578/**
579   * Adds a copy of the given {@link Parameter} object to the list of local
580   * parameters in this {@link KineticLaw}.
581   * <p>
582   * @param p the {@link Parameter} to add
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_LEVEL_MISMATCH LIBSBML_LEVEL_MISMATCH }
590   * <li> {@link  libsbmlConstants#LIBSBML_VERSION_MISMATCH LIBSBML_VERSION_MISMATCH }
591   * <li> {@link  libsbmlConstants#LIBSBML_DUPLICATE_OBJECT_ID LIBSBML_DUPLICATE_OBJECT_ID }
592   * <li> {@link  libsbmlConstants#LIBSBML_INVALID_OBJECT LIBSBML_INVALID_OBJECT }
593   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED }
594   * </ul>
595   * <p>
596   * @note This method should be used with some caution.  The fact that
597   * this method <em>copies</em> the object passed to it means that the caller
598   * will be left holding a physically different object instance than the
599   * one contained in this {@link KineticLaw}.  Changes made to the original object
600   * instance (such as resetting attribute values) will <em>not affect the
601   * instance in the {@link KineticLaw}</em>.  In addition, the caller should make
602   * sure to free the original object if it is no longer being used, or
603   * else a memory leak will result.  Please see
604   * {@link KineticLaw#createParameter()}
605   * for a method that does not lead to these issues.
606   * <p>
607   * @see #createParameter()
608   */ public
609 int addParameter(Parameter p) {
610    return libsbmlJNI.KineticLaw_addParameter(swigCPtr, this, Parameter.getCPtr(p), p);
611  }
612
613  
614/**
615   * Adds a copy of the given {@link LocalParameter} object to the list of local
616   * parameters in this {@link KineticLaw}.
617   * <p>
618   * @param p the {@link LocalParameter} to add
619   * <p>
620   * @return integer value indicating success/failure of the
621   * function. The possible values
622   * returned by this function are:
623   * <ul>
624   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS }
625   * <li> {@link  libsbmlConstants#LIBSBML_LEVEL_MISMATCH LIBSBML_LEVEL_MISMATCH }
626   * <li> {@link  libsbmlConstants#LIBSBML_VERSION_MISMATCH LIBSBML_VERSION_MISMATCH }
627   * <li> {@link  libsbmlConstants#LIBSBML_DUPLICATE_OBJECT_ID LIBSBML_DUPLICATE_OBJECT_ID }
628   * <li> {@link  libsbmlConstants#LIBSBML_INVALID_OBJECT LIBSBML_INVALID_OBJECT }
629   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED }
630   * </ul>
631   * <p>
632   * @note This method should be used with some caution.  The fact that
633   * this method <em>copies</em> the object passed to it means that the caller
634   * will be left holding a physically different object instance than the
635   * one contained in this {@link KineticLaw}.  Changes made to the original object
636   * instance (such as resetting attribute values) will <em>not affect the
637   * instance in the {@link KineticLaw}</em>.  In addition, the caller should make
638   * sure to free the original object if it is no longer being used, or
639   * else a memory leak will result.  Please see
640   * {@link KineticLaw#createParameter()}
641   * for a method that does not lead to these issues.
642   * <p>
643   * @see #createLocalParameter()
644   */ public
645 int addLocalParameter(LocalParameter p) {
646    return libsbmlJNI.KineticLaw_addLocalParameter(swigCPtr, this, LocalParameter.getCPtr(p), p);
647  }
648
649  
650/**
651   * Creates a new {@link Parameter} object, adds it to this {@link KineticLaw}'s list of
652   * local parameters, and returns the {@link Parameter} object created.
653   * <p>
654   * @return a new {@link Parameter} object instance
655   * <p>
656   * @see #addParameter(Parameter p)
657   */ public
658 Parameter createParameter() {
659    long cPtr = libsbmlJNI.KineticLaw_createParameter(swigCPtr, this);
660    return (cPtr == 0) ? null : new Parameter(cPtr, false);
661  }
662
663  
664/**
665   * Creates a new {@link LocalParameter} object, adds it to this {@link KineticLaw}'s list
666   * of local parameters, and returns the {@link LocalParameter} object created.
667   * <p>
668   * @return a new {@link LocalParameter} object instance
669   * <p>
670   * @see #addLocalParameter(LocalParameter p)
671   */ public
672 LocalParameter createLocalParameter() {
673    long cPtr = libsbmlJNI.KineticLaw_createLocalParameter(swigCPtr, this);
674    return (cPtr == 0) ? null : new LocalParameter(cPtr, false);
675  }
676
677  
678/**
679   * Returns the list of local parameters in this {@link KineticLaw} object.
680   * <p>
681   * @return the list of Parameters for this {@link KineticLaw}.
682   */ public
683 ListOfParameters getListOfParameters() {
684    long cPtr = libsbmlJNI.KineticLaw_getListOfParameters__SWIG_0(swigCPtr, this);
685    return (cPtr == 0) ? null : new ListOfParameters(cPtr, false);
686  }
687
688  
689/**
690   * Returns the list of local parameters in this {@link KineticLaw} object.
691   * <p>
692   * @return the list of LocalParameters for this {@link KineticLaw}.
693   */ public
694 ListOfLocalParameters getListOfLocalParameters() {
695    long cPtr = libsbmlJNI.KineticLaw_getListOfLocalParameters__SWIG_0(swigCPtr, this);
696    return (cPtr == 0) ? null : new ListOfLocalParameters(cPtr, false);
697  }
698
699  
700/**
701   * Returns the nth {@link Parameter} object in the list of local parameters in
702   * this {@link KineticLaw} instance.
703   * <p>
704   * @param n the index of the {@link Parameter} object sought
705   * <p>
706   * @return the nth {@link Parameter} of this {@link KineticLaw}.
707   */ public
708 Parameter getParameter(long n) {
709    long cPtr = libsbmlJNI.KineticLaw_getParameter__SWIG_0(swigCPtr, this, n);
710    return (cPtr == 0) ? null : new Parameter(cPtr, false);
711  }
712
713  
714/**
715   * Returns the nth {@link LocalParameter} object in the list of local parameters in
716   * this {@link KineticLaw} instance.
717   * <p>
718   * @param n the index of the {@link LocalParameter} object sought
719   * <p>
720   * @return the nth {@link LocalParameter} of this {@link KineticLaw}.
721   */ public
722 LocalParameter getLocalParameter(long n) {
723    long cPtr = libsbmlJNI.KineticLaw_getLocalParameter__SWIG_0(swigCPtr, this, n);
724    return (cPtr == 0) ? null : new LocalParameter(cPtr, false);
725  }
726
727  
728/**
729   * Returns a local parameter based on its identifier.
730   * <p>
731   * @param sid the identifier of the {@link Parameter} being sought.
732   * <p>
733   * @return the {@link Parameter} object in this {@link KineticLaw} instace having the
734   * given 'id', or <code>null</code> if no such {@link Parameter} exists.
735   */ public
736 Parameter getParameter(String sid) {
737    long cPtr = libsbmlJNI.KineticLaw_getParameter__SWIG_2(swigCPtr, this, sid);
738    return (cPtr == 0) ? null : new Parameter(cPtr, false);
739  }
740
741  
742/**
743   * Returns a local parameter based on its identifier.
744   * <p>
745   * @param sid the identifier of the {@link LocalParameter} being sought.
746   * <p>
747   * @return the {@link LocalParameter} object in this {@link KineticLaw} instace having the
748   * given 'id', or <code>null</code> if no such {@link LocalParameter} exists.
749   */ public
750 LocalParameter getLocalParameter(String sid) {
751    long cPtr = libsbmlJNI.KineticLaw_getLocalParameter__SWIG_2(swigCPtr, this, sid);
752    return (cPtr == 0) ? null : new LocalParameter(cPtr, false);
753  }
754
755  
756/**
757   * Returns the number of local parameters in this {@link KineticLaw} instance.
758   * <p>
759   * @return the number of Parameters in this {@link KineticLaw}.
760   */ public
761 long getNumParameters() {
762    return libsbmlJNI.KineticLaw_getNumParameters(swigCPtr, this);
763  }
764
765  
766/**
767   * Returns the number of local parameters in this {@link KineticLaw} instance.
768   * <p>
769   * @return the number of LocalParameters in this {@link KineticLaw}.
770   */ public
771 long getNumLocalParameters() {
772    return libsbmlJNI.KineticLaw_getNumLocalParameters(swigCPtr, this);
773  }
774
775  
776/**
777   * Calculates and returns a {@link UnitDefinition} that expresses the units
778   * of measurement assumed for the 'math' expression of this
779   * {@link KineticLaw}.
780   * <p>
781   * The units are calculated based on the mathematical expression in the
782   * {@link KineticLaw} and the model quantities referenced by
783   * <code>&lt;ci&gt;</code> elements used within that expression.  The
784   * {@link KineticLaw#getDerivedUnitDefinition()}
785   * method returns the calculated units.
786   * <p>
787   * Note that the functionality that facilitates unit analysis depends 
788   * on the model as a whole.  Thus, in cases where the object has not 
789   * been added to a model or the model itself is incomplete,
790   * unit analysis is not possible and this method will return <code>null.</code>
791   * <p>
792   * @warning Note that it is possible the 'math' expression in the
793   * {@link KineticLaw} contains pure numbers or parameters with undeclared
794   * units.  In those cases, it is not possible to calculate the units of
795   * the overall expression without making assumptions.  LibSBML does not
796   * make assumptions about the units, and
797   * {@link KineticLaw#getDerivedUnitDefinition()}
798   * only returns the units as far as it is able to determine them.  For
799   * example, in an expression <em>X + Y</em>, if <em>X</em> has
800   * unambiguously-defined units and <em>Y</em> does not, it will return
801   * the units of <em>X</em>.  <strong>It is important that callers also
802   * invoke the method</strong>
803   * {@link KineticLaw#containsUndeclaredUnits()}
804   * <strong>to determine whether this situation holds</strong>.  Callers may
805   * wish to take suitable actions in those scenarios.
806   * <p>
807   * @return a {@link UnitDefinition} that expresses the units of the math 
808   * expression of this {@link KineticLaw}, or <code>null</code> if one cannot be constructed.
809   * <p>
810   * @see #containsUndeclaredUnits()
811   */ public
812 UnitDefinition getDerivedUnitDefinition() {
813    long cPtr = libsbmlJNI.KineticLaw_getDerivedUnitDefinition__SWIG_0(swigCPtr, this);
814    return (cPtr == 0) ? null : new UnitDefinition(cPtr, false);
815  }
816
817  
818/**
819   * Predicate returning <code>true</code> if 
820   * the math expression of this {@link KineticLaw} contains
821   * parameters/numbers with undeclared units.
822   * <p>
823   * @return <code>true</code> if the math expression of this {@link KineticLaw}
824   * includes parameters/numbers 
825   * with undeclared units, <code>false</code> otherwise.
826   * <p>
827   * @note A return value of <code>true</code> indicates that the {@link UnitDefinition}
828   * returned by
829   * {@link KineticLaw#getDerivedUnitDefinition()}
830   * may not accurately represent the units of the expression.
831   * <p>
832   * @see #getDerivedUnitDefinition()
833   */ public
834 boolean containsUndeclaredUnits() {
835    return libsbmlJNI.KineticLaw_containsUndeclaredUnits__SWIG_0(swigCPtr, this);
836  }
837
838  
839/**
840   * Removes the nth {@link Parameter} object in the list of local parameters 
841   * in this {@link KineticLaw} instance and returns a pointer to it.
842   * <p>
843   * The caller owns the returned object and is responsible for deleting it.
844   * <p>
845   * @param n the index of the {@link Parameter} object to remove
846   * <p>
847   * @return the {@link Parameter} object removed.  As mentioned above, 
848   * the caller owns the returned item. <code>null</code> is returned if the given index 
849   * is out of range.
850   */ public
851 Parameter removeParameter(long n) {
852    long cPtr = libsbmlJNI.KineticLaw_removeParameter__SWIG_0(swigCPtr, this, n);
853    return (cPtr == 0) ? null : new Parameter(cPtr, true);
854  }
855
856  
857/**
858   * Removes the nth {@link LocalParameter} object in the list of local parameters 
859   * in this {@link KineticLaw} instance and returns a pointer to it.
860   * <p>
861   * The caller owns the returned object and is responsible for deleting it.
862   * <p>
863   * @param n the index of the {@link LocalParameter} object to remove
864   * <p>
865   * @return the {@link LocalParameter} object removed.  As mentioned above, 
866   * the caller owns the returned item. <code>null</code> is returned if the given index 
867   * is out of range.
868   */ public
869 LocalParameter removeLocalParameter(long n) {
870    long cPtr = libsbmlJNI.KineticLaw_removeLocalParameter__SWIG_0(swigCPtr, this, n);
871    return (cPtr == 0) ? null : new LocalParameter(cPtr, true);
872  }
873
874  
875/**
876   * Removes a {@link Parameter} object with the given identifier in the list of
877   * local parameters in this {@link KineticLaw} instance and returns a pointer to it.
878   * <p>
879   * The caller owns the returned object and is responsible for deleting it.
880   * <p>
881   * @param sid the identifier of the {@link Parameter} to remove
882   * <p>
883   * @return the {@link Parameter} object removed.  As mentioned above, the 
884   * caller owns the returned object. <code>null</code> is returned if no {@link Parameter}
885   * object with the identifier exists in this {@link KineticLaw} instance.
886   */ public
887 Parameter removeParameter(String sid) {
888    long cPtr = libsbmlJNI.KineticLaw_removeParameter__SWIG_1(swigCPtr, this, sid);
889    return (cPtr == 0) ? null : new Parameter(cPtr, true);
890  }
891
892  
893/**
894   * Removes a {@link LocalParameter} object with the given identifier in the list of
895   * local parameters in this {@link KineticLaw} instance and returns a pointer to it.
896   * <p>
897   * The caller owns the returned object and is responsible for deleting it.
898   * <p>
899   * @param sid the identifier of the {@link LocalParameter} to remove
900   * <p>
901   * @return the {@link LocalParameter} object removed.  As mentioned above, the 
902   * caller owns the returned object. <code>null</code> is returned if no {@link LocalParameter}
903   * object with the identifier exists in this {@link KineticLaw} instance.
904   */ public
905 LocalParameter removeLocalParameter(String sid) {
906    long cPtr = libsbmlJNI.KineticLaw_removeLocalParameter__SWIG_1(swigCPtr, this, sid);
907    return (cPtr == 0) ? null : new LocalParameter(cPtr, true);
908  }
909
910  
911/**
912   * Sets this SBML object to child SBML objects (if any).
913   * (Creates a child-parent relationship by the parent)
914   * <p>
915   * Subclasses must override this function if they define
916   * one ore more child elements.
917   * Basically, this function needs to be called in
918   * constructor, copy constructor and assignment operator.
919   * <p>
920   * @see setSBMLDocument
921   * @see enablePackageInternal
922   * @internal
923   */ public
924 void connectToChild() {
925    libsbmlJNI.KineticLaw_connectToChild(swigCPtr, this);
926  }
927
928  
929/**
930   * Enables/Disables the given package with this element and child
931   * elements (if any).
932   * (This is an internal implementation for enablePackage function)
933   * <p>
934   * @note Subclasses of the SBML Core package in which one or more child
935   * elements are defined must override this function.
936   * @internal
937   */ public
938 void enablePackageInternal(String pkgURI, String pkgPrefix, boolean flag) {
939    libsbmlJNI.KineticLaw_enablePackageInternal(swigCPtr, this, pkgURI, pkgPrefix, flag);
940  }
941
942  
943/**
944   * Returns the libSBML type code for this SBML object.
945   * <p>
946   * LibSBML attaches an identifying code to every
947   * kind of SBML object.  These are known as <em>SBML type codes</em>.  In
948   * other languages, the set of type codes is stored in an enumeration; in
949   * the Java language interface for libSBML, the type codes are defined as
950   * static integer constants in the interface class {@link
951   * libsbmlConstants}.  The names of the type codes all begin with the
952   * characters <code>SBML_.</code> 
953   * <p>
954   * @return the SBML type code for this object, or {@link 
955   * libsbmlConstants#SBML_UNKNOWN SBML_UNKNOWN} (default).
956   * <p>
957   * @see #getElementName()
958   */ public
959 int getTypeCode() {
960    return libsbmlJNI.KineticLaw_getTypeCode(swigCPtr, this);
961  }
962
963  
964/**
965   * Returns the XML element name of this object, which for {@link Species}, is
966   * always <code>'kineticLaw'.</code>
967   * <p>
968   * @return the name of this element, i.e., <code>'kineticLaw'.</code>
969   */ public
970 String getElementName() {
971    return libsbmlJNI.KineticLaw_getElementName(swigCPtr, this);
972  }
973
974  
975/**
976   * Predicate returning <code>true</code> if
977   * all the required attributes for this {@link KineticLaw} object
978   * have been set.
979   * <p>
980   * @note The required attributes for a {@link KineticLaw} object are:
981   * <ul>
982   * <li> 'formula' (SBML Level&nbsp;1 only)
983   * </ul>
984   * <p>
985   * @return a boolean value indicating whether all the required
986   * attributes for this object have been defined.
987   */ public
988 boolean hasRequiredAttributes() {
989    return libsbmlJNI.KineticLaw_hasRequiredAttributes(swigCPtr, this);
990  }
991
992  
993/**
994   * Predicate returning <code>true</code> if
995   * all the required elements for this {@link KineticLaw} object
996   * have been set.
997   * <p>
998   * @note The required elements for a {@link KineticLaw} object are:
999   * <ul>
1000   * <li> 'math'
1001   * </ul>
1002   * <p>
1003   * @return a boolean value indicating whether all the required
1004   * elements for this object have been defined.
1005   */ public
1006 boolean hasRequiredElements() {
1007    return libsbmlJNI.KineticLaw_hasRequiredElements(swigCPtr, this);
1008  }
1009
1010  
1011/**
1012   * Finds this {@link KineticLaw}'s {@link Reaction} parent and calls unsetKineticLaw() on it, indirectly deleting itself.  Overridden from the {@link SBase} function since the parent is not a {@link ListOf}.
1013   * <p>
1014   * @return integer value indicating success/failure of the
1015   * function.   The possible values
1016   * returned by this function are:
1017   * <ul>
1018   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS }
1019   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED }
1020   * </ul>
1021   */ public
1022 int removeFromParentAndDelete() {
1023    return libsbmlJNI.KineticLaw_removeFromParentAndDelete(swigCPtr, this);
1024  }
1025
1026  
1027/**
1028   * Renames all the SIdRef attributes on this element, including any found in MathML
1029   */ public
1030 void renameSIdRefs(String oldid, String newid) {
1031    libsbmlJNI.KineticLaw_renameSIdRefs(swigCPtr, this, oldid, newid);
1032  }
1033
1034  
1035/**
1036   * Renames all the UnitSIdRef attributes on this element
1037   */ public
1038 void renameUnitSIdRefs(String oldid, String newid) {
1039    libsbmlJNI.KineticLaw_renameUnitSIdRefs(swigCPtr, this, oldid, newid);
1040  }
1041
1042  
1043/**
1044   * Replace all nodes with the name 'id' from the child 'math' object with the provided function. 
1045   * <p>
1046   * @internal
1047   */ public
1048 void replaceSIDWithFunction(String id, ASTNode function) {
1049    libsbmlJNI.KineticLaw_replaceSIDWithFunction(swigCPtr, this, id, ASTNode.getCPtr(function), function);
1050  }
1051
1052  
1053/**
1054   * If this reaction id matches the provided 'id' string, replace the 'math' object with the function (existing/function). 
1055   * @internal 
1056   */ public
1057 void divideAssignmentsToSIdByFunction(String id, ASTNode function) {
1058    libsbmlJNI.KineticLaw_divideAssignmentsToSIdByFunction(swigCPtr, this, id, ASTNode.getCPtr(function), function);
1059  }
1060
1061  
1062/**
1063   * If this assignment assigns a value to the 'id' element, replace the 'math' object with the function (existing*function). 
1064   * @internal 
1065   */ public
1066 void multiplyAssignmentsToSIdByFunction(String id, ASTNode function) {
1067    libsbmlJNI.KineticLaw_multiplyAssignmentsToSIdByFunction(swigCPtr, this, id, ASTNode.getCPtr(function), function);
1068  }
1069
1070}