public class SBaseRef extends CompBase
The SBaseRef
class was introduced by the SBML Level 3 Hierarchical Model Composition
(&ldquocomp&rdquo) package as the principle way by which submodel
elements may be referenced. The SBaseRef
class is usually found as the
base class of a Port
, Deletion
, ReplacedElement
, or ReplacedBy
class, but
may appear as an child of one of the above classes if the parent object
references a Submodel
.
An SBaseRef
object must reference an element using exactly one of the
optional attributes of the class. Subclasses of SBaseRef
may define
additional optional attributes that are legal ways to reference an element.
SBaseRef
objects may reference elements that do not live in the Model
parent
of the SBaseRef
object. However, the SBaseRef
class itself does not
provide a method of determining which Model
or Submodel
is being referenced.
The subclasses of SBaseRef
provide methods for this instead.
Once the Model
to which the SBaseRef
object is referencing has been established,
there are four optional attributes defined in the SBaseRef
class that
are each methods of referencing an element:
PortSIdRef
): As its name implies, this attribute is used to
refer to a port identifier, in the case when the reference being
constructed with the SBaseRef
is intended to refer to a port on a
submodel. The namespace of the PortSIdRef
value is the set
of identifiers of type PortSId
defined in the submodel, not
the parent model.
SIdRef
): As its name implies, this attribute is used to
refer to a regular identifier (i.e., the value of an 'id'
attribute on some other object), in the case when the reference being
constructed with the SBaseRef
is intended to refer to an object that
does not have a port identifier. The namespace of the SIdRef
value is the set of identifiers of type SId defined in the
submodel, not the parent model.
UnitSIdRef
): This attribute is used to refer to the identifier
of a UnitDefinition
object. The namespace of the UnitSIdRef
value is the set of unit identifiers defined in the submodel, not the
parent model. (Note that even though this attribute is of type UnitSIdRef
,
the reserved unit identifiers that are defined by SBML Level 3 (see
Section 3.1.10 of the core specification) are
*not* permitted as values of 'unitRef'. Reserved unit
identifiers may not be replaced or deleted.)
IDREF
): This attribute is used to refer to a 'metaid'
attribute value on some other object, in the case when the reference
being constructed with the SBaseRef
is intended to refer to an object
that does not have a port identifier. The namespace of the 'metaIdRef'
value is the entire document in which the referenced model resides, but
must refer to a subelement of the referenced model. Since meta identifiers are
optional attributes of SBase
, all SBML objects have the potential to
have a meta identifier value.
An SBaseRef
object may have up to one subcomponent named 'sBaseRef', of
type SBaseRef
. This permits recursive structures to be constructed so
that objects inside submodels can be referenced.
The form of such recursive references must be as follows. The
highest-level SBaseRef
object of such a chain (which will necessarily
be an object of class Port
, Deletion
, ReplacedElement
or ReplacedBy
,
because they are the only classes derived from the class SBaseRef
) must
refer to a Submodel
object in the containing model. All child
SBaseRef
objects in the chain must refer to components inside the
Model
instance to which the Submodel
refers.
Constructor and Description |
---|
SBaseRef()
Creates a new
SBaseRef with the given level, version, and package version. |
SBaseRef(CompPkgNamespaces compns)
Creates a new
SBaseRef with the given CompPkgNamespaces object. |
SBaseRef(long level)
Creates a new
SBaseRef with the given level, version, and package version. |
SBaseRef(long level,
long version)
Creates a new
SBaseRef with the given level, version, and package version. |
SBaseRef(long level,
long version,
long pkgVersion)
Creates a new
SBaseRef with the given level, version, and package version. |
SBaseRef(SBaseRef source)
Copy constructor.
|
Modifier and Type | Method and Description |
---|---|
void |
clearReferencedElement()
Removes the saved referenced element, if it had been saved earlier.
|
SBase |
cloneObject()
Creates and returns a deep copy of this
SBaseRef object. |
void |
connectToChild()   |
SBaseRef |
createSBaseRef()
|
void |
delete()
Explicitly deletes the underlying native object.
|
SBase |
getElementByMetaId(java.lang.String metaid)
Returns the first child element it can find with the given
metaid , or
itself if it has the given metaid , or null if no such object is found. |
SBase |
getElementBySId(java.lang.String id)
Returns the first child element found that has the given
id in the
model-wide SId namespace, or null if no such object is found. |
java.lang.String |
getElementName()
Returns the XML element name of
this SBML object.
|
java.lang.String |
getIdRef()
Returns the value of the 'idRef' attribute of this
SBaseRef . |
java.lang.String |
getMetaIdRef()
Returns the value of the 'metaIdRef' attribute of this
SBaseRef . |
int |
getNumReferents()
Returns how many elements are being referred to by this
SBaseRef . |
java.lang.String |
getPortRef()
Returns the value of the 'portRef' attribute of this
SBaseRef . |
SBase |
getReferencedElement()
Returns the object pointed to by this element.
|
SBase |
getReferencedElementFrom(Model model)
Examines the referenced
Model for the referenced object, and returns it, if found. |
SBaseRef |
getSBaseRef()
Get the child sBaseRef of this sBaseRef.
|
int |
getTypeCode()
Returns the libSBML type code of this object instance.
|
java.lang.String |
getUnitRef()
Returns the value of the 'unitRef' attribute of this
SBaseRef . |
boolean |
hasRequiredAttributes()
Returns
true if getNumReferents() is exactly 1. |
boolean |
isSetIdRef()
Predicate returning
true or false depending on whether this
SBaseRef 's 'idRef' attribute has been set. |
boolean |
isSetMetaIdRef()
Predicate returning
true or false depending on whether this
SBaseRef 's 'metaIdRef' attribute has been set. |
boolean |
isSetPortRef()
Predicate returning
true or false depending on whether this
SBaseRef 's 'portRef' attribute has been set. |
boolean |
isSetSBaseRef()
Predicate for testing whether the sBaseRef for this
SBaseRef is set. |
boolean |
isSetUnitRef()
Predicate returning
true or false depending on whether this
SBaseRef 's 'unitRef' attribute has been set. |
int |
performDeletion()
DEPRECATED FUNCTION: DO NOT USE
|
int |
removeFromParentAndDelete()
|
void |
renameSIdRefs(java.lang.String oldid,
java.lang.String newid)
Replaces all uses of a given
SIdRef type attribute value with another
value. |
int |
saveReferencedElement()
|
int |
setIdRef(java.lang.String id)
Sets the value of the 'idRef' attribute of this
SBaseRef . |
int |
setMetaIdRef(java.lang.String id)
Sets the value of the 'metaIdRef' attribute of this
SBaseRef . |
int |
setPortRef(java.lang.String id)
Sets the value of the 'portRef' attribute of this
SBaseRef . |
int |
setSBaseRef(SBaseRef sBaseRef)
|
int |
setUnitRef(java.lang.String id)
Sets the value of the 'unitRef' attribute of this
SBaseRef . |
int |
unsetIdRef()
Unsets the value of the 'idRef' attribute of this
SBaseRef . |
int |
unsetMetaIdRef()
Unsets the value of the 'metaIdRef' attribute of this
SBaseRef . |
int |
unsetPortRef()
Unsets the value of the 'portRef' attribute of this
SBaseRef . |
int |
unsetSBaseRef()
|
int |
unsetUnitRef()
Unsets the value of the 'unitRef' attribute of this
SBaseRef . |
getPackageName, getPackageURI, getPackageVersion, getParentModel
addCVTerm, addCVTerm, appendAnnotation, appendAnnotation, appendNotes, appendNotes, deleteDisabledPlugins, deleteDisabledPlugins, disablePackage, enablePackage, equals, getAncestorOfType, getAncestorOfType, getAnnotation, getAnnotationString, getColumn, getCVTerm, getCVTerms, getDisabledPlugin, getId, getIdAttribute, getLevel, getLine, getListOfAllElements, getListOfAllElements, getListOfAllElementsFromPlugins, getListOfAllElementsFromPlugins, getMetaId, getModel, getModelHistory, getName, getNamespaces, getNotes, getNotesString, getNumCVTerms, getNumDisabledPlugins, getNumPlugins, getPackageCoreVersion, getParentSBMLObject, getPlugin, getPlugin, getPrefix, getResourceBiologicalQualifier, getResourceModelQualifier, getSBMLDocument, getSBOTerm, getSBOTermAsURL, getSBOTermID, getURI, getVersion, hashCode, hasValidLevelVersionNamespaceCombination, isPackageEnabled, isPackageURIEnabled, isPkgEnabled, isPkgURIEnabled, isSetAnnotation, isSetId, isSetIdAttribute, isSetMetaId, isSetModelHistory, isSetName, isSetNotes, isSetSBOTerm, isSetUserData, matchesRequiredSBMLNamespacesForAddition, matchesSBMLNamespaces, removeTopLevelAnnotationElement, removeTopLevelAnnotationElement, removeTopLevelAnnotationElement, renameMetaIdRefs, renameUnitSIdRefs, replaceTopLevelAnnotationElement, replaceTopLevelAnnotationElement, setAnnotation, setAnnotation, setId, setIdAttribute, setMetaId, setModelHistory, setName, setNamespaces, setNotes, setNotes, setNotes, setSBOTerm, setSBOTerm, toSBML, toXMLNode, unsetAnnotation, unsetCVTerms, unsetId, unsetIdAttribute, unsetMetaId, unsetModelHistory, unsetName, unsetNotes, unsetSBOTerm, unsetUserData
public SBaseRef(long level, long version, long pkgVersion) throws SBMLConstructorException
SBaseRef
with the given level, version, and package version.
level
- the SBML Level.version
- the Version within the SBML Level.pkgVersion
- the version of the package.
SBMLConstructorException
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. For packages, this means that the
parent object to which this package element is being added must have
been created with the package namespace, or that the package namespace
was added to it, even if that parent is not a package object itself.public SBaseRef(long level, long version) throws SBMLConstructorException
SBaseRef
with the given level, version, and package version.
level
- the SBML Level.version
- the Version within the SBML Level.pkgVersion
- the version of the package.
SBMLConstructorException
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. For packages, this means that the
parent object to which this package element is being added must have
been created with the package namespace, or that the package namespace
was added to it, even if that parent is not a package object itself.public SBaseRef(long level) throws SBMLConstructorException
SBaseRef
with the given level, version, and package version.
level
- the SBML Level.version
- the Version within the SBML Level.pkgVersion
- the version of the package.
SBMLConstructorException
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. For packages, this means that the
parent object to which this package element is being added must have
been created with the package namespace, or that the package namespace
was added to it, even if that parent is not a package object itself.public SBaseRef() throws SBMLConstructorException
SBaseRef
with the given level, version, and package version.
level
- the SBML Level.version
- the Version within the SBML Level.pkgVersion
- the version of the package.
SBMLConstructorException
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. For packages, this means that the
parent object to which this package element is being added must have
been created with the package namespace, or that the package namespace
was added to it, even if that parent is not a package object itself.public SBaseRef(CompPkgNamespaces compns) throws SBMLConstructorException
SBaseRef
with the given CompPkgNamespaces
object.
The package namespaces object used in this constructor is derived from a
SBMLNamespaces
object, which encapsulates SBML Level/Version/namespaces
information. It is used to communicate the SBML Level, Version, and
package version and name information used in addition to SBML Level 3 Core. A
common approach to using libSBML's SBMLNamespaces
facilities is to create an
package namespace object somewhere in a program once, then hand that object
as needed to object constructors of that package that accept it as and
argument, such as this one.
compns
- the CompPkgNamespaces
object.
SBMLConstructorException
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. For packages, this means that the
parent object to which this package element is being added must have
been created with the package namespace, or that the package namespace
was added to it, even if that parent is not a package object itself.public SBaseRef(SBaseRef source) throws SBMLConstructorException
source
- the 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 SBaseRef.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 SBaseRef.delete()
themselves.
public SBase cloneObject()
SBaseRef
object.
cloneObject
 in class SBase
