public class ReplacedElement extends Replacing
The ReplacedElement
class was introduced by the SBML Level 3 Hierarchical Model Composition (&ldquocomp&rdquo) package to allow submodel elements to be
replaced, but still allow references to those elements to be valid. A
ReplacedElement
object is essentially a pointer to a submodel object that
should be considered 'replaced'. The object holding the ReplacedElement
instance is the one doing the replacing the object pointed to by the
ReplacedElement
object is the object being replaced.
A replacement implies that dependencies involving the replaced object must be updated: all references to the replaced object elsewhere in the model are taken to refer to the replacement object instead. For example, if one species replaces another, then any reference to the original species in mathematical formulas, or lists of reactants or products or modifiers in reactions, or initial assignments, or any other SBML construct, are taken to refer to the replacement species, with its value possibly modified by either this object's 'conversionFactor' attribute or the relevant submodel's conversion factors. Moreover, any annotations that refer to the replaced species' 'metaid' value must be made to refer to the replacement species' 'metaid' value instead and anything else that referred either to an object identifier (i.e., attributes such as the 'id' attribute whose types inherit from the SId primitive data type) or the meta identifier (i.e., the 'metaid' attribute or any other attribute that inherits from the ID primitive data type) must be made to refer to the replacement species object instead.
It is worth noting that local parameters (inside Reaction
objects) pose an
interesting edge case for these rules. In order to determine which element
is pointed to by a <cn>
element within the
<math>
element of a KineticLaw
object, it is necessary
to examine the local parameters of that kinetic law's parent Reaction
object. Whether the <cn>
element is considered to
point to something new, then, depends on whether it pointed to the local
parameter and whether that local parameter was replaced, even if the text
of the element matched the SId value of another element in the model.
Note that local parameters may only effectively be replaced by global
parameters, since references to its SId are only valid from within the
Reaction
element to which it belongs.
When referencing an element within the Submodel
pointed to by the
'submodelRef' attribute (defined in libSBML in the Replacing
class),
any of the four attributes inherited from
SBaseRef
for the purpose may be used (portRef, idRef, unitRef, or
metaIdRef), or a new optional attribute 'deletion' may be used. This
attribute must be the identifier of a Deletion
object in the parent Model
of the ReplacedElement
(i.e., the value of
some Deletion
object's 'id' attribute). When 'deletion' is
set, it means the ReplacedElement
object is actually an annotation to
indicate that the replacement object replaces something deleted
from a submodel. The use of the 'deletion' attribute overrides
the use of the attributes inherited from SBaseRef: instead of using,
e.g., 'portRef' or 'idRef', the ReplacedElement
instance
sets 'deletion' to the identifier of the Deletion
object. In
addition, the referenced Deletion
must be a child of the Submodel
referenced by the 'submodelRef' attribute.
The use of ReplacedElement
objects to refer to deletions has no effect
on the composition of models or the mathematical properties of the
result. It serves instead to help record the decision-making process
that lead to a given model. It can be particularly useful for
visualization purposes, as well as to serve as scaffolding where other
types of annotations can be added using the normal Annotation
subcomponents available on all SBase
objects in SBML.
As with the Submodel
class, it may be that the units of the replaced
element may not match the units of the replacement element. In this case,
the optional 'conversionFactor' attribute may be used. This attribute, if
present, defines how to transform or rescale the replaced object's value
so that it is appropriate for the new contexts in which the object
appears. This attribute takes a value of type SIdRef, and
the value must refer to a Parameter
object instance defined in the
model. This parameter then acts as a conversion factor.
The value of the conversion factor should be defined such that a single
unit of the replaced element multiplied by the conversion factor should
equal a single unit of the replacement element, and the units of the
conversion factor should be commensurate with that transformation. The
referenced Parameter
may be non-constant, particularly if a Species
is
replaced by a Species
with a different 'hasOnlySubstanceUnits'
attribute value, thus changing amount to concentration, or visa versa.
Constructor and Description |
---|
ReplacedElement()
Creates a new
ReplacedElement with the given level, version, and package
version. |
ReplacedElement(CompPkgNamespaces compns)
Creates a new
ReplacedElement with the given CompPkgNamespaces object. |
ReplacedElement(long level)
Creates a new
ReplacedElement with the given level, version, and package
version. |
ReplacedElement(long level,
long version)
Creates a new
ReplacedElement with the given level, version, and package
version. |
ReplacedElement(long level,
long version,
long pkgVersion)
Creates a new
ReplacedElement with the given level, version, and package
version. |
ReplacedElement(ReplacedElement source)
Copy constructor.
|
Modifier and Type | Method and Description |
---|---|
SBase |
cloneObject()
Creates and returns a deep copy of this
ReplacedElement object. |
void |
delete()
Explicitly deletes the underlying native object.
|
java.lang.String |
getConversionFactor()
Returns the value of the 'conversionFactor' attribute of this
ReplacedElement . |
java.lang.String |
getDeletion()
Returns the value of the 'deletion' attribute of this
ReplacedElement . |
java.lang.String |
getElementName()
Returns the XML element name of
this SBML object.
|
int |
getNumReferents()
Returns how many elements are being referred to by this
ReplacedElement . |
SBase |
getReferencedElementFrom(Model model)
Finds the
SBase object this ReplacedElement object points to, if any. |
int |
getTypeCode()
Returns the libSBML type code of this object instance.
|
boolean |
isSetConversionFactor()
Predicate returning
true or false depending on whether this
ReplacedElement 's 'conversionFactor' attribute has been set. |
boolean |
isSetDeletion()
Predicate returning
true or false depending on whether this
SBaseRef 's 'deletion' attribute has been set. |
void |
renameSIdRefs(java.lang.String oldid,
java.lang.String newid)
Replaces all uses of a given
SIdRef type attribute value with another
value. |
int |
setConversionFactor(java.lang.String id)
Sets the value of the 'conversionFactor' attribute of this
ReplacedElement . |
int |
setDeletion(java.lang.String id)
Sets the value of the 'deletion' attribute of this
ReplacedElement . |
int |
unsetConversionFactor()
Unsets the value of the 'conversionFactor' attribute of this
ReplacedElement . |
int |
unsetDeletion()
Unsets the value of the 'deletion' attribute of this
ReplacedElement . |
getSubmodelRef, hasRequiredAttributes, isSetSubmodelRef, performReplacement, saveReferencedElement, setSubmodelRef, unsetSubmodelRef
clearReferencedElement, connectToChild, createSBaseRef, getElementByMetaId, getElementBySId, getIdRef, getMetaIdRef, getPortRef, getReferencedElement, getSBaseRef, getUnitRef, isSetIdRef, isSetMetaIdRef, isSetPortRef, isSetSBaseRef, isSetUnitRef, performDeletion, removeFromParentAndDelete, setIdRef, setMetaIdRef, setPortRef, setSBaseRef, setUnitRef, unsetIdRef, unsetMetaIdRef, unsetPortRef, unsetSBaseRef, unsetUnitRef
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, getObjectVersion, 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 ReplacedElement(long level, long version, long pkgVersion) throws SBMLConstructorException
ReplacedElement
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 ReplacedElement(long level, long version) throws SBMLConstructorException
ReplacedElement
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 ReplacedElement(long level) throws SBMLConstructorException
ReplacedElement
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 ReplacedElement() throws SBMLConstructorException
ReplacedElement
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 ReplacedElement(CompPkgNamespaces compns) throws SBMLConstructorException
ReplacedElement
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 ReplacedElement(ReplacedElement 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 ReplacedElement.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 ReplacedElement.delete()
themselves.
public SBase cloneObject()
ReplacedElement
object.
cloneObject
 in class SBaseRef
ReplacedElement
object.public java.lang.String getConversionFactor()
ReplacedElement
.
ReplacedElement
.public boolean isSetConversionFactor()
true
or false
depending on whether this
ReplacedElement
's 'conversionFactor' attribute has been set.
true
if this ReplacedElement
's 'conversionFactor' attribute has been set,
otherwise false
is returned.public int setConversionFactor(java.lang.String id)
ReplacedElement
.
public int unsetConversionFactor()
ReplacedElement
.
public java.lang.String getDeletion()
ReplacedElement
.
ReplacedElement
.public boolean isSetDeletion()
true
or false
depending on whether this
SBaseRef
's 'deletion' attribute has been set.
true
if this ReplacedElement
's 'deletion' attribute has been set,
otherwise false
is returned.public int setDeletion(java.lang.String id)
ReplacedElement
.
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 ReplacedElement
must use exactly
one method to point to a submodel element: deletion, port, idRef,
unitRef, or metaIdRef.
public int unsetDeletion()
ReplacedElement
.
public java.lang.String getElementName()
getElementName
 in class SBaseRef
public int getNumReferents()
ReplacedElement
. A
valid ReplacedElement
will have exactly one. Possible referents are deletion,
port, idRef, unitRef, and metaIdRef.
getNumReferents
 in class SBaseRef
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 getPackageName()
method on the object.
getTypeCode
 in class SBaseRef
SBML_COMP_REPLACEDELEMENT
.
ReplacedElement.getElementName()
,
CompBase.getPackageName()
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 Replacing
oldid
- the old identifier.newid
- the new identifier.public SBase getReferencedElementFrom(Model model)
SBase
object this ReplacedElement
object points to, if any.getReferencedElementFrom
 in class SBaseRef
model
- the Model
in which to look for the object referenced by
this SBaseRef
.
Model
to which this SBaseRef
refers. If this object references an object in a Submodel
, the returned
object will be in the instantiated Model
in that Submodel
.