Interface IOntologyBackend

  • All Superinterfaces:
    IServiceProvider
    All Known Implementing Classes:
    OpenRobotsOntology

    public interface IOntologyBackend
    extends IServiceProvider
    This interface describes the abstract behaviour of an ontology backend. It presents the list of operation the "knowledge store" should provide to be used with the ontology server.
    • Method Summary

      All Methods Instance Methods Abstract Methods Deprecated Methods 
      Modifier and Type Method Description
      boolean add​(com.hp.hpl.jena.rdf.model.Statement statement, MemoryProfile memProfile, boolean safe)
      Deprecated.
      boolean add​(java.util.Set<com.hp.hpl.jena.rdf.model.Statement> statements, MemoryProfile memProfile, boolean safe)
      Adds a set of new statements (assertion) to the ontology.
      boolean check​(com.hp.hpl.jena.rdf.model.Statement statement)
      Checks if a statement is asserted or can be inferred from the ontology.
      boolean check​(PartialStatement statement)
      Checks if a pattern represented as a partial statement matches at least one asserted of inferred statement.
      For instance: A pattern like [?object rdf:type Bottle] would match all instances of the class Bottle. [anAgent sees ?something] would match all objects seen by instance "anAgent".
      boolean checkConsistency()
      Performs a consistency validation against the ontology.
      boolean checkConsistency​(java.util.Set<com.hp.hpl.jena.rdf.model.Statement> statements)
      Checks a set of statements (or partial statements) are not inconsistent with the current model.
      void clear​(PartialStatement partialStmt)
      Remove all statements matching the partial statement.
      void clearEvent​(IWatcher watcher)
      Removes one specific event watcher.
      void clearEvents()
      Removes all registered event watchers for this model.
      void close()
      Closes the model
      PartialStatement createPartialStatement​(java.lang.String statement)
      This static method acts as a PartialStatement factory.
      com.hp.hpl.jena.ontology.OntProperty createProperty​(java.lang.String lex_property)
      Helper to create a property attached at the current OpenRobotOntology by mapping the method to the underlying ontology model.
      This is a shortcut for OpenRobotOntology.getModel().createProperty(Namespaces.format(lex_property))
      com.hp.hpl.jena.ontology.OntResource createResource​(java.lang.String lex_resource)
      Helper to create a resource attached at the current OpenRobotOntology by mapping the method to the underlying ontology model.
      This is a shortcut for OpenRobotOntology.getModel().createResource(Namespaces.format(lex_resource)).
      com.hp.hpl.jena.rdf.model.Statement createStatement​(java.lang.String statement)
      This static method acts as a Statement factory.
      java.util.Set<com.hp.hpl.jena.rdf.model.RDFNode> find​(java.lang.String varName, java.util.Set<PartialStatement> statements, java.util.Set<java.lang.String> filters)
      Tries to identify a resource given a set of partially defined statements (plus optional restrictions) about this resource.
      java.util.Set<com.hp.hpl.jena.ontology.OntClass> getClassesOf​(com.hp.hpl.jena.ontology.OntResource individual, boolean onlyDirect)  
      java.util.Set<com.hp.hpl.jena.ontology.OntResource> getInstancesOf​(com.hp.hpl.jena.ontology.OntClass type, boolean onlyDirect)  
      com.hp.hpl.jena.ontology.OntModel getModel()
      Returns the underlying Jena ontology model.
      com.hp.hpl.jena.ontology.OntResource getResource​(java.lang.String lex_resource)
      Try to retrieve a resource from the ontology, based on its lexical form.
      java.util.Set<com.hp.hpl.jena.ontology.OntClass> getSubclassesOf​(com.hp.hpl.jena.ontology.OntClass type, boolean onlyDirect)  
      com.hp.hpl.jena.rdf.model.Model getSubmodel​(com.hp.hpl.jena.rdf.model.Resource node)
      Returns the set of inferred and asserted statement involving a resource as a Jena Model..
      java.util.Set<com.hp.hpl.jena.ontology.OntClass> getSuperclassesOf​(com.hp.hpl.jena.ontology.OntClass type, boolean onlyDirect)  
      java.util.Set<IWatcher.EventType> getSupportedEvents()
      Return the list of event types implemented (hence usable) by this backend.
      java.util.Set<java.util.List<java.lang.String>> lookup​(java.lang.String id)
      Returns the set of all [id, type, label] (with type one of INSTANCE, CLASS, OBJECT_PROPERTY, DATATYPE_PROPERTY, UNDEFINED) of concepts whose labels or id match the given parameter.
      java.util.Set<java.lang.String> lookup​(java.lang.String id, ResourceType type)
      Returns the set of all id of concepts whose labels or ids match the given parameter and of the given type.
      java.util.Set<com.hp.hpl.jena.rdf.model.RDFNode> query​(java.lang.String key, java.lang.String query)
      Performs a SPARQL query on the OpenRobots ontology.
      For instance:
      void registerEvent​(IWatcher watcher)
      Allows to register several events providers (typically, one by underlying middleware) which in turn provide access to watchers.
      void remove​(com.hp.hpl.jena.rdf.model.Statement stmt)
      Deprecated.
      void remove​(java.util.Set<com.hp.hpl.jena.rdf.model.Statement> stmts)
      Removes a set of statements from the ontology.
      void save​(java.lang.String path)
      Saves the in-memory ontology model to a RDF/XML file.
      long size()
      Returns the number of statements in the model.
      void step()
      'Step' the model.
      void update​(java.util.Set<com.hp.hpl.jena.rdf.model.Statement> stmts)
      Update the value of a property.
    • Method Detail

      • createProperty

        com.hp.hpl.jena.ontology.OntProperty createProperty​(java.lang.String lex_property)
        Helper to create a property attached at the current OpenRobotOntology by mapping the method to the underlying ontology model.
        This is a shortcut for OpenRobotOntology.getModel().createProperty(Namespaces.format(lex_property))
        Parameters:
        lex_property - the lexical form of the property (eg "rdf:type").
        Returns:
        the corresponding Jena property.
        See Also:
        com.hp.hpl.jena.rdf.model.OntModel#createOntProperty(String)
      • createResource

        com.hp.hpl.jena.ontology.OntResource createResource​(java.lang.String lex_resource)
        Helper to create a resource attached at the current OpenRobotOntology by mapping the method to the underlying ontology model.
        This is a shortcut for OpenRobotOntology.getModel().createResource(Namespaces.format(lex_resource)). If a resource with the same lexical form already exist, it is reused. The getResource(String) method can be used to retrieve resource without creating a new one if it doesn't exist.
        Parameters:
        lex_resource - the lexical form of the resource.
        Returns:
        the corresponding Jena resource.
        See Also:
        getResource(String), com.hp.hpl.jena.rdf.model.OntModel#createOntResource(String)
      • getResource

        com.hp.hpl.jena.ontology.OntResource getResource​(java.lang.String lex_resource)
                                                  throws com.hp.hpl.jena.shared.NotFoundException
        Try to retrieve a resource from the ontology, based on its lexical form.
        Parameters:
        lex_resource - The URI of a resource in the ontology.
        Returns:
        a RDF model containing all the statements related the the given resource.
        Throws:
        com.hp.hpl.jena.shared.NotFoundException - thrown if the resource doesn't exist in the ontology.
        See Also:
        #getSubmodel(OntResource), createResource(String)
      • getSubmodel

        com.hp.hpl.jena.rdf.model.Model getSubmodel​(com.hp.hpl.jena.rdf.model.Resource node)
                                             throws com.hp.hpl.jena.shared.NotFoundException
        Returns the set of inferred and asserted statement involving a resource as a Jena Model..
        Parameters:
        resource - A Jena resource.
        Returns:
        a RDF model containing all the statements related the the given resource.
        Throws:
        com.hp.hpl.jena.shared.NotFoundException - thrown if the resource doesn't exist in the ontology.
        See Also:
        #getSubmodel(String)
      • createStatement

        com.hp.hpl.jena.rdf.model.Statement createStatement​(java.lang.String statement)
                                                     throws IllegalStatementException
        This static method acts as a Statement factory. It does some pre-processing to convert a string to a valid statement relative to the given ontology.
        Formatting follows roughly the SPARQL syntax :
        • Literals follows the "value"^^type rule for the general case. Simple or double quotes can be used. Cf examples below.
        • Resources can be either isolated ("individual1"). It will then use the default namespace as defined in the configuration file.
        • Or prefixed with the namespace prefix ("rdf:type"),
        • Or complete URIs ("<http://www.w3.org/1999/02/22-rdf-syntax-ns#type>"). In this case, the URI must be enclosed between < and >.

        Literals examples:
        • The boolean true can be represented either as "true"^^xsd:boolean or as true,
        • The integer 123 can be represented either as 123^^xsd:int or as 123. "123"^^xsd:int is also acceptable.
        • The double 1.23 can be represented either as 1.23^^xsd:double or as 1.23. "1.23"^^xsd:double is also acceptable.
        • User-defined dataypes can be represented with "xyz"^^<http://example.org/ns/userDatatype> or "xyz"^^oro:userDatatype.
        The unit test laas.openrobots.ontology.tests.OpenRobotsOntologyTest#testLiterals() extensively tests the various literal representation possibilities.
        Parameters:
        statement - a string containing a statement. For example, "oro:individual rdf:type oro:Class1" or "oro:individual <> oro:Class1"
        Returns:
        a new Jena statement
        Throws:
        IllegalStatementException
        See Also:
        Partial statements for partially unbound statements (like "?subject rdf:type oro:Class1")., #add(String), List of known namespace prefixes.
      • createPartialStatement

        PartialStatement createPartialStatement​(java.lang.String statement)
                                         throws IllegalStatementException
        This static method acts as a PartialStatement factory. It does some pre-processing to convert a string to a valid statement relative to the given ontology.
        See createStatement(java.lang.String) for syntax details regarding literals.
        To be valid, a partial statement must have at least one variable, prepended with a "?".
        Parameters:
        statement - a string representing the partial statement. For instance: "?mysterious oro:objProperty2 oro:individual2"
        Returns:
        a new partially defined statement
        Throws:
        IllegalStatementException
        See Also:
        createStatement(String), #find(String, Vector)
      • size

        long size()
        Returns the number of statements in the model.
        Returns:
        the number of statements in the model.
      • getModel

        com.hp.hpl.jena.ontology.OntModel getModel()
        Returns the underlying Jena ontology model.
        Returns:
        the current underlying Jena ontology model.
      • add

        boolean add​(java.util.Set<com.hp.hpl.jena.rdf.model.Statement> statements,
                    MemoryProfile memProfile,
                    boolean safe)
             throws IllegalStatementException
        Adds a set of new statements (assertion) to the ontology. If one of the statements already exists, it won't be inserted.
        A memory profile is associated to all the statements: statements associated to MemoryProfile.LONGTERM or MemoryProfile.DEFAULT are stored and never removed from the ontology while other memory profiles allow the ontology to "forget" about certain facts after a given amount of time.
        Parameters:
        statements - A set of statements to be inserted in the model.
        memProfile - The memory profile associated to this statement.
        safe - If true, the statement is added only if it does not
        Returns:
        True if all the statements have been actually added to the model (actually useful only in conjunction with the safe parameter enabled).
        Throws:
        IllegalStatementException - Currently only thrown if a concept is asserted to be both an instance and a class.
      • check

        boolean check​(com.hp.hpl.jena.rdf.model.Statement statement)
        Checks if a statement is asserted or can be inferred from the ontology. The check is done in an open world (everything is true except if it's explicitely false). For instance, if only the following statement is asserted:
         bottle hasColor green
         
        check("bottle hasColor orange") would return true. If the two following statements are added to the ontology:
         green owl:isDifferentFrom orange
         hasColor rdf:type owl:functionalProperty
         
        then check("bottle hasColor orange") would return false.
        Parameters:
        statement - the statement to be evaluated
        Returns:
        true if the statement is asserted in or can be inferred from the ontology
      • check

        boolean check​(PartialStatement statement)
        Checks if a pattern represented as a partial statement matches at least one asserted of inferred statement.
        For instance:
        • A pattern like [?object rdf:type Bottle] would match all instances of the class Bottle.
        • [anAgent sees ?something] would match all objects seen by instance "anAgent".
        Parameters:
        statement - the partial pattern to be evaluated
        Returns:
        true if the pattern matches at least one asserted or inferred statement of the ontology.
        See Also:
        #find(String, Vector)
      • checkConsistency

        boolean checkConsistency()
        Performs a consistency validation against the ontology. Returns false if the check fails.
      • query

        java.util.Set<com.hp.hpl.jena.rdf.model.RDFNode> query​(java.lang.String key,
                                                               java.lang.String query)
                                                        throws InvalidQueryException
        Performs a SPARQL query on the OpenRobots ontology.
        For instance:
                IOntologyServer myOntology = new OpenRobotsOntology();
                ResultSet result =      myOntology.query(
                                                        "PREFIX rdf:  \n" +
                                                        "PREFIX owl:  \n" +
                                                        "SELECT ?instances \n" +
                                                        "WHERE { \n" +
                                                        "?instances rdf:type owl:Thing}\n");
        
         for ( ; result.hasNext() ; )
                {
                        System.out.println(result.nextSolution().toString());
                }
         
        This example would print all the instances existing in the ontology.
        Attention! Unlike other methods which take string representation of statements or resource, namespaces or namespace prefixes CAN NOT be omitted: SELECT ?instance WHERE {?instance eats bananas} won't match the same things as SELECT ?instance WHERE {?instance oro:eats oro:bananas} even if oro is the prefix of the default namespace.
        Parameters:
        query - A well-formed SPARQL query to perform on the ontology. PREFIX statements may be omitted if they are the standard ones (namely, owl, rdf, rdfs) or the LAAS OpenRobots ontology (oro) one.
        query -
        Returns:
        The result of the query as a set of RDFNode (either resources or literals).
        Throws:
        com.hp.hpl.jena.query.QueryParseException - thrown if the argument is not a valid SPARQL query.
        InvalidQueryException
        See Also:
        #queryAsXML(String)
      • find

        java.util.Set<com.hp.hpl.jena.rdf.model.RDFNode> find​(java.lang.String varName,
                                                              java.util.Set<PartialStatement> statements,
                                                              java.util.Set<java.lang.String> filters)
                                                       throws InvalidQueryException
        Tries to identify a resource given a set of partially defined statements (plus optional restrictions) about this resource.
        Parameters:
        varName - The name of the variable to bind, as used in the partial statements.
        statements - A set of partial statements that globaly define a search pattern
        filters - a vector of string containing the various filters to be appended to the search. The syntax is the SPARQL one (as defined here: http://www.w3.org/TR/rdf-sparql-query/#tests).
        Returns:
        a set of resources or literal (RDFNode) that match the statements.
        Throws:
        InvalidQueryException
        See Also:
        Examples of use
      • getSuperclassesOf

        java.util.Set<com.hp.hpl.jena.ontology.OntClass> getSuperclassesOf​(com.hp.hpl.jena.ontology.OntClass type,
                                                                           boolean onlyDirect)
                                                                    throws com.hp.hpl.jena.shared.NotFoundException
        Throws:
        com.hp.hpl.jena.shared.NotFoundException
      • getSubclassesOf

        java.util.Set<com.hp.hpl.jena.ontology.OntClass> getSubclassesOf​(com.hp.hpl.jena.ontology.OntClass type,
                                                                         boolean onlyDirect)
                                                                  throws com.hp.hpl.jena.shared.NotFoundException
        Throws:
        com.hp.hpl.jena.shared.NotFoundException
      • getInstancesOf

        java.util.Set<com.hp.hpl.jena.ontology.OntResource> getInstancesOf​(com.hp.hpl.jena.ontology.OntClass type,
                                                                           boolean onlyDirect)
                                                                    throws com.hp.hpl.jena.shared.NotFoundException
        Throws:
        com.hp.hpl.jena.shared.NotFoundException
      • getClassesOf

        java.util.Set<com.hp.hpl.jena.ontology.OntClass> getClassesOf​(com.hp.hpl.jena.ontology.OntResource individual,
                                                                      boolean onlyDirect)
                                                               throws com.hp.hpl.jena.shared.NotFoundException
        Throws:
        com.hp.hpl.jena.shared.NotFoundException
      • lookup

        java.util.Set<java.util.List<java.lang.String>> lookup​(java.lang.String id)
        Returns the set of all [id, type, label] (with type one of INSTANCE, CLASS, OBJECT_PROPERTY, DATATYPE_PROPERTY, UNDEFINED) of concepts whose labels or id match the given parameter.
        Parameters:
        label - the label (in any language) or id to look for.
        Returns:
        A list made of the id of the concept whose label matches the parameter followed by its type, or an empty set if nothing was found.
        See Also:
        ResourceType, lookup(String, ResourceType), General syntax of RPCs for the oro-server socket connector.
      • lookup

        java.util.Set<java.lang.String> lookup​(java.lang.String id,
                                               ResourceType type)
        Returns the set of all id of concepts whose labels or ids match the given parameter and of the given type.
        Parameters:
        label - the label (in any language) or id to look for.
        type - the type of the resource that is looked for.
        Returns:
        A set of ids whose label matches the parameter or an empty set.
        See Also:
        ResourceType, General syntax of RPCs for the oro-server socket connector.
      • clear

        void clear​(PartialStatement partialStmt)
            throws OntologyServerException
        Remove all statements matching the partial statement. Usage example:
         IOntologyServer myOntology = new OpenRobotsOntology();
         Model results = myOntology.getInfos("ns:individual1");
         
         NodeIterator types = results.listObjectsOfProperty(myOntology.createProperty("rdf:type"));
        
         for ( ; types.hasNext() ; )
         {
                System.out.println(types.nextNode().toString());
         }
         
        Parameters:
        partialStmt - The partial statement representing a "mask" of statements to delete.
        Throws:
        OntologyServerException
      • remove

        @Deprecated
        void remove​(com.hp.hpl.jena.rdf.model.Statement stmt)
             throws OntologyServerException
        Deprecated.
        Removes a given statement from the ontology. Does nothing if the statement doesn't exist.
        Parameters:
        stmt - The statement to remove from the ontology.
        Throws:
        OntologyServerException
        See Also:
        #add(Statement)
      • remove

        void remove​(java.util.Set<com.hp.hpl.jena.rdf.model.Statement> stmts)
             throws OntologyServerException
        Removes a set of statements from the ontology. It ignores statements that do not exist.
        Parameters:
        stmts - The statements to remove from the ontology.
        Throws:
        OntologyServerException
        See Also:
        #add(Set)
      • registerEvent

        void registerEvent​(IWatcher watcher)
                    throws EventRegistrationException
        Allows to register several events providers (typically, one by underlying middleware) which in turn provide access to watchers. Watchers expose a watch expression which is a SPARQL ASK query. Every time a change is made on the ontology, the ontology backend which implements this interface is expected to execute this query against the model and notify the watchers (through IWatcher#notifySubscriber()) if the result is positive.
        Parameters:
        watcherProviders - A set of event providers.
        Throws:
        EventRegistrationException
        See Also:
        General syntax of RPCs for the oro-server socket connector.
      • clearEvents

        void clearEvents()
        Removes all registered event watchers for this model.
      • getSupportedEvents

        java.util.Set<IWatcher.EventType> getSupportedEvents()
        Return the list of event types implemented (hence usable) by this backend.
        Returns:
        The list of event type supported by the backend
      • step

        void step()
        'Step' the model. At each server main loop iteration, the 'step' method is called for each model. The model can do here its own internal homeworks.
      • close

        void close()
        Closes the model