org.gnowsis.pimo
Interface TaggingApi

All Known Implementing Classes:

TaggingApiApiImpl, TaggingApiImpl

public interface TaggingApi

Tag resources to things, saying that this document (resource) is about that topic (thing). Use this API to add tags to resources, remove the tags and list the tags. Many of these calls here use the PimoService to realise them. This is a simplification of PimoService The API can also make suggestions for possible tags of documents. It will use our text-classification system for this.

Author:

sauermann

Field Summary

static String

API_NAME

Method Summary

boolean	addTagToResource(String tagUri, String resourceUri) add a new tag to the passed resource.
String	createNewTagForResource(String tagName, String resourceUri) Create a new tag and add the resource as occurrence of the tag.
boolean	ensureResourceIsInStore(String resourceUri, String label, String typeUri, String fulltext, String metadataXML) check if the passed resource is in the resource-store.
Collection<Tag>	getPossibleTagsFor(String resourceUri) get possible tags for this resource, load the fulltext and metadata of the resource from the resource-storage.
Collection<Tag>	getPossibleTagsForTagName(String snippet) Find possible tags that contain the passed name.
Collection<Tag>	getPossibleTagsForText(String uri, String fullText) get possible tags for this resource, the fulltext of the resource and its uri are passed in.
Map<Tag,Float>	getRelatedTagsforTermsWeighted(Collection<String> terms) Get possible tags and their evidence for list of terms and its uri are passed in.
Collection<Tag>	getTagsOf(String resourceUri) get me the tags that are already associated to this resource.
Map<String,Collection<Tag>>	getTagsOfMany(Collection<String> uris) get the tags of many resources.
Collection<Tag>	getTagsWithName(String name) get tag(s) with exactly this name
boolean	removeTag(String tagUri, String resourceUri) Remove the occurrence between the resource and the thing.

Field Detail

API_NAME

static final String API_NAME

See Also:

Constant Field Values

Method Detail

getPossibleTagsFor

@Contains(value=Tag.class)
Collection<Tag> getPossibleTagsFor(String resourceUri)
                                   throws ResourceNotFoundException

get possible tags for this resource, load the fulltext and metadata of the resource from the resource-storage. The resource has to be stored already, which usually will not work for http-web-uris. Store them first in the resource-storage.

Parameters:

resourceUri - the uri of the resource

Returns:

a list of possible tags, better ones first.

Throws:

ResourceNotFoundException - if the passed uri is unknown in the storage

getPossibleTagsForText

@Contains(value=Tag.class)
Collection<Tag> getPossibleTagsForText(String uri,
                                                         String fullText)
                                       throws ResourceNotFoundException

get possible tags for this resource, the fulltext of the resource and its uri are passed in.

Parameters:

uri -

text -

Returns:

Throws:

ResourceNotFoundException

getRelatedTagsforTermsWeighted

Map<Tag,Float> getRelatedTagsforTermsWeighted(Collection<String> terms)
                                              throws Exception

Get possible tags and their evidence for list of terms and its uri are passed in.

Parameters:

terms - List of terms

Returns:

Throws:

Exception

getPossibleTagsForTagName

@Contains(value=Tag.class)
Collection<Tag> getPossibleTagsForTagName(String snippet)

Find possible tags that contain the passed name. Existing tags are searched by pimo:label, pimo:wikiName and pimo:altLabel, and perhaps also the connected wiki-text.

Parameters:

snippet - the string that has to be contained in the thing to be usable as a Tag

Returns:

an iterator of possible tags, ordered by relevance (better tags first).

getTagsWithName

@Contains(value=Tag.class)
Collection<Tag> getTagsWithName(String name)

get tag(s) with exactly this name

Parameters:

name -

Returns:

a collection with zero, one or more tags.

getTagsOf

@Contains(value=Tag.class)
Collection<Tag> getTagsOf(String resourceUri)
                          throws ResourceNotFoundException

get me the tags that are already associated to this resource. Has to be fast-as-hell.

Parameters:

uri - the uri of the resource in question

Returns:

the list of tags associated to the resource.

Throws:

ResourceNotFoundException

getTagsOfMany

Map<String,Collection<Tag>> getTagsOfMany(Collection<String> uris)

get the tags of many resources. result is a map where a URI of a resource is mapped to the tags associated. Used to augment the display of large lists of resources, for example the e-mail inbox. Has to be fast as hell (preferably one sparql query). If no tags for a resource uri are not found, the resource is ignored and will not be included in the results.

Parameters:

a - list of uris of resource for whom to search for tags.

Returns:

a map, mapping resource-uris to tags

addTagToResource

boolean addTagToResource(String tagUri,
                         String resourceUri)
                         throws ResourceNotFoundException,
                                ThingNotFoundException

add a new tag to the passed resource. The tag has to be identified using its uri from the PIMO of the user. Both have to exist. If the tag was already there, the method returns false.

Parameters:

tagUri - the uri of the thing that is used to tag

resourceUri - the uri of the resource being tagged. The resource already to be stored in resource-store. This will not be checked, you have to check it before calling.

Returns:

true, if the occurrence was created, false if it was already there

Throws:

ResourceNotFoundException - if the resource was not in resource-storage

ThingNotFoundException - it the thing was not in the pimo

createNewTagForResource

String createNewTagForResource(String tagName,
                               String resourceUri)
                               throws ResourceNotFoundException

Create a new tag and add the resource as occurrence of the tag. The tag is identified using its name. If a thing with this name already exists (either the label, altLabel or wikiname is equals name), the existing thing will be used, and the existing uri returned. Otherwise, a new tag will be created with default type (pimo:Topic) and the resource is an occurrence of the tag. Uri of the new tag returned.

Parameters:

tagName - the name of the tag to create

resourceUri - the uri of the resource being tagged. The resource already to be stored in resource-store. This will not be checked, you have to check it before calling.

Returns:

uri of the newly created topic.

Throws:

ResourceNotFoundException - if the resource was not in resource-storage

removeTag

boolean removeTag(String tagUri,
                  String resourceUri)
                  throws ResourceNotFoundException,
                         PimoInvalidException,
                         OntologyReadonlyException

Remove the occurrence between the resource and the thing.

Parameters:

tagUri - the uri of the thing that was used as tag

resourceUri - the uri of the resource that was used as tag

Returns:

true, if the occurrence was there and removed. False, if there was no occurrence.

Throws:

ResourceNotFoundException

OntologyReadonlyException

PimoInvalidException

ensureResourceIsInStore

boolean ensureResourceIsInStore(String resourceUri,
                                String label,
                                String typeUri,
                                String fulltext,
                                String metadataXML)
                                throws IOException,
                                       DataStoreException

check if the passed resource is in the resource-store. If it is already, do nothing. If the resource is not in the resource-store, take the passed parameters and add it.

Parameters:

resourceUri - uri of the resource

label - label of the resource

typeUri - type of the resource (RDF type, has to be a uri)

fulltext - (optional) fulltext description of the resource (for searching)

metadataXML - (optional) metadata of the resource as RDF/XML string.

Returns:

true, if the resource was added. false, if the resource was already in the store.

Throws:

IOException - when the passed metadataXML is bogus

DataStoreException - if the resource cannot be stored