de.ipcon.db.grooql

Class GrooqlFilter

java.lang.Object

de.ipcon.db.grooql.GrooqlFilter

All Implemented Interfaces:

BOFilterI

public class GrooqlFilter
extends java.lang.Object
implements BOFilterI

GrooqlFilter allow to query BOs that match given criteria from the DB and also check if given BOs match these criteria, both accomplished using only one single criteria definition.

GrooqlFilter could thus be seen as a combination of OQL queries and BOMasken.

The criteria definition is given as a script in a subset of the Groovy language. The script is used directly to check if given BOs match these criteria using the fits() method. For querying matching BOs from the DB the script is automatically transformed into an OQL query which retrieves a superset of the matching BOs which are then post-filtered with the script.

All attributes of the BO that is currently checked are available as variables in the script with their simple name; for example if a filter was defined for the class Benutzer Name, Beschreibung, AnmeldungVerweigern etc. would be available as variables in the script under the exact above names.

Constructor Summary

Constructors

Constructor and Description
GrooqlFilter(EntityI _entity, java.lang.String _filterSource) Creates and initializes a new GrooqlFilter.

Method Summary

Modifier and Type	Method and Description
long	count(GrooqlBOLoaderI gqbol) Gets the number of BOs in the DB that match this filter's criteria.
long	count(GrooqlBOLoaderI gqbol, java.util.Map binding)
long	count(GrooqlBOLoaderI gqbol, java.util.Map binding, java.lang.String additionalClauses)
long	count(GrooqlBOLoaderI gqbol, java.util.Map binding, java.lang.String additionalClauses, java.lang.Object[] additionalParams)
boolean	fits(BOI bo) Checks if the given BOI matches the filter criteria of this GrooqlFilter.
boolean	fits(BOI bo, java.util.Map binding)
boolean	fits(BOI bo, java.util.Map binding, boolean errorValue)
boolean	fits(BOI bo, java.util.Map binding, boolean errorValue, boolean doLogging)
EntityI	getEntity()
java.lang.String	getFilterSource()
OQLQueryInstanceI	getOQLQuery() Builds and returns an OQL query that will retrieve a superset of the BOs that would result if all existing BOs would be filtered by this filter's fits() method.
OQLQueryInstanceI	getOQLQuery(java.util.Map binding)
OQLQueryInstanceI	getOQLQuery(java.util.Map binding, java.lang.String additionalClauses)
OQLQueryInstanceI	getOQLQuery(java.util.Map binding, java.lang.String additionalClauses, java.lang.Object[] additionalParams)
OQLQueryInstanceI	getOQLQuery(java.util.Map binding, java.lang.String additionalClauses, java.lang.Object[] additionalParams, java.lang.String queryWhat)
boolean	mightFilterDependingOnBOInstance()
de.ipcon.db.core.QueryResultsI	query(GrooqlBOLoaderI gqbol) Retrieves BOs via this filter's getOQLQuery() method and the given GrooqlBOLoaderI and then automatically post-filters them using this filter's fits() method.
de.ipcon.db.core.QueryResultsI	query(GrooqlBOLoaderI gqbol, java.util.Map binding)
de.ipcon.db.core.QueryResultsI	query(GrooqlBOLoaderI gqbol, java.util.Map binding, java.lang.String orderBy)
de.ipcon.db.core.QueryResultsI	query(GrooqlBOLoaderI gqbol, java.util.Map binding, java.lang.String orderBy, int limit)
de.ipcon.db.core.QueryResultsI	query(GrooqlBOLoaderI gqbol, java.util.Map binding, java.lang.String orderBy, int limit, int offset)
de.ipcon.db.core.QueryResultsI	query(GrooqlBOLoaderI gqbol, java.util.Map binding, java.lang.String orderBy, int limit, int offset, java.lang.String additionalClauses)
de.ipcon.db.core.QueryResultsI	query(GrooqlBOLoaderI gqbol, java.util.Map binding, java.lang.String orderBy, int limit, int offset, java.lang.String additionalClauses, java.lang.Object[] additionalParams)
java.util.List	queryBO(GrooqlBOLoaderI gqbol) Retrieves BOs via this filter's getOQLQuery() method and the given GrooqlBOLoaderI and then automatically post-filters them using this filter's fits() method.
java.util.List	queryBO(GrooqlBOLoaderI gqbol, java.util.Map binding)
java.util.List	queryBO(GrooqlBOLoaderI gqbol, java.util.Map binding, java.lang.String orderBy)
java.util.List	queryBO(GrooqlBOLoaderI gqbol, java.util.Map binding, java.lang.String orderBy, int limit)
java.util.List	queryBO(GrooqlBOLoaderI gqbol, java.util.Map binding, java.lang.String orderBy, int limit, int offset)
java.util.List	queryBO(GrooqlBOLoaderI gqbol, java.util.Map binding, java.lang.String orderBy, int limit, int offset, java.lang.String additionalClauses)
java.util.List	queryBO(GrooqlBOLoaderI gqbol, java.util.Map binding, java.lang.String orderBy, int limit, int offset, java.lang.String additionalClauses, java.lang.Object[] additionalParams)
void	setEntity(EntityI $11)
void	setFilterSource(java.lang.String _filterSource) Sets the filter script source code and deletes the cached compiled version of the filter script.
long	upperCount(GrooqlBOLoaderI gqbol) Gets the maximum number of BOs in the DB that may match this filter's criteria.
long	upperCount(GrooqlBOLoaderI gqbol, java.util.Map binding)
long	upperCount(GrooqlBOLoaderI gqbol, java.util.Map binding, java.lang.String additionalClauses)
long	upperCount(GrooqlBOLoaderI gqbol, java.util.Map binding, java.lang.String additionalClauses, java.lang.Object[] additionalParams)

