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