public class SBMLReader 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 SBMLReader
class provides the main interface for reading SBML
content from files and strings. The methods for reading SBML all return
an SBMLDocument
object representing the results.
In the case of failures (such as if the SBML contains errors or a file
cannot be read), the errors will be recorded with the SBMLErrorLog
object kept in the SBMLDocument
returned by SBMLReader
. Consequently,
immediately after calling a method on SBMLReader
, callers should always
check for errors and warnings using the methods for this purpose
provided by SBMLDocument
.
For convenience as well as easy access from other languages besides C++,
this file also defines two global functions,
libsbml.readSBML(String filename)
and libsbml.readSBMLFromString(String xml)
.
They are equivalent to creating an SBMLReader
object and then calling the
SBMLReader.readSBML(String filename)
or
SBMLReader.readSBMLFromString(String xml)
methods, respectively.
LibSBML provides support for reading (as well as writing) compressed
SBML files. The process is transparent to the calling
application&mdashthe application does not need to do anything
deliberate to invoke the functionality. If a given SBML filename ends
with an extension for the gzip, zip or bzip2 compression
formats (respectively, .gz
, .zip
, or .bz2
), then the methods
SBMLReader.readSBML(String filename)
and
SBMLWriter.writeSBML(SBMLDocument d, String filename)
will automatically decompress and compress the file while writing and
reading it. If the filename has no such extension, it
will be read and written uncompressed as normal.
The compression feature requires that the zlib (for gzip and
zip formats) and/or bzip2 (for bzip2 format) be available on the
system running libSBML, and that libSBML was configured with their
support compiled-in. Please see the libSBML installation instructions for more information about this. The methods
SBMLReader.hasZlib()
and
SBMLReader.hasBzip2()
can be used by an application to query at run-time whether support
for the compression libraries is available in the present copy of
libSBML.
Support for compression is not mandated by the SBML standard, but applications may find it helpful, particularly when large SBML models are being communicated across data links of limited bandwidth.
Constructor and Description |
---|
SBMLReader()
Creates a new
SBMLReader and returns it. |
Modifier and Type | Method and Description |
---|---|
void |
delete()
Explicitly deletes the underlying native object.
|
boolean |
equals(java.lang.Object sb)
Equality comparison method for SBMLReader.
|
static boolean |
hasBzip2()
Static method returns
true if this copy of libSBML supports
bzip2 format compression. |
int |
hashCode()
Returns a hashcode for this SBMLReader object.
|
static boolean |
hasZlib()
Static method returns
true if this copy of libSBML supports
gzip and zip format compression. |
SBMLDocument |
readSBML(java.lang.String filename)
Reads an SBML document from a file.
|
SBMLDocument |
readSBMLFromFile(java.lang.String filename)
Reads an SBML document from a file.
|
SBMLDocument |
readSBMLFromString(java.lang.String xml)
Reads an SBML document from the given XML string.
|
public SBMLReader()
SBMLReader
and returns it.
The libSBML SBMLReader
objects offer methods for reading SBML in
XML form from files and text strings.
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 SBMLReader.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 SBMLReader.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 static boolean hasBzip2()
true
if this copy of libSBML supports
bzip2 format compression.
true
if libSBML is linked with the bzip2
libraries, false
otherwise.
SBMLReader.hasZlib()
public int hashCode()
hashCode
 in class java.lang.Object