SBaseRef
object.public SBase getElementBySId(java.lang.String id)
id
in the
model-wide SId namespace, or null
if no such object is found.
getElementBySId
 in class SBase
id
- string representing the id of the object to find.
SBase
element with the given id
.public SBase getElementByMetaId(java.lang.String metaid)
metaid
, or
itself if it has the given metaid
, or null
if no such object is found.
getElementByMetaId
 in class SBase
metaid
- string representing the metaid of the object to find.
SBase
element with the given metaid
.public java.lang.String getMetaIdRef()
SBaseRef
.
SBaseRef
.public boolean isSetMetaIdRef()
true
or false
depending on whether this
SBaseRef
's 'metaIdRef' attribute has been set.
true
if this SBaseRef
's 'metaIdRef' attribute has been set,
otherwise false
is returned.public int setMetaIdRef(java.lang.String id)
SBaseRef
.
This method fails if the id is not a valid syntax for an IDREF
(LIBSBML_INVALID_ATTRIBUTE_VALUE
), or if the SBaseRef
already
points to an element of the submodel using a different interface (LIBSBML_OPERATION_FAILED
). An sBaseRef must use exactly one
method to point to a submodel element.
public int unsetMetaIdRef()
SBaseRef
.
public java.lang.String getPortRef()
SBaseRef
.
SBaseRef
.public boolean isSetPortRef()
true
or false
depending on whether this
SBaseRef
's 'portRef' attribute has been set.
true
if this SBaseRef
's 'portRef' attribute has been set,
otherwise false
is returned.public int setPortRef(java.lang.String id)
SBaseRef
. Fails if
the id is not a valid syntax for a PortSIdRef
(LIBSBML_INVALID_ATTRIBUTE_VALUE
), or if the SBaseRef
already
points to an element of the submodel using a different interface (LIBSBML_OPERATION_FAILED
). An SBaseRef
must use exactly one
method to point to a submodel element.
public int unsetPortRef()
SBaseRef
.
public java.lang.String getIdRef()
SBaseRef
.
SBaseRef
.public boolean isSetIdRef()
true
or false
depending on whether this
SBaseRef
's 'idRef' attribute has been set.
true
if this SBaseRef
's 'idRef' attribute has been set,
otherwise false
is returned.public int setIdRef(java.lang.String id)
SBaseRef
.
This method fails if the id is not a valid syntax for an SIdRef
(LIBSBML_INVALID_ATTRIBUTE_VALUE
), or if the SBaseRef
already
points to an element of the submodel using a different interface (LIBSBML_OPERATION_FAILED
). A sBaseRef must use exactly one
method to point to a submodel element.
public int unsetIdRef()
SBaseRef
.
The identifier given by an object's 'id' attribute value
is used to identify the object within the SBML model definition.
Other objects can refer to the component using this identifier. The
data type of 'id' is always SId
or a type derived
from that, such as UnitSId
, depending on the object in
question. All data types are defined as follows:
letter .= 'a'..'z','A'..'Z' digit .= '0'..'9' idChar .= letter | digit | '_' SId .= ( letter | '_' ) idChar*
The characters (
and )
are used for grouping, the
character *
'zero or more times', and the character
|
indicates logical 'or'. The equality of SBML identifiers is
determined by an exact character sequence match i.e., comparisons must be
performed in a case-sensitive manner. This applies to all uses of SId
,
SIdRef
, and derived types.
In SBML Level 3 Version 2, the 'id' and 'name' attributes were
moved to SBase
directly, instead of being defined individually for many
(but not all) objects. Libsbml has for a long time provided functions
defined on SBase
itself to get, set, check, and unset those attributes, which
would fail or otherwise return empty strings if executed on any object
for which those attributes were not defined. Now that all SBase
objects
define those attributes, those functions now succeed for any object with
the appropriate level and version.
The exception to this rule is that for InitialAssignment
, EventAssignment
,
AssignmentRule
, and RateRule
objects, the getId() function and the isSetId()
functions (though not the setId() or unsetId() functions) would instead
reference the value of the 'variable' attribute (for the rules and event
assignments) or the 'symbol' attribute (for initial assignments).
The AlgebraicRule
fell into this category as well, though because it
contained neither a 'variable' nor a 'symbol' attribute, getId() would
always return an empty string, and isSetId() would always return false.
For this reason, four new functions are now provided
(getIdAttribute(), setIdAttribute(String),
isSetIdAttribute(), and unsetIdAttribute()) that will always
act on the actual 'id' attribute, regardless of the object's type. The
new functions should be used instead of the old ones unless the old behavior
is somehow necessary.
Regardless of the level and version of the SBML, these functions allow client applications to use more generalized code in some situations (for instance, when manipulating objects that are all known to have identifiers). If the object in question does not posess an 'id' attribute according to the SBML specification for the Level and Version in use, libSBML will not allow the identifier to be set, nor will it read or write 'id' attributes for those objects.
SBase.getIdAttribute()
,
SBase.setIdAttribute(String sid)
,
SBase.isSetIdAttribute()
,
SBase.unsetIdAttribute()
public java.lang.String getUnitRef()
SBaseRef
.
SBaseRef
.public boolean isSetUnitRef()
true
or false
depending on whether this
SBaseRef
's 'unitRef' attribute has been set.
true
if this SBaseRef
's 'unitRef' attribute has been set,
otherwise false
is returned.public int setUnitRef(java.lang.String id)
SBaseRef
.
This method fails if the id is not a valid syntax for a UnitSIdRef
(LIBSBML_INVALID_ATTRIBUTE_VALUE
), or if the SBaseRef
already
points to an element of the submodel using a different interface (LIBSBML_OPERATION_FAILED
). A sBaseRef must use exactly one
method to point to a submodel element.
public int unsetUnitRef()
SBaseRef
.
public SBaseRef getSBaseRef()
public boolean isSetSBaseRef()
SBaseRef
is set.
true
if the sBaseRef of this SBaseRef
is set, false
otherwise.public int setSBaseRef(SBaseRef sBaseRef)
SBaseRef
to a copy of the given
SBaseRef
object instance.
This method fails if the added sBaseRef does not match the level/version/package of the parent object or if the added sBaseRef cannot be copied.
sBaseRef
- the SBaseRef
object instance to use.
public SBaseRef createSBaseRef()
SBaseRef
object instance.public int unsetSBaseRef()
public int getNumReferents()
SBaseRef
. A
valid SBaseRef
will have exactly one. Possible referents are portRef,
idRef, unitRef, and metaIdRef.
public boolean hasRequiredAttributes()
true
if getNumReferents() is exactly 1.
hasRequiredAttributes
 in class SBase
