Annotation Back End

THIS SECTION OF GCUBE DOCUMENTATION IS CURRENTLY UNDER UPDATE.

Introduction

The Annotation Back End consists of two components - the implementation of the service as well as a client library that may be used to access the service. The Annotation Back End (ABE) service provides a generic annotation framework that offers application-to-application functionalities for the management of Diligent annotations. The service mediates between interactive annotation front-ends (like annotation portlets) and lower-level data management services (primarily Metadata Catalog services). Functionalities that rely on course-grained data exchange, that can be conveniently shared across clients, are provided through a number of coordinated web services. On the other hand, functionalities which rely instead on fine-grained data exchange, typically in real time through user interactions, are offered through the client-sided library.

Implementation Overview

ABE service

The ABE service operatates on a number of underlying component packages that provide a corse-grained division of functionality:

• Core: This package groups components responsible for implementing the main annotation functionalities. In particular it contains the three main interfacing service classes that are available for clients: AnnotationFactory, AnnotationManager, and AnnotationBroker.
  • The AnnotationFactory creates WS-Resources accessible through the AnnotationManager and the AnnotationBroker interfaces.
  • The AnnotationManager updates and retrieves annotations of objects within a collection C. This service addresses the needs of clients which operate in the scope of a single collection C, including those which wish to browse annotations drawn from multiple annotation collections for C. Furthermore, it allows clients to operatre in the scope of a single annotation collection for C for editing and linking of homogeneous collection bodies.
  • The AnnotationBroker retrieves annotations of objects from multiple collections C1,C2,…,Cn. This services addresses the needs of clients which operate across target collections and annotation collections, like those that browse the results of a distributed search.

• Handlers: This package contains a range of handlers that are used to specify the use of atomic and possibly stateful processes within the Content Source Description service - primarily during initialisation and update. This includes the atomic tasks of harvesting (the retrieval of remote content descriptions to allow for a qualitative decision on merging search results), ingesting (the integration of the content in the index of the DF), and the subscription for notifications.

Whether for retrieval or update purposes, the services expose a course-grained interface of bulk methods which offer by-value (arrays) and by-reference (ResultSet references) exchange of both input and output parameters. In addition, the services can retrieve summaries (headers) or full content (headers and bodies) of annotations.

The service exposes the following interfaces with operations:

AnnotationFactory:

• createAnnotationManager(params) -> EPR
  Takes a collection id wrapped in a paramter and returns the EPR of a WS-Resource with the AnnotationManager.

• createAnnotationBroker(params) -> EPR
  Takes identifiers of one or more collections and returns the EPR of a WS-Resource with the AnnotationBroker interface.

AnnotationManager:

• getCollectionID() -> String
  Returns the unique ID of the Collection this

AnnotationManager maintains.

• getAnnotationCollectionIDs() -> StringArray
  Returns all AnnotationCollection IDs for the

Collection this AnnotationManager maintains.

• createAnnotationCollection(StringMap parameters) -> String
  Creates a new AnnotationCollection for the

Collection from a given set of creation parameters and returns its identifier. The parameters are those specified by the MetadataCatalogFactory but exclude the secondary Role which is specified by the method as Is-Annotated-By.

• setAnnotations(SetAnnotations parameters) -> SetAnnotationsResponse
  Takes the identifier of an annotation collection AC for a collection C and a list of pairs composed of a collection ID and annotation lists for this collection ID.

• StringArray deleteAnnotations(DeleteAnnotations parameters)
  Takes an annotation collection ID and a list of annotations in this annotation collection. Deletes these annotations from the annotation collection.

• setAnnotationRS(org.diligentproject.annotationmanagement.abe.impl.core.stubs.SetRSParams parameters) -> EPR
  

• deleteAnnotationRS(DeleteRSParams parameters) -> ERP
  

• getAnnotations(StringArray parameters) -> GetAnnotationsResponse
  

• getAnnotationsByCollection(GetAnnotationsByCollection parameters) -> AnnotationMap
  

• getAnnotationHeaders(GetAnnotationHeadersParams parameters) -> StringArrayArray
  

• getAnnotationHeadersByCollection(GetAnnotationHeadersByCollectionParams parameters) -> StringArrayArray
  

