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