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-fbc"><a href="group__fbc.html">fbc</a></span>
013 A list of {@link GeneProduct} objects.
014 <p>
015 * The {@link ListOfGeneProducts} is a container for the SBML extended {@link Model}
016 * that lists all the possible {@link GeneProduct} elements in the model.  These
017 * {@link GeneProduct} elements are referenced in the {@link GeneProductAssociation} child
018 * of an extended {@link Reaction}.
019 <p>
020 * <p>
021 * The various ListOf___ classes in SBML
022 * are merely containers used for organizing the main components of an SBML
023 * model.  In libSBML's implementation, ListOf___
024 * classes are derived from the
025 * intermediate utility class {@link ListOf}, which
026 * is not defined by the SBML specifications but serves as a useful
027 * programmatic construct.  {@link ListOf} is itself is in turn derived from {@link SBase},
028 * which provides all of the various ListOf___
029 * classes with common features
030 * defined by the SBML specification, such as 'metaid' attributes and
031 * annotations.
032 <p>
033 * The relationship between the lists and the rest of an SBML model is
034 * illustrated by the following (for SBML Level&nbsp;2 Version&nbsp;4):
035 <p>
036 * <figure>
037  <object type="image/svg+xml" data="listof-illustration.svg" class="centered"></object>
038</figure>
039
040 <p>
041 * SBML Level&nbsp;3 Version&nbsp;1 has essentially the same structure as 
042 * Level&nbsp;2 Version&nbsp;4, depicted above, but SBML Level&nbsp;3 
043 * Version&nbsp;2 allows
044 * containers to contain zero or more of the relevant object, instead of 
045 * requiring at least one.  As such, libsbml will write out an 
046 * otherwise-empty ListOf___ element that has any optional attribute set 
047 * (such as 'id' or 'metaid'), that has an optional child (such 
048 * as a 'notes' or 'annotation'), or that has attributes or children set
049 * from any SBML Level&nbsp;3 package, whether or not the ListOf___ has 
050 * any other children.
051 <p>
052 * Readers may wonder about the motivations for using the ListOf___
053 * containers in SBML.  A simpler approach in XML might be to place the
054 * components all directly at the top level of the model definition.  The
055 * choice made in SBML is to group them within XML elements named after
056 * ListOf<em>Classname</em>, in part because it helps organize the
057 * components.  More importantly, the fact that the container classes are
058 * derived from {@link SBase} means that software tools can add information <em>about</em>
059 * the lists themselves into each list container's 'annotation'.
060 <p>
061 * @see ListOfFunctionDefinitions
062 * @see ListOfUnitDefinitions
063 * @see ListOfCompartmentTypes
064 * @see ListOfSpeciesTypes
065 * @see ListOfCompartments
066 * @see ListOfSpecies
067 * @see ListOfParameters
068 * @see ListOfInitialAssignments
069 * @see ListOfRules
070 * @see ListOfConstraints
071 * @see ListOfReactions
072 * @see ListOfEvents
073 <p>
074 * 
075 * <p>
076 * @note This class of objects was introduced in Version&nbsp;2 of the
077 * SBML Level&nbsp;3 Flux Balance Constraints (&ldquo;fbc&rdquo;)
078 * specification.  In Version&nbsp;1 of &ldquo;fbc&rdquo;, the information
079 * encoded by this class can be stored instead using the {@link Association} and
080 * {@link GeneAssociation} annotation classes.  Please see the Version&nbsp;1 and
081 * Version&nbsp;2 &ldquo;fbc&rdquo; specifications for more details.
082 <p>
083   * @see GeneProduct
084 * @see FbcModelPlugin
085 */
086
087public class ListOfGeneProducts extends ListOf {
088   private long swigCPtr;
089
090   protected ListOfGeneProducts(long cPtr, boolean cMemoryOwn)
091   {
092     super(libsbmlJNI.ListOfGeneProducts_SWIGUpcast(cPtr), cMemoryOwn);
093     swigCPtr = cPtr;
094   }
095
096   protected static long getCPtr(ListOfGeneProducts obj)
097   {
098     return (obj == null) ? 0 : obj.swigCPtr;
099   }
100
101   protected static long getCPtrAndDisown (ListOfGeneProducts obj)
102   {
103     long ptr = 0;
104
105     if (obj != null)
106     {
107       ptr             = obj.swigCPtr;
108       obj.swigCMemOwn = false;
109     }
110
111     return ptr;
112   }
113
114  protected void finalize() {
115    delete();
116  }
117
118  public synchronized void delete() {
119    if (swigCPtr != 0) {
120      if (swigCMemOwn) {
121        swigCMemOwn = false;
122        libsbmlJNI.delete_ListOfGeneProducts(swigCPtr);
123      }
124      swigCPtr = 0;
125    }
126    super.delete();
127  }
128
129  
130/**
131   * Creates a new {@link GeneProduct} with the given SBML Level, Version, and
132   * &ldquo;fbc&rdquo;package version.
133   <p>
134   * @param level a long integer, the SBML Level to assign to this
135   * {@link ListOfGeneProducts}.
136   <p>
137   * @param version a long integer, the SBML Version to assign to this
138   * {@link ListOfGeneProducts}.
139   <p>
140   * @param pkgVersion a long integer, the SBML Fbc Version to assign to
141   * this {@link ListOfGeneProducts}.
142   <p>
143   * <p>
144 * @note Attempting to add an object to an {@link SBMLDocument} having a different
145 * combination of SBML Level, Version and XML namespaces than the object
146 * itself will result in an error at the time a caller attempts to make the
147 * addition.  A parent object must have compatible Level, Version and XML
148 * namespaces.  (Strictly speaking, a parent may also have more XML
149 * namespaces than a child, but the reverse is not permitted.)  The
150 * restriction is necessary to ensure that an SBML model has a consistent
151 * overall structure.  This requires callers to manage their objects
152 * carefully, but the benefit is increased flexibility in how models can be
153 * created by permitting callers to create objects bottom-up if desired.  In
154 * situations where objects are not yet attached to parents (e.g.,
155 * {@link SBMLDocument}), knowledge of the intented SBML Level and Version help
156 * libSBML determine such things as whether it is valid to assign a
157 * particular value to an attribute.  For packages, this means that the 
158 * parent object to which this package element is being added must have
159 * been created with the package namespace, or that the package namespace
160 * was added to it, even if that parent is not a package object itself.
161   */ public
162 ListOfGeneProducts(long level, long version, long pkgVersion) throws org.sbml.libsbml.SBMLConstructorException {
163    this(libsbmlJNI.new_ListOfGeneProducts__SWIG_0(level, version, pkgVersion), true);
164  }
165
166  
167/**
168   * Creates a new {@link GeneProduct} with the given SBML Level, Version, and
169   * &ldquo;fbc&rdquo;package version.
170   <p>
171   * @param level a long integer, the SBML Level to assign to this
172   * {@link ListOfGeneProducts}.
173   <p>
174   * @param version a long integer, the SBML Version to assign to this
175   * {@link ListOfGeneProducts}.
176   <p>
177   * @param pkgVersion a long integer, the SBML Fbc Version to assign to
178   * this {@link ListOfGeneProducts}.
179   <p>
180   * <p>
181 * @note Attempting to add an object to an {@link SBMLDocument} having a different
182 * combination of SBML Level, Version and XML namespaces than the object
183 * itself will result in an error at the time a caller attempts to make the
184 * addition.  A parent object must have compatible Level, Version and XML
185 * namespaces.  (Strictly speaking, a parent may also have more XML
186 * namespaces than a child, but the reverse is not permitted.)  The
187 * restriction is necessary to ensure that an SBML model has a consistent
188 * overall structure.  This requires callers to manage their objects
189 * carefully, but the benefit is increased flexibility in how models can be
190 * created by permitting callers to create objects bottom-up if desired.  In
191 * situations where objects are not yet attached to parents (e.g.,
192 * {@link SBMLDocument}), knowledge of the intented SBML Level and Version help
193 * libSBML determine such things as whether it is valid to assign a
194 * particular value to an attribute.  For packages, this means that the 
195 * parent object to which this package element is being added must have
196 * been created with the package namespace, or that the package namespace
197 * was added to it, even if that parent is not a package object itself.
198   */ public
199 ListOfGeneProducts(long level, long version) throws org.sbml.libsbml.SBMLConstructorException {
200    this(libsbmlJNI.new_ListOfGeneProducts__SWIG_1(level, version), true);
201  }
202
203  
204/**
205   * Creates a new {@link GeneProduct} with the given SBML Level, Version, and
206   * &ldquo;fbc&rdquo;package version.
207   <p>
208   * @param level a long integer, the SBML Level to assign to this
209   * {@link ListOfGeneProducts}.
210   <p>
211   * @param version a long integer, the SBML Version to assign to this
212   * {@link ListOfGeneProducts}.
213   <p>
214   * @param pkgVersion a long integer, the SBML Fbc Version to assign to
215   * this {@link ListOfGeneProducts}.
216   <p>
217   * <p>
218 * @note Attempting to add an object to an {@link SBMLDocument} having a different
219 * combination of SBML Level, Version and XML namespaces than the object
220 * itself will result in an error at the time a caller attempts to make the
221 * addition.  A parent object must have compatible Level, Version and XML
222 * namespaces.  (Strictly speaking, a parent may also have more XML
223 * namespaces than a child, but the reverse is not permitted.)  The
224 * restriction is necessary to ensure that an SBML model has a consistent
225 * overall structure.  This requires callers to manage their objects
226 * carefully, but the benefit is increased flexibility in how models can be
227 * created by permitting callers to create objects bottom-up if desired.  In
228 * situations where objects are not yet attached to parents (e.g.,
229 * {@link SBMLDocument}), knowledge of the intented SBML Level and Version help
230 * libSBML determine such things as whether it is valid to assign a
231 * particular value to an attribute.  For packages, this means that the 
232 * parent object to which this package element is being added must have
233 * been created with the package namespace, or that the package namespace
234 * was added to it, even if that parent is not a package object itself.
235   */ public
236 ListOfGeneProducts(long level) throws org.sbml.libsbml.SBMLConstructorException {
237    this(libsbmlJNI.new_ListOfGeneProducts__SWIG_2(level), true);
238  }
239
240  
241/**
242   * Creates a new {@link GeneProduct} with the given SBML Level, Version, and
243   * &ldquo;fbc&rdquo;package version.
244   <p>
245   * @param level a long integer, the SBML Level to assign to this
246   * {@link ListOfGeneProducts}.
247   <p>
248   * @param version a long integer, the SBML Version to assign to this
249   * {@link ListOfGeneProducts}.
250   <p>
251   * @param pkgVersion a long integer, the SBML Fbc Version to assign to
252   * this {@link ListOfGeneProducts}.
253   <p>
254   * <p>
255 * @note Attempting to add an object to an {@link SBMLDocument} having a different
256 * combination of SBML Level, Version and XML namespaces than the object
257 * itself will result in an error at the time a caller attempts to make the
258 * addition.  A parent object must have compatible Level, Version and XML
259 * namespaces.  (Strictly speaking, a parent may also have more XML
260 * namespaces than a child, but the reverse is not permitted.)  The
261 * restriction is necessary to ensure that an SBML model has a consistent
262 * overall structure.  This requires callers to manage their objects
263 * carefully, but the benefit is increased flexibility in how models can be
264 * created by permitting callers to create objects bottom-up if desired.  In
265 * situations where objects are not yet attached to parents (e.g.,
266 * {@link SBMLDocument}), knowledge of the intented SBML Level and Version help
267 * libSBML determine such things as whether it is valid to assign a
268 * particular value to an attribute.  For packages, this means that the 
269 * parent object to which this package element is being added must have
270 * been created with the package namespace, or that the package namespace
271 * was added to it, even if that parent is not a package object itself.
272   */ public
273 ListOfGeneProducts() throws org.sbml.libsbml.SBMLConstructorException {
274    this(libsbmlJNI.new_ListOfGeneProducts__SWIG_3(), true);
275  }
276
277  
278/**
279   * Creates a new {@link ListOfGeneProducts} with the given {@link FbcPkgNamespaces} object.
280   <p>
281   * <p>
282 * The package namespaces object used in this constructor is derived from a
283 * {@link SBMLNamespaces} object, which encapsulates SBML Level/Version/namespaces
284 * information.  It is used to communicate the SBML Level, Version, and 
285 * package version and name information used in addition to SBML Level&nbsp;3 Core.  A
286 * common approach to using libSBML's {@link SBMLNamespaces} facilities is to create an
287 * package namespace object somewhere in a program once, then hand that object
288 * as needed to object constructors of that package that accept it as and
289 * argument, such as this one.
290   <p>
291   * @param fbcns the {@link FbcPkgNamespaces} object.
292   <p>
293   * <p>
294 * @note Attempting to add an object to an {@link SBMLDocument} having a different
295 * combination of SBML Level, Version and XML namespaces than the object
296 * itself will result in an error at the time a caller attempts to make the
297 * addition.  A parent object must have compatible Level, Version and XML
298 * namespaces.  (Strictly speaking, a parent may also have more XML
299 * namespaces than a child, but the reverse is not permitted.)  The
300 * restriction is necessary to ensure that an SBML model has a consistent
301 * overall structure.  This requires callers to manage their objects
302 * carefully, but the benefit is increased flexibility in how models can be
303 * created by permitting callers to create objects bottom-up if desired.  In
304 * situations where objects are not yet attached to parents (e.g.,
305 * {@link SBMLDocument}), knowledge of the intented SBML Level and Version help
306 * libSBML determine such things as whether it is valid to assign a
307 * particular value to an attribute.  For packages, this means that the 
308 * parent object to which this package element is being added must have
309 * been created with the package namespace, or that the package namespace
310 * was added to it, even if that parent is not a package object itself.
311   */ public
312 ListOfGeneProducts(FbcPkgNamespaces fbcns) throws org.sbml.libsbml.SBMLConstructorException {
313    this(libsbmlJNI.new_ListOfGeneProducts__SWIG_4(FbcPkgNamespaces.getCPtr(fbcns), fbcns), true);
314  }
315
316  
317/**
318   * Creates and returns a deep copy of this {@link ListOfGeneProducts} object.
319   <p>
320   * @return a (deep) copy of this {@link ListOfGeneProducts} object.
321   */ public
322 ListOfGeneProducts cloneObject() {
323    long cPtr = libsbmlJNI.ListOfGeneProducts_cloneObject(swigCPtr, this);
324    return (cPtr == 0) ? null : new ListOfGeneProducts(cPtr, true);
325  }
326
327  
328/**
329   * Get a {@link GeneProduct} from the {@link ListOfGeneProducts}.
330   <p>
331   * @param n the index number of the {@link GeneProduct} to get.
332   <p>
333   * @return the nth {@link GeneProduct} in this {@link ListOfGeneProducts}.
334   <p>
335   * @see #size()
336   */ public
337 GeneProduct get(long n) {
338    long cPtr = libsbmlJNI.ListOfGeneProducts_get__SWIG_0(swigCPtr, this, n);
339    return (cPtr == 0) ? null : new GeneProduct(cPtr, false);
340  }
341
342  
343/**
344   * Get a {@link GeneProduct} from the {@link ListOfGeneProducts} based on its identifier.
345   <p>
346   * @param sid a string representing the identifier of the {@link GeneProduct} to
347   * get.
348   <p>
349   * @return {@link GeneProduct} in this {@link ListOfGeneProducts} with the given id or null
350   * if no such {@link GeneProduct} exists.
351   <p>
352   * @see #get(long n)
353   * @see #size()
354   */ public
355 GeneProduct get(String sid) {
356    long cPtr = libsbmlJNI.ListOfGeneProducts_get__SWIG_2(swigCPtr, this, sid);
357    return (cPtr == 0) ? null : new GeneProduct(cPtr, false);
358  }
359
360  
361/**
362   * Adds a copy the given {@link GeneProduct} to this {@link ListOfGeneProducts}.
363   <p>
364   * @param gp the {@link GeneProduct} object to add.
365   <p>
366   * <p>
367 * @return integer value indicating success/failure of the
368 * function.   The possible values
369 * returned by this function are:
370   * <ul>
371   * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS}
372   * <li> {@link libsbmlConstants#LIBSBML_INVALID_ATTRIBUTE_VALUE LIBSBML_INVALID_ATTRIBUTE_VALUE}
373   * </ul>
374   */ public
375 int addGeneProduct(GeneProduct gp) {
376    return libsbmlJNI.ListOfGeneProducts_addGeneProduct(swigCPtr, this, GeneProduct.getCPtr(gp), gp);
377  }
378
379  
380/**
381   * Get the number of {@link GeneProduct} objects in this {@link ListOfGeneProducts}.
382   <p>
383   * @return the number of {@link GeneProduct} objects in this {@link ListOfGeneProducts}.
384   */ public
385 long getNumGeneProducts() {
386    return libsbmlJNI.ListOfGeneProducts_getNumGeneProducts(swigCPtr, this);
387  }
388
389  
390/**
391   * Creates a new {@link GeneProduct} object, adds it to the {@link ListOfGeneProducts} and
392   * returns the {@link GeneProduct} object created.
393   <p>
394   * @return a new {@link GeneProduct} object instance.
395   <p>
396   * @see #addGeneProduct(GeneProduct gp)
397   */ public
398 GeneProduct createGeneProduct() {
399    long cPtr = libsbmlJNI.ListOfGeneProducts_createGeneProduct(swigCPtr, this);
400    return (cPtr == 0) ? null : new GeneProduct(cPtr, false);
401  }
402
403  
404/**
405   * Removes the nth {@link GeneProduct} from this {@link ListOfGeneProducts}
406   * and returns a pointer to it.
407   <p>
408   * The caller owns the returned item and is responsible for deleting it.
409   <p>
410   * @param n the index of the {@link GeneProduct} to remove.
411   <p>
412   * @see #size()
413   */ public
414 GeneProduct remove(long n) {
415    long cPtr = libsbmlJNI.ListOfGeneProducts_remove__SWIG_0(swigCPtr, this, n);
416    return (cPtr == 0) ? null : new GeneProduct(cPtr, true);
417  }
418
419  
420/**
421   * Removes the {@link GeneProduct} from this {@link ListOfGeneProducts} with the given
422   * identifier and returns a pointer to it.
423   <p>
424   * The caller owns the returned item and is responsible for deleting it.
425   * If none of the items in this list have the identifier <code>sid</code>, then
426   * <code>null</code> is returned.
427   <p>
428   * @param sid the identifier of the {@link GeneProduct} to remove.
429   <p>
430   * @return the {@link GeneProduct} removed. As mentioned above, the caller owns the
431   * returned item.
432   */ public
433 GeneProduct remove(String sid) {
434    long cPtr = libsbmlJNI.ListOfGeneProducts_remove__SWIG_1(swigCPtr, this, sid);
435    return (cPtr == 0) ? null : new GeneProduct(cPtr, true);
436  }
437
438  
439/**
440   * Returns the XML element name of this object.
441   <p>
442   * For {@link ListOfGeneProducts}, the XML element name is always @c
443   * 'listOfGeneProducts'.
444   <p>
445   * @return the name of this element, i.e. <code>'listOfGeneProducts'.</code>
446   */ public
447 String getElementName() {
448    return libsbmlJNI.ListOfGeneProducts_getElementName(swigCPtr, this);
449  }
450
451  
452/**
453   * Returns the libSBML type code for this SBML object.
454   <p>
455   * <p>
456 * LibSBML attaches an identifying code to every kind of SBML object.  These
457 * are integer constants known as <em>SBML type codes</em>.  The names of all
458 * the codes begin with the characters <code>SBML_</code>.
459 * In the Java language interface for libSBML, the
460 * type codes are defined as static integer constants in the interface class
461 * {@link libsbmlConstants}.    Note that different Level&nbsp;3
462 * package plug-ins may use overlapping type codes; to identify the package
463 * to which a given object belongs, call the <code>getPackageName()</code>
464 * method on the object.
465   <p>
466   * @return the SBML type code for this object:
467   * {@link libsbmlConstants#SBML_LIST_OF SBML_LIST_OF} (default).
468   <p>
469   * <p>
470 * @warning <span class='warning'>The specific integer values of the possible
471 * type codes may be reused by different libSBML plug-ins for SBML Level&nbsp;3.
472 * packages,  To fully identify the correct code, <strong>it is necessary to
473 * invoke both getTypeCode() and getPackageName()</strong>.</span>
474   <p>
475   * @see #getElementName()
476   * @see #getPackageName()
477   */ public
478 int getTypeCode() {
479    return libsbmlJNI.ListOfGeneProducts_getTypeCode(swigCPtr, this);
480  }
481
482  
483/**
484   * Returns the libSBML type code for the objects contained in this {@link ListOf}.
485   <p>
486   * <p>
487 * LibSBML attaches an identifying code to every kind of SBML object.  These
488 * are integer constants known as <em>SBML type codes</em>.  The names of all
489 * the codes begin with the characters <code>SBML_</code>.
490 * In the Java language interface for libSBML, the
491 * type codes are defined as static integer constants in the interface class
492 * {@link libsbmlConstants}.    Note that different Level&nbsp;3
493 * package plug-ins may use overlapping type codes; to identify the package
494 * to which a given object belongs, call the <code>getPackageName()</code>
495 * method on the object.
496   <p>
497   * @return the SBML type code for the objects contained in this {@link ListOf}
498   * instance: {@link libsbmlConstants#SBML_FBC_GENEPRODUCT SBML_FBC_GENEPRODUCT} (default).
499   <p>
500   * @see #getElementName()
501   * @see #getPackageName()
502   */ public
503 int getItemTypeCode() {
504    return libsbmlJNI.ListOfGeneProducts_getItemTypeCode(swigCPtr, this);
505  }
506
507}