org.apache.stanbol.entityhub.servicesapi
Interface Entityhub

public interface Entityhub

The Entityhub defines an interface that allows to manage Entities. Entities managed by the Entityhub are often referred by "locally managed Entities" to differentiate them form entities managed by ReferencedSites.

The Entityhub supports full CRUD support for Entities and also allows to import Entities from Referenced sites.

In addition to Entities the Entityhub also allows to work with mappings between Entities of ReferencedSites with locally managed Entities.

Author:

Rupert Westenthaler

Field Summary

static String	DEFAUTL_ENTITYHUB_PREFIX
static Set<String>	ENTITYHUB_IDS Protected keys to be used as name for the Entityhub.

Method Summary

Entity	delete(String id) Deletes the Entity with the parsed id.
QueryResultList<Representation>	find(FieldQuery query) Searches for symbols based on the parsed FieldQuery and returns representations as defined by the selected fields of the query.
QueryResultList<Entity>	findEntities(FieldQuery query) Searches for Signs based on the parsed FieldQuery and returns the selected Signs including the whole representation.
QueryResultList<String>	findEntityReferences(FieldQuery query) Searches for symbols based on the parsed FieldQuery and returns the references (ids).
EntityhubConfiguration	getConfig() Getter for the Configuration of the Entityhub
Entity	getEntity(String entityId) Getter for an Entity managed by the Entityhub.
FieldMapper	getFieldMappings() Getter for the FieldMappings configured for this Site
Entity	getMappingById(String id) Getter for a MappedEntity based on the ID of the mapping itself.
Entity	getMappingBySource(String source) Getter for all mappings by the ID of the source.
Collection<Entity>	getMappingsByTarget(String entityId) Getter for all the mappings by the id of the target.
FieldQueryFactory	getQueryFactory() Getter for the FieldQueryFactory instance of the Entityhub.
Yard	getYard() Getter for the Yard storing the Entities and Mappings managed by this Entityhub.
Entity	importEntity(String reference) Imports an Entity from a referenced site to the Entityhub.
boolean	isRepresentation(String id) Checks if an Entity with the parsed id is managed by the Entityhub.
Entity	lookupLocalEntity(String reference) Getter for the locally managed Entity based on a reference to a Entity.
Entity	lookupLocalEntity(String reference, boolean create) Getter for the locally managed Entity based on a reference to a Entity.
Entity	setState(String id, ManagedEntityState state) Setter for the state of an Entity.
Entity	store(Representation representation) Stores (create or updates) the parsed representation within the Entityhub.

Field Detail

DEFAUTL_ENTITYHUB_PREFIX

static final String DEFAUTL_ENTITYHUB_PREFIX

See Also:

Constant Field Values

ENTITYHUB_IDS

static final Set<String> ENTITYHUB_IDS

Protected keys to be used as name for the Entityhub. Such keys MUST NOT be used as ids for ReferencedSites. (case insensitive)

The protected values are

• "local"
• "entityhub"

Method Detail

getYard

Yard getYard()

Getter for the Yard storing the Entities and Mappings managed by this Entityhub.

Note that the Yard can be reconfigured without restarting the Entityhub.

Returns:

The yard instance used to store the data of the Entityhub - the EntityhubYard

lookupLocalEntity

Entity lookupLocalEntity(String reference)
                         throws EntityhubException

Getter for the locally managed Entity based on a reference to a Entity. If a id of an locally managed Entity is parsed this Entity is returned. In any other case this Method searches if the parsed reference is mapped to a locally managed Entity and returns this Entity instead.

Parameters:

reference - the id of any Entity

Returns:

the locally managed Entity or null if no symbol for the parsed entity is available

Throws:

EntityhubException - On any error while performing the operation

lookupLocalEntity

Entity lookupLocalEntity(String reference,
                         boolean create)
                         throws IllegalArgumentException,
                                EntityhubException

Getter for the locally managed Entity based on a reference to a Entity. If a id of an locally managed Entity is parsed this Entity is returned. In any other case this Method searches if the parsed reference is mapped to a locally managed Entity and returns this Entity instead.

If create=true this method can imports Entities to the entityhub based on the definition(s) of referenced sites.

Parameters:

reference - the id of the referenced Entity

create - if true the Entityhub will try to create a new locally managed Entity by importing an Entity from referenced sites.

Returns:

the locally managed Entity or null if the parsed reference is not known by any referenced sites.

Throws:

