libSBML Perl API  libSBML 5.17.2 Perl API
SBMLInternalValidator Class Reference
Inheritance diagram for SBMLInternalValidator:
[legend]

Detailed Description

{core}

Basic SBML consistency checks and other validations.

This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. This class is not prescribed by the SBML specifications, although it is used to implement features defined in SBML.

LibSBML implements facilities for verifying that a given SBML document is valid according to the SBML specifications; it also exposes the validation interface so that user programs and SBML Level 3 package authors may use the facilities to implement new validators. The entry point for this is the SBMLValidator class.

The subclass SBMLInternalValidator embodies the implementation of the consistency-checking methods defined on SBMLDocument. The methods SBMLDocument::setConsistencyChecks(), SBMLDocument::checkConsistency(), SBMLDocument::checkInternalConsistency() and other method of that sort are in fact implemented by SBMLInternalValidator. These validations are all performed on the internal (in-memory) representation of an SBML model.

Users should not need to call SBMLInternalValidator methods directly, since the interface is already provided on SBMLDocument. However, this class is exposed in case users would like to implement new or additional validations by extending this class (SBMLInternalValidator) or using this class as an example of how to implement such validators.

Public Member Functions

unsigned int checkConsistency (bool writeDocument=false)
 Performs consistency checking and validation on this SBML document. More...
 
unsigned int checkInternalConsistency ()
 Performs consistency checking on libSBML's internal representation of an SBML Model. More...
 
unsigned int checkL1Compatibility ()
 Performs a set of consistency checks on the document to establish whether it is compatible with SBML Level 1 and can be converted to Level 1. More...
 
unsigned int checkL2v1Compatibility ()
 Performs a set of consistency checks on the document to establish whether it is compatible with SBML Level 2 Version 1 and can be converted to Level 2 Version 1. More...
 
unsigned int checkL2v2Compatibility ()
 Performs a set of consistency checks on the document to establish whether it is compatible with SBML Level 2 Version 2 and can be converted to Level 2 Version 2. More...
 
unsigned int checkL2v3Compatibility ()
 Performs a set of consistency checks on the document to establish whether it is compatible with SBML Level 2 Version 3 and can be converted to Level 2 Version 3. More...
 
unsigned int checkL2v4Compatibility ()
 Performs a set of consistency checks on the document to establish whether it is compatible with SBML Level 2 Version 4 and can be converted to Level 2 Version 4. More...
 
unsigned int checkL2v5Compatibility ()
 Performs a set of consistency checks on the document to establish whether it is compatible with SBML Level 2 Version 5 and can be converted to Level 2 Version 5. More...
 
unsigned int checkL3v1Compatibility ()
 Performs a set of consistency checks on the document to establish whether it is compatible with SBML Level 3 Version 1 and can be converted to Level 3 Version 1. More...
 
unsigned int checkL3v2Compatibility ()
 Performs a set of consistency checks on the document to establish whether it is compatible with SBML Level 3 Version 2 and can be converted to Level 3 Version 2. More...
 
virtual void clearFailures ()
 Clears this validator's list of failures. More...
 
virtual SBMLValidatorclone () const
 Creates and returns a deep copy of this SBMLValidator object. More...
 
unsigned char getApplicableValidators () const
 
unsigned char getConversionValidators () const
 
virtual SBMLDocumentgetDocument ()
 Returns the current SBML document in use by this validator. More...
 
virtual const SBMLDocumentgetDocument () const
 Returns the current SBML document in use by this validator. More...
 
SBMLErrorLoggetErrorLog ()
 Returns the list of errors or warnings logged during parsing, consistency checking, or attempted translation of this model. More...
 
SBMLErrorgetFailure (unsigned int n) const
 Returns the failure object at index n in this validator's list of failures logged during the last run. More...
 
const std::vector< SBMLError > & getFailures () const
 Returns a list of SBMLError objects (if any) that were logged by the last run of this validator. More...
 
const ModelgetModel () const
 Returns the Model object stored in the SBMLDocument. More...
 
ModelgetModel ()
 Returns the Model object stored in the SBMLDocument. More...
 
unsigned int getNumFailures () const
 Returns the number of failures encountered in the last validation run. More...
 
void logFailure (const SBMLError &err)
 Adds the given failure to this list of Validators failures. More...
 
 SBMLInternalValidator ()
 Constructor. More...
 
 SBMLInternalValidator (const SBMLInternalValidator &orig)
 Copy constructor; creates a copy of an SBMLInternalValidator object. More...
 
