org.sbml.jsbml

Class JSBML

java.lang.Object

org.sbml.jsbml.JSBML

public class JSBML
extends java.lang.Object

Wrapper class for global methods and constants defined by JSBML.

Since:

0.8

Author:

Andreas Dräger, Nicolas Rodriguez

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	CHILD_ELEMENT_NAMES Key used to store the list of the xml child element names of an SBase.
static int	DUPLICATE_OBJECT_ID
static java.lang.String	ILLEGAL_UNIT_EXCEPTION_MSG Error message for the case that an invalid unit identifier is to be added to this object.
static int	INDEX_EXCEEDS_SIZE
static int	INVALID_ATTRIBUTE_VALUE
static int	INVALID_OBJECT
static int	INVALID_XML_OPERATION
private static java.lang.String	jsbmlVersion The current version number of JSBML.
static int	LEVEL_MISMATCH
static int	OPERATION_FAILED
static int	OPERATION_SUCCESS
static java.lang.String	PIECEWISE_ID Key used to store the real parent element for each child of a ASTNode.Type.FUNCTION_PIECEWISE ASTNode.
static java.lang.String	READING_IN_PROGRESS
static java.lang.String	UNDEFINED_MODEL_MSG This indicates that the Model has not been set properly or that an element tries to access its containing model but this is not possible.
static java.lang.String	UNDEFINED_PARSE_ERROR_MSG This message indicates that a problem occurred but the current class cannot give any more precise information about the reasons.
static java.lang.String	UNDEFINED_PARSING_ERROR_MSG This message indicates that a problem occurred but the current class cannot give any more precise information about the reasons.
static int	UNEXPECTED_ATTRIBUTE
static java.lang.String	UNKNOWN_XML Key used to store any unknown XML encountered while reading an SBML file.
static java.lang.String	URI_PURL_ELEMENTS URI for the definition of purl elements
static java.lang.String	URI_PURL_TERMS URI for purl terms.
static java.lang.String	URI_XHTML_DEFINITION URI for the definition of XHTML.
static int	VERSION_MISMATCH

Constructor Summary

Constructors

Constructor and Description
JSBML()

Method Summary

Modifier and Type	Method and Description
static java.lang.String	addUnitDefinitionIfNotContained(Model model, UnitDefinition units) Adds the given UnitDefinition to the given model or returns the identifier of an equivalent UnitDefinition that is already part of the model.
static java.lang.String	formulaToString(ASTNode node) Converts an ASTNode formula to a text string using a specific syntax for mathematical formulas.
static java.lang.String	getJSBMLDottedVersion() Returns the JSBML version as a string of the form '1.2.3'.
static int	getJSBMLVersion() Returns the JSBML version as an integer: version 1.2.3 becomes 123.
static java.lang.String	getJSBMLVersionString() Returns the JSBML version as a string: version 1.2.3 becomes '123'.
static java.lang.String	getNamespaceFrom(int level, int version)
static <T> void	loadClasses(java.lang.String path, java.util.Map<java.lang.String,java.lang.Class<? extends T>> whereToPutProperties) Loads Properties from a configuration file with the given path assuming that all values represent class names.
static ASTNode	parseFormula(java.lang.String formula) Parses a text-string mathematical formula and returns a representation as an Abstract Syntax Tree.
static ASTNode	readMathMLFromString(java.lang.String xml) Reads the MathML from the given XML string, constructs a corresponding abstract syntax tree, and returns a pointer to the root of the tree.
static SBMLDocument	readSBML(java.lang.String fileName) Reads an SBML document from the given file.
static SBMLDocument	readSBMLFromFile(java.lang.String fileName) Reads an SBML document from the given file.
static SBMLDocument	readSBMLFromString(java.lang.String xml) Reads an SBML document from a string assumed to be in XML format.
static java.lang.String	writeMathMLToString(ASTNode node) Writes the given ASTNode (and its children) to a string as MathML, and returns the string.
static void	writeSBML(SBMLDocument d, java.lang.String filename) Writes the XML representation of an SBML document to a file.
static java.lang.String	writeSBMLToString(SBMLDocument d) Writes the given SBML document to an in-memory string.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DUPLICATE_OBJECT_ID