public void renameSIdRefs(java.lang.String oldid, java.lang.String newid)
Replaces all uses of a given SIdRef
type attribute value with another
value.
In SBML, object identifiers are of a data type called SId
.
In SBML Level 3, an explicit data type called SIdRef
was
introduced for attribute values that refer to SId
values in
previous Levels of SBML, this data type did not exist and attributes were
simply described to as 'referring to an identifier', but the effective
data type was the same as SIdRef
in Level 3. These and
other methods of libSBML refer to the type SIdRef
for all
Levels of SBML, even if the corresponding SBML specification did not
explicitly name the data type.
This method works by looking at all attributes and (if appropriate)
mathematical formulas in MathML content, comparing the referenced
identifiers to the value of oldid
. If any matches are found, the
matching values are replaced with newid
. The method does not
descend into child elements.
renameSIdRefs
 in class SBase
oldid
- the old identifier.newid
- the new identifier.public java.lang.String getElementName()
getElementName
 in class SBase
public int getTypeCode()
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
method on the object.
SBase.getPackageName()
getTypeCode
 in class SBase
SBML_COMP_SBASEREF
.
SBaseRef.getElementName()
,
CompBase.getPackageName()
public void connectToChild()
connectToChild
 in class SBase
public SBase getReferencedElementFrom(Model model)
Model
for the referenced object, and returns it, if found.
public int saveReferencedElement()
Model
it needs to
point to, calling 'saveReferencedElement' on its parent (which will also
be a SBaseRef
or one of its subclasses), and the storing the result.
public SBase getReferencedElement()
public void clearReferencedElement()
public int performDeletion()
Deletes the referenced object,
plus any other elements that element points to through ReplacedElement
or ReplacedBy
children. Instead of calling this function directly, use
'CompModelPlugin.instantiateSubmodels' instead, which deals with all the
intricacies of replacements and deletions, and gives you access to the
non-flattened hierarchical form of the model.
public int removeFromParentAndDelete()
SBaseRef
's parent, which can either be a List or can be
another SBaseRef
, and tells it to remove this.
removeFromParentAndDelete
 in class SBase