com.day.cq.search

Class Predicate

java.lang.Object

com.day.cq.search.Predicate

All Implemented Interfaces:

java.lang.Cloneable

Direct Known Subclasses:

PredicateGroup

public class Predicate
extends java.lang.Object
implements java.lang.Cloneable

A Predicate is a single constraint for a Query. It is a pure data model object, consisting of a parameter map based on key-value string pairs.

Each Predicate has a type (getType()) that is used to find the right PredicateEvaluator that will handle this predicate and eg. translate it into an XPath statement.

Using the composite pattern, the subclass PredicateGroup allows to group multiple predicates into one. This allows the query to actually consist of a predicate tree and reflects more complex queries that include sub-terms. The methods getName(), getPath() and #getParent() return that hierarchy information. The name/path is important, because facets will be returned in a map with the appropriate predicate path as key (see SearchResult.getFacets()).

The parameters are set via the set(String, String) method and retrieved via get(String), get(String, String) or getParameters(). Predicates are also Cloneable, so that it is easy to copy them.

Since:

5.2

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	ORDER_BY
static java.lang.String	PARAM_EXCERPT
static java.lang.String	PARAM_GUESS_TOTAL If true, this allows the implementation to optimize the query and return just a guessed count.
static java.lang.String	PARAM_LIMIT
static java.lang.String	PARAM_OFFSET
static java.lang.String	PARAM_SORT
static java.lang.String	SORT_ASCENDING
static java.lang.String	SORT_DESCENDING

Constructor Summary

Constructors

Constructor and Description
Predicate(java.lang.String type) Creates a Predicate of the given type.
Predicate(java.lang.String name, java.lang.String type) Creates a Predicate with the given name and type.

Method Summary

Methods

