org.nuxeo.ecm.platform.semanticentities

Interface LocalEntityService

All Known Implementing Classes:

LocalEntityServiceImpl

public interface LocalEntityService

Service to handle semantic entities linked to document in the local repository. Data to seed those entities can come from remote sources by using RemoteEntityService instead.

Author:

ogrisel

Method Summary

Methods

Modifier and Type	Method and Description
OccurrenceRelation	addOccurrence(CoreSession session, DocumentRef docRef, DocumentRef entityRef, String quoteContext, int startPosInContext, int endPosInContext) Assert that an entity is referred to in the text content of a document.
OccurrenceRelation	addOccurrences(CoreSession session, DocumentRef docRef, DocumentRef entityRef, List<OccurrenceInfo> occurrences) Add several occurrences of the same entity in to a given document (occurring in several text snippets).
void	addOccurrences(CoreSession session, DocumentRef ref, EntitySuggestion entitySuggestion, List<OccurrenceInfo> occurrences) Add several occurrences of the same entity in to a given document (occurring in several text snippets).
DocumentModel	asLocalEntity(CoreSession session, EntitySuggestion suggestion) Ensure that the suggestion is local.
DocumentModel	getEntityContainer(CoreSession session) The entity container is a singleton container document where to create the entities.
Set<String>	getEntityTypeNames()
DocumentModel	getLinkedLocalEntity(CoreSession session, URI remoteEntityURI) Lookup the local repo to find a local entity that is linked to the given remote entity URI through a owl:sameAs relationship.
OccurrenceRelation	getOccurrenceRelation(CoreSession session, DocumentRef documentRef, DocumentRef entityRef) Find the occurrence relation instance linking a document to an entity.
PageProvider<DocumentModel>	getRelatedDocuments(CoreSession session, DocumentRef entityRef, String documentType) Find entities of a given type related to a given document.
PageProvider<DocumentModel>	getRelatedEntities(CoreSession session, DocumentRef docRef, String entityType) Find entities of a given type related to a given document.
void	removeOccurrences(CoreSession session, DocumentRef docRef, DocumentRef entityRef, boolean forcePhysicalDelete) Remove any occurrence information of an entity on the specified documents.
List<DocumentModel>	suggestDocument(CoreSession session, String keywords, String type, int maxSuggestions) Helper method to suggest documents by keyword match on fulltext content.
List<EntitySuggestion>	suggestEntity(CoreSession session, OccurrenceGroup group, int maxSuggestions) Helper method to suggest entities by keyword match on names.
List<EntitySuggestion>	suggestEntity(CoreSession session, String keywords, String type, int maxSuggestions) Helper method to suggest entities by keyword match on names.
List<EntitySuggestion>	suggestLocalEntity(CoreSession session, String keywords, String type, int maxSuggestions) Helper method to suggest local entities by keyword match on names.

Method Detail

getEntityContainer

DocumentModel getEntityContainer(CoreSession session)
                                 throws ClientException

The entity container is a singleton container document where to create the entities. It is useful to have this has a container document to be able to use the regular ACL system of the Nuxeo repository to tell which group of users has the right to create, edit or browse entities.

Returns:

the DocumentModel of type EntityContainer (create it if missing) or null if the user does not have the permission to see it

Throws:

ClientException

suggestEntity

List<EntitySuggestion> suggestEntity(CoreSession session,
                                   String keywords,
                                   String type,
                                   int maxSuggestions)
                                     throws ClientException,
                                            DereferencingException

Helper method to suggest entities by keyword match on names. This method will call both the local entity lookup and the remote entity lookup and merge the results based on the sameas relationship.

Parameters:

session - an active CoreSession used for local entity queries.

keywords - keywords to match the entity names

type - the Nuxeo type name of entity to match (or null)

maxSuggestions - maximum number of entities to suggest

Returns:

a list of maximum maxSuggestions matching entities

Throws:

ClientException

DereferencingException

suggestEntity

List<EntitySuggestion> suggestEntity(CoreSession session,
                                   OccurrenceGroup group,
                                   int maxSuggestions)
                                     throws DereferencingException,
                                            ClientException

Helper method to suggest entities by keyword match on names. This method will call both the local entity lookup and the remote entity lookup and merge the results based on the sameas relationship. This method allows to pass an OccurrenceGroup instance directly. If the group has pre-fetched remote entities some calls to the remote sources are spared to reduce performance hits induced by network latency.

Parameters:

session - an active CoreSession used for local entity queries.

group - a group of occurrence pointing to a supposedly unique entity to be resolved in the various local and remote entity sources.

maxSuggestions - maximum number of entities to suggest

Returns:

a list of maximum maxSuggestions matching entities

Throws:

DereferencingException

ClientException

suggestLocalEntity

List<EntitySuggestion> suggestLocalEntity(CoreSession session,
                                        String keywords,
                                        String type,
                                        int maxSuggestions)
                                          throws ClientException

Helper method to suggest local entities by keyword match on names.

Parameters:

keywords - keywords to match the entity names

type - the Nuxeo type name of entity to match (or null)

maxSuggestions - maximum number of entities to suggest

Returns:

a list of maximum maxSuggestions matching entities

Throws:

ClientException

suggestDocument

List<DocumentModel> suggestDocument(CoreSession session,
                                  String keywords,
                                  String type,
                                  int maxSuggestions)
                                    throws Exception

