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-comp"><a href="group__comp.html">comp</a></span>
013 A list of {@link Port} objects.
014 <p>
015 * The {@link ListOfPorts} is a container for the extended 
016 * {@link Model} for {@link Port} objects for that {@link Model}.
017 <p>
018 * <p>
019 * The various ListOf___ classes in SBML
020 * are merely containers used for organizing the main components of an SBML
021 * model.  In libSBML's implementation, ListOf___
022 * classes are derived from the
023 * intermediate utility class {@link ListOf}, which
024 * is not defined by the SBML specifications but serves as a useful
025 * programmatic construct.  {@link ListOf} is itself is in turn derived from {@link SBase},
026 * which provides all of the various ListOf___
027 * classes with common features
028 * defined by the SBML specification, such as 'metaid' attributes and
029 * annotations.
030 <p>
031 * The relationship between the lists and the rest of an SBML model is
032 * illustrated by the following (for SBML Level&nbsp;2 Version&nbsp;4):
033 <p>
034 * <figure>
035  <object type="image/svg+xml" data="listof-illustration.svg" class="centered"></object>
036</figure>
037
038 <p>
039 * SBML Level&nbsp;3 Version&nbsp;1 has essentially the same structure as 
040 * Level&nbsp;2 Version&nbsp;4, depicted above, but SBML Level&nbsp;3 
041 * Version&nbsp;2 allows
042 * containers to contain zero or more of the relevant object, instead of 
043 * requiring at least one.  As such, libsbml will write out an 
044 * otherwise-empty ListOf___ element that has any optional attribute set 
045 * (such as 'id' or 'metaid'), that has an optional child (such 
046 * as a 'notes' or 'annotation'), or that has attributes or children set
047 * from any SBML Level&nbsp;3 package, whether or not the ListOf___ has 
048 * any other children.
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 <p>
072 * @see Port
073 * @see ListOfDeletions
074 * @see ListOfExternalModelDefinitions
075 * @see ListOfModelDefinitions
076 * @see ListOfReplacedElements
077 * @see ListOfSubmodels
078 */
079
080public class ListOfPorts extends ListOf {
081   private long swigCPtr;
082
083   protected ListOfPorts(long cPtr, boolean cMemoryOwn)
084   {
085     super(libsbmlJNI.ListOfPorts_SWIGUpcast(cPtr), cMemoryOwn);
086     swigCPtr = cPtr;
087   }
088
089   protected static long getCPtr(ListOfPorts obj)
090   {
091     return (obj == null) ? 0 : obj.swigCPtr;
092   }
093
094   protected static long getCPtrAndDisown (ListOfPorts obj)
095   {
096     long ptr = 0;
097
098     if (obj != null)
099     {
100       ptr             = obj.swigCPtr;
101       obj.swigCMemOwn = false;
102     }
103
104     return ptr;
105   }
106
107  protected void finalize() {
108    delete();
109  }
110
111  public synchronized void delete() {
112    if (swigCPtr != 0) {
113      if (swigCMemOwn) {
114        swigCMemOwn = false;
115        libsbmlJNI.delete_ListOfPorts(swigCPtr);
116      }
117      swigCPtr = 0;
118    }
119    super.delete();
120  }
121
122  
123/**
124   * Creates and returns a deep copy of this {@link ListOfPorts} object.
125   <p>
126   * @return a (deep) copy of this {@link ListOfPorts}.
127   */ public
128 ListOfPorts cloneObject() {
129    long cPtr = libsbmlJNI.ListOfPorts_cloneObject(swigCPtr, this);
130    return (cPtr == 0) ? null : new ListOfPorts(cPtr, true);
131  }
132
133  
134/**
135   * Creates a new {@link ListOfPorts} with the given level, version, and package version.
136   <p>
137   * @param level the SBML Level.
138   * @param version the Version within the SBML Level.
139   * @param pkgVersion the version of the package.
140   <p>
141   * <p>
142 * @note Attempting to add an object to an {@link SBMLDocument} having a different
143 * combination of SBML Level, Version and XML namespaces than the object
144 * itself will result in an error at the time a caller attempts to make the
145 * addition.  A parent object must have compatible Level, Version and XML
146 * namespaces.  (Strictly speaking, a parent may also have more XML
147 * namespaces than a child, but the reverse is not permitted.)  The
148 * restriction is necessary to ensure that an SBML model has a consistent
149 * overall structure.  This requires callers to manage their objects
150 * carefully, but the benefit is increased flexibility in how models can be
151 * created by permitting callers to create objects bottom-up if desired.  In
152 * situations where objects are not yet attached to parents (e.g.,
153 * {@link SBMLDocument}), knowledge of the intented SBML Level and Version help
154 * libSBML determine such things as whether it is valid to assign a
155 * particular value to an attribute.  For packages, this means that the 
156 * parent object to which this package element is being added must have
157 * been created with the package namespace, or that the package namespace
158 * was added to it, even if that parent is not a package object itself.
159   */ public
160 ListOfPorts(long level, long version, long pkgVersion) throws org.sbml.libsbml.SBMLConstructorException {
161    this(libsbmlJNI.new_ListOfPorts__SWIG_0(level, version, pkgVersion), true);
162  }
163
164  
165/**
166   * Creates a new {@link ListOfPorts} with the given level, version, and package version.
167   <p>
168   * @param level the SBML Level.
169   * @param version the Version within the SBML Level.
170   * @param pkgVersion the version of the package.
171   <p>
172   * <p>
173 * @note Attempting to add an object to an {@link SBMLDocument} having a different
174 * combination of SBML Level, Version and XML namespaces than the object
175 * itself will result in an error at the time a caller attempts to make the
176 * addition.  A parent object must have compatible Level, Version and XML
177 * namespaces.  (Strictly speaking, a parent may also have more XML
178 * namespaces than a child, but the reverse is not permitted.)  The
179 * restriction is necessary to ensure that an SBML model has a consistent
180 * overall structure.  This requires callers to manage their objects
181 * carefully, but the benefit is increased flexibility in how models can be
182 * created by permitting callers to create objects bottom-up if desired.  In
183 * situations where objects are not yet attached to parents (e.g.,
184 * {@link SBMLDocument}), knowledge of the intented SBML Level and Version help
185 * libSBML determine such things as whether it is valid to assign a
186 * particular value to an attribute.  For packages, this means that the 
187 * parent object to which this package element is being added must have
188 * been created with the package namespace, or that the package namespace
189 * was added to it, even if that parent is not a package object itself.
190   */ public
191 ListOfPorts(long level, long version) throws org.sbml.libsbml.SBMLConstructorException {
192    this(libsbmlJNI.new_ListOfPorts__SWIG_1(level, version), true);
193  }
194
195  
196/**
197   * Creates a new {@link ListOfPorts} with the given level, version, and package version.
198   <p>
199   * @param level the SBML Level.
200   * @param version the Version within the SBML Level.
201   * @param pkgVersion the version of the package.
202   <p>
203   * <p>
204 * @note Attempting to add an object to an {@link SBMLDocument} having a different
205 * combination of SBML Level, Version and XML namespaces than the object
206 * itself will result in an error at the time a caller attempts to make the
207 * addition.  A parent object must have compatible Level, Version and XML
208 * namespaces.  (Strictly speaking, a parent may also have more XML
209 * namespaces than a child, but the reverse is not permitted.)  The
210 * restriction is necessary to ensure that an SBML model has a consistent
211 * overall structure.  This requires callers to manage their objects
212 * carefully, but the benefit is increased flexibility in how models can be
213 * created by permitting callers to create objects bottom-up if desired.  In
214 * situations where objects are not yet attached to parents (e.g.,
215 * {@link SBMLDocument}), knowledge of the intented SBML Level and Version help
216 * libSBML determine such things as whether it is valid to assign a
217 * particular value to an attribute.  For packages, this means that the 
218 * parent object to which this package element is being added must have
219 * been created with the package namespace, or that the package namespace
220 * was added to it, even if that parent is not a package object itself.
221   */ public
222 ListOfPorts(long level) throws org.sbml.libsbml.SBMLConstructorException {
223    this(libsbmlJNI.new_ListOfPorts__SWIG_2(level), true);
224  }
225
226  
227/**
228   * Creates a new {@link ListOfPorts} with the given level, version, and package version.
229   <p>
230   * @param level the SBML Level.
231   * @param version the Version within the SBML Level.
232   * @param pkgVersion the version of the package.
233   <p>
234   * <p>
235 * @note Attempting to add an object to an {@link SBMLDocument} having a different
236 * combination of SBML Level, Version and XML namespaces than the object
237 * itself will result in an error at the time a caller attempts to make the
238 * addition.  A parent object must have compatible Level, Version and XML
239 * namespaces.  (Strictly speaking, a parent may also have more XML
240 * namespaces than a child, but the reverse is not permitted.)  The
241 * restriction is necessary to ensure that an SBML model has a consistent
242 * overall structure.  This requires callers to manage their objects
243 * carefully, but the benefit is increased flexibility in how models can be
244 * created by permitting callers to create objects bottom-up if desired.  In
245 * situations where objects are not yet attached to parents (e.g.,
246 * {@link SBMLDocument}), knowledge of the intented SBML Level and Version help
247 * libSBML determine such things as whether it is valid to assign a
248 * particular value to an attribute.  For packages, this means that the 
249 * parent object to which this package element is being added must have
250 * been created with the package namespace, or that the package namespace
251 * was added to it, even if that parent is not a package object itself.
252   */ public
253 ListOfPorts() throws org.sbml.libsbml.SBMLConstructorException {
254    this(libsbmlJNI.new_ListOfPorts__SWIG_3(), true);
255  }
256
257  
258/**
259   * Creates a new {@link ListOfPorts} with the given {@link CompPkgNamespaces} object.
260   <p>
261   * <p>
262 * The package namespaces object used in this constructor is derived from a
263 * {@link SBMLNamespaces} object, which encapsulates SBML Level/Version/namespaces
264 * information.  It is used to communicate the SBML Level, Version, and 
265 * package version and name information used in addition to SBML Level&nbsp;3 Core.  A
266 * common approach to using libSBML's {@link SBMLNamespaces} facilities is to create an
267 * package namespace object somewhere in a program once, then hand that object
268 * as needed to object constructors of that package that accept it as and
269 * argument, such as this one.
270   <p>
271   * @param compns the {@link CompPkgNamespaces} object.
272   <p>
273   * <p>
274 * @note Attempting to add an object to an {@link SBMLDocument} having a different
275 * combination of SBML Level, Version and XML namespaces than the object
276 * itself will result in an error at the time a caller attempts to make the
277 * addition.  A parent object must have compatible Level, Version and XML
278 * namespaces.  (Strictly speaking, a parent may also have more XML
279 * namespaces than a child, but the reverse is not permitted.)  The
280 * restriction is necessary to ensure that an SBML model has a consistent
281 * overall structure.  This requires callers to manage their objects
282 * carefully, but the benefit is increased flexibility in how models can be
283 * created by permitting callers to create objects bottom-up if desired.  In
284 * situations where objects are not yet attached to parents (e.g.,
285 * {@link SBMLDocument}), knowledge of the intented SBML Level and Version help
286 * libSBML determine such things as whether it is valid to assign a
287 * particular value to an attribute.  For packages, this means that the 
288 * parent object to which this package element is being added must have
289 * been created with the package namespace, or that the package namespace
290 * was added to it, even if that parent is not a package object itself.
291   */ public
292 ListOfPorts(CompPkgNamespaces compns) throws org.sbml.libsbml.SBMLConstructorException {
293    this(libsbmlJNI.new_ListOfPorts__SWIG_4(CompPkgNamespaces.getCPtr(compns), compns), true);
294  }
295
296  
297/**
298   * Get a {@link Port} from the {@link ListOfPorts}.
299   <p>
300   * @param n the index number of the {@link Port} to get.
301   <p>
302   * @return the nth {@link Port} in this {@link ListOfPorts}.
303   <p>
304   * @see #size()
305   */ public
306 SBase get(long n) {
307    long cPtr = libsbmlJNI.ListOfPorts_get__SWIG_0(swigCPtr, this, n);
308    return (cPtr == 0) ? null : new Port(cPtr, false);
309  }
310
311  
312/**
313   * Get a {@link Port} from the {@link ListOfPorts}
314   * based on its identifier.
315   <p>
316   * @param sid a string representing the identifier 
317   * of the {@link Port} to get.
318   <p>
319   * @return {@link Port} in this {@link ListOfPorts}
320   * with the given <code>sid</code> or <code>null</code> if no such
321   * {@link Member} exists.
322   <p>
323   * @see #get(long n)
324   * @see #size()
325   */ public
326 Port get(String sid) {
327    long cPtr = libsbmlJNI.ListOfPorts_get__SWIG_2(swigCPtr, this, sid);
328    return (cPtr == 0) ? null : new Port(cPtr, false);
329  }
330
331  
332/**
333   * Removes an item from this {@link ListOfPorts} items based on the identifier and
334   * returns a pointer to it.
335   <p>
336   * The caller owns the returned item and is responsible for deleting it.
337   <p>
338   * @param sid string representing the id of the {@link Port} to remove.
339   <p>
340   * @see #size()
341   */ public
342 Port remove(String sid) {
343    long cPtr = libsbmlJNI.ListOfPorts_remove__SWIG_0(swigCPtr, this, sid);
344    return (cPtr == 0) ? null : new Port(cPtr, true);
345  }
346
347  
348/**
349   * Removes the nth item from this {@link ListOfPorts} items and returns a pointer
350   * to it.
351   <p>
352   * The caller owns the returned item and is responsible for deleting it.
353   <p>
354   * @param n the index of the item to remove.
355   <p>
356   * @see #size()
357   */ public
358 SBase remove(long n) {
359    long cPtr = libsbmlJNI.ListOfPorts_remove__SWIG_1(swigCPtr, this, n);
360    return (cPtr == 0) ? null : new Port(cPtr, true);
361  }
362
363  
364/**
365   * Returns the libSBML type code for the objects contained in this {@link ListOf}
366   * (i.e., {@link Port} objects, if the list is non-empty).
367   <p>
368   * <p>
369 * LibSBML attaches an identifying code to every kind of SBML object.  These
370 * are integer constants known as <em>SBML type codes</em>.  The names of all
371 * the codes begin with the characters <code>SBML_</code>.
372 * In the Java language interface for libSBML, the
373 * type codes are defined as static integer constants in the interface class
374 * {@link libsbmlConstants}.    Note that different Level&nbsp;3
375 * package plug-ins may use overlapping type codes; to identify the package
376 * to which a given object belongs, call the 
377 * <code>{@link SBase#getPackageName()}
378 * </code>
379 * method on the object.
380   <p>
381   * @return the SBML type code for objects contained in this list:
382   * {@link libsbmlConstants#SBML_COMP_PORT SBML_COMP_PORT} (default).
383   <p>
384   * @see #getElementName()
385   * @see #getPackageName()
386   */ public
387 int getItemTypeCode() {
388    return libsbmlJNI.ListOfPorts_getItemTypeCode(swigCPtr, this);
389  }
390
391  
392/**
393   * Returns the XML element name of
394   * this SBML object.
395   <p>
396   * @return the name of this element, as a text string.
397   */ public
398 String getElementName() {
399    return libsbmlJNI.ListOfPorts_getElementName(swigCPtr, this);
400  }
401
402  
403/**
404   * Returns the first child element found that has the given <code>id</code> in the
405   * model-wide SId namespace, or <code>null</code> if no such object is found.  Since the
406   * id of {@link Port} objects are in the PortSId namespace, no {@link Port} object is
407   * returned by this function.
408   <p>
409   * @param id string representing the id of the object to find.
410   <p>
411   * @return a pointer to the {@link SBase} element with the given <code>id</code>.
412   */ public
413 SBase getElementBySId(String id) {
414  return libsbml.DowncastSBase(libsbmlJNI.ListOfPorts_getElementBySId(swigCPtr, this, id), false);
415}
416
417}