Inheritance diagram for libsbml.XMLError:

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 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 an enumeration type 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
XMLUnknownError	Unrecognized error encountered internally	INTERNAL	FATAL
XMLOutOfMemory	Out of memory	SYSTEM	FATAL
XMLFileUnreadable	File unreadable	SYSTEM	ERROR
XMLFileUnwritable	File unwritable	SYSTEM	ERROR
XMLFileOperationError	Error encountered while attempting file operation	SYSTEM	ERROR
XMLNetworkAccessError	Network access error	SYSTEM	ERROR
InternalXMLParserError	Internal XML parser state error	INTERNAL	FATAL
UnrecognizedXMLParserCode	XML parser returned an unrecognized error code	INTERNAL	FATAL
XMLTranscoderError	Character transcoder error	INTERNAL	FATAL
MissingXMLDecl	Missing XML declaration at beginning of XML input	XML	ERROR
MissingXMLEncoding	Missing encoding attribute in XML declaration	XML	ERROR
BadXMLDecl	Invalid or unrecognized XML declaration or XML encoding	XML	ERROR
BadXMLDOCTYPE	Invalid, malformed or unrecognized XML DOCTYPE declaration	XML	ERROR
InvalidCharInXML	Invalid character in XML content	XML	ERROR
BadlyFormedXML	XML content is not well-formed	XML	ERROR
UnclosedXMLToken	Unclosed XML token	XML	ERROR
InvalidXMLConstruct	XML construct is invalid or not permitted	XML	ERROR
XMLTagMismatch	Element tag mismatch or missing tag	XML	ERROR
DuplicateXMLAttribute	Duplicate XML attribute	XML	ERROR
UndefinedXMLEntity	Undefined XML entity	XML	ERROR
BadProcessingInstruction	Invalid, malformed or unrecognized XML processing instruction	XML	ERROR
BadXMLPrefix	Invalid or undefined XML namespace prefix	XML	ERROR
BadXMLPrefixValue	Invalid XML namespace prefix value	XML	ERROR
MissingXMLRequiredAttribute	Missing a required XML attribute	XML	ERROR
XMLAttributeTypeMismatch	Data type mismatch for the value of an attribute	XML	ERROR
XMLBadUTF8Content	Invalid UTF8 content	XML	ERROR
MissingXMLAttributeValue	Missing or improperly formed attribute value	XML	ERROR
BadXMLAttributeValue	Invalid or unrecognizable attribute value	XML	ERROR
BadXMLAttribute	Invalid, unrecognized or malformed attribute	XML	ERROR
UnrecognizedXMLElement	Element either not recognized or not permitted	XML	ERROR
BadXMLComment	Badly formed XML comment	XML	ERROR
BadXMLDeclLocation	XML declaration not permitted in this location	XML	ERROR
XMLUnexpectedEOF	Reached end of input unexpectedly	XML	ERROR
BadXMLIDValue	Value is invalid for XML ID, or has already been used	XML	ERROR
BadXMLIDRef	XML ID value was never declared	XML	ERROR
UninterpretableXMLContent	Unable to interpret content	XML	ERROR
BadXMLDocumentStructure	Bad XML document structure	XML	ERROR
InvalidAfterXMLContent	Encountered invalid content after expected content	XML	ERROR
XMLExpectedQuotedString	Expected to find a quoted string	XML	ERROR
XMLEmptyValueNotPermitted	An empty value is not permitted in this context	XML	ERROR
XMLBadNumber	Invalid or unrecognized number	XML	ERROR
XMLBadColon	Colon characters are invalid in this context	XML	ERROR
MissingXMLElements	One or more expected elements are missing	XML	ERROR
XMLContentEmpty	Main XML content is empty	XML	ERROR

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.

Public Member Functions
def	__init__ (self, args)
	This method has multiple variants; they differ in the arguments they accept. More...

def	getCategory (self)
	Returns the category of this error. More...

def	getCategoryAsString (self)
	Returns a string describing the category of this error. More...

def	getColumn (self)
	Returns the column number in the XML input near where the error, warning or other diagnostic occurred. More...

