public class ListOf extends SBase
This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. This class is not prescribed by the SBML specifications, although it is used to implement features defined in SBML.
The ListOf
class in libSBML is a utility class that serves as the parent
class for implementing the ListOf__ classes. It provides methods for
working generically with the various SBML lists of objects in a program.
LibSBML uses this separate list class rather than ordinary
Java lists,
so that it can provide the methods and features associated with SBase
.
The various ListOf___ classes in SBML
are merely containers used for organizing the main components of an SBML
model. In libSBML's implementation, ListOf___
classes are derived from the
intermediate utility class ListOf
, which
is not defined by the SBML specifications but serves as a useful
programmatic construct. ListOf
is itself is in turn derived from SBase
,
which provides all of the various ListOf___
classes with common features
defined by the SBML specification, such as 'metaid' attributes and
annotations.
The relationship between the lists and the rest of an SBML model is illustrated by the following (for SBML Level 2 Version 4):
Readers may wonder about the motivations for using the ListOf___
containers in SBML. A simpler approach in XML might be to place the
components all directly at the top level of the model definition. The
choice made in SBML is to group them within XML elements named after
ListOfClassname, in part because it helps organize the
components. More importantly, the fact that the container classes are
derived from SBase
means that software tools can add information about
the lists themselves into each list container's 'annotation'.
Constructor and Description |
---|
ListOf()
Creates a new
ListOf object. |
ListOf(ListOf orig)
Copy constructor creates a copy of this
ListOf . |
ListOf(long level)
Creates a new
ListOf object. |
ListOf(long level,
long version)
Creates a new
ListOf object. |
ListOf(SBMLNamespaces sbmlns)
Creates a new
ListOf with a given SBMLNamespaces object. |
Modifier and Type | Method and Description |
---|---|
int |
append(SBase item)
Adds an item to the end of this
ListOf 's list of items. |
int |
appendAndOwn(SBase disownedItem)
Adds an item to the end of this
ListOf 's list of items. |
int |
appendFrom(ListOf list)
Adds a clone of a list of items to this
ListOf 's list. |
void |
clear()
Removes all items in this
ListOf object. |
void |
clear(boolean doDelete)
Removes all items in this
ListOf object. |
ListOf |
cloneObject()
Creates and returns a deep copy of this
ListOf object. |
void |
connectToChild()   |
void |
delete()
Explicitly deletes the underlying native object.
|
SBase |
get(long n)
Get an item from the list.
|
SBase |
getElementByMetaId(java.lang.String metaid)
Returns the first child element found with the given meta-identifier.
|
SBase |
getElementBySId(java.lang.String id)
Returns the first child element found that has the given identifier.
|
java.lang.String |
getElementName()
Returns the XML element name of this object, which for
ListOf , is
always 'listOf'. |
int |
getItemTypeCode()
Get the type code of the objects contained in this
ListOf . |
int |
getTypeCode()
Returns the libSBML type code for this object, namely,
SBML_LIST_OF . |
int |
insert(int location,
SBase item)
Inserts an item at a given position in this
ListOf 's list of items. |
int |
insertAndOwn(int location,
SBase disownedItem)
Inserts an item at a given position in this
ListOf 's list of items. |
SBase |
remove(long n)
Removes the nth item from this
ListOf list of items and returns
it. |
int |
removeFromParentAndDelete()
Removes all items in this
ListOf object and deletes its properties too. |
long |
size()
Returns number of items in this
ListOf list. |
addCVTerm, addCVTerm, appendAnnotation, appendAnnotation, appendNotes, appendNotes, deleteDisabledPlugins, deleteDisabledPlugins, disablePackage, enablePackage, equals, getAncestorOfType, getAncestorOfType, getAnnotation, getAnnotationString, getColumn, getCVTerm, getCVTerms, getDisabledPlugin, getLevel, getLine, getListOfAllElements, getListOfAllElements, getListOfAllElementsFromPlugins, getListOfAllElementsFromPlugins, getMetaId, getModel, getModelHistory, getNamespaces, getNotes, getNotesString, getNumCVTerms, getNumDisabledPlugins, getNumPlugins, getPackageName, getPackageVersion, getParentSBMLObject, getPlugin, getPlugin, getPrefix, getResourceBiologicalQualifier, getResourceModelQualifier, getSBMLDocument, getSBOTerm, getSBOTermAsURL, getSBOTermID, getURI, getVersion, hashCode, hasValidLevelVersionNamespaceCombination, isPackageEnabled, isPackageURIEnabled, isPkgEnabled, isPkgURIEnabled, isSetAnnotation, isSetMetaId, isSetModelHistory, isSetNotes, isSetSBOTerm, isSetUserData, matchesRequiredSBMLNamespacesForAddition, matchesSBMLNamespaces, removeTopLevelAnnotationElement, removeTopLevelAnnotationElement, removeTopLevelAnnotationElement, renameMetaIdRefs, renameSIdRefs, renameUnitSIdRefs, replaceTopLevelAnnotationElement, replaceTopLevelAnnotationElement, setAnnotation, setAnnotation, setMetaId, setModelHistory, setNamespaces, setNotes, setNotes, setNotes, setSBOTerm, setSBOTerm, toSBML, toXMLNode, unsetAnnotation, unsetCVTerms, unsetId, unsetMetaId, unsetModelHistory, unsetName, unsetNotes, unsetSBOTerm, unsetUserData
public ListOf(long level, long version) throws SBMLConstructorException
ListOf
object.
level
- the SBML Level if not assigned, defaults to the
value of SBMLDocument.getDefaultLevel()
.
version
- the Version within the SBML Level if not assigned,
defaults to the value of SBMLDocument.getDefaultVersion()
.
SBMLConstructorException
ListOf
objects are
impossible to add to SBML models. The ListOf
class is simply the base
of other classes in
libSBML. Calling programs are not intended to create bare ListOf
objects themselves.
, Attempting to add an object to an SBMLDocument
having a different
combination of SBML Level, Version and XML namespaces than the object
itself will result in an error at the time a caller attempts to make the
addition. A parent object must have compatible Level, Version and XML
namespaces. (Strictly speaking, a parent may also have more XML
namespaces than a child, but the reverse is not permitted.) The
restriction is necessary to ensure that an SBML model has a consistent
overall structure. This requires callers to manage their objects
carefully, but the benefit is increased flexibility in how models can be
created by permitting callers to create objects bottom-up if desired. In
situations where objects are not yet attached to parents (e.g.,
SBMLDocument
), knowledge of the intented SBML Level and Version help
libSBML determine such things as whether it is valid to assign a
particular value to an attribute.
public ListOf(long level) throws SBMLConstructorException
ListOf
object.
level
- the SBML Level if not assigned, defaults to the
value of SBMLDocument.getDefaultLevel()
.
version
- the Version within the SBML Level if not assigned,
defaults to the value of SBMLDocument.getDefaultVersion()
.
SBMLConstructorException
ListOf
objects are
impossible to add to SBML models. The ListOf
class is simply the base
of other classes in
libSBML. Calling programs are not intended to create bare ListOf
objects themselves.
, Attempting to add an object to an SBMLDocument
having a different
combination of SBML Level, Version and XML namespaces than the object
itself will result in an error at the time a caller attempts to make the
addition. A parent object must have compatible Level, Version and XML
namespaces. (Strictly speaking, a parent may also have more XML
namespaces than a child, but the reverse is not permitted.) The
restriction is necessary to ensure that an SBML model has a consistent
overall structure. This requires callers to manage their objects
carefully, but the benefit is increased flexibility in how models can be
created by permitting callers to create objects bottom-up if desired. In
situations where objects are not yet attached to parents (e.g.,
SBMLDocument
), knowledge of the intented SBML Level and Version help
libSBML determine such things as whether it is valid to assign a
particular value to an attribute.
public ListOf() throws SBMLConstructorException
ListOf
object.
level
- the SBML Level if not assigned, defaults to the
value of SBMLDocument.getDefaultLevel()
.
version
- the Version within the SBML Level if not assigned,
defaults to the value of SBMLDocument.getDefaultVersion()
.
SBMLConstructorException
ListOf
objects are
impossible to add to SBML models. The ListOf
class is simply the base
of other classes in
libSBML. Calling programs are not intended to create bare ListOf
objects themselves.
, Attempting to add an object to an SBMLDocument
having a different
combination of SBML Level, Version and XML namespaces than the object
itself will result in an error at the time a caller attempts to make the
addition. A parent object must have compatible Level, Version and XML
namespaces. (Strictly speaking, a parent may also have more XML
namespaces than a child, but the reverse is not permitted.) The
restriction is necessary to ensure that an SBML model has a consistent
overall structure. This requires callers to manage their objects
carefully, but the benefit is increased flexibility in how models can be
created by permitting callers to create objects bottom-up if desired. In
situations where objects are not yet attached to parents (e.g.,
SBMLDocument
), knowledge of the intented SBML Level and Version help
libSBML determine such things as whether it is valid to assign a
particular value to an attribute.
public ListOf(SBMLNamespaces sbmlns) throws SBMLConstructorException
ListOf
with a given SBMLNamespaces
object.
sbmlns
- the set of SBML namespaces that this ListOf
should
contain.
SBMLConstructorException
ListOf
objects are
impossible to add to SBML models. The ListOf
class is simply the base
of other classes in
libSBML. Calling programs are not intended to create bare ListOf
objects themselves.
, Attempting to add an object to an SBMLDocument
having a different
combination of SBML Level, Version and XML namespaces than the object
itself will result in an error at the time a caller attempts to make the
addition. A parent object must have compatible Level, Version and XML
namespaces. (Strictly speaking, a parent may also have more XML
namespaces than a child, but the reverse is not permitted.) The
restriction is necessary to ensure that an SBML model has a consistent
overall structure. This requires callers to manage their objects
carefully, but the benefit is increased flexibility in how models can be
created by permitting callers to create objects bottom-up if desired. In
situations where objects are not yet attached to parents (e.g.,
SBMLDocument
), knowledge of the intented SBML Level and Version help
libSBML determine such things as whether it is valid to assign a
particular value to an attribute.
public ListOf(ListOf orig) throws SBMLConstructorException
ListOf
.
orig
- the ListOf
instance to copy.SBMLConstructorException
public void delete()
In general, application software will not need to call this method directly. The Java language binding for libSBML is implemented as a language wrapper that provides a Java interface to libSBML's underlying C++/C code. Some of the Java methods return objects that are linked to objects created not by Java code, but by C++ code. The Java objects wrapped around them will be deleted when the garbage collector invokes the corresponding C++ finalize()
methods for the objects. The finalize()
methods in turn call the ListOf.delete()
method on the libSBML object.
This method is exposed in case calling programs want to ensure that the underlying object is freed immediately, and not at some arbitrary time determined by the Java garbage collector. In normal usage, callers do not need to invoke ListOf.delete()
themselves.
public ListOf cloneObject()
ListOf
object.
cloneObject
 in class SBase
