de.uka.ipd.consensus.foundation.query
Interface QueryEngine

All Known Implementing Classes:

QueryEngineImpl, QueryEngineSPARQLDummyImpl

public interface QueryEngine

The QueryEngine is part of the OntologyManager. It is used to retrieve the elements of the ontology by id, by type or as various collections.

Version:

2006-06-14

Author:

Thomas Much

See Also:

OntologyManager

Method Summary

QueryEngineResultSet	executeQuery(User user, String query) Executes a query string and returns the result as a QueryEngineResultSet.
Association	getAssociationById(User user, String id) Returns an association for a given id.
int	getAssociationCount(User user) Returns the number of associations in the ontology that the user may see.
Collection	getAssociationRoles(User user, Association assoc) Returns a collection of all AssociationRole objects that are part of the given association.
Collection	getAssociations(User user, Topic topic) Returns a collection of all Association objects in which the given topic plays a role.
Collection	getAssociationsOfType(User user, Topic type) Returns a collection of all Association objects with the given type.
Collection	getClassRoots(User user) Returns a collection of class Topic objects that have no superclasses.
int	getClassTopicCount(User user) Returns the number of class topics in the ontology that the user may see.
Collection	getClassTopics(User user) Returns a collection of all class Topic objects.
Collection	getClassTopicsByBeginning(User user, String beginning) Returns a collection of class Topic objects whose names match the given beginning (case-insensitive).
Collection	getClassTopicsBySubstring(User user, String substring, boolean searchComment) Returns a collection of class Topic objects whose name (and optionally comment) contain the given substring (case-insensitive).
Concept	getConceptById(User user, String id) Returns a concept for a given id.
Collection	getInstanceRoots(User user) Returns a collection of instance Topic objects that have no types.
Collection	getInstances(User user, Topic topic) Returns a collection of TypeInstance objects that represent the instances of a given type topic.
int	getInstanceTopicCount(User user) Returns the number of non-class topics in the ontology that the user may see.
Collection	getInstanceTopics(User user) Returns a collection of all non-class Topic objects.
Collection	getInstanceTopicsByBeginning(User user, String beginning) Returns a collection of non-class Topic objects whose names match the given beginning (case-insensitive).
Collection	getInstanceTopicsBySubstring(User user, String substring, boolean searchComment) Returns a collection of non-class Topic objects whose name (and optionally comment) contain the given substring (case-insensitive).
String	getQuerySyntaxName() Returns the name of the query language that is provided by the implementation of the QueryEngine.
String	getQuerySyntaxURL() Returns a URL with human-readable information about the syntax of the query language that is provided by the implementation of the QueryEngine.
String	getQuerySyntaxVersion() Returns the version of the query language that is provided by the implementation of the QueryEngine.
Collection	getSubclasses(User user, Topic topic) Returns a collection of SuperSubclass objects that represent the subclasses of a given class topic.
Collection	getSuperclasses(User user, Topic topic) Returns a collection of SuperSubclass objects that represent the superclasses of a given class topic.
Topic	getTopicById(User user, String id) Returns a topic for a given id.
int	getTopicCount(User user) Returns the total number of topics in the ontology that the user may see.
Collection	getTopics(User user) Returns a collection of all Topic objects.
Collection	getTopicsByBeginning(User user, String beginning) Returns a collection of Topic objects whose names match the given beginning (case-insensitive).
Collection	getTopicsBySubstring(User user, String substring, boolean searchComment) Returns a collection of Topic objects whose name (and optionally comment) contain the given substring (case-insensitive).
Collection	getTypes(User user, Topic topic) Returns a collection of TypeInstance objects that represent the types of a given instance topic.
String	getVersion() Returns an implementation specific version of the QueryEngine.

Method Detail

executeQuery

public QueryEngineResultSet executeQuery(User user,
                                         String query)
                                  throws QueryEngineException,
                                         DynamicRightsManagerException

Executes a query string and returns the result as a QueryEngineResultSet.

Parameters:

user - the user who wants to do the query

query - the query string

Returns:

a possibly empty result set, never null

Throws:

QueryEngineSyntaxException - if the query string is syntactically incorrect

QueryEngineProcessingException - the the query could not be processed (for example, due to logical errors in the query string)