def	getErrorId (self)
	Returns the identifier of this error. More...

def	getErrorIdOffset (self)
	Returns libSBML's internal numerical offset for the error code associated with this error. More...

def	getLine (self)
	Returns the line number in the XML input near where the error, warning or other diagnostic occurred. More...

def	getMessage (self)
	Returns the message text of this error. More...

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

def	getSeverity (self)
	Returns the severity of this error. More...

def	getSeverityAsString (self)
	Returns a string describing the severity level of this error. More...

def	getShortMessage (self)
	Returns a brief message for this error. More...

def	getStandardMessage (code)
	Returns a copy of the message string associated with the given predefined XMLError code. More...

def	isError (self)
	Predicate returning `True` or `False` depending on whether this error is a significant error. More...

def	isFatal (self)
	Predicate returning `True` or `False` depending on whether this error is a fatal run-time error. More...

def	isInfo (self)
	Predicate returning `True` or `False` depending on whether this error object is for information purposes only. More...

def	isInternal (self)
	Predicate returning `True` or `False` depending on whether this error resulted from an internal program error. More...

def	isSystem (self)
	Predicate returning `True` or `False` depending on whether this error was generated by the operating system. More...

def	isValid (self)
	Predicate returning `True` or `False` depending on whether this error resulted from a problem or whether it was logged as an unknown error. More...

def	isWarning (self)
	Predicate returning `True` or `False` depending on whether this error object is a warning. More...

def	isXML (self)

def	setColumn (self, column)
	Sets the column number where this error occurred. More...

def	setLine (self, line)
	Sets the line number where this error occurred. More...

Constructor & Destructor Documentation

def libsbml.XMLError.__init__	(	self,
		args
	)

This method has multiple variants; they differ in the arguments they accept.

__init__(int  errorId=0, string details, long   line=0, long   column=0, long   severity, long   category)   XMLError
__init__(int  errorId=0, string details, long   line=0, long   column=0, long   severity)   XMLError
__init__(int  errorId=0, string details, long   line=0, long   column=0)   XMLError
__init__(int  errorId=0, string details, long   line=0)   XMLError
__init__(int  errorId=0, string details)   XMLError
__init__(int  errorId=0)   XMLError
__init__()   XMLError
__init__(XMLError orig)   XMLError

Each variant is described separately below.

Method variant with the following signature:

XMLError(XMLError orig)

Copy constructor; creates a copy of this XMLError.

orig the XMLError object to copy.

Method variant with the following signature:

