<!–Style guidelines: 1. Quote excerpts from Eclipse; commands, sections names, etc. 2. Italicize arguments: package names, class names, etc.

  remember that italics are placed on text delineated with 2 apostrophes: ''italicized words''
–> This page walks you through the steps necessary to creating the server-side implementation for a basic annotation task. The steps explained here correspond to Eclipse 3.7. This portion of the tutorial assumes that you've already worked through Creating an Annotation Task.

Create Server Package

In the Ccash Project:

  • Click “New”→“Package”
  • Set “Package” to edu.byu.nlp.ccash.tasks.demo.server
  • Click “Finish”

This operation should create the package edu.byu.nlp.ccash.tasks.demo.server.

Create an Annotation Manager

Create the Annotation Manager

In the Ccash Project:

  • Select the package edu.byu.nlp.ccash.tasks.demo.server
  • Click “New”→“Class”
  • Set “Name” to DemoAnnotationManager
  • Set “Superclass” to edu.byu.nlp.ccash.annotation.server.java.JavaAnnotationManager
  • Uncheck “Inherited abstract methods”
  • Click “Finish”

This operation should create the file DemoAnnotationManager.java in the package edu.byu.nlp.ccash.tasks.demo.server.

Specify Generic Parameters

JavaAnnotationManager takes two generic parameters, I for the class of instances that you will be annotating, and A for the class of annotations you will be producing. For this tutorial, set both to String as follows:

public class DemoAnnotationManager extends JavaAnnotationManager<String, String>

Implement Methods

Hover your mouse over the class name and click “Add unimplemented methods,” and then seven methods stubs should be generated. If you didn't uncheck “Inherited abstract methods” when you created the task, then the methods were auto-generated; you'll need to change some of the Object types to the more specific types for the generic types I and A (For this tutorial String).

The purposes of these methods are:

  • nextPreannotatedJavaInstance: returns the instance to be annotated next.
  • updateJavaAnnotation: allows your annotation manager to update its automatic annotations. For this tutorial we'll just return null.
  • getInstanceClass: should return the class type of the instances you'll be annotating. This allows GWT to automatically serialize and deserialize your instance object. For this tutorial return String.class.
  • getAnnotationClass: should return the class type of the annotations you'll be producing. This allows GWT to automatically serialize and deserialize your annotation object. For this tutorial return String.class.
  • javaAnnotationReceived: allows your annotation manager to record completed annotations.
  • startManager: called when the annotation manager is first created. Allows you to do necessary initialization. For this tutorial we'll leave it blank.
  • getDefaultManagerConfiguration: returns set of name-value properties that your manager relies on, set to their default values. For this tutorial we'll just return null.

Example Code

Here is a complete implementation of DemoAnnotationManager:

package edu.byu.nlp.ccash.tasks.demo.server;

import java.util.List;
import java.util.Map;
import java.util.UUID;

import edu.byu.nlp.ccash.annotation.server.java.AnnotationManagerJavaReturnValue;
import edu.byu.nlp.ccash.annotation.server.java.AutomaticAnnotationProviderJavaReturnValue;
import edu.byu.nlp.ccash.annotation.server.java.BasicAnnotationManagerJavaReturnValue;
import edu.byu.nlp.ccash.annotation.server.java.JavaAnnotationManager;
import edu.byu.nlp.ccash.client.CcashException;
import edu.byu.nlp.ccash.client.datatransferobjects.DBTimelineEventDTO;

public class DemoAnnotationManager extends JavaAnnotationManager<String, String> {

	@Override
	protected AnnotationManagerJavaReturnValue<String, String> nextPreannotatedJavaInstance(
			long annotatorId, long instanceProviderId, long projectIterationId,
			Map<String, String> configuration) throws CcashException {
	
		String instance = "UniqueInstance"+UUID.randomUUID().toString();
		AnnotationManagerJavaReturnValue<String, String> retVal = BasicAnnotationManagerJavaReturnValue.okayRetval(-1L, instance);
		return retVal;
	}

	@Override
	protected AutomaticAnnotationProviderJavaReturnValue<String, String> updateJavaAnnotation(
			String instanceValue, String annotationConstraint, long instanceId,
			long annotatorId, long automaticAnnotationProviderId,
			long projectIterationId, Map<String, String> configuration)
			throws CcashException {

		// No automatic updates to perform
		return null;
	}

	@Override
	protected Class<String> getAnnotationClass() {
		return String.class;
	}

	@Override
	protected Class<String> getInstanceClass() {
		return String.class;
	}

	@Override
	protected Long javaAnnotationReceived(long aiId, String annotation,
			long instanceId, long annotatorId,
			List<DBTimelineEventDTO> timelineEvents, long projectIterationId,
			long annotationManagerId,
			Map<String, String> annotationManagerConfiguration)
			throws CcashException {

		// log annotations to the command line		
		System.out.println(
				"Received annotation: " + annotation +
				" id: " + aiId +
				" on instance: " + instanceId +
				" from annotator: " + annotatorId);
		return null;
	}

	@Override
	protected void startManager(long projectId,
			Map<String, String> configuration) throws CcashException {
		// ignore
	}

	@Override
	protected Map<String, String> getDefaultManagerConfiguration() {
		// no configuration
		return null;
	}
}

Register Annotation Manager as a Network Service

Add a mapping for your class in the Ccash/src/org/apache/xmlrpc/webserver/XmlRpcServlet.properties file as follows:

DemoAnnotationManager=edu.byu.nlp.ccash.tasks.demo.server.DemoAnnotationManager

Advanced

In fact, Annotation Managers are just convenience wrappers around three internal structures: instance providers, automatic annotation providers, and annotation recorders. If you find yourself wanting to separate an annotation manager into reusable classes, you may do so by implementing these pieces separately, then assembling them in the Project wizard by selecting the “Advanced” tab.

  • Instance Providers are network services that serve instances that need to be annotated. An instance provider might serve up a document's sentences sequentially, or it might do something more sophisticated such as returning sentences selected with uncertainty sampling or diversity sampling.
  • Automatic Annotation Providers are network services that serve up automatic labels for instances. They could be as simple as serving up the most frequent label seen so far, or as sophisticated as using a probabilistic model that is being continually retrained.
  • Annotation Recorders are network services that listen for completed annotations. They might write annotations to a file, record them in a database, or even pass them on to another external web service in charge of housing the data.

In a typical annotation scenario, Ccash would query an instance provider for an instance, then ask an automatic annotation provider to make a guess at the correct labeling before presenting the pre-annotated instance to a human annotator via a compatible GUI task. After the annotator finished correcting the guess, the completed annotation would be sent to a set of annotation recorders to be preserved.

Other Languages

Find an xmlrpc implementation for your language of choice, and implement the interfaces that you find documented in the following classes in the package edu.byu.nlp.ccash.annotation.server:

  • XmlrpcAnnotationManager

Or

  • XmlrpcInstanceProvider
  • XmlrpcAutomaticAnnotationProvider
  • XmlrpcAnnotationRecorder

For more insight to how these interfaces are intended to work, see the corresponding interfaces in the packages edu.byu.nlp.ccash.annotation.server.rawjava and edu.byu.nlp.ccash.annotation.server.java.

nlp/creating-an-annotation-manager.txt · Last modified: 2015/04/16 20:14 by ryancha
Back to top
CC Attribution-Share Alike 4.0 International
chimeric.de = chi`s home Valid CSS Driven by DokuWiki do yourself a favour and use a real browser - get firefox!! Recent changes RSS feed Valid XHTML 1.0