public static boolean hasZlib()
true
if this copy of libSBML supports
gzip and zip format compression.
true
if libSBML has been linked with the zlib
library, false
otherwise.
SBMLReader.hasBzip2()
public SBMLDocument readSBML(java.lang.String filename)
This method is identical to SBMLReader.readSBMLFromFile(String filename)
.
If the file named filename
does not exist or its content is not
valid SBML, one or more errors will be logged with the SBMLDocument
object returned by this method. Callers can use the methods on
SBMLDocument
such as SBMLDocument.getNumErrors()
and
SBMLDocument.getError(long n)
to get the errors. The object returned by
SBMLDocument.getError(long n)
is an SBMLError
object, and it has methods to
get the error code, category, and severity level of the problem, as
well as a textual description of the problem. The possible severity
levels range from informational messages to fatal errors see the
documentation for SBMLError
for more information.
If the file filename
could not be read, the file-reading error will
appear first. The error code can provide a clue about what happened. For example,
a file might be unreadable (either because it does not actually exist
or because the user does not have the necessary access privileges to
read it) or some sort of file operation error may have been reported
by the underlying operating system. Callers can check for these
situations using a program fragment such as the following:
SBMLReader
reader = newSBMLReader
()SBMLDocument
doc = reader.readSBMLFromFile(filename) if (doc.getNumErrors() > 0) { if (doc.getError(0).getErrorId() == libsbmlConstants.XMLFileUnreadable) { // Handle case of unreadable file here. } else if (doc.getError(0).getErrorId() == libsbmlConstants.XMLFileOperationError) { // Handle case of other file operation error here. } else { // Handle other error cases. } }
If the given filename ends with the suffix '.gz'
(for example,
'myfile.xml.gz'
), the file is assumed to be compressed in gzip
format and will be automatically decompressed upon reading.
Similarly, if the given filename ends with '.zip'
or '.bz2'
, the
file is assumed to be compressed in zip or bzip2 format
(respectively). Files whose names lack these suffixes will be read
uncompressed. Note that if the file is in zip format but the
archive contains more than one file, only the first file in the
archive will be read and the rest ignored.
To read a gzip/zip file, libSBML needs to be configured and linked with the zlib library at compile time. It also needs to be linked with the bzip2 library to read files in bzip2 format. (Both of these are the default configurations for libSBML.) Errors about unreadable files will be logged if a compressed filename is given and libSBML was not linked with the corresponding required library.
filename
- the name or full pathname of the file to be read.
SBMLDocument
created from the SBML content.
SBMLError
,
SBMLDocument
public SBMLDocument readSBMLFromFile(java.lang.String filename)
This method is identical to SBMLReader.readSBML(String filename)
.
If the file named filename
does not exist or its content is not
valid SBML, one or more errors will be logged with the SBMLDocument
object returned by this method. Callers can use the methods on
SBMLDocument
such as SBMLDocument.getNumErrors()
and
SBMLDocument.getError(long n)
to get the errors. The object returned by
SBMLDocument.getError(long n)
is an SBMLError
object, and it has methods to
get the error code, category, and severity level of the problem, as
well as a textual description of the problem. The possible severity
levels range from informational messages to fatal errors see the
documentation for SBMLError
for more information.
If the file filename
could not be read, the file-reading error will
appear first. The error code can provide a clue about what happened. For example,
a file might be unreadable (either because it does not actually exist
or because the user does not have the necessary access privileges to
read it) or some sort of file operation error may have been reported
by the underlying operating system. Callers can check for these
situations using a program fragment such as the following:
SBMLReader
reader = newSBMLReader
()SBMLDocument
doc = reader.readSBMLFromFile(filename) if (doc.getNumErrors() > 0) { if (doc.getError(0).getErrorId() == libsbmlConstants.XMLFileUnreadable) { // Handle case of unreadable file here. } else if (doc.getError(0).getErrorId() == libsbmlConstants.XMLFileOperationError) { // Handle case of other file operation error here. } else { // Handle other error cases. } }
If the given filename ends with the suffix '.gz'
(for example,
'myfile.xml.gz'
), the file is assumed to be compressed in gzip
format and will be automatically decompressed upon reading.
Similarly, if the given filename ends with '.zip'
or '.bz2'
, the
file is assumed to be compressed in zip or bzip2 format
(respectively). Files whose names lack these suffixes will be read
uncompressed. Note that if the file is in zip format but the
archive contains more than one file, only the first file in the
archive will be read and the rest ignored.
To read a gzip/zip file, libSBML needs to be configured and linked with the zlib library at compile time. It also needs to be linked with the bzip2 library to read files in bzip2 format. (Both of these are the default configurations for libSBML.) Errors about unreadable files will be logged if a compressed filename is given and libSBML was not linked with the corresponding required library.
filename
- the name or full pathname of the file to be read.
SBMLDocument
created from the SBML content.
SBMLError
,
SBMLDocument
public SBMLDocument readSBMLFromString(java.lang.String xml)
This method is flexible with respect to the presence of an XML
declaration at the beginning of the string. In particular, if the
string in xml
does not begin with the XML declaration
<?xml version='1.0' encoding='UTF-8'?>
, then this
method will automatically prepend the declaration to xml
.
This method will log a fatal error if the content given in the
parameter xml
is not SBML. See the method documentation for
SBMLReader.readSBML(String filename)
for an example of code for testing the returned error code.
xml
- a string containing a full SBML model
SBMLDocument
created from the SBML content.
SBMLReader.readSBML(String filename)
SBMLDocument
that uses
the SBML L3 Hierarchical Model
Composition package (comp) the
document location cannot be set automatically. Thus, if the model
contains references to ExternalModelDefinitions, it will be necessary
to manually set the document URI location (setLocationURI) in order
to facilitate resolving these models.