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 Detail

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

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

      • 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