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 *  Parent class for libSBML's 'ListOfXYZ' classes.
013 <p>
014 * <p style='color: #777; font-style: italic'>
015This class of objects is defined by libSBML only and has no direct
016equivalent in terms of SBML components.  This class is not prescribed by
017the SBML specifications, although it is used to implement features
018defined in SBML.
019</p>
020
021 <p>
022 * The {@link ListOf} class in libSBML is a utility class that serves as the parent
023 * class for implementing the ListOf__ classes.  It provides methods for
024 * working generically with the various SBML lists of objects in a program.
025 * LibSBML uses this separate list class rather than ordinary
026 * Java lists,
027 * so that it can provide the methods and features associated with {@link SBase}.
028 <p>
029 * <p>
030 * The various ListOf___ classes in SBML
031 * are merely containers used for organizing the main components of an SBML
032 * model.  In libSBML's implementation, ListOf___
033 * classes are derived from the
034 * intermediate utility class {@link ListOf}, which
035 * is not defined by the SBML specifications but serves as a useful
036 * programmatic construct.  {@link ListOf} is itself is in turn derived from {@link SBase},
037 * which provides all of the various ListOf___
038 * classes with common features
039 * defined by the SBML specification, such as 'metaid' attributes and
040 * annotations.
041 <p>
042 * The relationship between the lists and the rest of an SBML model is
043 * illustrated by the following (for SBML Level&nbsp;2 Version&nbsp;4):
044 <p>
045 * <figure>
046  <object type="image/svg+xml" data="listof-illustration.svg" class="centered"></object>
047</figure>
048
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 */
072
073public class ListOf extends SBase {
074   private long swigCPtr;
075
076   protected ListOf(long cPtr, boolean cMemoryOwn)
077   {
078     super(libsbmlJNI.ListOf_SWIGUpcast(cPtr), cMemoryOwn);
079     swigCPtr = cPtr;
080   }
081
082   protected static long getCPtr(ListOf obj)
083   {
084     return (obj == null) ? 0 : obj.swigCPtr;
085   }
086
087   protected static long getCPtrAndDisown (ListOf obj)
088   {
089     long ptr = 0;
090
091     if (obj != null)
092     {
093       ptr             = obj.swigCPtr;
094       obj.swigCMemOwn = false;
095     }
096
097     return ptr;
098   }
099
100  protected void finalize() {
101    delete();
102  }
103
104  public synchronized void delete() {
105    if (swigCPtr != 0) {
106      if (swigCMemOwn) {
107        swigCMemOwn = false;
108        libsbmlJNI.delete_ListOf(swigCPtr);
109      }
110      swigCPtr = 0;
111    }
112    super.delete();
113  }
114
115  
116/**
117   * Creates a new {@link ListOf} object.
118   <p>
119   * @param level the SBML Level; if not assigned, defaults to the
120   * value of {@link SBMLDocument#getDefaultLevel()}.
121   <p>
122   * @param version the Version within the SBML Level; if not assigned,
123   * defaults to the value of {@link SBMLDocument#getDefaultVersion()}.
124   <p>
125   * 
126</dl><dl class="docnote"><dt><b>Documentation note:</b></dt><dd>
127The native C++ implementation of this method defines a default argument
128value. In the documentation generated for different libSBML language
129bindings, you may or may not see corresponding arguments in the method
130declarations. For example, in Java and C#, a default argument is handled by
131declaring two separate methods, with one of them having the argument and
132the other one lacking the argument. However, the libSBML documentation will
133be <em>identical</em> for both methods. Consequently, if you are reading
134this and do not see an argument even though one is described, please look
135for descriptions of other variants of this method near where this one
136appears in the documentation.
137</dd></dl>
138 
139   */ public
140 ListOf(long level, long version) throws org.sbml.libsbml.SBMLConstructorException {
141    this(libsbmlJNI.new_ListOf__SWIG_0(level, version), true);
142  }
143
144  
145/**
146   * Creates a new {@link ListOf} object.
147   <p>
148   * @param level the SBML Level; if not assigned, defaults to the
149   * value of {@link SBMLDocument#getDefaultLevel()}.
150   <p>
151   * @param version the Version within the SBML Level; if not assigned,
152   * defaults to the value of {@link SBMLDocument#getDefaultVersion()}.
153   <p>
154   * 
155</dl><dl class="docnote"><dt><b>Documentation note:</b></dt><dd>
156The native C++ implementation of this method defines a default argument
157value. In the documentation generated for different libSBML language
158bindings, you may or may not see corresponding arguments in the method
159declarations. For example, in Java and C#, a default argument is handled by
160declaring two separate methods, with one of them having the argument and
161the other one lacking the argument. However, the libSBML documentation will
162be <em>identical</em> for both methods. Consequently, if you are reading
163this and do not see an argument even though one is described, please look
164for descriptions of other variants of this method near where this one
165appears in the documentation.
166</dd></dl>
167 
168   */ public
169 ListOf(long level) throws org.sbml.libsbml.SBMLConstructorException {
170    this(libsbmlJNI.new_ListOf__SWIG_1(level), true);
171  }
172
173  
174/**
175   * Creates a new {@link ListOf} object.
176   <p>
177   * @param level the SBML Level; if not assigned, defaults to the
178   * value of {@link SBMLDocument#getDefaultLevel()}.
179   <p>
180   * @param version the Version within the SBML Level; if not assigned,
181   * defaults to the value of {@link SBMLDocument#getDefaultVersion()}.
182   <p>
183   * 
184</dl><dl class="docnote"><dt><b>Documentation note:</b></dt><dd>
185The native C++ implementation of this method defines a default argument
186value. In the documentation generated for different libSBML language
187bindings, you may or may not see corresponding arguments in the method
188declarations. For example, in Java and C#, a default argument is handled by
189declaring two separate methods, with one of them having the argument and
190the other one lacking the argument. However, the libSBML documentation will
191be <em>identical</em> for both methods. Consequently, if you are reading
192this and do not see an argument even though one is described, please look
193for descriptions of other variants of this method near where this one
194appears in the documentation.
195</dd></dl>
196 
197   */ public
198 ListOf() throws org.sbml.libsbml.SBMLConstructorException {
199    this(libsbmlJNI.new_ListOf__SWIG_2(), true);
200  }
201
202  
203/**
204   * Creates a new {@link ListOf} with {@link SBMLNamespaces} object.
205   <p>
206   * @param sbmlns the set of SBML namespaces that this {@link ListOf} should
207   * contain.
208   */ public
209 ListOf(SBMLNamespaces sbmlns) throws org.sbml.libsbml.SBMLConstructorException {
210    this(libsbmlJNI.new_ListOf__SWIG_3(SBMLNamespaces.getCPtr(sbmlns), sbmlns), true);
211  }
212
213  
214/**
215   * Copy constructor; creates a copy of this {@link ListOf}.
216   <p>
217   * @param orig the {@link ListOf} instance to copy.
218   */ public
219 ListOf(ListOf orig) throws org.sbml.libsbml.SBMLConstructorException {
220    this(libsbmlJNI.new_ListOf__SWIG_4(ListOf.getCPtr(orig), orig), true);
221  }
222
223  
224/**
225   * Creates and returns a deep copy of this {@link ListOf}.
226   <p>
227   * @return a (deep) copy of this {@link ListOf}.
228   */ public
229 ListOf cloneObject() {
230    long cPtr = libsbmlJNI.ListOf_cloneObject(swigCPtr, this);
231    return (cPtr == 0) ? null : new ListOf(cPtr, true);
232  }
233
234  
235/**
236   * Adds an item to the end of this {@link ListOf}'s list of items.
237   <p>
238   * This method makes a clone of the <code>item</code> handed to it.  This means that
239   * when the {@link ListOf} object is destroyed, the original items will not be
240   * destroyed.  For a method with an alternative ownership behavior, see the
241   * {@link ListOf#appendAndOwn(SBase item)} method.
242   <p>
243   * @param item the item to be added to the list.
244   <p>
245   * @see #appendAndOwn(SBase item)
246   * @see #appendFrom(ListOf list)
247   */ public
248 int append(SBase item) {
249    return libsbmlJNI.ListOf_append(swigCPtr, this, SBase.getCPtr(item), item);
250  }
251
252  
253/**
254   * Adds an item to the end of this {@link ListOf}'s list of items.
255   <p>
256   * This method does not clone the <code>item</code> handed to it; instead, it assumes
257   * ownership of it.  This means that when the {@link ListOf} is destroyed, the item
258   * will be destroyed along with it.  For a method with an alternative
259   * ownership behavior, see the {@link ListOf#append(SBase item)} method.
260   <p>
261   * @param item the item to be added to the list.
262   <p>
263   * @see #append(SBase item)
264   * @see #appendFrom(ListOf list)
265   */ public
266 int appendAndOwn(SBase item) {
267    return libsbmlJNI.ListOf_appendAndOwn(swigCPtr, this, SBase.getCPtrAndDisown(item), item);
268  }
269
270  
271/**
272   * Adds a clone of a list of items to this {@link ListOf}'s list.
273   <p>
274   * Note that because this clones the objects handed to it, the original
275   * items will not be destroyed when this {@link ListOf} object is destroyed.
276   <p>
277   * @param list a list of items to be added.
278   <p>
279   * @see #append(SBase item)
280   * @see #appendAndOwn(SBase item)
281   */ public
282 int appendFrom(ListOf list) {
283    return libsbmlJNI.ListOf_appendFrom(swigCPtr, this, ListOf.getCPtr(list), list);
284  }
285
286  
287/**
288   * Inserts an item at a given position in this {@link ListOf}'s list of items.
289   <p>
290   * This variant of the method makes a clone of the <code>item</code> handed to it.
291   * This means that when the {@link ListOf} is destroyed, the original items will
292   * not be destroyed.  For an alternative method with different ownership
293   * behavior, see insertAndOwn(int location, {@link SBase} item).
294   <p>
295   * @param location the location in the list where to insert the item.
296   * @param item the item to be inserted to the list.
297   <p>
298   * @see #insertAndOwn(int location, SBase item)
299   */ public
300 int insert(int location, SBase item) {
301    return libsbmlJNI.ListOf_insert(swigCPtr, this, location, SBase.getCPtr(item), item);
302  }
303
304  
305/**
306   * Inserts an item at a given position in this {@link ListOf}'s list of items.
307   <p>
308   * This variant of the method makes a clone of the <code>item</code> handet to it.
309   * This means that when the {@link ListOf} is destroyed, the original items will
310   * not be destroyed.
311   <p>
312   * @param location the location where to insert the item
313   * @param item the item to be inserted to the list
314   <p>
315   * @see #insert(int location, SBase item)
316   */ public
317 int insertAndOwn(int location, SBase item) {
318    return libsbmlJNI.ListOf_insertAndOwn(swigCPtr, this, location, SBase.getCPtrAndDisown(item), item);
319  }
320
321  
322/**
323   * Get an item from the list.
324   <p>
325   * @param n the index number of the item to get.
326   <p>
327   * @return the nth item in this {@link ListOf} items.
328   <p>
329   * @see #size()
330   */ public
331 SBase get(long n) {
332  return libsbml.DowncastSBase(libsbmlJNI.ListOf_get__SWIG_0(swigCPtr, this, n), false);
333}
334
335  
336/**
337   * Returns the first child element found that has the given identifier.
338   <p>
339   * This method searches this {@link ListOf}'s list of items for SBML objects based
340   * on their 'id' attribute value in the model-wide SId namespace.
341   <p>
342   * @param id string representing the id of objects to find.
343   <p>
344   * @return the first element found with the given <code>id</code>, or <code>null</code> if no
345   * such object is found.
346   */ public
347 SBase getElementBySId(String id) {
348  return libsbml.DowncastSBase(libsbmlJNI.ListOf_getElementBySId(swigCPtr, this, id), false);
349}
350
351  
352/**
353   * Returns the first child element found with the given <code>metaid</code>.
354   <p>
355   * @param metaid string representing the metaid of objects to find
356   <p>
357   * @return the first element found with the given <code>metaid</code>, or <code>null</code> if
358   * no such object is found.
359   */ public
360 SBase getElementByMetaId(String metaid) {
361  return libsbml.DowncastSBase(libsbmlJNI.ListOf_getElementByMetaId(swigCPtr, this, metaid), false);
362}
363
364  
365/**
366   * Removes all items in this {@link ListOf} object.
367   <p>
368   * If parameter <code>doDelete</code> is <code>true</code> (default), all items in this {@link ListOf}
369   * object are deleted and cleared, and thus the caller doesn't have to
370   * delete those items.  Otherwise, all items are cleared only from this
371   * {@link ListOf} object; the caller is still responsible for deleting all items.
372   * (In the latter case, callers are advised to store pointers to all items
373   * elsewhere before calling this function.)
374   <p>
375   * @param doDelete if <code>true</code> (default), all items are deleted and cleared.
376   * Otherwise, all items are just cleared and not deleted.
377   <p>
378   * 
379</dl><dl class="docnote"><dt><b>Documentation note:</b></dt><dd>
380The native C++ implementation of this method defines a default argument
381value. In the documentation generated for different libSBML language
382bindings, you may or may not see corresponding arguments in the method
383declarations. For example, in Java and C#, a default argument is handled by
384declaring two separate methods, with one of them having the argument and
385the other one lacking the argument. However, the libSBML documentation will
386be <em>identical</em> for both methods. Consequently, if you are reading
387this and do not see an argument even though one is described, please look
388for descriptions of other variants of this method near where this one
389appears in the documentation.
390</dd></dl>
391 
392   */ public
393 void clear(boolean doDelete) {
394    libsbmlJNI.ListOf_clear__SWIG_0(swigCPtr, this, doDelete);
395  }
396
397  
398/**
399   * Removes all items in this {@link ListOf} object.
400   <p>
401   * If parameter <code>doDelete</code> is <code>true</code> (default), all items in this {@link ListOf}
402   * object are deleted and cleared, and thus the caller doesn't have to
403   * delete those items.  Otherwise, all items are cleared only from this
404   * {@link ListOf} object; the caller is still responsible for deleting all items.
405   * (In the latter case, callers are advised to store pointers to all items
406   * elsewhere before calling this function.)
407   <p>
408   * @param doDelete if <code>true</code> (default), all items are deleted and cleared.
409   * Otherwise, all items are just cleared and not deleted.
410   <p>
411   * 
412</dl><dl class="docnote"><dt><b>Documentation note:</b></dt><dd>
413The native C++ implementation of this method defines a default argument
414value. In the documentation generated for different libSBML language
415bindings, you may or may not see corresponding arguments in the method
416declarations. For example, in Java and C#, a default argument is handled by
417declaring two separate methods, with one of them having the argument and
418the other one lacking the argument. However, the libSBML documentation will
419be <em>identical</em> for both methods. Consequently, if you are reading
420this and do not see an argument even though one is described, please look
421for descriptions of other variants of this method near where this one
422appears in the documentation.
423</dd></dl>
424 
425   */ public
426 void clear() {
427    libsbmlJNI.ListOf_clear__SWIG_1(swigCPtr, this);
428  }
429
430  
431/**
432   * Because {@link ListOf} objects typically live as object children of their parent
433   * object and not as pointer children, this function clears itself, but
434   * does not attempt to do anything else.
435   <p>
436   * If a particular {@link ListOf} subclass does indeed exist as a pointer only,
437   * this function will need to be overridden.
438   <p>
439   * @return integer value indicating success/failure of the
440   * function.   The possible values
441   * returned by this function are:
442   * <ul>
443   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS }
444   * </ul>
445   */ public
446 int removeFromParentAndDelete() {
447    return libsbmlJNI.ListOf_removeFromParentAndDelete(swigCPtr, this);
448  }
449
450  
451/**
452   * Removes the <em>n</em>th item from this {@link ListOf} items and returns it.
453   <p>
454   * The caller owns the returned item and is responsible for deleting it.
455   <p>
456   * @param n the index of the item to remove
457   <p>
458   * @see #size()
459   */ public
460 SBase remove(long n) {
461  return libsbml.DowncastSBase(libsbmlJNI.ListOf_remove(swigCPtr, this, n), true);
462}
463
464  
465/**
466   * Returns number of items in this {@link ListOf} list.
467   <p>
468   * @return the number of items in this {@link ListOf} items.
469   */ public
470 long size() {
471    return libsbmlJNI.ListOf_size(swigCPtr, this);
472  }
473
474  
475/**
476   * Sets this SBML object to child SBML objects (if any).
477   * (Creates a child-parent relationship by the parent)
478   <p>
479   * Subclasses must override this function if they define
480   * one ore more child elements.
481   * Basically, this function needs to be called in
482   * constructor, copy constructor and assignment operator.
483   <p>
484   <p>
485   * @internal
486   */ public
487 void connectToChild() {
488    libsbmlJNI.ListOf_connectToChild(swigCPtr, this);
489  }
490
491  
492/**
493   * Returns the libSBML type code for this object, namely,
494   * {@link  libsbmlConstants#SBML_LIST_OF SBML_LIST_OF}.
495   <p>
496   * <p>
497 * LibSBML attaches an identifying code to every kind of SBML object.  These
498 * are integer constants known as <em>SBML type codes</em>.  The names of all
499 * the codes begin with the characters &ldquo;<code>SBML_</code>&rdquo;. 
500 * In the Java language interface for libSBML, the
501 * type codes are defined as static integer constants in the interface class
502 * {@link libsbmlConstants}.    Note that different Level&nbsp;3 
503 * package plug-ins may use overlapping type codes; to identify the package
504 * to which a given object belongs, call the <code>getPackageName()</code>
505 * method on the object.
506   <p>
507   * @return the SBML type code for this object:
508   * {@link  libsbmlConstants#SBML_LIST_OF SBML_LIST_OF} (default).
509   <p>
510   * @note The various {@link ListOf} classes mostly differ from each other in what they
511   * contain.  Hence, one must call getItemTypeCode() to fully determine the
512   * class of this SBML object.
513   <p>
514   * <p>
515 * @warning <span class='warning'>The specific integer values of the possible
516 * type codes may be reused by different Level&nbsp;3 package plug-ins.
517 * Thus, to identifiy the correct code, <strong>it is necessary to invoke
518 * both getTypeCode() and getPackageName()</strong>.</span>
519   <p>
520   * @see #getItemTypeCode()
521   * @see #getElementName()
522   * @see #getPackageName()
523   */ public
524 int getTypeCode() {
525    return libsbmlJNI.ListOf_getTypeCode(swigCPtr, this);
526  }
527
528  
529/**
530   * Get the type code of the objects contained in this {@link ListOf}.
531   <p>
532   * <p>
533 * LibSBML attaches an identifying code to every kind of SBML object.  These
534 * are integer constants known as <em>SBML type codes</em>.  The names of all
535 * the codes begin with the characters &ldquo;<code>SBML_</code>&rdquo;. 
536 * In the Java language interface for libSBML, the
537 * type codes are defined as static integer constants in the interface class
538 * {@link libsbmlConstants}.    Note that different Level&nbsp;3 
539 * package plug-ins may use overlapping type codes; to identify the package
540 * to which a given object belongs, call the <code>getPackageName()</code>
541 * method on the object.
542   <p>
543   * Classes that inherit from the {@link ListOf} class should 
544   * override this function to return the SBML type code for 
545   * the objects contained in this {@link ListOf}.  If they do not, 
546   * {@link  libsbmlConstants#SBML_UNKNOWN SBML_UNKNOWN} is returned.
547   <p>
548   * @return The {@link ListOf} class itself contains no SBML objects, and 
549   * therefore returns {@link  libsbmlConstants#SBML_UNKNOWN SBML_UNKNOWN}.
550   <p>
551   * @see #getElementName()
552   * @see #getPackageName()
553   */ public
554 int getItemTypeCode() {
555    return libsbmlJNI.ListOf_getItemTypeCode(swigCPtr, this);
556  }
557
558  
559/**
560   * Returns the XML element name of this object, which for {@link ListOf}, is
561   * always <code>'listOf'.</code>
562   <p>
563   * @return the XML name of this element.
564   */ public
565 String getElementName() {
566    return libsbmlJNI.ListOf_getElementName(swigCPtr, this);
567  }
568
569  
570/**
571   * Enables/Disables the given package with this element and child
572   * elements (if any).
573   * (This is an internal implementation for enablePackage function)
574   <p>
575   * @note Subclasses of the SBML Core package in which one or more child
576   * elements are defined must override this function.
577   * @internal
578   */ public
579 void enablePackageInternal(String pkgURI, String pkgPrefix, boolean flag) {
580    libsbmlJNI.ListOf_enablePackageInternal(swigCPtr, this, pkgURI, pkgPrefix, flag);
581  }
582
583}