public class XMLError extends Object
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.
XMLError
objects
The error and warning codes returned by the XML layer in libSBML are
listed in the table below. In the libSBML Java language interface,
these error identifiers are currently implemented as static integer
constants defined in the interface class libsbmlConstants
. This is
admittedly not an ideal approach from the standpoint of modern Java
programming, but it was necessary to work around the lack of
enumerations in Java prior to JDK 1.5. Future versions of libSBML may
use a proper Java enumeration type to define the error
identifiers.
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 |
XMLError
objects
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 following table lists each possible value
and a brief description of its meaning.
As is the case with the error codes, in the libSBML Java language
interface, the category identifiers are currently implemented as static
integer constants defined in the interface class
libsbmlConstants
in the file 'libsbmlConstants.java'.
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. |
XMLError
objects
As described above, each XMLError
object contains a value for a severity
code, describing how severe is the issue that the XMLError
object
represents. The severity be retrieved from an XMLError
object using the
method XMLError.getSeverity()
. The following table lists each possible
value and a brief description of its meaning.
As is the case with the category codes, in the libSBML Java language
interface, these severity codes are currently
implemented as static integer constants defined in the interface class
libsbmlConstants
in the file 'libsbmlConstants.java'. This
is admittedly not an ideal approach from the standpoint of modern Java
programming, but it was necessary to work around the lack of
enumerations in Java prior to JDK 1.5. Future versions of libSBML may
use a proper Java enumeration type to define the severity
codes.
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. |
Constructor and Description |
---|
XMLError()
Creates a new
XMLError to report that something occurred during XML
processing. |
XMLError(int errorId)
Creates a new
XMLError to report that something occurred during XML
processing. |
XMLError(int errorId,
String details)
Creates a new
XMLError to report that something occurred during XML
processing. |
XMLError(int errorId,
String details,
long line)
Creates a new
XMLError to report that something occurred during XML
processing. |
XMLError(int errorId,
String details,
long line,
long column)
Creates a new
XMLError to report that something occurred during XML
processing. |
XMLError(int errorId,
String details,
long line,
long column,
long severity)
Creates a new
XMLError to report that something occurred during XML
processing. |
XMLError(int errorId,
String details,
long line,
long column,
long severity,
long category)
Creates a new
XMLError to report that something occurred during XML
processing. |
XMLError(XMLError orig)
Copy constructor creates a copy of this
XMLError . |
Modifier and Type | Method and Description |
---|---|
void |
delete()
Explicitly deletes the underlying native object.
|
boolean |
equals(Object sb)
Equality comparison method for XMLError.
|
long |
getCategory()
Returns the category of this error.
|
String |
getCategoryAsString()
Returns a string describing the category of this error.
|
long |
getColumn()
Returns the column number in the XML input near where the error,
warning or other diagnostic occurred.
|
long |
getErrorId()
Returns the identifier of this error.
|
long |
getErrorIdOffset()
Returns a copy of the message string associated with the given
predefined
XMLError code. |
long |
getLine()
Returns the line number in the XML input near where the error, warning
or other diagnostic occurred.
|
String |
getMessage()
Returns the message text of this error.
|
String |
getPackage()
Returns a copy of the message string associated with the given
predefined
XMLError code. |
long |
getSeverity()
Returns the severity of this error.
|
String |
getSeverityAsString()
Returns a string describing the severity level of this error.
|
String |
getShortMessage()
Returns a brief message for this error.
|
static String |
getStandardMessage(int code)
Returns a copy of the message string associated with the given
predefined
XMLError code. |
int |
hashCode()
Returns a hashcode for this XMLError object.
|
boolean |
isError()
Predicate returning
true or false depending on whether this
error is a significant error. |
boolean |
isFatal()
Predicate returning
true or false depending on whether this
error is a fatal run-time error. |
boolean |
isInfo()
Predicate returning
true or false depending on whether this
error object is for information purposes only. |
boolean |
isInternal()
Predicate returning
true or false depending on whether this
error resulted from an internal program error. |
boolean |
isSystem()
Predicate returning
true or false depending on whether this
error was generated by the operating system. |
boolean |
isValid()
Predicate returning
true or false depending on whether this
error resulted from a problem or whether it was logged as an unknown
error. |
boolean |
isWarning()
Predicate returning
true or false depending on whether
this error object is a warning. |
boolean |
isXML()
Predicate returning
true or false depending on whether this
error resulted from a problem in the XML input (e.g., an XML syntax
error). |
int |
setColumn(long column)
Sets the column number where this error occurred.
|
int |
setLine(long line)
Sets the line number where this error occurred.
|
public XMLError() throws XMLConstructorException
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 unsigned
integer 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
.
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.
XMLConstructorException
public XMLError(int errorId) throws XMLConstructorException
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 unsigned
integer 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
.
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.
XMLConstructorException
public XMLError(int errorId, String details) throws XMLConstructorException
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 unsigned
integer 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
.
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.
XMLConstructorException
public XMLError(int errorId, String details, long line) throws XMLConstructorException
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 unsigned
integer 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
.
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.
XMLConstructorException
public XMLError(int errorId, String details, long line, long column) throws XMLConstructorException
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 unsigned
integer 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
.
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.
XMLConstructorException
public XMLError(int errorId, String details, long line, long column, long severity) throws XMLConstructorException
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 unsigned
integer 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
.
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.
XMLConstructorException
public XMLError(int errorId, String details, long line, long column, long severity, long category) throws XMLConstructorException
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 unsigned
integer 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
.
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.
XMLConstructorException
public XMLError(XMLError orig) throws XMLConstructorException
XMLConstructorException
- Thrown if the argument orig
is null.
public void delete()
In general, application software will not need to call this method directly. The Java language binding for libSBML is implemented as a language wrapper that provides a Java interface to libSBML's underlying C++/C code. Some of the Java methods return objects that are linked to objects created not by Java code, but by C++ code. The Java objects wrapped around them will be deleted when the garbage collector invokes the corresponding C++ finalize()
methods for the objects. The finalize()
methods in turn call the XMLError.delete()
method on the libSBML object.
This method is exposed in case calling programs want to ensure that the underlying object is freed immediately, and not at some arbitrary time determined by the Java garbage collector. In normal usage, callers do not need to invoke XMLError.delete()
themselves.
public boolean equals(Object sb)
Because the Java methods for libSBML are actually wrappers around code
implemented in C++ and C, certain operations will not behave as
expected. Equality comparison is one such case. An instance of a
libSBML object class is actually a proxy object
wrapping the real underlying C/C++ object. The normal ==
equality operator in Java will only compare the Java proxy objects,
not the underlying native object. The result is almost never what you
want in practical situations. Unfortunately, Java does not provide a
way to override ==
.
The alternative that must be followed is to use the
equals()
method. The equals
method on this
class overrides the default java.lang.Object one, and performs an
intelligent comparison of instances of objects of this class. The
result is an assessment of whether two libSBML Java objects are truly
the same underlying native-code objects.
The use of this method in practice is the same as the use of any other
Java equals
method. For example,
a.equals(
b)
returns
true
if a and b are references to the
same underlying object.
public long getCategory()
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.
XMLError
.
XMLError.getSeverity()
,
XMLError.getCategoryAsString()
public String getCategoryAsString()
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.
XMLError
.
XMLError.getCategory()
,
XMLError.getSeverityAsString()
public long 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.
XMLError.getLine()
public long getErrorId()
XMLError.getMessage()
,
XMLError.getShortMessage()
,
XMLError.getCategory()
,
XMLError.getSeverity()
public long getErrorIdOffset()
XMLError
code.
code
- the error code whose message is sought it must be a
predefined value from the set
of predefined error identifiers.public long getLine()
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.
XMLError.getColumn()
public String getMessage()
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.
XMLError.getErrorId()
,
XMLError.getShortMessage()
,
XMLError.getCategory()
,
XMLError.getSeverity()
public String getPackage()
XMLError
code.
code
- the error code whose message is sought it must be a
predefined value from the set
of predefined error identifiers.public long getSeverity()
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.
XMLError
.
XMLError.getSeverityAsString()
,
XMLError.getCategory()
public String getSeverityAsString()
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.
XMLError
.
XMLError.getSeverity()
,
XMLError.getCategoryAsString()
public String getShortMessage()
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.
XMLError.getErrorId()
,
XMLError.getMessage()
,
XMLError.getCategory()
,
XMLError.getSeverity()
public static String getStandardMessage(int code)
XMLError
code.
code
- the error code whose message is sought it must be a
predefined value from the set
of predefined error identifiers.public int hashCode()
public boolean isError()
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
set of predefined
severity codes.
true
if this error is an error, false
otherwise.
XMLError.isInfo()
,
XMLError.isWarning()
,
XMLError.isFatal()
public boolean isFatal()
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
set of predefined severity codes.
true
if this error is a fatal error, false
otherwise.
XMLError.isInfo()
,
XMLError.isWarning()
,
XMLError.isError()
public boolean isInfo()
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
set of predefined
severity codes.
true
if this XMLError
is for informational purposes only,
false
otherwise.
XMLError.isWarning()
,
XMLError.isError()
,
XMLError.isFatal()
public boolean isInternal()
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
set of predefined category codes.
true
or false
XMLError.isSystem()
,
XMLError.isXML()
public boolean isSystem()
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
set of predefined category codes.
true
or false
XMLError.isInternal()
,
XMLError.isXML()
public boolean isValid()
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
set of predefined error codes.
true
or false
public boolean isWarning()
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
set of predefined
severity codes.
true
if this error is a warning, false
otherwise.
XMLError.isInfo()
,
XMLError.isError()
,
XMLError.isFatal()
public boolean isXML()
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.
true
or false
XMLError.isInternal()
,
XMLError.isSystem()
public int setColumn(long column)
column
- a long integer, the column number to set.
XMLError.setLine(long line)
public int setLine(long line)
line
- a long integer, the line number to set.
XMLError.setColumn(long column)