001/* ----------------------------------------------------------------------------
002 * This file was automatically generated by SWIG (http://www.swig.org).
003 * Version 3.0.10
004 *
005 * Do not make changes to this file unless you know what you are doing--modify
006 * the SWIG interface file instead.
007 * ----------------------------------------------------------------------------- */
008
009package org.sbml.libsbml;
010
011/** 
012 * <span class="pkg-marker pkg-color-qual"><a href="group__qual.html">qual</a></span>
013
014 A list of {@link Input} objects.
015 <p>
016 * The {@link ListOfInputs} is a container for the Inputs of a {@link Transition}.
017 <p>
018 * <p>
019 * The various ListOf___ classes in SBML
020 * are merely containers used for organizing the main components of an SBML
021 * model.  In libSBML's implementation, ListOf___
022 * classes are derived from the
023 * intermediate utility class {@link ListOf}, which
024 * is not defined by the SBML specifications but serves as a useful
025 * programmatic construct.  {@link ListOf} is itself is in turn derived from {@link SBase},
026 * which provides all of the various ListOf___
027 * classes with common features
028 * defined by the SBML specification, such as 'metaid' attributes and
029 * annotations.
030 <p>
031 * The relationship between the lists and the rest of an SBML model is
032 * illustrated by the following (for SBML Level&nbsp;2 Version&nbsp;4):
033 <p>
034 * <figure>
035  <object type="image/svg+xml" data="listof-illustration.svg" class="centered"></object>
036</figure>
037
038 <p>
039 * SBML Level&nbsp;3 Version&nbsp;1 has essentially the same structure as 
040 * Level&nbsp;2 Version&nbsp;4, depicted above, but SBML Level&nbsp;3 
041 * Version&nbsp;2 allows
042 * containers to contain zero or more of the relevant object, instead of 
043 * requiring at least one.  As such, libsbml will write out an 
044 * otherwise-empty ListOf___ element that has any optional attribute set 
045 * (such as 'id' or 'metaid'), that has an optional child (such 
046 * as a 'notes' or 'annotation'), or that has attributes or children set
047 * from any SBML Level&nbsp;3 package, whether or not the ListOf___ has 
048 * any other children.
049 <p>
050 * Readers may wonder about the motivations for using the ListOf___
051 * containers in SBML.  A simpler approach in XML might be to place the
052 * components all directly at the top level of the model definition.  The
053 * choice made in SBML is to group them within XML elements named after
054 * ListOf<em>Classname</em>, in part because it helps organize the
055 * components.  More importantly, the fact that the container classes are
056 * derived from {@link SBase} means that software tools can add information <em>about</em>
057 * the lists themselves into each list container's 'annotation'.
058 <p>
059 * @see ListOfFunctionDefinitions
060 * @see ListOfUnitDefinitions
061 * @see ListOfCompartmentTypes
062 * @see ListOfSpeciesTypes
063 * @see ListOfCompartments
064 * @see ListOfSpecies
065 * @see ListOfParameters
066 * @see ListOfInitialAssignments
067 * @see ListOfRules
068 * @see ListOfConstraints
069 * @see ListOfReactions
070 * @see ListOfEvents
071 <p>
072 * @see Input
073 */
074
075public class ListOfInputs extends ListOf {
076   private long swigCPtr;
077
078   protected ListOfInputs(long cPtr, boolean cMemoryOwn)
079   {
080     super(libsbmlJNI.ListOfInputs_SWIGUpcast(cPtr), cMemoryOwn);
081     swigCPtr = cPtr;
082   }
083
084   protected static long getCPtr(ListOfInputs obj)
085   {
086     return (obj == null) ? 0 : obj.swigCPtr;
087   }
088
089   protected static long getCPtrAndDisown (ListOfInputs obj)
090   {
091     long ptr = 0;
092
093     if (obj != null)
094     {
095       ptr             = obj.swigCPtr;
096       obj.swigCMemOwn = false;
097     }
098
099     return ptr;
100   }
101
102  protected void finalize() {
103    delete();
104  }
105
106  public synchronized void delete() {
107    if (swigCPtr != 0) {
108      if (swigCMemOwn) {
109        swigCMemOwn = false;
110        libsbmlJNI.delete_ListOfInputs(swigCPtr);
111      }
112      swigCPtr = 0;
113    }
114    super.delete();
115  }
116
117  
118/**
119   * Creates a new {@link ListOfInputs} with the given level, version, and package version.
120   <p>
121   * @param level a long integer, the SBML Level to assign to this {@link ListOfInputs}.
122   <p>
123   * @param version a long integer, the SBML Version to assign to this {@link ListOfInputs}.
124   <p>
125   * @param pkgVersion a long integer, the SBML Qual Version to assign to this {@link ListOfInputs}.
126   <p>
127   * <p>
128 * @note Attempting to add an object to an {@link SBMLDocument} having a different
129 * combination of SBML Level, Version and XML namespaces than the object
130 * itself will result in an error at the time a caller attempts to make the
131 * addition.  A parent object must have compatible Level, Version and XML
132 * namespaces.  (Strictly speaking, a parent may also have more XML
133 * namespaces than a child, but the reverse is not permitted.)  The
134 * restriction is necessary to ensure that an SBML model has a consistent
135 * overall structure.  This requires callers to manage their objects
136 * carefully, but the benefit is increased flexibility in how models can be
137 * created by permitting callers to create objects bottom-up if desired.  In
138 * situations where objects are not yet attached to parents (e.g.,
139 * {@link SBMLDocument}), knowledge of the intented SBML Level and Version help
140 * libSBML determine such things as whether it is valid to assign a
141 * particular value to an attribute.  For packages, this means that the 
142 * parent object to which this package element is being added must have
143 * been created with the package namespace, or that the package namespace
144 * was added to it, even if that parent is not a package object itself.
145   */ public
146 ListOfInputs(long level, long version, long pkgVersion) throws org.sbml.libsbml.SBMLConstructorException {
147    this(libsbmlJNI.new_ListOfInputs__SWIG_0(level, version, pkgVersion), true);
148  }
149
150  
151/**
152   * Creates a new {@link ListOfInputs} with the given level, version, and package version.
153   <p>
154   * @param level a long integer, the SBML Level to assign to this {@link ListOfInputs}.
155   <p>
156   * @param version a long integer, the SBML Version to assign to this {@link ListOfInputs}.
157   <p>
158   * @param pkgVersion a long integer, the SBML Qual Version to assign to this {@link ListOfInputs}.
159   <p>
160   * <p>
161 * @note Attempting to add an object to an {@link SBMLDocument} having a different
162 * combination of SBML Level, Version and XML namespaces than the object
163 * itself will result in an error at the time a caller attempts to make the
164 * addition.  A parent object must have compatible Level, Version and XML
165 * namespaces.  (Strictly speaking, a parent may also have more XML
166 * namespaces than a child, but the reverse is not permitted.)  The
167 * restriction is necessary to ensure that an SBML model has a consistent
168 * overall structure.  This requires callers to manage their objects
169 * carefully, but the benefit is increased flexibility in how models can be
170 * created by permitting callers to create objects bottom-up if desired.  In
171 * situations where objects are not yet attached to parents (e.g.,
172 * {@link SBMLDocument}), knowledge of the intented SBML Level and Version help
173 * libSBML determine such things as whether it is valid to assign a
174 * particular value to an attribute.  For packages, this means that the 
175 * parent object to which this package element is being added must have
176 * been created with the package namespace, or that the package namespace
177 * was added to it, even if that parent is not a package object itself.
178   */ public
179 ListOfInputs(long level, long version) throws org.sbml.libsbml.SBMLConstructorException {
180    this(libsbmlJNI.new_ListOfInputs__SWIG_1(level, version), true);
181  }
182
183  
184/**
185   * Creates a new {@link ListOfInputs} with the given level, version, and package version.
186   <p>
187   * @param level a long integer, the SBML Level to assign to this {@link ListOfInputs}.
188   <p>
189   * @param version a long integer, the SBML Version to assign to this {@link ListOfInputs}.
190   <p>
191   * @param pkgVersion a long integer, the SBML Qual Version to assign to this {@link ListOfInputs}.
192   <p>
193   * <p>
194 * @note Attempting to add an object to an {@link SBMLDocument} having a different
195 * combination of SBML Level, Version and XML namespaces than the object
196 * itself will result in an error at the time a caller attempts to make the
197 * addition.  A parent object must have compatible Level, Version and XML
198 * namespaces.  (Strictly speaking, a parent may also have more XML
199 * namespaces than a child, but the reverse is not permitted.)  The
200 * restriction is necessary to ensure that an SBML model has a consistent
201 * overall structure.  This requires callers to manage their objects
202 * carefully, but the benefit is increased flexibility in how models can be
203 * created by permitting callers to create objects bottom-up if desired.  In
204 * situations where objects are not yet attached to parents (e.g.,
205 * {@link SBMLDocument}), knowledge of the intented SBML Level and Version help
206 * libSBML determine such things as whether it is valid to assign a
207 * particular value to an attribute.  For packages, this means that the 
208 * parent object to which this package element is being added must have
209 * been created with the package namespace, or that the package namespace
210 * was added to it, even if that parent is not a package object itself.
211   */ public
212 ListOfInputs(long level) throws org.sbml.libsbml.SBMLConstructorException {
213    this(libsbmlJNI.new_ListOfInputs__SWIG_2(level), true);
214  }
215
216  
217/**
218   * Creates a new {@link ListOfInputs} with the given level, version, and package version.
219   <p>
220   * @param level a long integer, the SBML Level to assign to this {@link ListOfInputs}.
221   <p>
222   * @param version a long integer, the SBML Version to assign to this {@link ListOfInputs}.
223   <p>
224   * @param pkgVersion a long integer, the SBML Qual Version to assign to this {@link ListOfInputs}.
225   <p>
226   * <p>
227 * @note Attempting to add an object to an {@link SBMLDocument} having a different
228 * combination of SBML Level, Version and XML namespaces than the object
229 * itself will result in an error at the time a caller attempts to make the
230 * addition.  A parent object must have compatible Level, Version and XML
231 * namespaces.  (Strictly speaking, a parent may also have more XML
232 * namespaces than a child, but the reverse is not permitted.)  The
233 * restriction is necessary to ensure that an SBML model has a consistent
234 * overall structure.  This requires callers to manage their objects
235 * carefully, but the benefit is increased flexibility in how models can be
236 * created by permitting callers to create objects bottom-up if desired.  In
237 * situations where objects are not yet attached to parents (e.g.,
238 * {@link SBMLDocument}), knowledge of the intented SBML Level and Version help
239 * libSBML determine such things as whether it is valid to assign a
240 * particular value to an attribute.  For packages, this means that the 
241 * parent object to which this package element is being added must have
242 * been created with the package namespace, or that the package namespace
243 * was added to it, even if that parent is not a package object itself.
244   */ public
245 ListOfInputs() throws org.sbml.libsbml.SBMLConstructorException {
246    this(libsbmlJNI.new_ListOfInputs__SWIG_3(), true);
247  }
248
249  
250/**
251   * Creates a new {@link ListOfInputs} with the given {@link QualPkgNamespaces} object.
252   <p>
253   * <p>
254 * The package namespaces object used in this constructor is derived from a
255 * {@link SBMLNamespaces} object, which encapsulates SBML Level/Version/namespaces
256 * information.  It is used to communicate the SBML Level, Version, and 
257 * package version and name information used in addition to SBML Level&nbsp;3 Core.  A
258 * common approach to using libSBML's {@link SBMLNamespaces} facilities is to create an
259 * package namespace object somewhere in a program once, then hand that object
260 * as needed to object constructors of that package that accept it as and
261 * argument, such as this one.
262   <p>
263   * @param qualns the {@link QualPkgNamespaces} object.
264   <p>
265   * <p>
266 * @note Attempting to add an object to an {@link SBMLDocument} having a different
267 * combination of SBML Level, Version and XML namespaces than the object
268 * itself will result in an error at the time a caller attempts to make the
269 * addition.  A parent object must have compatible Level, Version and XML
270 * namespaces.  (Strictly speaking, a parent may also have more XML
271 * namespaces than a child, but the reverse is not permitted.)  The
272 * restriction is necessary to ensure that an SBML model has a consistent
273 * overall structure.  This requires callers to manage their objects
274 * carefully, but the benefit is increased flexibility in how models can be
275 * created by permitting callers to create objects bottom-up if desired.  In
276 * situations where objects are not yet attached to parents (e.g.,
277 * {@link SBMLDocument}), knowledge of the intented SBML Level and Version help
278 * libSBML determine such things as whether it is valid to assign a
279 * particular value to an attribute.  For packages, this means that the 
280 * parent object to which this package element is being added must have
281 * been created with the package namespace, or that the package namespace
282 * was added to it, even if that parent is not a package object itself.
283   */ public
284 ListOfInputs(QualPkgNamespaces qualns) throws org.sbml.libsbml.SBMLConstructorException {
285    this(libsbmlJNI.new_ListOfInputs__SWIG_4(QualPkgNamespaces.getCPtr(qualns), qualns), true);
286  }
287
288  
289/**
290   * Creates and returns a deep copy of this {@link ListOfInputs} object.
291   <p>
292   * @return a (deep) copy of this {@link ListOfInputs} object.
293   */ public
294 ListOfInputs cloneObject() {
295    long cPtr = libsbmlJNI.ListOfInputs_cloneObject(swigCPtr, this);
296    return (cPtr == 0) ? null : new ListOfInputs(cPtr, true);
297  }
298
299  
300/**
301   * Get a {@link Input} from the {@link ListOfInputs}.
302   <p>
303   * @param n the index number of the {@link Input} to get.
304   <p>
305   * @return the nth {@link Input} in this {@link ListOfInputs}.
306   <p>
307   * @see #size()
308   */ public
309 Input get(long n) {
310    long cPtr = libsbmlJNI.ListOfInputs_get__SWIG_0(swigCPtr, this, n);
311    return (cPtr == 0) ? null : new Input(cPtr, false);
312  }
313
314  
315/**
316   * Get a {@link Input} from the {@link ListOfInputs}
317   * based on its identifier.
318   <p>
319   * @param sid a string representing the identifier
320   * of the {@link Input} to get.
321   <p>
322   * @return {@link Input} in this {@link ListOfInputs}
323   * with the given id or null if no such
324   * {@link Input} exists.
325   <p>
326   * @see #get(long n)   *
327   * @see #size()
328   */ public
329 Input get(String sid) {
330    long cPtr = libsbmlJNI.ListOfInputs_get__SWIG_2(swigCPtr, this, sid);
331    return (cPtr == 0) ? null : new Input(cPtr, false);
332  }
333
334  
335/**
336   * Get a {@link Input} from the {@link ListOfInputs}
337   * based on the qualitativeSpecies to which it refers.
338   <p>
339   * @param sid a string representing the qualitativeSpecies attribute
340   * of the {@link Input} to get.
341   <p>
342   * @return the first {@link Input} in this {@link ListOfInputs}
343   * with the given qualitativeSpecies or null if no such
344   * {@link Input} exists.
345   <p>
346   * @see #get(long n)   *
347   * @see #size()
348   */ public
349 Input getBySpecies(String sid) {
350    long cPtr = libsbmlJNI.ListOfInputs_getBySpecies__SWIG_0(swigCPtr, this, sid);
351    return (cPtr == 0) ? null : new Input(cPtr, false);
352  }
353
354  
355/**
356   * Removes the nth {@link Input} from this {@link ListOfInputs}
357   * and returns a pointer to it.
358   <p>
359   * The caller owns the returned item and is responsible for deleting it.
360   <p>
361   * @param n the index of the {@link Input} to remove.
362   <p>
363   * @see #size()
364   */ public
365 Input remove(long n) {
366    long cPtr = libsbmlJNI.ListOfInputs_remove__SWIG_0(swigCPtr, this, n);
367    return (cPtr == 0) ? null : new Input(cPtr, true);
368  }
369
370  
371/**
372   * Removes the {@link Input} from this {@link ListOfInputs} with the given identifier
373   * and returns a pointer to it.
374   <p>
375   * The caller owns the returned item and is responsible for deleting it.
376   * If none of the items in this list have the identifier <code>sid</code>, then
377   * <code>null</code> is returned.
378   <p>
379   * @param sid the identifier of the {@link Input} to remove.
380   <p>
381   * @return the {@link Input} removed. As mentioned above, the caller owns the
382   * returned item.
383   */ public
384 Input remove(String sid) {
385    long cPtr = libsbmlJNI.ListOfInputs_remove__SWIG_1(swigCPtr, this, sid);
386    return (cPtr == 0) ? null : new Input(cPtr, true);
387  }
388
389  
390/**
391   * Returns the XML name of this object.
392   <p>
393   * @return the name of this element.
394   */ public
395 String getElementName() {
396    return libsbmlJNI.ListOfInputs_getElementName(swigCPtr, this);
397  }
398
399  
400/**
401   * Returns the libSBML type code for the SBML objects
402   * contained in this {@link ListOf} object.
403   <p>
404   * <p>
405 * LibSBML attaches an identifying code to every kind of SBML object.  These
406 * are integer constants known as <em>SBML type codes</em>.  The names of all
407 * the codes begin with the characters <code>SBML_</code>.
408 * In the Java language interface for libSBML, the
409 * type codes are defined as static integer constants in the interface class
410 * {@link libsbmlConstants}.    Note that different Level&nbsp;3
411 * package plug-ins may use overlapping type codes; to identify the package
412 * to which a given object belongs, call the <code>getPackageName()</code>
413 * method on the object.
414   <p>
415   * @return the SBML type code for objects contained in this list:
416   * {@link libsbmlConstants#SBML_QUAL_INPUT SBML_QUAL_INPUT} (default).
417   <p>
418   * @see #getElementName()
419   * @see #getPackageName()
420   */ public
421 int getItemTypeCode() {
422    return libsbmlJNI.ListOfInputs_getItemTypeCode(swigCPtr, this);
423  }
424
425}