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

Detailed Description

XML-level errors, warnings and other diagnostics.

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 can be configured to use any of a number of XML parsers; at the time of this writing, libSBML supports Xerces versions 2.4 through 3.1, Expat version 1.95.x and higher, and libxml2 version 2.6.16 and higher. These parsers each report different status codes for the various exceptions that can occur during XML processing. The XMLError object class abstracts away from the particular diagnostics reported by the different parsers and presents a single uniform interface and set of status codes, along with operations for manipulating the error objects.

When the libSBML XML parser layer encounters an error in the XML content being processed, or when there is something else wrong (such as an out-of-memory condition), the problems are reported as XMLError objects. Each XMLError object instance has an identification number that identifies the nature of the problem. This error identifier will be up to five digits long and drawn from the enumeration XMLErrorCode_t. Applications can use the error identifiers as a means of recognizing the error encountered and changing their behavior if desired.

Integer error codes are useful for software, but not so much for telling humans what happened. For this reason, XMLError also provides two text messages describing the nature of the error. These messages are accessible by means of the methods XMLError::getShortMessage() and XMLError::getMessage(). The method XMLError::getShortMessage() returns a very brief synopsis of the warning or error condition, whereas XMLError::getMessage() returns a longer explanation. These text strings are suitable for displaying to human users.

Each XMLError object also contains a category code; its value may be retrieved using the method XMLError::getCategory(). Category values are drawn from the enumeration XMLErrorCategory_t described below. Categories are used by libSBML to provide more information to calling programs about the nature of a given error.

In addition to category codes, each XMLError object also has a severity code; its value may be retrieved using the method XMLError::getSeverity(). Severity code values are drawn from the enumeration XMLErrorSeverity_t, described below. Severity levels range from informational (LIBSBML_SEV_INFO) to fatal errors (LIBSBML_SEV_FATAL).

Finally, XMLError objects record the line and column near where the problem occurred in the XML content. The values can be retrieved using the methods XMLError::getLine() and XMLError::getColumn(). We say "near where the problem occurred", because many factors affect how accurate the line/column information ultimately is. For example, sometimes, the underlying XML parsers can only report such information for the parent XML element where an error occurs, and not for the specific point where the problem occurs. In other situations, some parsers report invalid line and/or column numbers altogether. If this occurs, libSBML sets the line and/or column number in the XMLError object to either 0 or the value of the maximum unsigned long integer representable on the platform where libSBML is running. The probability that a true line or column number in an SBML model would equal this value is vanishingly small; thus, if an application encounters these values in an XMLError object, it can assume no valid line/column number could be provided by libSBML in that situation.

XMLErrorCode_t

This is an enumeration of all the error and warning codes returned by the XML layer in libSBML. Each code is an integer with a 4-digit value less than 10000. The following table lists each possible value and a brief description of its meaning.