QueryEngineException - if any other error occurs

DynamicRightsManagerException - if the user is not allowed to execute free queries in the query language

See Also:

DynamicRightsManager.mayQuery(User, String), getQuerySyntaxName(), getQuerySyntaxURL(), getQuerySyntaxVersion()

getTopicById

public Topic getTopicById(User user,
                          String id)
                   throws QueryEngineException

Returns a topic for a given id.

Parameters:

user - the user who wants to get the topic

id - the topic's id

Returns:

the topic with the given id or null if the id does not exist

Throws:

QueryEngineException - if the topic could not be read

See Also:

DynamicRightsManager.mayViewTopic(User, Topic)

getTopics

public Collection getTopics(User user)
                     throws QueryEngineException

Returns a collection of all Topic objects.

Parameters:

user - the user who wants to get the topics

Returns:

a possibly empty collection, never null

Throws:

QueryEngineException - if the topics could not be read

See Also:

Topic, DynamicRightsManager.mayViewTopic(User, Topic)

getTopicsByBeginning

public Collection getTopicsByBeginning(User user,
                                       String beginning)
                                throws QueryEngineException

Returns a collection of Topic objects whose names match the given beginning (case-insensitive).

Parameters:

user - the user who wants to get the topics

beginning - the required beginning of a topic name; null or the empty string match all topics

Returns:

a possibly empty collection, never null

Throws:

QueryEngineException - if the topics could not be read

See Also:

Topic, DynamicRightsManager.mayViewTopic(User, Topic)

getTopicsBySubstring

public Collection getTopicsBySubstring(User user,
                                       String substring,
                                       boolean searchComment)
                                throws QueryEngineException

Returns a collection of Topic objects whose name (and optionally comment) contain the given substring (case-insensitive).

Parameters:

user - the user who wants to get the topics

substring - the required substring of a topic name or comment; null or the empty string match all topics

searchComment - if true, the comments are searched for the substring, too, otherwise only the topic name is searched

Returns:

a possibly empty collection, never null

Throws:

QueryEngineException - if the topics could not be read

See Also:

Topic, DynamicRightsManager.mayViewTopic(User, Topic)

getClassTopics

public Collection getClassTopics(User user)
                          throws QueryEngineException

Returns a collection of all class Topic objects.

Parameters:

user - the user who wants to get the topics

Returns:

a possibly empty collection, never null

Throws:

QueryEngineException - if the topics could not be read

See Also:

Topic, Topic.isClassTopic(), DynamicRightsManager.mayViewTopic(User, Topic)

getClassTopicsByBeginning

public Collection getClassTopicsByBeginning(User user,
                                            String beginning)
                                     throws QueryEngineException

Returns a collection of class Topic objects whose names match the given beginning (case-insensitive).

Parameters:

user - the user who wants to get the topics

beginning - the required beginning of a topic name; null or the empty string match all class topics

Returns:

a possibly empty collection, never null

Throws:

QueryEngineException - if the topics could not be read

See Also:

Topic, Topic.isClassTopic(), DynamicRightsManager.mayViewTopic(User, Topic)

getClassTopicsBySubstring

public Collection getClassTopicsBySubstring(User user,
                                            String substring,
                                            boolean searchComment)
                                     throws QueryEngineException

Returns a collection of class Topic objects whose name (and optionally comment) contain the given substring (case-insensitive).

Parameters:

user - the user who wants to get the topics

substring - the required substring of a topic name or comment; null or the empty string match all class topics

searchComment - if true, the comments are searched for the substring, too, otherwise only the topic name is searched

Returns:

a possibly empty collection, never null

Throws:

QueryEngineException - if the topics could not be read

See Also:

Topic, Topic.isClassTopic(), DynamicRightsManager.mayViewTopic(User, Topic)

getInstanceTopics

public Collection getInstanceTopics(User user)
                             throws QueryEngineException

Returns a collection of all non-class Topic objects.

Parameters:

user - the user who wants to get the topics

Returns:

a possibly empty collection, never null

Throws:

QueryEngineException - if the topics could not be read

See Also:

Topic, Topic.isClassTopic(), DynamicRightsManager.mayViewTopic(User, Topic)

getInstanceTopicsByBeginning

