001/* ----------------------------------------------------------------------------
002 * This file was automatically generated by SWIG (http://www.swig.org).
003 * Version 3.0.7
004 *
005 * Do not make changes to this file unless you know what you are doing--modify
006 * the SWIG interface file instead.
007 * ----------------------------------------------------------------------------- */
008
009package org.sbml.libsbml;
010
011/** 
012 *  A list of {@link Unit} objects.
013 <p>
014 * {@link ListOfUnits} is entirely contained within {@link UnitDefinition}.
015 <p>
016 * <p>
017 * The various ListOf___ classes in SBML
018 * are merely containers used for organizing the main components of an SBML
019 * model.  In libSBML's implementation, ListOf___
020 * classes are derived from the
021 * intermediate utility class {@link ListOf}, which
022 * is not defined by the SBML specifications but serves as a useful
023 * programmatic construct.  {@link ListOf} is itself is in turn derived from {@link SBase},
024 * which provides all of the various ListOf___
025 * classes with common features
026 * defined by the SBML specification, such as 'metaid' attributes and
027 * annotations.
028 <p>
029 * The relationship between the lists and the rest of an SBML model is
030 * illustrated by the following (for SBML Level&nbsp;2 Version&nbsp;4):
031 <p>
032 * <figure>
033  <object type="image/svg+xml" data="listof-illustration.svg" class="centered"></object>
034</figure>
035
036 <p>
037 * Readers may wonder about the motivations for using the ListOf___
038 * containers in SBML.  A simpler approach in XML might be to place the
039 * components all directly at the top level of the model definition.  The
040 * choice made in SBML is to group them within XML elements named after
041 * ListOf<em>Classname</em>, in part because it helps organize the
042 * components.  More importantly, the fact that the container classes are
043 * derived from {@link SBase} means that software tools can add information <em>about</em>
044 * the lists themselves into each list container's 'annotation'.
045 <p>
046 * @see ListOfFunctionDefinitions
047 * @see ListOfUnitDefinitions
048 * @see ListOfCompartmentTypes
049 * @see ListOfSpeciesTypes
050 * @see ListOfCompartments
051 * @see ListOfSpecies
052 * @see ListOfParameters
053 * @see ListOfInitialAssignments
054 * @see ListOfRules
055 * @see ListOfConstraints
056 * @see ListOfReactions
057 * @see ListOfEvents
058 */
059
060public class ListOfUnits extends ListOf {
061   private long swigCPtr;
062
063   protected ListOfUnits(long cPtr, boolean cMemoryOwn)
064   {
065     super(libsbmlJNI.ListOfUnits_SWIGUpcast(cPtr), cMemoryOwn);
066     swigCPtr = cPtr;
067   }
068
069   protected static long getCPtr(ListOfUnits obj)
070   {
071     return (obj == null) ? 0 : obj.swigCPtr;
072   }
073
074   protected static long getCPtrAndDisown (ListOfUnits obj)
075   {
076     long ptr = 0;
077
078     if (obj != null)
079     {
080       ptr             = obj.swigCPtr;
081       obj.swigCMemOwn = false;
082     }
083
084     return ptr;
085   }
086
087  protected void finalize() {
088    delete();
089  }
090
091  public synchronized void delete() {
092    if (swigCPtr != 0) {
093      if (swigCMemOwn) {
094        swigCMemOwn = false;
095        libsbmlJNI.delete_ListOfUnits(swigCPtr);
096      }
097      swigCPtr = 0;
098    }
099    super.delete();
100  }
101
102  
103/**
104   * Creates a new {@link ListOfUnits} object.
105   <p>
106   * The object is constructed such that it is valid for the given SBML
107   * Level and Version combination.
108   <p>
109   * @param level the SBML Level
110   <p>
111   * @param version the Version within the SBML Level
112   <p>
113   * <p>
114 * @throws SBMLConstructorException
115 * Thrown if the given <code>level</code> and <code>version</code> combination are invalid
116 * or if this object is incompatible with the given level and version.
117   <p>
118   * <p>
119 * @note Attempting to add an object to an {@link SBMLDocument} having a different
120 * combination of SBML Level, Version and XML namespaces than the object
121 * itself will result in an error at the time a caller attempts to make the
122 * addition.  A parent object must have compatible Level, Version and XML
123 * namespaces.  (Strictly speaking, a parent may also have more XML
124 * namespaces than a child, but the reverse is not permitted.)  The
125 * restriction is necessary to ensure that an SBML model has a consistent
126 * overall structure.  This requires callers to manage their objects
127 * carefully, but the benefit is increased flexibility in how models can be
128 * created by permitting callers to create objects bottom-up if desired.  In
129 * situations where objects are not yet attached to parents (e.g.,
130 * {@link SBMLDocument}), knowledge of the intented SBML Level and Version help
131 * libSBML determine such things as whether it is valid to assign a
132 * particular value to an attribute.
133   */ public
134 ListOfUnits(long level, long version) throws org.sbml.libsbml.SBMLConstructorException {
135    this(libsbmlJNI.new_ListOfUnits__SWIG_0(level, version), true);
136  }
137
138  
139/**
140   * Creates a new {@link ListOfUnits} object.
141   <p>
142   * The object is constructed such that it is valid for the SBML Level and
143   * Version combination determined by the {@link SBMLNamespaces} object in 
144   * <code>sbmlns</code>.
145   <p>
146   * @param sbmlns an {@link SBMLNamespaces} object that is used to determine the
147   * characteristics of the {@link ListOfUnits} object to be created.
148   <p>
149   * <p>
150 * @throws SBMLConstructorException
151 * Thrown if the given <code>sbmlns</code> is inconsistent or incompatible
152 * with this object.
153   <p>
154   * <p>
155 * @note Attempting to add an object to an {@link SBMLDocument} having a different
156 * combination of SBML Level, Version and XML namespaces than the object
157 * itself will result in an error at the time a caller attempts to make the
158 * addition.  A parent object must have compatible Level, Version and XML
159 * namespaces.  (Strictly speaking, a parent may also have more XML
160 * namespaces than a child, but the reverse is not permitted.)  The
161 * restriction is necessary to ensure that an SBML model has a consistent
162 * overall structure.  This requires callers to manage their objects
163 * carefully, but the benefit is increased flexibility in how models can be
164 * created by permitting callers to create objects bottom-up if desired.  In
165 * situations where objects are not yet attached to parents (e.g.,
166 * {@link SBMLDocument}), knowledge of the intented SBML Level and Version help
167 * libSBML determine such things as whether it is valid to assign a
168 * particular value to an attribute.
169   */ public
170 ListOfUnits(SBMLNamespaces sbmlns) throws org.sbml.libsbml.SBMLConstructorException {
171    this(libsbmlJNI.new_ListOfUnits__SWIG_1(SBMLNamespaces.getCPtr(sbmlns), sbmlns), true);
172  }
173
174  
175/**
176   * Creates and returns a deep copy of this {@link ListOfUnits} object.
177   <p>
178   * @return the (deep) copy of this {@link ListOfUnits} object.
179   */ public
180 ListOfUnits cloneObject() {
181    long cPtr = libsbmlJNI.ListOfUnits_cloneObject(swigCPtr, this);
182    return (cPtr == 0) ? null : new ListOfUnits(cPtr, true);
183  }
184
185  
186/**
187   * Returns the libSBML type code for the objects contained in this {@link ListOf}
188   * (i.e., {@link Unit} objects, if the list is non-empty).
189   <p>
190   * <p>
191 * LibSBML attaches an identifying code to every kind of SBML object.  These
192 * are integer constants known as <em>SBML type codes</em>.  The names of all
193 * the codes begin with the characters <code>SBML_</code>.
194 * In the Java language interface for libSBML, the
195 * type codes are defined as static integer constants in the interface class
196 * {@link libsbmlConstants}.    Note that different Level&nbsp;3
197 * package plug-ins may use overlapping type codes; to identify the package
198 * to which a given object belongs, call the <code>getPackageName()</code>
199 * method on the object.
200   <p>
201   * @return the SBML type code for objects contained in this list:
202   * {@link libsbmlConstants#SBML_UNIT SBML_UNIT} (default).
203   <p>
204   * @see #getElementName()
205   * @see #getPackageName()
206   */ public
207 int getItemTypeCode() {
208    return libsbmlJNI.ListOfUnits_getItemTypeCode(swigCPtr, this);
209  }
210
211  
212/**
213   * Returns the XML element name of this object.
214   <p>
215   * For {@link ListOfUnits}, the XML element name is <code>'listOfUnits'.</code>
216   <p>
217   * @return the name of this element, i.e., <code>'listOfUnits'.</code>
218   */ public
219 String getElementName() {
220    return libsbmlJNI.ListOfUnits_getElementName(swigCPtr, this);
221  }
222
223  
224/**
225   * Get a {@link Unit} from the {@link ListOfUnits}.
226   <p>
227   * @param n the index number of the {@link Unit} to get.
228   <p>
229   * @return the nth {@link Unit} in this {@link ListOfUnits}.
230   <p>
231   * @see #size()
232   */ public
233 Unit get(long n) {
234    long cPtr = libsbmlJNI.ListOfUnits_get__SWIG_0(swigCPtr, this, n);
235    return (cPtr == 0) ? null : new Unit(cPtr, false);
236  }
237
238  
239/**
240   * Removes the nth item from this {@link ListOfUnits} items and returns a pointer to
241   * it.
242   <p>
243   * The caller owns the returned item and is responsible for deleting it.
244   <p>
245   * @param n the index of the item to remove
246   <p>
247   * @see #size()
248   */ public
249 Unit remove(long n) {
250    long cPtr = libsbmlJNI.ListOfUnits_remove(swigCPtr, this, n);
251    return (cPtr == 0) ? null : new Unit(cPtr, true);
252  }
253
254}