Methods inherited from class java.lang.Object

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

Constructor Detail

GrooqlFilter

public GrooqlFilter(EntityI _entity,
                    java.lang.String _filterSource)
             throws org.codehaus.groovy.control.CompilationFailedException

Creates and initializes a new GrooqlFilter.

Parameters:

_entity - the EntityI which the BOs must match

_src - the filter script source used to find and filter the BOs

Throws:

org.codehaus.groovy.control.CompilationFailedException - if the given filter script contained syntax errors or could not be compiled for other reasons

Method Detail

setFilterSource

public void setFilterSource(java.lang.String _filterSource)

Sets the filter script source code and deletes the cached compiled version of the filter script.

Parameters:

_src - the filter script source used to find and filter the BOs

mightFilterDependingOnBOInstance

public boolean mightFilterDependingOnBOInstance()

fits

public boolean fits(BOI bo)

Checks if the given BOI matches the filter criteria of this GrooqlFilter.

Specified by:

fits in interface BOFilterI

Parameters:

bo - the BO for which should be checked if it matches the criteria of this filter

binding - a Map containing name/value pairs that will be made available as variables for the script used by fits(). May be null.

errorValue - the boolean value that is returned if the filter script evaluation throws an exception; defaults to false.

doLogging - if true (the default) errors during script execution will be logged; if false not. Basically only for the automatic tests, since the stacktraces that are printed when error cases are tested are slightly annoying.

Returns:

false if bo is null, the class of bo is not a (sub)class of this filter's entity's class or if the filter script returned false. true if bo matched all the above criteria. _errorValue if the filter script evaluation threw an exception.

fits

public boolean fits(BOI bo,
                    java.util.Map binding)

fits

public boolean fits(BOI bo,
                    java.util.Map binding,
                    boolean errorValue)

fits

public boolean fits(BOI bo,
                    java.util.Map binding,
                    boolean errorValue,
                    boolean doLogging)

getOQLQuery

public OQLQueryInstanceI getOQLQuery()

Builds and returns an OQL query that will retrieve a superset of the BOs that would result if all existing BOs would be filtered by this filter's fits() method.

In most cases the OQL result set will already contain only BOs for which fits() returns true, but this cannot be guaranteed since it is not possible to filter as finegrained with OQL as can be done with the filter script.

