net.sourceforge.fluxion.datasource.utils
Class QueryUtils

java.lang.Object
  net.sourceforge.fluxion.datasource.utils.QueryUtils

public class QueryUtils
extends java.lang.Object

A general utility class for producing filters given an incoming query class. This should be the first pot of call when trying to obtain the results for a particular OWL query. In most cases, given an incoming OWL query class, "q", a client can simply call QueryUtils.createFilters(ontology, q) and get back a set of filters which, when used to generate and execute a query, is guaranteed to return at least all instances of the query class.

Version:

0.2

Author:

Tony Burdett

See Also:

OWLUtils, BeanUtils

Constructor Summary

QueryUtils()

Method Summary

static boolean	checkQueryIntegrity(org.semanticweb.owl.model.OWLOntology ontology, org.semanticweb.owl.model.OWLDescription query) This method checks the integrity of a query against the supplied ontology.
static BeanConverter	createConverterForFilter(ReasonerSession session, org.semanticweb.owl.model.OWLOntology schemaOntology, org.semanticweb.owl.model.OWLOntology resultOntology, org.semanticweb.owl.model.OWLDescription query, Filter filter)
static java.util.Set<Filter>	createFilters(ReasonerSession session, org.semanticweb.owl.model.OWLOntology ontology, org.semanticweb.owl.model.OWLDescription query) Convert an OWLClass into a Set of filters.
static Query	createQuery(java.lang.Class queryManager, Filter filter) Creates a new Query using the given QueryManager class and the Filter supplied.
static java.util.Set<org.semanticweb.owl.model.OWLEntity>	getBadlyFormedQueryEntities(org.semanticweb.owl.model.OWLOntology ontology, org.semanticweb.owl.model.OWLDescription query) Use this method to recover those entities that cause the query OWLDescription to fail and integrity check.
static java.lang.Class	getQueryManagerClass(ReasonerSession session, org.semanticweb.owl.model.OWLOntology ontology, org.semanticweb.owl.model.OWLDescription query) Get the QueryManager object for a given OWL class.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

QueryUtils

public QueryUtils()

Method Detail

checkQueryIntegrity

public static boolean checkQueryIntegrity(org.semanticweb.owl.model.OWLOntology ontology,
                                          org.semanticweb.owl.model.OWLDescription query)

This method checks the integrity of a query against the supplied ontology. An "integrity check" in this case checks all the things referred to by a query, and ensures they all exist with an ontology. So for example, a query that says A some(has_foo B) will check the supplied ontology to make sure A, has_foo, and B all exist. If any of these concepts are not declared by the supplied ontology or it's available imports closure then this method will return false, otherwise true.

Parameters:

ontology - the ontology to check

query - the query being integrity-checked

Returns:

true is this is a well formed query, false otherwise

getBadlyFormedQueryEntities

public static java.util.Set<org.semanticweb.owl.model.OWLEntity> getBadlyFormedQueryEntities(org.semanticweb.owl.model.OWLOntology ontology,
                                                                                             org.semanticweb.owl.model.OWLDescription query)

Use this method to recover those entities that cause the query OWLDescription to fail and integrity check. So, first call checkQueryIntegrity() and if this returns false and you want to obtain extra debugging info, call this method to get a set of those terms not present in the ontology.

Parameters:

ontology - the ontology being checked

query - the OWLDescription being assessed

Returns:

the set of badly formed entities

getQueryManagerClass

public static java.lang.Class getQueryManagerClass(ReasonerSession session,
                                                   org.semanticweb.owl.model.OWLOntology ontology,
                                                   org.semanticweb.owl.model.OWLDescription query)
                                            throws MissingElementException

Get the QueryManager object for a given OWL class. This is acheived by looking for a RelatedBean annotation on the owl class. NUll is returned if this method can't find a QueryManager for this class, after axhausting possibilities of looking within this class for an OWL class with a RelatedBean annotation (i.e. by searching for intersection class, and restrictions).

Parameters:

ontology - the ontology being queried

query - the OWLDescription describing our query

Returns:

a new instance of the QueryManager for this set owl class

Throws:

MissingElementException - if the QueryManager class can't be discovered

createFilters

public static java.util.Set<Filter> createFilters(ReasonerSession session,
                                                  org.semanticweb.owl.model.OWLOntology ontology,
                                                  org.semanticweb.owl.model.OWLDescription query)
                                           throws OWLTransformationException

Convert an OWLClass into a Set of filters. Normally, an OWLClass is represented by a Javabean class description. However, to do a query against the bean model when the OWLClass contains restricted properties, we cannot model the class in the same way. In this case, the restrictions on a class are used to create a filter, which acts to select those properties on a bean which are required to set query parameters, and which should be returned. This acts as an equivalent in Java to the open world reasoning logic in OWL. This filter is then used to generate a query, which when executed will return a set of fully described bean instances.

A given query class can be translated into a (set of) filters. In the special case where the query class is a whole class as defined by the ontology, we can use the RelatedBean annotation to get a target bean FooBean, then trivialy get hold of its filter to return all bean instances. However, in all other cases we must obtain the set of superclasses of the query class to determmine those beans we need to query, and any restrictions to set.

Note that the owlClass passed as a parameter must somewhere in its composition contain a described class, containing a "RelatedBean" annotation, to allow us to locate the appropriate bean in the model.

Parameters:

ontology - the ontology we're querying against

query - the incoming query description

Returns:

a bean instance object

Throws:

OWLTransformationException - if there is some problem in translating the owl

createQuery

public static Query createQuery(java.lang.Class queryManager,
                                Filter filter)
                         throws OWLTransformationException

Creates a new Query using the given QueryManager class and the Filter supplied.

Parameters:

queryManager - the QueryManager class, which must be on the current classpath

filter - the Filter to use to create this query

Returns:

the query that returns the results given by the filter

Throws:

OWLTransformationException - if there is a problem generating the query

createConverterForFilter

public static BeanConverter createConverterForFilter(ReasonerSession session,
                                                     org.semanticweb.owl.model.OWLOntology schemaOntology,
                                                     org.semanticweb.owl.model.OWLOntology resultOntology,
                                                     org.semanticweb.owl.model.OWLDescription query,
                                                     Filter filter)
                                              throws OWLTransformationException

Throws:

OWLTransformationException