Possible XMLError error codes. Depending on the programming language in use, the Enumerator values will be defined either as a value from an enumeration type (XMLErrorCode_t) or as integer constants. To make this table more compact, we have shortened the identifiers for the category and severity codes to their essential parts. To get the actual names of the constants, prepend LIBSBML_CAT_ to the category names and LIBSBML_SEV_ to the severity names shown in the two right-hand columns.
Enumerator Meaning Category Severity
XMLUnknownErrorUnrecognized error encountered internallyINTERNALFATAL
XMLOutOfMemory Out of memorySYSTEMFATAL
XMLFileUnreadable File unreadableSYSTEMERROR
XMLFileUnwritable File unwritableSYSTEMERROR
XMLFileOperationErrorError encountered while attempting file operationSYSTEMERROR
XMLNetworkAccessErrorNetwork access errorSYSTEMERROR
InternalXMLParserErrorInternal XML parser state errorINTERNALFATAL
UnrecognizedXMLParserCodeXML parser returned an unrecognized error codeINTERNALFATAL
XMLTranscoderErrorCharacter transcoder errorINTERNALFATAL
MissingXMLDeclMissing XML declaration at beginning of XML inputXMLERROR
MissingXMLEncodingMissing encoding attribute in XML declarationXMLERROR
BadXMLDeclInvalid or unrecognized XML declaration or XML encodingXMLERROR
BadXMLDOCTYPEInvalid, malformed or unrecognized XML DOCTYPE declarationXMLERROR
InvalidCharInXMLInvalid character in XML contentXMLERROR
BadlyFormedXMLXML content is not well-formedXMLERROR
UnclosedXMLTokenUnclosed XML tokenXMLERROR
InvalidXMLConstructXML construct is invalid or not permittedXMLERROR
XMLTagMismatchElement tag mismatch or missing tagXMLERROR
DuplicateXMLAttributeDuplicate XML attributeXMLERROR
UndefinedXMLEntityUndefined XML entityXMLERROR
BadProcessingInstructionInvalid, malformed or unrecognized XML processing instructionXMLERROR
BadXMLPrefixInvalid or undefined XML namespace prefixXMLERROR
BadXMLPrefixValueInvalid XML namespace prefix valueXMLERROR
MissingXMLRequiredAttributeMissing a required XML attributeXMLERROR
XMLAttributeTypeMismatchData type mismatch for the value of an attributeXMLERROR
XMLBadUTF8ContentInvalid UTF8 contentXMLERROR
MissingXMLAttributeValueMissing or improperly formed attribute valueXMLERROR
BadXMLAttributeValueInvalid or unrecognizable attribute valueXMLERROR
BadXMLAttributeInvalid, unrecognized or malformed attributeXMLERROR
UnrecognizedXMLElementElement either not recognized or not permittedXMLERROR
BadXMLCommentBadly formed XML commentXMLERROR
BadXMLDeclLocationXML declaration not permitted in this locationXMLERROR
XMLUnexpectedEOFReached end of input unexpectedlyXMLERROR
BadXMLIDValueValue is invalid for XML ID, or has already been usedXMLERROR
BadXMLIDRefXML ID value was never declaredXMLERROR
UninterpretableXMLContentUnable to interpret contentXMLERROR
BadXMLDocumentStructureBad XML document structureXMLERROR
InvalidAfterXMLContentEncountered invalid content after expected contentXMLERROR
XMLExpectedQuotedStringExpected to find a quoted stringXMLERROR
XMLEmptyValueNotPermittedAn empty value is not permitted in this contextXMLERROR
XMLBadNumberInvalid or unrecognized numberXMLERROR
XMLBadColonColon characters are invalid in this contextXMLERROR
MissingXMLElementsOne or more expected elements are missingXMLERROR
XMLContentEmptyMain XML content is emptyXMLERROR

XMLErrorCategory_t

As discussed above, each XMLError object contains a value for a category identifier, describing the type of issue that the XMLError object represents. The category can be retrieved from an XMLError object using the method XMLError::getCategory(). The value is chosen from the enumeration of category codes XMLErrorCategory_t. The following table lists each possible value and a brief description of its meaning.

Enumerator Meaning
LIBSBML_CAT_INTERNAL A problem involving the libSBML software itself or the underlying XML parser. This almost certainly indicates a software defect (i.e., bug) in libSBML. Please report instances of this to the libSBML developers.
LIBSBML_CAT_SYSTEM A problem reported by the operating system, such as an inability to read or write a file. This indicates something that is not a program error but is outside of the control of libSBML.
LIBSBML_CAT_XML A problem in the XML content itself. This usually arises from malformed XML or the use of constructs not permitted in SBML.

XMLErrorSeverity_t

As described above, each XMLError object contains a value for a severity code, describing how critical is the issue that the XMLError object represents. The severity can be retrieved from an XMLError object using the method XMLError::getSeverity(). The value is chosen from the enumeration of category codes XMLErrorSeverity_t. The following table lists each possible value and a brief description of its meaning.

