Constraint (LibSBML Java API)

java.lang.Object
- org.sbml.libsbml.SBase
- - org.sbml.libsbml.Constraint

```
public class Constraint
extends SBase
```
An SBML constraint, for stating validity assumptions.
The Constraint object class was introduced in SBML Level 2 Version 2 as a mechanism for stating the assumptions under which a model is designed to operate. The constraints are statements about permissible values of different quantities in a model. Constraints are not used to compute dynamical values for simulation or analysis, but rather, they serve an advisory role for simulation/analysis tools.
SBML's Constraint object class has one required attribute, 'id', to give the parameter a unique identifier by which other parts of an SBML model definition can refer to it. A Constraint object can also have an optional 'name' attribute of type string. Identifiers and names must be used according to the guidelines described in the SBML specification (e.g., Section 3.3 in the Level 2 Version 4 specification).
Constraint has one required subelement, 'math', containing a MathML formula defining the condition of the constraint. This formula must return a boolean value of true when the model is a valid state. The formula can be an arbitrary expression referencing the variables and other entities in an SBML model. The evaluation of 'math' and behavior of constraints are described in more detail below.
A Constraint structure also has an optional subelement called 'message'. This can contain a message in XHTML format that may be displayed to the user when the condition of the formula in the 'math' subelement evaluates to a value of false. Software tools are not required to display the message, but it is recommended that they do so as a matter of best practice. The XHTML content within a 'message' subelement must follow the same restrictions as for the 'notes' element on SBase described in in the SBML Level 2 specification please consult the SBML specification document corresponding to the SBML Level and Version of your model for more information about the requirements for 'notes' content.
Constraint was introduced in SBML Level 2 Version 2. It is not available in earlier versions of Level 2 nor in any version of Level 1.

Semantics of Constraints

In the context of a simulation, a Constraint has effect at all times t ≥ 0. Each Constraint's 'math' subelement is first evaluated after any InitialAssignment definitions in a model at t = 0 and can conceivably trigger at that point. (In other words, a simulation could fail a constraint immediately.)
Constraint structures cannot and should not be used to compute the dynamical behavior of a model as part of, for example, simulation. Constraints may be used as input to non-dynamical analysis, for instance by expressing flux constraints for flux balance analysis.
The results of a simulation of a model containing a constraint are invalid from any simulation time at and after a point when the function given by the 'math' subelement returns a value of false. Invalid simulation results do not make a prediction of the behavior of the biochemical reaction network represented by the model. The precise behavior of simulation tools is left undefined with respect to constraints. If invalid results are detected with respect to a given constraint, the 'message' subelement may optionally be displayed to the user. The simulation tool may also halt the simulation or clearly delimit in output data the simulation time point at which the simulation results become invalid.
SBML does not impose restrictions on duplicate Constraint definitions or the order of evaluation of Constraint objects in a model. It is possible for a model to define multiple constraints all with the same mathematical expression. Since the failure of any constraint indicates that the model simulation has entered an invalid state, a system is not required to attempt to detect whether other constraints in the model have failed once any one constraint has failed.

Constructor Summary

Constructors
Constructor and Description
`Constraint(Constraint orig)` Copy constructor creates a copy of this `Constraint`.
`Constraint(long level, long version)` Creates a new `Constraint` using the given SBML `level` and `version` values.
`Constraint(SBMLNamespaces sbmlns)` Creates a new `Constraint` using the given `SBMLNamespaces` object `sbmlns`.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`Constraint`	`cloneObject()` Creates and returns a deep copy of this `Constraint` object.
`void`	`delete()` Explicitly deletes the underlying native object.
`java.lang.String`	`getElementName()` Returns the XML element name of this object, which for `Constraint`, is always `'constraint'.`
`ASTNode`	`getMath()` Get the mathematical expression of this `Constraint`
`XMLNode`	`getMessage()` Get the message, if any, associated with this `Constraint`
`java.lang.String`	`getMessageString()` Get the message string, if any, associated with this `Constraint`
`int`	`getTypeCode()` Returns the libSBML type code for this SBML object.
`boolean`	`hasRequiredElements()` Predicate returning `true` if all the required elements for this `Constraint` object have been set.
`boolean`	`isSetMath()` Predicate returning `true` if a mathematical formula is defined for this `Constraint`.
`boolean`	`isSetMessage()` Predicate returning `true` if a message is defined for this `Constraint`.
`void`	`renameSIdRefs(java.lang.String oldid, java.lang.String newid)` Replaces all uses of a given `SIdRef` type attribute value with another value.
`void`	`renameUnitSIdRefs(java.lang.String oldid, java.lang.String newid)` Replaces all uses of a given `UnitSIdRef` type attribute value with another value.
`int`	`setMath(ASTNode math)` Sets the mathematical expression of this `Constraint` to a copy of the AST given as `math`.
`int`	`setMessage(java.lang.String message)` Sets the message of this `Constraint`.
`int`	`setMessage(java.lang.String message, boolean addXHTMLMarkup)` Sets the message of this `Constraint`.
`int`	`setMessage(XMLNode xhtml)` Sets the message of this `Constraint`.
`int`	`unsetMessage()` Unsets the 'message' subelement of this `Constraint`.

