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 Level 3's LocalParameter construct.
014 * <p>
015 * {@link LocalParameter} has been introduced in SBML Level&nbsp;3 to serve as the
016 * object class for parameter definitions that are intended to be local to
017 * a {@link Reaction}.  Objects of class {@link LocalParameter} never appear at the {@link Model}
018 * level; they are always contained within {@link ListOfLocalParameters} lists
019 * which are in turn contained within {@link KineticLaw} objects.
020 * <p>
021 * Like its global {@link Parameter} counterpart, the {@link LocalParameter} object class
022 * is used to define a symbol associated with a value; this symbol can then
023 * be used in a model's mathematical formulas (and specifically, for
024 * {@link LocalParameter}, reaction rate formulas).  Unlike {@link Parameter}, the
025 * {@link LocalParameter} class does not have a 'constant' attribute: local
026 * parameters within reactions are <em>always</em> constant.
027 * <p>
028 * {@link LocalParameter} has one required attribute, 'id', to give the
029 * parameter a unique identifier by which other parts of an SBML model
030 * definition can refer to it.  A parameter can also have an optional
031 * 'name' attribute of type <code>string.</code>  Identifiers and names must be used
032 * according to the guidelines described in the SBML specifications.
033 * <p>
034 * The optional attribute 'value' determines the value (of type <code>double</code>)
035 * assigned to the parameter.  A missing value for 'value' implies that
036 * the value either is unknown, or to be obtained from an external source,
037 * or determined by an initial assignment.  The unit of measurement
038 * associated with the value of the parameter can be specified using the
039 * optional attribute 'units'.  Here we only mention briefly some notable
040 * points about the possible unit choices, but readers are urged to consult
041 * the SBML specification documents for more information:
042 * <ul>
043 * <p>
044 * <li> In SBML Level&nbsp;3, there are no constraints on the units that
045 * can be assigned to parameters in a model; there are also no units to
046 * inherit from the enclosing {@link Model} object.
047 * <p>
048 * <li> In SBML Level&nbsp;2, the value assigned to the parameter's 'units'
049 * attribute must be chosen from one of the following possibilities: one of
050 * the base unit identifiers defined in SBML; one of the built-in unit
051 * identifiers <code>'substance'</code>, <code>'time'</code>, <code>'volume'</code>, <code>'area'</code> or 
052 * <code>'length'</code>; or the identifier of a new unit defined in the list of unit
053 * definitions in the enclosing {@link Model} structure.  There are no constraints
054 * on the units that can be chosen from these sets.  There are no default
055 * units for local parameters.
056 * </ul>
057 * <p>
058 * As with all other major SBML components, {@link LocalParameter} is derived from
059 * {@link SBase}, and the methods defined on {@link SBase} are available on {@link LocalParameter}.
060 * <p>
061 * @warning LibSBML derives {@link LocalParameter} from {@link Parameter}; however, this
062 * does not precisely match the object hierarchy defined by SBML
063 * Level&nbsp;3, where {@link LocalParameter} is derived directly from {@link SBase} and not
064 * {@link Parameter}.  We believe this arrangement makes it easier for libSBML
065 * users to program applications that work with both SBML Level&nbsp;2 and
066 * SBML Level&nbsp;3, but programmers should also keep in mind this
067 * difference exists.  A side-effect of libSBML's scheme is that certain
068 * methods on {@link LocalParameter} that are inherited from {@link Parameter} do not
069 * actually have relevance to {@link LocalParameter} objects.  An example of this
070 * is the methods pertaining to {@link Parameter}'s attribute 'constant'
071 * (i.e., isSetConstant(), setConstant(), and getConstant()).
072 * <p>
073 * @see ListOfLocalParameters
074 * @see KineticLaw
075 * <p>
076 * <!-- leave this next break as-is to work around some doxygen bug -->
077 */
078
079public class LocalParameter extends Parameter {
080   private long swigCPtr;
081
082   protected LocalParameter(long cPtr, boolean cMemoryOwn)
083   {
084     super(libsbmlJNI.LocalParameter_SWIGUpcast(cPtr), cMemoryOwn);
085     swigCPtr = cPtr;
086   }
087
088   protected static long getCPtr(LocalParameter obj)
089   {
090     return (obj == null) ? 0 : obj.swigCPtr;
091   }
092
093   protected static long getCPtrAndDisown (LocalParameter obj)
094   {
095     long ptr = 0;
096
097     if (obj != null)
098     {
099       ptr             = obj.swigCPtr;
100       obj.swigCMemOwn = false;
101     }
102
103     return ptr;
104   }
105
106  protected void finalize() {
107    delete();
108  }
109
110  public synchronized void delete() {
111    if (swigCPtr != 0) {
112      if (swigCMemOwn) {
113        swigCMemOwn = false;
114        libsbmlJNI.delete_LocalParameter(swigCPtr);
115      }
116      swigCPtr = 0;
117    }
118    super.delete();
119  }
120
121  
122/**
123   * Creates a new {@link LocalParameter} object with the given SBML <code>level</code> and
124   * <code>version</code> values.
125   * <p>
126   * @param level a long integer, the SBML Level to assign to this
127   * {@link LocalParameter}.
128   * <p>
129   * @param version a long integer, the SBML Version to assign to this
130   * {@link LocalParameter}.
131   * <p>
132   * @throws SBMLConstructorException 
133   * Thrown if the given <code>level</code> and <code>version</code> combination, or this kind
134   * of SBML object, are either invalid or mismatched with respect to the
135   * parent {@link SBMLDocument} object.
136   * <p>
137   * @note Upon the addition of a {@link LocalParameter} object to an {@link SBMLDocument}
138   * (e.g., using {@link KineticLaw#addLocalParameter(LocalParameter p)}), the SBML Level, SBML
139   * Version and XML namespace of the document <em>override</em> the
140   * values used when creating the {@link LocalParameter} object via this
141   * constructor.  This is necessary to ensure that an SBML document is a
142   * consistent structure.  Nevertheless, the ability to supply the values
143   * at the time of creation of a {@link LocalParameter} is an important aid to
144   * producing valid SBML.  Knowledge of the intented SBML Level and
145   * Version determine whether it is valid to assign a particular value to
146   * an attribute, or whether it is valid to add an object to an existing
147   * {@link SBMLDocument}.
148   */ public
149 LocalParameter(long level, long version) throws org.sbml.libsbml.SBMLConstructorException {
150    this(libsbmlJNI.new_LocalParameter__SWIG_0(level, version), true);
151  }
152
153  
154/**
155   * Creates a new {@link LocalParameter} object with the given {@link SBMLNamespaces}
156   * object <code>sbmlns</code>.
157   * <p>
158   * The {@link SBMLNamespaces} object encapsulates SBML Level/Version/namespaces
159   * information.  It is used to communicate the SBML Level, Version, and
160   * (in Level&nbsp;3) packages used in addition to SBML Level&nbsp;3 Core.
161   * A common approach to using this class constructor is to create an
162   * {@link SBMLNamespaces} object somewhere in a program, once, then pass it to
163   * object constructors such as this one when needed.
164   * <p>
165   * It is worth emphasizing that although this constructor does not take
166   * an identifier argument, in SBML Level&nbsp;2 and beyond, the 'id'
167   * (identifier) attribute of a {@link LocalParameter} is required to have a value.
168   * Thus, callers are cautioned to assign a value after calling this
169   * constructor if no identifier is provided as an argument.  Setting the
170   * identifier can be accomplished using the method
171   * setId(String id).
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 LocalParameter} object to an {@link SBMLDocument}
181   * (e.g., using {@link KineticLaw#addLocalParameter(LocalParameter p)}), the SBML XML namespace of
182   * the document <em>overrides</em> the value used when creating the
183   * {@link LocalParameter} object via this constructor.  This is necessary to
184   * ensure that an SBML document is a consistent structure.  Nevertheless,
185   * the ability to supply the values at the time of creation of a
186   * {@link LocalParameter} is an important aid to producing valid SBML.  Knowledge
187   * of the intented SBML Level and Version determine whether it is valid
188   * to assign a particular value to an attribute, or whether it is valid
189   * to add an object to an existing {@link SBMLDocument}.
190   */ public
191 LocalParameter(SBMLNamespaces sbmlns) throws org.sbml.libsbml.SBMLConstructorException {
192    this(libsbmlJNI.new_LocalParameter__SWIG_1(SBMLNamespaces.getCPtr(sbmlns), sbmlns), true);
193  }
194
195  
196/**
197   * Copy constructor; creates a copy of a given {@link LocalParameter} object.
198   * <p>
199   * @param orig the {@link LocalParameter} instance to copy.
200   * <p>
201   * @throws SBMLConstructorException 
202   * Thrown if the argument <code>orig</code> is <code>null.</code>
203   */ public
204 LocalParameter(LocalParameter orig) throws org.sbml.libsbml.SBMLConstructorException {
205    this(libsbmlJNI.new_LocalParameter__SWIG_2(LocalParameter.getCPtr(orig), orig), true);
206  }
207
208  
209/**
210   * Copy constructor; creates a {@link LocalParameter} object by copying
211   * the attributes of a given {@link Parameter} object.
212   * <p>
213   * @param orig the {@link Parameter} instance to copy.
214   * <p>
215   * @throws SBMLConstructorException 
216   * Thrown if the argument <code>orig</code> is <code>null.</code>
217   */ public
218 LocalParameter(Parameter orig) throws org.sbml.libsbml.SBMLConstructorException {
219    this(libsbmlJNI.new_LocalParameter__SWIG_3(Parameter.getCPtr(orig), orig), true);
220  }
221
222  
223/**
224   * Creates and returns a deep copy of this {@link LocalParameter}.
225   * <p>
226   * @return a (deep) copy of this {@link LocalParameter}.
227   */ public
228 LocalParameter cloneObject() {
229    long cPtr = libsbmlJNI.LocalParameter_cloneObject(swigCPtr, this);
230    return (cPtr == 0) ? null : new LocalParameter(cPtr, true);
231  }
232
233  
234/**
235   * Constructs and returns a {@link UnitDefinition} that corresponds to the units
236   * of this {@link LocalParameter}'s value.
237   * <p>
238   * LocalParameters in SBML have an attribute ('units') for declaring the
239   * units of measurement intended for the parameter's value.  <b>No
240   * defaults are defined</b> by SBML in the absence of a definition for
241   * 'units'.  This method returns a {@link UnitDefinition} object based on the
242   * units declared for this {@link LocalParameter} using its 'units' attribute, or
243   * it returns <code>null</code> if no units have been declared.
244   * <p>
245   * Note that unit declarations for {@link LocalParameter} objects are specified
246   * in terms of the <em>identifier</em> of a unit (e.g., using setUnits()), but
247   * <em>this</em> method returns a {@link UnitDefinition} object, not a unit
248   * identifier.  It does this by constructing an appropriate
249   * {@link UnitDefinition}.  For SBML Level&nbsp;2 models, it will do this even
250   * when the value of the 'units' attribute is one of the predefined SBML
251   * units <code>'substance'</code>, <code>'volume'</code>, <code>'area'</code>, <code>'length'</code> or 
252   * <code>'time'.</code>  Callers may find this useful in conjunction with the helper
253   * methods provided by the {@link UnitDefinition} class for comparing different
254   * {@link UnitDefinition} objects.
255   * <p>
256   * @return a {@link UnitDefinition} that expresses the units of this 
257   * {@link LocalParameter}, or <code>null</code> if one cannot be constructed.
258   * <p>
259   * @note The libSBML system for unit analysis depends on the model as a
260   * whole.  In cases where the {@link LocalParameter} object has not yet been
261   * added to a model, or the model itself is incomplete, unit analysis is
262   * not possible, and consequently this method will return <code>null.</code>
263   * <p>
264   * @see #isSetUnits()
265   */ public
266 UnitDefinition getDerivedUnitDefinition() {
267    long cPtr = libsbmlJNI.LocalParameter_getDerivedUnitDefinition__SWIG_0(swigCPtr, this);
268    return (cPtr == 0) ? null : new UnitDefinition(cPtr, false);
269  }
270
271  
272/**
273   * Returns the libSBML type code for this SBML object.
274   * <p>
275   * LibSBML attaches an identifying code to every
276   * kind of SBML object.  These are known as <em>SBML type codes</em>.  In
277   * other languages, the set of type codes is stored in an enumeration; in
278   * the Java language interface for libSBML, the type codes are defined as
279   * static integer constants in the interface class {@link
280   * libsbmlConstants}.  The names of the type codes all begin with the
281   * characters <code>SBML_.</code> 
282   * <p>
283   * @return the SBML type code for this object, or {@link 
284   * libsbmlConstants#SBML_UNKNOWN SBML_UNKNOWN} (default).
285   * <p>
286   * @see #getElementName()
287   */ public
288 int getTypeCode() {
289    return libsbmlJNI.LocalParameter_getTypeCode(swigCPtr, this);
290  }
291
292  
293/**
294   * Returns the XML element name of this object, which for {@link LocalParameter},
295   * is always <code>'localParameter'.</code>
296   * <p>
297   * @return the name of this element, i.e., <code>'localParameter'.</code>
298   */ public
299 String getElementName() {
300    return libsbmlJNI.LocalParameter_getElementName(swigCPtr, this);
301  }
302
303  
304/**
305   * Predicate returning <code>true</code> if
306   * all the required attributes for this {@link LocalParameter} object
307   * have been set.
308   * <p>
309   * @note The required attributes for a {@link LocalParameter} object are:
310   * <ul>
311   * <li> 'id'
312   * <li> 'value'
313   * </ul>
314   * <p>
315   * @return a boolean value indicating whether all the required
316   * attributes for this object have been defined.
317   */ public
318 boolean hasRequiredAttributes() {
319    return libsbmlJNI.LocalParameter_hasRequiredAttributes(swigCPtr, this);
320  }
321
322}