org.mmbase.bridge

Interface Query

All Superinterfaces:

Cacheable, Cloneable, PublicCloneable<Query>, SearchQuery, SearchQueryWrapper

All Known Subinterfaces:

NodeQuery

All Known Implementing Classes:

AbstractQueryWrapper, BasicNodeQuery, BasicQuery, NodeQueryWrapper, QueryWrapper, RemoteNodeQuery_Proxy, RemoteQuery_Proxy

public interface Query
extends SearchQuery, PublicCloneable<Query>, SearchQueryWrapper

Representation of a (database) query. It is modifiable for use by bridge-users.

Since:

MMBase-1.7

Version:

$Id$

Author:

Michiel Meeuwissen, Pierre van Rooden

See Also:

Queries

Field Summary

Fields inherited from interface org.mmbase.storage.search.SearchQuery

DEFAULT_MAX_NUMBER, DEFAULT_OFFSET

Method Summary

Modifier and Type	Method and Description
AggregatedField	addAggregatedField(Step step, Field field, int aggregationType) Add an aggregated field to a step
StepField	addField(Step step, Field field) Adds a field to a step.
StepField	addField(String field) Adds a field by string
void	addNode(Step s, int number)
void	addNode(Step s, Node node) Adds a node to a step.
RelationStep	addRelationStep(NodeManager otherManager) If you need to add a 'related' NodeManager without specifying a role/searchDir simply use these addRelationStep.
RelationStep	addRelationStep(NodeManager nodeManager, String role, String searchDir) Adds new Relation step to the query.
SortOrder	addSortOrder(StepField f, int direction) Defaulting version of addSortOrder(StepField, int, boolean, int) (sorting case insensitively, and no date parts).
SortOrder	addSortOrder(StepField f, int direction, boolean caseSensitive) Defaulting version of addSortOrder(StepField, int, boolean, int) (no date parts)
SortOrder	addSortOrder(StepField f, int direction, boolean caseSensitive, int part) Adds an order on a certain field.
Step	addStep(NodeManager nodeManager) Adds a NodeManager to this Query.
Query	aggregatingClone() Creates an unused aggregate clone of this query.
Query	clone() Create an (unused) clone
Query	cloneWithoutFields() Clones this object, only without the fields
CompositeConstraint	createConstraint(Constraint c1, int op, Constraint c2) Combines two Constraints to one new one, using a boolean operator (AND or OR).
FieldNullConstraint	createConstraint(StepField f) Create a constraint (for use with this Query object).
FieldValueConstraint	createConstraint(StepField f, int op, Object v) Create a constraint (for use with this Query object).
FieldValueConstraint	createConstraint(StepField f, int op, Object v, int part) Create a constraint (for use with this Query object).
CompareFieldsConstraint	createConstraint(StepField f, int op, StepField v) Create a constraint (for use with this Query object).
FieldValueConstraint	createConstraint(StepField f, Object v) Create a constraint (for use with this Query object).
FieldValueBetweenConstraint	createConstraint(StepField f, Object o1, Object o2) Create a constraint (for use with this Query object).
FieldValueInQueryConstraint	createConstraint(StepField f, Query q)
FieldValueInConstraint	createConstraint(StepField f, SortedSet<? extends Object> v) Create a constraint (for use with this Query object).
LegacyConstraint	createConstraint(String s) Create a constraint (for use with this Query object).
StepField	createStepField(Step step, Field field) Creates a StepField object withouth adding it (needed for aggregated queries).
StepField	createStepField(Step step, String fieldName) Creates a StepField object withouth adding it (needed for aggregated queries).
StepField	createStepField(String fieldIdentifer) Creates the step field for the given name.
Constraint	getCleanConstraint() Gets the 'clean' constraint on this query.
Cloud	getCloud() Returns the Cloud for which this Query was defined.
NodeList	getList() Executes the query and returns the resulting node list.
Step	getStep(String stepAlias) Returns the step with given alias, or null if it is not present
boolean	isUsed() Whether this query was used or not.
boolean	markUsed() Mark this query 'used'.
void	removeFields() Removes all fields from the Query object.
void	removeImplicitFields()
void	setAlias(Step step, String alias) Sets the alias to the given step.
FieldConstraint	setCaseSensitive(FieldConstraint constraint, boolean sensitive) Changes the given constraint's 'case sensitivity' (if applicable).
void	setConstraint(Constraint c) The (composite) constraint can actually be set into the query with this method.
Query	setDistinct(boolean distinct) Specifies wether the query result must contain only 'distinct' results.
Constraint	setInverse(Constraint c, boolean i) Changes the given constraint's 'inverse' (if applicable).
Query	setMaxNumber(int maxNumber) Limits the query-result to maxNumber records.
Query	setOffset(int offset) Offsets the query-result with offset records.
String	toSql() Shows the query in a human-readable SQL form.