The query() and queryBO() methods of this class can be used to retrieve the exact set of matching BOs, since they will automatically post-filter the set of BOs retrieved from the DB with fits(). As a side-effect, the flag #encounteredUnsupportedParts will be initialized.

Parameters:

binding - a Map containing name/value pairs that will be made available as variables for the script used by fits(). May be null.

additionalClauses - additional custom WHERE clauses that are added to the generated OQL's WHERE clause (with "and"). May be and defaults to null.

additionalParams - parameters for the additional WHERE clauses. May be and defaults to null.

Returns:

an OQLQueryInstanceI FIXME

getOQLQuery

public OQLQueryInstanceI getOQLQuery(java.util.Map binding)

getOQLQuery

public OQLQueryInstanceI getOQLQuery(java.util.Map binding,
                                     java.lang.String additionalClauses)

getOQLQuery

public OQLQueryInstanceI getOQLQuery(java.util.Map binding,
                                     java.lang.String additionalClauses,
                                     java.lang.Object[] additionalParams)

getOQLQuery

public OQLQueryInstanceI getOQLQuery(java.util.Map binding,
                                     java.lang.String additionalClauses,
                                     java.lang.Object[] additionalParams,
                                     java.lang.String queryWhat)

query

public de.ipcon.db.core.QueryResultsI query(GrooqlBOLoaderI gqbol)

Retrieves BOs via this filter's getOQLQuery() method and the given GrooqlBOLoaderI and then automatically post-filters them using this filter's fits() method.

The returned QueryResultsI will thus only include BOs fully matching this filter.

Parameters:

gqbol - a GrooqlBOLoaderI used to query the BOs from the DB

binding - a Map containing name/value pairs that will be made available as variables for the script used by fits(). May be and defaults to null.

orderBy - an OQL "order by" clause (not including the actual "order by" keywords) that is added to the generated query. May be and defaults to null.

limit - a limit count that is used to restrict the number of returned BOs to the given amount. If <= 0 no limit will be applied and all matching BOs will be returned. Defaults to -1.

offset - an offset starting from which the retrieved BOs will be returned. Only honoured if _limit > 0 and _offset >= 0. Defaults to -1.

additionalClauses - additional custom WHERE clauses that are added to the generated OQL's WHERE clause (with "and"). May be and defaults to null.

additionalParams - parameters for the additional WHERE clauses. May be and defaults to null.

Returns:

an QueryResultsI that can be used to retrieve the queried and matching BOs

query

public de.ipcon.db.core.QueryResultsI query(GrooqlBOLoaderI gqbol,
                                            java.util.Map binding)

query

public de.ipcon.db.core.QueryResultsI query(GrooqlBOLoaderI gqbol,
                                            java.util.Map binding,
                                            java.lang.String orderBy)

query

public de.ipcon.db.core.QueryResultsI query(GrooqlBOLoaderI gqbol,
                                            java.util.Map binding,
                                            java.lang.String orderBy,
                                            int limit)

query

public de.ipcon.db.core.QueryResultsI query(GrooqlBOLoaderI gqbol,
                                            java.util.Map binding,
                                            java.lang.String orderBy,
                                            int limit,
                                            int offset)

query

public de.ipcon.db.core.QueryResultsI query(GrooqlBOLoaderI gqbol,
                                            java.util.Map binding,
                                            java.lang.String orderBy,
                                            int limit,
                                            int offset,
                                            java.lang.String additionalClauses)

query

public de.ipcon.db.core.QueryResultsI query(GrooqlBOLoaderI gqbol,
                                            java.util.Map binding,
                                            java.lang.String orderBy,
                                            int limit,
                                            int offset,
                                            java.lang.String additionalClauses,
                                            java.lang.Object[] additionalParams)

queryBO

public java.util.List queryBO(GrooqlBOLoaderI gqbol)

Retrieves BOs via this filter's getOQLQuery() method and the given GrooqlBOLoaderI and then automatically post-filters them using this filter's fits() method.

The returned QueryResultsI will thus only include BOs fully matching this filter.

Parameters:

gqbol - a GrooqlBOLoaderI used to query the BOs from the DB

