Linked Objects in Text

{toc}
{jira:RS-1472}
{jira:RS-305}

h1. Intro

Various RS objects can be linked into free text (annotation text or forum post). The user can paste any [Data Basket|Data Basket Model] item using the editor toolbar, and we want to track all [Item Types|Data Basket Model#Item Types] except:
- Forum: forum post linking is handled by jForum
- Image: We currently don't have a display of image alone
- Text Snippet which: pasted itself, has no URI
- Web Link: represented as a normal URL in the text, doesn't need to be tracked
- Search: doesn't need to be tracked

h2. Use Case

In the first tab of a Museum Object (Object Details), we want to show all related annotations and forum posts. Related annotations/posts for an object are the ones that mention it, or one of its fields

h2. Link Types

Links are represented in text like this:
{code:html}
<a class="rslink linkMO" href="http://collection.britishmuseum.org/id/object/RFI41407">
RFI41407 Chromolithograph pictorial label used for...</a>
<a class="rslink linkStatement" href="http://www.researchspace.org/st/2">
amulet YCA70788 Glass two-finger amulet: this moulded funerary...: dimension</a>
{code}

|| CSS Class || Item Type || Sample URL || Note ||
| linkMO | rso:FC70_Thing | [http://collection.britishmuseum.org/id/object/RFI41407] | Museum Object |
| linkStatement | rdf:Statement | [http://www.researchspace.org/st/2] | [Annotation Point|Annotation Design#Annotation Point] |
| linkDataAnnotation | rso:DataAnnotation | [http://collection.britishmuseum.org/id/object/RFI41407/annot/1] | [Data Annotaton|Open Annotation Collaboration (OAC)#Annotation with OAC and Reification] |
| linkImageAnnotation | rso:ImageAnnotation | [http://www.researchspace.org/DT219363.tif/annot/1] | [Image Annotation|Image Annotation Design#Example] |

h2. Linked Object
An annotation/post Links to an object ?obj iff: there is an ?uri in the free-text such that:
|| Link to || Conditions || Notes ||
| object itself | ?uri a rso:FC70_Thing. ?uri=?obj |
| annotation point | {nf}?uri a rdf:Statement; dcterms:isPartOf ?obj{nf} | See [Open Annotation Collaboration (OAC)#Annotation with OAC and Reification|Open Annotation Collaboration (OAC)#Annotation with OAC and Reification] |
| data annotation | \{?uri a rso:DataAnnotation; oac:hasTarget ?obj} UNION \\
\{?uri a rso:DataAnnotation; oac:hasTarget ?st. ?st a rdf:Statement; dcterms:isPartOf ?obj} | See same |

h1. Link Data Model

Since Links are pasted from the Data Basket, they are similar to the [Bookmark Data Model|Data Basket Model#Bookmark]
| *Property* | *Notes* |
| rdf:type | rso:Link (new class) |
| oac:hasBody | rso:DataAnnotation or rso:ImageAnnotation or rso:Forum
- For annotation: the free text linking the object is in in oac:hasBody/oac:hasBody/rso:P3_has_description.
- For forum post: they are stored in jForum, not OWLIM. We generate URIs like [http://www.researchspace.com/forum/123] (where 123 is the forum ID), mark the URI with rso:Forum (new class), and put the ID in dcterms:identifier |
| oac:hasTarget | rso:FC70_Thing matching one of the conditions in [#Linked Object]

h2. Link Data Example

Here is a comprehensive example involving 3 links:
# Data annotation <object/123/annot/23> mentions <object/456>
# Forum post 321 mentions data annotation <object/456/annot/45> of <object/456>
# Image annotation <pic.tif/annot/67> mentions annotation point <st/56> of <object/456>

{noformat}
<link/1> a rso:Link;
oac:hasBody <object/123/annot/23>;
oac:hasTarget <object/456>.

<forum/123> a rso:Forum;
dcterms:identifier "123".

<link/2> a rso:Link;
oac:hasBody <forum/123>;
oac:hasTarget <object/456>.

<link/3> a rso:Link;
oac:hasBody <pic.tif/annot/67/body>;
oac:hasTarget <object/456>.
{noformat}
All these statements (including "a rso:Forum") need to be created

h2. Link Data Illustration

The figure above shows the same example, plus the extra statements that make the link to <object/456>.
!link-illustration.png!

h1. Link API

h2. Extract Links

- The annotation/forum text should be parsed to find all links (see patterns in [#Link Types])
- Each link is processed to find the linked object rso:root (see conditions in [#Definition of Link])
- If the link in text point to an Annotation Point (that is, it is "linkStatement"), then we need to load the rdf:Statement and get the object it is part of.

h2. Update Links

To implement this below for posts, we need to hook into the jForum API for create/update/delete.
- On *create* of annotation or post: extract and store the links.
Do this after the annotation/post is saved, so that we have the new annotation's URI
- On *edit* of annotation body or post: reparse and recreate the Links for that annotation/post
I.e. delete any existing links, extract and store new links
- On *delete* of annotation/post: delete the corresponding links


Links are stored using a method in the DMS2RDF class.

h2. Retrieve Links

There will be 2 methods in DMS2RDF:
{code:java}
URI[] getReferringAnnotations(URI uri):
// returns all annotation URIs that mention the MO with this uri or its annotation points
String[] getReferringForumPosts(URI uri):
// returns all forum posts that mention the MO with this uri or its annotation points
// IDs for the forum posts are returned as Strings.
{code}

{warning}Jana, don't you also need to list the data annotations of the object, even if they don't mention the object?{warning}