Deserialising KGCL-DSL

Use the KGCLReader class to deserialise a changeset from a KGCL-DSL file:

import java.util.List;
import org.incenp.obofoundry.kgcl.KGCLReader;
import org.incenp.obofoundry.kgcl.model.Change;

try {
    KGCLReader reader = new KGCLReader("my-changeset.kgcl");
    if ( reader.read() ) {
        // Parsing successful, get the actual changes
        List<Change> changeset = reader.getChangeSet();
    } else {
        // Invalid KGCL instructions, get details about the errors
        List<KGCLSyntaxError> errors = reader.getErrors();
    }
} catch ( IOException ioe ) {
    // A non-KGCL-specific I/O error occurred
}

To parse KGCL instructions from a String, you can either call the KGCLReader constructor with a StringReader object:

import java.io.StringReader;

StringReader kgcl = new StringReader("obsolete EX:0001");
KGCLReader reader = new KGCLReader(kgcl);

or you can use the argument-less constructor and pass the string containing the KGCL instructions to the read() method – this form allows to use the same reader object to parse several strings by repeatedly calling the read() method, before getting all the accumulated changes at the end with getChangeSet():

KGCLReader reader = new KGCLReader();
reader.read("create class EX:0002 'my new class'");
reader.read("obsolete EX:0001 with replacement EX:0002");
if ( ! reader.hasErrors() ) {
    List<Change> changeset = reader.getChangeSet();
}

Serialising KGCL-DSL

Use the KGCLwriter class to serialise a KGCL change(set) into a KGCL-DSL file:

import org.incenp.obofoundry.kgcl.KGCLWriter;

List<Change> changeset = ...; // the changeset to serialise
try {
    KGCLWriter writer = new KGCLWriter("my-changeset.kgcl");
    writer.write(changeset);
    writer.close();
} catch ( IOException ioe ) {
    // A non-KGCL-specific I/O error occurred
}

To get the serialised KGCL as a string, you can either write to a StringWriter object rather than a file, or use instead the KGCLTextTranslator class (which is used internally by KGCLWriter to get the text representation of a KGCL change object):

import org.incenp.obofoundry.kgcl.KGCLTextTranslator;

Change change = ...; // the change to serialise
KGCLTextTranslator translator = new KGCLTextTranslator();
String kgcl = change.accept(translator);

Identifying nodes using shortened identifiers or labels

If the KGCL instructions to parse reference nodes using shortened identifiers (a.k.a “CURIEs”, such as EX:0001), the KGCLReader object may be provided with a PrefixManager from the OWLAPI to automatically resolve any shortened identifier into its corresponding full-length IRI:

import org.semanticweb.owlapi.model.PrefixManager;

PrefixManager pm = ...; // Obtain a PrefixManager suitable for the
                        // prefixes used in the changeset
KGCLReader reader = new KGCLReader("my-changeset.kgcl");
reader.setPrefixManager(pm);
reader.read();

Note that all the classes of the KGCL library that manipulate KGCL objects, and in particular the classes that can be used to apply a changeset to a OWL ontology, assume that the KGCL objects contain full-length identifiers only instead of shortened identifiers, so using a PrefixManager at the parsing stage to automatically resolve all shortened identifiers is strongly recommended.

Alternatively, rather than a PrefixManager object, the reader may be provided with a map of prefix names to prefixes, using the setPrefixMap() method.

When serialising, the KGCLWriter object may likewise be provided with a PrefixManager or a prefix map so that identifiers may be written in shortened form.

The KGCL-DSL syntax also allows referencing nodes using their labels rather than their identifiers. For that to be possible, the KGCLReader object must be provided with an implementation of the LabelResolver object so that the labels can be resolved into proper identifiers. The library provides an implementation that can resolve labels based on a OWL ontology:

import org.semanticweb.owlapi.model.OWLOntology;
import org.incenp.obofoundry.kgcl.owl.OntologyBasedLabelResolver;

OWLOntology ont = ...; // the ontology to apply the changes to
KGCLReader reader = new KGCLReader("my-changeset.kgcl");
reader.setLabelResolver(new OntologyBasedLabelResolver(ont));