public class SBMLConverter extends java.lang.Object
This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. It is a class used in the implementation of extra functionality provided by libSBML.
The SBMLConverter
class is the base class for the various SBML
converters: classes of objects that transform or convert SBML documents.
These transformations can involve essentially anything that can be written
algorithmically examples include converting the units of measurement in a
model, or converting from one Level+Version combination of SBML to
another. Applications can also create their own converters by subclassing
SBMLConverter
and following the examples of the existing converters.
The use of all the converters follows a similar approach. First, one
creates a ConversionProperties
object and calls
ConversionProperties.addOption(ConversionOption)
on this object with one arguments: a text string that identifies the desired
converter. (The text string is specific to each converter consult the
documentation for a given converter to find out how it should be enabled.)
Next, for some converters, the caller can optionally set some
converter-specific properties using additional calls to
ConversionProperties.addOption(ConversionOption)
.
Many converters provide the ability to
configure their behavior to some extent this is realized through the use
of properties that offer different options. The default property values
for each converter can be interrogated using the method
SBMLConverter.getDefaultProperties()
on the converter class in question .
Finally, the caller should invoke the method
SBMLDocument.convert(ConversionProperties)
with the ConversionProperties
object as an argument.
The following code fragment illustrates an example using
SBMLReactionConverter
, which is invoked using the option string
'replaceReactions':
ConversionProperties
props = newConversionProperties
() if (props != null) { props.addOption('replaceReactions') } else { // Deal with error. }
In the case of SBMLReactionConverter
, there are no options to affect
its behavior, so the next step is simply to invoke the converter on
an SBMLDocument
object. Continuing the example code:
// Assume that the variable 'document' has been set to an SBMLDocument
object.
status = document.convert(config)
if (status != libsbml.LIBSBML_OPERATION_SUCCESS)
{
// Handle error somehow.
System.out.println('Error: conversion failed due to the following:')
document.printErrors()
}
Here is an example of using a converter that offers an option. The
following code invokes SBMLStripPackageConverter
to remove the
SBML Level 3 Layout package from a model. It sets the name
of the package to be removed by adding a value for the option named
'package'
defined by that converter:
ConversionProperties
config = newConversionProperties
() if (config != None) { config.addOption('stripPackage') config.addOption('package', 'layout') status = document.convert(config) if (status != LIBSBML_OPERATION_SUCCESS) { // Handle error somehow. System.out.println('Error: unable to strip theLayout
package') document.printErrors() } } else { // Handle error somehow. System.out.println('Error: unable to createConversionProperties
object') }
LibSBML provides a number of built-in converters by convention, their names end in Converter. The following are the built-in converters provided by libSBML 5.13.0 :
CobraToFbcConverter
CompFlatteningConverter
FbcToCobraConverter
FbcV1ToV2Converter
FbcV2ToV1Converter
SBMLFunctionDefinitionConverter
SBMLIdConverter
SBMLInferUnitsConverter
SBMLInitialAssignmentConverter
SBMLLevel1Version1Converter
SBMLLevelVersionConverter
SBMLLocalParameterConverter
SBMLReactionConverter
SBMLRuleConverter
SBMLStripPackageConverter
SBMLUnitsConverter
Constructor and Description |
---|
SBMLConverter()
Creates a new
SBMLConverter object. |
SBMLConverter(SBMLConverter orig)
Copy constructor.
|
SBMLConverter(java.lang.String name)
Creates a new
SBMLConverter object with a given name. |
Modifier and Type | Method and Description |
---|---|
SBMLConverter |
cloneObject()
Creates and returns a deep copy of this
SBMLConverter object. |
int |
convert()
Perform the conversion.
|
void |
delete()
Explicitly deletes the underlying native object.
|
ConversionProperties |
getDefaultProperties()
Returns the default properties of this converter.
|
SBMLDocument |
getDocument()
Returns the SBML document that is the subject of the conversions.
|
java.lang.String |
getName()
Returns the name of this converter.
|
ConversionProperties |
getProperties()
Returns the current properties in effect for this converter.
|
SBMLNamespaces |
getTargetNamespaces()
Returns the target SBML namespaces of the currently set properties.
|
boolean |
matchesProperties(ConversionProperties props)
Returns
true if this converter matches the given properties. |
int |
setDocument(SBMLDocument doc)
Sets the SBML document to be converted.
|
int |
setProperties(ConversionProperties props)
Sets the configuration properties to be used by this converter.
|
public SBMLConverter()
SBMLConverter
object.public SBMLConverter(java.lang.String name)
SBMLConverter
object with a given name.
name
- the name for the converter to createpublic SBMLConverter(SBMLConverter orig)
This creates a copy of an SBMLConverter
object.
orig
- the SBMLConverter
object to copy.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 SBMLConverter.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 SBMLConverter.delete()
themselves.
public SBMLConverter cloneObject()
SBMLConverter
object.
SBMLConverter
object.public SBMLDocument getDocument()
SBMLDocument
object.public ConversionProperties getDefaultProperties()
A given converter exposes one or more properties that can be adjusted
in order to influence the behavior of the converter. This method
returns the default property settings for this converter. It is
meant to be called in order to discover all the settings for the
converter object. The run-time properties of the converter object can
be adjusted by using the method
SBMLConverter.setProperties(ConversionProperties props)
.
SBMLConverter.setProperties(ConversionProperties)
,
SBMLConverter.matchesProperties(ConversionProperties)
public SBMLNamespaces getTargetNamespaces()
SBML namespaces are used by libSBML to express the Level+Version of the
SBML document (and, possibly, any SBML Level 3 packages in
use). Some converters' behavior is affected by the SBML namespace
configured in the converter. For example, in SBMLLevelVersionConverter
(the converter for converting SBML documents from one Level+Version
combination to another), the actions are fundamentally dependent on the
SBML namespaces targeted.
SBMLNamespaces
object that describes the SBML namespaces
in effect, or null
if none are set.public boolean matchesProperties(ConversionProperties props)
true
if this converter matches the given properties.
Given a ConversionProperties
object props
, this method checks that
props
possesses an option value to enable this converter. If it does,
this method returns true.
props
- the properties to match.
true
if the properties props
would match the necessary
properties for this type of converter, false
otherwise.public int setDocument(SBMLDocument doc)
doc
- the document to use for this conversion.
SBMLConverter
being used, but the default method can return the
following:
public int setProperties(ConversionProperties props)
props
- the ConversionProperties
object defining the properties
to set.
SBMLConverter
being used, but the default method can return the
following values:
SBMLConverter.getProperties()
,
SBMLConverter.matchesProperties(ConversionProperties)
public ConversionProperties getProperties()
A given converter exposes one or more properties that can be adjusted
in order to influence the behavior of the converter. This method
returns the current properties for this converter in other words, the
settings in effect at this moment. To change the property values, you
can use SBMLConverter.setProperties(ConversionProperties props)
.
SBMLConverter.setProperties(ConversionProperties)
,
SBMLConverter.matchesProperties(ConversionProperties)
public int convert()
This method causes the converter to do the actual conversion work,
that is, to convert the SBMLDocument
object set by
SBMLConverter.setDocument(SBMLDocument)
and
with the configuration options set by
SBMLConverter.setProperties(ConversionProperties)
.
public java.lang.String getName()