IllegalArgumentException - If the referenced Entity was found, no existing EntityMapping is present, but it is not possible to create a locally managed Entity for the referenced Entity (normally this is because of insufficient/invalid information of the referenced Entity.

EntityhubException - On any error while performing the operation

getEntity

Entity getEntity(String entityId)
                 throws IllegalArgumentException,
                        EntityhubException

Getter for an Entity managed by the Entityhub. This method does only work with references to locally managed Entities.

Parameters:

entityId - the ID of the locally managed Entity

Returns:

the Entity or null if no Entity with that ID is managed by the Entityhub.

Throws:

IllegalArgumentException - if null or an empty String is parsed as symbolId or if the parsed ID does not represent a Entity

EntityhubException - On any error while performing the operation

importEntity

Entity importEntity(String reference)
                    throws IllegalStateException,
                           IllegalArgumentException,
                           EntityhubException

Imports an Entity from a referenced site to the Entityhub. If there is already an Entity present for the parsed reference, than this Method throws an IllegalStateException. If the referenced Entity is not found on any referenced site, than null is returned. If the referenced Entity provides insufficient data to create a locally managed Entity, than an IllegalArgumentException is thrown.

Parameters:

reference - the id of the Entity to import

Returns:

the imported Entity or null if the import was not successful.

Throws:

IllegalStateException - if there exists already a Entity for the parsed reference in the entityhub

IllegalArgumentException - If an import is not possible (e.g. because the Representation of the Entity provides insufficient data or some configuration that importing Entities from this referenced site is not allowed).

EntityhubException - On any error while performing the operation

getMappingById

Entity getMappingById(String id)
                      throws EntityhubException,
                             IllegalArgumentException

Getter for a MappedEntity based on the ID of the mapping itself.

Parameters:

id - the id of the mapped entity

Returns:

the MappedEntity or null if none was found

Throws:

EntityhubException - On any error while performing the operation

IllegalArgumentException - If null or an empty string is parsed as ID or if the parsed ID does not represent an EntityMapping

getMappingBySource

Entity getMappingBySource(String source)
                          throws EntityhubException

Getter for all mappings by the ID of the source. The source is the id of an Entity managed by an referenced site. TODO: check if an Entity of an referenced site can be mapped to more than one locally managed Entity

Parameters:

source - the ID of the source (an entity managed by some referenced site)

Returns:

Iterator over all the Mappings defined for this entity

Throws:

EntityhubException - On any error while performing the operation

getQueryFactory

FieldQueryFactory getQueryFactory()

Getter for the FieldQueryFactory instance of the Entityhub. Typical implementation will return the factory implementation used by the current Yard used by the entity hub.

Returns:

the query factory

getFieldMappings

FieldMapper getFieldMappings()

Getter for the FieldMappings configured for this Site

Returns:

The FieldMapping present for this Site.

getMappingsByTarget

Collection<Entity> getMappingsByTarget(String entityId)
                                       throws EntityhubException

Getter for all the mappings by the id of the target. The target is an locally managed entity.

Parameters:

entityId - the id of the target (a locally managed entity)

Returns:

the mappings for the parsed target

Throws:

EntityhubException - On any error while performing the operation

findEntityReferences

QueryResultList<String> findEntityReferences(FieldQuery query)
                                             throws EntityhubException

Searches for symbols 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 symbols

Throws:

EntityhubException - On any error while performing the operation

find

QueryResultList<Representation> find(FieldQuery query)
                                     throws EntityhubException

Searches for symbols 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 symbols as representation containing only the selected fields and there values.

Throws:

EntityhubException - On any error while performing the operation

findEntities

QueryResultList<Entity> findEntities(FieldQuery query)
                                     throws EntityhubException

Searches for Signs based on the parsed FieldQuery and returns the selected Signs 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:

EntityhubException - On any error while performing the operation

isRepresentation

boolean isRepresentation(String id)
                         throws EntityhubException,
                                IllegalArgumentException

Checks if an Entity with the parsed id is managed by the Entityhub.

Parameters:

id - the id of the entity

Returns:

If an Entity with the given id is managed by the Entityhub

Throws:

EntityhubException - On any error while performing the operation

IllegalArgumentException - if null or an empty String is parsed as id

store

Entity store(Representation representation)
             throws EntityhubException,
                    IllegalArgumentException

Stores (create or updates) the parsed representation within the Entityhub. The representation can be both data or metadata of an entity.

To only allow create or update operations check first with isRepresentation(String).

Parameters:

representation - the representation to be updated

Returns:

The updated entity.

Throws:

EntityhubException - On any error while performing the operation

IllegalArgumentException - if null is parsed as Representation or if no Representation with the parsed id is managed by the Entityhub.

delete

Entity delete(String id)
              throws EntityhubException,
                     IllegalArgumentException

Deletes the Entity with the parsed id. This will delete the entity and all its information including metadata and mappings to other entities form the Entityhub. To mark the Entity as removed use setState(String, ManagedEntityState) with ManagedEntityState.removed as second parameter.

Parameters:

id - The id of the Entity to delete

Returns:

The deleted Entity

Throws:

EntityhubException - On any error while performing the operation

IllegalArgumentException - if null or an empty String is parsed as id

setState

Entity setState(String id,
                ManagedEntityState state)
                throws EntityhubException,
                       IllegalArgumentException

Setter for the state of an Entity. This can be used to directly set the ManagedEntityState as stored with the metadata of an entity.

Parameters:

id - The id of the Entity (or the metadata of the entity)

state - the new state

Returns:

the entity with the new state or null if no entity for the parsed id was found.

Throws:

EntityhubException - On any error while performing the operation

IllegalArgumentException - if null is parsed as any of the two parameter or if the parsed id is an empty string

getConfig

EntityhubConfiguration getConfig()

Getter for the Configuration of the Entityhub

Returns:

the configuration