public class SBMLLevelVersionConverter extends SBMLConverter
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.
This SBML converter takes an SBML document having one SBML Level+Version combination, and attempts to convert it to an SBML document having a different Level+Version combination.
This class is also the basis for
SBMLDocument.setLevelAndVersion(long, long, boolean)
.
SBMLLevelVersionConverter
SBMLLevelVersionConverter
is enabled by creating a ConversionProperties
object with the option 'setLevelAndVersion'
, and passing this
properties object to SBMLDocument.convert(ConversionProperties)
. The target SBML Level and Version
combination are determined by the value of the SBML namespace set on the
ConversionProperties
object (using
ConversionProperties.setTargetNamespaces(SBMLNamespaces targetNS)
).
In addition, this converter offers the following options:
'strict':
If this option has the value true
, then the validity
of the SBML document will be strictly preserved. This means that SBML
validation will be performed, and if the original model is not valid or
semantics cannot be preserved in the converted model, then conversion will
not be performed. Conversely, if this option is set to false
, model
conversion will always be performed if any errors are detected related to
altered semantics, the errors will be logged in the usual way (i.e., the
error log on the SBMLDocument
object).
'addDefaultUnits':
By default, a conversion from SBML Level 2
to Level 3 will explicitly add UnitDefinition
objects and unit
attributes on the Model
object to define units that are implicitly defined
in SBML Level 2. This is usually desirable because in SBML
Level 3, there are no default units and a conversion from
Level 2 that did not add unit definitions would actually result
in a loss of information. However, some users or software tools may not
need or want this, or worse, may be fooled into thinking that libSBML has
somehow inferred the proper units for model quantities. (It has not it
merely adds generic predefined units.) This option lets callers control
this behavior.
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 |
---|
SBMLLevelVersionConverter()
Creates a new
SBMLLevelVersionConverter object. |
SBMLLevelVersionConverter(SBMLLevelVersionConverter obj)
Copy constructor creates a copy of an
SBMLLevelVersionConverter
object. |
Modifier and Type | Method and Description |
---|---|
SBMLConverter |
cloneObject()
Creates and returns a deep copy of this
SBMLLevelVersionConverter
object. |
int |
convert()
Perform the conversion.
|
void |
delete()
Explicitly deletes the underlying native object.
|
boolean |
getAddDefaultUnits()
Returns the flag indicating whether default units should be added when
converting to L3 or not.
|
ConversionProperties |
getDefaultProperties()
Returns the default properties of this converter.
|
long |
getTargetLevel()
Returns the target SBML Level for the conversion.
|
long |
getTargetVersion()
Returns the target SBML Version for the conversion.
|
boolean |
getValidityFlag()
Returns the flag indicating whether the conversion has been set to 'strict'.
|
boolean |
matchesProperties(ConversionProperties props)
Returns
true if this converter object's properties match the given
properties. |
getDocument, getName, getProperties, getTargetNamespaces, setDocument, setProperties
public SBMLLevelVersionConverter()
SBMLLevelVersionConverter
object.public SBMLLevelVersionConverter(SBMLLevelVersionConverter obj)
SBMLLevelVersionConverter
object.
obj
- the SBMLLevelVersionConverter
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 SBMLLevelVersionConverter.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 SBMLLevelVersionConverter.delete()
themselves.
delete
 in class SBMLConverter
public SBMLConverter cloneObject()
SBMLLevelVersionConverter
object.
cloneObject
 in class SBMLConverter
public boolean matchesProperties(ConversionProperties props)
true
if this converter object's properties match the given
properties.
A typical use of this method involves creating a ConversionProperties
object, setting the options desired, and then calling this method on
an SBMLLevelVersionConverter
object to find out if the object's
property values match the given ones. This method is also used by
SBMLConverterRegistry.getConverterFor(ConversionProperties)
to search across all registered converters for one matching particular
properties.
matchesProperties
 in class SBMLConverter
props
- the properties to match.
true
if this converter's properties match, false
otherwise.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)
.
convert
 in class SBMLConverter
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.
getDefaultProperties
 in class SBMLConverter
ConversionProperties
object describing the default properties
for this converter.SBMLConverter.setProperties(ConversionProperties)
,
SBMLConverter.matchesProperties(ConversionProperties)
public long getTargetLevel()
public long getTargetVersion()
public boolean getValidityFlag()
true
if strict validity has been requested, false
otherwise.public boolean getAddDefaultUnits()
true
if default units should be added, false
otherwise.