Methods inherited from interface org.mmbase.storage.search.SearchQuery

equals, getConstraint, getFields, getMaxNumber, getOffset, getSortOrders, getSteps, hashCode, isAggregating, isDistinct, toString

Methods inherited from interface org.mmbase.cache.Cacheable

getCachePolicy, setCachePolicy

Methods inherited from interface org.mmbase.storage.search.SearchQueryWrapper

unwrap

Method Detail

getCloud

Cloud getCloud()

Returns the Cloud for which this Query was defined.

Returns:

Cloud

addStep

Step addStep(NodeManager nodeManager)

Adds a NodeManager to this Query. This can normally be done only once. After that you need to use (one of the) 'addRelationStep'.

Parameters:

nodeManager - The nodeManager associated with the step.

Returns:

The 'step' wrapping the NodeManager.

Throws:

IllegalArgumentException - when an invalid argument is supplied.

See Also:

addRelationStep(NodeManager)

setAlias

void setAlias(Step step,
              String alias)

Sets the alias to the given step.

Parameters:

step - step to add the alias for

alias - The alias which must be given to the step. If it is "" an alias should be generated. 'null' removes the alias.

getStep

Step getStep(String stepAlias)

Returns the step with given alias, or null if it is not present

Parameters:

stepAlias - Alias for the step (may also be tableName, in which case the first step for this table is returned)

Returns:

step with given alias

addRelationStep

RelationStep addRelationStep(NodeManager nodeManager,
                             String role,
                             String searchDir)

Adds new Relation step to the query. Adds the next step as well, it can be retrieved by calling getNext() on the relationstep, and cast to Step.

Parameters:

nodeManager - node manager on the other side of the relation

role - role of a relation

searchDir - the direction of the relation

Returns:

new Relation step

Throws:

IllegalArgumentException - when an invalid argument is supplied.

IllegalStateException - when there is no previous step.

addRelationStep

RelationStep addRelationStep(NodeManager otherManager)

If you need to add a 'related' NodeManager without specifying a role/searchDir simply use these addRelationStep.

Parameters:

otherManager - node manager on the other side of the relation

Returns:

new Relation step

addField

StepField addField(Step step,
                   Field field)

Adds a field to a step.

Parameters:

step - step to add field to

field - field to add

Returns:

new StepField

addField

StepField addField(String field)

Adds a field by string

Parameters:

field - field to add

Returns:

new StepField

removeFields

void removeFields()

Removes all fields from the Query object.

createStepField

StepField createStepField(Step step,
                          Field field)

Creates a StepField object withouth adding it (needed for aggregated queries).

Parameters:

step - step to create StepField from

field - field to create StepField from

Returns:

new StepField

createStepField

StepField createStepField(Step step,
                          String fieldName)

Creates a StepField object withouth adding it (needed for aggregated queries).

Parameters:

step - step to create StepField from

fieldName - name of field to create StepField from

Returns:

new StepField

createStepField

StepField createStepField(String fieldIdentifer)

Creates the step field for the given name. For a NodeQuery the arguments is simply the name of the field. For a 'normal' query, it should be prefixed by the (automatic) alias of the Step.

Parameters:

fieldIdentifer - field identifier to create StepField from

Returns:

new StepField

addAggregatedField

AggregatedField addAggregatedField(Step step,
                                   Field field,
                                   int aggregationType)

