public class XMLErrorLog 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.
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) const. 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 |
clearLog()
Deletes all errors from this log.
|
void |
delete()
Explicitly deletes the underlying native object.
|
boolean |
equals(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 |
hashCode()
Returns a hashcode for this XMLErrorLog object.
|
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
|
String |
toString()
Writes all errors contained in this log to a string and returns it.
|
public void clearLog()
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(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 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 long getNumErrors()
To retrieve individual errors from the log, callers may use
XMLErrorLog.getError(long n)
.
public int hashCode()
public void printErrors()
It prints the text to the stream given by the optional parameter
stream
. If no parameter is given, it prints the output to the
standard error stream.
If no errors have occurred, i.e., getNumErrors() == 0
, no
output will be sent to the stream.
The format of the output is:
N error(s): line NNN: (id) message
stream
- the ostream or ostringstream object indicating where
the output should be printed.
public void printErrors(OStream stream)
It prints the text to the stream given by the optional parameter
stream
. If no parameter is given, it prints the output to the
standard error stream.
If no errors have occurred, i.e., getNumErrors() == 0
, no
output will be sent to the stream.
The format of the output is:
N error(s): line NNN: (id) message
stream
- the ostream or ostringstream object indicating where
the output should be printed.
public 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 Object
XMLErrorLog.printErrors()