public static final int DUPLICATE_OBJECT_ID

See Also:

Constant Field Values

ILLEGAL_UNIT_EXCEPTION_MSG

public static final java.lang.String ILLEGAL_UNIT_EXCEPTION_MSG

Error message for the case that an invalid unit identifier is to be added to this object.

See Also:

Constant Field Values

INDEX_EXCEEDS_SIZE

public static final int INDEX_EXCEEDS_SIZE

See Also:

Constant Field Values

INVALID_ATTRIBUTE_VALUE

public static final int INVALID_ATTRIBUTE_VALUE

See Also:

Constant Field Values

INVALID_OBJECT

public static final int INVALID_OBJECT

See Also:

Constant Field Values

INVALID_XML_OPERATION

public static final int INVALID_XML_OPERATION

See Also:

Constant Field Values

jsbmlVersion

private static final java.lang.String jsbmlVersion

The current version number of JSBML.

See Also:

Constant Field Values

LEVEL_MISMATCH

public static final int LEVEL_MISMATCH

See Also:

Constant Field Values

OPERATION_FAILED

public static final int OPERATION_FAILED

See Also:

Constant Field Values

OPERATION_SUCCESS

public static final int OPERATION_SUCCESS

See Also:

Constant Field Values

UNDEFINED_MODEL_MSG

public static final java.lang.String UNDEFINED_MODEL_MSG

This indicates that the Model has not been set properly or that an element tries to access its containing model but this is not possible.

See Also:

Constant Field Values

UNDEFINED_PARSE_ERROR_MSG

public static final java.lang.String UNDEFINED_PARSE_ERROR_MSG

This message indicates that a problem occurred but the current class cannot give any more precise information about the reasons.

See Also:

Constant Field Values

UNDEFINED_PARSING_ERROR_MSG

public static final java.lang.String UNDEFINED_PARSING_ERROR_MSG

This message indicates that a problem occurred but the current class cannot give any more precise information about the reasons.

See Also:

Constant Field Values

UNEXPECTED_ATTRIBUTE

public static final int UNEXPECTED_ATTRIBUTE

See Also:

Constant Field Values

VERSION_MISMATCH

public static final int VERSION_MISMATCH

See Also:

Constant Field Values

URI_PURL_TERMS

public static final transient java.lang.String URI_PURL_TERMS

URI for purl terms.

See Also:

Constant Field Values

URI_PURL_ELEMENTS

public static final transient java.lang.String URI_PURL_ELEMENTS

URI for the definition of purl elements

See Also:

Constant Field Values

URI_XHTML_DEFINITION

public static final transient java.lang.String URI_XHTML_DEFINITION

URI for the definition of XHTML.

See Also:

Constant Field Values

READING_IN_PROGRESS

public static final transient java.lang.String READING_IN_PROGRESS

See Also:

Constant Field Values

PIECEWISE_ID

public static final transient java.lang.String PIECEWISE_ID

Key used to store the real parent element for each child of a ASTNode.Type.FUNCTION_PIECEWISE ASTNode.

See Also:

Constant Field Values

UNKNOWN_XML

public static final transient java.lang.String UNKNOWN_XML

Key used to store any unknown XML encountered while reading an SBML file.

See Also:

Constant Field Values

CHILD_ELEMENT_NAMES

public static final transient java.lang.String CHILD_ELEMENT_NAMES

Key used to store the list of the xml child element names of an SBase. It later allows us to validate the order or check if any elements are duplicated.

See Also:

Constant Field Values

Constructor Detail

JSBML

public JSBML()

Method Detail

addUnitDefinitionIfNotContained

public static java.lang.String addUnitDefinitionIfNotContained(Model model,
                                                               UnitDefinition units)

