cz.cuni.versatile.api
Interface QueryTemplate

All Superinterfaces:
Query

public interface QueryTemplate
extends Query

QueryTemplate represents the Versatile API to the underlying "meta-data query language". In a typical case, the actual Query objects are not created directly but they are instantiated using newQuery method of the QueryTemplate class. The instances of the QueryTemplate class serve the following purposes:

  1. define a set of meta-data constraints and preferences (an ordered list of predicates)
  2. define the query evaluation preferences (N-best, score threshold, scoring factor)
  3. allow to re-use the same settings for multiple different queries (with different resource name)
  4. allow to fully automate property value evaluation and substitution during query instantiation (automatically retrieving property values for each predicate from the associated delivery context)

The interface provides a generic method for adding property predicates (addPredicate) and a set of methods allowing a short-hand notation for all the Versatile predefined operators.

Author:
Jaroslav Gergic
See Also:
PropertyOperators

Field Summary
 
Fields inherited from interface cz.cuni.versatile.api.Query
BIASED_SCORING_FACTOR, DEFAULT_MATCH_SCORE, DEFAULT_N_BEST, DEFAULT_SCORING_FACTOR, EXACT_MATCH_SCORE, NEUTRAL_SCORING_FACTOR
 
Method Summary
 void add_Equal(java.lang.String uniqueName)
          Add a meta-data predicate using a given property and the PropertyOperators#EQ (equals) intrinsic operator.
 void add_GE(java.lang.String uniqueName)
          Add a meta-data predicate using a given property and the PropertyOperators#GE (greater than or equals) intrinsic operator.
 void add_GT(java.lang.String uniqueName)
          Add a meta-data predicate using a given property and the PropertyOperators#GT (greater than) intrinsic operator.
 void add_LE(java.lang.String uniqueName)
          Add a meta-data predicate using a given property and the PropertyOperators#LE (less than or equals) intrinsic operator.
 void add_LT(java.lang.String uniqueName)
          Add a meta-data predicate using a given property and the PropertyOperators#LT (less than) intrinsic operator.
 void addAssert(java.lang.String uniqueName)
          Add a meta-data predicate using a given property and the PropertyOperators#ASSERT (assert) extrinsic operator.
 void addAssertInv(java.lang.String uniqueName)
          Add a meta-data predicate using a given property and the PropertyOperators#ASSERT_INV (assertInv) extrinsic operator.
 void addAssertLevel(java.lang.String uniqueName, int level)
          Add a meta-data predicate using a given property and the PropertyOperators#ASSERT_LEVEL (assertLevel) extrinsic operator.
 void addBestMatch(java.lang.String uniqueName)
          Add a meta-data predicate using a given property and the PropertyOperators#BEST_MATCH (bestMatch) extrinsic operator.
 void addComparable(java.lang.String uniqueName)
          Add a meta-data predicate using a given property and the PropertyOperators#COMPARABLE (comparable) extrinsic operator.
 void addEquivalent(java.lang.String uniqueName)
          Add a meta-data predicate using a given property and the PropertyOperators#EQUIVALENT (equivalent) extrinsic operator.
 void addIsAncestor(java.lang.String uniqueName)
          Add a meta-data predicate using a given property and the PropertyOperators#IS_ANCESTOR (isAncestor) extrinsic operator.
 void addIsChild(java.lang.String uniqueName)
          Add a meta-data predicate using a given property and the PropertyOperators#IS_CHILD (isChild) extrinsic operator.
 void addIsDescendant(java.lang.String uniqueName)
          Add a meta-data predicate using a given property and the PropertyOperators#IS_DESCENDANT (isDescendant) extrinsic operator.
 void addIsParent(java.lang.String uniqueName)
          Add a meta-data predicate using a given property and the PropertyOperators#IS_PARENT (isParent) extrinsic operator.
 void addPredicate(PropertyPredicate pp)
          A generic method for adding a meta-data predicate.
 DeliveryContext getDeliveryContext()
          Returns the associated delivery context used to evaluate property values and substitute them to the property predicates during query instantiation.
 TemplateBasedQuery newQuery(java.lang.String resourceName)
          Query factory method.
 void setNBest(int nbest)
          Sets the N-best size for queries based on this template.
 void setScoreThreshold(double threshold)
          Sets the score threshold for queries based on this template.
 void setScoringFactor(double scoringFactor)
          Sets the scoring factor for queries based on this template.
 
Methods inherited from interface cz.cuni.versatile.api.Query
getNBest, getPredicates, getResourceName, getScoreThreshold, getScoringFactor
 

Method Detail

setNBest

public void setNBest(int nbest)
Sets the N-best size for queries based on this template.

Parameters:
nbest - a positive integer
See Also:
Query.DEFAULT_N_BEST

setScoreThreshold

public void setScoreThreshold(double threshold)
Sets the score threshold for queries based on this template.