binding - a Map containing name/value pairs that will be made available as variables for the script used by fits(). May be and defaults to null.

orderBy - an OQL "order by" clause (not including the actual "order by" keywords) that is added to the generated query. May be and defaults to null.

limit - a limit count that is used to restrict the number of returned BOs to the given amount. If <= 0 no limit will be applied and all matching BOs will be returned. Defaults to -1.

offset - an offset starting from which the retrieved BOs will be returned. Only honoured if _limit > 0 and _offset >= 0. Defaults to -1.

additionalClauses - additional custom WHERE clauses that are added to the generated OQL's WHERE clause (with "and"). May be and defaults to null.

additionalParams - parameters for the additional WHERE clauses. May be and defaults to null.

Returns:

a List containing all the queried and matching BOs

queryBO

public java.util.List queryBO(GrooqlBOLoaderI gqbol,
                              java.util.Map binding)

queryBO

public java.util.List queryBO(GrooqlBOLoaderI gqbol,
                              java.util.Map binding,
                              java.lang.String orderBy)

queryBO

public java.util.List queryBO(GrooqlBOLoaderI gqbol,
                              java.util.Map binding,
                              java.lang.String orderBy,
                              int limit)

queryBO

public java.util.List queryBO(GrooqlBOLoaderI gqbol,
                              java.util.Map binding,
                              java.lang.String orderBy,
                              int limit,
                              int offset)

queryBO

public java.util.List queryBO(GrooqlBOLoaderI gqbol,
                              java.util.Map binding,
                              java.lang.String orderBy,
                              int limit,
                              int offset,
                              java.lang.String additionalClauses)

queryBO

public java.util.List queryBO(GrooqlBOLoaderI gqbol,
                              java.util.Map binding,
                              java.lang.String orderBy,
                              int limit,
                              int offset,
                              java.lang.String additionalClauses,
                              java.lang.Object[] additionalParams)

count

public long count(GrooqlBOLoaderI gqbol)

Gets the number of BOs in the DB that match this filter's criteria.

FIXME! Currently this method needs to actually query all the objects that match the filter which can make it very costly, so only call it if you really need it. If you need the objects anyway rather use queryBO() and get the size of the returned list (this is what this method does internally basically).

Parameters:

gqbol - a GrooqlBOLoaderI used to query the BOs from the DB

binding - a Map containing name/value pairs that will be made available as variables for the script used by fits(). May be and defaults to null.

additionalClauses - additional custom WHERE clauses that are added to the generated OQL's WHERE clause (with "and"). May be and defaults to null.

additionalParams - parameters for the additional WHERE clauses. May be and defaults to null.

Returns:

the number of BOs in the DB that match this filter's criteria

count

public long count(GrooqlBOLoaderI gqbol,
                  java.util.Map binding)

count

public long count(GrooqlBOLoaderI gqbol,
                  java.util.Map binding,
                  java.lang.String additionalClauses)

count

public long count(GrooqlBOLoaderI gqbol,
                  java.util.Map binding,
                  java.lang.String additionalClauses,
                  java.lang.Object[] additionalParams)

upperCount

public long upperCount(GrooqlBOLoaderI gqbol)

Gets the maximum number of BOs in the DB that may match this filter's criteria. Sometimes this is enough information and it is a good deal less costly than count.

Parameters:

gqbol - a GrooqlBOLoaderI used to query the BOs from the DB

Returns:

the maximum number of BOs in the DB that may match this filter's criteria

upperCount

public long upperCount(GrooqlBOLoaderI gqbol,
                       java.util.Map binding)

upperCount

public long upperCount(GrooqlBOLoaderI gqbol,
                       java.util.Map binding,
                       java.lang.String additionalClauses)

upperCount

public long upperCount(GrooqlBOLoaderI gqbol,
                       java.util.Map binding,
                       java.lang.String additionalClauses,
                       java.lang.Object[] additionalParams)

getFilterSource

public java.lang.String getFilterSource()

getEntity

public EntityI getEntity()

setEntity

public void setEntity(EntityI $11)