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