FunctionDefinition (LibSBML Java API)

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

```
public class FunctionDefinition
extends SBase
```
A user-defined function in an SBML model.
The FunctionDefinition structure associates an identifier with a function definition. This identifier can then be used as the function called in subsequent MathML content elsewhere in an SBML model.
FunctionDefinition has one required attribute, 'id', to give the function a unique identifier by which other parts of an SBML model definition can refer to it. A FunctionDefinition instance 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).
FunctionDefinition has a required 'math' subelement containing a MathML expression defining the function body. The content of this element can only be a MathML 'lambda' element. The 'lambda' element must begin with zero or more 'bvar' elements, followed by any other of the elements in the MathML subset allowed in SBML Level 2 except 'lambda' (i.e., a 'lambda' element cannot contain another 'lambda' element). This is the only place in SBML where a 'lambda' element can be used. The function defined by a FunctionDefinition is only available for use in other MathML elements that follow the FunctionDefinition definition in the model. (These restrictions prevent recursive and mutually-recursive functions from being expressed.)
A further restriction on the content of 'math' is that it cannot contain references to variables other than the variables declared to the 'lambda' itself. That is, the contents of MathML 'ci' elements inside the body of the 'lambda' can only be the variables declared by its 'bvar' elements, or the identifiers of other FunctionDefinition instances in the model. This means must be written so that all variables or parameters used in the MathML content are passed to them via their function parameters. In SBML Level 2, this restriction applies also to the MathML csymbol elements for time and delay in SBML Level 3, it additionally applies to the csymbol element for avogadro.

"Note:"

Function definitions (also informally known as user-defined functions) were introduced in SBML Level 2. They have purposefully limited capabilities. A function cannot reference parameters or other model quantities outside of itself values must be passed as parameters to the function. Moreover, recursive and mutually-recursive functions are not permitted. The purpose of these limitations is to balance power against complexity of implementation. With the restrictions as they are, function definitions could be implemented as textual substitutions&mdashthey are simply macros. Software implementations therefore do not need the full function-definition machinery typically associated with programming languages.

Another important point to note is FunctionDefinition does not have a separate attribute for defining the units of the value returned by the function. The units associated with the function's return value, when the function is called from within MathML expressions elsewhere in SBML, are simply the overall units of the expression in FunctionDefinition's 'math' subelement when applied to the arguments supplied in the call to the function. Ascertaining these units requires performing dimensional analysis on the expression. (Readers may wonder why there is no attribute. The reason is that having a separate attribute for declaring the units would not only be redundant, but also lead to the potential for having conflicting information. In the case of a conflict between the declared units and those of the value actually returned by the function, the only logical resolution rule would be to assume that the correct units are those of the expression anyway.)

Constructor Summary

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

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`FunctionDefinition`	`cloneObject()` Creates and returns a deep copy of this `FunctionDefinition` object.
`void`	`delete()` Explicitly deletes the underlying native object.
`ASTNode`	`getArgument(long n)` Get the `n`th argument to this function.
`ASTNode`	`getArgument(java.lang.String name)` Get the argument named `name` to this `FunctionDefinition`.
`ASTNode`	`getBody()` Get the mathematical expression that is the body of this `FunctionDefinition` object.
`java.lang.String`	`getElementName()` Returns the XML element name of this object, which for `FunctionDefinition`, is always `'functionDefinition'.`
`java.lang.String`	`getId()` Returns the value of the 'id' attribute of this `FunctionDefinition`.
`ASTNode`	`getMath()` Get the mathematical formula of this `FunctionDefinition`.
`java.lang.String`	`getName()` Returns the value of the 'name' attribute of this `FunctionDefinition`.
`long`	`getNumArguments()` Get the number of arguments (bound variables) taken by this `FunctionDefinition`.
`int`	`getTypeCode()` Returns the libSBML type code for this SBML object.
`boolean`	`hasRequiredAttributes()` Predicate returning `true` if all the required attributes for this `FunctionDefinition` object have been set.
`boolean`	`hasRequiredElements()` Predicate returning `true` if all the required elements for this `FunctionDefinition` object have been set.
`boolean`	`isSetBody()` Predicate returning `true` if the body of this `FunctionDefinition` has set.
`boolean`	`isSetId()` Predicate returning `true` if this `FunctionDefinition`'s 'id' attribute is set.
`boolean`	`isSetMath()` Predicate returning `true` if this `FunctionDefinition`'s 'math' subelement contains a value.
`boolean`	`isSetName()` Predicate returning `true` if this `FunctionDefinition`'s 'name' attribute is set.
`void`	`renameUnitSIdRefs(java.lang.String oldid, java.lang.String newid)` Renames all the `UnitSIdRef` attributes on this element.
`int`	`setId(java.lang.String sid)` Sets the value of the 'id' attribute of this `FunctionDefinition`.
`int`	`setMath(ASTNode math)` Sets the 'math' subelement of this `FunctionDefinition` to the Abstract Syntax Tree given in `math`.
`int`	`setName(java.lang.String name)` Sets the value of the 'name' attribute of this `FunctionDefinition`.
`int`	`unsetName()` Unsets the value of the 'name' attribute of this `FunctionDefinition`.

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, renameSIdRefs, replaceTopLevelAnnotationElement, replaceTopLevelAnnotationElement, setAnnotation, setAnnotation, setMetaId, setModelHistory, setNamespaces, setNotes, setNotes, setNotes, setSBOTerm, setSBOTerm, toSBML, toXMLNode, unsetAnnotation, unsetCVTerms, unsetId, unsetMetaId, unsetModelHistory, unsetNotes, unsetSBOTerm, unsetUserData

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

