BiVeS – Java API

Using BiVeS from within your Java application is no big deal.

Snippets

Here we collect some code snippets to boost the integration process.

Get The type of a document

1
2
3
4
5
6
7
8
9
10
DocumentClassifier classifier = new DocumentClassifier ();
// the bits in type indicate the type of the file
int type = classifier.classify (file);
// use bitwise operations to identify the type of this document
if (type != (DocumentClassifier.SBML | DocumentClassifier.XML))
  System.out.println ("this is not SBML!");
if ((type & DocumentClassifier.CELLML) != 0)
  System.out.println ("this is CellML");
if ((type & DocumentClassifier.XML) != 0 && (type & (DocumentClassifier.SBML | DocumentClassifier.CELLML)) == 0)
  System.out.println ("this is xml, but neither cellml nor sbml.");

please note that if the classifier classifies a document to be SBML it still does not have to be valid SBML. Our parsers are very permissive.

Just to give you an idea the bits in the classification result are set as:

  • 21 — XML
  • 22 — SBML
  • 24 — CellML

But please do not rely on these numbers, since they might change in the next release. Better use the constants from DocumentClassifier.*.

Difference Detection…

There is an abstract class de.unirostock.sems.bives.api.Diff, its subclasses facilitate the mapping of two XML trees:

.. of two XML files

1
2
RegularDiff differ = new RegularDiff (file1, file2);
differ.mapTrees ();

.. of two SBML files

1
2
3
4
File modelA = new File ("/path/to/modelA");
File modelB = new File ("/path/to/modelB");
SBMLDiff differ = new SBMLDiff (modelA, modelB);
differ.mapTrees ();

.. of two cellML files

1
2
3
4
File modelA = new File ("/path/to/modelA");
File modelB = new File ("/path/to/modelB");
CellMLDiff differ = new CellMLDiff (modelA, modelB);
differ.mapTrees ();

.. of two yet unknown files

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
File modelA = new File ("/path/to/modelA");
File modelB = new File ("/path/to/modelB");
DocumentClassifier classifier = new DocumentClassifier ();
int typeA = classifier.classify (modelA);
int typeB = classifier.classify (modelB);
// here the magic begins
Diff differ = null;
if ((type & DocumentClassifier.CELLML) != 0)
  differ = new CellMLDiff (file1, file2);
else if ((type & DocumentClassifier.SBML) != 0)
  differ = new CellMLDiff (file1, file2);
else if ((type & DocumentClassifier.XML) != 0)
  differ = new CellMLDiff (file1, file2);
else
  throw new SomeCrazyException ("unable to recognize file type..");
differ.mapTrees ();

Evaluate the Mapping

When both trees are mapped BiVeS is able to export the result in various formats:

Get the XML Patch

1
String patch = differ.getDiff ();

Get the Highlighted Chemical Reaction Network

1
2
3
4
// get the graph encoded in GraphML
String graph = differ.getCRNGraphML ();
// get the graph encoded in Dot
String graph = differ.getCRNDotGraph ();

Get the Highlighted Component Hierarchy (CellML only)

1
2
3
4
// get the graph encoded in GraphML
String graph = differ.getHierarchyGraphML ();
// get the graph encoded in Dot
String graph = differ.getHierarchyDotGraph ();

Get the Report

1
2
3
4
// get the report in HTML format
String html = differ.getHTMLReport ();
// get the report encoded in MarkDown
String md = differ.getMarkDownReport ();

Full Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
File modelA = new File ("/path/to/modelA");
File modelB = new File ("/path/to/modelB");

// get the type of the documents
DocumentClassifier classifier = new DocumentClassifier ();
int typeA = classifier.classify (modelA);
int typeB = classifier.classify (modelB);

Diff differ = null;

// what flags have both in common
int common = typeA & typeB;
if ((common & DocumentClassifier.SBML) != 0)
  // both are SBML documents
  differ = new SBMLDiff (modelA, modelB);
else if ((common & DocumentClassifier.CELLML) != 0)
  // both are CellML files
  differ = new CellMLDiff (modelA, modelB);
else if ((common & DocumentClassifier.XML) != 0)
  // both are XML
  differ = new RegularDiff (modelA, modelB);
else
  // at least one of them is not valid XML
  throw new MyCrazyException ("cannot compare these non-XML files");

// map the trees
differ.mapTrees ();

// display some results
System.out.println ("the xml diff: " + differ.getDiff ());
System.out.println ("the highlighted chemical reaction network encoded in GraphML: " + differ.getCRNGraphML ());
System.out.println ("the highlighted chemical reaction network encoded in Dot: " + differ.getCRNDotGraph ());
System.out.println ("the highlighted component hierarchy encoded in GraphML: " + differ.getHierarchyGraphML ());
System.out.println ("the highlighted component hierarchy encoded in Dot: " + differ.getHierarchyDotGraph ());
System.out.println ("the HTML report: " + differ.getHTMLReport ());
System.out.println ("the MarkDown report: " + differ.getMarkDownReport ());