void setApplicableValidators (unsigned char appl)
 Set the current list of validators to be applied. More...
 
void setConsistencyChecks (SBMLErrorCategory_t category, bool apply)
 Controls the consistency checks that are performed when SBMLDocument::checkConsistency() is called. More...
 
void setConsistencyChecksForConversion (SBMLErrorCategory_t category, bool apply)
 Controls the consistency checks that are performed when SBMLDocument::setLevelAndVersion() is called. More...
 
void setConversionValidators (unsigned char appl)
 Set the current list of conversion validators to be applied. More...
 
virtual int setDocument (const SBMLDocument *doc)
 Sets the current SBML document to the given SBMLDocument object. More...
 
unsigned int validate (const SBMLDocument &d)
 Validates the given SBMLDocument object. More...
 
unsigned int validate (const std::string &filename)
 Validates the SBML document located at the given filename. More...
 
virtual unsigned int validate ()
 Runs the validations. More...
 
virtual ~SBMLInternalValidator ()
 Destroy this object. More...
 

Constructor & Destructor Documentation

◆ SBMLInternalValidator() [1/2]

SBMLInternalValidator::SBMLInternalValidator ( )

Constructor.

◆ SBMLInternalValidator() [2/2]

SBMLInternalValidator::SBMLInternalValidator ( const SBMLInternalValidator orig)

Copy constructor; creates a copy of an SBMLInternalValidator object.

Parameters
origthe object to copy.

◆ ~SBMLInternalValidator()

SBMLInternalValidator::~SBMLInternalValidator ( )
virtual

Destroy this object.

Member Function Documentation

◆ checkConsistency()

unsigned int SBMLInternalValidator::checkConsistency ( bool  writeDocument = false)

Performs consistency checking and validation on this SBML document.

If this method returns a nonzero value (meaning, one or more consistency checks have failed for SBML document), the failures may be due to warnings or errors. Callers should inspect the severity flag in the individual SBMLError objects returned by SBMLDocument::getError() to determine the nature of the failures.

Parameters
writeDocumentby default checkConsistency will write the document in order to determine all errors for the document. This will also clear the error log. Setting this parameter to false will skip this additional step but might not find all errors.
Returns
the number of failed checks (errors) encountered.
See also
SBMLDocument::checkInternalConsistency()

◆ checkInternalConsistency()

unsigned int SBMLInternalValidator::checkInternalConsistency ( )

Performs consistency checking on libSBML's internal representation of an SBML Model.

Callers should query the results of the consistency check by calling SBMLDocument::getError().

Returns
the number of failed checks (errors) encountered.

The distinction between this method and SBMLDocument::checkConsistency() is that this method reports on fundamental syntactic and structural errors that violate the XML Schema for SBML; by contrast, SBMLDocument::checkConsistency() performs more elaborate model verifications and also validation according to the validation rules written in the appendices of the SBML Level 2 Versions 2–4 specification documents.

See also
SBMLDocument::checkConsistency()

◆ checkL1Compatibility()

unsigned int SBMLInternalValidator::checkL1Compatibility ( )

Performs a set of consistency checks on the document to establish whether it is compatible with SBML Level 1 and can be converted to Level 1.

Callers should query the results of the consistency check by calling SBMLDocument::getError().

Returns
the number of failed checks (errors) encountered.

◆ checkL2v1Compatibility()

unsigned int SBMLInternalValidator::checkL2v1Compatibility ( )

Performs a set of consistency checks on the document to establish whether it is compatible with SBML Level 2 Version 1 and can be converted to Level 2 Version 1.

Callers should query the results of the consistency check by calling SBMLDocument::getError().

Returns
the number of failed checks (errors) encountered.

◆ checkL2v2Compatibility()

unsigned int SBMLInternalValidator::checkL2v2Compatibility ( )

Performs a set of consistency checks on the document to establish whether it is compatible with SBML Level 2 Version 2 and can be converted to Level 2 Version 2.

Callers should query the results of the consistency check by calling SBMLDocument::getError().

Returns
the number of failed checks (errors) encountered.

◆ checkL2v3Compatibility()

unsigned int SBMLInternalValidator::checkL2v3Compatibility ( )