- Constructor Detail
  - FunctionDefinition
```
public FunctionDefinition(long level,
                          long version)
                   throws SBMLConstructorException
```
    Creates a new FunctionDefinition using the given SBML level and version values.
    
    Parameters:
    
    level - a long integer, the SBML Level to assign to this FunctionDefinition
    
    version - a long integer, the SBML Version to assign to this FunctionDefinition
    
    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.
  - FunctionDefinition
```
public FunctionDefinition(SBMLNamespaces sbmlns)
                   throws SBMLConstructorException
```
    Creates a new FunctionDefinition 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.
  - FunctionDefinition
```
public FunctionDefinition(FunctionDefinition orig)
                   throws SBMLConstructorException
```
    Copy constructor creates a copy of this FunctionDefinition.
    
    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 FunctionDefinition.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 FunctionDefinition.delete() themselves.
    
    Overrides:
    
    delete in class SBase
  - cloneObject
```
public FunctionDefinition cloneObject()
```
    Creates and returns a deep copy of this FunctionDefinition object.
    
    Overrides:
    
    cloneObject in class SBase
    
    Returns:
    
    the (deep) copy of this FunctionDefinition object.
  - getId
```
public java.lang.String getId()
```
    Returns the value of the 'id' attribute of this FunctionDefinition.
    
    Overrides:
    
    getId in class SBase
    
    Returns:
    
    the id of this FunctionDefinition.
  - getName
```
public java.lang.String getName()
```
    Returns the value of the 'name' attribute of this FunctionDefinition.
    
    Overrides:
    
    getName in class SBase
    
    Returns:
    
    the name of this FunctionDefinition.
  - getMath
```
public ASTNode getMath()
```
    Get the mathematical formula of this FunctionDefinition.
    
    Returns:
    
    an ASTNode, the value of the 'math' subelement of this FunctionDefinition
  - isSetId
```
public boolean isSetId()
```
    Predicate returning true if this FunctionDefinition's 'id' attribute is set.
    
    Overrides:
    
    isSetId in class SBase
    
    Returns:
    
    true if the 'id' attribute of this FunctionDefinition is set, false otherwise.
  - isSetName
```
public boolean isSetName()
```
    Predicate returning true if this FunctionDefinition's 'name' attribute is set.
    
    Overrides:
    
    isSetName in class SBase
    
    Returns:
    
    true if the 'name' attribute of this FunctionDefinition is set, false otherwise.
  - isSetMath
```
public boolean isSetMath()
```
    Predicate returning true if this FunctionDefinition's 'math' subelement contains a value.
    
    Returns:
    
    true if the 'math' for this FunctionDefinition is set, false otherwise.
  - setId
```
public int setId(java.lang.String sid)
```
    Sets the value of the 'id' attribute of this FunctionDefinition.
    The string sid is copied.
    
    SBML has strict requirements for the syntax of identifiers, that is, the values of the 'id' attribute present on most types of SBML objects. The following is a summary of the definition of the SBML identifier type SId, which defines the permitted syntax of identifiers. We express the syntax using an extended form of BNF notation:
```
 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. In addition, there are a few conditions for the uniqueness of identifiers in an SBML model. Please consult the SBML specifications for the exact details of the uniqueness requirements.
    Overrides:
    
    setId in class SBase
    
    Parameters:
    
    sid - the string to use as the identifier of this FunctionDefinition
    
    Returns:
    integer value indicating success/failure of the function. The possible values returned by this function are:
    
    LIBSBML_OPERATION_SUCCESS
    LIBSBML_INVALID_ATTRIBUTE_VALUE
  - setName
```
public int setName(java.lang.String name)
```
    Sets the value of the 'name' attribute of this FunctionDefinition.
    The string in name is copied.
    Overrides:
    
    setName in class SBase
    
    Parameters:
    
    name - the new name for the FunctionDefinition
    
    Returns:
    integer value indicating success/failure of the function. The possible values returned by this function are:
    
    LIBSBML_OPERATION_SUCCESS
    LIBSBML_INVALID_ATTRIBUTE_VALUE
  - setMath
```
public int setMath(ASTNode math)
```
    Sets the 'math' subelement of this FunctionDefinition to the Abstract Syntax Tree given in math.
    Parameters:
    
    math - an AST containing the mathematical expression to be used as the formula for this FunctionDefinition.
    
    Returns:
    integer value indicating success/failure of the function. The possible values returned by this function are:
    
    LIBSBML_OPERATION_SUCCESS
    LIBSBML_INVALID_OBJECT
  - unsetName
```
public int unsetName()
```
    Unsets the value of the 'name' attribute of this FunctionDefinition.
    Overrides:
    
    unsetName in class SBase
    
    Returns:
    integer value indicating success/failure of the function. The possible values returned by this function are:
    
    LIBSBML_OPERATION_SUCCESS
    LIBSBML_OPERATION_FAILED
  - getArgument
```
public ASTNode getArgument(long n)
```
    Get the nth argument to this function.
    Callers should first find out the number of arguments to the function by calling getNumArguments().
    
    Parameters:
    
    n - an integer index for the argument sought.
    
    Returns:
    
    the nth argument (bound variable) passed to this FunctionDefinition.
    
    See Also:
    
    FunctionDefinition.getNumArguments()
  - getArgument
```
public ASTNode getArgument(java.lang.String name)
```
    Get the argument named name to this FunctionDefinition.
    
    Parameters:
    
    name - the exact name (case-sensitive) of the sought-after argument
    
    Returns:
    
    the argument (bound variable) having the given name, or null if no such argument exists.
  - getBody
```
public ASTNode getBody()
```
    Get the mathematical expression that is the body of this FunctionDefinition object.
    
    Returns:
    
    the body of this FunctionDefinition as an Abstract Syntax Tree, or null if no body is defined.
  - isSetBody
```
public boolean isSetBody()
```
    Predicate returning true if the body of this FunctionDefinition has set.
    
    Returns:
    
    true if the body of this FunctionDefinition is set, false otherwise.
  - getNumArguments
```
public long getNumArguments()
```
    Get the number of arguments (bound variables) taken by this FunctionDefinition.
    
    Returns:
    
    the number of arguments (bound variables) that must be passed to this FunctionDefinition.
  - 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_FUNCTION_DEFINITION (default).
    
    See Also:
    
    FunctionDefinition.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 FunctionDefinition, is always 'functionDefinition'.
    
    Overrides:
    
    getElementName in class SBase
    
    Returns:
    
    the name of this element, i.e., 'functionDefinition'.
  - hasRequiredAttributes
```
public boolean hasRequiredAttributes()
```
    Predicate returning true if all the required attributes for this FunctionDefinition object have been set.
    The required attributes for a FunctionDefinition object are:
    - 'id'
    Overrides:
    
    hasRequiredAttributes in class SBase
    
    Returns:
    
    true if the required attributes have been set, false otherwise.
  - hasRequiredElements
```
public boolean hasRequiredElements()
```
    Predicate returning true if all the required elements for this FunctionDefinition 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 FunctionDefinition object are:
    
    'math'
  - renameUnitSIdRefs
```
public void renameUnitSIdRefs(java.lang.String oldid,
                              java.lang.String newid)
```
    Renames all the UnitSIdRef attributes on this element.
    
    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 unit identifiers to the value of oldid. If any matches are found, the matching identifiers 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

Class FunctionDefinition

Constructor Summary

Method Summary

Methods inherited from class org.sbml.libsbml.SBase

Methods inherited from class java.lang.Object

Constructor Detail

FunctionDefinition

FunctionDefinition

FunctionDefinition

Method Detail

delete

cloneObject

getId

getName

getMath

isSetId

isSetName

isSetMath

setId

setName

setMath

unsetName

getArgument

getArgument

getBody

isSetBody

getNumArguments

getTypeCode

getElementName

hasRequiredAttributes

hasRequiredElements

renameUnitSIdRefs