ListOf
object.public int append(SBase item)
ListOf
's list of items.
This method makes a clone of the item
handed to it. This means that
when the ListOf
object is destroyed, the original items will not be
destroyed. For a method with an alternative ownership behavior, see the
ListOf.appendAndOwn(SBase)
method.
item
- the item to be added to the list.
ListOf.appendAndOwn(SBase disownedItem)
,
ListOf.appendFrom(ListOf list)
public int appendAndOwn(SBase disownedItem)
ListOf
's list of items.
This method does not clone the disownedItem
handed to it instead, it assumes
ownership of it. This means that when the ListOf
is destroyed, the item
will be destroyed along with it. For a method with an alternative
ownership behavior, see the ListOf.append(SBase item)
method.
disownedItem
- the item to be added to the list.
ListOf.append(SBase item)
,
ListOf.appendFrom(ListOf list)
public int appendFrom(ListOf list)
ListOf
's list.
Note that because this clones the objects handed to it, the original
items will not be destroyed when this ListOf
object is destroyed.
list
- a list of items to be added.
ListOf.append(SBase item)
,
ListOf.appendAndOwn(SBase disownedItem)
public int insert(int location, SBase item)
ListOf
's list of items.
This variant of the method makes a clone of the item
handed to it.
This means that when the ListOf
is destroyed, the original item
will
not be destroyed.
location
- the location in the list where to insert the item.item
- the item to be inserted to the list.
ListOf.insertAndOwn(int location, SBase item)
public int insertAndOwn(int location, SBase disownedItem)
ListOf
's list of items.
This variant of the method does not make a clone of the disownedItem
handed to it.
This means that when the ListOf
is destroyed, the original item
will be destroyed.
location
- the location where to insert the itemdisownedItem
- the item to be inserted to the list
ListOf.insert(int location, SBase item)
public SBase get(long n)
n
- the index number of the item to get.
ListOf
items, or a null pointer if
the index number n
refers to a nonexistent position in this list.
ListOf.size()
public SBase getElementBySId(java.lang.String id)
This method searches this ListOf
's list of items for SBML objects based
on their 'id' attribute value in the model-wide SId
identifier namespace.
getElementBySId
 in class SBase
