org.eclipse.lyo.store

Interface Store

All Known Implementing Classes:

JenaTdbStoreImpl, SparqlStoreImpl

public interface Store

Store is the main interface for operations on OSLC Resources with the backing triplestore. Please use StoreFactory to instantiate concrete implementations.

The store is designed to be used for storing individual IResources or unordered sets of them (due to how triplestores work).

Resources are stored under a specific named graph similar to how the keys are used in the Map. That is, a unique named graph must be supplied to store a (group of) resource(s) under the same named graph in the triplestore. The named graph is expected to be a valid URI.

In the case of an individual resource, you can use the resource's about URI as the namedGraph.

Example uses:

• store.containsKey(resource.getAbout().toString()) - returns whether a resource is stored under its named graph URI
• store.putResources(resource.getAbout().toString(), resource) - store the resource under the namedGraph that corresponds to the about URI of the resource. Equivalent of store.putResource(resource)
• store.putResources(serviceProviderId, resources) - store all resources managed by a given Service Provider, under a named graph identified by the serviceProviderId URI. This assumes that the serviceProviderId is a valid URI.

Since:

0.14.0

Version:

$version-stub$

Author:

Andrew Berezovskyi (andriib@kth.se)

Method Summary

Modifier and Type	Method and Description
default <T extends org.eclipse.lyo.oslc4j.core.model.IResource> boolean	appendResource(URI namedGraphUri, T resource) Adds an OSLC IResource instance in addition to other instances already present on this named graph into the triplestore.
<T extends org.eclipse.lyo.oslc4j.core.model.IResource> boolean	appendResources(URI namedGraphUri, Collection<T> resources) Adds OSLC IResource instances in addition to other instances already present on this named graph into the triplestore.
void	clear(URI namedGraphUri) Deletes the resources and statements stored under the given named graph from the triplestore.
void	deleteResources(URI namedGraphUri, org.eclipse.lyo.oslc4j.core.model.IResource... resources) Delete all statements whose subject is one of the resources's URis.
void	deleteResources(URI namedGraphUri, URI... nodeUris) Delete all statements whose subject is one of nodeUris
org.apache.jena.rdf.model.Model	getJenaModelForSubject(URI namedGraphUri, URI subject) Retrieve a Jena model for triples under the given subject from the corresponding named graph.
<T extends org.eclipse.lyo.oslc4j.core.model.IResource> T	getResource(URI namedGraphUri, URI uri, Class<T> clazz) Retrieve a single IResource instance specified by the concrete type, unmarshaled from the RDF graph persisted in the triplestore under the given named graph.
<T extends org.eclipse.lyo.oslc4j.core.model.IResource> List<T>	getResources(URI namedGraphUri, Class<T> clazz) Retrieve the collection of IResource instances specified by the concrete type, unmarshaled from the RDF graph persisted in the triplestore under the given named graph.
<T extends org.eclipse.lyo.oslc4j.core.model.IResource> List<T>	getResources(URI namedGraphUri, Class<T> clazz, int limit, int offset) Alternative to getResources(URI, Class) with paging on the OSLC resource level.
<T extends org.eclipse.lyo.oslc4j.core.model.IResource> List<T>	getResources(URI namedGraphUri, Class<T> clazz, String prefixes, String where, String searchTerms, int limit, int offset) Alternative to getResources(URI, Class) with paging on the OSLC resource level.
org.apache.jena.rdf.model.Model	getResources(URI namedGraph, String prefixes, String where, int limit, int offset) Retrieve a Jena model that satisfies the given where parameter as defined in the OSLC Query language (https://tools.oasis-open.org/version-control/svn/oslc-core/trunk/specs/oslc-query.html) If the namedGraph is null, the query is applied on all namedGraph in the triplestore.
org.apache.jena.rdf.model.Model	getResources(URI namedGraph, String prefixes, String where, String searchTerms, int limit, int offset) Retrieve a Jena model that satisfies the given where parameter as defined in the OSLC Query language (https://tools.oasis-open.org/version-control/svn/oslc-core/trunk/specs/oslc-query.html) If the namedGraph is null, the query is applied on all namedGraph in the triplestore.
void	insertJenaModel(URI namedGraphUri, org.apache.jena.rdf.model.Model model) Insert a jena model into the named graph with corresponding URI.
boolean	insertResources(URI namedGraphUri, Object... resources) Insert Jena models representations of OSLC IResource instances into the named graph.
Set<String>	keySet() Enumerates all named graph URIs within the dataset.
boolean	namedGraphExists(URI namedGraphUri) Checks if the triplestore has the named graph under the corresponding URI.
<T extends org.eclipse.lyo.oslc4j.core.model.IResource> boolean	putResources(URI namedGraphUri, Collection<T> resources) Inserts OSLC IResource instances into the triplestore in the designed namedGraph.
void	removeAll() Remove EVERYTHING from the triplestore.
boolean	resourceExists(URI namedGraphUri, URI resourceUri) Checks if a resource with resourceUri exists under the corresponding named graph.
<T extends org.eclipse.lyo.oslc4j.core.model.IResource> boolean	updateResources(URI namedGraphUri, T... resources) Insert Jena models representations of OSLC IResource instances into the named graph.

Method Detail

insertJenaModel

void insertJenaModel(URI namedGraphUri,
                     org.apache.jena.rdf.model.Model model)

Insert a jena model into the named graph with corresponding URI.

insertResources

boolean insertResources(URI namedGraphUri,
                        Object... resources)
                 throws StoreAccessException

Insert Jena models representations of OSLC IResource instances into the named graph. existing statements already present in the named graph are not overridden, nor removed.

Throws:

StoreAccessException

deleteResources

void deleteResources(URI namedGraphUri,
                     URI... nodeUris)

Delete all statements whose subject is one of nodeUris

deleteResources

void deleteResources(URI namedGraphUri,
                     org.eclipse.lyo.oslc4j.core.model.IResource... resources)

Delete all statements whose subject is one of the resources's URis.

namedGraphExists

boolean namedGraphExists(URI namedGraphUri)

Checks if the triplestore has the named graph under the corresponding URI.

Parameters:

namedGraphUri - URI of a named graph that shall be a valid URI and was used before with the put* methods.

Returns:

does the triplestore contain any resources for a given named graph

resourceExists

boolean resourceExists(URI namedGraphUri,
                       URI resourceUri)

Checks if a resource with resourceUri exists under the corresponding named graph.

getJenaModelForSubject

org.apache.jena.rdf.model.Model getJenaModelForSubject(URI namedGraphUri,
                                                       URI subject)
                                                throws NoSuchElementException

Retrieve a Jena model for triples under the given subject from the corresponding named graph.

Throws:

NoSuchElementException

getResources

<T extends org.eclipse.lyo.oslc4j.core.model.IResource> List<T> getResources(URI namedGraphUri,
                                                                             Class<T> clazz)
                                                                      throws StoreAccessException,
                                                                             ModelUnmarshallingException

Retrieve the collection of IResource instances specified by the concrete type, unmarshaled from the RDF graph persisted in the triplestore under the given named graph. The named graph must represent a URI that was previously given to another method call or a Resource about URI if the resource was saved alone.

Parameters:

clazz - Concrete type of the stored resources. Must be correct (correspond to the marshaled type and be a subclass of IResource), otherwise the instantiation from model will not succeed.

Returns:

A collection of IResource instances, unmarshaled from the RDF graph persisted in the triplestore.

Throws:

StoreAccessException - if there was a problem with the triplestore (or the dataset, more broadly).

ModelUnmarshallingException - if the classes cannot be instantiated or another error occurred when working with Jena model.

getResources

<T extends org.eclipse.lyo.oslc4j.core.model.IResource> List<T> getResources(URI namedGraphUri,
                                                                             Class<T> clazz,
                                                                             int limit,
                                                                             int offset)
                                                                      throws StoreAccessException,
                                                                             ModelUnmarshallingException

Alternative to getResources(URI, Class) with paging on the OSLC resource level.

Parameters:

namedGraphUri - URI of a named graph under which resources were stored

clazz - class of the resources being retrieved

limit - paging limit

offset - paging offset

Returns:

list of OSLC resources, size is less or equal to 'limit'

Throws:

StoreAccessException - if there was a problem with the triplestore (or the dataset, more broadly).

ModelUnmarshallingException - if the classes cannot be instantiated or another error occurred when working with Jena model.

getResources

<T extends org.eclipse.lyo.oslc4j.core.model.IResource> List<T> getResources(URI namedGraphUri,
                                                                             Class<T> clazz,
                                                                             String prefixes,
                                                                             String where,
                                                                             String searchTerms,
                                                                             int limit,
                                                                             int offset)
                                                                      throws StoreAccessException,
                                                                             ModelUnmarshallingException

Alternative to getResources(URI, Class) with paging on the OSLC resource level.

Parameters:

namedGraphUri - URI of a named graph under which resources were stored

clazz - class of the resources being retrieved

prefixes - defines the prefixes for prefixed names that appear in the oslc.where query parameter.

where - filters the member list, keeping only those member resources that satisfy the boolean test on the member resource properties. (See oslc.where at https://tools.oasis-open.org/version-control/browse/wsvn/oslc-core/trunk/specs/oslc-query.html)

searchTerms - score each member resource using a full text search on it text-valued properties. (See oslc.searchTerms at https://tools.oasis-open.org/version-control/browse/wsvn/oslc-core/trunk/specs/oslc-query.html)

limit - paging limit

offset - paging offset

Returns:

list of OSLC resources, size is less or equal to 'limit'

Throws:

StoreAccessException - if there was a problem with the triplestore (or the dataset, more broadly).

ModelUnmarshallingException - if the classes cannot be instantiated or another error occurred when working with Jena model.

getResources

org.apache.jena.rdf.model.Model getResources(URI namedGraph,
                                             String prefixes,
                                             String where,
                                             int limit,
                                             int offset)

Retrieve a Jena model that satisfies the given where parameter as defined in the OSLC Query language (https://tools.oasis-open.org/version-control/svn/oslc-core/trunk/specs/oslc-query.html) If the namedGraph is null, the query is applied on all namedGraph in the triplestore. The method currently only provides support for terms of type Comparisons, where the operator is 'EQUALS', and the operand is either a String or a URI.

Parameters:

namedGraph - namedGraphUri URI of a named graph under which resources were stored

prefixes - defines the prefixes for prefixed names that appear in the oslc.where query parameter.

where - filters the member list, keeping only those member resources that satisfy the boolean test on the member resource properties. (See oslc.where at https://tools.oasis-open.org/version-control/browse/wsvn/oslc-core/trunk/specs/oslc-query.html)

limit - paging limit

offset - paging offset

Returns:

list of resources, size is less or equal to 'limit'

getResources

org.apache.jena.rdf.model.Model getResources(URI namedGraph,
                                             String prefixes,
                                             String where,
                                             String searchTerms,
                                             int limit,
                                             int offset)

Retrieve a Jena model that satisfies the given where parameter as defined in the OSLC Query language (https://tools.oasis-open.org/version-control/svn/oslc-core/trunk/specs/oslc-query.html) If the namedGraph is null, the query is applied on all namedGraph in the triplestore. The method currently only provides support for terms of type Comparisons, where the operator is 'EQUALS', and the operand is either a String or a URI.

Parameters:

namedGraph - namedGraphUri URI of a named graph under which resources were stored

prefixes - defines the prefixes for prefixed names that appear in the oslc.where query parameter.

where - filters the member list, keeping only those member resources that satisfy the boolean test on the member resource properties. (See oslc.where at https://tools.oasis-open.org/version-control/browse/wsvn/oslc-core/trunk/specs/oslc-query.html)

searchTerms - score each member resource using a full text search on it text-valued properties. (See oslc.searchTerms at https://tools.oasis-open.org/version-control/browse/wsvn/oslc-core/trunk/specs/oslc-query.html)

limit - paging limit

offset - paging offset

Returns:

list of resources, size is less or equal to 'limit'

getResource

<T extends org.eclipse.lyo.oslc4j.core.model.IResource> T getResource(URI namedGraphUri,
                                                                      URI uri,
                                                                      Class<T> clazz)
                                                               throws NoSuchElementException,
                                                                      StoreAccessException,
                                                                      ModelUnmarshallingException

Retrieve a single IResource instance specified by the concrete type, unmarshaled from the RDF graph persisted in the triplestore under the given named graph. namedGraph must represent a URI that was previously given to another call.

Parameters:

namedGraphUri - URI of a named graph under which resources were stored

clazz - Java class of the stored resources.

Returns:

An IResource instance, unmarshaled from the RDF graph persisted in the triplestore.

Throws:

NoSuchElementException - if the resource is not present under a given named graph URI or if the named graph itself contains no resources (effectively missing).

StoreAccessException - if there was a problem with the triplestore (or the dataset, more broadly).

ModelUnmarshallingException - if the classes cannot be instantiated or another error occurred when working with Jena model.

updateResources

<T extends org.eclipse.lyo.oslc4j.core.model.IResource> boolean updateResources(URI namedGraphUri,
                                                                                T... resources)
                                                                         throws StoreAccessException

Insert Jena models representations of OSLC IResource instances into the named graph. Any existing model representations of these instances are overridden. other existing statements in the named graph are not overridden, nor removed.

Throws:

StoreAccessException

putResources

<T extends org.eclipse.lyo.oslc4j.core.model.IResource> boolean putResources(URI namedGraphUri,
                                                                             Collection<T> resources)
                                                                      throws StoreAccessException

Inserts OSLC IResource instances into the triplestore in the designed namedGraph.

Any previously stored resource(s) and/or statements will be overwritten.

Parameters:

namedGraphUri - A unique URI that is used as a named graph to which resources are appended

resources - A collection of IResource instances

Returns:

Operation success

Throws:

StoreAccessException - if the operation can't be performed

appendResources

<T extends org.eclipse.lyo.oslc4j.core.model.IResource> boolean appendResources(URI namedGraphUri,
                                                                                Collection<T> resources)
                                                                         throws StoreAccessException

Adds OSLC IResource instances in addition to other instances already present on this named graph into the triplestore. Jena models representing existing and added resource arrays will be combined.

Parameters:

namedGraphUri - A unique URI that is used as a named graph to which resources are appended

resources - A collection of IResource instances

Returns:

Operation success

Throws:

StoreAccessException - if the operation can't be performed

appendResource

default <T extends org.eclipse.lyo.oslc4j.core.model.IResource> boolean appendResource(URI namedGraphUri,
                                                                                       T resource)
                                                                                throws StoreAccessException

Adds an OSLC IResource instance in addition to other instances already present on this named graph into the triplestore. Jena models representing existing and added resource arrays will be combined.

Parameters:

namedGraphUri - A unique URI that is used as a named graph to which resources are appended

resource - An IResource instance with 'about' property set

Returns:

Operation success

Throws:

StoreAccessException - if the operation can't be performed

clear

void clear(URI namedGraphUri)

Deletes the resources and statements stored under the given named graph from the triplestore.

May delete the containing named graph, many triplestores will delete the named graph automatically as well as soon as it doesn't contain any triples.

keySet

Set<String> keySet()

Enumerates all named graph URIs within the dataset.

If the dataset was not manipulated by other means than via this interface, it can be assumed that all URIs in the set are valid keys.

Returns:

The set of all named graph URIs, may contain URIs that are not valid keys if the dataset was manipulated directly.

removeAll

void removeAll()

Remove EVERYTHING from the triplestore.

Since:

0.23.0