Package org.eclipse.lyo.store

Interface Store

All Known Implementing Classes:
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 Details

    • insertJenaModel

      void insertJenaModel(URI namedGraphUri, 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, 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

      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 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 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 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

      <T extends IResource> List<T> getResources(URI namedGraphUri, Class<T> clazz, String prefixes, String where, String searchTerms, int limit, int offset, List<String> additionalDistinctVars, org.apache.jena.arq.querybuilder.SelectBuilder additionalQueryFilter) throws StoreAccessException, ModelUnmarshallingException
      Alternative to getResources(URI, Class, String, String, String, int, int) with additional parameters for inlined resources. These parameters extend the default query from: 
       DESCRIBE ?s
 WHERE {
   ...
   SELECT distinct ?s
     WHERE {
       ?s ?p ?o .
       ?s rdf:type  <http://...> .
       ...
     }
 }
      to: 
       DESCRIBE ?s ?a ?b
 WHERE {
 ...
   SELECT distinct ?s ?a ?b
   WHERE {
     ?s  ?p        ?o .
     ?s rdf:type  <http://...> .
     ?s <http://...#prp1>  ?a .
     ?a <http://prp2> ?b
   }
 }
      hence allowing ?a and ?b to be described, as well as ?s. Corresponding parameters to achieve this: 
        List additionalDistinctVars = new ArrayList();
  additionalDistinctVars.add("a");
  additionalDistinctVars.add("b");

  SelectBuilder additionalQueryFilter = new SelectBuilder();
  additionalQueryFilter
  .addWhere( "?s", new ResourceImpl("http://...#" + "prp1"), "?a")
  .addWhere( "?a", new ResourceImpl(http://...# + "prp2"), "?b");
      Parameters:
      additionalDistinctVars -
      additionalQueryFilter -
      Throws:
      StoreAccessException
      ModelUnmarshallingException

    • getResources

      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

      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:
      a Jena Model with the less than or equal to limit resources.

    • getResources

      Model getResources(URI namedGraph, String prefixes, String where, String searchTerms, int limit, int offset, List<String> additionalDistinctVars, org.apache.jena.arq.querybuilder.SelectBuilder additionalQueryFilter)
      Alternative to getResources(URI, String, String, String, int, int) with additional parameters for inlined resources. See getResources(URI, Class, String, String, String, int, int, List, SelectBuilder) for an explanation of these additional parameters.

    • getResource

      <T extends 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 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 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 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 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

    • close

      void close()
      Close connection
      Since:
      4.1.0