001/* ----------------------------------------------------------------------------
002 * This file was automatically generated by SWIG (http://www.swig.org).
003 * Version 3.0.10
004 *
005 * Do not make changes to this file unless you know what you are doing--modify
006 * the SWIG interface file instead.
007 * ----------------------------------------------------------------------------- */
008
009package org.sbml.libsbml;
010
011/** 
012 *  A parameter inside an SBML <em>reaction</em> definition.
013 <p>
014 * {@link LocalParameter} has been introduced in SBML Level&nbsp;3 to serve as the
015 * object class for parameter definitions that are intended to be local to
016 * a {@link Reaction}.  Objects of class {@link LocalParameter} never appear at the {@link Model}
017 * level; they are always contained within {@link ListOfLocalParameters} lists
018 * which are in turn contained within {@link KineticLaw} objects.
019 <p>
020 * Like its global {@link Parameter} counterpart, the {@link LocalParameter} object class
021 * is used to define a symbol associated with a value; this symbol can then
022 * be used in a model's mathematical formulas (and specifically, for
023 * {@link LocalParameter}, reaction rate formulas).  Unlike {@link Parameter}, the
024 * {@link LocalParameter} class does not have a 'constant' attribute: local
025 * parameters within reactions are <em>always</em> constant.
026 <p>
027 * {@link LocalParameter} has one required attribute, 'id', to give the
028 * parameter a unique identifier by which other parts of an SBML model
029 * definition can refer to it.  A parameter can also have an optional
030 * 'name' attribute of type <code>string.</code>  Identifiers and names must be used
031 * according to the guidelines described in the SBML specifications.
032 <p>
033 * The optional attribute 'value' determines the value (of type <code>double</code>)
034 * assigned to the parameter.  A missing value for 'value' implies that
035 * the value either is unknown, or to be obtained from an external source,
036 * or determined by an initial assignment.  The unit of measurement
037 * associated with the value of the parameter can be specified using the
038 * optional attribute 'units'.  Here we only mention briefly some notable
039 * points about the possible unit choices, but readers are urged to consult
040 * the SBML specification documents for more information:
041 * <ul>
042 <p>
043 * <li> In SBML Level&nbsp;3, there are no constraints on the units that
044 * can be assigned to parameters in a model; there are also no units to
045 * inherit from the enclosing {@link Model} object.
046 <p>
047 * <li> In SBML Level&nbsp;2, the value assigned to the parameter's 'units'
048 * attribute must be chosen from one of the following possibilities: one of
049 * the base unit identifiers defined in SBML; one of the built-in unit
050 * identifiers <code>'substance'</code>, <code>'time'</code>, <code>'volume'</code>, <code>'area'</code> or 
051 * <code>'length'</code>; or the identifier of a new unit defined in the list of unit
052 * definitions in the enclosing {@link Model} structure.  There are no constraints
053 * on the units that can be chosen from these sets.  There are no default
054 * units for local parameters.
055 * </ul>
056 <p>
057 * As with all other major SBML components, {@link LocalParameter} is derived from
058 * {@link SBase}, and the methods defined on {@link SBase} are available on {@link LocalParameter}.
059 <p>
060 * In SBML Level&nbsp;3 Version&nbsp;2, the scope of the {@link LocalParameter} 
061 * was expanded slightly to officially encompass the entire {@link Reaction}
062 * instead of just the {@link KineticLaw} in which it appears.  This has no
063 * effect on models using only SBML Level&nbsp;3 Core constructs,
064 * but has the potential to allow SBML Level&nbsp;3 Packages to
065 * include elements in a {@link Reaction} that could reference a
066 * {@link LocalParameter} from that {@link Reaction}'s {@link KineticLaw}.  It also means that
067 * no {@link LocalParameter} may have the same <code>'id'</code> as a referenced {@link Species}
068 * in any {@link SimpleSpeciesReference} in that {@link Reaction}. 
069 <p>
070 * @warning <span class='warning'>LibSBML derives {@link LocalParameter} from
071 * {@link Parameter}; however, this does not precisely match the object hierarchy
072 * defined by SBML Level&nbsp;3, where {@link LocalParameter} is derived directly
073 * from {@link SBase} and not {@link Parameter}.  We believe this arrangement makes it easier
074 * for libSBML users to program applications that work with both SBML
075 * Level&nbsp;2 and SBML Level&nbsp;3, but programmers should also keep in
076 * mind this difference exists.  A side-effect of libSBML's scheme is that
077 * certain methods on {@link LocalParameter} that are inherited from {@link Parameter} do not
078 * actually have relevance to {@link LocalParameter} objects.  An example of this is
079 * the methods pertaining to {@link Parameter}'s attribute 'constant' (i.e.,
080 * isSetConstant(), setConstant(), and getConstant()).</span>
081 <p>
082 * @see ListOfLocalParameters
083 * @see KineticLaw
084 */
085
086public class LocalParameter extends Parameter {
087   private long swigCPtr;
088
089   protected LocalParameter(long cPtr, boolean cMemoryOwn)
090   {
091     super(libsbmlJNI.LocalParameter_SWIGUpcast(cPtr), cMemoryOwn);
092     swigCPtr = cPtr;
093   }
094
095   protected static long getCPtr(LocalParameter obj)
096   {
097     return (obj == null) ? 0 : obj.swigCPtr;
098   }
099
100   protected static long getCPtrAndDisown (LocalParameter obj)
101   {
102     long ptr = 0;
103
104     if (obj != null)
105     {
106       ptr             = obj.swigCPtr;
107       obj.swigCMemOwn = false;
108     }
109
110     return ptr;
111   }
112
113  protected void finalize() {
114    delete();
115  }
116
117  public synchronized void delete() {
118    if (swigCPtr != 0) {
119      if (swigCMemOwn) {
120        swigCMemOwn = false;
121        libsbmlJNI.delete_LocalParameter(swigCPtr);
122      }
123      swigCPtr = 0;
124    }
125    super.delete();
126  }
127
128  
129/**
130   * Creates a new {@link LocalParameter} object with the given SBML <code>level</code> and
131   * <code>version</code> values.
132   <p>
133   * @param level a long integer, the SBML Level to assign to this
134   * {@link LocalParameter}.
135   <p>
136   * @param version a long integer, the SBML Version to assign to this
137   * {@link LocalParameter}.
138   <p>
139   * <p>
140 * @throws SBMLConstructorException
141 * Thrown if the given <code>level</code> and <code>version</code> combination are invalid
142 * or if this object is incompatible with the given level and version.
143   <p>
144   * <p>
145 * @note Attempting to add an object to an {@link SBMLDocument} having a different
146 * combination of SBML Level, Version and XML namespaces than the object
147 * itself will result in an error at the time a caller attempts to make the
148 * addition.  A parent object must have compatible Level, Version and XML
149 * namespaces.  (Strictly speaking, a parent may also have more XML
150 * namespaces than a child, but the reverse is not permitted.)  The
151 * restriction is necessary to ensure that an SBML model has a consistent
152 * overall structure.  This requires callers to manage their objects
153 * carefully, but the benefit is increased flexibility in how models can be
154 * created by permitting callers to create objects bottom-up if desired.  In
155 * situations where objects are not yet attached to parents (e.g.,
156 * {@link SBMLDocument}), knowledge of the intented SBML Level and Version help
157 * libSBML determine such things as whether it is valid to assign a
158 * particular value to an attribute.
159   */ public
160 LocalParameter(long level, long version) throws org.sbml.libsbml.SBMLConstructorException {
161    this(libsbmlJNI.new_LocalParameter__SWIG_0(level, version), true);
162  }
163
164  
165/**
166   * Creates a new {@link LocalParameter} object with the given {@link SBMLNamespaces}
167   * object <code>sbmlns</code>.
168   <p>
169   * <p>
170 * The {@link SBMLNamespaces} object encapsulates SBML Level/Version/namespaces
171 * information.  It is used to communicate the SBML Level, Version, and (in
172 * Level&nbsp;3) packages used in addition to SBML Level&nbsp;3 Core.  A
173 * common approach to using libSBML's {@link SBMLNamespaces} facilities is to create an
174 * {@link SBMLNamespaces} object somewhere in a program once, then hand that object
175 * as needed to object constructors that accept {@link SBMLNamespaces} as arguments. 
176   <p>
177   * It is worth emphasizing that although this constructor does not take
178   * an identifier argument, in SBML Level&nbsp;2 and beyond, the 'id'
179   * (identifier) attribute of a {@link LocalParameter} is required to have a value.
180   * Thus, callers are cautioned to assign a value after calling this
181   * constructor if no identifier is provided as an argument.  Setting the
182   * identifier can be accomplished using the method
183   * setId(String id).
184   <p>
185   * @param sbmlns an {@link SBMLNamespaces} object.
186   <p>
187   * <p>
188 * @throws SBMLConstructorException
189 * Thrown if the given <code>sbmlns</code> is inconsistent or incompatible
190 * with this object.
191   <p>
192   * <p>
193 * @note Attempting to add an object to an {@link SBMLDocument} having a different
194 * combination of SBML Level, Version and XML namespaces than the object
195 * itself will result in an error at the time a caller attempts to make the
196 * addition.  A parent object must have compatible Level, Version and XML
197 * namespaces.  (Strictly speaking, a parent may also have more XML
198 * namespaces than a child, but the reverse is not permitted.)  The
199 * restriction is necessary to ensure that an SBML model has a consistent
200 * overall structure.  This requires callers to manage their objects
201 * carefully, but the benefit is increased flexibility in how models can be
202 * created by permitting callers to create objects bottom-up if desired.  In
203 * situations where objects are not yet attached to parents (e.g.,
204 * {@link SBMLDocument}), knowledge of the intented SBML Level and Version help
205 * libSBML determine such things as whether it is valid to assign a
206 * particular value to an attribute.
207   */ public
208 LocalParameter(SBMLNamespaces sbmlns) throws org.sbml.libsbml.SBMLConstructorException {
209    this(libsbmlJNI.new_LocalParameter__SWIG_1(SBMLNamespaces.getCPtr(sbmlns), sbmlns), true);
210  }
211
212  
213/**
214   * Copy constructor; creates a copy of a given {@link LocalParameter} object.
215   <p>
216   * @param orig the {@link LocalParameter} instance to copy.
217   */ public
218 LocalParameter(LocalParameter orig) throws org.sbml.libsbml.SBMLConstructorException {
219    this(libsbmlJNI.new_LocalParameter__SWIG_2(LocalParameter.getCPtr(orig), orig), true);
220  }
221
222  
223/**
224   * Copy constructor; creates a {@link LocalParameter} object by copying
225   * the attributes of a given {@link Parameter} object.
226   <p>
227   * @param orig the {@link Parameter} instance to copy.
228   */ public
229 LocalParameter(Parameter orig) throws org.sbml.libsbml.SBMLConstructorException {
230    this(libsbmlJNI.new_LocalParameter__SWIG_3(Parameter.getCPtr(orig), orig), true);
231  }
232
233  
234/**
235   * Creates and returns a deep copy of this {@link LocalParameter} object.
236   <p>
237   * @return the (deep) copy of this {@link LocalParameter} object.
238   */ public
239 LocalParameter cloneObject() {
240    long cPtr = libsbmlJNI.LocalParameter_cloneObject(swigCPtr, this);
241    return (cPtr == 0) ? null : new LocalParameter(cPtr, true);
242  }
243
244  
245/**
246   * Constructs and returns a {@link UnitDefinition} that corresponds to the units
247   * of this {@link LocalParameter}'s value.
248   <p>
249   * <p>
250 * LocalParameters in SBML have an attribute ('units') for declaring the
251 * units of measurement intended for the parameter's value.  <b>No
252 * defaults are defined</b> by SBML in the absence of a definition for
253 * 'units'.  This method returns a {@link UnitDefinition} object based on the
254 * units declared for this {@link LocalParameter} using its 'units' attribute, or
255 * it returns <code>null</code> if no units have been declared.
256 <p>
257 * Note that unit declarations for {@link LocalParameter} objects are specified
258 * in terms of the <em>identifier</em> of a unit (e.g., using setUnits()), but
259 * <em>this</em> method returns a {@link UnitDefinition} object, not a unit
260 * identifier.  It does this by constructing an appropriate
261 * {@link UnitDefinition}.  For SBML Level&nbsp;2 models, it will do this even
262 * when the value of the 'units' attribute is one of the predefined SBML
263 * units <code>'substance'</code>, <code>'volume'</code>, <code>'area'</code>, <code>'length'</code> or 
264 * <code>'time'.</code>  Callers may find this useful in conjunction with the helper
265 * methods provided by the {@link UnitDefinition} class for comparing different
266 * {@link UnitDefinition} objects.
267   <p>
268   * @return a {@link UnitDefinition} that expresses the units of this 
269   * {@link LocalParameter}, or <code>null</code> if one cannot be constructed.
270   <p>
271   * @note The libSBML system for unit analysis depends on the model as a
272   * whole.  In cases where the {@link LocalParameter} object has not yet been
273   * added to a model, or the model itself is incomplete, unit analysis is
274   * not possible, and consequently this method will return <code>null.</code>
275   <p>
276   * @see #isSetUnits()
277   */ public
278 UnitDefinition getDerivedUnitDefinition() {
279    long cPtr = libsbmlJNI.LocalParameter_getDerivedUnitDefinition__SWIG_0(swigCPtr, this);
280    return (cPtr == 0) ? null : new UnitDefinition(cPtr, false);
281  }
282
283  
284/**
285   * Returns the libSBML type code for this SBML object.
286   <p>
287   * <p>
288 * LibSBML attaches an identifying code to every kind of SBML object.  These
289 * are integer constants known as <em>SBML type codes</em>.  The names of all
290 * the codes begin with the characters <code>SBML_</code>.
291 * In the Java language interface for libSBML, the
292 * type codes are defined as static integer constants in the interface class
293 * {@link libsbmlConstants}.    Note that different Level&nbsp;3
294 * package plug-ins may use overlapping type codes; to identify the package
295 * to which a given object belongs, call the <code>getPackageName()</code>
296 * method on the object.
297   <p>
298   * @return the SBML type code for this object:
299   * {@link libsbmlConstants#SBML_LOCAL_PARAMETER SBML_LOCAL_PARAMETER} (default).
300   <p>
301   * <p>
302 * @warning <span class='warning'>The specific integer values of the possible
303 * type codes may be reused by different libSBML plug-ins for SBML Level&nbsp;3.
304 * packages,  To fully identify the correct code, <strong>it is necessary to
305 * invoke both getTypeCode() and getPackageName()</strong>.</span>
306   <p>
307   * @see #getElementName()
308   * @see #getPackageName()
309   */ public
310 int getTypeCode() {
311    return libsbmlJNI.LocalParameter_getTypeCode(swigCPtr, this);
312  }
313
314  
315/**
316   * Returns the XML element name of this object, which for {@link LocalParameter},
317   * is always <code>'localParameter'.</code>
318   <p>
319   * @return the name of this element, i.e., <code>'localParameter'.</code>
320   */ public
321 String getElementName() {
322    return libsbmlJNI.LocalParameter_getElementName(swigCPtr, this);
323  }
324
325  
326/**
327   * Predicate returning <code>true</code> if all the required attributes for this
328   * {@link LocalParameter} object have been set.
329   <p>
330   * The required attributes for a {@link LocalParameter} object are:
331   * <ul>
332   * <li> 'id'
333   * <li> 'value'
334   *
335   * </ul> <p>
336   * @return <code>true</code> if the required attributes have been set, <code>false</code>
337   * otherwise.
338   */ public
339 boolean hasRequiredAttributes() {
340    return libsbmlJNI.LocalParameter_hasRequiredAttributes(swigCPtr, this);
341  }
342
343  
344/** * @internal */ public
345 boolean getConstant() {
346    return libsbmlJNI.LocalParameter_getConstant(swigCPtr, this);
347  }
348
349  
350/** * @internal */ public
351 boolean isSetConstant() {
352    return libsbmlJNI.LocalParameter_isSetConstant(swigCPtr, this);
353  }
354
355  
356/** * @internal */ public
357 int setConstant(boolean flag) {
358    return libsbmlJNI.LocalParameter_setConstant(swigCPtr, this, flag);
359  }
360
361  
362/** * @internal */ public
363 int unsetConstant() {
364    return libsbmlJNI.LocalParameter_unsetConstant(swigCPtr, this);
365  }
366
367}