public class XMLErrorLog extends java.lang.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.
The error log is a list. The XML layer of libSBML maintains an error
log associated with a given XML document or data stream. When an
operation results in an error, or when there is something wrong with the
XML content, the problem is reported as an XMLError
object stored in the
XMLErrorLog
list. Potential problems range from low-level issues (such
as the inability to open a file) to XML syntax errors (such as
mismatched tags or other problems).
A typical approach for using this error log is to first use
XMLErrorLog.getNumErrors()
to inquire how many XMLError
object instances it contains, and then to
iterate over the list of objects one at a time using
getError(long n) . Indexing in the list begins at 0.
In normal circumstances, programs using libSBML will actually obtain an
SBMLErrorLog
rather than an XMLErrorLog
. The former is subclassed from
XMLErrorLog
and simply wraps commands for working with SBMLError
objects
rather than the low-level XMLError
objects. Classes such as
SBMLDocument
use the higher-level SBMLErrorLog
.
Modifier and Type | Method and Description |
---|---|
void |
changeErrorSeverity(int originalSeverity,
int targetSeverity)
Changes the severity override for errors in the log that have a given
severity.
|
void |
changeErrorSeverity(int originalSeverity,
int targetSeverity,
java.lang.String arg2)
Changes the severity override for errors in the log that have a given
severity.
|
void |
clearLog()
Deletes all errors from this log.
|
boolean |
contains(long errorId)
Returns
true if XMLErrorLog contains an errorId |
void |
delete()
Explicitly deletes the underlying native object.
|
boolean |
equals(java.lang.Object sb)
Equality comparison method for XMLErrorLog.
|
XMLError |
getError(long n)
Returns the nth
XMLError object in this log. |
long |
getNumErrors()
Returns the number of errors that have been logged.
|
int |
getSeverityOverride()
Returns the current override.
|
int |
hashCode()
Returns a hashcode for this XMLErrorLog object.
|
boolean |
isSeverityOverridden()
Returns a boolean indicating whether or not the severity has been
overridden.
|
void |
printErrors()
Prints all the errors or warnings stored in this error log.
|
void |
printErrors(OStream stream)
Prints all the errors or warnings stored in this error log.
|
void |
printErrors(OStream stream,
long severity)
Prints the errors or warnings with given severity stored in this error log.
|
void |
setSeverityOverride(int severity)
Set the severity override.
|
java.lang.String |
toString()
Writes all errors contained in this log to a string and returns it.
|
void |
unsetSeverityOverride()
Usets an existing override.
|
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 XMLErrorLog.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 XMLErrorLog.delete()
themselves.
public boolean equals(java.lang.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.
equals
 in class java.lang.Object
sb
- a reference to an object to which the current object
instance will be comparedtrue
if sb
refers to the same underlying
native object as this one, false
otherwisepublic int hashCode()
hashCode
 in class java.lang.Object
public long getNumErrors()
To retrieve individual errors from the log, callers may use
XMLErrorLog.getError(long n)
.
public XMLError getError(long n)
XMLError
object in this log.
Index n
is counted from 0. Callers should first inquire about the
number of items in the log by using the method
XMLErrorLog.getNumErrors()
.
Attempts to use an error index number that exceeds the actual number
of errors in the log will result in a null
being returned.
n
- the index number of the error to retrieve (with 0 being the
first error).
XMLError
in this log, or null
if n
is
greater than or equal to
XMLErrorLog.getNumErrors()
.
XMLErrorLog.getNumErrors()
public void clearLog()
public java.lang.String toString()
This method uses printErrors() to format the diagnostic messages. Please consult that method for information about the organization of the messages in the string returned by this method.
toString
 in class java.lang.Object
XMLErrorLog.printErrors()
public void printErrors(OStream stream)
This method prints the text to the stream given by the optional
parameter stream
. If no stream is given, the method prints the
output to the standard error stream.
The format of the output is:
N error(s): line NNN: (id) messageIf no errors have occurred, i.e.,
getNumErrors() == 0
, then no output will be produced.
stream
- the ostream or ostringstream object indicating where
the output should be printed.
public void printErrors()
This method prints the text to the stream given by the optional
parameter stream
. If no stream is given, the method prints the
output to the standard error stream.
The format of the output is:
N error(s): line NNN: (id) messageIf no errors have occurred, i.e.,
getNumErrors() == 0
, then no output will be produced.
stream
- the ostream or ostringstream object indicating where
the output should be printed.
public void printErrors(OStream stream, long severity)
This method prints the text to the stream given by the optional
parameter stream
. If no stream is given, the method prints the
output to the standard error stream.
The format of the output is:
N error(s): line NNN: (id) messageIf no errors with that severity was found, then no output will be produced.
stream
- the ostream or ostringstream object indicating where
the output should be printed.severity
- the severity of the errors sought.public boolean isSeverityOverridden()
The severity override mechanism in XMLErrorLog
is intended to help
applications handle error conditions in ways that may be more convenient
for those applications. It is possible to use the mechanism to override
the severity code of errors logged by libSBML, and even to disable error
logging completely. An override stays in effect until the override is
changed again by the calling application.
true
if an error severity override has been set, false
otherwise.
XMLErrorLog.getSeverityOverride()
,
XMLErrorLog.setSeverityOverride(int)
,
XMLErrorLog.unsetSeverityOverride()
,
XMLErrorLog.changeErrorSeverity(int, int, String)
public void unsetSeverityOverride()
The severity override mechanism in XMLErrorLog
is intended to help
applications handle error conditions in ways that may be more convenient
for those applications. It is possible to use the mechanism to override
the severity code of errors logged by libSBML, and even to disable error
logging completely. An override stays in effect until the override is
changed again by the calling application.
public int getSeverityOverride()
The severity override mechanism in XMLErrorLog
is intended to help
applications handle error conditions in ways that may be more convenient
for those applications. It is possible to use the mechanism to override
the severity code of errors logged by libSBML, and even to disable error
logging completely. An override stays in effect until the override is
changed again by the calling application.
LIBSBML_OVERRIDE_
:
XMLErrorLog.isSeverityOverridden()
,
XMLErrorLog.setSeverityOverride(int)
,
XMLErrorLog.unsetSeverityOverride()
,
XMLErrorLog.changeErrorSeverity(int, int, String)
public void setSeverityOverride(int severity)
The severity override mechanism in XMLErrorLog
is intended to help
applications handle error conditions in ways that may be more convenient
for those applications. It is possible to use the mechanism to override
the severity code of errors logged by libSBML, and even to disable error
logging completely. An override stays in effect until the override is
changed again by the calling application.
severity
- an override code indicating what to do. If the value is
LIBSBML_OVERRIDE_DISABLED
(the default setting) all errors logged will be given the severity
specified in their usual definition. If the value is
LIBSBML_OVERRIDE_WARNING
,
then all errors will be logged as warnings. If the value is
LIBSBML_OVERRIDE_DONT_LOG
,
no error will be logged, regardless of their severity.
XMLErrorLog.isSeverityOverridden()
,
XMLErrorLog.getSeverityOverride()
,
XMLErrorLog.unsetSeverityOverride()
,
XMLErrorLog.changeErrorSeverity(int, int, String)
public void changeErrorSeverity(int originalSeverity, int targetSeverity, java.lang.String arg2)
This method searches through the list of errors in the log, comparing
each one's severity to the value of originalSeverity
. For each error
encountered with that severity logged by the named package
, the
severity of the error is reset to targetSeverity
.
The severity override mechanism in XMLErrorLog
is intended to help
applications handle error conditions in ways that may be more convenient
for those applications. It is possible to use the mechanism to override
the severity code of errors logged by libSBML, and even to disable error
logging completely. An override stays in effect until the override is
changed again by the calling application.
originalSeverity
- the severity code to match.
targetSeverity
- the severity code to use as the new severity.
package
- a string, the name of an SBML Level 3 package
extension to use to narrow the search for errors. A value of 'all'
signifies to match against errors logged from any package a value of a
package nickname such as 'comp'
signifies to limit consideration to
errors from just that package. If no value is provided, 'all'
is the
default.
XMLErrorLog.isSeverityOverridden()
,
XMLErrorLog.getSeverityOverride()
,
XMLErrorLog.setSeverityOverride(int)
,
XMLErrorLog.unsetSeverityOverride()
public void changeErrorSeverity(int originalSeverity, int targetSeverity)
This method searches through the list of errors in the log, comparing
each one's severity to the value of originalSeverity
. For each error
encountered with that severity logged by the named package
, the
severity of the error is reset to targetSeverity
.
The severity override mechanism in XMLErrorLog
is intended to help
applications handle error conditions in ways that may be more convenient
for those applications. It is possible to use the mechanism to override
the severity code of errors logged by libSBML, and even to disable error
logging completely. An override stays in effect until the override is
changed again by the calling application.
originalSeverity
- the severity code to match.
targetSeverity
- the severity code to use as the new severity.
package
- a string, the name of an SBML Level 3 package
extension to use to narrow the search for errors. A value of 'all'
signifies to match against errors logged from any package a value of a
package nickname such as 'comp'
signifies to limit consideration to
errors from just that package. If no value is provided, 'all'
is the
default.
XMLErrorLog.isSeverityOverridden()
,
XMLErrorLog.getSeverityOverride()
,
XMLErrorLog.setSeverityOverride(int)
,
XMLErrorLog.unsetSeverityOverride()
public boolean contains(long errorId)
true
if XMLErrorLog
contains an errorId
errorId
- the error identifier of the error to be found.