Helper method to suggest documents by keyword match on fulltext content.

Parameters:

keywords - keywords to match the document names

type - the Nuxeo type name of documents to match (or null)

maxSuggestions - maximum number of entities to suggest

Returns:

a list of maximum maxSuggestions matching documents ordered by relevance

Throws:

Exception

addOccurrence

OccurrenceRelation addOccurrence(CoreSession session,
                               DocumentRef docRef,
                               DocumentRef entityRef,
                               String quoteContext,
                               int startPosInContext,
                               int endPosInContext)
                                 throws ClientException

Assert that an entity is referred to in the text content of a document. As document content might change the occurrence position is identified by a quoteContext String that contains the surrounding sentences and the position of the expression referring to the entity is relative to this context.

Parameters:

session - active session to the repository holding the document and entities

docRef - the id of the document referring to the entity

entityRef - the id of the entity referred to by the document snippet

quoteContext - the text snippet holding the expression pointing to the entity

startPosInContext - the position of the start of the expression

endPosInContext -

Returns:

the DocumentModel of type Occurrence holding the relation

Throws:

ClientException

addOccurrences

OccurrenceRelation addOccurrences(CoreSession session,
                                DocumentRef docRef,
                                DocumentRef entityRef,
                                List<OccurrenceInfo> occurrences)
                                  throws ClientException

Add several occurrences of the same entity in to a given document (occurring in several text snippets).

Parameters:

session - active session to the repository holding the document and entities

docRef - the id of the document referring to the entity

entityRef - the id of the entity referred to by the document snippet

occurrences - list of occurrence data to add to the relationship

Returns:

an OccurrenceRelation holding the aggregated occurrence data

Throws:

ClientException

addOccurrences

void addOccurrences(CoreSession session,
                  DocumentRef ref,
                  EntitySuggestion entitySuggestion,
                  List<OccurrenceInfo> occurrences)
                    throws ClientException,
                           IOException

Add several occurrences of the same entity in to a given document (occurring in several text snippets).

Parameters:

session - active session to the repository holding the document and entities

docRef - the id of the document referring to the entity

entitySuggestion - entity to dereference if not local, and link to it

occurrences - list of occurrence data to add to the relationship

Throws:

IOException - if dereferencing remote entity fails

ClientException

removeOccurrences

void removeOccurrences(CoreSession session,
                     DocumentRef docRef,
                     DocumentRef entityRef,
                     boolean forcePhysicalDelete)
                       throws ClientException

Remove any occurrence information of an entity on the specified documents. If the entity was automatically created (by the "system" principal) and nobody else edited it, it is also removed from the entity base. If the trash service if applicable. Otherwise the related document(s) are simply deleted from the repository.

Parameters:

session - active session to the repository holding the document and entities

docRef - the id of the document referring to the entity

entityRef - the id of the entity to remove occurrences for

forcePhysicalDelete - perform physical deletion (no trash)

Throws:

ClientException - if the repository fails or the document does not exist.

getOccurrenceRelation

OccurrenceRelation getOccurrenceRelation(CoreSession session,
                                       DocumentRef documentRef,
                                       DocumentRef entityRef)
                                         throws ClientException

Find the occurrence relation instance linking a document to an entity. Return null if no such relation exist in the repository.

Parameters:

session - the repository session where the document is stored

documentRef - the reference of the source document

entityRef - the reference of the targeted entity

Returns:

an instance of OccurrenceRelation or null

Throws:

ClientException

getRelatedEntities

PageProvider<DocumentModel> getRelatedEntities(CoreSession session,
                                             DocumentRef docRef,
                                             String entityType)
                                               throws ClientException

Find entities of a given type related to a given document.

Parameters:

session - the repository session where the document is stored

docRef - the reference of the document to seach entities for

entityType - the Nuxeo type of entities to lookup (can be null)

Returns:

a paginated collection of matching entities

Throws:

ClientException

getRelatedDocuments

PageProvider<DocumentModel> getRelatedDocuments(CoreSession session,
                                              DocumentRef entityRef,
                                              String documentType)
                                                throws ClientException

Find entities of a given type related to a given document.

Parameters:

session - the repository session where the document is stored

entityRef - the reference of the entities to search documents for

documentType - the Nuxeo type of documents to lookup (can be null)

Returns:

a paginated collection of matching entities

Throws:

ClientException

getLinkedLocalEntity

DocumentModel getLinkedLocalEntity(CoreSession session,
                                 URI remoteEntityURI)
                                   throws ClientException

Lookup the local repo to find a local entity that is linked to the given remote entity URI through a owl:sameAs relationship.

Parameters:

remoteEntityURI - the entity URI to lookup locally

Returns:

the matching local document model or null if none

Throws:

ClientException - in case of problem accessing the local repo

getEntityTypeNames

Set<String> getEntityTypeNames()
                               throws Exception

Returns:

the document type names deriving from the Entity type

Throws:

Exception - thrown if the TypeManager is not available

asLocalEntity

DocumentModel asLocalEntity(CoreSession session,
                          EntitySuggestion suggestion)
                            throws ClientException,
                                   IOException

Ensure that the suggestion is local. If not, use the remote entity service to dereference it into a new local entity using the provided core session.

Throws:

ClientException

IOException