Modifier and Type	Method and Description
Predicate	clone() Clones this predicate so that the returned clone can be used completely independently from this original.
Predicate	clone(boolean resetName) Clones this predicate so that the returned clone can be used completely independently from this original.
java.lang.String	get(java.lang.String parameterName) Returns the value for the given parameter name or null if that parameter is not set.
java.lang.String	get(java.lang.String parameterName, java.lang.String defaultValue) Returns the value for the given parameter name or the given default value if that parameter is not set.
boolean	getBool(java.lang.String parameterName) Returns the boolean value for the given parameter name or false if that parameter is not set, ie.
java.lang.String	getName() Returns the name of this predicate.
java.util.Map<java.lang.String,java.lang.String>	getParameters() Returns an unmodifiable map of all parameters and their values.
java.lang.String	getPath() Returns the path in a predicate tree of PredicateGroups to this predicate, eg.
java.lang.String	getType() Returns the predicate type name for finding the right PredicateEvaluator.
boolean	hasNonEmptyValue(java.lang.String parameterName) Returns true when there is a parameter present with the given name and if the string value is not empty.
boolean	ignored() This is used only during evaluation and indicates that this predicate is marked as "invisible" for any PredicateEvaluator that will encounter it.
Predicate	set(java.lang.String parameterName, java.lang.String value) Sets the parameter 'parameterName' to the value given by 'value'.
void	setIgnored(boolean ignore) This is used only during evaluation and marks this predicate as "invisible" for any PredicateEvaluator that will encounter it.
protected void	setParent(PredicateGroup parent) Used by PredicateGroup to store the hierarchy information when adding a predicate (through eg.
java.lang.String	toString() Overwrites the standard Object.toString() implementation and returns a debug-friendly string representation of the predicate.

Methods inherited from class java.lang.Object

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

Field Detail

PARAM_OFFSET

public static final java.lang.String PARAM_OFFSET

See Also:

Constant Field Values

PARAM_LIMIT

public static final java.lang.String PARAM_LIMIT

See Also:

Constant Field Values

PARAM_EXCERPT

public static final java.lang.String PARAM_EXCERPT

See Also:

Constant Field Values

PARAM_GUESS_TOTAL

public static final java.lang.String PARAM_GUESS_TOTAL

If true, this allows the implementation to optimize the query and return just a guessed count. Defaults to false, in which case the total is always accurate.

Since:

5.4

See Also:

Constant Field Values

ORDER_BY

public static final java.lang.String ORDER_BY

See Also:

Constant Field Values

PARAM_SORT

public static final java.lang.String PARAM_SORT

See Also:

Constant Field Values

SORT_ASCENDING

public static final java.lang.String SORT_ASCENDING

See Also:

Constant Field Values

SORT_DESCENDING

public static final java.lang.String SORT_DESCENDING

See Also:

Constant Field Values

Constructor Detail

Predicate

public Predicate(java.lang.String type)

Creates a Predicate of the given type. Note that the type cannot be changed later. The name will be deducted automatically, see getName(). Initially no parameters will be set and no parent will be present.

Parameters:

type - predicate type name for finding the right PredicateEvaluator

Predicate

public Predicate(java.lang.String name,
         java.lang.String type)

Creates a Predicate with the given name and type. Note that name and type cannot be changed later. Initially no parameters will be set and no parent will be present.

The name should not be null - this case is reserved for a root PredicateGroup (using PredicateGroup.PredicateGroup()).

Parameters:

name - identifying name for this predicate

type - predicate type name for finding the right PredicateEvaluator

Method Detail

getType

public java.lang.String getType()

Returns the predicate type name for finding the right PredicateEvaluator.

getName

public java.lang.String getName()

Returns the name of this predicate. The name is used to allow round-trip serialization of predicate trees (where the order is encoded in the names) and for identifying predicates in the facet map, in logging or other debug output.

When a predicate is included in PredicateGroup, the names of the parent predicates will make up the path, eg. parent.child.grandchild. The name must not be changed after the predicate is passed to a Query.

If no name was set previously, it will be automatically created. If this predicate is part of a group, it will get a name of the form "N_type" where N is the 1-based index of its position in the parent group and "type" is it's type. If it does not have a parent group, the name will only consist of the type.

Returns:

identifying name for this predicate (can be null if no name was set)

getPath

public java.lang.String getPath()

Returns the path in a predicate tree of PredicateGroups to this predicate, eg. parent.child.grandchild. This can be null if no name was set. The path is used for identifying predicates in the facet map, in logging or other debug output.

get

public java.lang.String get(java.lang.String parameterName)

Returns the value for the given parameter name or null if that parameter is not set. Parameters always have String values.

get

public java.lang.String get(java.lang.String parameterName,
                   java.lang.String defaultValue)

Returns the value for the given parameter name or the given default value if that parameter is not set. Parameters always have String values.

getBool

public boolean getBool(java.lang.String parameterName)

Returns the boolean value for the given parameter name or false if that parameter is not set, ie. it assumes false as the default of the boolean parameter.

Since actual parameter values are strings, it is considered true if the string value is either "true" or "on" (used by HTTP forms for checkboxes).

set

public Predicate set(java.lang.String parameterName,
            java.lang.String value)

Sets the parameter 'parameterName' to the value given by 'value'. Parameters have always String values.

Returns:

returns itself for simple one-liners: group.add(new Predicate("mytype", "type").set("type", "nt:file"));

hasNonEmptyValue

public boolean hasNonEmptyValue(java.lang.String parameterName)

Returns true when there is a parameter present with the given name and if the string value is not empty. Parameters always have String values.

getParameters

public java.util.Map<java.lang.String,java.lang.String> getParameters()

Returns an unmodifiable map of all parameters and their values.

setIgnored

public void setIgnored(boolean ignore)

This is used only during evaluation and marks this predicate as "invisible" for any PredicateEvaluator that will encounter it. Don't use that method when creating a query.

Parameters:

ignore - true if this predicate should be ignored by evaluators (default is false)

ignored

public boolean ignored()

This is used only during evaluation and indicates that this predicate is marked as "invisible" for any PredicateEvaluator that will encounter it. This method has no use for clients of the querybuilder API.

Returns:

true if this predicate should be ignored by evaluators (default is false)

clone

public Predicate clone()

Clones this predicate so that the returned clone can be used completely independently from this original. Same as clone(false).

Overrides:

clone in class java.lang.Object

clone

public Predicate clone(boolean resetName)

Clones this predicate so that the returned clone can be used completely independently from this original. Allows for automatic reset of the name.

Parameters:

resetName - whether to reset the name to null so that they will be automatically deducted (see getName())

setParent

protected void setParent(PredicateGroup parent)

Used by PredicateGroup to store the hierarchy information when adding a predicate (through eg. PredicateGroup.add(Predicate)). Normally there is no reason to call this method, hence it is protected.

Parameters:

parent - parent predicate group to set

toString

public java.lang.String toString()

Overwrites the standard Object.toString() implementation and returns a debug-friendly string representation of the predicate.

Overrides:

toString in class java.lang.Object