Performs a set of consistency checks on the document to establish whether it is compatible with SBML Level 2 Version 3 and can be converted to Level 2 Version 3.

Callers should query the results of the consistency check by calling SBMLDocument::getError().

Returns
the number of failed checks (errors) encountered.

◆ checkL2v4Compatibility()

unsigned int SBMLInternalValidator::checkL2v4Compatibility ( )

Performs a set of consistency checks on the document to establish whether it is compatible with SBML Level 2 Version 4 and can be converted to Level 2 Version 4.

Callers should query the results of the consistency check by calling SBMLDocument::getError().

Returns
the number of failed checks (errors) encountered.

◆ checkL2v5Compatibility()

unsigned int SBMLInternalValidator::checkL2v5Compatibility ( )

Performs a set of consistency checks on the document to establish whether it is compatible with SBML Level 2 Version 5 and can be converted to Level 2 Version 5.

Callers should query the results of the consistency check by calling SBMLDocument::getError().

Returns
the number of failed checks (errors) encountered.

◆ checkL3v1Compatibility()

unsigned int SBMLInternalValidator::checkL3v1Compatibility ( )

Performs a set of consistency checks on the document to establish whether it is compatible with SBML Level 3 Version 1 and can be converted to Level 3 Version 1.

Callers should query the results of the consistency check by calling SBMLDocument::getError().

Returns
the number of failed checks (errors) encountered.

◆ checkL3v2Compatibility()

unsigned int SBMLInternalValidator::checkL3v2Compatibility ( )

Performs a set of consistency checks on the document to establish whether it is compatible with SBML Level 3 Version 2 and can be converted to Level 3 Version 2.

Callers should query the results of the consistency check by calling SBMLDocument::getError().

Returns
the number of failed checks (errors) encountered.

◆ clearFailures()

void SBMLValidator::clearFailures ( )
virtualinherited

Clears this validator's list of failures.

If you are validating multiple SBML documents with the same validator, call this method after you have processed the list of failures from the last validation run and before validating the next document.

◆ clone()

SBMLValidator * SBMLInternalValidator::clone ( ) const
virtual

Creates and returns a deep copy of this SBMLValidator object.

Returns
the (deep) copy of this SBMLValidator object.

Reimplemented from SBMLValidator.

◆ getApplicableValidators()

unsigned char SBMLInternalValidator::getApplicableValidators ( ) const
Returns
the current list of selected validators.

◆ getConversionValidators()

unsigned char SBMLInternalValidator::getConversionValidators ( ) const
Returns
the current list of selected validators for conversion.

◆ getDocument() [1/2]

SBMLDocument * SBMLValidator::getDocument ( )
virtualinherited

Returns the current SBML document in use by this validator.

Returns
the current SBML document.
See also
setDocument()

◆ getDocument() [2/2]

const SBMLDocument * SBMLValidator::getDocument ( ) const
virtualinherited

Returns the current SBML document in use by this validator.

Returns
a const reference to the current SBML document.
See also
setDocument()

◆ getErrorLog()

SBMLErrorLog * SBMLValidator::getErrorLog ( )
inherited

Returns the list of errors or warnings logged during parsing, consistency checking, or attempted translation of this model.

Note that this refers to the SBMLDocument object's error log (i.e., the list returned by SBMLDocument::getErrorLog()). That list of errors and warnings is separate from the validation failures tracked by this validator (i.e., the list returned by getFailures()).

Returns
the SBMLErrorLog used for the SBMLDocument.

◆ getFailure()

SBMLError * SBMLValidator::getFailure ( unsigned int  n) const
inherited

Returns the failure object at index n in this validator's list of failures logged during the last run.

Callers should use getNumFailures() first, to find out the number of entries in this validator's list of failures.

Parameters
nan integer indicating the index of the object to return from the failures list; index values start at 0.
Returns
the failure at the given index number.
See also
getNumFailures()

◆ getFailures()

const std::vector< SBMLError > & SBMLValidator::getFailures ( ) const
inherited

Returns a list of SBMLError objects (if any) that were logged by the last run of this validator.

Returns
a list of errors, warnings and other diagnostics logged during validation.
See also
clearFailures()

◆ getModel() [1/2]

const Model * SBMLValidator::getModel ( ) const
inherited

Returns the Model object stored in the SBMLDocument.

