libSBML C API  libSBML 5.8.0 C API
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
XMLError_t Class Reference

Detailed Description

Representation of 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 is one of the constants listed in the next section below. 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 a set of constants whose names begin with the characters LIBSBML_CAT_, 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 a set of constants whose names begin with the characters LIBSBML_SEV_, 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.

Possible XMLError error codes. Depending on the programming language in use, the Enumerator values will be defined either as a value from the enumeration 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
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.
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.