id
- string representing the id of the object to find.
id
, or null
if no
such object is found.public SBase getElementByMetaId(java.lang.String metaid)
getElementByMetaId
 in class SBase
metaid
- string representing the 'metaid' attribute of the object
to find.
metaid
, or null
if
no such object is found.public void clear(boolean doDelete)
ListOf
object.
If parameter doDelete
is true
(default), all items in this ListOf
object are deleted and cleared, and thus the caller doesn't have to
delete those items. Otherwise, all items are cleared only from this
ListOf
object the caller is still responsible for deleting the actual
items. (In the latter case, callers are advised to store pointers to
all items elsewhere before calling this function.)
doDelete
- if true
(default), all items are deleted and cleared.
Otherwise, all items are just cleared and not deleted.
public void clear()
ListOf
object.
If parameter doDelete
is true
(default), all items in this ListOf
object are deleted and cleared, and thus the caller doesn't have to
delete those items. Otherwise, all items are cleared only from this
ListOf
object the caller is still responsible for deleting the actual
items. (In the latter case, callers are advised to store pointers to
all items elsewhere before calling this function.)
doDelete
- if true
(default), all items are deleted and cleared.
Otherwise, all items are just cleared and not deleted.
public int removeFromParentAndDelete()
ListOf
object and deletes its properties too.
This performs a call to clear() with an argument of true
(thus removing
all the child objects in the list), followed by calls to various libSBML
unsetFoo
methods to delete everything else: CVTerm
objects, model history objects, etc.
removeFromParentAndDelete
 in class SBase
