org.apache.stanbol.entityhub.servicesapi.yard
Interface Yard

All Known Subinterfaces:

Cache

public interface Yard

The Yard represents a local cache for Representations of the Entities and Symbols managed by a referenced site.

Referenced Sites need to provide the configuration if there representations should be cached locally. This is done by using one of the defined CacheStrategy.

The Idea is not to have one big Yard that caches all the representations, but to provide the possibility to use different caches. This means, that each Site can have its own Yard instance. However several Sites might also use the same Yard.

The YardManager is an singleton services that manages the different Yard instances and provides an central point of access for the Entityhub and the SiteManager.

This should also allow for implementing Yards that are based on

• Indexes generated by dumps of the referred Site
• local installations of the software used by the referred site
• and so on ...

TODO: The framework need to provide a special Yard for storing Symbol and EntityMapping information. This Yard is currently referenced as Entityhub-Yard. Do we need also a special API for this Yard? One could still provide a "default" implementation that implements this interface based on a Component that provides the normal Yard service.

Side note: The name yard was chosen as name because in farming "yard" refers to a piece of enclosed land for farm animals or other agricultural purpose and the storage component of the entityhub does the same thing for Entities.

Author:

Rupert Westenthaler

Field Summary

static String	DESCRIPTION
static String	ID
static String	NAME

Method Summary

Representation	create() Creates a new empty representation and stores it in the Yard.
Representation	create(String id) Creates a new representation for the given id
QueryResultList<Representation>	find(FieldQuery query) Getter for a view onto the Representations selected by the Query.
QueryResultList<String>	findReferences(FieldQuery query) Finds all representations base on the parse query.
QueryResultList<Representation>	findRepresentation(FieldQuery query) Searches for all the Representation fulfilling the constraints of the query and returns the (whole) representation as stored in the Yard.
String	getDescription()
String	getId() Getter for the unique ID of the Yard
String	getName()
FieldQueryFactory	getQueryFactory() Getter for the FieldQueryFactory used by this Yard
Representation	getRepresentation(String id) Getter for the representation based on the id.
ValueFactory	getValueFactory() Getter for the ValueFactory instance used by this Yard to create Representation, Reference and Text instances.
boolean	isRepresentation(String id) checks if a representation with the given id is present in the Yard
void	remove(Iterable<String> ids) Removes all the Representation of the parsed ids.
void	remove(String id) Removes the Representation with the given id
void	removeAll() Removes all the Representation managed by this Yard
Iterable<Representation>	store(Iterable<Representation> representations) Stores all the parsed representation in a single chunk in the Yard.
Representation	store(Representation representation) Stores the representation in the Yard.
Iterable<Representation>	update(Iterable<Representation> representations) Updates the store with the new state of the parsed representations.
Representation	update(Representation representation) Updates the store with the new state of the parsed representation

Field Detail

ID

static final String ID

See Also:

Constant Field Values

NAME

static final String NAME

See Also:

Constant Field Values

DESCRIPTION

static final String DESCRIPTION

See Also:

Constant Field Values

Method Detail

getId

String getId()

Getter for the unique ID of the Yard

Returns:

the id

getName

String getName()

getDescription

String getDescription()

create

Representation create()
                      throws YardException

Creates a new empty representation and stores it in the Yard. The Yard is responsible to assign a valid ID.

Returns:

the created Representation initialised with a valid ID

Throws:

YardException - On any error while creating or storing the representation

create

Representation create(String id)
                      throws IllegalArgumentException,
                             YardException

Creates a new representation for the given id

Parameters:

id - the id for the new representation or null to indicate that the Yard should assign an id.

Returns:

the created Representation

Throws:

IllegalArgumentException - if the parsed id is not valid (especially if an empty string is parsed as ID) or there exists already a representation with the parsed id.

YardException - On any error while creating or storing the representation

store

Representation store(Representation representation)
                     throws NullPointerException,
                            YardException

Stores the representation in the Yard. if the parsed representation is not present in the Yard it will add it to the Yard.

Parameters:

representation - the representation

Returns:

the representation as stored

Throws:

NullPointerException - if null is parsed as argument.

YardException - On any error related to the Yard

store

Iterable<Representation> store(Iterable<Representation> representations)
                               throws NullPointerException,
                                      YardException

Stores all the parsed representation in a single chunk in the Yard. This can improve performance, because it does not require multiple commits.
null values are ignored and added as null in the returned Iterable. Otherwise same as store(Representation).

Parameters:

representations - all the representations to store. null values are ignored and MUST NOT throw any exceptions. Parsing an Iterable without any element will have none effect but also MUST NOT throw an exception.

