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 UnitDefinition construct.
014 * <p>
015 * Units of measurement may be supplied in a number of contexts in an SBML
016 * model.  The SBML unit definition facility uses two classes of objects,
017 * {@link UnitDefinition} and {@link Unit}.  The approach to defining units in SBML is
018 * compositional; for example, <em>meter second<sup> &ndash;2</sup></em> is
019 * constructed by combining a {@link Unit} object representing <em>meter</em> with
020 * another {@link Unit} object representing <em>second<sup> &ndash;2</sup></em>.
021 * The combination is wrapped inside a {@link UnitDefinition}, which provides for
022 * assigning an identifier and optional name to the combination.  The
023 * identifier can then be referenced from elsewhere in a model.  Thus, the
024 * {@link UnitDefinition} class is the container, and {@link Unit} instances are placed
025 * inside {@link UnitDefinition} instances.
026 * <p>
027 * Two points are worth discussing in the context of SBML units.  First,
028 * unit declarations in SBML models are <em>optional</em>.  The consequence of
029 * this is that a model must be numerically self-consistent independently
030 * of unit declarations, for the benefit of software tools that cannot
031 * interpret or manipulate units.  {@link Unit} declarations in SBML are thus more
032 * akin to a type of annotation; they can indicate intentions, and can be
033 * used by model readers for checking the consistency of the model,
034 * labeling simulation output, etc., but any transformations of values
035 * implied by different units must be incorporated <em>explicitly</em> into a
036 * model.
037 * <p>
038 * Second, the vast majority of situations that require new SBML unit
039 * definitions involve simple multiplicative combinations of base units and
040 * factors.  An example is <em>moles per litre per second</em>.  What
041 * distinguishes these sorts of unit definitions from more complex ones is
042 * that they may be expressed without the use of an additive offset from a
043 * zero point.  The use of offsets complicates all unit definition systems,
044 * yet in the domain of SBML, the real-life cases requiring offsets are few
045 * (and in fact, to the best of our knowledge, only involve temperature).
046 * Consequently, the SBML unit system has been consciously designed to
047 * simplify implementation of unit support for the most common cases in
048 * systems biology.  The cost of this simplification is to require units
049 * with offsets to be handled explicitly by the modeler.
050 * <p>
051 * <h2>Summary of the {@link UnitDefinition} construct</h2>
052 * <p>
053 * {@link UnitDefinition} has two attributes and one subelement.  The two
054 * attributes are 'id' and 'name', and the subelement is {@link ListOfUnits}.
055 * <p>
056 * The required attribute 'id' and optional attribute 'name' are both
057 * strings.  The 'id' attribute is used to give the defined unit a unique
058 * identifier by which other parts of an SBML model definition can refer to
059 * it.  The 'name' attribute is intended to be used for giving the unit
060 * definition an optional human-readable name.  Please see the <a
061 * href='#unitdef-id'>next section</a> for information about the values
062 * permitted for 'id'.
063 * <p>
064 * A {@link UnitDefinition} must contain exactly one {@link ListOfUnits}, and this list
065 * must contain one or more {@link Unit} definitions; see the definitions of these
066 * other object classes for more information about them.  The following
067 * example illustrates a complete unit definition (when written in XML)
068 * when they all the pieces are combined together.  This defines 'mmls'
069 * to be millimoles per litre per second.
070 * <div class='fragment'><pre>
071 &lt;listOfUnitDefinitions&gt;
072     &lt;unitDefinition id='mmls'&gt;
073         &lt;listOfUnits&gt;
074             &lt;unit kind='mole'   scale='-3'/&gt;
075             &lt;unit kind='litre'  exponent='-1'/&gt;
076             &lt;unit kind='second' exponent='-1'/&gt;
077         &lt;/listOfUnits&gt;
078     &lt;/unitDefinition&gt;
079 &lt;/listOfUnitDefinitions&gt;
080 </pre></div>
081 * <p>
082 * <h2>Special considerations for {@link Unit} object identifiers</h2>
083 * <p>
084 * The attribute 'id' in {@link UnitDefinition} cannot be given simply any value,
085 * and the precise details of the values permitted differ slightly between
086 * Levels of SBML:
087 * <ul>
088 * <p>
089 * <li> The 'id' of a {@link UnitDefinition} must <em>not</em> contain a value from the
090 * list of SBML's predefined base unit names (i.e., the strings <code>gram</code>, 
091 * <code>litre</code>, etc.).  In SBML Level&nbsp;3, this list consists of the
092 * following:
093 * <p>
094 * <center>
095<table border='0' class='text-table width80 normal-font'
096       style='border-top: none !important; border-bottom: none !important; color: black; font-weight: bold; font-family: Courier New, Courier, monospace, fixed;'>
097<tr>
098<td>ampere</td><td>farad</td><td>joule</td><td>lux</td><td>radian</td><td>volt</td>
099</tr>
100<tr>
101<td>avogadro</td><td>gram</td><td>katal</td><td>metre</td><td>second</td><td>watt</td>
102</tr>
103<tr>
104<td>becquerel</td><td>gray</td><td>kelvin</td><td>mole</td><td>siemens</td><td>weber</td>
105</tr>
106<tr>
107<td>candela</td><td>henry</td><td>kilogram</td><td>newton</td><td>sievert</td>
108</tr>
109<tr>
110<td>coulomb</td><td>hertz</td><td>litre</td><td>ohm</td><td>steradian</td>
111</tr>
112<tr>
113<td>dimensionless</td><td>item</td><td>lumen</td><td>pascal</td><td>tesla</td>
114</tr>
115</table>
116</center>
117
118 * <p>
119 * This list of predefined base units is nearly identical in SBML
120 * Level&nbsp;2 Version&nbsp;4, the exception being that Level&nbsp;2 does
121 * not define <code>avogadro.</code>  SBML Level&nbsp;2 Version&nbsp;1 (and <em>only</em>
122 * this Level+Version combination) provides an additional predefined unit
123 * name, <code>Celsius</code>, not available in Level&nbsp;3.  Finally, SBML
124 * Level&nbsp;1 Versions&nbsp;2&ndash;3 provide two more additional
125 * predefined unit names, <code>meter</code> and <code>liter.</code>  This is explained in
126 * somewhat greater detail in the description of the {@link Unit} class.
127 * <p>
128 * <li> In SBML Level&nbsp;2 (all Versions), there is an additional set of
129 * reserved identifiers: <code>substance</code>, <code>volume</code>, <code>area</code>, <code>length</code>, and
130 * <code>time.</code>  Using one of these values for the attribute 'id' of a
131 * {@link UnitDefinition} has the effect of redefining the model-wide default units
132 * for the corresponding quantities.  The list of special unit names in
133 * SBML Level&nbsp;2 is given in the table below:
134 * <p>
135 *   <center>
136<table border='0' class='text-table width80 normal-font alt-row-colors'>
137 <tr>
138     <th align='left'>Identifier</th>
139     <th align='left'>Possible scalable units</th>
140     <th align='left'>Default units</th>
141 </tr>
142<tr><td><code>substance</code></td><td>mole, item, gram, kilogram, dimensionless</td><td>mole</td></tr>
143<tr><td><code>volume</code></td><td>litre, cubic metre, dimensionless</td><td>litre</td></tr>
144<tr><td><code>area</code></td><td>square metre, dimensionless</td><td>square metre</td></tr>
145<tr><td><code>length</code></td><td>metre, dimensionless</td><td>metre</td></tr>
146<tr><td><code>time</code></td><td>second, dimensionless</td><td>second</td></tr>
147</table>
148</center>
149
150 * <p>
151 * Also, SBML Level&nbsp;2 imposes two limitations on redefining the
152 * predefined unit <code>substance</code>, <code>volume</code>, <code>area</code>, <code>length</code>, and 
153 * <code>time:</code> (1) The {@link UnitDefinition} of a predefined SBML unit can only contain
154 * a single {@link Unit} object within it.  (2) The value of the 'kind' attribute
155 * in a {@link Unit} instance must be drawn from one of the values in the second
156 * column of the table above.
157 * <p>
158 * The special unit names <code>substance</code>, <code>volume</code>, <code>area</code>, <code>length</code>, and
159 * <code>time</code> are not defined by SBML Level&nbsp;3, which uses a different
160 * approach to setting model-wide inherited units.
161 * <p>
162 * </ul>
163 * <p>
164 * <p>
165 * <h2>Further comments about SBML's unit definition system</h2>
166 * <p>
167 * The vast majority of modeling situations requiring new SBML unit
168 * definitions involve simple multiplicative combinations of base units and
169 * factors.  An example of this might be <em>moles per litre per
170 * second</em>.  What distinguishes these sorts of simpler unit definitions
171 * from more complex ones is that they may be expressed without the use of
172 * an additive offset from a zero point.  The use of offsets complicates
173 * all unit definition systems, yet in the domain of SBML the real-life
174 * cases requiring offsets are few (and in fact, to the best of our
175 * knowledge, only involve temperature).  Consequently, the SBML unit
176 * system has been consciously designed in a way that attempts to simplify
177 * implementation of unit support for the most common cases in systems
178 * biology.
179 * <p>
180 * As of SBML Level&nbsp;2 Version&nbsp;2, {@link Unit} no longer has the
181 * attribute called 'offset' introduced in SBML Level&nbsp;2
182 * Version&nbsp;1.  It turned out that the general case involving units
183 * with offsets was incorrectly defined, and few (if any) developers even
184 * attempted to support offset-based units in their software.  In the
185 * development of Level&nbsp;2 Version&nbsp;2, a consensus among SBML
186 * developers emerged that a fully generalized unit scheme is <em>so</em>
187 * confusing and complicated that it actually <em>impedes</em> interoperability.
188 * SBML Level&nbsp;2 Version&nbsp;2, Version&nbsp;3 and Version&nbsp;4 acknowledge this
189 * reality by reducing and simplifying the unit system, specifically by
190 * removing the 'offset' attribute on {@link Unit} and <code>Celsius</code> as a pre-defined
191 * unit.
192 * <p>
193 * The following guidelines suggest methods for handling units that do
194 * require the use of zero offsets for their definitions:
195 * <ul>
196 * <li> <em>Handling Celsius</em>.  A model in which certain quantities are
197 *   temperatures measured in degrees Celsius can be converted
198 *   straightforwardly to a model in which those temperatures are in
199 *   kelvin.  A software tool could do this by performing a straightforward
200 *   substitution using the following relationship: <em>T<sub> kelvin</sub> =
201 *   T<sub>Celsius</sub> + 273.15</em>.  In every mathematical formula of the
202 *   model where a quantity (call it <em>x</em>) in degrees Celsius appears,
203 *   replace <em>x</em> with <em>x<sub>k</sub>+ 273.15</em>, where
204 *   <em>x<sub>k</sub></em> is now in kelvin.  An alternative approach would 
205 *   be to use a {@link FunctionDefinition} object to define a function encapsulating this
206 *   relationship above and then using that in the rest of the model as
207 *   needed.  Since Celsius is a commonly-used unit, software tools could
208 *   help users by providing users with the ability to express temperatures
209 *   in Celsius in the tools' interfaces, and making substitutions
210 *   automatically when writing out the SBML.
211 * <p>
212 * <li> <em>Other units requiring offsets</em>.  One approach to handling
213 *   other kinds of units is to use a {@link FunctionDefinition} to define a function
214 *   encapsulating the necessary mathematical relationship, then
215 *   substituting a call to this function wherever the original quantity
216 *   appeared in the model.  For example, here is a possible definition for
217 *   converting Fahrenheit to Celsius degrees:
218 *   <div class='fragment'><pre>
219 &lt;functionDefinition id='Fahrenheit_to_kelvin'&gt;
220     &lt;math xmlns='http://www.w3.org/1998/Math/MathML'&gt;
221         &lt;lambda&gt;
222             &lt;bvar&gt;&lt;ci&gt; temp_in_fahrenheit &lt;/ci&gt;&lt;/bvar&gt;
223             &lt;apply&gt;
224                 &lt;divide/&gt;
225                 &lt;apply&gt;
226                     &lt;plus/&gt;
227                     &lt;ci&gt; temp_in_fahrenheit &lt;/ci&gt;
228                     &lt;cn&gt; 459.67 &lt;/cn&gt;
229                 &lt;/apply&gt;
230                 &lt;cn&gt; 1.8 &lt;/cn&gt;
231             &lt;/apply&gt;
232         &lt;/lambda&gt;
233     &lt;/math&gt;
234 &lt;/functionDefinition&gt;
235 </pre></div>
236 * <p>
237 * <li> An alternative approach not requiring the use of function definitions
238 *   is to use an {@link AssignmentRule} for each variable in Fahrenheit units.
239 *   The {@link AssignmentRule} could compute the conversion from Fahrenheit to
240 *   (say) kelvin, assign its value to a variable (in Kelvin units), and
241 *   then that variable could be used elsewhere in the model.
242 * <p>
243 * <li> Still another approach is to rewrite the mathematical formulas of a
244 *   model to directly incorporate the conversion formula wherever the
245 *   original quantity appeared.
246 * </ul>
247 * <p>
248 * Please consult the SBML specifications for more information about this
249 * and other issues involving units.
250 * <p>
251 * <!-- leave this next break as-is to work around some doxygen bug -->
252 */
253
254public class UnitDefinition extends SBase {
255   private long swigCPtr;
256
257   protected UnitDefinition(long cPtr, boolean cMemoryOwn)
258   {
259     super(libsbmlJNI.UnitDefinition_SWIGUpcast(cPtr), cMemoryOwn);
260     swigCPtr = cPtr;
261   }
262
263   protected static long getCPtr(UnitDefinition obj)
264   {
265     return (obj == null) ? 0 : obj.swigCPtr;
266   }
267
268   protected static long getCPtrAndDisown (UnitDefinition obj)
269   {
270     long ptr = 0;
271
272     if (obj != null)
273     {
274       ptr             = obj.swigCPtr;
275       obj.swigCMemOwn = false;
276     }
277
278     return ptr;
279   }
280
281  protected void finalize() {
282    delete();
283  }
284
285  public synchronized void delete() {
286    if (swigCPtr != 0) {
287      if (swigCMemOwn) {
288        swigCMemOwn = false;
289        libsbmlJNI.delete_UnitDefinition(swigCPtr);
290      }
291      swigCPtr = 0;
292    }
293    super.delete();
294  }
295
296  
297/**
298   * Creates a new {@link UnitDefinition} using the given SBML <code>level</code> and <code>version</code>
299   * values.
300   * <p>
301   * @param level a long integer, the SBML Level to assign to this {@link UnitDefinition}
302   * <p>
303   * @param version a long integer, the SBML Version to assign to this
304   * {@link UnitDefinition}
305   * <p>
306   * @throws SBMLConstructorException 
307   * Thrown if the given <code>level</code> and <code>version</code> combination, or this kind
308   * of SBML object, are either invalid or mismatched with respect to the
309   * parent {@link SBMLDocument} object.
310   * <p>
311   * @note Upon the addition of a {@link UnitDefinition} object to an {@link SBMLDocument}
312   * (e.g., using {@link Model#addUnitDefinition(UnitDefinition ud)}), the SBML Level, SBML Version
313   * and XML namespace of the document <em>override</em> the values used
314   * when creating the {@link UnitDefinition} object via this constructor.  This is
315   * necessary to ensure that an SBML document is a consistent structure.
316   * Nevertheless, the ability to supply the values at the time of creation
317   * of a {@link UnitDefinition} is an important aid to producing valid SBML.
318   * Knowledge of the intented SBML Level and Version determine whether it
319   * is valid to assign a particular value to an attribute, or whether it
320   * is valid to add an object to an existing {@link SBMLDocument}.
321   */ public
322 UnitDefinition(long level, long version) throws org.sbml.libsbml.SBMLConstructorException {
323    this(libsbmlJNI.new_UnitDefinition__SWIG_0(level, version), true);
324  }
325
326  
327/**
328   * Creates a new {@link UnitDefinition} using the given {@link SBMLNamespaces} object
329   * <code>sbmlns</code>.
330   * <p>
331   * The {@link SBMLNamespaces} object encapsulates SBML Level/Version/namespaces
332   * information.  It is used to communicate the SBML Level, Version, and
333   * (in Level&nbsp;3) packages used in addition to SBML Level&nbsp;3 Core.
334   * A common approach to using this class constructor is to create an
335   * {@link SBMLNamespaces} object somewhere in a program, once, then pass it to
336   * object constructors such as this one when needed.
337   * <p>
338   * @param sbmlns an {@link SBMLNamespaces} object.
339   * <p>
340   * @throws SBMLConstructorException 
341   * Thrown if the given <code>level</code> and <code>version</code> combination, or this kind
342   * of SBML object, are either invalid or mismatched with respect to the
343   * parent {@link SBMLDocument} object.
344   * <p>
345   * @note Upon the addition of a {@link UnitDefinition} object to an {@link SBMLDocument}
346   * (e.g., using {@link Model#addUnitDefinition(UnitDefinition ud)}), the SBML XML namespace of
347   * the document <em>overrides</em> the value used when creating the
348   * {@link UnitDefinition} object via this constructor.  This is necessary to
349   * ensure that an SBML document is a consistent structure.  Nevertheless,
350   * the ability to supply the values at the time of creation of a
351   * {@link UnitDefinition} is an important aid to producing valid SBML.  Knowledge
352   * of the intented SBML Level and Version determine whether it is valid
353   * to assign a particular value to an attribute, or whether it is valid
354   * to add an object to an existing {@link SBMLDocument}.
355   */ public
356 UnitDefinition(SBMLNamespaces sbmlns) throws org.sbml.libsbml.SBMLConstructorException {
357    this(libsbmlJNI.new_UnitDefinition__SWIG_1(SBMLNamespaces.getCPtr(sbmlns), sbmlns), true);
358  }
359
360  
361/**
362   * Copy constructor; creates a copy of this {@link UnitDefinition}.
363   * <p>
364   * @param orig the object to copy.
365   * <p>
366   * @throws SBMLConstructorException 
367   * Thrown if the argument <code>orig</code> is <code>null.</code>
368   */ public
369 UnitDefinition(UnitDefinition orig) throws org.sbml.libsbml.SBMLConstructorException {
370    this(libsbmlJNI.new_UnitDefinition__SWIG_2(UnitDefinition.getCPtr(orig), orig), true);
371  }
372
373  
374/**
375   * Creates and returns a deep copy of this {@link UnitDefinition}.
376   * <p>
377   * @return a (deep) copy of this {@link UnitDefinition}.
378   */ public
379 UnitDefinition cloneObject() {
380    long cPtr = libsbmlJNI.UnitDefinition_cloneObject(swigCPtr, this);
381    return (cPtr == 0) ? null : new UnitDefinition(cPtr, true);
382  }
383
384  
385/**
386   * 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.
387   * <p>
388   * @param id string representing the id of objects to find.
389   * <p>
390   * @return pointer to the first element found with the given <code>id</code>.
391   */ public
392 SBase getElementBySId(String id) {
393  return libsbml.DowncastSBase(libsbmlJNI.UnitDefinition_getElementBySId(swigCPtr, this, id), false);
394}
395
396  
397/**
398   * Returns the first child element it can find with the given <code>metaid</code>, or <code>null</code> if no such object is found.
399   * <p>
400   * @param metaid string representing the metaid of objects to find
401   * <p>
402   * @return pointer to the first element found with the given <code>metaid</code>.
403   */ public
404 SBase getElementByMetaId(String metaid) {
405  return libsbml.DowncastSBase(libsbmlJNI.UnitDefinition_getElementByMetaId(swigCPtr, this, metaid), false);
406}
407
408  
409/**
410   * Returns the value of the 'id' attribute of this {@link UnitDefinition}.
411   * <p>
412   * @return the id of this {@link UnitDefinition}.
413   */ public
414 String getId() {
415    return libsbmlJNI.UnitDefinition_getId(swigCPtr, this);
416  }
417
418  
419/**
420   * Returns the value of the 'name' attribute of this {@link UnitDefinition}.
421   * <p>
422   * @return the name of this {@link UnitDefinition}.
423   */ public
424 String getName() {
425    return libsbmlJNI.UnitDefinition_getName(swigCPtr, this);
426  }
427
428  
429/**
430   * Predicate returning <code>true</code> if this
431   * {@link UnitDefinition}'s 'id' attribute is set.
432   * <p>
433   * @return <code>true</code> if the 'id' attribute of this {@link UnitDefinition} is
434   * set, <code>false</code> otherwise.
435   */ public
436 boolean isSetId() {
437    return libsbmlJNI.UnitDefinition_isSetId(swigCPtr, this);
438  }
439
440  
441/**
442   * Predicate returning <code>true</code> if this
443   * {@link UnitDefinition}'s 'name' attribute is set.
444   * <p>
445   * @return <code>true</code> if the 'name' attribute of this {@link UnitDefinition} is
446   * set, <code>false</code> otherwise.
447   */ public
448 boolean isSetName() {
449    return libsbmlJNI.UnitDefinition_isSetName(swigCPtr, this);
450  }
451
452  
453/**
454   * Sets the value of the 'id' attribute of this {@link UnitDefinition}.
455   * <p>
456   * The string <code>sid</code> is copied.  Note that SBML has strict requirements
457   * for the syntax of identifiers.  The following is a summary of the definition of the SBML identifier type 
458<code>SId</code>, which defines the permitted syntax of identifiers.  We
459express the syntax using an extended form of BNF notation: 
460<pre style='margin-left: 2em; border: none; font-weight: bold; font-size: 13px; color: black'>
461letter .= 'a'..'z','A'..'Z'
462digit  .= '0'..'9'
463idChar .= letter | digit | '_'
464SId    .= ( letter | '_' ) idChar*
465</pre>
466The characters <code>(</code> and <code>)</code> are used for grouping, the
467character <code>*</code> 'zero or more times', and the character
468<code>|</code> indicates logical 'or'.  The equality of SBML identifiers is
469determined by an exact character sequence match; i.e., comparisons must be
470performed in a case-sensitive manner.  In addition, there are a few
471conditions for the uniqueness of identifiers in an SBML model.  Please
472consult the SBML specifications for the exact formulations.
473<p>
474
475   * <p>
476   * @param sid the string to use as the identifier of this {@link UnitDefinition}
477   * <p>
478   * @return integer value indicating success/failure of the
479   * function.  The possible values
480   * returned by this function are:
481   * <ul>
482   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS }
483   * <li> {@link  libsbmlConstants#LIBSBML_INVALID_ATTRIBUTE_VALUE LIBSBML_INVALID_ATTRIBUTE_VALUE }
484   * </ul>
485   */ public
486 int setId(String sid) {
487    return libsbmlJNI.UnitDefinition_setId(swigCPtr, this, sid);
488  }
489
490  
491/**
492   * Sets the value of the 'name' attribute of this {@link UnitDefinition}.
493   * <p>
494   * The string in <code>name</code> is copied.
495   * <p>
496   * @param name the new name for the {@link UnitDefinition}
497   * <p>
498   * @return integer value indicating success/failure of the
499   * function.  The possible values
500   * returned by this function are:
501   * <ul>
502   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS }
503   * <li> {@link  libsbmlConstants#LIBSBML_INVALID_ATTRIBUTE_VALUE LIBSBML_INVALID_ATTRIBUTE_VALUE }
504   * </ul>
505   */ public
506 int setName(String name) {
507    return libsbmlJNI.UnitDefinition_setName(swigCPtr, this, name);
508  }
509
510  
511/**
512   * Unsets the value of the 'name' attribute of this {@link UnitDefinition}.
513   * <p>
514   * @return integer value indicating success/failure of the
515   * function.  The possible values
516   * returned by this function are:
517   * <ul>
518   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS }
519   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED }
520   * </ul>
521   */ public
522 int unsetName() {
523    return libsbmlJNI.UnitDefinition_unsetName(swigCPtr, this);
524  }
525
526  
527/**
528   * Convenience function for testing if a given unit definition is a
529   * variant of the predefined unit identifier <code>'area'.</code>
530   * <p>
531   * @return <code>true</code> if this {@link UnitDefinition} is a variant of the predefined
532   * unit <code>area</code>, meaning square metres with only abritrary variations
533   * in scale or multiplier values; <code>false</code> otherwise.
534   */ public
535 boolean isVariantOfArea() {
536    return libsbmlJNI.UnitDefinition_isVariantOfArea(swigCPtr, this);
537  }
538
539  
540/**
541   * Convenience function for testing if a given unit definition is a
542   * variant of the predefined unit identifier <code>'length'.</code>
543   * <p>
544   * @return <code>true</code> if this {@link UnitDefinition} is a variant of the predefined
545   * unit <code>length</code>, meaning metres with only abritrary variations in scale
546   * or multiplier values; <code>false</code> otherwise.
547   */ public
548 boolean isVariantOfLength() {
549    return libsbmlJNI.UnitDefinition_isVariantOfLength(swigCPtr, this);
550  }
551
552  
553/**
554   * Convenience function for testing if a given unit definition is a
555   * variant of the predefined unit identifier <code>'substance'.</code>
556   * <p>
557   * @return <code>true</code> if this {@link UnitDefinition} is a variant of the predefined
558   * unit <code>substance</code>, meaning moles or items (and grams or kilograms from
559   * SBML Level&nbsp;2 Version&nbsp;2 onwards) with only abritrary variations
560   * in scale or multiplier values; <code>false</code> otherwise.
561   */ public
562 boolean isVariantOfSubstance() {
563    return libsbmlJNI.UnitDefinition_isVariantOfSubstance(swigCPtr, this);
564  }
565
566  
567/**
568   * Convenience function for testing if a given unit definition is a
569   * variant of the predefined unit identifier <code>'time'.</code>
570   * <p>
571   * @return <code>true</code> if this {@link UnitDefinition} is a variant of the predefined
572   * unit <code>time</code>, meaning seconds with only abritrary variations in scale or
573   * multiplier values; <code>false</code> otherwise.
574   */ public
575 boolean isVariantOfTime() {
576    return libsbmlJNI.UnitDefinition_isVariantOfTime(swigCPtr, this);
577  }
578
579  
580/**
581   * Convenience function for testing if a given unit definition is a
582   * variant of the predefined unit identifier <code>'volume'.</code>
583   * <p>
584   * @return <code>true</code> if this {@link UnitDefinition} is a variant of the predefined
585   * unit <code>volume</code>, meaning litre or cubic metre with only abritrary
586   * variations in scale or multiplier values; <code>false</code> otherwise.
587   */ public
588 boolean isVariantOfVolume() {
589    return libsbmlJNI.UnitDefinition_isVariantOfVolume(swigCPtr, this);
590  }
591
592  
593/**
594   * Convenience function for testing if a given unit definition is a
595   * variant of the unit <code>'dimensionless'.</code>
596   * <p>
597   * @return <code>true</code> if this {@link UnitDefinition} is a variant of 
598   * <code>dimensionless</code>, meaning dimensionless with only abritrary variations in
599   * scale or multiplier values; <code>false</code> otherwise.
600   */ public
601 boolean isVariantOfDimensionless() {
602    return libsbmlJNI.UnitDefinition_isVariantOfDimensionless(swigCPtr, this);
603  }
604
605  
606/**
607   * Convenience function for testing if a given unit definition is a
608   * variant of the predefined unit identifier <code>'mass'.</code>
609   * <p>
610   * @return <code>true</code> if this {@link UnitDefinition} is a variant of mass units,
611   * meaning gram or kilogram with only abritrary variations in scale or
612   * multiplier values; <code>false</code> otherwise.
613   */ public
614 boolean isVariantOfMass() {
615    return libsbmlJNI.UnitDefinition_isVariantOfMass(swigCPtr, this);
616  }
617
618  
619/**
620   * Convenience function for testing if a given unit definition is a
621   * variant of the predefined unit <code>'substance'</code> divided by the predefined
622   * unit <code>'time'.</code>
623   * <p>
624   * @return <code>true</code> if this {@link UnitDefinition} is a variant of the predefined
625   * unit <code>substance</code> per predefined unit <code>time</code>, meaning it contains two
626   * units one of which is a variant of substance and the other is a
627   * variant of time which an exponent of -1; <code>false</code> otherwise.
628   */ public
629 boolean isVariantOfSubstancePerTime() {
630    return libsbmlJNI.UnitDefinition_isVariantOfSubstancePerTime(swigCPtr, this);
631  }
632
633  
634/**
635   * Adds a copy of the given {@link Unit} to this {@link UnitDefinition}.
636   * <p>
637   * @param u the {@link Unit} instance to add to this {@link UnitDefinition}.
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_LEVEL_MISMATCH LIBSBML_LEVEL_MISMATCH }
645   * <li> {@link  libsbmlConstants#LIBSBML_VERSION_MISMATCH LIBSBML_VERSION_MISMATCH }
646   * <li> {@link  libsbmlConstants#LIBSBML_INVALID_OBJECT LIBSBML_INVALID_OBJECT }
647   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED }
648   * </ul>
649   * <p>
650   * @note This method should be used with some caution.  The fact that
651   * this method <em>copies</em> the object passed to it means that the caller
652   * will be left holding a physically different object instance than the
653   * one contained in this {@link UnitDefinition}.  Changes made to the original
654   * object instance (such as resetting attribute values) will <em>not
655   * affect the instance in the {@link UnitDefinition}</em>.  In addition, the
656   * caller should make sure to free the original object if it is no longer
657   * being used, or else a memory leak will result.  Please see
658   * {@link UnitDefinition#createUnit()} for a method that does not lead to these
659   * issues.
660   * <p>
661   * @see #createUnit()
662   */ public
663 int addUnit(Unit u) {
664    return libsbmlJNI.UnitDefinition_addUnit(swigCPtr, this, Unit.getCPtr(u), u);
665  }
666
667  
668/**
669   * Creates a new and empty {@link Unit}, adds it to this {@link UnitDefinition}'s list of
670   * units, and returns it.
671   * <p>
672   * @return a newly constructed (and empty) {@link Unit} instance.
673   * <p>
674   * @note It is worth emphasizing that the attribute 'kind' value of a
675   * {@link Unit} is a required attribute for a valid {@link Unit} definition.  The
676   * createUnit() method does not assign a valid kind to the constructed
677   * unit (instead, it sets the 'kind' to {@link  libsbmlConstants#UNIT_KIND_INVALID UNIT_KIND_INVALID}).
678   * Callers are cautioned to set the newly-constructed {@link Unit}'s kind using
679   * {@link Unit#setKind(int kind)} soon after calling this method.
680   * <p>
681   * @see #addUnit(Unit u)
682   */ public
683 Unit createUnit() {
684    long cPtr = libsbmlJNI.UnitDefinition_createUnit(swigCPtr, this);
685    return (cPtr == 0) ? null : new Unit(cPtr, false);
686  }
687
688  
689/**
690   * Returns the list of Units for this {@link UnitDefinition} instance.
691   * @return the {@link ListOfUnits} value for this {@link UnitDefinition}.
692   */ public
693 ListOfUnits getListOfUnits() {
694    long cPtr = libsbmlJNI.UnitDefinition_getListOfUnits__SWIG_0(swigCPtr, this);
695    return (cPtr == 0) ? null : new ListOfUnits(cPtr, false);
696  }
697
698  
699/**
700   * Returns a specific {@link Unit} instance belonging to this {@link UnitDefinition}.
701   * <p>
702   * @param n an integer, the index of the {@link Unit} to be returned.
703   * <p>
704   * @return the nth {@link Unit} of this {@link UnitDefinition}.
705   * <p>
706   * @see #getNumUnits()
707   */ public
708 Unit getUnit(long n) {
709    long cPtr = libsbmlJNI.UnitDefinition_getUnit__SWIG_0(swigCPtr, this, n);
710    return (cPtr == 0) ? null : new Unit(cPtr, false);
711  }
712
713  
714/**
715   * Returns the number of {@link Unit} objects contained within this
716   * {@link UnitDefinition}.
717   * <p>
718   * @return an integer representing the number of Units in this
719   * {@link UnitDefinition}.
720   */ public
721 long getNumUnits() {
722    return libsbmlJNI.UnitDefinition_getNumUnits(swigCPtr, this);
723  }
724
725  
726/**
727   * Removes the nth {@link Unit} object from this {@link UnitDefinition} object and
728   * returns a pointer to it.
729   * <p>
730   * The caller owns the returned object and is responsible for deleting it.
731   * <p>
732   * @param n the index of the {@link Unit} object to remove
733   * <p>
734   * @return the {@link Unit} object removed, or <code>null</code> if the given index 
735   * is out of range.
736   * <p>
737   */ public
738 Unit removeUnit(long n) {
739    long cPtr = libsbmlJNI.UnitDefinition_removeUnit(swigCPtr, this, n);
740    return (cPtr == 0) ? null : new Unit(cPtr, true);
741  }
742
743  
744/**
745   * Sets this SBML object to child SBML objects (if any).
746   * (Creates a child-parent relationship by the parent)
747   * <p>
748   * Subclasses must override this function if they define
749   * one ore more child elements.
750   * Basically, this function needs to be called in
751   * constructor, copy constructor and assignment operator.
752   * <p>
753   * @see setSBMLDocument
754   * @see enablePackageInternal
755   * @internal
756   */ public
757 void connectToChild() {
758    libsbmlJNI.UnitDefinition_connectToChild(swigCPtr, this);
759  }
760
761  
762/**
763   * Enables/Disables the given package with this element and child
764   * elements (if any).
765   * (This is an internal implementation for enablePackage function)
766   * <p>
767   * @note Subclasses of the SBML Core package in which one or more child
768   * elements are defined must override this function.
769   * @internal
770   */ public
771 void enablePackageInternal(String pkgURI, String pkgPrefix, boolean flag) {
772    libsbmlJNI.UnitDefinition_enablePackageInternal(swigCPtr, this, pkgURI, pkgPrefix, flag);
773  }
774
775  
776/**
777   * Returns the libSBML type code for this object instance.
778   * <p>
779   * LibSBML attaches an identifying code to every
780   * kind of SBML object.  These are known as <em>SBML type codes</em>.  In
781   * other languages, the set of type codes is stored in an enumeration; in
782   * the Java language interface for libSBML, the type codes are defined as
783   * static integer constants in the interface class {@link
784   * libsbmlConstants}.  The names of the type codes all begin with the
785   * characters <code>SBML_.</code> 
786   * <p>
787   * @return the SBML type code for this object, or {@link  libsbmlConstants#SBML_UNKNOWN SBML_UNKNOWN} (default).
788   * <p>
789   * @see #getElementName()
790   */ public
791 int getTypeCode() {
792    return libsbmlJNI.UnitDefinition_getTypeCode(swigCPtr, this);
793  }
794
795  
796/**
797   * Returns the XML element name of this object, which for {@link UnitDefinition},
798   * is always <code>'unitDefinition'.</code>
799   * <p>
800   * @return the name of this element, i.e., <code>'unitDefinition'.</code>
801   */ public
802 String getElementName() {
803    return libsbmlJNI.UnitDefinition_getElementName(swigCPtr, this);
804  }
805
806  
807/** 
808   * Simplifies the {@link UnitDefinition} such that any given kind of {@link Unit} object
809   * occurs only once in the {@link ListOfUnits}.
810   * <p>
811   * For example, the following definition,
812   * <div class='fragment'><pre>
813 &lt;unitDefinition&gt;
814  &lt;listOfUnits&gt;
815    &lt;unit kind='metre' exponent='1'/&gt;
816    &lt;unit kind='metre' exponent='2'/&gt;
817  &lt;/listOfUnits&gt;
818 &lt;unitDefinition&gt;
819 </pre></div>
820   * will be simplified to 
821   * <div class='fragment'><pre>
822 &lt;unitDefinition&gt;
823   &lt;listOfUnits&gt;
824     &lt;unit kind='metre' exponent='3'/&gt;
825   &lt;/listOfUnits&gt;
826 &lt;unitDefinition&gt;
827 </pre></div>
828   * <p>
829   * @param ud the {@link UnitDefinition} object to be simplified.
830   * <p>
831   * @note Because this is a <em>static</em> method, the
832   * non-C++ language interfaces for libSBML will contain two variants.  One
833   * will be a static method on the class (i.e., {@link UnitDefinition}), and the
834   * other will be a standalone top-level function with the name
835   * UnitDefinition_simplify(). They are functionally identical. 
836   */ public
837 static void simplify(UnitDefinition ud) {
838    libsbmlJNI.UnitDefinition_simplify(UnitDefinition.getCPtr(ud), ud);
839  }
840
841  
842/** 
843   * Alphabetically orders the {@link Unit} objects within the {@link ListOfUnits} of a
844   * {@link UnitDefinition}.
845   * <p>
846   * @param ud the {@link UnitDefinition} object whose units are to be reordered.
847   * <p>
848   * @note Because this is a <em>static</em> method, the
849   * non-C++ language interfaces for libSBML will contain two variants.  One
850   * will be a static method on the class (i.e., {@link UnitDefinition}), and the
851   * other will be a standalone top-level function with the name
852   * UnitDefinition_reorder(). They are functionally identical. 
853   */ public
854 static void reorder(UnitDefinition ud) {
855    libsbmlJNI.UnitDefinition_reorder(UnitDefinition.getCPtr(ud), ud);
856  }
857
858  
859/**
860   * Convert a given {@link UnitDefinition} into a new {@link UnitDefinition} object
861   * that uses SI units.
862   * <p>
863   * @param ud the {@link UnitDefinition} object to convert to SI
864   * <p>
865   * @return a new {@link UnitDefinition} object representing the results of the
866   * conversion.
867   * <p>
868   * @note Because this is a <em>static</em> method, the
869   * non-C++ language interfaces for libSBML will contain two variants.  One
870   * will be a static method on the class (i.e., {@link UnitDefinition}), and the
871   * other will be a standalone top-level function with the name
872   * UnitDefinition_convertToSI(). They are functionally identical. 
873   */ public
874 static UnitDefinition convertToSI(UnitDefinition ud) {
875    long cPtr = libsbmlJNI.UnitDefinition_convertToSI(UnitDefinition.getCPtr(ud), ud);
876    return (cPtr == 0) ? null : new UnitDefinition(cPtr, true);
877  }
878
879  
880/** 
881   * Predicate returning <code>true</code> if two
882   * {@link UnitDefinition} objects are identical.
883   * <p>
884   * For the purposes of performing this comparison, two {@link UnitDefinition}
885   * objects are considered identical when they contain identical lists of
886   * {@link Unit} objects.  Pairs of {@link Unit} objects in the lists are in turn
887   * considered identical if they satisfy the predicate
888   * {@link Unit#areIdentical(Unit u1, Unit u2)}.
889   * The predicate compares every attribute of the
890   * {@link Unit} objects.
891   * <p>
892   * @param ud1 the first {@link UnitDefinition} object to compare
893   * @param ud2 the second {@link UnitDefinition} object to compare
894   * <p>
895   * @return <code>true</code> if all the {@link Unit} objects in ud1 are identical to the
896   * {@link Unit} objects of ud2, <code>false</code> otherwise.
897   * <p>
898   * @note Because this is a <em>static</em> method, the
899   * non-C++ language interfaces for libSBML will contain two variants.  One
900   * will be a static method on the class (i.e., {@link UnitDefinition}), and the
901   * other will be a standalone top-level function with the name
902   * UnitDefinition_areIdentical(). They are functionally identical. 
903   * <p>
904   * @see UnitDefinition#areEquivalent(UnitDefinition  ud1, UnitDefinition  ud2)
905   * @see Unit#areIdentical(Unit  unit1, Unit  unit2)
906   */ public
907 static boolean areIdentical(UnitDefinition ud1, UnitDefinition ud2) {
908    return libsbmlJNI.UnitDefinition_areIdentical(UnitDefinition.getCPtr(ud1), ud1, UnitDefinition.getCPtr(ud2), ud2);
909  }
910
911  
912/** 
913   * Predicate returning <code>true</code> if two
914   * {@link UnitDefinition} objects are equivalent.
915   * <p>
916   * For the purposes of performing this comparison, two {@link UnitDefinition}
917   * objects are considered equivalent when they contain <em>equivalent</em>
918   * list of {@link Unit} objects.  {@link Unit} objects are in turn considered equivalent
919   * if they satisfy the predicate
920   * {@link Unit#areEquivalent(Unit u1, Unit u2)}.
921   * The predicate tests a subset of the objects's attributes.
922   * <p>
923   * @param ud1 the first {@link UnitDefinition} object to compare
924   * <p>
925   * @param ud2 the second {@link UnitDefinition} object to compare
926   * <p>
927   * @return <code>true</code> if all the {@link Unit} objects in ud1 are equivalent
928   * to the {@link Unit} objects in ud2, <code>false</code> otherwise.
929   * <p>
930   * @note Because this is a <em>static</em> method, the
931   * non-C++ language interfaces for libSBML will contain two variants.  One
932   * will be a static method on the class (i.e., {@link UnitDefinition}), and the
933   * other will be a standalone top-level function with the name
934   * UnitDefinition_areEquivalent(). They are functionally identical. 
935   * <p>
936   * @see UnitDefinition#areIdentical(UnitDefinition  ud1, UnitDefinition  ud2)
937   * @see Unit#areEquivalent(Unit  unit1, Unit  unit2)
938   */ public
939 static boolean areEquivalent(UnitDefinition ud1, UnitDefinition ud2) {
940    return libsbmlJNI.UnitDefinition_areEquivalent(UnitDefinition.getCPtr(ud1), ud1, UnitDefinition.getCPtr(ud2), ud2);
941  }
942
943  
944/** 
945   * Combines two {@link UnitDefinition} objects into a single {@link UnitDefinition}.
946   * <p>
947   * This takes {@link UnitDefinition} objects <code>ud1</code> and <code>ud2</code>, and creates a
948   * {@link UnitDefinition} object that expresses the product of the units of 
949   * <code>ud1</code> and <code>ud2</code>.
950   * <p>
951   * @param ud1 the first {@link UnitDefinition} object 
952   * @param ud2 the second {@link UnitDefinition} object
953   * <p>
954   * @return a {@link UnitDefinition} which represents the product of the 
955   * units of the two argument UnitDefinitions.
956   * <p>
957   * @note Because this is a <em>static</em> method, the
958   * non-C++ language interfaces for libSBML will contain two variants.  One
959   * will be a static method on the class (i.e., {@link UnitDefinition}), and the
960   * other will be a standalone top-level function with the name
961   * UnitDefinition_combine(). They are functionally identical. 
962   */ public
963 static UnitDefinition combine(UnitDefinition ud1, UnitDefinition ud2) {
964    long cPtr = libsbmlJNI.UnitDefinition_combine(UnitDefinition.getCPtr(ud1), ud1, UnitDefinition.getCPtr(ud2), ud2);
965    return (cPtr == 0) ? null : new UnitDefinition(cPtr, true);
966  }
967
968  
969/** 
970   * Expresses the given definition in a plain-text form.
971   * <p>
972   * For example,
973   * {@link UnitDefinition#printUnits(UnitDefinition u)}
974   * applied to
975   * <div class='fragment'><pre>
976 &lt;unitDefinition&gt;
977  &lt;listOfUnits&gt;
978    &lt;unit kind='metre' exponent='1'/&gt;
979    &lt;unit kind='second' exponent='-2'/&gt;
980  &lt;/listOfUnits&gt;
981 &lt;unitDefinition&gt;
982 </pre></div>
983   * will return the string <code>'metre (exponent = 1, multiplier = 1,
984   * scale = 0) second (exponent = -2, multiplier = 1, scale = 0)'</code>
985   * or, if the optional parameter <code>compact</code> is given the value <code>true</code>,
986   * the string <code>'(1 metre)^1 (1 second)^-2'</code>.  This method may
987   * be useful for printing unit information to human users, or in
988   * debugging software, or other situations.
989   * <p>
990   * @param ud the {@link UnitDefinition} object
991   * @param compact boolean indicating whether the compact form
992   * should be used (defaults to false)
993   * <p>
994   * @return a string expressing the unit definition defined by the given
995   * {@link UnitDefinition} object <code>ud</code>.
996   * <p>
997   * @note Because this is a <em>static</em> method, the
998   * non-C++ language interfaces for libSBML will contain two variants.  One
999   * will be a static method on the class (i.e., {@link UnitDefinition}), and the
1000   * other will be a standalone top-level function with the name
1001   * UnitDefinition_printUnits(). They are functionally identical. 
1002   */ public
1003 static String printUnits(UnitDefinition ud, boolean compact) {
1004    return libsbmlJNI.UnitDefinition_printUnits__SWIG_0(UnitDefinition.getCPtr(ud), ud, compact);
1005  }
1006
1007  
1008/** 
1009   * Expresses the given definition in a plain-text form.
1010   * <p>
1011   * For example,
1012   * {@link UnitDefinition#printUnits(UnitDefinition u)}
1013   * applied to
1014   * <div class='fragment'><pre>
1015 &lt;unitDefinition&gt;
1016  &lt;listOfUnits&gt;
1017    &lt;unit kind='metre' exponent='1'/&gt;
1018    &lt;unit kind='second' exponent='-2'/&gt;
1019  &lt;/listOfUnits&gt;
1020 &lt;unitDefinition&gt;
1021 </pre></div>
1022   * will return the string <code>'metre (exponent = 1, multiplier = 1,
1023   * scale = 0) second (exponent = -2, multiplier = 1, scale = 0)'</code>
1024   * or, if the optional parameter <code>compact</code> is given the value <code>true</code>,
1025   * the string <code>'(1 metre)^1 (1 second)^-2'</code>.  This method may
1026   * be useful for printing unit information to human users, or in
1027   * debugging software, or other situations.
1028   * <p>
1029   * @param ud the {@link UnitDefinition} object
1030   * @param compact boolean indicating whether the compact form
1031   * should be used (defaults to false)
1032   * <p>
1033   * @return a string expressing the unit definition defined by the given
1034   * {@link UnitDefinition} object <code>ud</code>.
1035   * <p>
1036   * @note Because this is a <em>static</em> method, the
1037   * non-C++ language interfaces for libSBML will contain two variants.  One
1038   * will be a static method on the class (i.e., {@link UnitDefinition}), and the
1039   * other will be a standalone top-level function with the name
1040   * UnitDefinition_printUnits(). They are functionally identical. 
1041   */ public
1042 static String printUnits(UnitDefinition ud) {
1043    return libsbmlJNI.UnitDefinition_printUnits__SWIG_1(UnitDefinition.getCPtr(ud), ud);
1044  }
1045
1046  
1047/**
1048   * Predicate returning <code>true</code> if
1049   * all the required attributes for this {@link UnitDefinition} object
1050   * have been set.
1051   * <p>
1052   * @note The required attributes for a {@link UnitDefinition} object are:
1053   * <ul>
1054   * <li> 'id'
1055   * </ul>
1056   * <p>
1057   * @return a boolean value indicating whether all the required
1058   * attributes for this object have been defined.
1059   */ public
1060 boolean hasRequiredAttributes() {
1061    return libsbmlJNI.UnitDefinition_hasRequiredAttributes(swigCPtr, this);
1062  }
1063
1064  
1065/**
1066   * Predicate returning <code>true</code> if
1067   * all the required elements for this {@link UnitDefinition} object
1068   * have been set.
1069   * <p>
1070   * @note The required elements for a {@link Constraint} object are:
1071   * <ul>
1072   * <li> 'listOfUnits' (required in SBML Level&nbsp;2 only, optional in Level&nbsp;3)
1073   * </ul>
1074   * <p>
1075   * @return a boolean value indicating whether all the required
1076   * elements for this object have been defined.
1077   */ public
1078 boolean hasRequiredElements() {
1079    return libsbmlJNI.UnitDefinition_hasRequiredElements(swigCPtr, this);
1080  }
1081
1082}