ChAO API

Accessing the collaboration features programmatically (The Changes and Annotations API)

Protege provides support for collaboration through the Collaborative Protege extension: e.g., tracking changes, annotating ontology components (classes, properties, etc.) or changes (creation of a class). This wiki page describes how to access the change tracking and the annotation information programatically.

Other relevant documentation: the Changes Tab, the Collaborative Protege paper, the paper describing the Changes and Annotation ontology.

The change tracking information and annotation of ontology entities and changes is stored as instances of the Changes and Annotation Ontology (ChAO), called the ChAO KB. This wiki page shows how to access this information programmatically.

The ChAO KB Manager

One of the most important classes is the edu.stanford.bmir.protegex.chao.ChAOKbManager found in the change-model.jar from the edu.stanford.smi.protegex.changes plugin folder. It contains methods for creating and retrieving the ChAO KB for different modes: stand-alone, multi-user client and multi-user server. All code should use the method:

public static KnowledgeBase getChAOKb(KnowledgeBase kb)

to get access to the ChAO KB associated to kb.

Create a ChAO KB stored in RDF(S) files (default)

You may also create the ChAO KB. To create a ChAO KB stored in RDF(S) files (default option), call:

public static KnowledgeBase createRDFFileChAOKb(KnowledgeBase kb, URI chaoURI) 

Code example:

private KnowledgeBase void createCHAOFileProject() {
   //load the project
   Project prj = Project.loadProjectFromFile("/tmp/pizza.pprj", new ArrayList());
   OWLModel owlModel = (OWLModel) prj.getKnowledgeBase();
   //create the ChAO KB
   KnowledgeBase changesKb = ChAOKbManager.createRDFFileChAOKb(owlModel, ChAOKbManager.getChAOProjectURI(owlModel));
   //save the ChAO
   ArrayList errors = new ArrayList();
   changesKb.getProject().save(errors);
   //optional to save also the main project. It helps if the ChAO project does not have the default name
   prj.save(errors);
   return changesKb;
}

Create a ChAO KB stored in a database

To create the ChAO KB stored in a database, call:

public static KnowledgeBase createDbChAOKb(KnowledgeBase kb, URI chaoURI, String dbDriver, String dbUrl, String dbTable, String dbUser, String dbPassword)

Code example:

private KnowledgeBase void createCHAOFileProject() {
   //load the project
   Project prj = Project.loadProjectFromFile("/tmp/pizza.pprj", new ArrayList());
   OWLModel owlModel = (OWLModel) prj.getKnowledgeBase();
   //create the ChAO KB
    KnowledgeBase changesKb = ChAOKbManager.createDbChAOKb(owlModel, ChAOKbManager.getChAOProjectURI(owlModel), "com.mysql.jdbc.Driver", "jdbc:mysql://localhost/protege", "myTableName", "myUser", "myPassword");
   //save the ChAO
   ArrayList errors = new ArrayList();
   changesKb.getProject().save(errors);
   //optional to save also the main project. It helps if the ChAO project does not have the default name
   prj.save(errors);
   return changesKb;
}

Accessing the annotation information

The access to the annotation information is done through the edu.stanford.bmir.protegex.chao.annotation.api.AnnotationFactory class found in the change-model.jar from the edu.stanford.smi.protegex.changes plugin folder. The name of the methods are quite self evident. The code for the AnnotationFactory has been generated from the ChAO ontology. For example, if in the ontology there is a class Annotation that has a slot attached to it, author, then the generated Java interface Annotation will have a method getAuthor().

Get all annotations

Example of how to print all annotations of a pizza.pprj file (stored in a ChAOKB project, for example annotation_pizza.pprj).

private void printAllAnnotations() {
   Project prj = Project.loadProjectFromFile("/tmp/pizza.pprj", new ArrayList());
   KnowledgeBase kb = prj.getKnowledgeBase();
   AnnotationFactory factory = new AnnotationFactory(ChAOKbManager.getChAOKb(kb));
   Collection<Annotation> annotations = factory.getAllAnnotationObjects(true);
   for (Annotation annotation : annotations) {
       System.out.println("\nAuthor: " + annotation.getAuthor());
       System.out.println("Date: " + annotation.getCreated().getDate());
       System.out.println("Body: " + annotation.getBody());
    }
}

Get annotations associated to an ontology entity

Below is an example of how to get the annotations associated to a class "Pizza". (It works also with Frames and other backends)

 OWLModel owlModel = ...
 AnnotationFactory factory = new AnnotationFactory(ChAOKbManager.getChAOKb(owlModel));
 Ontology_Component oc = ChAOUtil.getOntologyComponent(owlModel.getOWLNamedClass("Pizza"));
 Collection annotations = oc.getAssociatedAnnotations();
 //then use code similar to printAllAnnotations from above

Create an annotation on an ontology component

Example of how to create a comment on class Pizza:

  OWLModel owlModel = ...
  AnnotationFactory factory = new AnnotationFactory(ChAOKbManager.getChAOKb(owlModel));
  Ontology_Component oc = ChAOUtil.getOntologyComponent(owlModel.getOWLNamedClass("Pizza"));

  Comment comment = factory.createComment(null);
  factory.fillDefaultValues(comment); //fills in creation date and author
  comment.setBody("I know this class from somewhere..");

  oc.addAssociatedAnnotations(comment);

Accessing the changes information

The access to the change information is done through the <codeedu.stanford.bmir.protegex.chao.change.api.ChangeFactory</code> class found in the change-model.jar from the edu.stanford.smi.protegex.changes plugin folder. The name of the methods are quite self evident. The code for the ChangeFactory has been generated from the ChAO ontology. For example, if in the ontology there is a class Class_Create that has a slot attached to it, author, then the generated Java interface Class_Create will have a method getAuthor().

Get all changes

The code below shows how to get all changes from a ChAO KB.

private void printAllChanges() {
   Project prj = Project.loadProjectFromFile("/tmp/pizza.pprj", new ArrayList());
   KnowledgeBase kb = prj.getKnowledgeBase();
   ChangeFactory factory = new ChangeFactory(ChAOKbManager.getChAOKb(kb));
  
   Collection<Change> changes = factory.getAllChangeObjects(true);
   for (Change change : changes) {
        System.out.println("\nAuthor: " + change.getAuthor());
       System.out.println("Date: " + change.getTimestamp().getDate());
       System.out.println("Change on: " + change.getApplyTo().getCurrentName());
       System.out.println("Description of change: " + change.getContext());
  }
}

Get the changes associated to an ontology entity

Code below shows how to get all changes for a class Pizza.

 OWLModel owlModel = ...
 Ontology_Component oc = ChAOUtil.getOntologyComponent(owlModel.getOWLNamedClass("Pizza"));
 Collection<Change> changes = oc.getChanges();
 //then use code similar to printAllChanges from above

What you need in your classpath to use the Changes and Annotations API

To use the Changes and Annotations API, you need to include in your classpath:

• from plugins/edu.stanford.smi.protegex.changes:
  • change_model.jar
  • changes_management.jar

• from plugins/edu.stanford.smi.protege.collab:
  • protege-collab.jar (temporary - won't be needed in future versions)

And of course, the protege.jar, and the jars from the protege-owl directory (if you use OWL).