Returns:

the stored representations in the same iteration order

Throws:

NullPointerException - if null is parsed as Iterable, but NOT if the parsed Iterable does not contain any Elements or the null value.

YardException - On any error related to the Yard

remove

void remove(String id)
            throws IllegalArgumentException,
                   YardException

Removes the Representation with the given id

Parameters:

id - the id

Throws:

IllegalArgumentException - if the parsed ID is null or not valid formatted

YardException - On any error related to the Yard

remove

void remove(Iterable<String> ids)
            throws IllegalArgumentException,
                   YardException

Removes all the Representation of the parsed ids. null values are ignored.

Parameters:

ids - the iterable over the ids to remove

Throws:

IllegalArgumentException - if null is parsed as iterable

YardException - On any error related to the Yard

removeAll

void removeAll()
               throws YardException

Removes all the Representation managed by this Yard

Throws:

YardException - On any error related to the Yard

isRepresentation

boolean isRepresentation(String id)
                         throws YardException,
                                IllegalArgumentException

checks if a representation with the given id is present in the Yard

Parameters:

id - the id. Calls with null are ignored

Returns:

true if a representation with the id is present in the Yard. Otherwise false.

Throws:

NullPointerException - if null is parsed as ID

IllegalArgumentException - if the parsed ID is not valid formatted (especially if an empty String is parsed as ID

YardException - On any error related to the Yard

getRepresentation

Representation getRepresentation(String id)
                                 throws YardException,
                                        IllegalArgumentException

Getter for the representation based on the id. Calls with id = null should return null.

Parameters:

id - the id.

Returns:

The representation with the parsed id or null if no representation with this id is present in the Yard

Throws:

NullPointerException - if null is parsed as id

IllegalArgumentException - if the parsed ID is not valid formatted

YardException - On any error related to the Yard

update

Representation update(Representation representation)
                      throws YardException,
                             IllegalArgumentException

Updates the store with the new state of the parsed representation

Parameters:

representation - the representation

Returns:

the representation as stored

Throws:

NullPointerException - If null is parsed as representation

IllegalArgumentException - if the parsed representation is not present in the Yard (and can not be updated therefore). TODO: evaluate if this should really throw only a RuntimeException.

YardException - On any error related to the Yard

update

Iterable<Representation> update(Iterable<Representation> representations)
                                throws YardException,
                                       IllegalArgumentException

Updates the store with the new state of the parsed representations. This can improve performance, because it does not require multiple commits.
null values are ignored and added as null in the returned Iterable. Otherwise same as update(Representation).

Parameters:

representations - the representations to update

Returns:

the updated stored representations in the same iteration order

Throws:

YardException - On any error related to the Yard

IllegalArgumentException - if null is parsed as Iterable

findReferences

QueryResultList<String> findReferences(FieldQuery query)
                                       throws YardException,
                                              IllegalArgumentException

Finds all representations base on the parse query. Selected fields of the query may be ignored, because only the ids of the found representations are returned

Parameters:

query - The query

Returns:

A ResultList containing the IDs of the found representations

Throws:

IllegalArgumentException - if null is parsed as Query

YardException - On any error related to the Yard

find

QueryResultList<Representation> find(FieldQuery query)
                                     throws YardException,
                                            IllegalArgumentException

Getter for a view onto the Representations selected by the Query. Note that the returned Representations will only include fields that are selected by the parsed query. And such fields will only contain values that are not filtered by the query.

Parameters:

query - the query

Returns:

the view onto selected representations as defined by the query

Throws:

IllegalArgumentException - if null is parsed as Query

YardException - On any error related to the Yard

findRepresentation

QueryResultList<Representation> findRepresentation(FieldQuery query)
                                                   throws YardException,
                                                          IllegalArgumentException

Searches for all the Representation fulfilling the constraints of the query and returns the (whole) representation as stored in the Yard. Note that any as selected fields of the parsed query are ignored. Use find(FieldQuery) to retrieve representations that only contain values for fields marked as selected by the parsed query.

Parameters:

query - the Query used to select representations in the Yard

Returns:

the selected representations as stored in this yard.

Throws:

IllegalArgumentException - if null is parsed as Query

YardException - On any error related to the Yard

getQueryFactory

FieldQueryFactory getQueryFactory()

Getter for the FieldQueryFactory used by this Yard

Returns:

the FieldQueryFactory

getValueFactory

ValueFactory getValueFactory()

Getter for the ValueFactory instance used by this Yard to create Representation, Reference and Text instances.

Returns:

the valueFactory used by the store