compared with
Current by Vladimir Alexiev
on Feb 19, 2013 10:30.

Key
This line was removed.
This word was removed. This word was added.
This line was added.

Changes (53)

View Page History
{jira:RS-305}

h1. Linked Objects in Free Text
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
- 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
!related_objects.png!

h2. Link Types

Links are represented in the text like this:
{code:html}
<a class="rslink linkMO" href="http://collection.britishmuseum.org/id/object/RFI41407">
{code}

||Link Class||Item Type||Sample URL||Note|| || CSS Class || Item Type || Sample URL || Note ||
|linkMO|rso:FC70_Thing|[http://collection.britishmuseum.org/id/object/RFI41407]|Museum Object| | linkMO | rso:FC70_Thing | [http://collection.britishmuseum.org/id/object/RFI41407] | Museum Object |
|linkStatement|rdf:Statement|[http://www.researchspace.org/st/2]|[Annotation | linkStatement | rdf:Statement | [http://www.researchspace.org/st/2] | [Annotation Point|Annotation Design#Annotation Point] |
|linkDataAnnotation|rso:DataAnnotation|TODO| |
| 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]| | linkImageAnnotation | rso:ImageAnnotation | [http://www.researchspace.org/DT219363.tif/annot/1] | [Image Annotation|Image Annotation Design#Example] |
|linkSearch|rso:Search|TODO| |

h2. Related Object to Annotation/Post
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 its fields.
!related_objects.png!
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 |

An annotation/post is related 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]|
|data annotation|{nf}{?uri a rso:DataAnnotation; oac:hasTarget ?obj}
UNION {?uri a rso:DataAnnotation; oac:hasTarget ?st. ?st a rdf:Statement; dcterms:isPartOf ?obj}{nf}|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 | oac:Body (for annotations) or rso:Forum (for a post). See note below |
| oac:hasTarget | ?uri pointing to one of the [#Link Item Types] |
| rso:root | if ?uri matches one of the conditions above, the respective rso:FC70_Thing |
Note about hasBody:
- For annotation: points to the oac:Body of the annotation. The annotation text is stored in oac:hasBody/rso:P3_has_description.
| 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), and 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:

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>
{noformat}
<link/1> a rso:Link;
oac:hasBody <object/123/annot/23/body>;
oac:hasTarget <object/456>;.
rso:root <object/456>.

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

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

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

All of these statements (incl "a rso:Forum") need to be created, except the last line.

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!

{flowchart}
"<link/1>" [label="<link/1>"\na rso:Link"]
"<link/1>" -> "<object/123/annot/23/body>" [label="oac:hasBody"]
"<link/1>" -> "<object/456>" [label="oac:hasTarget"]
"<link/1>" -> "<object/456>" [label="rso:root"]

"<object/123/annot/23/body>" [label=<
&lt;object/123/annot/23/body&gt;
rso:P3_has_description "...<u>object 456</u>..."
>]

"<forum/123>" [label=<
&lt;forum/123&gt;<br/>
a rso:Forum<br/>
"...<u>data annotation 45</u>..."
>]

"<link/2>" [label="<link/2>\na rso:Link"]
"<link/2>" -> "<forum/123>" [label="oac:hasBody"]
"<link/2>" -> "<object/456/annot/45/body>" [label="oac:hasTarget"]
"<link/2>" -> "<object/456>" [label="rso:root"]

"<object/456/annot/45>" -> "<object/456/annot/45/body>" [label="oac:hasBody"]
"<object/456/annot/45>" -> "<object/456>" [label="oac:hasTarget"]

"<pic.tif/annot/67/body>" [label=<
&lt;pic.tif/annot/67/body&gt;
rso:P3_has_description "...<u>statement 56</u>..."
>]

"<link/3>" [label="<link/3>\na rso:Link"]
"<link/3>" -> "<pic.tif/annot/67/body>" [label="oac:hasBody"]
"<link/3>" -> "<st/56>" [label="oac:hasTarget"]
"<link/3>" -> "<object/456>" [label="rso:root"]

"<st/56>" label ["<st/56>\na rdf:Statement"]
"<st/56>" -> "<object/456>" [label="dcterms:isPartOf"]
{flowchart}

h1. Link API
Annotation's content is stored as text and we need to parse it and find out if any links to objects are present. We will do that when saving annotation/post.

If any linked objects are present in text, we need to refresh the list of related objects for the annotation/post in OWLIM. That is, each time annotation/post is edited we need to parse and recreate the list per annotation/post.
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.

When an, we need to parse the text and extract linked objects. We search for links like:
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

h3. Storing related objects

Links are stored using a method in the DMS2RDF class.

h2. Retrieve Links

We collect the URIs of the MO/AP. If it is Annotation Point, then we load it and get URI if the object it belongs to. (See APLink class and APLink.annotationPoint.main)

After annotation is saved (so that we have the annotation's URI for new annotations), we recreate the list of related objects for this annotation. That is, we delete all related objects and create a new list that contains the latest ones.

Same goes for the forum posts.

Related objects are stored using a method in the&nbsp;DMS2RDF class.

h3. Retrieving related objects
There will be 2 methods in&nbsp;DMS2RDF: in DMS2RDF:
{code:java}
URI[] getReferringAnnotations(URI uri):
// returns all annotations' URIs that mention the MO with this uri or its data fields (annotation points); annotation points
String[] getReferringForumPosts(URI uri):
// returns all forum posts that mention the MO with this uri or its data fields (annotation points); 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}