Add an aggregated field to a step

Parameters:

step - step to add field to

field - field to add

aggregationType - Type of aggregation

Returns:

new AggregatedField

setDistinct

Query setDistinct(boolean distinct)

Specifies wether the query result must contain only 'distinct' results.

Parameters:

distinct - 'distinct' results

Returns:

Query

See Also:

BasicSearchQuery.setDistinct(boolean), SearchQuery.isDistinct()

setMaxNumber

Query setMaxNumber(int maxNumber)

Limits the query-result to maxNumber records.

Parameters:

maxNumber - max number of results

Returns:

Query

See Also:

BasicSearchQuery.setMaxNumber(int)

setOffset

Query setOffset(int offset)

Offsets the query-result with offset records.

Parameters:

offset - offset in results

Returns:

Query

See Also:

BasicSearchQuery.setOffset(int)

getCleanConstraint

Constraint getCleanConstraint()

Gets the 'clean' constraint on this query. I.e. the constraint which were automaticly added because of security are stripped away, and it is garanteed that you get back what you put in. It is adviced that you use this in stead of SearchQuery#getConstraint, because that function is used by the Query handlers, which do need the security constraints. But otherwise you don't want to see those.

Returns:

Constraint

Since:

MMBase-1.7.1

createConstraint

LegacyConstraint createConstraint(String s)

Create a constraint (for use with this Query object). The argument is a string, as also can be used as an argument of the 'non-query' getList. This should be considered legacy.

Parameters:

s - String with LegacyConstraint

Returns:

LegacyConstraint

See Also:

Cloud.getList(String startNodes, String nodePath, String fields, String constraints, String orderby, String directions, String searchDir, boolean distinct), NodeManager.getList(String constraints, String orderby, String directions)

createConstraint

FieldNullConstraint createConstraint(StepField f)

Create a constraint (for use with this Query object). The given field must be 'null'.

Parameters:

f - Stepfield

Returns:

FieldNullConstraint

createConstraint

FieldValueConstraint createConstraint(StepField f,
                                      Object v)

Create a constraint (for use with this Query object). The given field must equal the given value 'v'.

Parameters:

f - field

v - value

Returns:

FieldValueConstraint

createConstraint

FieldValueConstraint createConstraint(StepField f,
                                      int op,
                                      Object v)

Create a constraint (for use with this Query object). The given field and the given value 'v', combined with given operator must evaluate to true.

Parameters:

f - field

op - operator

v - value

Returns:

FieldValueConstraint

createConstraint

FieldValueConstraint createConstraint(StepField f,
                                      int op,
                                      Object v,
                                      int part)

Create a constraint (for use with this Query object). The given date field and the given value 'v', combined with given operator must evaluate to true for the specified date part.

Parameters:

f - field

op - operator

v - value

part - part of the date value

Returns:

FieldValueConstraint

createConstraint

CompareFieldsConstraint createConstraint(StepField f,
                                         int op,
                                         StepField v)

Create a constraint (for use with this Query object). The two given fields , combined with given operator must evaluate to true.

Parameters:

f - field

op - operator

v - value

Returns:

CompareFieldsConstraint

createConstraint

FieldValueBetweenConstraint createConstraint(StepField f,
                                             Object o1,
                                             Object o2)

Create a constraint (for use with this Query object). The given field must lie between the two given values.

Parameters:

f - field

o1 - value one

o2 - value two

Returns:

FieldValueBetweenConstraint

createConstraint

FieldValueInConstraint createConstraint(StepField f,
                                        SortedSet<? extends Object> v)

Create a constraint (for use with this Query object). The given field value must be contained by the given set of values. If the given set is empty, a FieldValueInConstraint will be constructed for the number field in stead ('number IN (-1)'), which ensures that also in that case the logical thing will happen. (' IN ()' fails in most databases).

Parameters:

f - field

v - value

Returns:

the new Constraint.

createConstraint

FieldValueInQueryConstraint createConstraint(StepField f,
                                             Query q)

setCaseSensitive

