Class BaseModule

    • Method Summary

      All Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      void add​(java.util.Set<java.lang.String> rawStmts)
      Like #add(Set, String) with the MemoryProfile.DEFAULT memory profile.
      void add​(java.util.Set<java.lang.String> rawStmts, java.lang.String memProfile)
      Adds a set of statements (assertions) to the ontology from their string representation in the given memory profile.
      This method does nothing if the statements already exist with the same memory profile.
      java.lang.Boolean check​(java.util.Set<java.lang.String> stmts)  
      java.lang.Boolean checkConsistency()
      Checks if the ontology is consistent.
      java.lang.Boolean checkConsistency​(java.util.Set<java.lang.String> rawStmts)
      Checks that a set of statements are consistent with the current model.
      void clear​(java.util.Set<java.lang.String> rawStmts)
      Removes all statements matching any statements or partial statements in the provided set.
      java.util.Set<java.lang.String> find​(java.lang.String varName, java.util.Set<java.lang.String> statements)
      Tries to identify a resource given a set of partially defined statements about this resource.
      This is a simpler form for find(String, Set, Set), without filters.
      java.util.Set<java.lang.String> find​(java.lang.String varName, java.util.Set<java.lang.String> 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.
      First simple example:
      java.util.Map<java.lang.String,​java.util.Set<java.lang.String>> find​(java.util.Set<java.lang.String> variables, java.util.Set<java.lang.String> partialStatements)  
      java.util.Map<java.lang.String,​java.lang.String> getClassesOf​(java.lang.String individual)  
      java.util.Map<java.lang.String,​java.lang.String> getDirectClassesOf​(java.lang.String individual)  
      java.util.Map<java.lang.String,​java.lang.String> getDirectInstancesOf​(java.lang.String type)
      Returns all the direct instances of a given class (ie, the instances whose the given class is the direct parent), as asserted or inferred from the ontology.
      java.util.Map<java.lang.String,​java.lang.String> getDirectSubclassesOf​(java.lang.String type)
      Returns all the direct sub-classes of a given class (ie, the classes whose the given class is the direct parent), as asserted or inferred from the ontology.
      java.util.Map<java.lang.String,​java.lang.String> getDirectSuperclassesOf​(java.lang.String type)
      Returns all the direct super-classes of a given class (ie, the classes whose the given class is a direct descendant), as asserted or inferred from the ontology.
      java.util.Set<java.lang.String> getInfos​(java.lang.String lex_resource)
      Returns the set of asserted and inferred statements whose the given node is part of.
      java.util.Map<java.lang.String,​java.lang.String> getInstancesOf​(java.lang.String type)
      Returns all the instances of a given class, as asserted or inferred from the ontology.
      java.lang.String getLabel​(java.lang.String id)
      Returns the label associated to a concept whose name is 'id'.
      ResourceDescription getResourceDetails​(java.lang.String id)
      Like getResourceDetails(String, String) with language set to default language (as set in the server config file).
      ResourceDescription getResourceDetails​(java.lang.String id, java.lang.String language_code)
      Returns a complete description of a resource identified by id, including its type, label (in a specified language, if available), plus: - superclasses, subclasses and instances for classes - class for instances These data are sent as a JSON serialization.
      java.util.Map<java.lang.String,​java.lang.String> getSubclassesOf​(java.lang.String type)
      Returns all the sub-classes of a given class, as asserted or inferred from the ontology.
      java.util.Map<java.lang.String,​java.lang.String> getSuperclassesOf​(java.lang.String type)
      Returns all the super classes of a given class, as asserted or inferred from the ontology.
      java.util.Set<java.util.List<java.lang.String>> lookup​(java.lang.String id)  
      java.util.Set<java.lang.String> lookup​(java.lang.String id, java.lang.String type)  
      java.util.Set<java.lang.String> query​(java.lang.String key, java.lang.String q)
      void remove​(java.util.Set<java.lang.String> rawStmts)
      Deprecated.
      Use clear(Set) instead.
      boolean safeAdd​(java.util.Set<java.lang.String> rawStmts)  
      boolean safeAdd​(java.util.Set<java.lang.String> rawStmts, java.lang.String memProfile)
      Adds statements with a specific memory model, but only if the statement doesn't cause any inconsistency.
      void update​(java.util.Set<java.lang.String> rawStmts)
      Update the value of a property.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Method Detail

      • add

        @RPCMethod(desc="adds one or several statements (triplets S-P-O) to the robot model associated with a memory profile.")
        public void add​(java.util.Set<java.lang.String> rawStmts,
                        java.lang.String memProfile)
                 throws IllegalStatementException
        Adds a set of statements (assertions) to the ontology from their string representation in the given memory profile.
        This method does nothing if the statements already exist with the same memory profile. If the same statements are added with a different memory profile, the shortest term memory container has priority. To create literals, you must suffix the value with ^^xsd: and the XML schema datatype.

        For instance:
         IOntologyServer myOntology = new OpenRobotsOntology();
         myOntology.add("myIndividual myBooleanPredicate true^^xsd:boolean", MemoryProfile.SHORTTERM);
         
        Examples of statements:
        • "oro:instance1 rdf:type oro:Class1"
        • "oro:instance1 oro:dataProperty1 true^^xsd:boolean"
        • "instance1 dataProperty1 true" (if no namespace is specified, it uses the default one)
        C++ code snippet with liboro library:
         #include "oro.h"
         #include "socket_connector.h"
         
         using namespace std;
         using namespace oro;
         int main(void) {
         
                        SocketConnector connector("localhost", "6969");
                        Ontology* onto = Ontology::createWithConnector(connector);
         
                        onto->add(Statement("gorilla rdf:type Monkey"));
                        onto->add(Statement("gorilla age 12^^xsd:int"));
                        onto->add(Statement("gorilla weight 75.2"));
         
                        // You can as well send a set of statement. The transport will be optimized (all the statements are sent in one time).
                        vector stmts;
         
                        stmts.push_back("gorilla rdf:type Monkey");
                        stmts.push_back("gorilla age 12^^xsd:int");
                        stmts.push_back("gorilla weight 75.2");
         
                        onto->add(stmts);
         
                        return 0;
         }
         
        This method does nothing if the statement already exists with the same memory profile. If the same statement is added with a different memory profile, the shortest term memory container has priority.
        Parameters:
        rawStmts - A set of new statements.
        memProfile - The memory profile associated with this statement.
        Throws:
        IllegalStatementException
        See Also:
        Syntax details regarding the string describing the statement., IOntologyBackend.add(Statement, MemoryProfile, boolean), remove(Set)
      • safeAdd

        @RPCMethod(desc="try to add news statements with a specific memory profile, if they don\'t lead to inconsistencies (return false if at least one stmt wasn\'t added).")
        public boolean safeAdd​(java.util.Set<java.lang.String> rawStmts,
                               java.lang.String memProfile)
                        throws IllegalStatementException
        Adds statements with a specific memory model, but only if the statement doesn't cause any inconsistency. If one statement cause an inconsistency, it won't be added, the return value will be "false", and the process continue with the remaining statements.
        Parameters:
        rawStmts - a set of statements
        memProfile - the memory profile
        Returns:
        false if at least one statement was not added because it would lead to inconsistencies.
        Throws:
        IllegalStatementException
      • clear

        @RPCMethod(desc="removes statements in the given set")
        public void clear​(java.util.Set<java.lang.String> rawStmts)
                   throws IllegalStatementException,
                          OntologyServerException
        Removes all statements matching any statements or partial statements in the provided set. Complete statements (like 'bottle1 hasColor blue') and partial statements (like 'bottle1 hasColor ?val') can be freely mixed. Partial statements can be seen as 'statements with wildcards'. Attention, the implicit relation between each of the partial statements in the set is a OR: the ontology is matched against each of the provided partial statements, and for each of them, all matching statements are removed. If need, the "AND" behaviour can be added. Please drop a mail to openrobots@laas.fr
        Parameters:
        stmts - A set of statements, partial or not, to remove.
        Throws:
        IllegalStatementException - thrown if the string does not represent a valid statement or partial statement.
        OntologyServerException
        See Also:
        PartialStatement, General syntax of RPCs for the oro-server socket connector.
      • checkConsistency

        @RPCMethod(desc="checks that the ontology is semantically consistent")
        public java.lang.Boolean checkConsistency()
        Checks if the ontology is consistent.
        Returns:
        true if the ontology is consistent, false otherwise.
      • checkConsistency

        @RPCMethod(desc="checks that a set of statements are consistent with the current model")
        public java.lang.Boolean checkConsistency​(java.util.Set<java.lang.String> rawStmts)
                                           throws IllegalStatementException
        Checks that a set of statements are consistent with the current model. Statements are not added to the model.
        Returns:
        true if the set of given statement is consistent with the ontology, false otherwise.
        Throws:
        IllegalStatementException
      • find

        @RPCMethod(category="querying",
                   desc="tries to identify a resource given a set of partially defined statements plus restrictions about this resource.")
        public java.util.Set<java.lang.String> find​(java.lang.String varName,
                                                    java.util.Set<java.lang.String> statements,
                                                    java.util.Set<java.lang.String> filters)
                                             throws IllegalStatementException,
                                                    OntologyServerException
        Tries to identify a resource given a set of partially defined statements (plus optional restrictions) about this resource.
        First simple example:
         IOntologyServer myOntology = new OpenRobotsOntology();
        
         Set knowledge = new Set();
         knowledge.add("?mysterious_object ns:isEdibleBy ns:monkey");
         knowledge.add("?mysterious_object ns:color "yellow"^^ns:color");
        
         Set results = myOntology.find("mysterious_object", knowledge);
         for (String res:results)
                        System.out.println(res);
         
        Supposing your ontology defines the right properties and instances, you can expect this example to output something like ns:banana.

        Example with restrictions:
         IOntologyServer myOntology = new OpenRobotsOntology();
        
         Set knowledge = new Set();
         Set filters = new Set();
         
         knowledge.add("?mysterious_object ns:isEdibleBy ns:monkey");
         knowledge.add("?mysterious_object ns:color "yellow"^^ns:color");
         knowledge.add("?mysterious_object ns:size ?size);
        
         filters.add("?size >= 200.0");
         filters.add("?size < 250.0");
        
         Set results = myOntology.find("mysterious_object", knowledge, filters);
         for (String res:results)
                        System.out.println(res);
         
        This example would output all the ns:bananas whose size is comprised between 200 and 250mm (assuming mm is the unit you are using...).
        C++ code snippet using liboro:
         #include "oro.h"
         #include "yarp_connector.h"
         
         using namespace std;
         using namespace oro;
         int main(void) {
                        set<Concept> result;
                        set<string> partial_stmts;
                        set<string> filters;
         
                        YarpConnector connector("myDevice", "oro");
                        Ontology* onto = Ontology::createWithConnector(connector);
         
                        partial_stmts.insert("?mysterious rdf:type oro:Monkey");
                        partial_stmts.insert("?mysterious oro:weight ?value");
         
                        filters.insert("?value >= 50");
         
                        onto->find("mysterious", partial_stmts, filters, result);
         
                        //display the result
                        copy(result.begin(), result.end(), ostream_iterator(cout, "\n"));
         
                        return 0;
         }
         
        Parameters:
        varName - The name of the variable to identify, as used in the statements.
        statements - The partial statement statements defining (more or less) the resource your looking for.
        filters - a vector of string containing the various filters you want to append to your search. The syntax is the SPARQL one (as defined here: http://www.w3.org/TR/rdf-sparql-query/#tests).
        Returns:
        A vector of resources which match the statements. An empty vector is no matching resource is found.
        Throws:
        IllegalStatementException
        OntologyServerException
        See Also:
        Syntax of partial statements, General syntax of RPCs for the oro-server socket connector.
      • find

        @RPCMethod(category="querying",
                   desc="tries to identify a resource given a set of partially defined statements about this resource.")
        public java.util.Set<java.lang.String> find​(java.lang.String varName,
                                                    java.util.Set<java.lang.String> statements)
                                             throws IllegalStatementException,
                                                    OntologyServerException
        Tries to identify a resource given a set of partially defined statements about this resource.
        This is a simpler form for find(String, Set, Set), without filters.
        C++ code snippet using liboro:
         #include "oro.h"
         #include "yarp_connector.h"
         
         using namespace std;
         using namespace oro;
         int main(void) {
                        set<Concept> result;
                        set<string> partial_stmts;
         
                        YarpConnector connector("myDevice", "oro");
                        Ontology* onto = Ontology::createWithConnector(connector);
         
                        partial_stmts.insert("?mysterious oro:eats oro:banana_tree");
                        partial_stmts.insert("?mysterious oro:isFemale true^^xsd:boolean");
         
                        onto->find("mysterious", partial_stmts, result);
         
                        //display the result
                        copy(result.begin(), result.end(), ostream_iterator(cout, "\n"));
         
                        return 0;
         }
         
        Parameters:
        varName - The name of the variable to identify, as used in the statements.
        statements - The partial statement statements defining (more or less) the resource your looking for.
        Returns:
        A vector of resources which match the statements. An empty vector is no matching resource is found.
        Throws:
        IllegalStatementException
        OntologyServerException
        See Also:
        #find(String, Vector, Vector), General syntax of RPCs for the oro-server socket connector.
      • find

        public java.util.Map<java.lang.String,​java.util.Set<java.lang.String>> find​(java.util.Set<java.lang.String> variables,
                                                                                          java.util.Set<java.lang.String> partialStatements)
      • getInfos

        @RPCMethod(category="querying",
                   desc="returns the set of asserted and inferred statements whose the given node is part of. It represents the usages of a resource.")
        public java.util.Set<java.lang.String> getInfos​(java.lang.String lex_resource)
                                                 throws com.hp.hpl.jena.shared.NotFoundException
        Returns the set of asserted and inferred statements whose the given node is part of. It represents the "usages" of a resource.
        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());
         }
         
        This example would print all the types (classes) of the instance ns:individual1.
        Parameters:
        lex_resource - the lexical form of an existing resource.
        Returns:
        a RDF model containing all the statements related the the given resource.
        Throws:
        com.hp.hpl.jena.shared.NotFoundException - thrown if the lex_resource doesn't exist in the ontology.
        See Also:
        General syntax of RPCs for the oro-server socket connector.
      • getSuperclassesOf

        @RPCMethod(category="taxonomy",
                   desc="returns a map of {class name, label} (or {class name, class name without namespace} is no label is available) of all asserted and inferred superclasses of a given class.")
        public java.util.Map<java.lang.String,​java.lang.String> getSuperclassesOf​(java.lang.String type)
                                                                                 throws com.hp.hpl.jena.shared.NotFoundException
        Returns all the super classes of a given class, as asserted or inferred from the ontology.
        Parameters:
        type - A class, in its namespace (if no namespace is specified, the default namespace is assumed, as defined in the configuration file)
        Returns:
        A map of classe ids associated to their labels (in the default language, as defined in the configuration file).
        Throws:
        com.hp.hpl.jena.shared.NotFoundException
        See Also:
        General syntax of RPCs for the oro-server socket connector.
      • getDirectSuperclassesOf

        @RPCMethod(category="taxonomy",
                   desc="returns a map of {class name, label} (or {class name, class name without namespace} is no label is available) of all asserted and inferred direct superclasses of a given class.")
        public java.util.Map<java.lang.String,​java.lang.String> getDirectSuperclassesOf​(java.lang.String type)
                                                                                       throws com.hp.hpl.jena.shared.NotFoundException
        Returns all the direct super-classes of a given class (ie, the classes whose the given class is a direct descendant), as asserted or inferred from the ontology.
        Parameters:
        type - A class, in its namespace (if no namespace is specified, the default namespace is assumed, as defined in the configuration file)
        Returns:
        A map of classe ids associated to their labels (in the default language, as defined in the configuration file).
        Throws:
        com.hp.hpl.jena.shared.NotFoundException
        See Also:
        General syntax of RPCs for the oro-server socket connector.
      • getSubclassesOf

        @RPCMethod(category="taxonomy",
                   desc="returns a map of {class name, label} (or {class name, class name without namespace} is no label is available) of all asserted and inferred subclasses of a given class.")
        public java.util.Map<java.lang.String,​java.lang.String> getSubclassesOf​(java.lang.String type)
                                                                               throws com.hp.hpl.jena.shared.NotFoundException
        Returns all the sub-classes of a given class, as asserted or inferred from the ontology.
        Parameters:
        type - A class, in its namespace (if no namespace is specified, the default namespace is assumed, as defined in the configuration file)
        Returns:
        A map of classe ids associated to their labels (in the default language, as defined in the configuration file).
        Throws:
        com.hp.hpl.jena.shared.NotFoundException
        See Also:
        General syntax of RPCs for the oro-server socket connector.
      • getDirectSubclassesOf

        @RPCMethod(category="taxonomy",
                   desc="returns a map of {class name, label} (or {class name, class name without namespace} is no label is available) of all asserted and inferred direct subclasses of a given class.")
        public java.util.Map<java.lang.String,​java.lang.String> getDirectSubclassesOf​(java.lang.String type)
                                                                                     throws com.hp.hpl.jena.shared.NotFoundException
        Returns all the direct sub-classes of a given class (ie, the classes whose the given class is the direct parent), as asserted or inferred from the ontology.
        Parameters:
        type - A class, in its namespace (if no namespace is specified, the default namespace is assumed, as defined in the configuration file)
        Returns:
        A map of classe ids associated to their labels (in the default language, as defined in the configuration file).
        Throws:
        com.hp.hpl.jena.shared.NotFoundException
        See Also:
        General syntax of RPCs for the oro-server socket connector.
      • getInstancesOf

        @RPCMethod(category="taxonomy",
                   desc="returns a map of {instance name, label} (or {instance name, instance name without namespace} is no label is available) of asserted and inferred instances of a given class.")
        public java.util.Map<java.lang.String,​java.lang.String> getInstancesOf​(java.lang.String type)
                                                                              throws com.hp.hpl.jena.shared.NotFoundException
        Returns all the instances of a given class, as asserted or inferred from the ontology.
        Parameters:
        type - A class, in its namespace (if no namespace is specified, the default namespace is assumed, as defined in the configuration file)
        Returns:
        A map of classe ids associated to their labels (in the default language, as defined in the configuration file).
        Throws:
        com.hp.hpl.jena.shared.NotFoundException
        See Also:
        General syntax of RPCs for the oro-server socket connector.
      • getDirectInstancesOf

        @RPCMethod(category="taxonomy",
                   desc="returns a map of {instance name, label} (or {instance name, instance name without namespace} is no label is available) of asserted and inferred direct instances of a given class.")
        public java.util.Map<java.lang.String,​java.lang.String> getDirectInstancesOf​(java.lang.String type)
                                                                                    throws com.hp.hpl.jena.shared.NotFoundException
        Returns all the direct instances of a given class (ie, the instances whose the given class is the direct parent), as asserted or inferred from the ontology.
        Parameters:
        type - A class, in its namespace (if no namespace is specified, the default namespace is assumed, as defined in the configuration file)
        Returns:
        A map of instances ids (individuals) associated to their labels (in the default language, as defined in the configuration file).
        Throws:
        com.hp.hpl.jena.shared.NotFoundException
        See Also:
        General syntax of RPCs for the oro-server socket connector.
      • getClassesOf

        @RPCMethod(category="taxonomy",
                   desc="returns a map of {class name, label} (or {class name, class name without namespace} is no label is available) of asserted and inferred classes of a given individual.")
        public java.util.Map<java.lang.String,​java.lang.String> getClassesOf​(java.lang.String individual)
                                                                            throws com.hp.hpl.jena.shared.NotFoundException
        Throws:
        com.hp.hpl.jena.shared.NotFoundException
      • getDirectClassesOf

        @RPCMethod(category="taxonomy",
                   desc="returns a map of {class name, label} (or {class name, class name without namespace} is no label is available) of asserted and inferred direct classes of a given individual.")
        public java.util.Map<java.lang.String,​java.lang.String> getDirectClassesOf​(java.lang.String individual)
                                                                                  throws com.hp.hpl.jena.shared.NotFoundException
        Throws:
        com.hp.hpl.jena.shared.NotFoundException
      • getResourceDetails

        @RPCMethod(category="querying",
                   desc="returns a serialized ResourceDescription object that describe all the links of this resource with others resources (sub and superclasses, instances, properties, etc.). The second parameter specify the desired language (following RFC4646).")
        public ResourceDescription getResourceDetails​(java.lang.String id,
                                                      java.lang.String language_code)
                                               throws com.hp.hpl.jena.shared.NotFoundException
        Returns a complete description of a resource identified by id, including its type, label (in a specified language, if available), plus: - superclasses, subclasses and instances for classes - class for instances These data are sent as a JSON serialization. Reference for language code is available in RFC4646.
        Parameters:
        id - the concept whose description is queried
        language_code - a standard language code.
        Returns:
        a ResourceDescription object, serializable as a JSON string
        Throws:
        com.hp.hpl.jena.shared.NotFoundException
        See Also:
        ResourceDescription
      • getResourceDetails

        @RPCMethod(category="querying",
                   desc="returns a serialized ResourceDescription object that describe all the links of this resource with others resources (sub and superclasses, instances, properties, etc.).")
        public ResourceDescription getResourceDetails​(java.lang.String id)
                                               throws com.hp.hpl.jena.shared.NotFoundException
        Like getResourceDetails(String, String) with language set to default language (as set in the server config file).
        Parameters:
        id - the concept whose description is queried
        Returns:
        a ResourceDescription object, serializable as a JSON string
        Throws:
        com.hp.hpl.jena.shared.NotFoundException
        See Also:
        getResourceDetails(String, String)
      • lookup

        @RPCMethod(desc="try to identify a concept from its id or label, and return it, along with its type (class, instance, object_property, datatype_property).")
        public java.util.Set<java.util.List<java.lang.String>> lookup​(java.lang.String id)
      • lookup

        @RPCMethod(desc="try to identify a concept from its id or label and its type (class, instance, object_property, datatype_property).")
        public java.util.Set<java.lang.String> lookup​(java.lang.String id,
                                                      java.lang.String type)
      • getLabel

        @RPCMethod(desc="return the label of a concept, if available.")
        public java.lang.String getLabel​(java.lang.String id)
                                  throws com.hp.hpl.jena.shared.NotFoundException
        Returns the label associated to a concept whose name is 'id'. The label language can be specified in the configuration file (option 'language') and default to English ('en'). If the concept has no label, the concept id is returned.
        Parameters:
        the - id to look for.
        Returns:
        One of the labels associated to this id or the id itself if no label has been defined.
        Throws:
        OntologyServerException
        com.hp.hpl.jena.shared.NotFoundException