Adds the given UnitDefinition to the given model or returns the identifier of an equivalent UnitDefinition that is already part of the model. In case that the given model is null, the return value of this method will also be null.

Parameters:

model - The model where to add the given UnitDefinition

units - The UnitDefinition to be checked and possibly added to the given Model

Returns:

The identifier of the given UnitDefinition if this one has been added to the given model, the identifier of an equivalent UnitDefinition that is already part of the given model, or null.

formulaToString

public static java.lang.String formulaToString(ASTNode node)
                                        throws SBMLException

Converts an ASTNode formula to a text string using a specific syntax for mathematical formulas.

The text-string form of mathematical formulas produced by ASTNode.formulaToString(ASTNode) and read by ASTNode.parseFormula(String) are simple C-inspired infix notation taken from SBML Level 1. A formula in this text-string form therefore can be handed to a program that understands SBML Level 1 mathematical expressions, or used as part of a formula translation system. The syntax is described in detail in the libsbml documentation for ASTNode.

Be careful that the default FormulaCompilerLibSBML used produce an output a bit different than pure SBML level 1 mathematical expressions, in particular for logical and relational operators. If the default output is not convenient for you, you can easily extends one of the existing FormulaCompiler and overwrite the methods where you want a different output.

Parameters:

node - the root of the ASTNode formula expression tree

Returns:

the formula from the given AST as an SBML Level 1 text-string mathematical formula. null is returned if the given argument is null.

Throws:

SBMLException - In case the given ASTNode tree contains invalid nodes.

See Also:

ASTNode.toFormula(), ASTNode.toFormula(FormulaCompiler), FormulaCompiler, FormulaCompilerLibSBML, LibSBMLFormulaCompiler, FormulaCompilerNoPiecewise

getJSBMLDottedVersion

public static java.lang.String getJSBMLDottedVersion()

Returns the JSBML version as a string of the form '1.2.3'.

Returns:

the JSBML version as a string of the form '1.2.3'.

getJSBMLVersion

public static int getJSBMLVersion()

Returns the JSBML version as an integer: version 1.2.3 becomes 123.

Returns:

the JSBML version as an integer: version 1.2.3 becomes 123.

getJSBMLVersionString

public static java.lang.String getJSBMLVersionString()

Returns the JSBML version as a string: version 1.2.3 becomes '123'.

Returns:

the JSBML version as a string: version 1.2.3 becomes '123'.

loadClasses

public static <T> void loadClasses(java.lang.String path,
                                   java.util.Map<java.lang.String,java.lang.Class<? extends T>> whereToPutProperties)

Loads Properties from a configuration file with the given path assuming that all values represent class names.

Type Parameters:

T -

Parameters:

path -

whereToPutProperties -

parseFormula

public static ASTNode parseFormula(java.lang.String formula)
                            throws ParseException

Parses a text-string mathematical formula and returns a representation as an Abstract Syntax Tree.

Support the syntax defined in FormulaParserLL3 which is almost the same syntax as defined in the LibSBML L3 parser. The things not supported for now are the units associated with numbers.

Parsing of the various MathML functions and constants are all case-sensitive by default: names such as 'Cos' and 'COS' are not parsed as the MathML cosine operator, '<cos>'. As well, if you have an SBML entities (species, parameter, ...) that has an id identical to one of the supported mathML element, the parser will interpret the String as the mathML element and not the SBML entity.

You can change this behaviour by using the FormulaParserLL3.setCaseSensitive(boolean) method and using the ASTNode.parseFormula(String, IFormulaParser) method instead of this one:

   FormulaParserLL3 caseSensitiveParser = new FormulaParserLL3(new StringReader(""));
   caseInsensitiveParser.setCaseSensitive(false);
   ASTNode n = ASTNode.parseFormula("Cos(x)", caseInsensitiveParser);