Enumerator Meaning
LIBSBML_SEV_INFO The error is actually informational and not necessarily a serious problem.
LIBSBML_SEV_WARNING The error object represents a problem that is not serious enough to necessarily stop the problem, but applications should take note of the problem and evaluate what its implications may be.
LIBSBML_SEV_ERROR The error object represents a serious error. The application may continue running but it is unlikely to be able to continue processing the same XML file or data stream.
LIBSBML_SEV_FATAL A serious error occurred, such as an out-of-memory condition, and the software should terminate immediately.

Public Member Functions

unsigned int getCategory () const
 Returns the category of this error. More...
 
const std::string & getCategoryAsString () const
 Returns a string describing the category of this error. More...
 
unsigned int getColumn () const
 Returns the column number in the XML input near where the error, warning or other diagnostic occurred. More...
 
unsigned int getErrorId () const
 Returns the identifier of this error. More...
 
unsigned int getErrorIdOffset () const
 Returns libSBML's internal numerical offset for the error code associated with this error. More...
 
unsigned int getLine () const
 Returns the line number in the XML input near where the error, warning or other diagnostic occurred. More...
 
const std::string & getMessage () const
 Returns the message text of this error. More...
 
const std::string & getPackage () const
 Returns the SBML Level 3 package extension (if any) that logged this error. More...
 
unsigned int getSeverity () const
 Returns the severity of this error. More...
 
const std::string & getSeverityAsString () const
 Returns a string describing the severity level of this error. More...
 
const std::string & getShortMessage () const
 Returns a brief message for this error. More...
 
bool isError () const
 Predicate returning true or false depending on whether this error is a significant error. More...
 
bool isFatal () const
 Predicate returning true or false depending on whether this error is a fatal run-time error. More...
 
bool isInfo () const
 Predicate returning true or false depending on whether this error object is for information purposes only. More...
 
bool isInternal () const
 Predicate returning true or false depending on whether this error resulted from an internal program error. More...
 
bool isSystem () const
 Predicate returning true or false depending on whether this error was generated by the operating system. More...
 
bool isValid () const
 Predicate returning true or false depending on whether this error resulted from a problem or whether it was logged as an unknown error. More...
 
bool isWarning () const
 Predicate returning true or false depending on whether this error object is a warning. More...
 
bool isXML () const
 Predicate returning true or false depending on whether this error resulted from a problem in the XML input (e.g., an XML syntax error). More...
 
XMLErroroperator= (const XMLError &rhs)
 Assignment operator for XMLError. More...
 
int setColumn (unsigned int column)
 Sets the column number where this error occurred. More...
 
int setLine (unsigned int line)
 Sets the line number where this error occurred. More...
 
 XMLError (const int errorId=0, const std::string details="", const unsigned int line=0, const unsigned int column=0, const unsigned int severity=LIBSBML_SEV_FATAL, const unsigned int category=LIBSBML_CAT_INTERNAL)
 Creates a new XMLError to report that something occurred during XML processing. More...
 
 XMLError (const XMLError &orig)
 Copy constructor; creates a copy of this XMLError. More...
 
virtual ~XMLError ()
 Destroys this XMLError. More...
 

Static Public Member Functions

static const std::string getStandardMessage (const int code)
 Returns a copy of the message string associated with the given predefined XMLError code. More...
 

Constructor & Destructor Documentation

XMLError::XMLError ( const int  errorId = 0,
const std::string  details = "",
const unsigned int  line = 0,
const unsigned int  column = 0,
const unsigned int  severity = LIBSBML_SEV_FATAL,
const unsigned int  category = LIBSBML_CAT_INTERNAL 
)

Creates a new XMLError to report that something occurred during XML processing.

XMLError objects have identification numbers to indicate the nature of the exception. These numbers are drawn from the enumeration XMLErrorCode_t. The argument errorId to this constructor can be (but does not have to be) a value from this enumeration. If it is a value from XMLErrorCode_t, the XMLError class assumes the error is a low-level system or XML layer error and prepends a built-in, predefined error message to any string passed in the argument details to this constructor. In addition, all XMLErrorCode_t errors have associated values for the severity and category codes, and these fields are filled-in as well from the enumerations XMLErrorSeverity_t and XMLErrorCategory_t, respectively.