It is important to note that this method does not create a Model instance. The model in the SBMLDocument must have been created at some prior time, for example using SBMLDocument::createModel() or SBMLDocument::setModel(). This method returns NULL if a model does not yet exist.

Returns
the Model contained in this validator's SBMLDocument object.
See also
SBMLDocument::setModel()
SBMLDocument::createModel()

◆ getModel() [2/2]

Model * SBMLValidator::getModel ( )
inherited

Returns the Model object stored in the SBMLDocument.

It is important to note that this method does not create a Model instance. The model in the SBMLDocument must have been created at some prior time, for example using SBMLDocument::createModel() or SBMLDocument::setModel(). This method returns NULL if a model does not yet exist.

Returns
the Model contained in this validator's SBMLDocument object.
See also
SBMLDocument::setModel()
SBMLDocument::createModel()

◆ getNumFailures()

unsigned int SBMLValidator::getNumFailures ( ) const
inherited

Returns the number of failures encountered in the last validation run.

This method returns the number of failures logged by this validator. This number only reflects this validator's actions; the number may not be the same as the number of errors and warnings logged on the SBMLDocument object's error log (i.e., the object returned by SBMLDocument::getErrorLog()), because other parts of libSBML may log errors and warnings beyond those found by this validator.

Returns
the number of errors logged by this validator.

◆ logFailure()

void SBMLValidator::logFailure ( const SBMLError err)
inherited

Adds the given failure to this list of Validators failures.

Parameters
erran SBMLError object representing an error or warning.

◆ setApplicableValidators()

void SBMLInternalValidator::setApplicableValidators ( unsigned char  appl)

Set the current list of validators to be applied.

Parameters
applthe mask of validators to be applied.

◆ setConsistencyChecks()

void SBMLInternalValidator::setConsistencyChecks ( SBMLErrorCategory_t  category,
bool  apply 
)

Controls the consistency checks that are performed when SBMLDocument::checkConsistency() is called.

This method works by adding or subtracting consistency checks from the set of all possible checks that SBMLDocument::checkConsistency() knows how to perform. This method may need to be called multiple times in order to achieve the desired combination of checks. The first argument (category) in a call to this method indicates the category of consistency/error checks that are to be turned on or off, and the second argument (apply, a boolean) indicates whether to turn it on (value of true) or off (value of false).

◆ setConsistencyChecksForConversion()

void SBMLInternalValidator::setConsistencyChecksForConversion ( SBMLErrorCategory_t  category,
bool  apply 
)

Controls the consistency checks that are performed when SBMLDocument::setLevelAndVersion() is called.

This method works by adding or subtracting consistency checks from the set of all possible checks that may be performed to avoid conversion to or from an invalid document. This method may need to be called multiple times in order to achieve the desired combination of checks. The first argument (category) in a call to this method indicates the category of consistency/error checks that are to be turned on or off, and the second argument (apply, a boolean) indicates whether to turn it on (value of true) or off (value of false).

◆ setConversionValidators()

void SBMLInternalValidator::setConversionValidators ( unsigned char  appl)

Set the current list of conversion validators to be applied.

Parameters
applthe mask of validators to be applied.

◆ setDocument()

int SBMLValidator::setDocument ( const SBMLDocument doc)
virtualinherited

Sets the current SBML document to the given SBMLDocument object.

Parameters
docthe document to use for this validation.

◆ validate() [1/3]

unsigned int SBMLValidator::validate ( const SBMLDocument d)
inherited

Validates the given SBMLDocument object.

This is identical to calling setDocument() followed by validate().

Parameters
dthe SBML document to validate.
Returns
the number of validation failures that occurred. The objects describing the actual failures can be retrieved using getFailures().

◆ validate() [2/3]

unsigned int SBMLValidator::validate ( const std::string &  filename)
inherited

Validates the SBML document located at the given filename.

This is a convenience method that saves callers the trouble of using SBMLReader to read the document first.

Parameters
filenamethe path to the file to be read and validated.
Returns
the number of validation failures that occurred. The objects describing the actual failures can be retrieved using getFailures().

◆ validate() [3/3]

unsigned int SBMLInternalValidator::validate ( )
virtual

Runs the validations.

This runs the validations that were previously enabled via methods such as SBMLDocument::setConsistencyChecks().

Returns
the number of validation failures that occurred. The objects describing the actual failures can be retrieved using getFailures().

Reimplemented from SBMLValidator.