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