Parameters:
threshold - a number in the interval <Query#DEFAULT_MATCH_SCORE, Query#EXACT_MATCH_SCORE> (<0.0, 1.0>)
See Also:
Query.DEFAULT_MATCH_SCORE, Query.EXACT_MATCH_SCORE

setScoringFactor

public void setScoringFactor(double scoringFactor)
Sets the scoring factor for queries based on this template. The scoring factor determines relative significance of property predicates. It has a significant impact on results in cases when there are multiple property predicates using constraint-relaxing operator like bestMatch.

Parameters:
scoringFactor - a number in the interval (0, Query#NEUTRAL_SCORING_FACTOR>.
See Also:
Query

getDeliveryContext

public DeliveryContext getDeliveryContext()
Returns the associated delivery context used to evaluate property values and substitute them to the property predicates during query instantiation.

Returns:
the associated delivery context

addPredicate

public void addPredicate(PropertyPredicate pp)
                  throws UnregisteredPropertyException
A generic method for adding a meta-data predicate. It allows to build queries using extension property operators which are not pre-defined in Versatile.

Parameters:
pp - a meta-data predicate describing one particular aspect of a desired resource.
Throws:
UnregisteredPropertyException - if the associated DeliveryContext does not recognize a given property (an attribute of the PropertyPredicate parameter)
See Also:
PropertyOperators

add_Equal

public void add_Equal(java.lang.String uniqueName)
               throws UnregisteredPropertyException
Add a meta-data predicate using a given property and the PropertyOperators#EQ (equals) intrinsic operator.

Parameters:
uniqueName - a unique name of the Property
Throws:
UnregisteredPropertyException - if the associated DeliveryContext does not recognize a given property
See Also:
PropertyOperators.EQ

add_GT

public void add_GT(java.lang.String uniqueName)
            throws UnregisteredPropertyException
Add a meta-data predicate using a given property and the PropertyOperators#GT (greater than) intrinsic operator.

Parameters:
uniqueName - a unique name of the Property
Throws:
UnregisteredPropertyException - if the associated DeliveryContext does not recognize a given property
See Also:
PropertyOperators.GT

add_LT

public void add_LT(java.lang.String uniqueName)
            throws UnregisteredPropertyException
Add a meta-data predicate using a given property and the PropertyOperators#LT (less than) intrinsic operator.

Parameters:
uniqueName - a unique name of the Property
Throws:
UnregisteredPropertyException - if the associated DeliveryContext does not recognize a given property
See Also:
PropertyOperators.LT

add_GE

public void add_GE(java.lang.String uniqueName)
            throws UnregisteredPropertyException
Add a meta-data predicate using a given property and the PropertyOperators#GE (greater than or equals) intrinsic operator.

Parameters:
uniqueName - a unique name of the Property
Throws:
UnregisteredPropertyException - if the associated DeliveryContext does not recognize a given property
See Also:
PropertyOperators.GE

add_LE

public void add_LE(java.lang.String uniqueName)
            throws UnregisteredPropertyException
Add a meta-data predicate using a given property and the PropertyOperators#LE (less than or equals) intrinsic operator.

Parameters:
uniqueName - a unique name of the Property
Throws:
UnregisteredPropertyException - if the associated DeliveryContext does not recognize a given property
See Also:
PropertyOperators.LE

addAssert

public void addAssert(java.lang.String uniqueName)
               throws UnregisteredPropertyException,
                      UnsupportedPropertyOperatorException
Add a meta-data predicate using a given property and the PropertyOperators#ASSERT (assert) extrinsic operator.

Parameters:
uniqueName - a unique name of the Property
Throws:
UnregisteredPropertyException - if the associated DeliveryContext does not recognize a given property
UnsupportedPropertyOperatorException - is the operator is not applicable to a given property type
See Also:
PropertyOperators.ASSERT

addAssertInv

public void addAssertInv(java.lang.String uniqueName)
                  throws UnregisteredPropertyException,
                         UnsupportedPropertyOperatorException
Add a meta-data predicate using a given property and the PropertyOperators#ASSERT_INV (assertInv) extrinsic operator.

Parameters:
uniqueName - a unique name of the Property
Throws:
UnregisteredPropertyException - if the associated DeliveryContext does not recognize a given property
UnsupportedPropertyOperatorException - is the operator is not applicable to a given property type
See Also:
PropertyOperators.ASSERT_INV

addAssertLevel

public void addAssertLevel(java.lang.String uniqueName,
                           int level)
                    throws UnregisteredPropertyException,
                           UnsupportedPropertyOperatorException
Add a meta-data predicate using a given property and the PropertyOperators#ASSERT_LEVEL (assertLevel) extrinsic operator.

Parameters:
uniqueName - a unique name of the Property
Throws:
UnregisteredPropertyException - if the associated DeliveryContext does not recognize a given property
UnsupportedPropertyOperatorException - is the operator is not applicable to a given property type
See Also:
PropertyOperators.ASSERT_LEVEL

addEquivalent

public void addEquivalent(java.lang.String uniqueName)
                   throws UnregisteredPropertyException,
                          UnsupportedPropertyOperatorException
Add a meta-data predicate using a given property and the PropertyOperators#EQUIVALENT (equivalent) extrinsic operator.

Parameters:
uniqueName - a unique name of the Property
Throws:
UnregisteredPropertyException - if the associated DeliveryContext does not recognize a given property
UnsupportedPropertyOperatorException - is the operator is not applicable to a given property type
See Also:
PropertyOperators.EQUIVALENT

addComparable

public void addComparable(java.lang.String uniqueName)
                   throws UnregisteredPropertyException,
                          UnsupportedPropertyOperatorException
Add a meta-data predicate using a given property and the PropertyOperators#COMPARABLE (comparable) extrinsic operator.

Parameters:
uniqueName - a unique name of the Property
Throws:
UnregisteredPropertyException - if the associated DeliveryContext does not recognize a given property
UnsupportedPropertyOperatorException - is the operator is not applicable to a given property type
See Also:
PropertyOperators.COMPARABLE

addIsParent

public void addIsParent(java.lang.String uniqueName)
                 throws UnregisteredPropertyException,
                        UnsupportedPropertyOperatorException
Add a meta-data predicate using a given property and the PropertyOperators#IS_PARENT (isParent) extrinsic operator.

Parameters:
uniqueName - a unique name of the Property
Throws:
UnregisteredPropertyException - if the associated DeliveryContext does not recognize a given property
UnsupportedPropertyOperatorException - is the operator is not applicable to a given property type
See Also:
PropertyOperators.IS_PARENT

addIsChild

public void addIsChild(java.lang.String uniqueName)
                throws UnregisteredPropertyException,
                       UnsupportedPropertyOperatorException
Add a meta-data predicate using a given property and the PropertyOperators#IS_CHILD (isChild) extrinsic operator.

Parameters:
uniqueName - a unique name of the Property
Throws:
UnregisteredPropertyException - if the associated DeliveryContext does not recognize a given property
UnsupportedPropertyOperatorException - is the operator is not applicable to a given property type
See Also:
PropertyOperators.IS_CHILD

addIsAncestor

public void addIsAncestor(java.lang.String uniqueName)
                   throws UnregisteredPropertyException,
                          UnsupportedPropertyOperatorException
Add a meta-data predicate using a given property and the PropertyOperators#IS_ANCESTOR (isAncestor) extrinsic operator.

Parameters:
uniqueName - a unique name of the Property
Throws:
UnregisteredPropertyException - if the associated DeliveryContext does not recognize a given property
UnsupportedPropertyOperatorException - is the operator is not applicable to a given property type
See Also:
PropertyOperators.IS_ANCESTOR

addIsDescendant

public void addIsDescendant(java.lang.String uniqueName)
                     throws UnregisteredPropertyException,
                            UnsupportedPropertyOperatorException
Add a meta-data predicate using a given property and the PropertyOperators#IS_DESCENDANT (isDescendant) extrinsic operator.

Parameters:
uniqueName - a unique name of the Property
Throws:
UnregisteredPropertyException - if the associated DeliveryContext does not recognize a given property
UnsupportedPropertyOperatorException - is the operator is not applicable to a given property type
See Also:
PropertyOperators.IS_DESCENDANT

addBestMatch

public void addBestMatch(java.lang.String uniqueName)
                  throws UnregisteredPropertyException,
                         UnsupportedPropertyOperatorException
Add a meta-data predicate using a given property and the PropertyOperators#BEST_MATCH (bestMatch) extrinsic operator.

Parameters:
uniqueName - a unique name of the Property
Throws:
UnregisteredPropertyException - if the associated DeliveryContext does not recognize a given property
UnsupportedPropertyOperatorException - is the operator is not applicable to a given property type
See Also:
PropertyOperators.BEST_MATCH

newQuery

public TemplateBasedQuery newQuery(java.lang.String resourceName)
Query factory method. It takes a unique resource name as its input (resourceName) and creates an immutable Query object using the current QueryTemplate settings and its current predicate list. An implementation of this method performs the following tasks:
  1. clone the list of the existing property predicates and query template settings (N-best, score threshold, scoring factor)
  2. scan the list of all property predicates and build a set of properties used by this query
  3. use the associated DeliveryContext to provide values for all the properties, each property is evaluated only once, even if it appears in more than one predicate
  4. substitute the property values to the predicates
  5. instantiate a Query using the data gathered in the above steps

Remarks:

Parameters:
resourceName - a resource name uniquely identifying a particular resource within the scope of the target ResourceProvider
Returns:
a query object ready to be passed to the intended ResouceProvider