org.apache.stanbol.entityhub.servicesapi.site
Interface Site

All Known Subinterfaces:

ManagedSite

public interface Site

A site that provides Entities for the Entityhub. Sites are read-only and do support dereferencing of entities. They optionally can support search.

ManagedSites do also support create/update/delete on managed entities. They are also required to support the query. NOTE: this interface replaces ReferencedSite in versions later than 0.10.0-incubating.

Author:

Rupert Westenthaler

Field Summary

static Set<String>

PROHIBITED_SITE_IDS List of ids that are not allowed to be used (case insensitive) for referenced sites.

Method Summary

QueryResultList<Representation>	find(FieldQuery query) Searches for entities based on the parsed FieldQuery and returns representations as defined by the selected fields of the query.
QueryResultList<Entity>	findEntities(FieldQuery query) Searches for Entities based on the parsed FieldQuery and returns the selected Entities including the whole representation.
QueryResultList<String>	findReferences(FieldQuery query) Searches for entities based on the parsed FieldQuery and returns the references (ids).
SiteConfiguration	getConfiguration() Getter for the configuration of this referenced site
InputStream	getContent(String id, String contentType) Getter for the Content of the Entity
Entity	getEntity(String id) Getter for the Entity by the id
FieldMapper	getFieldMapper() Getter for the FieldMappings configured for this Site
String	getId() The Id of this site.
FieldQueryFactory	getQueryFactory() Getter for the QueryFactory implementation preferable used with this Site.
boolean	supportsLocalMode() Returns if this referenced site supports local mode - meaning, that it can be used to search and retrieve entities in offline mode.
boolean	supportsSearch() Returns if this referenced site supports queries.

Field Detail

PROHIBITED_SITE_IDS

static final Set<String> PROHIBITED_SITE_IDS

List of ids that are not allowed to be used (case insensitive) for referenced sites.

Method Detail

getId

String getId()

The Id of this site. This Method MUST return the same value as getConfiguration().getId(). The configured ID MUST NOT be null, empty or one of the PROHIBITED_SITE_IDS.

Returns:

the ID of this site

findReferences

QueryResultList<String> findReferences(FieldQuery query)
                                       throws SiteException

Searches for entities based on the parsed FieldQuery and returns the references (ids). Note that selected fields of the query are ignored.

Parameters:

query - the query

Returns:

the references of the found entities

Throws:

SiteException - If the request can not be executed both on the Cache and by using the EntityDereferencer/ EntitySearcher accessing the remote site. For errors with the remote site the cause will always be a Yard Exceptions. Errors for remote Sites are usually IOExceptions.

find

QueryResultList<Representation> find(FieldQuery query)
                                     throws SiteException

Searches for entities based on the parsed FieldQuery and returns representations as defined by the selected fields of the query. Note that if the query defines also Constraints for selected fields, that the returned representation will only contain values selected by such constraints.

Parameters:

query - the query

Returns:

the found entities as representation containing only the selected fields and there values.

Throws:

SiteException - If the request can not be executed both on the Cache and by using the EntityDereferencer/ EntitySearcher accessing the remote site. For errors with the remote site the cause will always be a Yard Exceptions. Errors for remote Sites are usually IOExceptions.

findEntities

QueryResultList<Entity> findEntities(FieldQuery query)
                                     throws SiteException

Searches for Entities based on the parsed FieldQuery and returns the selected Entities including the whole representation. Note that selected fields of the query are ignored.

Parameters:

query - the query

Returns:

All Entities selected by the Query.

Throws:

SiteException - If the request can not be executed both on the Cache and by using the EntityDereferencer/ EntitySearcher accessing the remote site. For errors with the remote site the cause will always be a Yard Exceptions. Errors for remote Sites are usually IOExceptions.

getEntity

Entity getEntity(String id)
                 throws SiteException

Getter for the Entity by the id

Parameters:

id - the id of the entity

Returns:

the entity or null if not found

Throws:

SiteException - If the request can not be executed both on the Cache and by using the EntityDereferencer/ EntitySearcher accessing the remote site. For errors with the remote site the cause will always be a Yard Exceptions. Errors for remote Sites are usually IOExceptions.

getContent

InputStream getContent(String id,
                       String contentType)
                       throws SiteException

Getter for the Content of the Entity

Parameters:

id - the id of the Entity

contentType - the requested contentType

Returns:

the content or null if no entity with the parsed id was found or the parsed ContentType is not supported for this Entity

Throws:

SiteException - If the request can not be executed both on the Cache and by using the EntityDereferencer/ EntitySearcher accessing the remote site. For errors with the remote site the cause will always be a Yard Exceptions. Errors for remote Sites are usually IOExceptions.

getFieldMapper

FieldMapper getFieldMapper()

Getter for the FieldMappings configured for this Site

Returns:

The FieldMapping present for this Site.

getQueryFactory

FieldQueryFactory getQueryFactory()

Getter for the QueryFactory implementation preferable used with this Site. Note that Site MUST support query instances regardless of there specific implementation. However specific implementations might have performance advantages for query processing and may be even execution. Therefore if one creates queries that are specifically executed on this specific site, that it is best practice to use the instance provided by this method.

Returns:

The query factory of this site.

getConfiguration

SiteConfiguration getConfiguration()

Getter for the configuration of this referenced site

Returns:

the configuration

supportsLocalMode

boolean supportsLocalMode()

Returns if this referenced site supports local mode - meaning, that it can be used to search and retrieve entities in offline mode.

The result MUST reflect the current situation and not be based on the configuration. Meaning, that if the configuration defines a local cache but the cache is currently not available this method needs to return false.

Returns:

if the local mode is currently supported by this referenced site

supportsSearch

boolean supportsSearch()

Returns if this referenced site supports queries. Some Referenced sites might not be able to support queries (e.g. if a remote linked data endpoint does not support an SPARQL endpoint). In such cases the dereferencing functionality can still be used to retrieve representations for entities by IDs. However all find** methods could not be used.

The result MUST refelct the current situation and not be based on the configuration. E.g. if the remote site does not support querys and the local cache is temporary not available this method would need to support false even that based on the configuration the site would theoretically support queries.

TODO: This need to be extended as soon as support for multiple query languages is added.

Returns:

if this referenced site supports queries for entities.