public SBase remove(long n)
ListOf
list of items and returns
it.
The caller owns the returned item and is responsible for deleting it.
n
- the index of the item to remove
ListOf.size()
public long size()
ListOf
list.
ListOf
items.public void connectToChild()
connectToChild
 in class SBase
public int getTypeCode()
SBML_LIST_OF
.
LibSBML attaches an identifying code to every kind of SBML object. These
are integer constants known as SBML type codes. The names of all
the codes begin with the characters SBML_
.
In the Java language interface for libSBML, the
type codes are defined as static integer constants in the interface class
libsbmlConstants
. Note that different Level 3
package plug-ins may use overlapping type codes to identify the package
to which a given object belongs, call the getPackageName()
method on the object.
getTypeCode
 in class SBase
SBML_LIST_OF
(default).
ListOf.getItemTypeCode()
,
ListOf.getElementName()
,
SBase.getPackageName()
ListOf
classes mostly differ from each other in what they
contain. Hence, one must call getItemTypeCode() to fully determine the
class of this SBML object.
public int getItemTypeCode()
ListOf
.
LibSBML attaches an identifying code to every kind of SBML object. These
are integer constants known as SBML type codes. The names of all
the codes begin with the characters SBML_
.
In the Java language interface for libSBML, the
type codes are defined as static integer constants in the interface class
libsbmlConstants
. Note that different Level 3
package plug-ins may use overlapping type codes to identify the package
to which a given object belongs, call the getPackageName()
method on the object.
Classes that inherit from the ListOf
class should override this method
to return the SBML type code for the objects contained in this ListOf
.
If they do not, this method will return
SBML_UNKNOWN
ListOf
base class contains no SBML objects, and therefore
this method returns SBML_UNKNOWN
.
ListOf.getElementName()
,
SBase.getPackageName()
public java.lang.String getElementName()
ListOf
, is
always 'listOf'.
getElementName
 in class SBase