Methods inherited from class org.sbml.libsbml.SBase
addCVTerm, addCVTerm, appendAnnotation, appendAnnotation, appendNotes, appendNotes, connectToChild, deleteDisabledPlugins, deleteDisabledPlugins, disablePackage, enablePackage, equals, getAncestorOfType, getAncestorOfType, getAnnotation, getAnnotationString, getColumn, getCVTerm, getCVTerms, getDisabledPlugin, getElementByMetaId, getElementBySId, 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, removeFromParentAndDelete, removeTopLevelAnnotationElement, removeTopLevelAnnotationElement, removeTopLevelAnnotationElement, renameMetaIdRefs, replaceTopLevelAnnotationElement, replaceTopLevelAnnotationElement, setAnnotation, setAnnotation, setMetaId, setModelHistory, setNamespaces, setNotes, setNotes, setNotes, setSBOTerm, setSBOTerm, toSBML, toXMLNode, unsetAnnotation, unsetCVTerms, unsetId, unsetMetaId, unsetModelHistory, unsetName, unsetNotes, unsetSBOTerm, unsetUserData

Methods inherited from class java.lang.Object
getClass, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - Constraint
```
public Constraint(long level,
                  long version)
           throws SBMLConstructorException
```
    Creates a new Constraint using the given SBML level and version values.
    
    Parameters:
    
    level - a long integer, the SBML Level to assign to this Constraint
    
    version - a long integer, the SBML Version to assign to this Constraint
    
    Throws:
    
    SBMLConstructorException - Thrown if the given level and version combination are invalid or if this object is incompatible with the given level and version.
    
    "Note:"
    
    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.
  - Constraint
```
public Constraint(SBMLNamespaces sbmlns)
           throws SBMLConstructorException
```
    Creates a new Constraint using the given SBMLNamespaces object sbmlns.
    
    The SBMLNamespaces object encapsulates SBML Level/Version/namespaces information. It is used to communicate the SBML Level, Version, and (in Level 3) packages used in addition to SBML Level 3 Core. A common approach to using libSBML's SBMLNamespaces facilities is to create an SBMLNamespaces object somewhere in a program once, then hand that object as needed to object constructors that accept SBMLNamespaces as arguments.
    
    Parameters:
    
    sbmlns - an SBMLNamespaces object.
    
    Throws:
    
    SBMLConstructorException - Thrown if the given sbmlns is inconsistent or incompatible with this object.
    
    "Note:"
    
    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.
  - Constraint
```
public Constraint(Constraint orig)
           throws SBMLConstructorException
```
    Copy constructor creates a copy of this Constraint.
    
    Parameters:
    
    orig - the object to copy.
    
    Throws:
    
    SBMLConstructorException
- Method Detail
  - delete
```
public void delete()
```
    Explicitly deletes the underlying native object.
    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 Constraint.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 Constraint.delete() themselves.
    
    Overrides:
    
    delete in class SBase
  - cloneObject
```
public Constraint cloneObject()
```
    Creates and returns a deep copy of this Constraint object.
    
    Overrides:
    
    cloneObject in class SBase
    
    Returns:
    
    the (deep) copy of this Constraint object.
  - getMessage
```
public XMLNode getMessage()
```
    Get the message, if any, associated with this Constraint
    
    Returns:
    
    the message for this Constraint, as an XMLNode.
  - getMessageString
```
public java.lang.String getMessageString()
```
    Get the message string, if any, associated with this Constraint
    
    Returns:
    
    the message for this Constraint, as a string.
  - getMath
```
public ASTNode getMath()
```
    Get the mathematical expression of this Constraint
    
    Returns:
    
    the math for this Constraint, as an ASTNode.
  - isSetMessage
```
public boolean isSetMessage()
```
    Predicate returning true if a message is defined for this Constraint.
    
    Returns:
    
    true if the message of this Constraint is set, false otherwise.
  - isSetMath
```
public boolean isSetMath()
```
    Predicate returning true if a mathematical formula is defined for this Constraint.
    
    Returns:
    
    true if the 'math' subelement for this Constraint is set, false otherwise.
  - setMessage
```
public int setMessage(XMLNode xhtml)
```
    Sets the message of this Constraint.
    The XMLNode tree passed in xhtml is copied.
    Parameters:
    
    xhtml - an XML tree containing XHTML content.
    
    Returns:
    integer value indicating success/failure of the function. The possible values returned by this function are:
    
    LIBSBML_OPERATION_SUCCESS
    LIBSBML_INVALID_OBJECT
  - setMessage
