Skip to content

Plugins how to use existing and custom annotation data models

Jump to bottom Edit New page
Yifan NIng edited this page Apr 25, 2014 · 11 revisions

1 Overview

All annotations created in Domeo by any plugin will be stored in a version of [the Open Annotation model](http://www.openannotation.org/spec/core/). As of this writing, the specific annotation model is the original [Annotation Ontology](https://code.google.com/p/annotation-ontology/) (a future version of Domeo will likely implement an official W3C Open Annotation standard). This model represents the target resource of the annotation which consists of a URL to the target of annotation and a selector resource that clarifies what portion of the target document has been annotated. The model also represents the body of the annotation but only generically. Its up to plugins to provide code that writes and reads detailed annotation body resources.

2 Understanding the relationship between Open Annotation, JSON, JSON-LD, Javascript, and GWT

Summary: The Domeo system consists of the Domeo server application and a javascript client. The server application is system that includes a tomcat container, a mysql database, and an Elasticsearch database (see https://github.com/domeo/domeo/wiki/Storage-set-up). The mysql database is used for authentication and user role management. The Elasticsearch database acts as long term storage for annotations created by Domeo users. The server works with an instance of Elasticsearch to store the annotations as JSON-LD with meta-data to track annotation provenance (i.e., versioning, creator, and so forth). The client application has a “persistence manager” that acts as a temporary javascript store of annotations created within the client’s browser. Annotation plugins can use the persistence manager to store and re-load annotation data. When the user selects “Save”, the annotations in the persistence manager are extracted from the persistence manager, converted to JSON-LD, and sent to the server for storage in Elasticsearch. These same annotations will be sent from the server to the client when a user points the client to the same target that was previously annotated. The client receives JSON-LD from the server which it converts to javascript instances and puts in the persistence manager.

- The client persistence manager

Persistence manager plays very important role in client side. In DomeoClient, the class AnnotationPersistenceManager load annotation datasets into Client, set new annotations and return back current loaded annotations. Also, there are lots of extra advance functions it provides, such as retrieve the loaded dataset by annotation type or resource local id.

In development of new plugin, UI component can call functions in PersistenceManager to get current data set and then display by parsing it.

- The server JSON-LD store

Domeo use JSON-LD as format for send data from server to client. The Json-LD store is Elastic Search DB.

- Connectors

Connectors are the way Domeo uses to communicate with external services. Normally, besides the external web service, there are two components involved. The one is the connector server side which connects to the external web service. The purpose of this connector is to send the request and get response in
a way that the Domeo client can parse them. for instance, It get dataset from public sites and converts data from XML, which is the data format a majority of sites uses, to JSON LD.

The another component is the connector for client side connect to the connector server side. This is basically providing interfaces for the user to query the external web service.

- custom ontologies

Ontology can be custom by select text, create and edit annotation in UI components. In default Plugins architecture (see https://github.com/domeo/DomeoClient/wiki/Plugins-Architecture), Form is a part of UI, which allows manual creation and editing of the annotation. By creating predefined labels, radio button, check-box, drop down list-box or textarea that reflect labels of a object, form can representing an existing data model.

For how to create annotation model, please see the example of SPLs annotation model creation (https://github.com/domeo/DomeoClient/wiki/SPLs-Annotation-Model).

3 Marshaling – save annotation into ElasticSearch

(1) Serializer converts javaScript object to JSON-LD

In package “model.serilization”, it is annotation serilizers that response for data format conversion from JavaScript to JSON-LD.

Example of SPLs plugin:

The JsonSPLsAnnotationSerializer is serializer in SPLs plugin. It serializes annotation object to JSON and writes body elements in the output JSON object.

There are two steps to do for conversion. Firstly, serializer get current annotation by call get function in model (MSPLsAnnotation)

             MSPLsAnnotation ann = (MSPLsAnnotation) obj;
             MLinkedResource pkImpact = ann.getPKImpact();

Secondly, create JSON object to load current annotation

             JSONArray bodies = new JSONArray();
             JSONObject body = new JSONObject(); 
	      String statementUUID = UUID.uuid(); 
	      body.put("@id", new JSONString(SPL_URN_PREFIX + statementUUID)); 
	      body.put("@type", new JSONString(SPL_POC_PREFIX + "PharmacogenomicsStatement"));
	      body.put(SIO_PREFIX + "SIO_000563", new JSONString(SPL_POC_PREFIX + "PharmacokineticImpact"));
	      body.put(SPL_POC_PREFIX + "PharmacokineticImpact", new JSONString(pkImpact.getUrl()));
	      body.put(IRdfsOntology.label, new JSONString(pkImpact.getLabel()));
              body.put(IDublinCoreTerms.description,new JSONString(pkImpact.getDescription()));
	      bodies.set(idx, body);

(2) store JSON-LD into ElasticSearch

After convert the data from JavaScript object to JSON object, DomeoClient will send JSON format data to domeo server for analyze and retrieve. Then, the domeo server can store these created annotation into JSON-LD database,ElasticSearch.

Example of SPLs plugin:

JsonSerializerManager stores all of annotations in a HashMap to send to domeo server 

         private HashMap<String, ISerializer> serializers = new HashMap<String, ISerializer>();
         private JsonSerializerManager(IDomeo domeo) {
		_domeo = domeo;
		registerSerializers();
	}

        private void registerSerializers() {
		serializers.put(MSPLsAnnotation.class.getName(), new JsonSPLsAnnotationSerializer());
                ...
        }

4 Unmarshaling – read annotation(target resources) from ElasticSearch

The target resources can be existing annotations that storing in ElasticSearch. Domeo can requests resource by the URI of annotation. ElasticSearch will pulls back result set in JSON-LD to Domeo by the received URI.

Domeo server will brings selected target annotation in and send to Client. The domeo client will converts annotation in JSON-LD to JavaScript Object, load annotations in persistence manager and display in user interface if the URI of annotation matches.

Example of SPLs:

(1) JsAnnotationSPL extends JavaScriptObject for accessing the representation of the annotation of type SPL (Pharmacogenomics) in JSON format. The function getId() will return a URI of annotation that used for query external resources in ElasticSearch

	//  Identity
	public final native String getId() /*-{ 
		return this[@org.mindinformatics.gwt.domeo.model.persistence.ontologies.IDomeoOntology::generalId]; 
	}-*/;

	//  Annotation Ontology
	public final native JsArray<JsAnnotationTarget> getTargets() /*-{ 
		return this[@org.mindinformatics.gwt.domeo.model.persistence.ontologies.IDomeoOntology::hasTarget]; 
	}-*/;

	public final native JsArray<JsoPharmgxUsage> getBodies() /*-{ 
		return this[@org.mindinformatics.gwt.domeo.model.persistence.ontologies.IDomeoOntology::content]; 
	}-*/;

(2) JsoPharmgxUsage extends JavaScriptObject to supports getting the individual body elements in semantic model.

public final native String getId() /*-{
		return this[@org.mindinformatics.gwt.domeo.model.persistence.ontologies.IDomeoOntology::generalId];
	}-*/;

public final native String getPKImpact() /*-{
		return this['poc:PharmacokineticImpact'];
	}-*/;

(3) USPLJsonUnmarshaller converts JSON-LD annotation to JavaScript object

 public Object unmarshall(JsonUnmarshallingManager manager,
			JavaScriptObject json, String validation, MAnnotationSet set,
			ArrayList<MSelector> selectors) {
JsAnnotationSPL spl = (JsAnnotationSPL) json;

MSPLsAnnotation ann = AnnotationFactory.cloneSPLs(spl.getId(), ...  null);

JsArray<JsoPharmgxUsage> aus = spl.getBodies();

for (int j = 0; j < aus.length(); j++) {
			JsoPharmgxUsage au = aus.get(j);

                        String jsPkImpact = au.getPKImpact();
			if (jsPkImpact != null) {
				
				String jsLabel = au.getLabel();
				String jsDescript = au.getDescription();
				MLinkedResource pkImpact = ResourcesFactory.createLinkedResource(jsPkImpact, jsLabel, jsDescript);
				ann.setPKImpact(pkImpact);
			} 
    }
                        return ann;
}

(4) registers new plugin in JsonUnmarshallingManager 



private void registerDeserializers() {

		unmarshallers.put(MSPLsAnnotation.class.getName(), new USPLJsonUnmarshaller(_domeo));

	}

(5) add an if statement in JsonUnmarshallingManager for function unmarshall

else if (typesSet.contains(MSPLsAnnotation.TYPE)){
	SPLType splType = null;
	splType = SPLType.PHARMGX_TYPE; 
	if(splType!=null) {
		 ann = unmarshallSPLAnnotation((JsAnnotationSPL) jsonAnnotations.get(j), "", set, selectors);
		((MSPLsAnnotation) ann).setType(splType);													
							}

5 How to test saving and restoring annotations in hosted mode

(1) modify Annotation serializers to add functions to convert JavaScript object to JSON format

please see the example in Reading target resources

(2) Create a annotation by select text and fill fields in form

(3) By click save icon that in middle top of screen, we can save current editing annotation to get the output of JSON object that contains value of labels in JSON format. In hosted mode, the JSON outputs won’t saved into domeo server. instead, it will dump out by pop out a JavaScript window to display.

(4) copy the output JSON String into text editor, replace " to \" for converting unrecognised mark and then paste it into a test function in class AnnotationPersistenceServiceFacade as follows:

        JsArray<JsAnnotationSet> retrieveAnnotationById(String id, String idType, String allowed, boolean
        extend, String username) {

	String json = "[{\"pav:createdWith\":\"urn:domeo:software:id:Domeo-2.0alpha-040\",\"ao:item\":[{\"pav:createdWith\":\"urn:domeo:software:id:Domeo-2.0alpha-040\",\"rdfs:label\":\"SPL Annotation\",\"@type\":\"ao:SPLAnnotation\",\"domeo:belongsToSet\":\"urn:domeoclient:uuid:B2CBE747-9368-48D3-8AB8-0ECDA72850D1\",\"pav:createdBy\":\"urn:person:uuid:080e1430434f70e501434f711b6e0000\",\"pav:versionNumber\":\"1\",\"pav:lastSavedOn\":\"2014-01-22 17:35:57 -0500\",\"ao:context\":[{\"ao:hasSource\":\"http://127.0.0.1:8888/tests/SPL-annotation/Warfarin-ab047628-67d0-4a64-8d77-36b054969b44.html\",\"@type\":\"ao:SpecificResource\",\"@id\":\"urn:domeoclient:uuid:54CDC1E5-65E1-480A-A1C4-957BD32F7308\",\"domeo_temp_localId\":\"1\",\"ao:hasSelector\":{\"ao:prefix\":\"These highlights do not include all the information needed to use\",\"@type\":\"ao:PrefixSuffixTextSelector\",\"@id\":\"urn:domeoclient:uuid:54CDC1E5-65E1-480A-A1C4-957BD32F7308\",\"domeo_temp_localId\":\"1\",\"pav:createdOn\":\"2014-01-22 17:35:52 -0500\",\"ao:exact\":\" warfarin sodium safely and effectively. See full \",\"ao:suffix\":\"prescribing information for warfarin sodium.\",\"domeo:uuid\":\"54CDC1E5-65E1-480A-A1C4-957BD32F7308\"}}],\"ao:body\":[{\"sio:SIO_000563\":\"poc:PharmacokineticImpact\",\"@type\":\"poc:PharmacogenomicsStatement\",\"@id\":\"urn:linkedspls:uuid:38ACB655-54F2-43F3-8463-7AA1833725B5\",\"poc:PharmacokineticImpact\":\"http://purl.org/net/nlprepository/spl-pharmgx-annotation-poc#distribution-increase\"}],\"pav:lineageUri\":\"urn:domeoserver:annotation:A3653D48-231D-44CE-A309-B2C2F4311404\",\"pav:previousVersion\":\"\",\"@id\":\"urn:domeoclient:uuid:8E11483E-4C21-4188-AC79-B5BADA60ECE9\",\"pav:createdOn\":\"2014-01-22 17:35:52 -0500\"}],\"rdfs:label\":\"Default Set\",\"ao:annotatesResource\":\"http://127.0.0.1:8888/tests/SPL-annotation/Warfarin-ab047628-67d0-4a64-8d77-36b054969b44.html\",\"domeo:resources\":[{\"label\":\"WARFARIN SODIUM TABLET [AMERICAN HEALTH PACKAGING]\",\"url\":\"http://127.0.0.1:8888/tests/SPL-annotation/Warfarin-ab047628-67d0-4a64-8d77-36b054969b44.html\"}],\"@type\":\"ao:AnnotationSet\",\"pav:createdBy\":\"urn:person:uuid:080e1430434f70e501434f711b6e0000\",\"pav:lastSavedOn\":\"2014-01-22 17:35:57 -0500\",\"pav:versionNumber\":\"1\",\"permissions:permissions\":{\"permissions:isLocked\":\"false\",\"permissions:accessType\":\"urn:domeo:access:public\"},\"pav:lineageUri\":\"urn:domeoserver:annotationset:65B8CECA-8AFA-47C2-B14C-60ECB6FEC4F2\",\"domeo:agents\":[{\"rdfs:label\":\"boycer\",\"foafx:middlename\":\"\",\"foafx:lastname\":\"Boyce\",\"@type\":\"foafx:Person\",\"foafx:homepage\":\"\",\"foafx:picture\":\" http://www.hcklab.org/images/me/paolo%20ciccarese-boston.jpg\",\"foafx:email\":\"[email protected]\",\"foafx:firstname\":\"Richard\",\"foafx:title\":\"\",\"@id\":\"urn:person:uuid:080e1430434f70e501434f711b6e0000\",\"foafx:name\":\"boycer\"},{\"foafx:build\":\"040\",\"rdfs:label\":\"Domeo Annotation Toolkit\",\"@type\":\"foafx:Software\",\"foafx:homepage\":\"\",\"@id\":\"urn:domeo:software:id:Domeo-2.0alpha-040\",\"foafx:name\":\"Domeo Annotation Toolkit\",\"foafx:version\":\"2.0alpha\"}],\"pav:previousVersion\":\"\",\"dct:description\":\"The default set is created automatically by Domeo when no other set is existing.\",\"@id\":\"urn:domeoclient:uuid:B2CBE747-9368-48D3-8AB8-0ECDA72850D1\",\"pav:createdOn\":\"2014-01-22 17:35:44 -0500\"}]"; 

       }

(5) make modifications in USPLsJsonUnmarshaller to read JSON object and convert it to JavaScript for display.

please see the example in Reading target resources

(6) rerun the Domeo.html as web application and import existing annotation. Click the highlight text to see if the custom annotation are loaded correctly and displayed in card.

Add a custom footer
Add a custom sidebar
Clone this wiki locally