If the error identifier errorId is a number greater than 9999, this constructor assumes that the error was generated from another part of the software, and does not do additional filling in of values beyond the defaults in the constructor itself. This allows XMLError to serve as a base class for other errors (and is used in this way elsewhere in libSBML). Callers should fill in all the parameters with suitable values if generating errors with codes greater than 9999 to make maximum use of the XMLError facilities.

As mentioned above, there are two other enumerations, XMLErrorSeverity_t and XMLErrorCategory_t, used for indicating the severity and category of error for the predefined XMLError codes. The values passed in severity and category override the defaults assigned based on the error code. If the value of errorId is a value from XMLErrorCode_t, callers do not need to fill in severity and category. Conversely, if errorId is not a value from XMLErrorCode_t, callers can use other values (not just those from XMLErrorSeverity_t and XMLErrorCategory_t, but their own special values) for severity and category.

Parameters
errorIdan unsigned int, the identification number of the error.
detailsa string containing additional details about the error. If the error code in errorId is one that is recognized by XMLError, the given message is appended to a predefined message associated with the given code. If the error code is not recognized, the message is stored as-is as the text of the error.
linean unsigned int, the line number at which the error occured.
columnan unsigned int, the column number at which the error occured.
severityan integer indicating severity of the error.
categoryan integer indicating the category to which the error belongs.
XMLError::XMLError ( const XMLError orig)

Copy constructor; creates a copy of this XMLError.

orig the XMLError object to copy.

XMLError::~XMLError ( )
virtual

Destroys this XMLError.

Member Function Documentation

unsigned int XMLError::getCategory ( ) const

Returns the category of this error.

XMLError defines an enumeration of category codes for the XML layer. Applications that build on XMLError by subclassing it may add their own categories with numbers higher than those in the predefined set of category codes.

Categories can be used to partition errors into distinct groups. Among other things, this can be used to prevent id conflicts by uniquely identifying an XMLError by both id and category.

Returns
the category of this XMLError.
See also
getSeverity()
getCategoryAsString()
const std::string & XMLError::getCategoryAsString ( ) const

Returns a string describing the category of this error.

XMLError defines an enumeration of category codes for the XML layer. Applications that build on XMLError by subclassing it may add their own categories with numbers higher than those in the predefined set of category codes.

Categories can be used to partition errors into distinct groups. Among other things, this can be used to prevent id conflicts by uniquely identifying an XMLError by both id and category.

Returns
string representing the category of this XMLError.
See also
getCategory()
getSeverityAsString()
unsigned int XMLError::getColumn ( ) const

Returns the column number in the XML input near where the error, warning or other diagnostic occurred.

We say "near where the problem occurred", because many factors affect how accurate the line/column information ultimately is. For example, sometimes, the underlying XML parsers can only report such information for the parent XML element where an error occurs, and not for the specific point where the problem occurs. In other situations, some parsers report invalid line and/or column numbers altogether. If this occurs, libSBML sets the line and/or column number in the XMLError object to either 0 or the value of the maximum unsigned long integer representable on the platform where libSBML is running. The probability that a true line or column number in an SBML model would equal this value is vanishingly small; thus, if an application encounters these values in an XMLError object, it can assume no valid line/column number could be provided by libSBML in that situation.

Returns
the column number.
See also
getLine()
unsigned int XMLError::getErrorId ( ) const

Returns the identifier of this error.

Returns
the error code for this error.
See also
getMessage()
getShortMessage()
getCategory()
getSeverity()
unsigned int XMLError::getErrorIdOffset ( ) const

Returns libSBML's internal numerical offset for the error code associated with this error.