FieldConstraint setCaseSensitive(FieldConstraint constraint,
                                 boolean sensitive)

Changes the given constraint's 'case sensitivity' (if applicable). Default it is true.

Parameters:

constraint - constraint to change

sensitive - case sensitivity

Returns:

modified FieldConstraint

setInverse

Constraint setInverse(Constraint c,
                      boolean i)

Changes the given constraint's 'inverse' (if applicable). Default it is (of course) false.

Parameters:

c - constraint

i - inverse

Returns:

Inversed constraint

createConstraint

CompositeConstraint createConstraint(Constraint c1,
                                     int op,
                                     Constraint c2)

Combines two Constraints to one new one, using a boolean operator (AND or OR). Every new constraint must be combined with the ones you already have with such a new CompositeConstraint. If the first constraint is a composite constraint (with the same logical operator), then the second one will simply be added.

Parameters:

c1 - constraint one

op - operator (CompositeConstraint.LOGICAL_AND, CompositeConstraint.LOGICAL_OR)

c2 - constraint two

Returns:

a Composite constraint (might not be a new one)

setConstraint

void setConstraint(Constraint c)

The (composite) constraint can actually be set into the query with this method.

Parameters:

c - constraint

addSortOrder

SortOrder addSortOrder(StepField f,
                       int direction,
                       boolean caseSensitive,
                       int part)

Adds an order on a certain field.

Parameters:

f - field

direction - SortOrder.ORDER_ASCENDING or SortOrder.ORDER_DESCENDING

caseSensitive - case sensitivity

part - part to sort on for a date value

Returns:

new SortOrder

Since:

MMBase-1.9

See Also:

BasicSearchQuery.addSortOrder(org.mmbase.storage.search.StepField)

addSortOrder

SortOrder addSortOrder(StepField f,
                       int direction,
                       boolean caseSensitive)

Defaulting version of addSortOrder(StepField, int, boolean, int) (no date parts)

Parameters:

f - field

direction - SortOrder.ORDER_ASCENDING or SortOrder.ORDER_DESCENDING

caseSensitive - case sensitivity

Returns:

new SortOrder

Since:

MMBase-1.8

addSortOrder

SortOrder addSortOrder(StepField f,
                       int direction)

Defaulting version of addSortOrder(StepField, int, boolean, int) (sorting case insensitively, and no date parts).

Parameters:

f - field

direction - SortOrder.ORDER_ASCENDING or SortOrder.ORDER_DESCENDING

Returns:

new SortOrder

addNode

void addNode(Step s,
             Node node)

Adds a node to a step.

Parameters:

s - step

node - node to add

addNode

void addNode(Step s,
             int number)

Parameters:

s - query step

number - node number

Since:

MMBase-1.8

isUsed

boolean isUsed()

Whether this query was used or not. If is was used, then you cannot modify it anymore (would kill caches, and references to 'original query' would get invalid)

Returns:

query already used or not

markUsed

boolean markUsed()

Mark this query 'used'. It has to be copied first, if you want to add things to it.

Specified by:

markUsed in interface SearchQuery

Returns:

if this query is was used before this method call

clone

Query clone()

Create an (unused) clone

Specified by:

clone in interface PublicCloneable<Query>

Returns:

Cloned Query

cloneWithoutFields

Query cloneWithoutFields()

Clones this object, only without the fields

Returns:

Cloned Query

aggregatingClone

Query aggregatingClone()

Creates an unused aggregate clone of this query. If this query is not itself aggregated, all fields are removed (but the constraints on them remain), and you can add aggregated fields then.

Returns:

Cloned Query

getList

NodeList getList()

Executes the query and returns the resulting node list.

Returns:

resulting node list

Since:

MMBase-1.8

toSql

String toSql()

Shows the query in a human-readable SQL form. This is probably not the query which will actually be sent to the database. This method is provided because 'toString' on a Query object is pretty complete, but pretty undigestable for mere mortals too. Implementions can also implement getSql(), which would make this available in e.g. EL too.

Returns:

human-readable SQL

Since:

MMBase-1.8

removeImplicitFields

void removeImplicitFields()