This method has a different behaviour since JSBML-1.0 compare to JSBML-0.8. There is a different operator precedence, the parsing is now case sensitive for mathML elements and boolean operators are now differently interpreted: '&&' and '||' are used instead of 'and' and 'or'.
If you want to use the parser used in JSBML-0.8, you can do that by using the FormulaParser parser class and using the ASTNode.parseFormula(String, IFormulaParser) method instead of this one:

   FormulaParser oldParser = new FormulaParser(new StringReader(""));

   ASTNode n = ASTNode.parseFormula("x and y", oldParser);

If you are not satisfied with the behaviour of the existing parsers, you can create your own, you just need to implement the IFormulaParser interface.

Parameters:

formula - a text-string mathematical formula.

Returns:

an ASTNode representing the formula.

Throws:

ParseException - If the given formula is not of valid format or cannot be parsed for other reasons.

See Also:

ASTNode.parseFormula(String), ASTNode.parseFormula(String, IFormulaParser), FormulaParserLL3, FormulaParser

readMathMLFromString

public static ASTNode readMathMLFromString(java.lang.String xml)

Reads the MathML from the given XML string, constructs a corresponding abstract syntax tree, and returns a pointer to the root of the tree.

Parameters:

xml - the MathML XML string.

Returns:

an ASTNode

readSBML

public static SBMLDocument readSBML(java.lang.String fileName)
                             throws javax.xml.stream.XMLStreamException,
                                    java.io.IOException

Reads an SBML document from the given file.

Parameters:

fileName - the file name.

Returns:

an SBMLDocument object.

Throws:

javax.xml.stream.XMLStreamException - if any error occur while creating the XML document.

java.io.IOException - if the file does not exist or cannot be read.

readSBMLFromFile

public static SBMLDocument readSBMLFromFile(java.lang.String fileName)
                                     throws javax.xml.stream.XMLStreamException,
                                            java.io.IOException

Reads an SBML document from the given file.

Parameters:

fileName - the file name.

Returns:

an SBMLDocument object.

Throws:

javax.xml.stream.XMLStreamException - if any error occur while creating the XML document.

java.io.IOException - if the file does not exist or cannot be read.

readSBMLFromString

public static SBMLDocument readSBMLFromString(java.lang.String xml)
                                       throws javax.xml.stream.XMLStreamException

Reads an SBML document from a string assumed to be in XML format.

Parameters:

xml - the SBMLDocument as XML.

Returns:

an SBMLDocument object.

Throws:

javax.xml.stream.XMLStreamException - if any error occur while creating the XML document.

writeMathMLToString

public static java.lang.String writeMathMLToString(ASTNode node)
                                            throws javax.xml.stream.XMLStreamException,
                                                   SBMLException

Writes the given ASTNode (and its children) to a string as MathML, and returns the string.

Parameters:

node - the ASTNode

Returns:

the MathML string representing the given ASTNode

Throws:

javax.xml.stream.XMLStreamException

SBMLException

writeSBML

public static void writeSBML(SBMLDocument d,
                             java.lang.String filename)
                      throws javax.xml.stream.XMLStreamException,
                             SBMLException,
                             java.io.IOException

Writes the XML representation of an SBML document to a file.

Parameters:

d - the SBMLdocument

filename - the file name

Throws:

javax.xml.stream.XMLStreamException - if any error occur while creating the XML document.

SBMLException

java.io.IOException - if an I/O error occurs.

writeSBMLToString

public static java.lang.String writeSBMLToString(SBMLDocument d)
                                          throws javax.xml.stream.XMLStreamException,
                                                 SBMLException

Writes the given SBML document to an in-memory string.

Parameters:

d - the SBMLDocument

Returns:

the XML representation of the SBMLDocument as a String.

Throws:

javax.xml.stream.XMLStreamException - if any error occur while creating the XML document.

SBMLException

getNamespaceFrom

public static java.lang.String getNamespaceFrom(int level,
                                                int version)

Parameters:

level -

version -

Returns:

the name space matching the level and version.