```
public int setMessage(java.lang.String message,
                      boolean addXHTMLMarkup)
```
    Sets the message of this Constraint.
    Parameters:
    
    message - an XML string that is to be used as the content of the 'message' subelement of this object
    
    addXHTMLMarkup - a boolean indicating whether to wrap the contents of the message argument with XHTML paragraph (<p>) tags. This is appropriate when the string in message does not already containg the appropriate XHTML markup.
    
    Returns:
    integer value indicating success/failure of the function. The possible values returned by this function are:
    
    LIBSBML_OPERATION_SUCCESS
    LIBSBML_INVALID_OBJECT
  - setMessage
```
public int setMessage(java.lang.String message)
```
    Sets the message of this Constraint.
    Parameters:
    
    message - an XML string that is to be used as the content of the 'message' subelement of this object
    
    addXHTMLMarkup - a boolean indicating whether to wrap the contents of the message argument with XHTML paragraph (<p>) tags. This is appropriate when the string in message does not already containg the appropriate XHTML markup.
    
    Returns:
    integer value indicating success/failure of the function. The possible values returned by this function are:
    
    LIBSBML_OPERATION_SUCCESS
    LIBSBML_INVALID_OBJECT
  - setMath
```
public int setMath(ASTNode math)
```
    Sets the mathematical expression of this Constraint to a copy of the AST given as math.
    Parameters:
    
    math - an ASTNode expression to be assigned as the 'math' subelement of this Constraint
    
    Returns:
    integer value indicating success/failure of the function. The possible values returned by this function are:
    
    LIBSBML_OPERATION_SUCCESS
    LIBSBML_INVALID_OBJECT
  - unsetMessage
```
public int unsetMessage()
```
    Unsets the 'message' subelement of this Constraint.
    Returns:
    integer value indicating success/failure of the function. The possible values returned by this function are:
    
    LIBSBML_OPERATION_SUCCESS
    LIBSBML_OPERATION_FAILED
  - renameSIdRefs
```
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 SIdRefin 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.
    
    Overrides:
    
    renameSIdRefs in class SBase
    
    Parameters:
    
    oldid - the old identifier
    
    newid - the new identifier
  - renameUnitSIdRefs
```
public void renameUnitSIdRefs(java.lang.String oldid,
                              java.lang.String newid)
```
    Replaces all uses of a given UnitSIdRef type attribute value with another value.
    
    In SBML, unit definitions have identifiers of type UnitSId. In SBML Level 3, an explicit data type called UnitSIdRef was introduced for attribute values that refer to UnitSId values in previous Levels of SBML, this data type did not exist and attributes were simply described to as 'referring to a unit identifier', but the effective data type was the same as UnitSIdRef in Level 3. These and other methods of libSBML refer to the type UnitSIdRef 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 unit identifier attribute values (including, if appropriate, inside mathematical formulas), comparing the referenced unit 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.
    
    Overrides:
    
    renameUnitSIdRefs in class SBase
    
    Parameters:
    
    oldid - the old identifier
    
    newid - the new identifier
  - getTypeCode
```
public int getTypeCode()
```
    Returns the libSBML type code for this SBML object.
    
    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.
    
    Overrides:
    
    getTypeCode in class SBase
    
    Returns:
    
    the SBML type code for this object: SBML_CONSTRAINT (default).
    
    See Also:
    
    Constraint.getElementName(), SBase.getPackageName()
    
    "Warning:"
    
    The specific integer values of the possible type codes may be reused by different Level 3 package plug-ins. Thus, to identifiy the correct code, it is necessary to invoke both getTypeCode() and getPackageName().
  - getElementName
```
public java.lang.String getElementName()
```
    Returns the XML element name of this object, which for Constraint, is always 'constraint'.
    
    Overrides:
    
    getElementName in class SBase
    
    Returns:
    
    the name of this element, i.e., 'constraint'.
  - hasRequiredElements
```
public boolean hasRequiredElements()
```
    Predicate returning true if all the required elements for this Constraint object have been set.
    Overrides:
    
    hasRequiredElements in class SBase
    
    Returns:
    
    a boolean value indicating whether all the required elements for this object have been defined.
    
    "Note:"
    The required elements for a Constraint object are:
    
    'math'

Class Constraint

Semantics of Constraints

Constructor Summary

Method Summary

Methods inherited from class org.sbml.libsbml.SBase

Methods inherited from class java.lang.Object

Constructor Detail

Constraint

Constraint

Constraint

Method Detail

delete

cloneObject

getMessage

getMessageString

getMath

isSetMessage

isSetMath

setMessage

setMessage

setMessage

setMath

unsetMessage

renameSIdRefs

renameUnitSIdRefs

getTypeCode

getElementName

hasRequiredElements