public class SBMLWriter 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 SBMLWriter
class is the converse of SBMLReader
, and provides the
main interface for serializing SBML models into XML and writing the
result to files and text strings. The methods for writing SBML all take
an SBMLDocument
object and a destination. They return a boolean or
integer value to indicate success or failure.
LibSBML provides support for writing (as well as reading) 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
SBMLWriter.writeSBML(SBMLDocument d, String filename)
and SBMLReader.readSBML(String filename)
will automatically compress and decompress the file while writing and
reading it. If the filename has no such extension, it
will be written and read 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
SBMLWriter.hasZlib()
and
SBMLWriter.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 |
---|
SBMLWriter()
Creates a new
SBMLWriter . |
Modifier and Type | Method and Description |
---|---|
void |
delete()
Explicitly deletes the underlying native object.
|
boolean |
equals(Object sb)
Equality comparison method for SBMLWriter.
|
static boolean |
hasBzip2()
Predicate returning
true if this copy of libSBML has been linked
with the bzip2 library. |
int |
hashCode()
Returns a hashcode for this SBMLWriter object.
|
static boolean |
hasZlib()
Predicate returning
true if this copy of libSBML has been linked
with the zlib library. |
int |
setProgramName(String name)
Sets the name of this program, i.e., the program that is about to
write out the
SBMLDocument . |
int |
setProgramVersion(String version)
Sets the version of this program, i.e., the program that is about to
write out the
SBMLDocument . |
boolean |
writeSBML(SBMLDocument d,
OStream stream)
Writes the given SBML document to the output stream.
|
boolean |
writeSBML(SBMLDocument d,
String filename)
Writes the given SBML document to filename.
|
boolean |
writeSBMLToFile(SBMLDocument d,
String filename)
Writes the given SBML document to filename.
|
String |
writeSBMLToString(SBMLDocument d)
Writes the given SBML document to an in-memory string and returns a
pointer to it.
|
public SBMLWriter()
SBMLWriter
.
The libSBML SBMLWriter
objects offer methods for writing SBML in
XML form to 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 SBMLWriter.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 SBMLWriter.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 static boolean hasBzip2()
true
if this copy of libSBML has been linked
with the bzip2 library.
LibSBML supports reading and writing files compressed with either bzip2 or zip/gzip compression. The facility depends on libSBML having been compiled with the necessary support libraries. This method allows a calling program to inquire whether that is the case for the copy of libSBML it is using.
true
if libSBML is linked with bzip2, false
otherwise.
SBMLWriter.hasZlib()
SBMLWriter
), and the other
will be a standalone top-level function with the name
SBMLWriter_hasZlib(). They are functionally identical.
public int hashCode()
public static boolean hasZlib()
true
if this copy of libSBML has been linked
with the zlib library.
LibSBML supports reading and writing files compressed with either bzip2 or zip/gzip compression. The facility depends on libSBML having been compiled with the necessary support libraries. This method allows a calling program to inquire whether that is the case for the copy of libSBML it is using.
true
if libSBML is linked with zlib, false
otherwise.
SBMLWriter.hasBzip2()
SBMLWriter
), and the other
will be a standalone top-level function with the name
SBMLWriter_hasZlib(). They are functionally identical.
public int setProgramName(String name)
SBMLDocument
.
If the program name and version are set (see
SBMLWriter.setProgramVersion(String version)
), the
following XML comment, intended for human consumption, will be written
at the beginning of the XML document:
<!-- Created by <program name> version <program version>
on yyyy-MM-dd HH:mm with libSBML version <libsbml
version>. -->
If the program name and version are not set at some point before calling the writeSBML() methods, no such comment is written out.
name
- the name of this program (where 'this program' refers to
program in which libSBML is embedded, not libSBML itself!)
SBMLWriter.setProgramVersion(String version)
public int setProgramVersion(String version)
SBMLDocument
.
If the program version and name are set (see
SBMLWriter.setProgramName(String name)
), the
following XML comment, intended for human consumption, will be written
at the beginning of the document:
<!-- Created by <program name> version <program version>
on yyyy-MM-dd HH:mm with libSBML version <libsbml
version>. -->
If the program version and name are not set at some point before calling the writeSBML() methods, no such comment is written out.
version
- the version of this program (where 'this program'
refers to program in which libSBML is embedded, not libSBML itself!)
SBMLWriter.setProgramName(String name)
public boolean writeSBML(SBMLDocument d, OStream stream)
d
- the SBML document to be written
stream
- the stream object where the SBML is to be written.
true
on success and false
if one of the underlying
parser components fail (rare).
SBMLWriter.setProgramVersion(String version)
,
SBMLWriter.setProgramName(String name)
public boolean writeSBML(SBMLDocument d, String filename)
If the given filename ends with the suffix ".gz"
(for example, "myfile.xml.gz"
), libSBML assumes the
caller wants the file to be written compressed in gzip format.
Similarly, if the given filename ends with ".zip"
or
".bz2"
, libSBML assumes the caller wants the file to
be compressed in zip or bzip2 format (respectively).
Files whose names lack these suffixes will be written uncompressed.
Special considerations for the zip format: If the given filename
ends with ".zip"
, the file placed in the zip archive
will have the suffix ".xml"
or
".sbml"
. For example, the file in the zip archive
will be named "test.xml"
if the given filename is
"test.xml.zip"
or "test.zip"
.
Similarly, the filename in the archive will be
"test.sbml"
if the given filename is
"test.sbml.zip"
.
d
- the SBML document to be written
filename
- the name or full pathname of the file where the SBML
is to be written.
true
on success and false
if the filename could not be
opened for writing.
SBMLWriter.setProgramVersion(String version)
,
SBMLWriter.setProgramName(String name)
false
if a compressed filename is given and libSBML was
not linked with the corresponding required library.
public boolean writeSBMLToFile(SBMLDocument d, String filename)
If the given filename ends with the suffix ".gz"
(for example, "myfile.xml.gz"
), libSBML assumes the
caller wants the file to be written compressed in gzip format.
Similarly, if the given filename ends with ".zip"
or
".bz2"
, libSBML assumes the caller wants the file to
be compressed in zip or bzip2 format (respectively).
Files whose names lack these suffixes will be written uncompressed.
Special considerations for the zip format: If the given filename
ends with ".zip"
, the file placed in the zip archive
will have the suffix ".xml"
or
".sbml"
. For example, the file in the zip archive
will be named "test.xml"
if the given filename is
"test.xml.zip"
or "test.zip"
.
Similarly, the filename in the archive will be
"test.sbml"
if the given filename is
"test.sbml.zip"
.
d
- the SBML document to be written
filename
- the name or full pathname of the file where the SBML
is to be written.
true
on success and false
if the filename could not be
opened for writing.
SBMLWriter.setProgramVersion(String version)
,
SBMLWriter.setProgramName(String name)
false
if a compressed filename is given and libSBML was
not linked with the corresponding required library.
public String writeSBMLToString(SBMLDocument d)
The string is owned by the caller and should be freed (with free
())
when no longer needed.
d
- the SBML document to be written
0
if one of the underlying parser
components fail.
SBMLWriter.setProgramVersion(String version)
,
SBMLWriter.setProgramName(String name)