In the SBML Level 3 package specifications, package validation rules are identified by 5-digit numbers prefixed with the nickname of the package itself—e.g., “comp-10101”, “fbc-20301”, etc. Historically, libSBML reported error codes as pure integers, and some application software systems make decisions based on the numerical values of the error codes. To permit these applications to continue to function in this fashion, libSBML internally continues to maintain error identifiers as pure integers. To handle the possibility that errors may come from package extensions, libSBML uses numerical offsets added to the internal error codes. These offsets add two leading digits to the regular 5-digit error codes; for example, “comp” error codes are stored as 1010101, 1020102, etc. The offset in this case is 1000000. Another package will have the offset 2000000, yet another will have 3000000, etc.

This method returns the integer offset in this error's error code. Calling applications can get the 5-digit package-specific number for a given error code by subtracting the offset from the value reported by getErrorId():

getErrorId() - getErrorIdOffset()

When libSBML produces error messages, it combines the text string returned by getPackage() with the subtracted value of the error code, to produce a text string of the form “comp-10101”.

See also
getErrorId()
getPackage()
unsigned int XMLError::getLine ( ) const

Returns the line number in the XML input near where the error, warning or other diagnostic occurred.

We say "near where the problem occurred", because many factors affect how accurate the line/column information ultimately is. For example, sometimes, the underlying XML parsers can only report such information for the parent XML element where an error occurs, and not for the specific point where the problem occurs. In other situations, some parsers report invalid line and/or column numbers altogether. If this occurs, libSBML sets the line and/or column number in the XMLError object to either 0 or the value of the maximum unsigned long integer representable on the platform where libSBML is running. The probability that a true line or column number in an SBML model would equal this value is vanishingly small; thus, if an application encounters these values in an XMLError object, it can assume no valid line/column number could be provided by libSBML in that situation.

Returns
the line number.
See also
getColumn()
const string & XMLError::getMessage ( ) const

Returns the message text of this error.

The message associated with an error object describes the nature of the problem. The message returned by this method is generally longer and clearer than the message returned by XMLError::getShortMessage(), but not in all cases.

Callers may use XMLError::getCategory() and XMLError::getSeverity() to obtain additional information about the nature and severity of the problem.

Returns
the message text.
See also
getErrorId()
getShortMessage()
getCategory()
getSeverity()
const std::string & XMLError::getPackage ( ) const

Returns the SBML Level 3 package extension (if any) that logged this error.

Each error logged by an libSBML extension for SBML Level 3 packages includes a record of the package that logged it. The field is a simple text string. If the string is empty or has the value "core", then the error came from libSBML core; otherwise, the string will be the short-form name of the package (e.g., "comp" for the Hierarchical Model Composition package).

Returns
a string representing the name of the package that logged this error. If the error did not come from a package extension, the value will be the empty string or "core".
unsigned int XMLError::getSeverity ( ) const

Returns the severity of this error.

XMLError defines an enumeration of severity codes for the XML layer. Applications that build on XMLError by subclassing it may add their own severity codes with numbers higher than those in the predefined set of severity codes.

Returns
the severity of this XMLError.
See also
getSeverityAsString()
getCategory()
const std::string & XMLError::getSeverityAsString ( ) const

Returns a string describing the severity level of this error.

XMLError defines an enumeration of severity codes for the XML layer. Applications that build on XMLError by subclassing it may add their own severity codes with numbers higher than those in the predefined set of severity codes.

Returns
string representing the severity of this XMLError.
See also
getSeverity()
getCategoryAsString()
const string & XMLError::getShortMessage ( ) const

Returns a brief message for this error.

This is an alternative error message that, in general, is as short as the authors could make it. However, brevity is often inversely proportional to clarity, so this short message may not be sufficiently informative to understand the nature of the error. Calling applications may wish to check XMLError::getMessage() in addition or instead.

Returns
the short error message text.
See also
getErrorId()
getMessage()
getCategory()
getSeverity()
const string XMLError::getStandardMessage ( const int  code)
static

Returns a copy of the message string associated with the given predefined XMLError code.

Parameters
codethe error code whose message is sought; it must be a predefined value from XMLErrorCode_t.
bool XMLError::isError ( ) const

