Class OpenRobotsOntology
java.lang.Object
laas.openrobots.ontology.backends.OpenRobotsOntology
- All Implemented Interfaces:
IOntologyBackend
,IServiceProvider
The OpenRobotsOntology class is the main storage backend for oro-server.
It maps useful methods for knowledge access in a robotic context to a Jena-baked
Amongst other feature, it offers an easy way to
the ontology with standard SPARQL requests, it can try to
resources matching a set of
statements or check the consistency of the
knowledge storage.
Examples covering the various aspects of the API can be found in the Unit Tests.
It maps useful methods for knowledge access in a robotic context to a Jena-baked
ontology
.Amongst other feature, it offers an easy way to
invalid reference
query
invalid reference
find
Examples covering the various aspects of the API can be found in the Unit Tests.
-
Constructor Summary
ConstructorsConstructorDescriptionConstructors *OpenRobotsOntology
(com.hp.hpl.jena.ontology.OntModel onto) Constructor which takes a Jena OntModel as parameter.OpenRobotsOntology
(com.hp.hpl.jena.ontology.OntModel onto, Properties parameters) OpenRobotsOntology
(Properties parameters) Constructor which takes a config file as parameter.
The constructor first opens the ontology, then loads it into memory and eventually bounds it to Jena internal reasoner. -
Method Summary
Modifier and TypeMethodDescriptionboolean
add
(com.hp.hpl.jena.rdf.model.Statement statement, MemoryProfile memProfile, boolean safe) Adds a new statement (assertion) to the ontology.boolean
add
(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 classBottle
.[anAgent sees ?something]
would match all objects seen by instance "anAgent
".boolean
Performs a consistency validation against the ontology.boolean
checkConsistency
(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
classify()
Classify the underlying model.void
clear
(PartialStatement partialStmt) Remove all statements matching the partial statement.void
clearEvent
(IWatcher watcher) Removes one specific event watcher.void
Removes all registered event watchers for this model.void
close()
Closes the modelcreatePartialStatement
(String statement) This static method acts as a PartialStatement factory.com.hp.hpl.jena.ontology.OntProperty
createProperty
(String lex_property) Accessors and helpers *com.hp.hpl.jena.ontology.OntResource
createResource
(String lex_resource) Helper to create ainvalid reference
resource
This is a shortcut forOpenRobotOntology.getModel().createResource(Namespaces.format(lex_resource))
.com.hp.hpl.jena.rdf.model.Statement
createStatement
(String statement) This static method acts as a Statement factory.Set
<com.hp.hpl.jena.rdf.model.RDFNode> Tries to identify a resource given a set of partially defined statements (plus optional restrictions) about this resource.Set
<com.hp.hpl.jena.ontology.OntClass> getClassesOf
(com.hp.hpl.jena.ontology.OntResource resource, boolean onlyDirect) 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.Returns the current set of parameters.com.hp.hpl.jena.ontology.OntResource
getResource
(String lex_resource) Try to retrieve a resource from the ontology, based on its lexical form.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..Set
<com.hp.hpl.jena.ontology.OntClass> getSuperclassesOf
(com.hp.hpl.jena.ontology.OntClass type, boolean onlyDirect) Return the list of event types implemented (hence usable) by this backend.void
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.lookup
(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.protected void
onModelChange
(String rsName) This protected method is called every time the ontology model changes (ie upon addition or removal of statements in the ontology).Set
<com.hp.hpl.jena.rdf.model.RDFNode> 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
Removes a set of statements from the ontology.void
save()
void
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 the value of a property.
-
Constructor Details
-
OpenRobotsOntology
public OpenRobotsOntology()Constructors * -
OpenRobotsOntology
Constructor which takes a config file as parameter.
The constructor first opens the ontology, then loads it into memory and eventually bounds it to Jena internal reasoner. Thus, the instanciation of OpenRobotsOntology may take some time (several seconds, depending on the size on the ontology).
Available options:
- verbose = [true|false]: set it to true to get more infos from the engine.
- ontology = PATH: the path to the OWL (or RDF) ontology to be loaded.
- default_namespace = NAMESPACE: set the default namespace. Don't forget the trailing #!
- short_namespaces = [true|false] (default: true): if true, the ontology engine will return resource with prefix instead of full URI, or nothing if the resource is in the default namespace.
OroServer
. Have a look as well at the config file itself for more details.- Parameters:
parameters
- The set of parameters, read from the server configuration file.
-
OpenRobotsOntology
public OpenRobotsOntology(com.hp.hpl.jena.ontology.OntModel onto) Constructor which takes a Jena OntModel as parameter.- Parameters:
onto
- An already built ontology model. The OpenRobotsOntology will wrap it.
-
OpenRobotsOntology
-
-
Method Details
-
createProperty
Accessors and helpers *- Specified by:
createProperty
in interfaceIOntologyBackend
- Parameters:
lex_property
- the lexical form of the property (eg"rdf:type"
).- Returns:
- the corresponding Jena property.
- See Also:
-
createResource
Description copied from interface:IOntologyBackend
Helper to create ainvalid reference
resource
This is a shortcut forOpenRobotOntology.getModel().createResource(Namespaces.format(lex_resource))
. If a resource with the same lexical form already exist, it is reused. TheIOntologyBackend.getResource(String)
method can be used to retrieve resource without creating a new one if it doesn't exist.- Specified by:
createResource
in interfaceIOntologyBackend
- Parameters:
lex_resource
- the lexical form of the resource.- Returns:
- the corresponding Jena resource.
- See Also:
-
createStatement
public com.hp.hpl.jena.rdf.model.Statement createStatement(String statement) throws IllegalStatementException Description copied from interface:IOntologyBackend
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 theinvalid reference
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 astrue
, - The integer
123
can be represented either as123^^xsd:int
or as123
."123"^^xsd:int
is also acceptable. - The double
1.23
can be represented either as1.23^^xsd:double
or as1.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
.
invalid reference
laas.openrobots.ontology.tests.OpenRobotsOntologyTest#testLiterals()
- Specified by:
createStatement
in interfaceIOntologyBackend
- 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:
- Literals follows the
-
createPartialStatement
Description copied from interface:IOntologyBackend
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.
SeeIOntologyBackend.createStatement(java.lang.String)
for syntax details regarding literals.
To be valid, a partial statement must have at least one variable, prepended with a "?".- Specified by:
createPartialStatement
in interfaceIOntologyBackend
- 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:
-
getModel
public com.hp.hpl.jena.ontology.OntModel getModel()Description copied from interface:IOntologyBackend
Returns the underlying Jena ontology model.- Specified by:
getModel
in interfaceIOntologyBackend
- Returns:
- the current underlying Jena ontology model.
-
classify
public void classify()Classify the underlying model. Note that this method modifies the underlying model. -
add
public boolean add(com.hp.hpl.jena.rdf.model.Statement statement, MemoryProfile memProfile, boolean safe) throws IllegalStatementException Description copied from interface:IOntologyBackend
Adds a new statement (assertion) to the ontology.- Specified by:
add
in interfaceIOntologyBackend
- Throws:
IllegalStatementException
- See Also:
-
add
public boolean add(Set<com.hp.hpl.jena.rdf.model.Statement> statements, MemoryProfile memProfile, boolean safe) throws IllegalStatementException Description copied from interface:IOntologyBackend
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 toinvalid reference
MemoryProfile.LONGTERM
invalid reference
MemoryProfile.DEFAULT
- Specified by:
add
in interfaceIOntologyBackend
- 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
public boolean check(com.hp.hpl.jena.rdf.model.Statement statement) Description copied from interface:IOntologyBackend
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 returntrue
. If the two following statements are added to the ontology:green owl:isDifferentFrom orange hasColor rdf:type owl:functionalProperty
thencheck("bottle hasColor orange")
would returnfalse
.- Specified by:
check
in interfaceIOntologyBackend
- Parameters:
statement
- the statement to be evaluated- Returns:
- true if the statement is asserted in or can be inferred from the ontology
-
check
Description copied from interface:IOntologyBackend
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 classBottle
. [anAgent sees ?something]
would match all objects seen by instance "anAgent
".
- Specified by:
check
in interfaceIOntologyBackend
- 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:
- A pattern like
-
checkConsistency
public boolean checkConsistency()Description copied from interface:IOntologyBackend
Performs a consistency validation against the ontology. Returns false if the check fails.- Specified by:
checkConsistency
in interfaceIOntologyBackend
-
checkConsistency
Description copied from interface:IOntologyBackend
Checks a set of statements (or partial statements) are not inconsistent with the current model. The method temporarily adds the given statements to the model, checks the whole model consistency, remove the statements and return the result of the consistency check (true or false).- Specified by:
checkConsistency
in interfaceIOntologyBackend
- See Also:
-
query
public Set<com.hp.hpl.jena.rdf.model.RDFNode> query(String key, String query) throws InvalidQueryException Description copied from interface:IOntologyBackend
Performs a SPARQL query on the OpenRobots ontology.
For instance:IOntologyServer myOntology = new OpenRobotsOntology(); ResultSet result = myOntology.query( "PREFIX rdf: invalid input: '<'http://www.w3.org/1999/02/22-rdf-syntax-ns#> \n" + "PREFIX owl: invalid input: '<'http://www.w3.org/2002/07/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 asSELECT ?instance WHERE {?instance oro:eats oro:bananas}
even iforo
is the prefix of the default namespace.- Specified by:
query
in interfaceIOntologyBackend
- 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.- Returns:
- The result of the query as a set of RDFNode (either resources or literals).
- Throws:
InvalidQueryException
- See Also:
-
find
public Set<com.hp.hpl.jena.rdf.model.RDFNode> find(String varName, Set<PartialStatement> statements, Set<String> filters) throws InvalidQueryException Description copied from interface:IOntologyBackend
Tries to identify a resource given a set of partially defined statements (plus optional restrictions) about this resource.- Specified by:
find
in interfaceIOntologyBackend
- 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 patternfilters
- 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:
-
getResource
public com.hp.hpl.jena.ontology.OntResource getResource(String lex_resource) throws com.hp.hpl.jena.shared.NotFoundException Description copied from interface:IOntologyBackend
Try to retrieve a resource from the ontology, based on its lexical form.- Specified by:
getResource
in interfaceIOntologyBackend
- 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
public com.hp.hpl.jena.rdf.model.Model getSubmodel(com.hp.hpl.jena.rdf.model.Resource node) throws com.hp.hpl.jena.shared.NotFoundException Description copied from interface:IOntologyBackend
Returns the set of inferred and asserted statement involving a resource as a Jena Model..- Specified by:
getSubmodel
in interfaceIOntologyBackend
- 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:
-
getSuperclassesOf
public Set<com.hp.hpl.jena.ontology.OntClass> getSuperclassesOf(com.hp.hpl.jena.ontology.OntClass type, boolean onlyDirect) throws com.hp.hpl.jena.shared.NotFoundException - Specified by:
getSuperclassesOf
in interfaceIOntologyBackend
- Throws:
com.hp.hpl.jena.shared.NotFoundException
-
getSubclassesOf
public Set<com.hp.hpl.jena.ontology.OntClass> getSubclassesOf(com.hp.hpl.jena.ontology.OntClass type, boolean onlyDirect) throws com.hp.hpl.jena.shared.NotFoundException - Specified by:
getSubclassesOf
in interfaceIOntologyBackend
- Throws:
com.hp.hpl.jena.shared.NotFoundException
-
getInstancesOf
public Set<com.hp.hpl.jena.ontology.OntResource> getInstancesOf(com.hp.hpl.jena.ontology.OntClass type, boolean onlyDirect) throws com.hp.hpl.jena.shared.NotFoundException - Specified by:
getInstancesOf
in interfaceIOntologyBackend
- Throws:
com.hp.hpl.jena.shared.NotFoundException
-
getClassesOf
public Set<com.hp.hpl.jena.ontology.OntClass> getClassesOf(com.hp.hpl.jena.ontology.OntResource resource, boolean onlyDirect) throws com.hp.hpl.jena.shared.NotFoundException - Specified by:
getClassesOf
in interfaceIOntologyBackend
- Throws:
com.hp.hpl.jena.shared.NotFoundException
-
lookup
Description copied from interface:IOntologyBackend
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.- Specified by:
lookup
in interfaceIOntologyBackend
- 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:
-
lookup
Description copied from interface:IOntologyBackend
Returns the set of all id of concepts whose labels or ids match the given parameter and of the given type.- Specified by:
lookup
in interfaceIOntologyBackend
- Parameters:
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:
-
getParameters
Returns the current set of parameters.- Returns:
- the current set of parameters, reflecting the content of the configuration file.
-
clear
Description copied from interface:IOntologyBackend
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()); }
- Specified by:
clear
in interfaceIOntologyBackend
- Parameters:
partialStmt
- The partial statement representing a "mask" of statements to delete.- Throws:
OntologyServerException
-
remove
@Deprecated public void remove(com.hp.hpl.jena.rdf.model.Statement stmt) throws OntologyServerException Deprecated.Description copied from interface:IOntologyBackend
Removes a given statement from the ontology. Does nothing if the statement doesn't exist.- Specified by:
remove
in interfaceIOntologyBackend
- Parameters:
stmt
- The statement to remove from the ontology.- Throws:
OntologyServerException
- See Also:
-
remove
Description copied from interface:IOntologyBackend
Removes a set of statements from the ontology. It ignores statements that do not exist.- Specified by:
remove
in interfaceIOntologyBackend
- Parameters:
stmts
- The statements to remove from the ontology.- Throws:
OntologyServerException
- See Also:
-
update
public void update(Set<com.hp.hpl.jena.rdf.model.Statement> stmts) throws IllegalStatementException, InconsistentOntologyException, OntologyServerException Description copied from interface:IOntologyBackend
Update the value of a property. This method is equivalent to aIOntologyBackend.remove(Statement)
followed by anIOntologyBackend.add(Set, MemoryProfile, boolean)
. ATTENTION: this method works only on functional properties (ie, properties that are subclasses ofowl:FunctionalProperty
. For non-functional properties (or if the subject or predicate does not exist), this method behaves likeinvalid reference
#add(Set)
- Specified by:
update
in interfaceIOntologyBackend
- Parameters:
stmts
- The set of statements to update in the ontology.- Throws:
IllegalStatementException
InconsistentOntologyException
OntologyServerException
-
save
@RPCMethod(category="administration", desc="exports the current ontology model to an OWL file. The provided path must be writable by the server.") public void save(String path) throws OntologyServerException Description copied from interface:IOntologyBackend
Saves the in-memory ontology model to a RDF/XML file.- Specified by:
save
in interfaceIOntologyBackend
- Parameters:
path
- The path and name of the OWL file to save to (for instance./ontos/saved.owl
)- Throws:
OntologyServerException
- thrown when the output path is not valid or not accessible.- See Also:
-
save
@RPCMethod(category="administration", desc="exports the current ontology model to an OWL file. The file will be saved to the current directory with an automaticallygenerated name.") public void save() throws OntologyServerException- Throws:
OntologyServerException
-
list
@RPCMethod(category="administration", desc="Lists on the serveur stdout all facts matching a given pattern.") public void list(String pattern) throws IllegalStatementException - Throws:
IllegalStatementException
-
registerEvent
Description copied from interface:IOntologyBackend
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 SPARQLASK
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 (throughinvalid reference
IWatcher#notifySubscriber()
- Specified by:
registerEvent
in interfaceIOntologyBackend
- Throws:
EventRegistrationException
- See Also:
-
clearEvents
public void clearEvents()Description copied from interface:IOntologyBackend
Removes all registered event watchers for this model.- Specified by:
clearEvents
in interfaceIOntologyBackend
-
clearEvent
Description copied from interface:IOntologyBackend
Removes one specific event watcher.- Specified by:
clearEvent
in interfaceIOntologyBackend
- Parameters:
watcher
- the watcher to remove- Throws:
OntologyServerException
-
getSupportedEvents
Description copied from interface:IOntologyBackend
Return the list of event types implemented (hence usable) by this backend.- Specified by:
getSupportedEvents
in interfaceIOntologyBackend
- Returns:
- The list of event type supported by the backend
-
step
public void step()Description copied from interface:IOntologyBackend
'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.- Specified by:
step
in interfaceIOntologyBackend
-
close
public void close()Description copied from interface:IOntologyBackend
Closes the model- Specified by:
close
in interfaceIOntologyBackend
-
onModelChange
This protected method is called every time the ontology model changes (ie upon addition or removal of statements in the ontology). It is mainly responsible for testing the various watchPatterns as provided by the set of activeIWatcher
against the ontology. onModelChange() relies on a caching mechanism of requests to improve performances. It remains however a serious performance bottleneck.- Parameters:
rsName
- the name of the reified statements whose creation triggered the update. Can be null if it does not apply.- See Also:
-
size
public long size()Description copied from interface:IOntologyBackend
Returns the number of statements in the model.- Specified by:
size
in interfaceIOntologyBackend
- Returns:
- the number of statements in the model.
-