libSBML C++ API  5.18.0
SBMLValidator Class Reference
Inheritance diagram for SBMLValidator:
[legend]

Detailed Description

Base class for SBML validators.

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. There are two main interfaces to libSBML's validation facilities, based on the classes Validator and SBMLValidator.

The Validator class is the basis of the system for validating an SBML document against the validation rules defined in the SBML specifications. The scheme used by Validator relies is compact and uses the visitor programming pattern, but it relies on C/C++ features and is not directly accessible from language bindings. SBMLValidator offers a framework for straightforward class-based extensibility, so that user code can subclass SBMLValidator to implement new validation systems, different validators can be introduced or turned off at run-time, and interfaces can be provided in the libSBML language bindings. SBMLValidator can call Validator functionality internally (as is the case in the current implementation of SBMLInternalValidator) or use entirely different implementation approaches, as necessary.

Users of libSBML may already be familiar with the facilities encompassed by the validation system, in the form 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 via SBMLValidator, specifically as methods on the class SBMLInternalValidator.

Authors may use SBMLValidator as the base class for their own validator extensions to libSBML. The class SBMLInternalValidator may serve as a code example for how to implement such things.

Examples:
addCustomValidator.cpp, and rngvalidator.cpp.

Public Member Functions

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...
 
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...
 
SBMLValidatoroperator= (const SBMLValidator &rhs)
 Assignment operator for SBMLValidator. More...
 
 SBMLValidator ()
 Creates a new SBMLValidator. More...
 
 SBMLValidator (const SBMLValidator &orig)
 Copy constructor; creates a copy of an SBMLValidator object. More...
 
virtual int setDocument (const SBMLDocument *doc)
 Sets the current SBML document to the given SBMLDocument object. More...
 
virtual unsigned int validate ()
 Runs this validator on the current SBML document. 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 ~SBMLValidator ()
 Destroy this object. More...
 

Constructor & Destructor Documentation

SBMLValidator::SBMLValidator ( )

Creates a new SBMLValidator.

SBMLValidator::SBMLValidator ( const SBMLValidator orig)

Copy constructor; creates a copy of an SBMLValidator object.

Parameters
origthe object to copy.
SBMLValidator::~SBMLValidator ( )
virtual

Destroy this object.

Member Function Documentation

void SBMLValidator::clearFailures ( )
virtual

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.

See also
getFailures()
SBMLValidator * SBMLValidator::clone ( ) const
virtual

Creates and returns a deep copy of this SBMLValidator object.

Returns
the (deep) copy of this SBMLValidator object.

Reimplemented in SBMLInternalValidator.

SBMLDocument * SBMLValidator::getDocument ( )
virtual

Returns the current SBML document in use by this validator.

Returns
the current SBML document.
See also
setDocument()
const SBMLDocument * SBMLValidator::getDocument ( ) const
virtual

Returns the current SBML document in use by this validator.

Returns
a const reference to the current SBML document.
See also
setDocument()
SBMLErrorLog * SBMLValidator::getErrorLog ( )

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.
See also
getFailures()
SBMLError * SBMLValidator::getFailure ( unsigned int  n) const

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()
const std::vector< SBMLError > & SBMLValidator::getFailures ( ) const

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()
const Model * SBMLValidator::getModel ( ) const

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()
Model * SBMLValidator::getModel ( )

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()
unsigned int SBMLValidator::getNumFailures ( ) const

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.
void SBMLValidator::logFailure ( const SBMLError err)

Adds the given failure to this list of Validators failures.

Parameters
erran SBMLError object representing an error or warning.
See also
getFailures()
SBMLValidator & SBMLValidator::operator= ( const SBMLValidator rhs)

Assignment operator for SBMLValidator.

Parameters
rhsthe object whose values are used as the basis of the assignment.
int SBMLValidator::setDocument ( const SBMLDocument doc)
virtual

Sets the current SBML document to the given SBMLDocument object.

Parameters
docthe document to use for this validation.
Returns
integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. This particular function only does one thing irrespective of user input or object state, and thus will only return a single value:
See also
getDocument()
unsigned int SBMLValidator::validate ( )
virtual

Runs this validator on the current SBML document.

Returns
an integer value indicating the success/failure of the validation. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are determined by the specific subclasses of this class.

Reimplemented in SBMLInternalValidator.

unsigned int SBMLValidator::validate ( const SBMLDocument d)

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().
unsigned int SBMLValidator::validate ( const std::string &  filename)

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().