public Collection getInstanceTopicsByBeginning(User user,
                                               String beginning)
                                        throws QueryEngineException

Returns a collection of non-class Topic objects whose names match the given beginning (case-insensitive).

Parameters:

user - the user who wants to get the topics

beginning - the required beginning of a topic name; null or the empty string match all non-class topics

Returns:

a possibly empty collection, never null

Throws:

QueryEngineException - if the topics could not be read

See Also:

Topic, Topic.isClassTopic(), DynamicRightsManager.mayViewTopic(User, Topic)

getInstanceTopicsBySubstring

public Collection getInstanceTopicsBySubstring(User user,
                                               String substring,
                                               boolean searchComment)
                                        throws QueryEngineException

Returns a collection of non-class Topic objects whose name (and optionally comment) contain the given substring (case-insensitive).

Parameters:

user - the user who wants to get the topics

substring - the required substring of a topic name or comment; null or the empty string match all non-class topics

searchComment - if true, the comments are searched for the substring, too, otherwise only the topic name is searched

Returns:

a possibly empty collection, never null

Throws:

QueryEngineException - if the topics could not be read

See Also:

Topic, Topic.isClassTopic(), DynamicRightsManager.mayViewTopic(User, Topic)

getTypes

public Collection getTypes(User user,
                           Topic topic)
                    throws QueryEngineException

Returns a collection of TypeInstance objects that represent the types of a given instance topic.

Parameters:

user - the user who wants to get the types

topic - the instance topic for which the types are returned

Returns:

a possibly empty collection, never null

Throws:

QueryEngineException - if the types could not be read

See Also:

TypeInstance, DynamicRightsManager.mayViewTopic(User, Topic)

getInstances

public Collection getInstances(User user,
                               Topic topic)
                        throws QueryEngineException

Returns a collection of TypeInstance objects that represent the instances of a given type topic.

Parameters:

user - the user who wants to get the instances

topic - the type topic for which the instances are returned

Returns:

a possibly empty collection, never null

Throws:

QueryEngineException - if the instances could not be read

See Also:

TypeInstance, DynamicRightsManager.mayViewTopic(User, Topic)

getInstanceRoots

public Collection getInstanceRoots(User user)
                            throws QueryEngineException

Returns a collection of instance Topic objects that have no types.

Parameters:

user - the user who wants to get the root instance topics

Returns:

a possibly empty collection, never null

Throws:

QueryEngineException - if the root instance topics could not be read

See Also:

Topic, DynamicRightsManager.mayViewTopic(User, Topic)

getSuperclasses

public Collection getSuperclasses(User user,
                                  Topic topic)
                           throws QueryEngineException

Returns a collection of SuperSubclass objects that represent the superclasses of a given class topic.

If the implementation does not support classes, an empty collection is returned.

Parameters:

user - the user who wants to get the superclasses

topic - the class topic for which the superclasses are returned

Returns:

a possibly empty collection, never null

Throws:

QueryEngineException - if the superclasses could not be read

See Also:

SuperSubclass, DynamicRightsManager.mayViewTopic(User, Topic)

getSubclasses

public Collection getSubclasses(User user,
                                Topic topic)
                         throws QueryEngineException

Returns a collection of SuperSubclass objects that represent the subclasses of a given class topic.

If the implementation does not support classes, an empty collection is returned.

Parameters:

user - the user who wants to get the subclasses

topic - the class topic for which the subclasses are returned

Returns:

a possibly empty collection, never null

Throws:

QueryEngineException - if the subclasses could not be read

See Also:

SuperSubclass, DynamicRightsManager.mayViewTopic(User, Topic)

getClassRoots

public Collection getClassRoots(User user)
                         throws QueryEngineException

Returns a collection of class Topic objects that have no superclasses.

If the implementation does not support classes, an empty collection is returned.

Parameters:

user - the user who wants to get the root class topics

Returns:

a possibly empty collection, never null

Throws:

QueryEngineException - if the root class topics could not be read

See Also:

Topic, Topic.isClassTopic(), DynamicRightsManager.mayViewTopic(User, Topic)

getAssociationById

public Association getAssociationById(User user,
                                      String id)
                               throws QueryEngineException

Returns an association for a given id.

Parameters:

user - the user who wants to get the association

id - the association's id