• getAnnotationRS(EPR parameters) -> EPR
  

• getAnnotationRSByCollection(GetAnnotationRSByCollectionParams parameters) -> EPR
  

• getAnnotationHeadersRS(EPR parameters) -> EPR
  

• getAnnotationHeadersRSByCollection(GetAnnotationHeadersRSByCollectionParams parameters) -> EPR
  

• getAnnotationCollectionSummaries() GetAnnotationCollectionSummariesResponse
  

AnnotationBroker:

• getAnnotations(GetBAnnotations params) -> GetBAnnotationsResponse
  Takes the identifiers of a list of objects oi and corresponding collections Ci and returns a list whose elements are lists of all the annotations for oi across all the annotation collections for Ci.

• getCollectionIDs(VoidType params) -> StringArray
  Returns the unique IDs of all Collections.

• getAnnotationManagers(VoidType params) -> GetAnnotationManagersResponse
  Returns a list of all AnnotationManager EPRs of

all the Collections that are administrated by this AnnotationBroker.

ABE library

Created for the client-side, the main task of the ABE library is to simplify interaction between ABE clients and ABE services. In particular, library support consists of:

• encapsulation of the ABE service stubs behind an object-oriented interface (e.g. object modelling of service input and outputs, use of overloading to simplify service APIs, etc.);
• an extensible framework for transparent object binding of XML representations of annotations. The framework is built as an ABE-specific extension of the framework offered directly by the MC library (to confirm) and indirectly by the ResultSet client library. Clients who wish to do so can model annotations as objects with the advantages of expressiveness and early validation which normally characterise data binding solutions;
• built-in support for linking of annotations of the same object into 'threads' similar to those typically formed by postings in mailing lists or message boards.
• annotation buffering to mediate between the fine-grained nature of operations within annotation sessions and the coarse-grained nature of interaction with the ABE service. This enables responsive user interfaces by concentrating bulk network interactions at distinguished 'commit' points.

Dependencies

• Java JDK 1.5
• WS-Core
• DiligentProvider
• KXML (version 2.3.0)
• DIRCommons library
• MetaDataManager Broker
• MetaDataManager Catalog
• DISHL client
• DISIP
• ResultSet library
• ResultSet Client library

Usage Example

Creating Annotation Broker (using the Service)

 // necessary imports
 import org.apache.axis.message.addressing.EndpointReferenceType;
 import org.apache.axis.message.addressing.Address;
 import org.diligentproject.annotationmanagement.abe.impl.core.stubs.
   service.AnnotationFactoryServiceAddressingLocator;
 import org.diligentproject.annotationmanagement.abe.impl.core.stubs.
   service.AnnotationBrokerServiceAddressingLocator;
 import org.diligentproject.annotationmanagement.abe.impl.core.stubs.EPR;
 import org.diligentproject.annotationmanagement.abe.impl.core.stubs.FBParams;
 
 // the host where the CSD service runs 
 String myhost = "bob";
 String collectionURIs={"myCollection"};
 
 String factoryURI = "http://" + myhost + ":8080/wsrf/services/diligentproject/
   annotationmanagement/abe/AnnotationFactory";
 EndpointReferenceType endpoint = new EndpointReferenceType();
 endpoint.setAddress(new Address(factoryURI));
 AnnotationFactoryServiceAddressingLocator factoryLocator = new 
   AnnotationFactoryServiceAddressingLocator();
 factory = factoryLocator.getAnnotationFactoryPortTypePort(endpoint);
 	
 // create AnnotationBroker
 AnnotationBrokerServiceAddressingLocator annotationBrokerLocator = 
   new AnnotationBrokerServiceAddressingLocator();
 FBParams params = new FBParams();
 params.setCollectionURI(args);
 EPR eprWrapper = factory.createAnnotationBroker(params);
 EndpointReferenceType epr = eprWrapper.getEndpointReference();
 AnnotationBrokerPortType annotationBroker = annotationBrokerLocator.
   getAnnotationBrokerPortTypePort(epr);

Creating Annotation Broker (using the Library)

 AnnotationBroker broker = AnnotationBroker.newInstance(uris);