background image
Nuxeo EP 5 - Nuxeo Annotation
Service
Copyright © 2000-2007, Nuxeo SAS.
background image
Table of Contents
1. Requirements overview .............................................................................................................1
1.1. W3C Annotea ..................................................................................................................1
1.2. Extensions to Annotea ....................................................................................................1
1.2.1. URLs vs Document Ids ........................................................................................1
1.2.2. Image annotation ..................................................................................................1
1.2.3. Metadata management .........................................................................................1
1.2.4. Permission management ......................................................................................2
1.3. Additionnal requirements ................................................................................................2
1.3.1. Integration in Nuxeo preview system ..................................................................2
1.3.2. Stand alone html client .........................................................................................2
2. Logical architecture overview ....................................................................................................3
3. NXAS HTML Client ..................................................................................................................5
3.1. Overview .........................................................................................................................5
3.2. Implementation ...............................................................................................................5
4. Annotation Service Core ............................................................................................................6
4.1. Overview .........................................................................................................................6
4.2. Implementation ...............................................................................................................6
4.3. Storage ............................................................................................................................6
4.4. Query Support .................................................................................................................6
4.5. Extension points ..............................................................................................................7
4.5.1. urlResolver ...........................................................................................................7
4.5.2. urlPatternFilter .....................................................................................................7
4.5.3. metadata ...............................................................................................................7
4.5.4. permissionManager ..............................................................................................7
4.5.5. annotabilityManager ............................................................................................7
4.5.6. eventManager .......................................................................................................8
4.6. Event management ..........................................................................................................8
4.7. URLs and Document .......................................................................................................8
4.8. XPointer extension ..........................................................................................................8
5. Annotation Service Facade ......................................................................................................10
5.1. Implementation .............................................................................................................10
5.2. JMS ...............................................................................................................................10
5.3. Extension points ............................................................................................................10
5.3.1. annotationsRules ................................................................................................10
6. Annotation Service Javascript Library .....................................................................................12
6.1. overview ........................................................................................................................12
6.2. Implementation .............................................................................................................12
6.3. RDF / JSON ..................................................................................................................12
6.4. Annotating images ........................................................................................................12
7. Annotation Service HTTP Gateway ........................................................................................13
7.1. Overview .......................................................................................................................13
7.2. Implementation .............................................................................................................13
7.3. Authentication ...............................................................................................................13
7.4. State management .........................................................................................................13
8. Integrating the Annotation service ...........................................................................................14
8.1. Configure preview ........................................................................................................14
8.2. Configure Annotation policy ........................................................................................14
ii
background image
8.3. Configure Annotation Meta-data ..................................................................................14
8.4. Handle indexing ............................................................................................................14
8.5. Integrate HTML/JS Client ............................................................................................14
9. Packaging and deployment ......................................................................................................15
9.1. Target platform .............................................................................................................15
9.2. Packaging ......................................................................................................................15
10. W3C Annotea compliance .....................................................................................................16
10.1. Annotea clients. ...........................................................................................................16
10.2. Annotea Algae. ...........................................................................................................16
11. References ..............................................................................................................................17
Nuxeo EP 5 - Nuxeo Annotation Service
iii
background image
Chapter 1. Requirements overview
This chapter provides an overview of the requirements for the Nuxeo Annotation Service.
1.1. W3C Annotea
Nuxeo Annotation service will be based on Annotea W3C specification. This basically means that
Nuxeo Annotation Service (NXAS) will be compliant with the specification published at
http://www.w3.org/2001/Annotea/User/Protocol.html .
1.2. Extensions to Annotea
The annotea specification is quite old and does not handle all uses cases for annotating documents in
the context of Nuxeo ECM. Therefore, we propose to provide some extensions to annotea
1.2.1. URLs vs Document Ids
The Annotea specification only deals with URLs. In the context of Nuxeo ECM it may be usefull to
track the relationship between a URL and a Document Id. Keeping this relation will be usefull for :
• Managing versioning
It may be usefull to copy the annotations on a given version to the new version
• Managing Publication
Since Nuxeo ECM allow the usage of proxies the same document may be consulted via several
URls. With plain Annotea, a document and all it's proxies will have different URLs and then
different annotations. In most cases, this is not what we want.
• Document Indexing
Some implementations of Nuxeo platform may want to index annotations as meta-data of the
document. This will require to be able to extract the annotations from the document UUID.
For all these reasons, Nuxeo Annotation Service provides a plugable system to be able to keep track
of the relationship between a annotated URL and the underlying nuxeo document.
1.2.2. Image annotation
Inside Nuxeo EP we want to be able to annotate the HTML preview of a document. This preview may
include images. This images should be annotatble as the rest of the document, but it will require an
extension to the Xpointer specification since user may want to annotate just a portion (zone) of the
image.
1.2.3. Metadata management
1
background image
Annotea specification includes very few meta-data. Inside Nuxeo we want the annotation to have a
pluggable meta-data schema so that each project implementation may add it's own set of meta-data.
1.2.4. Permission management
Annotea specification includes no permission management. Inside Nuxeo we require the permission to
be checked according to the global security policy.
1.3. Additionnal requirements
1.3.1. Integration in Nuxeo preview system
The annotation service will provide an integration with the existing Nuxeo Html Preview system. The
goal of to use the Nuxeo preview tab to access the annotation feature.
1.3.2. Stand alone html client
A Standalone html client will be provided.
Requirements overview
2
background image
Chapter 2. Logical architecture overview
This chapter provides an overview of the logical architecture of the Nuxeo Annotation service.
• Annotation Service API
nuxeo-platform-annotations-api
Provides Java API and all the needed Java artifacts needed to call the Annotation service
remotly.
• Annotation Service Core
nuxeo-platform-annotations-core
Provides the Nuxeo Service that exposes the required annotation Java Interface. This service
will be implemented as a Nuxeo Runtime component and will provide the needed extension
points .
• Annotation Service Facade
nuxeo-platform-annotations-facade
Provides the service EJB3 facade for remote (RMI) access. Also includes integration with JMS
: sending JMS events and listen to events via MessageDrivenBeans.
• Annotation Service Http gateway
nuxeo-platform-annotations-restlets
The HTTP Gateway will implement the Annotea HTTP protocol. It will implemented as a set of
Restlets that will enable access to the annotation service via http GET/POST requests as defined
in the W3C Annotea specification.
• Annotation Service JavaScript Client
nuxeo-platform-annotations-js-client
The JS Library is the client part of the Annotea specification. It will manage :
• communication with the http gateway
• extended XPointer resolution
• annotation display and edit
• ...
• Annotation Service preview plugin
nuxeo-platform-annotations-preview-plugin
Access to annotations service will be available via the nuxeo preview service. This package will
integrate the annotation JS client into the html preview tab.
• Annotation Service standalone client
nuxeo-platform-annotations-html-client
This package will provide a simple stand-alone html client that embeds the JS client.
3
background image
Figure 2.1. NXAS Components JPG
Logical architecture overview
4
background image
Chapter 3. NXAS HTML Client
3.1. Overview
The NXAS HTML Client is the a web interface that can be used by the end user. It is a very simple
web application consisting of single html page. The page looks like a browser. It allows to enter URL
and show its content. The User can annotate places in the text or part of images, he can
see/add/remove/change annotations.
This HTML client is very much like the annotation system integrated in the Nuxeo preview tab, but
without the need of Nuxeo EP.
This HTML client will be usable in standalone mode outside of Nuxeo. In this standalone mode, the
user will have to enter : the url of the annotation service, and his login/password.
3.2. Implementation
Simple Html page with some JavaScript.
The Html page displays 3 zones :
• Server settings
This zone let the user define his login/password and the Annotation server base URL.
• Page settings
This zone let the user enter the URL of the document he wants to annotate. A simple validation
button makes the third zone display the targeted page.
• HTML Page display
Contains a IFRAME that displays the url selected by the user.
Annotations tools will be available here.
The Html Client uses the NXAS JS library to handle communication with the server and to manage
annotations on the targeted web page.
5
background image
Chapter 4. Annotation Service Core
4.1. Overview
This is the main component of NXAS, the one that contains all the logic for managing RDF based
annotations.
This component is also responsible for exposing all the needed extension points that will be used for
configuration and integration.
4.2. Implementation
The service is implemented as a Runtime service on top of a Nuxeo Runtime component. The runtime
component will provide the extension point mechanisms. The API provided by the service will target
managing annotations on both URLs and documents.
As any Nuxeo Service, the Annotation Service is accessible via the Runtime lookup method :
Framework.getLocalService(AnnotationService.class)
4.3. Storage
The Annotation service will store the annotations as a RDF graph.
The Annotation service will contribute a new RDF Graph, a new set of RDF predicate and a new set
of resources adapters for the Nuxeo Relation Service. Nuxeo Relation Service is responsible for
storing and managing the RDF data.
According to Annotea specifications, the felowing graphs and namespaces will be supported:
• http://www.w3.org/2000/10/annotation-ns
• http://www.w3.org/2001/03/thread
• http://www.w3.org/2001/12/replyType
These graphs will be extended and completed to support the extension to the specification :
• XPointer extension to support Images
• Pluggable meta-data management
• Document vs URLs management
4.4. Query Support
Even if Algae won't be implemented, NXAS will provide a Query API to retrive Annotations based on
6
background image
criteria.
Search criteria include :
• target Document URL or DocumentLocation
• attributes of the annotation
• attributes of the author of the annotation
4.5. Extension points
The runtime service will manage several exctension points in order to provide the needed flexibility.
4.5.1. urlResolver
The urlResolver extension point allows to contribute a class that is responsible for resolving url to
Document Location (repository name / document UUID).
This extension point is very important since it will provide the link between documents and URLs that
will be used for the versionning and proxy resolution.
The default implementation will use the url codec service to try to do the translation. The preview
URL system will also be supported.
4.5.2. urlPatternFilter
The urlPatternFilter extension point allows to contribute regular expression pattern to the list of
allowed URL pattern or disallowed URL pattern. When a request is made to get/set annotations on an
URL, the server check the list. If the URL match a pattern on the disallowed list, then no action will
be possible. Then if the URL match a pattern on the allowed list, then annotation will be processed.
4.5.3. metadata
The metadata extension point allows to contribute class that provides metadata. The class implements
a simple interface. Its duty is to return a Map of metadata when being passed the annotation and
author name. The default implementation is to provide author, timestamp, annotation type and author
organizational unit.
4.5.4. permissionManager
The permissionManager extension point allows to contribute a class that will check viewAnnotation,
updateAnnotation and deleteAnnotation on URL. The default behavior is to map to the
view/update/delete permission on the corresponding document.
4.5.5. annotabilityManager
Annotation Service Core
7
background image
The annotabilityManager extension point allows to contribute a class to fine grain which documents
can be annotated. Default implementation will allow simple filtring on Document facet 'Annotable'.
4.5.6. eventManager
The eventManager extension point allows to contribute a listener class handle annotation related
events.
4.6. Event management
The Annotation service will trigger several events associated to annotations :
• annotationCreated
• annotationModified
• annotationDeleted
Each event will be trigger twice : once before the action and once after the action. Event listeners are
synchonous and have an interface that is very much like the core event listeners.
4.7. URLs and Document
The resolution between URLs and Document will rely in the contributed urlResolver plugins. A
built-in event listener will use this plugin to propagate annotations to the target document if url can be
resolved. As a single Nuxeo Document can have several preview URLs, the relation can not be a
bijection between a URL and a Document. The Bijection is between a URL and a tuple
(DocumentLocation, xpath of target field). Basically there will be a relation between a
(DocumentLocation, path) and the URL, the annotations will be linked to the URL and to the tuple
(DocumentLocation, path) (if available). This means than when retrieving annotation from an URL
the service will :
• resolve URL to (DocumentLocation, path) if possible
• resolve proxy if DocumentLocation is a proxy
• get the annotations linked to this (DocumentLocation, path)
In most cases, a Nuxeo Document has only one preview URL associated to the default preview xpath
(see preview component doc).
4.8. XPointer extension
The XPointer W3C specification is based on XPath and is made to identify a fragment of an html
document.
The XPointer synthax will be extended to include the possibility to identify a shape inside a image
that is inside the HTML page. The NXPointer will typically contain the XPath to locate the image
Annotation Service Core
8
background image
within the HTML document and a shape descriptor with pixel based values.
Annotation Service Core
9
background image
Chapter 5. Annotation Service Facade
As for any Nuxeo Service, the facade will provide the integration of the service into JEE
infrastructure.
This includes :
• Remoting
• Transactions
• JMS
5.1. Implementation
EJB3 Stateless Session Bean facade on top of the runtime service.
This makes the Annotation Service remotable and accessible via the standard Nuxeo Lookup facility :
Framework.getService(AnnotationService.class)
5.2. JMS
The facade package also includes Listeners contributions to the core service in order to forward core
service events to the JMS topic.
By default, all annotation related events are sent on the JMS topic : this can be useful for external
indexers, that may want to reindex the document when an annotation is createed or modified.
The Facade will also host a MessageDrivenBean that will react to core document events (creation,
modification, delete). The behavior of this MDB will be configured via a dedicated Extension Point
(see below).
5.3. Extension points
5.3.1. annotationsRules
This extension point takes configuration that will be used by the MDB to define what must be done
depending on the event.
This configuration binds actions to events. Events are :
• documentModified
• documentVersionned
• documentPublished
10
background image
• documentDeleted
• documentCopied
• documentLifeCycleChanged
Actions are :
• duplicate
Duplicate annotation graph for the new document. Typically, this can be useful for document
versionning or document copy.
• relink
Link the annotatation to the new document reference. Typically this can be usefull for
publishing.
• delete
Remove the annotation graph. Typically, this can be usefull when document are deleted.
• nop
Null operation
This configuration will let the MDB define what action must be done when an event occurs. In most
case, the same action could be done directly by the synchronous event listener in the NXAS Core
service. But for performances reason, it is safer to let these actions handled asynchronously via JMS
and MDB pooling.
Annotation Service Facade
11
background image
Chapter 6. Annotation Service Javascript
Library
6.1. overview
This library offers a simple interface to interact with the NXAS Server. It allows to
create/read/update/delete annotations related to a URI, and to the URIs of the different version of the
corresponding document.
This library also offers the UI functions to grab part of a document, including picture, and transform it
into URI using XPointer.
6.2. Implementation
Implementation will be in pure JavaScript. JQuery library will be used for DOM manipulation and the
JQuery Dialog toolkit will be used to managing UI.
6.3. RDF / JSON
The NXAS JS Library is dedciated to be used with Nuxeo Annotation service. Therefore, it does not
have to use RDF encoding. For optimization reason, the JS lib may use a JSON marshing rather than
plain RDF.
6.4. Annotating images
The Client JS library will handle image annotation and permit to define a shape (rectangle/elipse) in
the image that should hold the annotation. The shape will be handled as respect to the image size in
the HTML. If the HTML conversion flattern all images in the documents as one background image in
the HTML preview, then the annotation client will see only one image.
12
background image
Chapter 7. Annotation Service HTTP Gateway
7.1. Overview
The Annotation Service HTTP gateway provides the http API on top of the java APi of the Annotation
Service
7.2. Implementation
The http gateway will be implemented as a set of restlets.
The gateway package will also include serializer/deserializer for RDF and JSON. This allows the http
service to respond in RDF or JSON according to client requirements. The format parameter is simply
added to the standard Annota API, defaut format is RDF (for compliancy reasons).
The URL filting will be delegated to the underlying Nuxeo Service, this HTTP layer is only a gateway
and must handle as less logic as possible.
7.3. Authentication
The Annotation Restlet interface is guarded by the
NuxeoAuthenticationFilter
. This means that the
access via http to the annotation service requires a valid authentication.
NuxeoAuthenticationFilter
will be configured (via it's EP) to let annotation related URLs be starting
URLs.
Annonymous access to the annotation service is possible, in the Anonymous Authentication Plugin is
deployed.
7.4. State management
The restlets used to provide http access to the annotation service are stateless restlets.This means they
don't depend on Seam or JSF. Nevertheless, because of the Authentication system, client will have to
maintain a Session Cookie to avoid reauthenticating on each call.
13
background image
Chapter 8. Integrating the Annotation service
Integrating the Nuxeo Annotation Service to your project may require several steps.
8.1. Configure preview
You can use Nuxeo Preview adpaters extension points to configure how the html previews of your
documents will be generated.
Default implementation includes preview via transformers and preview based on pre-stored data.
Please refer to the according documentation.
8.2. Configure Annotation policy
The Annotation service exposes an Extension Point to define how annotations are managed during
versionning / publishing events. You can define your own configuration for that.
8.3. Configure Annotation Meta-data
You can change default meta-data associated to the annotations. For this you need to contribute a
simple java class.
Default implementation includes : author, timestamp, annotation type and author company
8.4. Handle indexing
Nuxeo default indexing does not handle Annotation indexing.
Nevertheless, if you use an external indexer, you may use a MDB to listen to Annotation events and
trigger a reinddexation of the target document. This means that your indexing wrapper will contact the
Annotation service to fetch the annotations associated to the document.
8.5. Integrate HTML/JS Client
By default Nuxeo provides 2 clients : one integrated into the preview tab and one standalone.
You may need to integrate the Preview in dedicated screens or to adapter the default screens to you
own graphic theme.
14
background image
Chapter 9. Packaging and deployment
9.1. Target platform
The logical target plaform is Nuxeo EP 5.2.
The NXAS Addon will also be available on 5.1 branch (5.1.6).
9.2. Packaging
NXAS will be packaged as a set of java artifacts that are plugins for Nuxeo EP.
Java artifacts includes :
•
nuxeo-platform-annotations-api
•
nuxeo-platform-annotations-core
•
nuxeo-platform-annotations-facade
•
nuxeo-platform-annotations-restlets
•
nuxeo-platform-annotations-preview-plugin
•
nuxeo-platform-annotations-html-client
•
nuxeo-platform-annotations-js-client
•
nuxeo-platform-annotations-tests
Some of these artifacts are resources only artifacts (for JS and HTML).
The support for NXAS inside the Nuxeo "light packaging" (Jetty bundle) is not directly targeted, but
this should not be a problem ouside of the facade artifact.
15
background image
Chapter 10. W3C Annotea compliance
As explained before, Annotea specification is not broad enought to include all Nuxeo EP requirements
for managing Annotations.
10.1. Annotea clients.
Nevertheless, NXAS will support Annotea basic clients like Mozilla Annozilla Annotea extension.
Using a standard Annotea Client may retrain features : for examples additionnal metadata and Image
annotations won't be availables.
10.2. Annotea Algae.
The Algae specification describe a Query Language that may be implemented by Annotea clients and
servers. NXAS won't implement Algae
16
background image
Chapter 11. References
•
W3C Annotea Protocols
•
Nuxeo preview addon
•
XPointer
17

Document Outline