Returns:

the association with the given id or null if the id does not exist

Throws:

QueryEngineException - if the association could not be read

See Also:

DynamicRightsManager.mayViewAssociation(User, Association)

getAssociations

public Collection getAssociations(User user,
                                  Topic topic)
                           throws QueryEngineException

Returns a collection of all Association objects in which the given topic plays a role.

Parameters:

user - the user who wants to get the associations

topic - the topic that is player in all returned associations

Returns:

a possibly empty collection, never null

Throws:

QueryEngineException - if the associations could not be read

See Also:

Association, DynamicRightsManager.mayViewAssociation(User, Association)

getAssociationsOfType

public Collection getAssociationsOfType(User user,
                                        Topic type)
                                 throws QueryEngineException

Returns a collection of all Association objects with the given type.

Parameters:

user - the user who wants to get the associations

type - the type of all returned associations, including null for typeless associations

Returns:

a possibly empty collection, never null

Throws:

QueryEngineException - if the associations could not be read

See Also:

Association, DynamicRightsManager.mayViewAssociation(User, Association)

getAssociationRoles

public Collection getAssociationRoles(User user,
                                      Association assoc)
                               throws QueryEngineException

Returns a collection of all AssociationRole objects that are part of the given association. This includes the typeless role if it is part of the association.

Parameters:

user - the user who wants to get the association roles

assoc - the association for which the roles are returned

Returns:

a possibly empty collection, never null

Throws:

QueryEngineException - if the association roles could not be read

See Also:

AssociationRole, DynamicRightsManager.mayViewTopic(User, Topic)

getConceptById

public Concept getConceptById(User user,
                              String id)
                       throws QueryEngineException

Returns a concept for a given id.

Parameters:

user - the user who wants to get the concept

id - the concept's id

Returns:

the concept with the given id or null if the id does not exist

Throws:

QueryEngineException - if the concept could not be read

See Also:

DynamicRightsManager.mayViewTopic(User, Topic), DynamicRightsManager.mayViewAssociation(User, Association), DynamicRightsManager.mayViewAttribute(User, Attribute)

getTopicCount

public int getTopicCount(User user)

Returns the total number of topics in the ontology that the user may see.

Parameters:

user - the user who wants to read the number of topics

Returns:

the number of topics the user is allowed to see

See Also:

DynamicRightsManager.mayViewTopic(User, Topic)

getClassTopicCount

public int getClassTopicCount(User user)

Returns the number of class topics in the ontology that the user may see.

Parameters:

user - the user who wants to read the number of class topics

Returns:

the number of class topics the user is allowed to see

See Also:

Topic.isClassTopic(), DynamicRightsManager.mayViewTopic(User, Topic)

getInstanceTopicCount

public int getInstanceTopicCount(User user)

Returns the number of non-class topics in the ontology that the user may see.

Parameters:

user - the user who wants to read the number of non-class topics

Returns:

the number of non-class topics the user is allowed to see

See Also:

Topic.isClassTopic(), DynamicRightsManager.mayViewTopic(User, Topic)

getAssociationCount

public int getAssociationCount(User user)

Returns the number of associations in the ontology that the user may see.

Parameters:

user - the user who wants to read the number of associations

Returns:

the number of associations the user is allowed to see

See Also:

DynamicRightsManager.mayViewAssociation(User, Association)

getVersion

public String getVersion()

Returns an implementation specific version of the QueryEngine.

Returns:

the version of the QueryEngine

getQuerySyntaxName

public String getQuerySyntaxName()

Returns the name of the query language that is provided by the implementation of the QueryEngine.

Returns:

the name of the query language (e.g. "Tolog")

See Also:

getQuerySyntaxVersion(), executeQuery(User, String)

getQuerySyntaxVersion

public String getQuerySyntaxVersion()

Returns the version of the query language that is provided by the implementation of the QueryEngine.

Returns:

the version of the query language (e.g. "1.0")

See Also:

getQuerySyntaxName(), executeQuery(User, String)

getQuerySyntaxURL

public String getQuerySyntaxURL()

Returns a URL with human-readable information about the syntax of the query language that is provided by the implementation of the QueryEngine.

Returns:

a URL that points to a query language documentation

See Also:

executeQuery(User, String)