Predicate returning true or false depending on whether this error is a significant error.

This is equivalent to obtaining the severity code from an XMLError object (via XMLError::getSeverity()) and then comparing it to the value LIBSBML_SEV_ERROR from the enumeration XMLErrorSeverity_t.

Returns
true if this error is an error, false otherwise.
See also
isInfo()
isWarning()
isFatal()
Examples:
createExampleSBML.cpp, and validateSBML.cpp.
bool XMLError::isFatal ( ) const

Predicate returning true or false depending on whether this error is a fatal run-time error.

This is equivalent to obtaining the severity code from an XMLError object (via XMLError::getSeverity()) and then comparing it to the value LIBSBML_SEV_FATAL from the enumeration XMLErrorSeverity_t.

Returns
true if this error is a fatal error, false otherwise.
See also
isInfo()
isWarning()
isError()
Examples:
createExampleSBML.cpp, and validateSBML.cpp.
bool XMLError::isInfo ( ) const

Predicate returning true or false depending on whether this error object is for information purposes only.

This is equivalent to obtaining the severity code from an XMLError object (via XMLError::getSeverity()) and then comparing it to the value LIBSBML_SEV_INFO from the enumeration XMLErrorSeverity_t.

Returns
true if this XMLError is for informational purposes only, false otherwise.
See also
isWarning()
isError()
isFatal()
bool XMLError::isInternal ( ) const

Predicate returning true or false depending on whether this error resulted from an internal program error.

This is equivalent to obtaining the category identifier from an XMLError object (via XMLError::getCategory()) and then comparing it to the value LIBSBML_CAT_INTERNAL from the enumeration XMLErrorCategory_t.

Returns
a boolean indicating whether the error is an internal error.
See also
isSystem()
isXML()
bool XMLError::isSystem ( ) const

Predicate returning true or false depending on whether this error was generated by the operating system.

This is equivalent to obtaining the category identifier from an XMLError object (via XMLError::getCategory()) and then comparing it to the value LIBSBML_CAT_SYSTEM from the enumeration XMLErrorCategory_t.

Returns
boolean indicating whether the error is a system error.
See also
isInternal()
isXML()
bool XMLError::isValid ( ) const

Predicate returning true or false depending on whether this error resulted from a problem or whether it was logged as an unknown error.

This is equivalent to obtaining the error identifier from an XMLError object (via XMLError::getErrorId()) and then comparing it to the value XMLUnknownError or UnknownError from the enumeration XMLErrorCode_t.

Returns
a boolean indicating whether the error is a valid error (true) or whether it is unknown (false).
bool XMLError::isWarning ( ) const

Predicate returning true or false depending on whether this error object is a warning.

This is equivalent to obtaining the severity code from an XMLError object (via XMLError::getSeverity()) and then comparing it to the value LIBSBML_SEV_WARNING from the enumeration XMLErrorSeverity_t.

Returns
true if this error is a warning, false otherwise.
See also
isInfo()
isError()
isFatal()
bool XMLError::isXML ( ) const

Predicate returning true or false depending on whether this error resulted from a problem in the XML input (e.g., an XML syntax error).

This is equivalent to obtaining the category identifier from an XMLError object (via XMLError::getCategory()) and then comparing it to the value LIBSBML_CAT_XML from the enumeration XMLErrorCategory_t.

Returns
a boolean indicating whether the error is an XML catetory error.
See also
isInternal()
isSystem()
XMLError & XMLError::operator= ( const XMLError rhs)

Assignment operator for XMLError.

Parameters
rhsthe XMLError object whose values are used as the basis of the assignment.
int XMLError::setColumn ( unsigned int  column)

Sets the column number where this error occurred.

Parameters
columnan unsigned int, the column number to set.
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
setLine(unsigned int line)
int XMLError::setLine ( unsigned int  line)

Sets the line number where this error occurred.

Parameters
linean unsigned int, the line number to set.
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
setColumn(unsigned int column)