XMLError(int errorId = 0, string details = '', long line = 0, long column = 0, long severity = LIBSBML_SEV_FATAL, long 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 defined as longeger constants in the file 'libsbmlConstants.java'. See the top of this documentation for a table listing the possible values and their meanings. The argument errorId to this constructor can be (but does not have to be) a value from this set of constants. If it is one of the predefined error identifiers, 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 the predefined error identifiers have associated values for the severity and category codes, and these fields are filled-in as well.

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 additional constants defined for standard severity and standard category codes, and every predefined error in libSBML has an associated value for severity and category taken from these predefined sets. These constants have symbol names prefixed with LIBSBML_SEV_ and LIBSBML_CAT_, respectively. If the value of errorId is one of the standard error codes, callers do not need to fill in severity and category in a call to this constructor. Conversely, if errorId is not an existing XML-level error code, callers can use other values for severity and category.

Parameters

errorId	a long integer, the identification number of the error.
details	a 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.
line	a long integer, the line number at which the error occured.
column	a long integer, the column number at which the error occured.
severity	an integer indicating severity of the error.
category	an integer indicating the category to which the error belongs.

Note: Owing to the way that language interfaces are created in libSBML, this documentation may show methods that define default values for parameters with text that has the form parameter = value. This is not to be intepreted as a Python keyword argument; the use of a parameter name followed by an equals sign followed by a value is only meant to indicate a default value if the argument is not provided at all. It is not a keyword in the Python sense.

Member Function Documentation

def libsbml.XMLError.getCategory ( self )

Returns the category of this error.

getCategory()   long

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

def libsbml.XMLError.getCategoryAsString ( self )

Returns a string describing the category of this error.

getCategoryAsString()   string

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

def libsbml.XMLError.getColumn ( self )

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

getColumn()   long

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

def libsbml.XMLError.getErrorId ( self )

Returns the identifier of this error.

getErrorId()   long

Returns: the error code for this error.

See also: getMessage(); getShortMessage(); getCategory(); getSeverity()

def libsbml.XMLError.getErrorIdOffset ( self )

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

getErrorIdOffset()   long

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

def libsbml.XMLError.getLine ( self )

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

getLine()   long

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

def libsbml.XMLError.getMessage ( self )

Returns the message text of this error.

getMessage()   string

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

def libsbml.XMLError.getPackage ( self )

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

getPackage()   string

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'.

def libsbml.XMLError.getSeverity ( self )

Returns the severity of this error.

getSeverity()   long

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

def libsbml.XMLError.getSeverityAsString ( self )

Returns a string describing the severity level of this error.

getSeverityAsString()   string

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

def libsbml.XMLError.getShortMessage ( self )

Returns a brief message for this error.

getShortMessage()   string

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

def libsbml.XMLError.getStandardMessage ( code )

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

getStandardMessage(int  code)   string

Parameters

code	the error code whose message is sought; it must be a predefined value from the set of predefined error identifiers.

def libsbml.XMLError.isError ( self )

Predicate returning True or False depending on whether this error is a significant error.

isError()   bool

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 set of predefined severity codes.

Returns: True if this error is an error, False otherwise.

See also: isInfo(); isWarning(); isFatal()

def libsbml.XMLError.isFatal ( self )

Predicate returning True or False depending on whether this error is a fatal run-time error.

isFatal()   bool

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 set of predefined severity codes.

Returns: True if this error is a fatal error, False otherwise.

See also: isInfo(); isWarning(); isError()

def libsbml.XMLError.isInfo ( self )

Predicate returning True or False depending on whether this error object is for information purposes only.

isInfo()   bool

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 set of predefined severity codes.

Returns: True if this XMLError is for informational purposes only, False otherwise.

See also: isWarning(); isError(); isFatal()

def libsbml.XMLError.isInternal ( self )

Predicate returning True or False depending on whether this error resulted from an internal program error.

isInternal()   bool

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 set of predefined category codes.

Returns: a boolean indicating whether the error is an internal error.

See also: isSystem(); isXML()

def libsbml.XMLError.isSystem ( self )

Predicate returning True or False depending on whether this error was generated by the operating system.

isSystem()   bool

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 set of predefined category codes.

Returns: boolean indicating whether the error is a system error.

See also: isInternal(); isXML()

def libsbml.XMLError.isValid ( self )

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

isValid()   bool

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 set of predefined error codes.

Returns: a boolean indicating whether the error is a valid error (True) or whether it is unknown (False).

def libsbml.XMLError.isWarning ( self )

Predicate returning True or False depending on whether this error object is a warning.

isWarning()   bool

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 set of predefined severity codes.

Returns: True if this error is a warning, False otherwise.

See also: isInfo(); isError(); isFatal()

def libsbml.XMLError.isXML ( self )

isXML()   bool

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 set of predefined category codes.

Returns: a boolean indicating whether the error is an XML catetory error.

See also: isInternal(); isSystem()

def libsbml.XMLError.setColumn	(	self,
		column
	)

Sets the column number where this error occurred.

setColumn(long  column)   int

Parameters

column a long integer, the column number to set.

Returns

integer value indicating success/failure of the function. This particular function only does one thing irrespective of user input or object state, and thus will only return a single value:

LIBSBML_OPERATION_SUCCESS

See also: setLine()

def libsbml.XMLError.setLine	(	self,
		line
	)

Sets the line number where this error occurred.

setLine(long  line)   int

Parameters

line	a long integer, the line number to set.

Returns

integer value indicating success/failure of the function. This particular function only does one thing irrespective of user input or object state, and thus will only return a single value:

LIBSBML_OPERATION_SUCCESS

See also: setColumn()

Detailed Description

Public Member Functions

Constructor & Destructor Documentation

Member Function Documentation